diff --git a/docs/prds/0070-per-host-orchestrator.md b/docs/prds/0070-per-host-orchestrator.md index aab0800..c79bc18 100644 --- a/docs/prds/0070-per-host-orchestrator.md +++ b/docs/prds/0070-per-host-orchestrator.md @@ -279,6 +279,33 @@ SQLite is right for the runtime tier (mutable, concurrent, queried) and wrong for the other two (Nix can't read it at eval time; it fights the declarative manifest trust model). Keep the tiers separate. +**The DB file is host-resident, not owned inside the orchestrator unit** +(decided in review). Two reasons: + +- **Durability across restarts.** Re-adoption sweeps the registry after an + orchestrator restart, so the state *must* outlive the orchestrator + instance's lifecycle. A host-resident file (the slice-1 default under + `~/.cache/bot-bottle/orchestrator/`) is the simplest durable store; the + orchestrator VM/container mounts it rather than carrying it. +- **Integrity via access-scoping, not location.** Agents can't touch the + DB directly regardless of where it lives — they're network-isolated in + their bottles and only ever speak to the control/data plane. The real + risk is a *compromised agent-facing data-plane service* (egress/git-gate, + which parse hostile bytes) writing the registry and forging attribution. + The control is a **read/write split**: writes (register/deregister) come + only from the **control plane**; the **data plane gets the DB read-only** + for attribution lookups. A host-resident file makes that split + enforceable (mount `ro` into the data plane, `rw` into the control + plane) — which owning it "entirely inside" a monolithic orchestrator + would not. + +Implementation note for the VM slices: SQLite **WAL** over a guest share +(virtiofs/9p) is finicky (the `-shm`/`-wal` files need real mmap/locking), +so the durable-DB-on-host may want a small **host-side owner** the +orchestrator reaches over the control-plane RPC, rather than a shared +mount. Decide this at the Firecracker slice; `sqlite3` itself is stdlib, so +"the host needs SQLite" is a non-cost. + ## Sequencing Jump straight to the **virtualized** end state (not a host-daemon stepping