Freeze canonical Target IR artifacts

[flyingrobots]

Summary

Closes #105.

This freezes canonical Target IR artifact bytes and digests for the current Echo and git-warp Target IR envelope without expanding into runtime execution, verifier reports, general target plugin dispatch, admission execution, or canonical ContractBundleManifest bytes.

• Adds the intentional edict.target-ir.artifact/v1 canonical value/digest frame and public encode_target_ir_artifact / digest_target_ir_artifact APIs.
• Adds strict lowercase digest locking for Target IR artifact target-profile references before hashing.
• Adds deterministic Echo and git-warp byte/digest goldens under fixtures/target-ir/canonical/ plus cargo xtask target-ir-goldens --check/--write, wired into cargo xtask verify.
• Adds mutation/determinism tests for Target IR bytes and digest sensitivity.
• Adds assemble_contract_bundle_from_target_ir(...) so bundle assembly can compute targetIrDigest from a real TargetIrArtifact without a caller-supplied target IR digest field.
• Updates Target IR and contract-bundle topic shelves, the v0.11 design note, and the changelog to describe current branch truth.

Scope Boundaries

• Freezes canonical Target IR artifact bytes and digest values for the existing Echo/git-warp review artifacts.
• Does not freeze canonical ContractBundleManifest bytes.
• Does not add Echo execution, git-warp execution, verifier reports, admission execution, new target profiles, or general plugin dispatch.

RED

• cargo test -p edict-syntax target_ir_artifact failed because digest_target_ir_artifact, encode_target_ir_artifact, and TARGET_IR_ARTIFACT_DIGEST_DOMAIN did not exist.
• cargo xtask target-ir-goldens --check failed first because the command was unknown, then failed because the Target IR golden fixtures were absent.
• cargo test -p edict-syntax assembled_bundle_from_real_target_ir_computes_target_ir_digest failed because assemble_contract_bundle_from_target_ir and ContractBundleAssemblyFromTargetIrInput did not exist.

GREEN

• cargo test -p edict-syntax target_ir
• cargo test -p edict-syntax contract_bundle_assembly
• cargo test -p xtask target_ir_goldens_match_executable_encoder
• cargo xtask target-ir-goldens --check
• cargo xtask contract-check
• cargo xtask verify

Golden Digests

• Echo Target IR: sha256:f5a81ddfb84a704c180c9c0e03210445da1873bea397edc8ac683738710ed2b7
• git-warp Target IR: sha256:032dba1b21bc18970ccfb05141d9ad1fd2f1ab94b6de0cd6e853c04e76eeb116

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: ae19c2ba-5b7b-43b0-81bc-59b1c3482532

📥 Commits

Reviewing files that changed from the base of the PR and between d613833 and 099a5cf.

📒 Files selected for processing (4)

• CHANGELOG.md
• crates/edict-syntax/src/contract_bundle.rs
• crates/edict-syntax/tests/contract_bundle.rs
• docs/topics/contract-bundles/test-plan.md

📜 Recent review details

🧰 Additional context used

📓 Path-based instructions (2)

**

⚙️ CodeRabbit configuration file

**: # AGENTS

Git Rules

NEVER amend git commits. Make a new commit instead.

NEVER use git rebase unless the user explicitly approves a rare exception.
Use regular merge commits.

NEVER force any git operation. If a force operation appears necessary, stop and
explain what happened and what options remain.

NEVER create draft pull requests.

NEVER use a codex prefix in branch names, PR titles, or commit messages.

Pull request bodies for issue work MUST include GitHub auto-close text such as
Closes #123`` for every issue the PR is intended to close.

Think

Think is durable memory for cross-session coordination.

• Use codex-think --remember --json when starting a new session, changing into
  this repository, or regaining context after a context shift.
• Use codex-think "..." --json when a cycle closes or a significant event
  should survive across turns.
• Treat Think as memory, not repo truth. Anchor strong claims back to files,
  commits, commands, issues, or pull requests.
• Claude memories are read-only. Use claude-think --remember --json only for
  additional context.

Topic Shelves

docs/topics/ contains the living contract graph for landed behavior. Topic
shelves are not proposals, retrospectives, or design archaeology.

Each shelf may contain:

• README.md: what is true in HEAD.
• test-plan.md: how those truths are verified, including requirements, cases,
  fixtures, oracles, implemented evidence, planned cases, and known gaps.
• architecture.md: optional structure or dataflow notes when the machinery
  earns a separate page.
• rationale.md: optional still-relevant tradeoffs and rejected approaches.

When To Update Topic Shelves

For every nontrivial behavior, contract, workflow, release, schema, validation,
or public-surface change:

1. Identify the owning topic shelf before editing code.
2. If no shelf owns durable behavior, create one.
3. Update test-plan.md before or alongside tests with requirement IDs, case
   IDs,...

Files:

• CHANGELOG.md
• crates/edict-syntax/tests/contract_bundle.rs
• crates/edict-syntax/src/contract_bundle.rs
• docs/topics/contract-bundles/test-plan.md

docs/topics/**/test-plan.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/topics/**/test-plan.md: Update a topic shelf test-plan.md before or alongside tests with requirement IDs, case IDs, fixtures, oracles, implemented evidence, planned cases, and known gaps.
Mark planned cases as implemented only when executable evidence exists.
Do not use policy rows in topic-shelf test plans to avoid writing behavior tests for software behavior.
Negative tests in topic-shelf test plans should assert stable error kinds or structured artifacts, not merely is_err() or diagnostic text.
For nontrivial behavior, contract, workflow, release, schema, validation, or public-surface changes, update the owning topic test-plan.md with planned requirement and case rows before or alongside the first test.
Mark planned rows as implemented only after executable evidence exists.

Files:

• docs/topics/contract-bundles/test-plan.md

🔇 Additional comments (4)

crates/edict-syntax/src/contract_bundle.rs (1)

527-532: LGTM!

crates/edict-syntax/tests/contract_bundle.rs (1)

448-527: LGTM!

Also applies to: 589-654

CHANGELOG.md (1)

40-48: LGTM!

docs/topics/contract-bundles/test-plan.md (1)

13-14: LGTM!

Also applies to: 27-28, 46-46, 68-71, 84-89

---

Summary by CodeRabbit

• New Features
  • Added canonical Target IR artifact encoding and domain-separated digest support (including new public APIs and digest domain constant).
  • Contract bundles can now be assembled from a real Target IR artifact; the Target IR digest is computed automatically.
  • Added cargo xtask target-ir-goldens (with --write/--check) and wired it into verification.
• Bug Fixes
  • Rejects Target IR artifacts when the embedded source Core coordinate doesn’t match the selected Core module.
  • Improved rejection and stable error reporting for invalid/missing Target IR digest inputs.
• Documentation / Tests
  • Updated Target IR and contract bundle design/topic docs; refreshed canonical fixtures and expanded determinism/digest tests.

Walkthrough

Adds canonical CBOR encoding and digest framing for TargetIrArtifact, reviewed golden fixtures for Echo and git-warp, an xtask golden check/write command wired into cargo xtask verify, and assemble_contract_bundle_from_target_ir that computes targetIrDigest from a real artifact and validates source Core coordinate consistency.

Changes

Canonical Target IR Encoding, Digests, Goldens, and Bundle Integration

Layer / File(s)	Summary
Target IR canonical value construction and public encode/digest APIs crates/edict-syntax/src/canonical.rs, crates/edict-syntax/src/lib.rs	Adds TARGET_IR_ARTIFACT_DIGEST_DOMAIN, encode_target_ir_artifact, digest_target_ir_artifact, and private canonical map builders that validate coordinates, resolved digests, and lowercase sha256 review strings; re-exports the new APIs from lib.rs.
Target IR canonical encoding and digest tests crates/edict-syntax/tests/target_ir.rs	Adds gitwarp_artifact plus determinism, canonicalization, semantic-mutation, obstruction-arm, and digest-validation tests for TargetIrArtifact encoding and digesting.
assemble_contract_bundle_from_target_ir and TargetIrSourceMismatch crates/edict-syntax/src/contract_bundle.rs, crates/edict-syntax/tests/contract_bundle.rs	Adds TargetIrSourceMismatch, ContractBundleAssemblyFromTargetIrInput, and assemble_contract_bundle_from_target_ir; the new path validates source Core coordinates, computes the Target IR digest from the artifact, derives a digest-locked target profile, and delegates to existing bundle assembly. Test coverage adds the computed-Target-IR path plus mismatch and invalid embedded target-profile digest failures.
xtask target-ir-goldens command and verify integration xtask/src/main.rs, fixtures/target-ir/canonical/*.sha256	Adds TargetIrGoldenMode/Kind/Case, the target_ir_goldens pipeline for Echo and git-warp, CLI dispatch for --write/--check, verify integration, two reviewed sha256 fixture files, and a unit test that checks executable output against goldens.
Design docs, topic docs, test plans, and changelog docs/design/canonical-target-ir-v0.11.md, docs/design/contract-bundle-assembly-v0.11.md, docs/topics/contract-bundles/..., docs/topics/target-ir/..., CHANGELOG.md	Adds the canonical-target-ir design doc, updates contract-bundle assembly design and topic docs, revises target-ir topic docs and test plans, and updates the changelog to describe the computed Target IR digest path and reviewed goldens.

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~60 minutes

Possibly related issues

• #105: Directly matches the added canonical Target IR encoder/digest work, reviewed goldens, and bundle assembly integration for computed targetIrDigest.
• v0.11: assemble a contract bundle from digest-locked artifact references #106: Strong code-level overlap with the new bundle-assembly path that computes targetIrDigest from a real TargetIrArtifact.

Possibly related PRs

• flyingrobots/edict#67: Introduces the TargetIrArtifact lowering surface that this PR encodes, digests, and feeds into bundle assembly.

Poem

Bytes meet CBOR, neat and tight,
Goldens guard the digest right.
Source and module must align,
Else the bundle throws a sign.
xtask verify now keeps the flame,
Reviewed hashes win the game.

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Title check	✅ Passed	The title clearly captures the main change: freezing canonical Target IR artifacts.
Description check	✅ Passed	The description matches the PR scope and accurately summarizes the Target IR freeze and bundle-assembly work.
Linked Issues check	✅ Passed	The changes implement the canonical Target IR encoder/digest, goldens, xtask workflow, and bundle-assembly integration required by #105.
Out of Scope Changes check	✅ Passed	The diff stays focused on Target IR canonicalization, tests, docs, and bundle integration without unrelated feature work.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[flyingrobots]

@codex review please

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 827c0c5276

ℹ️ About Codex in GitHub

Your team has set up Codex to review pull requests in this repo. Reviews are triggered when you

• Open a pull request for review
• Mark a draft as ready
• Comment "@codex review".

If Codex has suggestions, it will comment; otherwise it will react with 👍.

Codex can also answer questions or update the PR. Try commenting "@codex address that feedback".

[flyingrobots]

@codex self-audit found additional issue before fixes:

Priority	Source	File	Lines	Issue	Planned handling
P3	Self	crates/edict-syntax/tests/target_ir.rs, docs/topics/target-ir/test-plan.md	test EOF / TIR-TP-018..019	Implemented evidence claims obstruction-arm mutation sensitivity and step-order preservation, but current tests only mutate obstruction failure keys and do not prove step order changes digest.	Add focused RED coverage, then minimal test-only/doc evidence correction if needed.

[chatgpt-codex-connector]

Summary

• Added Target IR digest mutation evidence for obstruction arm value changes and target step-order swaps, closing the self-audit gap without changing production behavior. crates/edict-syntax/tests/target_ir.rsL1013-L1019 crates/edict-syntax/tests/target_ir.rsL1045-L1053
• Corrected the Target IR test-plan claims so construction-order canonicalization is scoped to equivalent construction order, while semantic step-order sensitivity is claimed under mutation evidence. docs/topics/target-ir/test-plan.mdL78-L79
• Committed the changes on the current branch with commit 61d5ad7 (Tighten Target IR digest evidence) and created the follow-up PR via make_pr.

Testing

• ✅ cargo test -p edict-syntax target_ir_digest_moves_for_artifact_semantic_mutations
• ✅ cargo test -p edict-syntax target_ir_artifact_canonicalization_ignores_equivalent_construction_order
• ✅ cargo xtask verify

View task →

[flyingrobots]

Code Lawyer Activity Summary

#	Priority	Source	File	Issue	Commit	Outcome
1	P2	PR	crates/edict-syntax/src/contract_bundle.rs	Computed Target IR bundle assembly accepted Core/Target IR source-coordinate mismatches.	36c40f7	Added TargetIrSourceMismatch, rejected mismatched target_ir_artifact.source_core_coordinate, updated docs/changelog, resolved review thread.
2	P3	Self	crates/edict-syntax/tests/target_ir.rs, docs/topics/target-ir/test-plan.md	Implemented evidence undercovered obstruction-arm mutation and step-order digest sensitivity.	d613833	Added focused Target IR digest tests and updated test-plan evidence.

Verification:

• RED: cargo test -p edict-syntax assembly_from_target_ir_rejects_mismatched_core_source failed on missing TargetIrSourceMismatch.
• RED: cargo xtask contract-check failed because target_ir_step_order_changes_digest did not match a Rust test function.
• GREEN: cargo test -p edict-syntax contract_bundle_assembly
• GREEN: cargo test -p edict-syntax --test target_ir target_ir_step_order_changes_digest
• GREEN: cargo test -p edict-syntax --test target_ir target_ir_obstruction_arm_value_mutation_moves_digest
• GREEN: cargo test -p edict-syntax target_ir
• GREEN: cargo xtask contract-check
• GREEN: cargo xtask verify

[coderabbitai]

Actionable comments posted: 2

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@crates/edict-syntax/src/contract_bundle.rs`:
- Around line 527-531: Validate target_ir_artifact.target_profile before calling
digest_target_ir_artifact, so ContractBundleAssemblyError reports the stable
InvalidDigest failure for target_ir_artifact.target_profile instead of a generic
canonical-digest error on target_ir_artifact. Reorder the logic in the
contract_bundle assembly path to invoke target_profile_from_target_ir_artifact
first, then hash only after that reference is known to be valid, preserving the
existing error conversion and symbol names used in this flow.

In `@docs/topics/target-ir/test-plan.md`:
- Around line 77-83: The test-plan rows for TIR-TP-018 and TIR-TP-019 are marked
implemented without matching executable evidence in the PR. Update the rows in
the test-plan and the related coverage in crates/edict-syntax/tests/target_ir.rs
so they only claim behavior that is actually covered, or add the missing
RED/GREEN tests (especially step-order digest sensitivity) and then keep the
rows as implemented. Use the existing target_ir_* test names and the
TIR-TP-018/TIR-TP-019 entries to align the wording with the real evidence before
merge.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro

Run ID: cdb633cf-b5c5-4faf-a86d-668568cfea92

📥 Commits

Reviewing files that changed from the base of the PR and between 45c00c6 and d613833.

📒 Files selected for processing (17)

• CHANGELOG.md
• crates/edict-syntax/src/canonical.rs
• crates/edict-syntax/src/contract_bundle.rs
• crates/edict-syntax/src/lib.rs
• crates/edict-syntax/tests/contract_bundle.rs
• crates/edict-syntax/tests/target_ir.rs
• docs/design/canonical-target-ir-v0.11.md
• docs/design/contract-bundle-assembly-v0.11.md
• docs/topics/contract-bundles/README.md
• docs/topics/contract-bundles/test-plan.md
• docs/topics/target-ir/README.md
• docs/topics/target-ir/test-plan.md
• fixtures/target-ir/canonical/echo-effectful.target-ir.cbor
• fixtures/target-ir/canonical/echo-effectful.target-ir.sha256
• fixtures/target-ir/canonical/gitwarp-append.target-ir.cbor
• fixtures/target-ir/canonical/gitwarp-append.target-ir.sha256
• xtask/src/main.rs

📜 Review details

🧰 Additional context used

📓 Path-based instructions (3)

**

⚙️ CodeRabbit configuration file

**: # AGENTS

Git Rules

NEVER amend git commits. Make a new commit instead.

NEVER use git rebase unless the user explicitly approves a rare exception.
Use regular merge commits.

NEVER force any git operation. If a force operation appears necessary, stop and
explain what happened and what options remain.

NEVER create draft pull requests.

NEVER use a codex prefix in branch names, PR titles, or commit messages.

Pull request bodies for issue work MUST include GitHub auto-close text such as
Closes #123`` for every issue the PR is intended to close.

Think

Think is durable memory for cross-session coordination.

• Use codex-think --remember --json when starting a new session, changing into
  this repository, or regaining context after a context shift.
• Use codex-think "..." --json when a cycle closes or a significant event
  should survive across turns.
• Treat Think as memory, not repo truth. Anchor strong claims back to files,
  commits, commands, issues, or pull requests.
• Claude memories are read-only. Use claude-think --remember --json only for
  additional context.

Topic Shelves

docs/topics/ contains the living contract graph for landed behavior. Topic
shelves are not proposals, retrospectives, or design archaeology.

Each shelf may contain:

• README.md: what is true in HEAD.
• test-plan.md: how those truths are verified, including requirements, cases,
  fixtures, oracles, implemented evidence, planned cases, and known gaps.
• architecture.md: optional structure or dataflow notes when the machinery
  earns a separate page.
• rationale.md: optional still-relevant tradeoffs and rejected approaches.

When To Update Topic Shelves

For every nontrivial behavior, contract, workflow, release, schema, validation,
or public-surface change:

1. Identify the owning topic shelf before editing code.
2. If no shelf owns durable behavior, create one.
3. Update test-plan.md before or alongside tests with requirement IDs, case
   IDs,...

Files:

• fixtures/target-ir/canonical/gitwarp-append.target-ir.sha256
• fixtures/target-ir/canonical/echo-effectful.target-ir.sha256
• docs/design/canonical-target-ir-v0.11.md
• CHANGELOG.md
• docs/design/contract-bundle-assembly-v0.11.md
• docs/topics/target-ir/test-plan.md
• crates/edict-syntax/src/contract_bundle.rs
• xtask/src/main.rs
• crates/edict-syntax/tests/contract_bundle.rs
• crates/edict-syntax/src/lib.rs
• docs/topics/contract-bundles/README.md
• docs/topics/target-ir/README.md
• docs/topics/contract-bundles/test-plan.md
• crates/edict-syntax/src/canonical.rs
• crates/edict-syntax/tests/target_ir.rs

docs/topics/**/test-plan.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/topics/**/test-plan.md: Update a topic shelf test-plan.md before or alongside tests with requirement IDs, case IDs, fixtures, oracles, implemented evidence, planned cases, and known gaps.
Mark planned cases as implemented only when executable evidence exists.
Do not use policy rows in topic-shelf test plans to avoid writing behavior tests for software behavior.
Negative tests in topic-shelf test plans should assert stable error kinds or structured artifacts, not merely is_err() or diagnostic text.
For nontrivial behavior, contract, workflow, release, schema, validation, or public-surface changes, update the owning topic test-plan.md with planned requirement and case rows before or alongside the first test.
Mark planned rows as implemented only after executable evidence exists.

Files:

• docs/topics/target-ir/test-plan.md
• docs/topics/contract-bundles/test-plan.md

docs/topics/**/README.md

📄 CodeRabbit inference engine (AGENTS.md)

docs/topics/**/README.md: Topic shelf README.md files must describe only what is true in HEAD.
Update the topic shelf README.md only after the behavior exists in the branch; do not describe intended future behavior there.
Do not churn topic-shelf README files for purely mechanical edits that do not change a contract.

Files:

• docs/topics/contract-bundles/README.md
• docs/topics/target-ir/README.md

🔇 Additional comments (10)

CHANGELOG.md (1)

38-47: LGTM!

docs/design/canonical-target-ir-v0.11.md (1)

1-103: LGTM!

docs/design/contract-bundle-assembly-v0.11.md (1)

15-16: LGTM!

Also applies to: 29-39, 88-109, 125-125, 142-146, 156-157

docs/topics/contract-bundles/README.md (1)

9-11: LGTM!

Also applies to: 22-25, 68-77, 104-105

crates/edict-syntax/src/canonical.rs (1)

1-6: LGTM!

Also applies to: 19-19, 30-32, 183-219, 451-540

crates/edict-syntax/src/lib.rs (1)

34-37: LGTM!

Also applies to: 96-112

xtask/src/main.rs (1)

12-17: LGTM!

Also applies to: 56-72, 98-98, 248-434, 1107-1140

fixtures/target-ir/canonical/echo-effectful.target-ir.sha256 (1)

1-1: LGTM!

fixtures/target-ir/canonical/gitwarp-append.target-ir.sha256 (1)

1-1: LGTM!

crates/edict-syntax/tests/target_ir.rs (1)

7-18: LGTM!

Also applies to: 81-86, 902-1122

[flyingrobots]

Code Lawyer Activity Summary

#	Priority	Source	File	Issue	Commit	Outcome
1	P2	PR	crates/edict-syntax/src/contract_bundle.rs	Computed Target IR bundle assembly validated the embedded target-profile reference only after hashing, losing the stable assembly error field for invalid profile digests.	099a5cf	Added focused regression coverage, validated target_ir_artifact.target_profile before Target IR hashing, updated contract-bundle evidence and changelog, resolved review thread.
2	P3	PR	docs/topics/target-ir/test-plan.md, crates/edict-syntax/tests/target_ir.rs	CodeRabbit reported TIR-TP-018/TIR-TP-019 as implemented without step-order and obstruction-arm mutation evidence.	d613833	Verified the named tests exist and pass on current head; contract-check accepts the evidence rows; resolved stale review thread.

Self-audit: git diff origin/main...HEAD found no additional actionable issues in this pass.

Verification:

• RED: cargo test -p edict-syntax assembly_from_target_ir_rejects_invalid_target_profile_digest_with_stable_field failed with CanonicalDigest instead of InvalidDigest.
• GREEN: cargo test -p edict-syntax assembly_from_target_ir_rejects_invalid_target_profile_digest_with_stable_field
• GREEN: cargo test -p edict-syntax contract_bundle_assembly
• GREEN: cargo test -p edict-syntax --test target_ir target_ir_step_order_changes_digest
• GREEN: cargo test -p edict-syntax --test target_ir target_ir_obstruction_arm_value_mutation_moves_digest
• GREEN: cargo xtask contract-check
• GREEN: cargo xtask verify