feat: add transactional catalog snapshot and apply

agent-session-id: dev3.dotfiles-cos-misc-agent-runtime-simplification
agent-tool: Codex
agent-tool-version: 0.145.0
agent-model: gpt-5.6-sol
agent-runtime-profile: /home/schickling/.config/coding-agents/profile.json
agent-skills-manifest: /nix/store/nk9iml2841l1yjjg0f6f0d3y60zkg1nn-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@4a0515f

Author: schickling-assistant

README.md

@@ -97,12 +97,31 @@ mkdir -p "$bundle/assets"
 cp examples/native/agent-codex.kdl "$bundle/agent.kdl"
 cp ./composed-AGENTS.md "$bundle/assets/AGENTS.md"
 ${EDITOR:-vi} "$bundle/agent.kdl"
-st2 agent publish --catalog "$CATALOG" --bundle "$bundle" --expect-absent --json
+input_sha256="$(st2 agent digest --bundle "$bundle")"
+st2 agent publish --catalog "$CATALOG" --bundle "$bundle" \
+  --input-sha256 "$input_sha256" --expect-absent --json
 ```
 
 Replace `<host>`, `<identity>`, `<workspace>`, and `<boot prompt>`. Include every file referenced by
 `copy` in the bundle. For a later declaration-only update, publish `agent.kdl` with the current
 declaration's SHA-256 via `--spec ... --expect-sha256 HEX`; sibling assets and state are preserved.
+Bind either operation to the exact captured source with the SHA-256 returned by
+`st2 agent digest`.
+
+To prepare and apply a complete declaration-plane replacement without copying
+runtime state or workspaces:
+
+```sh
+st2 catalog snapshot --catalog "$CATALOG" --output ./prepared --json
+# Edit/render ./prepared, then retain the rootSha256 from the snapshot receipt.
+st2 catalog apply --catalog "$CATALOG" --prepared ./prepared \
+  --expect-sha256 <rootSha256> --json
+```
+
+`catalog apply` is policy-free. It rejects state/control content, symlinks,
+unprojected workspaces, and effective PTY-root changes. A crash leaves a durable
+marker and content-addressed stage; rerunning the same prepared root and
+original expectation resumes it.
 
 The compact declaration shape is:
 
@@ -364,7 +383,8 @@ ls, up, down, validate, doctor
 message, ding, agents, status, context, resource
 env, pty, shell, pretrust
 hooks, service, eval
-agent publish
+agent digest, agent publish
+catalog snapshot, catalog apply
 completions
 ```
 
@@ -424,6 +444,8 @@ interviewer reply at-or-after the exact kickoff receipt completes it. Canonical
 verdict. Without the directive, Agent Spec-shaped files inside a fixture remain inert and compact
 evals retain their flat bus and completion semantics.
 
-`st2 agent publish --catalog ROOT (--spec FILE | --bundle DIR) (--expect-absent |
---expect-sha256 HEX)` is the sole catalog-declaration writer. The publisher admits the complete
+`st2 agent publish --catalog ROOT (--spec FILE | --bundle DIR) --input-sha256 HEX
+(--expect-absent | --expect-sha256 HEX)` is the single-agent declaration writer.
+`st2 catalog apply --catalog ROOT --prepared DIR --expect-sha256 ROOT_HEX` is the
+complete declaration-plane writer. Each admits the complete
 prospective catalog under a compare-and-swap lock before making one atomic change.

crates/agent-spec/src/discovery.rs

@@ -80,6 +80,19 @@ pub fn is_catalog_path(root: &Path, path: &Path) -> bool {
         return false;
     }
 
+    // Canonical state has a stable address independent of whether a declaration is currently
+    // present. This keeps orphan state after retirement/removal out of discovery and out of a
+    // whole-catalog transaction's declaration identity.
+    if components.first().and_then(|name| name.to_str()) == Some("agents")
+        && components.len() >= 4
+        && matches!(
+            components[3].to_str(),
+            Some("resources" | "archive" | "inbox" | "status")
+        )
+    {
+        return false;
+    }
+
     let mut parent = root.to_path_buf();
     for name in components {
         if matches!(name.to_str(), Some("resources" | "archive" | "inbox"))

docs/vrs/requirements.md

@@ -134,3 +134,12 @@ accepted.
   but performs zero lifecycle actions until the transaction is completed.
   Presence, messages, context, and Resource state remain independently writable
   and are never serialized behind catalog authoring.
+  A caller binds single-agent publication to the exact no-follow source capture
+  with an authoritative input digest. A canonical whole-catalog snapshot
+  externalizes the declaration-root digest while excluding runtime state and
+  catalog-contained workspaces. Whole-catalog apply accepts only that closed
+  declaration projection, rechecks the root digest under the exclusive lock,
+  durably stages the desired bytes, and converges after interruption from a
+  closed marker record. Version 1 rejects effective PTY-root changes. It never
+  deletes or relocates state, and newly created canonical identity directories
+  become visible only as complete bundles.

docs/vrs/spec.md

@@ -91,9 +91,11 @@ and the portable Agent Spec envelope in
 
 ## Transactional catalog authoring
 
+`st2 agent digest (--spec FILE | --bundle DIR)` captures a source through
+retained no-follow file descriptors and returns its authoritative digest.
 `st2 agent publish --catalog ROOT (--spec FILE | --bundle DIR)
-(--expect-absent | --expect-sha256 HEX) --json` is the sole supported
-declaration writer. It accepts exactly one canonical KDL `agent` node with an
+--input-sha256 HEX (--expect-absent | --expect-sha256 HEX) --json` binds
+publication to that exact capture. It accepts exactly one canonical KDL `agent` node with an
 explicit, path-safe host and identity. st2 no longer exposes an intent compiler:
 external renderers own the transformation from human intent to exact Agent Spec
 bytes or a create-only publication bundle.
@@ -104,18 +106,45 @@ read/write transaction domain:
 ```text
 publisher (EX)  : snapshot input -> CAS -> full-catalog admission -> atomic publish + fsync
 reader (SH)     : discover -> materialize/observe -> plan -> execute
-state plane     : message | context | Resource | status                 (unlocked)
+bulk apply (EX) : root CAS -> durable stage+marker -> converge -> verify+clear
+state plane     : message | context | Resource | status                    (unlocked)
 ```
 
 The publisher derives the destination from the captured declaration, replaces
 only `agent.kdl` for a hash-authorized update, and preserves all sibling runtime
 state. A bundle is create-only and is renamed from a hidden same-filesystem
 stage; retry reports `unchanged` only when every projected bundle file already
 matches. `--expect-absent` is idempotent for identical input.
-`--expect-sha256` rejects a stale writer. Full-catalog admission rejects any
+`--input-sha256` rejects a caller/source swap and `--expect-sha256` rejects a
+stale declaration writer. Full-catalog admission rejects any
 structural validation error before publication. The typed result is
 `published` or `unchanged`.
 
+`st2 catalog snapshot --catalog ROOT --output DIR --json` holds SH while it
+captures the canonical declaration projection: `catalog.kdl`, exact
+`agents/<host>/<identity>/agent.kdl` files, static files inside those bounded
+agent bundles, and catalog-owned files statically referenced by `render {
+copy ... }`. Runtime state, `.git`, `.st2`, the native `pty` registry, and
+arbitrary catalog-contained workspaces are excluded. The output is a
+create-only durable directory; an identical retry is `unchanged`. Its
+domain-separated, path-sorted root SHA-256 covers normalized relative paths,
+file bytes, and executable bits.
+
+`st2 catalog apply --catalog ROOT --prepared DIR --expect-sha256 HEX --json`
+rejects any prepared state/control path, symlink, special node, unprojected
+file/directory, malformed declaration, or effective PTY-root change. It
+captures and validates exact prepared bytes, takes EX, rechecks the canonical
+live root, and either reports `unchanged` or creates a durable content-addressed
+stage before publishing the marker. It changes declaration leaves only;
+canonical state directories and arbitrary workspaces are never traversed,
+deleted, or hashed. New identity bundles use an exclusive directory rename, so
+no empty identity becomes state-addressable. Applied leaves and their parents
+are fsynced, the live root is re-hashed and fully admitted, then the marker is
+unlinked and `.st2` is fsynced.
+The catalog parent is fsynced when `.st2` is first created, including the
+concurrent create/observe race. Retained source capture rejects a staging
+destination contained by its source before enumerating that source.
+
 The lock file is never removed: replacing its inode would split the transaction
 domain for processes that already hold it open. Reconciliation holds SH from
 discovery through execution. Validation, doctor, roster, listing,
@@ -128,18 +157,28 @@ transaction fence. Any presence is authoritative, including malformed content.
 The reserved canonical record is:
 
 ```json
-{"schema":"st2.catalog-apply-incomplete.v1","desiredStorePath":"/nix/store/..."}
+{"schema":"st2.catalog-apply-incomplete.v1","stageName":"catalog-apply-stage-<prepared-root-sha256>","expectedRootSha256":"<previous-root-sha256>","preparedRootSha256":"<prepared-root-sha256>","originalPaths":["<sorted-owned-declaration-leaf>", "..."]}
 ```
 
 After taking its authoring lock, st2 refuses publication, validation,
 materialization, teardown, roster, doctor, and catalog listing while the marker
 exists. One-shot and selected reconcile fail explicitly. A resident supervisor
 instead remains alive, reports a skipped/incomplete pass, and performs no
 runtime observation or lifecycle action, avoiding a service restart storm.
-Message, context, Resource, and status operations remain available. The future
-whole-catalog apply command owns marker creation, admission, durable apply,
-verification, and clearing inside one transaction; external lock execution and
-bypass flags are not part of the contract.
+Message, context, Resource, and status operations remain available. While the
+marker exists they resolve canonical state independently of live declaration
+discovery; an existing state-only orphan remains addressable, an incomplete new
+identity does not fall back to a flat bus. A dotted bare identity is tried as
+the complete local identity alongside every possible qualified bus-address
+split; exactly one distinct canonical address must exist. Only real state
+directories and a real regular status file can establish marker-time addressability. Only
+`catalog apply` may open an existing marker. A retry must name the same prepared
+and expected roots; marker
+authority proves the original CAS already passed, so recovery converges the
+partial live tree from the durable desired stage and original owned-leaf list
+without re-enforcing that stale precondition. Malformed or
+mismatched records remain fenced. External lock execution and bypass flags are
+not part of the contract.
 
 ## Host-local scheduling and supervision
 

examples/README.md

@@ -13,7 +13,9 @@ and gate the result before starting a process:
 ```sh
 st2 hooks install
 st2 hooks verify
-st2 agent publish --catalog <catalog> --bundle <bundle> --expect-absent --json
+input_sha256="$(st2 agent digest --bundle <bundle>)"
+st2 agent publish --catalog <catalog> --bundle <bundle> \
+  --input-sha256 "$input_sha256" --expect-absent --json
 st2 validate --catalog <catalog>
 st2 up --catalog <catalog> --host <host> --materialize-only
 st2 up --catalog <catalog> --host <host> --once

examples/native/README.md

@@ -25,7 +25,9 @@ Use this sequence:
 ```sh
 st2 hooks install
 st2 hooks verify
-st2 agent publish --catalog <catalog> --bundle <bundle> --expect-absent --json
+input_sha256="$(st2 agent digest --bundle <bundle>)"
+st2 agent publish --catalog <catalog> --bundle <bundle> \
+  --input-sha256 "$input_sha256" --expect-absent --json
 st2 validate <catalog>
 st2 up <catalog> --host <host> --materialize-only
 st2 up <catalog> --host <host> --once