docs(prd): 0070 registry DB is host-resident with rw/ro access split (#352)
test / unit (pull_request) Successful in 55s
test / integration (pull_request) Successful in 16s
test / coverage (pull_request) Successful in 1m1s

Per review: the SQLite runtime-state DB lives on the host, not owned
inside the orchestrator unit. Durability (re-adoption must survive an
orchestrator restart) + integrity via access-scoping (control-plane rw,
data-plane ro) rather than location. Note the WAL-over-guest-share wrinkle
for the VM slices (may want a host-side DB owner reached over the RPC).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01WBMWTEtQdJ4W5UrWuLHCck
This commit is contained in:
2026-07-13 13:17:05 -04:00
parent 1702664b81
commit ed7307e0e3
+27
View File
@@ -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