feat(echo-wesley-gen): generate canonical Edict provider artifacts

[flyingrobots]

Summary

• Admit the exact Edict provider contract pack and turn exact Echo semantic-source, contract-pack, and generation-settings bytes into one canonical Wesley extension-generation input.
• Generate, validate, provenance-bind, review, and check a deterministic first Echo Edict-provider artifact corpus without filesystem, registry, environment, or network discovery inside the generation APIs.
• Keep authored provider semantics separate from Echo runtime authority: generated authority-facts documents attest semantic declarations, while Echo must still explicitly admit and install runtime artifacts and operations.

Scope

• Tests only
• Docs only
• Runtime code

Links

• Closes Generate Echo Edict lawpack, target profile, authority facts, and provenance #652
• Refs Goalpost: Echo Edict Provider Walking Skeleton #650
• Wesley generation-contract API: Publish extension generation provenance contract wesley#731
• Wesley published prerelease: https://github.com/flyingrobots/wesley/releases/tag/v0.3.0-alpha.1
• Edict contract-pack publication: Publish canonical provider contract pack edict#162

Plain-English architecture walkthrough

1. Echo vendors and authenticates the exact Apache-2.0 Edict provider contract-pack publication. Admission pins its CDDL, manifest, inventories, resources, raw/domain-framed digests, and provenance before parsing or use.
2. The provider-generation boundary accepts only explicit bytes: Echo semantic source, admitted Edict CDDL and manifest, and versioned generation settings. It performs no hidden filesystem, registry, environment, or network discovery.
3. Semantic validation resolves capabilities, obstructions, profiles, implementations, schema roles, and authority families into one order-independent model. Exact authored bytes remain separately bound as evidence, so a formatting-only source change moves generation provenance without being misrepresented as normalized source bytes.
4. The first closure is deliberately GraphQL-free. Its Wesley L1 Shape is exactly empty and has no Law IR. If a semantic source declares GraphQL authority while shape source is none, generation fails closed instead of silently omitting authority bytes.
5. Echo deterministically emits six primary artifacts: two source-partitioned authority-facts documents, a registration generated-artifact profile, lawpack, self-contained provider CDDL, and target profile. Mutating declarations may route toward DPO lowering; revelation/read declarations remain bounded observer/optic contracts.
6. Every authoritative output is encoded under the Edict canonical-byte contract and validated against its owning admitted CDDL root. Successful decoding alone is not treated as admission.
7. Stable structured failures cover conflicting declarations, unknown capabilities and obstructions, profile/fact disagreement, malformed/tampered contract material, canonicalization errors, and corpus drift.
8. Wesley generation provenance binds exact source, settings, generator material, contract versions, and primary-output digests. A deterministic non-authoritative review projection binds that provenance without becoming another authority surface.
9. The checked 22-file corpus includes primary artifacts, declared resources, provenance, and review. Generation is byte-identical across runs; --check reports missing, changed, extra, symlinked, or non-regular entries without rewriting them.

This remains generic provider infrastructure. It adds no Jim-specific checkpoint, rope, causal-anchor, editor, or handwritten adapter semantics.

Wesley dependency rationale

crates.io wesley-core 0.2.0 predates Wesley's public extension-generation contract, so development temporarily used exact commit f66b81cb01918777d5856aa8236b4e46fdf7505d from Wesley PR #731.

Wesley subsequently published that implementation through signed tag v0.3.0-alpha.1 and its protected release workflow. The tagged and crates.io-packaged extension-generation source is byte-identical to the source tested at f66b81cb. Echo now pins:

wesley-core = "=0.3.0-alpha.1"

The exact requirement prevents an implicit move to another prerelease or stable version. Cargo.lock records the crates.io source and checksum 77ca44ae03bac1966eaa6d7660621160f10d3e6979bac26f5929a25a3829c1f4. Because the manifest and lockfile participate in generator-source identity, the dependency transition intentionally moves only generator/provenance/review digests; all six primary semantic artifact digests and declared resource bytes remain unchanged.

Wesley 0.3.0-alpha.1 does not declare an MSRV, so compatibility is established here by the successful Echo Rust 1.90 build/test evidence rather than by an upstream MSRV claim.

RED evidence

The campaign was built in focused executable slices:

cargo +1.90.0 test -p echo-wesley-gen --test provider_contract_pack

Initially failed because the provider_contract_pack module and admission boundary did not exist.

cargo +1.90.0 test -p echo-wesley-gen --test provider_generation_input

The retained second-slice RED failed because ProviderGenerationErrorKind::GraphqlSourceMissing and ProviderGenerationError::semantic_source_kind() did not exist. GREEN added typed semantic-source error preservation and explicit fail-closed GraphQL-authority handling.

Subsequent artifact, provenance, review, and corpus suites were introduced as the executable witnesses for their corresponding absent behavior:

cargo +1.90.0 test -p echo-wesley-gen --test provider_canonical_contract
cargo +1.90.0 test -p echo-wesley-gen --test provider_primary_artifacts
cargo +1.90.0 test -p echo-wesley-gen --test provider_generation_provenance
cargo +1.90.0 test -p echo-wesley-gen --test provider_generation_review
cargo +1.90.0 test -p echo-wesley-gen --test provider_artifact_corpus

Review-driven RED assertions also demonstrated that public diagnostics previously exposed Rust Debug spellings; GREEN replaced those with exhaustive stable kebab-case labels.

GREEN and final verification

Focused compatibility/admission witnesses:

cargo +1.90.0 test --locked -p echo-wesley-gen \
  --test provider_generation_input \
  --test provider_semantic_source \
  --test provider_contract_pack \
  --test runtime_optic_import

All-target and strict lint gates:

cargo +1.90.0 test --locked -p echo-wesley-gen --all-targets
cargo +1.90.0 clippy --locked -p echo-wesley-gen --all-targets \
  -- -D warnings -D missing-docs
cargo +1.90.0 run --locked -p echo-wesley-gen \
  --bin echo-edict-provider-artifacts -- --check
git diff --check

Full branch gate under Echo's supported Node line:

mise exec node@24.12.0 -- pnpm install --frozen-lockfile
mise exec node@24.12.0 -- cargo +1.90.0 xtask pr-preflight --full

The full preflight passed all seven checks: full local verification, documentation dead references, Markdown lint, runtime-schema validation, both no-default-feature contracts, and shell syntax.

The pre-push hook also reran the exact affected Rust slices and Markdown formatting successfully.

Compatibility notes

• echo-wesley-gen follows Wesley's operation-neutral public names. Source consumers of import_runtime_optic_artifact and import_registration_descriptor must update from Wesley's former OpticArtifact / OpticRegistrationDescriptor argument types to OperationArtifact / OperationRegistrationDescriptor.
• Echo's runtime-local optic artifact types, handles, and observer semantics are unchanged.
• The first provider generation closure rejects GraphQL authority without explicit Shape bytes. A later slice may accept and lower explicit GraphQL SDL.
• Generated authority-facts documents describe or attest provider semantics; they do not grant Echo runtime authority.
• Reads remain bounded observers/optics rather than being forced into mutation DPOs.
• No provider artifact is installed or executed by this PR. Runtime admission, installation, scheduling, execution, receipts, WAL/recovery, and observations remain Echo-owned later boundaries.

Documentation impact

Updated:

• CHANGELOG.md
• crates/echo-wesley-gen/README.md
• schemas/edict-provider/README.md
• schemas/edict-provider/contracts/v1/README.md
• schemas/edict-provider/generated/README.md
• docs/architecture/application-contract-hosting.md

These document exact-input generation, canonical/output validation, checked-corpus operation, dependency compatibility, and the separation between provider semantic evidence and runtime authority.

Checklist

• CI green (fmt, clippy, tests, rustdoc, audit/deny)
• Kept PR small and focused (one thing)
• Local full preflight green
• Independent Code Lawyer review clean: no P0-P2 findings
• Normal, non-draft PR

Summary by CodeRabbit

• New Features

  • Added deterministic generation of Edict provider artifacts, provenance, and review outputs.
  • Added strict validation for canonical data encoding, schemas, digests, and contract packages.
  • Added commands to rebuild artifact corpora or check for drift without modifying files.
  • Added filesystem-safe, atomic artifact updates.

• Bug Fixes

  • Improved validation failures with stable, readable diagnostic labels.
  • Prevented mismatched, tampered, or non-canonical inputs from being accepted.

• Documentation

  • Expanded guidance on provider contracts, trusted inputs, generated outputs, provenance, and verification.

[coderabbitai]

Warning

Review limit reached

@flyingrobots, you've reached your PR review limit, so we couldn't start this review.

Next review available in: 10 minutes

Enable usage-based reviews in Billing to review now. Otherwise, wait until the next included review is available.
You're only billed for reviews past your plan's rate limits ($0.25/file).

How can I continue?

After more reviews become available, a review can be triggered using the @coderabbitai review command as a PR comment. Alternatively, push new commits to this PR.

To avoid repeated limits, reduce automatic review volume by pausing incremental auto-reviews earlier, using label-based review opt-in, excluding WIP or generated PR titles, or requesting reviews manually when the PR is ready. If your team needs uninterrupted high-volume reviews, an organization admin can enable usage-based reviews.

How do review limits work?

CodeRabbit enforces per-developer PR review limits for each organization. Most developers receive the normal plan review availability.

For paid Pro and Pro+ PR reviews, CodeRabbit uses adaptive limits for sustained high-volume activity. When a developer's recent PR review activity reaches the 95th percentile or higher among CodeRabbit users, additional reviews become available more gradually as earlier reviews age out of the rolling window.

Please refer docs for additional details.

Review details

⚙️ Run configuration

Configuration used: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: 68db8832-1afd-4dd0-8944-ce29e9bb8772

📥 Commits

Reviewing files that changed from the base of the PR and between c6d50e5 and 68db9f5.

⛔ Files ignored due to path filters (3)

• Cargo.lock is excluded by !**/*.lock
• schemas/edict-provider/generated/v1/evidence/provenance.provider-generation.json is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/evidence/review.provider-generation.json is excluded by !**/generated/**

📒 Files selected for processing (10)

• CHANGELOG.md
• crates/echo-wesley-gen/Cargo.toml
• crates/echo-wesley-gen/README.md
• crates/echo-wesley-gen/src/bin/echo-edict-provider-artifacts.rs
• crates/echo-wesley-gen/src/main.rs
• crates/echo-wesley-gen/src/provider_canonical.rs
• crates/echo-wesley-gen/src/provider_provenance.rs
• crates/echo-wesley-gen/tests/provider_artifact_corpus.rs
• crates/echo-wesley-gen/tests/provider_generation_provenance.rs
• docs/architecture/application-contract-hosting.md

📝 Walkthrough

Walkthrough

Adds a deterministic Edict provider pipeline covering pinned contract admission, canonical CBOR validation, Wesley generation input, primary artifacts, provenance, review, corpus rendering, drift checking, filesystem-safe emission, tests, and documentation.

Changes

Edict provider generation

Layer / File(s)	Summary
Canonical contract admission boundary crates/echo-wesley-gen/src/provider_canonical.rs, crates/echo-wesley-gen/src/provider_contract_pack.rs, schemas/edict-provider/contracts/v1/*, tests/provider_*contract*	Adds canonical CBOR encoding/digesting, pinned Edict contract-pack admission, CDDL roots, manifest inventories, provenance checks, and typed validation failures.
Canonical generation input and primary outputs crates/echo-wesley-gen/src/provider_generation.rs, crates/echo-wesley-gen/src/provider_artifacts.rs, src/provider_semantics.rs, tests/provider_generation_input.rs, tests/provider_primary_artifacts.rs	Builds validated Wesley generation inputs and projects semantic sources into digest-closed provider artifacts, resources, authority facts, and self-contained schemas.
Provenance-bound review derivation src/provider_provenance.rs, src/provider_review.rs, tests/provider_generation_provenance.rs, tests/provider_generation_review.rs	Binds exact source, settings, generator, and output materials into verified provenance, then derives canonical non-authoritative review data.
Deterministic corpus rendering and filesystem emission src/provider_corpus.rs, src/bin/echo-edict-provider-artifacts.rs, tests/provider_artifact_corpus.rs	Creates a fixed generator source bundle, renders the expected corpus, compares drift, supports check mode, and performs symlink-safe atomic file replacement.
Public wiring and repository integration src/lib.rs, Cargo.toml, README.md, docs/architecture/*, schemas/edict-provider/*, .gitattributes, CHANGELOG.md	Exposes provider modules, updates operation-artifact imports, adds generation settings and contract-pack documentation, and records generated-file handling.

Estimated code review effort: 5 (Critical) | ~120 minutes

Possibly related issues

• Publish a canonical provider contract pack for runtime-owned generators edict#161 — Adds the Edict contract pack and admission flow implemented by this change.
• Goalpost: Echo Edict Provider Walking Skeleton #650 — Covers the broader Echo Edict provider generation and artifact pipeline implemented here.

Possibly related PRs

• flyingrobots/echo#344 — Directly relates to the runtime optic import boundary updated from optic artifacts to operation artifacts.

Suggested labels: tooling

🚥 Pre-merge checks | ✅ 5

✅ Passed checks (5 passed)

Check name	Status	Explanation
Description Check	✅ Passed	Check skipped - CodeRabbit’s high-level summary is enabled.
Title check	✅ Passed	The title names the main change: generating canonical Edict provider artifacts in echo-wesley-gen.
Linked Issues check	✅ Passed	The PR implements #652's generator, provenance, review, check mode, and corpus tests with the required outputs.
Out of Scope Changes check	✅ Passed	The doc, test, packaging, and .gitattributes changes all support the provider-artifact generator and its corpus.
Docstring Coverage	✅ Passed	Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch provider/652-generated-artifacts

---

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.}

[chatgpt-codex-connector]

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: f34f570fea

ℹ️ 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".

[coderabbitai]

Actionable comments posted: 5

🤖 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/echo-wesley-gen/src/bin/echo-edict-provider-artifacts.rs`:
- Around line 205-220: Eliminate path-based TOCTOU races in write_corpus,
preflight_corpus_write, ensure_corpus_directory, and replace_corpus_file by
using directory-handle-relative operations that refuse symlinks. Retain
validated parent directory handles through directory creation, temporary-file
creation, and final replacement, rather than re-resolving paths between checks
and writes. Ensure every opened or renamed entry remains confined to the
canonical corpus root.
- Around line 205-221: Update write_corpus and its preflight flow to inspect the
existing corpus inventory before writing, reject any unexpected files or
directories, and return an error before reporting success; preserve the current
expected-file generation behavior and use the existing corpus validation helpers
where applicable.
- Around line 371-397: Update replace_temporary_file to replace the existing
destination atomically, preserving the old corpus file if replacement fails
instead of calling remove_file before rename. Retain destination validation and
contextual errors, and add a regression test covering a forced replacement
failure when the destination already exists.

In `@crates/echo-wesley-gen/src/provider_canonical.rs`:
- Around line 438-451: Update the length method to compare the declared CBOR
length against self.remaining() before converting it to usize, ensuring
oversized declarations consistently return UnexpectedEof on all platforms. Only
convert the value after that bounds check, preserving the existing
UnsupportedCbor error for values that fit the remaining-byte constraint but
cannot be represented as usize.

In `@crates/echo-wesley-gen/src/provider_provenance.rs`:
- Around line 329-363: Update validate_generator_coordinate to include
input.source_artifacts() when collecting conflicting roles, alongside
generated_artifacts and artifact_resources, so matching source-artifact
coordinates return GeneratorCoordinateConflict. Add a regression case covering
all three source-artifact coordinates and preserve the existing conflict-role
reporting behavior.

🪄 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: Path: .coderabbit.yaml

Review profile: ASSERTIVE

Plan: Pro

Run ID: d5b13c58-d59a-4c81-a2d3-163df3f03578

📥 Commits

Reviewing files that changed from the base of the PR and between 24cf997 and c6d50e5.

⛔ Files ignored due to path filters (24)

• Cargo.lock is excluded by !**/*.lock
• schemas/edict-provider/generated/README.md is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/evidence/provenance.provider-generation.json is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/evidence/review.provider-generation.json is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/primary/authority-facts.echo-dpo.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/primary/authority-facts.echo-lawpack.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/primary/generated-artifact-profile.echo-dpo-registration.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/primary/lawpack.echo-dpo.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/primary/schema.echo-provider-artifacts.cddl is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/primary/target-profile.echo-dpo.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.conformance-corpus.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.lawpack-compatibility.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.lawpack-exports.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.lawpack-target-adapter.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.lawpack-verifier.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.target-bundle-profile.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.target-cost-algebra.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.target-footprint-algebra.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.target-intrinsics.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.target-ir.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.target-lowerer-contract.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.target-obstruction-taxonomy.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.target-operation-profiles.cbor is excluded by !**/generated/**
• schemas/edict-provider/generated/v1/resources/resource.target-verifier-contract.cbor is excluded by !**/generated/**

📒 Files selected for processing (30)

• .gitattributes
• CHANGELOG.md
• crates/echo-wesley-gen/Cargo.toml
• crates/echo-wesley-gen/README.md
• crates/echo-wesley-gen/src/bin/echo-edict-provider-artifacts.rs
• crates/echo-wesley-gen/src/lib.rs
• crates/echo-wesley-gen/src/provider_artifacts.rs
• crates/echo-wesley-gen/src/provider_canonical.rs
• crates/echo-wesley-gen/src/provider_contract_pack.rs
• crates/echo-wesley-gen/src/provider_corpus.rs
• crates/echo-wesley-gen/src/provider_generation.rs
• crates/echo-wesley-gen/src/provider_provenance.rs
• crates/echo-wesley-gen/src/provider_review.rs
• crates/echo-wesley-gen/src/provider_semantics.rs
• crates/echo-wesley-gen/tests/provider_artifact_corpus.rs
• crates/echo-wesley-gen/tests/provider_canonical_contract.rs
• crates/echo-wesley-gen/tests/provider_contract_pack.rs
• crates/echo-wesley-gen/tests/provider_generation_input.rs
• crates/echo-wesley-gen/tests/provider_generation_provenance.rs
• crates/echo-wesley-gen/tests/provider_generation_review.rs
• crates/echo-wesley-gen/tests/provider_primary_artifacts.rs
• crates/echo-wesley-gen/tests/provider_semantic_source.rs
• crates/echo-wesley-gen/tests/runtime_optic_import.rs
• docs/architecture/application-contract-hosting.md
• schemas/edict-provider/README.md
• schemas/edict-provider/contracts/v1/README.md
• schemas/edict-provider/contracts/v1/edict-provider-contracts.cddl
• schemas/edict-provider/contracts/v1/manifest.json
• schemas/edict-provider/echo-provider-semantics-v1.json
• schemas/edict-provider/generation-settings-v1.json