docs(catalog): define opaque raw preimages

agent-identity: dev3.direct.omp.2cshu64q
agent-persona: generalist
agent-supervisor: unavailable
agent-tool: OMP
agent-tool-version: 18.0.9
agent-runtime: OMP 18.0.9
tooling-profile: dotfiles@b607597

Author: schickling-assistant

README.md

@@ -156,8 +156,8 @@ st2 catalog apply --catalog "$CATALOG" --prepared ./prepared \
   --input-sha256 <afterRootSha256> --expect-sha256 <rootSha256> --json
 ```
 
-If the incumbent Agent Specs cannot be parsed, bind a one-time repair to their
-exact structural declaration bytes instead:
+If the incumbent declarations cannot be parsed or must remain opaque to the
+current parser, bind a one-time repair to their exact structural bytes instead:
 
 ```sh
 st2 catalog snapshot --catalog "$CATALOG" --output ./invalid-preimage \
@@ -169,11 +169,12 @@ st2 catalog apply --catalog "$CATALOG" --prepared ./prepared \
   --raw-preimage --json
 ```
 
-Raw-preimage mode has its own hash and receipt schemas. It refuses a
-strictly-valid incumbent, still fully validates the prepared and applied
-catalogs, and requires a readable external PTY-root declaration that remains
-unchanged. It is a generic invalid-preimage transaction, not a validation
-bypass or migration-policy engine.
+Raw-preimage mode has its own hash and receipt schemas. It makes no semantic
+assertion about the live bytes—including validity, profiles, the catalog
+envelope, or effective PTY root—while still fully validating the prepared and
+applied catalogs. The caller-supplied raw-domain digest is the exact live
+precondition. This is a byte-oriented transaction, not a validation bypass or
+migration-policy engine.
 
 To publish that exact snapshot as a new, absent catalog:
 
@@ -182,18 +183,19 @@ st2 catalog bootstrap --catalog "$NEW_CATALOG" --prepared ./prepared \
   --input-sha256 <rootSha256> --json
 ```
 
-`catalog apply` is policy-free. It rejects state/control content, symlinks,
-unprojected workspace facts, catalog-local/default PTY roots, and effective
-PTY-root changes. Bootstrap is a separate create-only declaration transaction,
-not an apply mode. It atomically publishes absence or the complete catalog,
-initializes its persistent lock and generation before visibility, and never
-reads or writes the external PTY registry. Process adoption and PTY-root
-migration remain separate because that registry has independent producers. A
-crash during apply leaves a durable marker and content-addressed stage;
-`st2 catalog apply --catalog "$CATALOG" --resume --json` resumes without the
-original prepared source. Snapshots own the complete bounded `_templates`
-library and empty canonical per-agent `.workspace` directory facts, but never
-traverse, hash, copy, or delete workspace content.
+Ordinary `catalog apply` is policy-free. It rejects state/control content,
+symlinks, unprojected workspace facts, catalog-local/default PTY roots, and
+effective PTY-root changes. Raw-preimage apply replaces those live semantic
+checks with its exact byte-domain CAS. Bootstrap is a separate create-only
+declaration transaction, not an apply mode. It atomically publishes absence or
+the complete catalog, initializes its persistent lock and generation before
+visibility, and never reads or writes the external PTY registry. Process
+adoption and PTY-root migration remain separate because that registry has
+independent producers. A crash during apply leaves a durable marker and
+content-addressed stage. `st2 catalog apply --catalog "$CATALOG" --resume --json`
+resumes without the original prepared source. Snapshots own the complete
+bounded `_templates` library and empty canonical per-agent `.workspace`
+directory facts, but never traverse, hash, copy, or delete workspace content.
 
 The compact declaration shape is:
 
@@ -687,9 +689,10 @@ evals retain their flat bus and completion semantics.
 declaration-plane writer. Each admits the complete prospective catalog under a
 compare-and-swap lock before making one atomic change.
 `st2 catalog digest --catalog ROOT --prepared DIR` computes the exact desired
-projection digest consumed by apply, including for raw-preimage repair where the
-invalid incumbent cannot support semantic diff. Ordinary valid-catalog workflows
-reuse `afterRootSha256` from the required policy-inspection diff instead.
+projection digest consumed by apply. Raw-preimage repair uses it for the fully
+validated successor while binding the opaque incumbent through the separate
+raw-domain digest. Ordinary valid-catalog workflows reuse `afterRootSha256`
+from the required policy-inspection diff instead.
 `st2 catalog bootstrap --catalog ROOT --prepared DIR --input-sha256 ROOT_HEX`
 is the create-only writer for an absent catalog. An exact completed replay is
 `unchanged`; any different or incomplete existing target fails closed.

docs/vrs/requirements.md

@@ -219,12 +219,13 @@ accepted.
   caller-supplied input digest before locking or mutation, rechecks the incumbent
   root digest under the exclusive lock, durably stages the desired bytes, and resumes
   after interruption solely from a closed marker and its content-addressed
-  stage. A distinct raw-preimage projection may bind a repair to the exact
-  structural declaration bytes of an invalid incumbent without interpreting
-  those bytes. It has a separate hash and receipt type, refuses a strictly valid
-  incumbent, admits only a fully valid prepared result, and persists its mode in
-  the recovery marker. Version 1 requires one explicit external PTY root and
-  rejects effective PTY-root changes. Fresh-catalog bootstrap is a distinct create transaction,
+  stage. A distinct raw-preimage projection may bind a repair or migration to
+  the exact structural declaration bytes of any incumbent without interpreting
+  those bytes. It has a separate hash and receipt type, admits only a fully
+  valid prepared result, and persists its mode in the recovery marker. Raw mode
+  makes no semantic assertion about the incumbent, including its validity or
+  effective PTY root; the caller's exact raw-domain digest is the complete live
+  precondition. Fresh-catalog bootstrap is a distinct create transaction,
   not a catalog-apply mode: it binds an exact captured prepared projection to a
   caller-supplied digest, initializes the persistent authoring lock and first
   catalog generation before visibility, and publishes the complete catalog by

docs/vrs/spec.md

@@ -307,15 +307,14 @@ covers normalized relative paths, file bytes, executable bits, and empty
 workspace directory facts.
 
 `st2 catalog snapshot --catalog ROOT --output DIR --raw-preimage --json`
-exists only to externalize CAS for an invalid incumbent. Under the same shared
-lock it structurally captures `catalog.kdl`, canonical
+externalizes a byte-oriented CAS preimage. Under the same shared lock it
+structurally captures `catalog.kdl`, canonical
 `agents/<host>/<identity>/agent.kdl` leaves, their bounded static bundle files,
 the bounded `_templates` tree, and existing canonical `.workspace` directory
-facts without parsing Agent Spec bytes. The ordinary state/control exclusions
+facts without parsing declaration bytes. The ordinary state/control exclusions
 still apply. Every captured input must be a safe real file or directory with no
-symlink or hard-link alias. The incumbent catalog envelope must parse and name
-an external PTY root. A catalog that passes strict projection, live workspace
-validation, and full admission is refused. Its root uses the distinct
+symlink or hard-link alias. No live validity, catalog-envelope, profile, or
+effective PTY-root assertion exists in this mode. Its root uses the distinct
 `st2.catalog-raw-preimage-root.v1` hash domain and the receipt schema is
 `st2.catalog-raw-preimage-snapshot.v1`; it is not interchangeable with a strict
 snapshot root. Create-only retry rechecks both the raw root and output link
@@ -471,18 +470,18 @@ External lock execution and bypass flags are not part of the contract.
 `st2 catalog apply --catalog ROOT --prepared DIR --input-sha256 INPUT_HEX --expect-sha256 HEX
 --raw-preimage --json` is the only writer that accepts the raw-preimage root.
 It first captures and fully admits `DIR` through the ordinary strict prepared
-projection. Under EX it refuses a strictly valid incumbent, requires the
-incumbent catalog envelope to parse, proves the effective external PTY root is
-unchanged, structurally reprojects the invalid live declaration plane, and
-checks its raw-domain root against `HEX` before any declaration, workspace,
-state, writer-temporary, marker, or stage mutation. A successful CAS reuses the
-ordinary durable stage, generation commit, leaf publication, strict live
-verification, and fsync sequence. Its receipt schema is
+projection. Under EX it structurally reprojects the opaque live declaration
+plane and checks its raw-domain root against `HEX` before any declaration,
+workspace, state, writer-temporary, marker, or stage mutation. It never parses
+or semantically validates the live bytes, including their catalog envelope,
+profiles, validity, or effective PTY root. A successful CAS reuses the ordinary
+durable stage, generation commit, leaf publication, strict live verification,
+and fsync sequence. Its receipt schema is
 `st2.catalog-raw-preimage-apply.v1`; its durable marker schema is
 `st2.catalog-raw-preimage-apply-incomplete.v1`. The marker schema preserves the
 projection type, so source-free `--resume` emits the truthful raw-preimage
 receipt after converging from the strictly validated stage. This mode owns no
-policy for interpreting or transforming invalid bytes.
+policy for interpreting or transforming incumbent bytes.
 
 `st2 catalog bootstrap --catalog ROOT --prepared DIR --input-sha256 HEX --json`
 is the create-only declaration transaction for an absent catalog. `ROOT` must