feat(catalog): repair invalid preimages atomically

[schickling]

Why

A clean Agent Spec format transition can leave a live catalog whose declaration bytes are structurally safe but no longer parse under the current schema. The existing catalog snapshot / catalog apply path correctly requires a valid incumbent, so operators otherwise have to publish repaired declarations outside st2's catalog-wide lock, CAS, durable marker, and crash recovery.

This became concrete after #262. Strict rejection is not a bug; the missing piece is an explicit, narrowly fenced upgrade path.

What

Add st2 catalog snapshot --raw-preimage and st2 catalog apply --raw-preimage.

• The current declaration plane is hashed structurally under a distinct raw hash domain.
• Raw mode is allowed only when the current catalog fails normal strict admission.
• The prepared, staged, and resulting catalogs remain fully parsed and validated.
• The incumbent catalog envelope must parse and the effective external PTY root must remain unchanged.
• A distinct durable marker preserves raw-preimage authority across source-free --resume.

How

The implementation reuses the existing catalog transaction: persistent authoring lock, retained no-follow projection, declaration-root CAS, content-addressed stage, durable apply marker, generation commit, fsync boundaries, and recovery. Wrong raw CAS is checked before writer-temporary cleanup, stage/marker publication, or declaration/workspace/state mutation.

The primitive owns no schema migration policy. It never interprets the invalid declaration bytes; callers prepare a complete valid postimage offline.

Rationale

Keeping this as an explicit flag on the existing snapshot/apply commands makes the authority boundary visible without adding a second publisher. Separate raw snapshot/apply/marker schemas and hash domains prevent raw and strict receipts from being confused. Refusing already-valid incumbents prevents the mode from becoming a general validation bypass.

Verification

• Focused raw-preimage controls: 5/5 passed
• cargo test --test catalog_apply --all-features: 46/46 passed
• cargo check --all-targets --all-features: passed
• Exact-commit independent contract review: passed
• git diff --check: passed

The repository-wide suite is not globally green on current main: an untouched catalog-diff admission test fails; with that skipped, an unrelated eval E2E route-freeze test timed out; one runtime-owner lock test flaked once and passed alone. Existing Clippy warnings also remain outside this diff.

Related

• Remove Resource _tag and derive profiles from URI schemes #262 clean Agent Spec transition that motivated the repair seam
• Add crash-recoverable catalog snapshot and apply #113 strict crash-recoverable snapshot/apply foundation
• Fresh catalogs cannot enter the transactional snapshot/apply path #141 / feat: add transactional catalog bootstrap #142 absent-catalog bootstrap (different boundary)
• Define Agent Spec schema versioning and compatibility semantics #127 future schema-version policy
• Incubate a transactional content-addressed Agent Spec catalog #52 longer-term immutable catalog design

[chatgpt-codex-connector]

You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard.
To continue using code reviews, add credits to your account and enable them for code reviews in your settings.