# 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.