Jon Chery
40b5e781ce
Operator decision (resolves grill C-04 + escalation E-03): keep 2 milestones (v0.9 + v0.10), keep all phases (40 total, exceeds 35 soft limit), v1.0 is UAT-gated and cut as a separate tag (v1.0.0) after v0.10 completion per operator sign-off — not a separate milestone. Relabels all v1.0 milestone references to v0.10 across ROADMAP, REQUIREMENTS, GRILL_v0.9, IDEATION_v0.9, PRD_v0.9, PROJECT. Phase content unchanged; only the milestone label moves. Historical grill narrative (the original PRD §23 counts and the E-03 auto-split reasoning) preserved verbatim for audit integrity. C-04 and E-03 marked RESOLVED in GRILL_v0.9.md. Milestone structure: - v0.9: Re-architecture Foundation & Workloads (13 phases P00..P0X) - v0.10: Production Hardening (19 phases P00..P16, milestone tag v0.10.0) - v1.0: UAT-gated production-ready cut (separate v1.0.0 tag, not a milestone) verify-reqs: 90 requirements consistent. ---ci--- project: orca phase: 0 milestone: v0.9 status: complete gate: C-04 resolved ---/ci---
92 lines
6.3 KiB
Markdown
92 lines
6.3 KiB
Markdown
# Orca — Comprehensive Product Requirements Document (v0.9/v0.10)
|
||
|
||
**Audience:** Operators, AI agents, downstream tooling authors
|
||
|
||
> This PRD SUPERSEDES the shipped v0.1–v0.8 architecture. The v0.9 and v0.10
|
||
> milestones implement a re-architecture whose load-bearing rules (R-001…R-016)
|
||
> and decisions (D-068…D-206) replace or demote several earlier documented
|
||
> decisions. See §22 decision-trace and the Supersession Table in
|
||
> `ARCHITECTURE.md` for the recorded reversals and their evidence basis.
|
||
|
||
## Status
|
||
|
||
| Item | Status |
|
||
|---|---|
|
||
| Spec lock-in | ✅ R-001…R-016 + D-001…D-206 settled |
|
||
| v0.1–v0.8 implementation | ✅ shipped (REQ-001..060, D-001..D-047) |
|
||
| v0.9 implementation | ⬜ Phase 0 pre-execution (this file is the spec input) |
|
||
| v0.10 implementation | ⬜ planning (post-PRD) |
|
||
| v1.x multi-host state | ⬜ parked (post-v1.0) |
|
||
| v2.x full Nomad-HCL | ⬜ parked (post-v1.x) |
|
||
|
||
## Override justification (recorded for the grill supersession)
|
||
|
||
The v0.9/v0.10 re-architecture is justified on six independent grounds rather
|
||
than preference. Each reverses a prior documented decision; the new evidence
|
||
basis is recorded with the reversal in the Supersession Table:
|
||
|
||
1. **The v0.8 daemon model is operationally failing** in the target environment
|
||
— R-001 ("no orca binary on any server") is a response to measured pain, not
|
||
preference.
|
||
2. **step-ca is externally mandated** (D-101) — the operator environment requires
|
||
an external CA; AD-010's "too heavyweight" rationale is no longer operative.
|
||
3. **Multi-tenancy is a hard product requirement** (R-002) — real multi-tenant
|
||
use cases cannot be served by the single-namespace layout; the
|
||
"no multi-tenancy" anti-pattern is obsolete.
|
||
4. **WASM is a hard workload requirement** (D-088) — workloads are WASM, not
|
||
processes; `os/exec` is insufficient; the "no container runtime" anti-pattern
|
||
is reversed.
|
||
5. **SSH-push is the only viable deployment target** for the operator's
|
||
bare-Linux/Proxmox environment — installing/maintaining an orca daemon on
|
||
every peer is operationally infeasible.
|
||
6. **Simplicity/vision correction** — the v0.1-v0.8 daemon model was a wrong
|
||
turn against the original CLI-first vision; the re-architecture corrects the
|
||
vision.
|
||
|
||
## Canonical references
|
||
|
||
The full PRD text was provided by the operator and adopted wholesale. The
|
||
load-bearing rules (R-001…R-016), the concept model (§4), the architecture
|
||
(§5), the milestone plan (§23), and the decision trace (§22) are reproduced
|
||
in the operator's original document. This file is the auditable pointer to
|
||
that source; the substantive planning artifacts live in:
|
||
|
||
- `IDEATION_v0.9.md` — 30 ideas (REQ-061..REQ-090), three tiers
|
||
- `GRILL_v0.9.md` — 9-axis adversarial review, 19 binding conditions, 10 phase challenges
|
||
- `REQUIREMENTS.md` — REQ-061..REQ-090 appended
|
||
- `ROADMAP.md` — v0.9 (13 phases) + v0.10 (19 phases) appended
|
||
- `PERSONAS.md` — security/network/devops reactivated
|
||
- `ARCHITECTURE.md` — v0.9 banners + Supersession Table
|
||
|
||
## The 16 load-bearing rules (invariants)
|
||
|
||
| ID | Rule |
|
||
|---|---|
|
||
| R-001 | No Orca Go binary runs on any server. The `orca` CLI on the operator's host is the only Orca software. Servers run Linux + systemd + apt-managed packages + config files written by the CLI. |
|
||
| R-002 | Filesystem paths are namespaces. `ORCA_HOME` hosts many namespaces; each is a dir with `db/`, `.env`, `.env.secrets`, `jobs/`, `alloc/`, `ns.md`. `_defaults/` always exists. No `namespace` column in SQLite. |
|
||
| R-003 | Cluster lead is always bare Linux; Proxmox can never be lead. |
|
||
| R-004 | Workload migration Linux↔Proxmox supported; runtime can change at migration; SPIFFE identity preserved. |
|
||
| R-005 | Storage replication enables migration; a Service's `count` replicas share one `runtime {}` block. |
|
||
| R-006 | mTLS on by default; cluster CA = step-ca; Traefik + `LoadCredential=` are load-bearing. |
|
||
| R-007 | Sockets by default (`/run/orca/alloc-<id>/port-<name>.sock`); `127.0.0.1` opt-in. |
|
||
| R-008 | CLI results cached locally with per-class TTLs (`orca_cache` SQLite). |
|
||
| R-009 | CLI host SPOF mitigated by external shared state in v1.x; v0.10 ships the abstractions + cache layer. |
|
||
| R-010 | Control plane updates are transactional (ArgoCD-style desired-state/lead-applier). |
|
||
| R-011 | Each namespace has `.env` (plaintext) and `.env.secrets` (AES-256-GCM, per-line nonce); master key per `ORCA_HOME` at `cluster/master.key`. |
|
||
| R-012 | Workload kinds are `Job`, `Service`, `DaemonSet`; schema-separated by `kind:` in frontmatter. |
|
||
| R-013 | Jobspec format is Markdown with YAML frontmatter (`.md` preferred); `.yaml` and `.hcl` accepted by parser dispatcher. |
|
||
| R-014 | All user-facing config is Markdown with YAML frontmatter; body preserved verbatim. |
|
||
| R-015 | Body of every `.md` config file is preserved verbatim and surfaced in `inspect`, `history`, diffs. |
|
||
| R-016 | `.env` and `.env.secrets` are exempt from R-014 — standard dotenv format retained. |
|
||
|
||
## Milestone summary (§23, reordered per grill PC-01..PC-10)
|
||
|
||
### v0.9 — Workloads + Re-architecture Foundation (13 phases)
|
||
P00 (deprecation sweep + migration-ordering + txn-design spike + test-infra bootstrap + persona reactivation + doc banners), P0a1 (path resolver + config demotion), P0a2 (namespace CRUD + inheritance), P0b (Markdown jobspec parser + fuzz), P0c (schemas + emitter interface), P01 (SSH-push transport + host-path volumes), P02 (service + Traefik emitter), P03 (update stanza), P04 (lifecycle hooks), P05 (constraints + CLI-side scheduler), P06 (task groups), P07a/P07b/P07c (process+podman / wasmtime [C-01 gated] / pve-vm+ct runtimes), P08 (sockets), P09 (Syncthing [C-02 gated]), P10 (lead rules + migration), P0X (ship + audit).
|
||
|
||
### v0.10 — Production Hardening (19 phases)
|
||
P00 (CLI cache), P01 (metrics), P01.5 (SPIFFE spike [C-08 gated]), P02 (ACL), P03 (secrets), P04 (backup/restore), P05 (drain + daemon drain-and-stop), P06 (alloc history), P07 (recovery), P08 (integration tests), P09 (collector+aggregator), P10 (transactional plane [C-09 gated]), P11 (job lint), P12 (job verify), P13 (ns subcommands), P14a/P14b/P14c (data / daemon cutover / mixed-version tolerance), P15 (README), P15.5 (threat model [C-19 gated]), P16 (final review + ship — v1.0.0 release).
|
||
|
||
See `ROADMAP.md` for the full reordered plan and `GRILL_v0.9.md` for the 19
|
||
binding conditions (C-01..C-19) and 10 phase challenges (PC-01..PC-10) that
|
||
gate specific phases. |