Skip to content

Add read-only prepared catalog semantic diff - #143

Merged
schickling-assistant merged 1 commit into
mainfrom
schickling-assistant/2026-08-01-catalog-semantic-diff
Aug 1, 2026
Merged

Add read-only prepared catalog semantic diff#143
schickling-assistant merged 1 commit into
mainfrom
schickling-assistant/2026-08-01-catalog-semantic-diff

Conversation

@schickling-assistant

@schickling-assistant schickling-assistant commented Aug 1, 2026

Copy link
Copy Markdown
Contributor

Why

Transactional catalog consumers can prove the live declaration root, but they cannot currently inspect what a fully admitted prepared catalog would change without applying it. That forces downstream policy to infer semantics from bytes or duplicate Agent Spec parsing.

What

  • add st2 catalog diff --prepared DIR --expect-sha256 HEX --json
  • hold the existing shared authoring lock and capture prepared input through retained no-follow capabilities
  • fully admit both live and prepared projections before emitting a receipt
  • report versioned, deterministically ordered projected-path and normalized Agent Spec-model field deltas
  • keep payload values, per-field hashes, migration policy, and publication authority out of the receipt
  • document the durable requirement and exact receipt contract

The command is read-only: it does not initialize a catalog or write declarations, markers, generation state, runtime state, workspaces, or the prepared source.

Verification

  • cargo test --test catalog_diff: 14 passed
  • cargo clippy --test catalog_diff -- --cap-lints warn: passed; only pre-existing library warnings remain
  • independent implementation and VRS reviews: approved
  • cargo test --workspace --all-targets: remainder passed with the documented host-isolation skip after excluding four failures reproduced on the pristine base; one transient PTY registry test passed on isolated retry

The remaining effect-level path normalization and watcher consumption gap stays explicit in the Agent Spec VRS and is outside this policy-free primitive.

agent-session-id: ed878dac-3735-4276-b3e0-ea1b1cd65291
agent-tool: Codex CLI
agent-tool-version: 0.145.0
agent-model: unknown
agent-runtime-profile: /nix/store/mnx8agbdq3wiyb6vz63lhgscgazkrn98-coding-agent-runtime-profile/share/coding-agents/profile.json
agent-skills-manifest: /nix/store/5r69m9k2llmri3na81518zx0a7y0d3cn-agent-skills-corpus/share/agent-skills/manifest.json
tooling-profile: dotfiles@0fb7e03
@schickling-assistant
schickling-assistant marked this pull request as ready for review August 1, 2026 14:24
@schickling-assistant
schickling-assistant marked this pull request as draft August 1, 2026 14:24
@schickling-assistant
schickling-assistant marked this pull request as ready for review August 1, 2026 14:24
@schickling-assistant
schickling-assistant merged commit 509ffb4 into main Aug 1, 2026
1 check passed
@schickling-assistant

Copy link
Copy Markdown
Contributor Author

Thanks @myobie for the careful guidance on the PTY boundary and for making the upstream primitives strong enough to keep this comparison policy-free. Merged cleanly!

celebration dance

@schickling schickling added area:agent-spec Agent Spec format, parsing, and the agent-spec crate · Set: manual area:catalog Catalog structure, declarations, transactions, and admission · Set: manual origin:agent Filed or primarily produced by an AI agent · Set: manual type:feature New user-visible or system capability · Set: manual labels Aug 18, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

area:agent-spec Agent Spec format, parsing, and the agent-spec crate · Set: manual area:catalog Catalog structure, declarations, transactions, and admission · Set: manual origin:agent Filed or primarily produced by an AI agent · Set: manual type:feature New user-visible or system capability · Set: manual

Projects

None yet

Development

Successfully merging this pull request may close these issues.

2 participants