docs(vrs): refresh host-local implementation map

Author: myobie

docs/vrs/03-host-local/requirements.md

@@ -6,7 +6,7 @@ control-plane replacement in
 [R03](../requirements.md#L38-L39),
 [R04](../requirements.md#L43-L46), and
 [R11](../requirements.md#L65-L70). Partition safety remains a fleet-level
-contract in [R18–R19](../requirements.md); this sub-VRS does not redefine it.
+contract in [R18/R26](../requirements.md); this sub-VRS does not redefine it.
 
 ## Requirements
 
@@ -45,5 +45,5 @@ contract in [R18–R19](../requirements.md); this sub-VRS does not redefine it.
   Relocation requires the explicit coordinated migration contract in
   [issue #85](https://github.com/compoundingtech/st2/issues/85).
 
-Current mechanisms, executable evidence, and unimplemented partition
-activation work are mapped in [spec.md](spec.md).
+Current mechanisms, executable evidence, and the remaining partition questions
+are mapped in [spec.md](spec.md).

docs/vrs/03-host-local/spec.md

@@ -7,22 +7,22 @@ policy, or a second Doctor health model.
 
 ## Subject selection and ownership
 
-The CLI selects a catalog and an explicit or locally detected host. A
-[`HostLock`](../../../src/host_lock.rs#L1-L67) tracks resident ownership of
-that `(catalog, host)` subject independently from another host's slice of the
-same synced catalog.
+The CLI selects a catalog and an explicit or locally detected host.
+[`HostOwnership`](../../../src/host_lock.rs) canonicalizes that subject and
+retains its host-scoped kernel `flock` for the resident writer's lifetime,
+independently from another host's slice of the same synced catalog.
 
 ## Current mechanism and evidence
 
 | Requirement | Current mechanism | Evidence |
 | --- | --- | --- |
-| HOST-R01 | Reconciliation filters every declaration through its resolved host; remote declarations are reported but not acted on. | [`reconcile`](../../../src/reconcile.rs#L106-L191); [host-placement tests](../../../tests/reconcile.rs#L135-L153) |
-| HOST-R02 | One pass discovers declarations, obtains an authoritative local session view, computes desired versus actual, and then adopts or executes the plan. A failed session listing skips the whole pass. | [reconcile pass](../../../src/run.rs#L737-L813); [reconcile-plan model](../../../src/reconcile.rs#L66-L81) |
-| HOST-R03 | The long-running CLI checks for a live owner of the same catalog and host, records its own PID, and reclaims stale ownership. | [catalog supervisor entry](../../../src/main.rs#L1738-L1838); [`HostLock` tests](../../../src/host_lock.rs#L83-L143) |
-| HOST-R04 | PTY and exec tasks survive normal or forced control-plane termination and binary replacement; the successor preserves PID and creation identity while adopting them. | [replacement acceptance](../../../tests/nomad_survival.rs#L592-L701) |
-| HOST-R05 | Normal supervisor exit leaves tasks running. Teardown and retirement are separate paths that target only the selected host's declared task IDs. | [`down` and teardown](../../../src/run.rs#L987-L1056); [explicit-lifecycle acceptance](../../../tests/nomad_survival.rs#L703-L780) |
-| HOST-R06 | The deterministic loop surfaces bounded crash-loop failure to the declared supervisor; the root-agent responsibility itself is owned by root R04. | [crash-loop surfacing](../../../src/run.rs#L1090-L1189); [R04](../requirements.md#L43-L46) |
-| HOST-R07 | Agent/task liveness and the resident supervisor lock are separate observations. A replacement adopts matching work visible in its selected current state. Sidecar-only work does not make an otherwise unrunnable agent live. No global catalog-liveness classifier is implemented. | [replacement adoption](https://github.com/compoundingtech/st2/blob/661c88b6e50cddbdf85e8ffaca9245c46491a1e0/tests/nomad_survival.rs#L608-L717); [separate supervisor report](https://github.com/compoundingtech/st2/blob/661c88b6e50cddbdf85e8ffaca9245c46491a1e0/src/main.rs#L985-L1008); [DING-only boundary](https://github.com/compoundingtech/st2/blob/661c88b6e50cddbdf85e8ffaca9245c46491a1e0/tests/reconcile.rs#L533-L561) |
+| HOST-R01 | Reconciliation filters every declaration through its resolved host; remote declarations are reported but not acted on. | [`reconcile_selected`](../../../src/reconcile.rs); [`other_host_specs_are_skipped`](../../../tests/reconcile.rs) |
+| HOST-R02 | One admitted pass discovers declarations, obtains an authoritative local runtime view, computes desired versus actual, and then adopts or executes the plan. A failed session listing skips the whole pass. | [`reconcile_pass_admitted`](../../../src/run.rs); [`up_once_marks_a_list_failure_as_a_skipped_pass`](../../../tests/run.rs) |
+| HOST-R03 | `HostOwnership` canonicalizes one catalog/host subject and retains its persistent-inode kernel `flock`; a simultaneous second claim refuses. PID text is diagnostic only. | [`HostOwnership` and `HostLock`](../../../src/host_lock.rs); [ownership tests](../../../src/host_lock.rs) |
+| HOST-R04 | PTY and exec tasks survive normal or forced control-plane termination and binary replacement; the successor preserves PID and creation identity while adopting them. | [replacement acceptance](../../../tests/nomad_survival.rs) |
+| HOST-R05 | Normal supervisor exit leaves tasks running. Teardown and retirement are separate paths that target only the selected host's declared task IDs. | [`down` and teardown](../../../src/run.rs); [explicit-lifecycle acceptance](../../../tests/nomad_survival.rs) |
+| HOST-R06 | The deterministic loop surfaces bounded crash-loop failure to the declared supervisor; the root-agent responsibility itself is owned by root R04. | [`surface_crash_loop`](../../../src/run.rs); [crash-loop acceptance](../../../tests/run.rs); [R04](../requirements.md#L43-L46) |
+| HOST-R07 | Agent/task liveness and resident supervisor ownership are separate observations. A replacement adopts matching work visible in its selected current state. Sidecar-only work does not make an otherwise unrunnable agent live. No global catalog-liveness classifier is implemented. | [replacement adoption](../../../tests/nomad_survival.rs); [supervisor reporting](../../../src/main.rs); [DING-only boundary](../../../tests/reconcile.rs) |
 | HOST-R08 | Stable catalog-root and PTY-root path lifetime is an accepted constraint. The guided coordinated relocation operation is not implemented. | [migration contract](https://github.com/compoundingtech/st2/issues/85) |
 
 ## Catalog liveness and path lifetime
@@ -52,29 +52,29 @@ paths and never scan arbitrary old roots.
 
 ## Partition boundary
 
-The root [R18–R19](../requirements.md) contract requires a complete,
-validated, locally applied catalog to remain authoritative through transport
-loss. The current reconciler instead discovers the live catalog filesystem on
-each pass ([source](../../../src/run.rs#L737-L758)), while validation is a
-separate read-only command
-([source](../../../src/validate.rs#L1-L24)). st2 does not yet stage a candidate
-catalog, assign or compare catalog versions, atomically activate a validated
-snapshot, or retain an activation receipt. That durable last-known-good
-activation path is unimplemented.
+The root [R18/R26](../requirements.md) contract requires a complete, validated,
+locally applied catalog to remain authoritative through transport loss.
+[`st2 catalog snapshot` and `catalog apply`](../../../src/catalog_transaction.rs)
+implement the local activation boundary. Snapshot emits the exact declaration
+root digest. Apply captures and validates a complete candidate, takes the
+exclusive catalog lock, rechecks the expected predecessor digest, durably stages
+the bytes, publishes an incomplete marker, and atomically applies the
+projection. A crash resumes from that marker and content-addressed stage without
+reopening the original candidate. While the marker exists, declaration readers
+and lifecycle actions fail closed. The executable acceptance is in
+[`tests/catalog_apply.rs`](../../../tests/catalog_apply.rs).
 
 Peer reachability is not currently a reconciler input. This is consistent with
 peer absence being neutral, but the declaration shape for an explicit local
 operation that depends on a peer or source is not yet specified.
 
+The predecessor and target digests provide exact compare-and-swap authority;
+they do not define a fleet-wide ordering that proves one independently
+published catalog is newer than another.
+
 ## Open questions
 
-- What identifies a complete candidate catalog and orders it after the locally
-  applied version?
-- What atomic activation and durable receipt let a replacement control plane
-  recover the last-known-good version after interruption?
+- What version or ordering contract proves that one complete candidate is newer
+  than the locally applied digest across independently converging hosts?
 - How does a declaration express a local operation's dependency on a peer or
   source without turning peer presence into general health?
-- [`HostLock` acquisition](../../../src/host_lock.rs#L26-L48) is currently
-  check-then-write rather than an atomic create. What ownership primitive
-  closes simultaneous first-start races while retaining host-scoped
-  stale-owner recovery?

docs/vrs/spec.md

@@ -437,26 +437,27 @@ validate ──► materialize ──► host-local st2 scheduler/reconciler
 - **R18:** Transport loss does not invalidate a host's locally applied desired
   state. Missing, partial, or invalid incoming catalog state cannot replace the
   last complete validated version or cause teardown.
-- **R19:** Hosts may temporarily apply different catalog versions and converge
+- **R26:** Hosts may temporarily apply different catalog versions and converge
   independently. Peer or source absence is neutral unless a declared local
   operation explicitly depends on it; reconnect is not itself evidence that a
   candidate catalog is complete, valid, or newer.
 
 Current host isolation is source-backed: reconciliation filters declarations
-to one selected host
-([source](../../src/reconcile.rs#L106-L191)), a host-scoped lock detects an
-existing resident writer for the same local subject
-([source](../../src/host_lock.rs#L1-L67)), and running tasks survive control
-plane loss and adoption
-([evidence](../../tests/nomad_survival.rs#L592-L701)).
-
-The durable catalog-activation half of R18–R19 is not implemented. Each pass
-currently discovers the live catalog directory directly
-([source](../../src/run.rs#L737-L758)); `st2 validate` is separate and
-read-only. There is no staged candidate boundary, catalog version ordering,
-atomic validated activation, or durable last-known-good receipt. The exact
-candidate-completeness, version, and activation-recovery contracts remain open
-design work.
+to one selected host ([source](../../src/reconcile.rs)), retained
+`HostOwnership` holds the kernel lock for one canonical catalog/host subject
+([source](../../src/host_lock.rs)), and running tasks survive control-plane loss
+and adoption ([evidence](../../tests/nomad_survival.rs)).
+
+The local activation half of R18/R26 is implemented by
+[`catalog snapshot` and `catalog apply`](../../src/catalog_transaction.rs).
+Snapshot binds a complete declaration root. Apply validates a retained
+candidate, rechecks its expected predecessor digest under the exclusive lock,
+durably stages it, publishes a recovery marker, and atomically applies it.
+Interrupted apply resumes from the marker and content-addressed stage while
+other declaration reads and lifecycle actions remain fenced. CAS identifies an
+exact predecessor and target, but it does not define fleet-wide version
+ordering. The ordering contract and the shape of an explicit local dependency
+on a peer or source remain open; peer reachability is not a reconciler input.
 
 ## Message lifecycle