orca/.ciagent/PRD_v0.9.md

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.