daemon: correct ARCHITECTURE doc to match actual package shape + lock scope

Two promises the doc was making that the code doesn't keep:

1. "Helpers moved out so the package stays focused on orchestration."
   The package still has ~29 files and ~130 func (d *Daemon) methods
   wiring VM lifecycle, image management, host networking, background
   reconciliation, and JSON-RPC dispatch. Calling it "just orchestration"
   sets readers up for surprise. Rewrite the subpackages preamble to
   say so, and flag the service split as a post-v0.1.0 project.

2. "vmLocks[id] is held only across short synchronous state validation
   and DB mutations." That's what workspace.prepare does; regular
   lifecycle ops (start/stop/delete/set) go through withVMLockByRef
   and hold the lock across the whole callback body, which for `start`
   means preflight + bridge + firecracker spawn + post-boot wiring.
   Rewrite the vmLocks bullet and the lock-ordering section to say
   that explicitly, so readers don't build "surely my long flow under
   the lock can't be what the doc means" reasoning on top of a false
   premise.

Doc-only change. Code behaviour is unchanged.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
This commit is contained in:
Thales Maciel 2026-04-20 13:02:36 -03:00
parent 34dd7644d8
commit e69810610a
No known key found for this signature in database
GPG key ID: 33112E6833C34679
2 changed files with 36 additions and 15 deletions

View file

@ -67,6 +67,10 @@
//
// vmLocks[id] → workspaceLocks[id] → {createVMMu, imageOpsMu} → subsystem-local locks
//
// Subsystem-local locks (tapPool.mu, opstate.Registry mu) are leaves and
// do not contend with each other. See ARCHITECTURE.md for details.
// vmLocks[id] is held across entire lifecycle ops (start/stop/delete/set),
// not just a validation window — callers that want to avoid blocking
// lifecycle on slow guest I/O must explicitly split off to
// workspaceLocks[id] the way workspace.prepare does. Subsystem-local
// locks (tapPool.mu, opstate.Registry mu) are leaves and do not contend
// with each other. See ARCHITECTURE.md for details.
package daemon