feat(catalog): repair invalid preimages atomically

README.md

@@ -125,6 +125,23 @@ st2 catalog apply --catalog "$CATALOG" --prepared ./prepared \
   --expect-sha256 <rootSha256> --json
 ```
 
+If the incumbent Agent Specs cannot be parsed, bind a one-time repair to their
+exact structural declaration bytes instead:
+
+```sh
+st2 catalog snapshot --catalog "$CATALOG" --output ./invalid-preimage \
+  --raw-preimage --json
+# Produce a fully valid ./prepared directory from that capture.
+st2 catalog apply --catalog "$CATALOG" --prepared ./prepared \
+  --expect-sha256 <raw-rootSha256> --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.
+
 To publish that exact snapshot as a new, absent catalog:
 
 ```sh
@@ -580,7 +597,7 @@ evals retain their flat bus and completion semantics.
 `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 | --resume)` is the complete
+(--prepared DIR --expect-sha256 ROOT_HEX [--raw-preimage] | --resume)` is the complete
 declaration-plane writer. Each admits the complete prospective catalog under a
 compare-and-swap lock before making one atomic change.
 `st2 catalog bootstrap --catalog ROOT --prepared DIR --input-sha256 ROOT_HEX`

docs/vrs/requirements.md

@@ -192,8 +192,12 @@ accepted.
   facts. Whole-catalog apply accepts only that projection, rechecks the 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. 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 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,
   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

@@ -292,6 +292,21 @@ identical retry is `unchanged`. Its domain-separated, path-sorted root SHA-256
 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
+`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
+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
+`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
+counts.
+
 `st2 catalog diff --catalog ROOT --prepared DIR --expect-sha256 HEX --json`
 holds the existing authoring lock in shared mode and performs no initialization
 or publication. It projects and fully admits the coherent live catalog, rejects
@@ -428,6 +443,22 @@ 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.
 
+`st2 catalog apply --catalog ROOT --prepared DIR --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
+`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.
+
 `st2 catalog bootstrap --catalog ROOT --prepared DIR --input-sha256 HEX --json`
 is the create-only declaration transaction for an absent catalog. `ROOT` must
 be one absent final component below an existing canonical real parent. st2