Skip to content

Publish extension generation provenance contract - #731

Merged
flyingrobots merged 15 commits into
mainfrom
provider/728-generation-provenance
Jul 14, 2026
Merged

Publish extension generation provenance contract#731
flyingrobots merged 15 commits into
mainfrom
provider/728-generation-provenance

Conversation

@flyingrobots

@flyingrobots flyingrobots commented Jul 14, 2026

Copy link
Copy Markdown
Owner

Plain-English Walkthrough

TL;DR

[claim:canonical-generation-input, confidence:1.00] Wesley now exposes a
versioned Rust input that combines canonical Shape IR, normalized root
operations, optional bound Law IR, explicit owner-declaration references, a
settings digest, and requested projection roles. Canonical bytes exclude ambient
Shape metadata and normalize set-like values, so equivalent explicit inputs
produce the same identity
(crates/wesley-core/src/domain/extension_generation.rs#115@a0d4b871;
canonical_generation_input_ignores_ambient_metadata_and_set_order in
crates/wesley-core/tests/extension_generation.rs#76@a0d4b871).

[claim:provenance-recomputes-material, confidence:1.00] A generation provenance
manifest binds the input, generator, source declarations, settings, contract
versions, and emitted artifacts. Verification recomputes the generator and every
supplied source/output digest before returning a receipt
(crates/wesley-core/src/domain/extension_generation.rs#295@a0d4b871;
provenance_recomputes_generator_source_and_output_digests in
crates/wesley-core/tests/extension_generation.rs#306@a0d4b871).

[claim:review-remains-non-authoritative, confidence:1.00] The review projection
is deterministic and structurally non-authoritative: the authority field is
private, deserialization rejects true with the stable authority-rejection
code, construction writes false, and the JSON Schema requires false
(crates/wesley-core/src/domain/extension_generation.rs#452@a0d4b871;
generation_review_deserialization_rejects_authority_claims in
crates/wesley-core/tests/extension_generation.rs#419@a0d4b871).

Walkthrough

Before this change, an external semantic generator had no single Wesley-owned
Rust contract for canonical compiler facts and generation provenance. A consumer
either had to scrape CLI JSON, duplicate canonicalization, or adopt the unrelated
descriptor-only target protocol. This PR adds the missing in-memory boundary
without moving Echo, Edict, or any other target's semantics into Wesley.

The flow deliberately separates neutral compiler facts, owner-supplied meaning,
and post-generation evidence:

flowchart LR
    A[Canonical Shape and operation facts] --> B[ExtensionGenerationInputV1]
    C[Optional bound Law IR] --> B
    D[Owner declarations and settings digest] --> B
    B --> E[External owner generator]
    E --> F[Emitted artifact bytes]
    B --> G[GenerationProvenanceManifestV1]
    H[Exact generator and source bytes] --> G
    F --> G
    G --> I[Digest verification receipt]
    G --> J[Non-authoritative review JSON]
Loading
Caption: Generation ownership and evidence flow
  1. Wesley supplies only canonical, domain-neutral compiler facts.
  2. The external owner supplies semantic declarations, settings, generator code,
    and emitted artifact schemas.
  3. Provenance binds exact identities and bytes after generation.
  4. Verification admits a receipt only after recomputing every referenced digest;
    the review JSON remains derived evidence rather than authority.

The diagram's key boundary is between ExtensionGenerationInputV1 and the
external generator. Wesley defines what bytes and identities cross that boundary,
but it does not execute the generator or interpret target-specific output.

Canonical input and failures

[claim:no-ambient-discovery, confidence:0.99] Construction operates only on
explicit in-memory values: it strips WesleyIR.metadata, validates and sorts
operations, normalizes active Law IR, sorts owner references and projection
roles, and performs no filesystem, registry, network, clock, process, or
environment lookup
(crates/wesley-core/src/domain/extension_generation.rs#140@a0d4b871;
docs/reference/extension-generation.md#84@a0d4b871).

Conflicting digests for one coordinate, malformed digests, unsupported versions,
Law binding failures, missing or unexpected verification material, digest
mismatches, and attempted authoritative review output use structured stable error
kinds. Target meaning and target artifact validation stay with the external
owner.

[claim:stable-token-diagnostics, confidence:1.00] Malformed generic tokens such
as projection roles and Law tags use InvalidToken /
WESLEY_GENERATION_INVALID_TOKEN, while artifact, generator-version, and
operation coordinates retain InvalidCoordinate
(crates/wesley-core/src/domain/extension_generation.rs#579@a0d4b871;
generation_input_classifies_invalid_projection_roles_as_tokens in
crates/wesley-core/tests/extension_generation.rs#238@a0d4b871).

[claim:operation-coordinate-validation, confidence:1.00] Publicly constructed
operation catalogs cannot emit schema-invalid empty, padded, or control-bearing
root, field, or argument names. Validation occurs before sorting and
canonicalization and returns the stable InvalidCoordinate kind
(crates/wesley-core/src/domain/extension_generation.rs#693@a0d4b871;
generation_input_rejects_malformed_operation_coordinates in
crates/wesley-core/tests/extension_generation.rs#208@a0d4b871).

Published schemas

[claim:nested-schema-enforcement, confidence:1.00] The input JSON Schema validates
nested Shape IR and operation structures and composes the existing canonical Law
IR schema. Negative witnesses reject empty operations, empty Shape types, and
incomplete Law IR
(schemas/wesley-extension-generation-input-v1.schema.json#1@a0d4b871;
published_input_schema_rejects_malformed_nested_contracts in
crates/wesley-core/tests/extension_generation.rs#535@a0d4b871).

[claim:documented-shape-arguments, confidence:1.00] Shape field arguments use
their own schema definition, so optional descriptions emitted by the Rust Shape
IR are accepted without incorrectly adding descriptions to root operation
arguments
(schemas/wesley-extension-generation-input-v1.schema.json#1@a0d4b871;
published_input_schema_accepts_documented_shape_arguments in
crates/wesley-core/tests/extension_generation.rs#608@a0d4b871).

[claim:generation-token-schema, confidence:1.00] The input, provenance, and review
schemas now reject leading/trailing whitespace and C0/C1 control characters on
every token surface already validated by the Rust generation contract
(schemas/wesley-generation-provenance-manifest-v1.schema.json#1@a0d4b871;
published_generation_schemas_reject_malformed_tokens in
crates/wesley-core/tests/extension_generation.rs#570@a0d4b871).

CI admission

[claim:generation-fixture-ci, confidence:1.00] A change limited to checked
extension-generation fixtures now triggers the Rust product preflight for both
pull requests and main-branch pushes, so fixture drift cannot skip the Rust
projection and schema witnesses
(.github/workflows/rust-native.yml#22@a0d4b871;
rust native preflight provisions pnpm and watches audit inputs in
test/ci-workflows.bats#34@a0d4b871).

Pre-push containment incident

[claim:prepush-index-isolation, confidence:1.00] Review exposed that Git's
pre-push hook context leaked into nested repository tests, allowing a fixture
git add to replace the caller's index. The runner now removes every
repository-local Git variable, including indexed
GIT_CONFIG_KEY_*/GIT_CONFIG_VALUE_* entries, before spawning child checks
(scripts/pre-push-sanity.mjs#285@a0d4b871;
pre-push sanity removes hook-local Git context from child checks in
scripts/pre-push-sanity.test.mjs#111@a0d4b871).

The damaged original worktree was left untouched. A fresh worktree was used for
review, and an end-to-end leaked-environment run completed the Rust product
preflight and repo Bats suite while preserving the exact index tree hash before
and after execution.

Contract Surface

  • ExtensionGenerationInputV1 and its canonical bytes/digest.
  • GenerationArtifactReferenceV1 and explicit artifact content.
  • GeneratorIdentityV1 and frozen schema/ABI identities.
  • GenerationProvenanceManifestV1 verification.
  • GenerationReviewV1 as derived, non-authoritative JSON.
  • Three checked JSON Schemas plus canonical fixtures and external-crate tests.

RED / GREEN

Initial contract RED:

  • cargo test -p wesley-core --test extension_generation failed because the
    public generation/provenance API did not exist.

Code Lawyer RED:

  • node --test scripts/pre-push-sanity.test.mjs failed because the runner did
    not expose or implement repository-context sanitization.
  • cargo test -p wesley-core --test extension_generation published_input_schema_rejects_malformed_nested_contracts -- --exact
    failed because the input schema accepted an empty operation.
  • cargo test -p wesley-core --test extension_generation published_input_schema_accepts_documented_shape_arguments -- --exact
    failed because a valid Shape argument description was rejected.
  • The focused ci-workflows.bats case failed because the generation-fixture
    trigger occurred zero times instead of twice.
  • cargo test -p wesley-core --test extension_generation generation_input_rejects_malformed_operation_coordinates -- --exact
    failed because an empty root coordinate was accepted.
  • cargo test -p wesley-core --test extension_generation published_generation_schemas_reject_malformed_tokens -- --exact
    failed because a padded source coordinate passed the input schema.
  • cargo test -p wesley-core --test extension_generation generation_input_classifies_invalid_projection_roles_as_tokens -- --exact
    failed because the stable InvalidToken category did not exist.
  • cargo test -p wesley-core --test extension_generation generation_review_deserialization_rejects_authority_claims -- --exact
    failed because authoritative: true deserialized successfully.

Final GREEN:

  • pnpm run preflight passed workspace fmt, Clippy with warnings denied,
    dependency audit, docs checks, every Rust test, doc tests, and CLI smoke on
    head a0d4b871.
  • The leaked-GIT_* pre-push simulation passed the complete repo Bats suite and
    preserved index tree ab7e3f92f77450bfbbe8aab42468d00c19a2be9c before and
    after execution.
  • cargo test -p wesley-core --test extension_generation passed 12 tests.
  • cargo test -p wesley-core --test generated_json_artifacts passed 6 tests.
  • bats -t test/ci-workflows.bats passed all 29 workflow cases.
  • cargo xtask legacy-preflight passed 13 Node harness tests, docs truth,
    package-manager policy, and dependency-cruiser boundaries after a frozen
    lockfile install restored the fresh worktree toolchain.

Compatibility, Dependencies, and Docs

[claim:additive-public-surface, confidence:0.99] The Rust API is additive and
re-exported from wesley-core; no existing public export was removed or
signature-changed
(crates/wesley-core/src/lib.rs#27@a0d4b871). No third-party dependency was
added. The reference guide, extension topic, crate README, schema index, fixture
index, and changelog describe the current contract and ownership boundary.

Review Notes

The initial pre-push defect created fixture-authored commits 7fc9fd8f and
f98febb5. History was deliberately preserved: no amend, reset, rebase,
force-push, or branch deletion was used. The final tree contains no stray root
schema.graphql, and the current reviewed commits use the maintainer identity.

Linked Issue

Issue #728 is closed by
the directive after the citations appendix.

Branch / Issue-Title Check

  • Exception documented: provider/728-generation-provenance follows the
    provider-campaign branch convention and includes the linked issue number.

Summary

  • Publishes canonical semantic-generation input, provenance, verification, and
    non-authoritative review contracts for external Rust consumers.
  • Includes the schema, fixture, documentation, CI-admission, and review-found
    harness corrections required to make that boundary enforceable.

Why

The contract keeps Wesley domain-neutral while giving runtime owners a stable,
content-addressed source for generated provider artifacts. Wasmtime execution,
provider packaging, registry resolution, and runtime-specific semantics remain
outside this PR. The pre-push containment changes are included because the
review harness damaged the original worktree while validating this branch; they
are required to make the evidence trustworthy, not a separate product feature.

Changes

  • Added pure Rust generation input, provenance, verification, review, and stable
    failure types.
  • Added strict JSON Schemas, canonical fixtures, and positive/negative evidence.
  • Added generation-fixture CI triggers and isolated child checks from hook-owned
    Git repository state.
  • Addressed every actionable Codex and CodeRabbit correctness finding.

Method Evidence

  • Design scope is the linked issue and durable extension-generation guide.
  • RED/GREEN commands and final validation are recorded above.
  • The leaked-context witness and consolidated Code Lawyer activity summary
    are posted on this PR.
  • Closeout evidence is captured in the citations appendix and activity
    summary.

Tracker Hygiene

  • The issue did not carry work-in-progress; this audit began after the
    feature branch already existed, so the history is reported rather than
    rewritten retroactively.
  • Current issue labels are consistent with a Wesley core feature/enabler.
  • No accepted follow-up is hidden in chat or a local backlog. The suggested
    normalization optimization was not accepted without benchmark evidence because
    it would add a private path that assumes prior validation.

Risk

The primary risk is accepting an artifact whose Rust and JSON Schema
interpretations differ. Exact nested schemas, canonical fixture round trips,
stable negative diagnostics, digest recomputation, and full local/remote gates
mitigate that risk. The change does not execute external code and adds no
dependency.

Backout

Revert the merge commit. Consumers must then stop producing or accepting the
three wesley.*generation*/v1 artifacts until a replacement contract lands.
No registry migration, publication, or persisted runtime state is introduced by
this PR.

Testing

  • pnpm run preflight
  • cargo xtask legacy-preflight
  • cargo test -p wesley-core --test extension_generation
  • cargo test -p wesley-core --test generated_json_artifacts
  • bats -t test/ci-workflows.bats
  • Leaked-GIT_* pre-push simulation with identical before/after index tree

EvidenceMap / SourceMap

Not applicable. This contract does not map SQL or emit an EvidenceMap/SourceMap.

Screenshots / Logs

Not applicable. This PR has no visual surface; command evidence is recorded
above and in the activity summary.

Merge Strategy

  • Merge commit only; no squash or rebase.
  • Preserve branches and the damaged original worktree per the explicit audit
    constraints; no branch deletion is part of this merge.

Checklist

  • Issue scope plus required audit-containment corrections are documented.
  • Rust-native preflight passes.
  • Legacy preflight passes for the JavaScript harness and docs changes.
  • No workflow permission or secret scope was widened.
  • Documentation and changelog match the implemented behavior.
Appendix: Citations
Claim Evidence Confidence Notes
claim:canonical-generation-input crates/wesley-core/src/domain/extension_generation.rs#115@a0d4b871; crates/wesley-core/tests/extension_generation.rs#76@a0d4b871 1.00 Source and deterministic equality witness agree.
claim:provenance-recomputes-material crates/wesley-core/src/domain/extension_generation.rs#352@a0d4b871; crates/wesley-core/tests/extension_generation.rs#306@a0d4b871 1.00 Positive and tamper/missing-material witnesses pass.
claim:review-remains-non-authoritative crates/wesley-core/src/domain/extension_generation.rs#452@a0d4b871; crates/wesley-core/tests/extension_generation.rs#419@a0d4b871 1.00 Privacy, deserialization, construction, and schema enforce the claim.
claim:no-ambient-discovery crates/wesley-core/src/domain/extension_generation.rs#140@a0d4b871; docs/reference/extension-generation.md#84@a0d4b871 0.99 Direct source inspection plus metadata-independence evidence.
claim:stable-token-diagnostics crates/wesley-core/src/domain/extension_generation.rs#579@a0d4b871; crates/wesley-core/tests/extension_generation.rs#238@a0d4b871 1.00 Generic tokens and coordinates retain distinct stable kinds.
claim:operation-coordinate-validation crates/wesley-core/src/domain/extension_generation.rs#693@a0d4b871; crates/wesley-core/tests/extension_generation.rs#208@a0d4b871 1.00 Three stable negative paths pass.
claim:nested-schema-enforcement schemas/wesley-extension-generation-input-v1.schema.json#1@a0d4b871; crates/wesley-core/tests/extension_generation.rs#535@a0d4b871 1.00 Negative nested-object witnesses pass.
claim:documented-shape-arguments schemas/wesley-extension-generation-input-v1.schema.json#1@a0d4b871; crates/wesley-core/tests/extension_generation.rs#608@a0d4b871 1.00 Rust-emitted documented argument validates.
claim:generation-token-schema schemas/wesley-generation-provenance-manifest-v1.schema.json#1@a0d4b871; crates/wesley-core/tests/extension_generation.rs#570@a0d4b871 1.00 Input, provenance, and review mutations are rejected.
claim:generation-fixture-ci .github/workflows/rust-native.yml#22@a0d4b871; test/ci-workflows.bats#34@a0d4b871 1.00 Both trigger entries and the full workflow suite pass.
claim:prepush-index-isolation scripts/pre-push-sanity.mjs#285@a0d4b871; scripts/pre-push-sanity.test.mjs#111@a0d4b871 1.00 Unit and end-to-end witnesses agree.
claim:additive-public-surface crates/wesley-core/src/lib.rs#27@a0d4b871; git diff origin/main...a0d4b871 0.99 Public surface inspection found no removal.

Closes #728

@coderabbitai

coderabbitai Bot commented Jul 14, 2026

Copy link
Copy Markdown

Review Change Stack

📝 Walkthrough

Walkthrough

Adds a pure wesley-core extension-generation contract with canonical inputs, provenance verification, deterministic review projections, published schemas, fixtures, and documentation. It also isolates Git child checks from ambient repository variables and updates Bats tests to use vendored plugins.

Changes

Extension generation contract

Layer / File(s) Summary
Canonical generation and provenance model
crates/wesley-core/src/domain/extension_generation.rs, crates/wesley-core/src/domain/mod.rs, crates/wesley-core/src/lib.rs
Adds versioned input, artifact, generator, provenance, review, canonicalization, digest, verification, and error APIs.
Contract validation and fixture coverage
crates/wesley-core/tests/extension_generation.rs
Tests deterministic canonicalization, digest sensitivity, collision rejection, provenance verification, review output, schema compatibility, and malformed nested contracts.
Published schemas and checked fixtures
schemas/*, test/fixtures/extension-generation/*
Adds schemas and fixture artifacts for generation inputs, provenance manifests, reviews, source materials, generated output, and shape data.
Contract documentation
crates/wesley-core/README.md, docs/reference/extension-generation.md, docs/topics/*, CHANGELOG.md
Documents the external generator boundary, public API, verification flow, schemas, and non-authoritative review projection.

Git environment isolation

Layer / File(s) Summary
Isolated Git command environment
crates/wesley-cli/tests/cli.rs, scripts/pre-push-sanity.mjs, scripts/pre-push-sanity.test.mjs
Clears hook-owned Git discovery variables before child checks and tests the normalized environment.

Vendored Bats test loading

Layer / File(s) Summary
Vendored Bats helper imports
test/*.bats
Updates Bats support and assertion imports to use vendored plugin paths.
Fixture directory documentation
test/fixtures/README.md
Adds the extension-generation fixture directory to the overview table.

Estimated code review effort: 4 (Complex) | ~60 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Generator
  participant ExtensionGenerationInputV1
  participant ProvenanceManifest
  participant ReviewProjection
  Generator->>ExtensionGenerationInputV1: consume canonical Shape, Law, operation, owner, and settings data
  Generator->>ProvenanceManifest: submit generator, source, and output references
  ProvenanceManifest->>ProvenanceManifest: recompute and verify supplied digests
  ProvenanceManifest->>ReviewProjection: derive deterministic non-authoritative review
Loading

Possibly related PRs

Suggested labels: enhancement, feature

🚥 Pre-merge checks | ✅ 3 | ❌ 2

❌ Failed checks (2 warnings)

Check name Status Explanation Resolution
Out of Scope Changes check ⚠️ Warning The pre-push Git-sanitizing changes and Bats vendored-plugin path updates are unrelated to #728's semantic-generation contract. If they are intentional, add a separate linked issue or explain them in scope; otherwise remove the harness-only changes.
Docstring Coverage ⚠️ Warning Docstring coverage is 33.33% which is insufficient. The required threshold is 80.00%. Write docstrings for the functions missing them to satisfy the coverage threshold.
✅ Passed checks (3 passed)
Check name Status Explanation
Linked Issues check ✅ Passed The PR implements the canonical input, provenance manifest, review projection, schemas, docs, and tests requested by #728.
Title check ✅ Passed The title matches the main change: publishing the extension-generation provenance contract.
Description check ✅ Passed The PR description follows the repository template closely and fills the required sections with substantive details.
✨ Finishing Touches
📝 Generate docstrings
  • Create stacked PR
  • Commit on current branch
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch provider/728-generation-provenance

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

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

@github-actions

github-actions Bot commented Jul 14, 2026

Copy link
Copy Markdown

🔍 The Case of Pull Request #731

Schema Sets

  • ecommerce
  • reference

Schema Set ecommerce

Plain-English Readout

  • Holmes (evidence investigation): The Holmes report is unavailable because the workflow finished without a readable holmes-report.json artifact.
  • Watson (independent verification): The Watson report is unavailable because the workflow finished without a readable watson-report.json artifact.
  • Moriarty (trend forecast): The Moriarty forecast is unavailable because the workflow finished without a readable moriarty-report.json artifact.

Suggested next actions

  1. Regenerate the HOLMES artifacts and make sure holmes-report.json is uploaded before trusting this PR summary.
  2. Regenerate the WATSON artifacts and make sure watson-report.json is uploaded before trusting this PR summary.
  3. Regenerate the MORIARTY artifacts and make sure moriarty-report.json is uploaded before trusting this PR summary.
🕵️ SHA-lock HOLMES full report for ecommerce (click to expand)

Report unavailable for holmes: readable holmes-report.md artifact not found.

🩺 Dr. WATSON full report for ecommerce (click to expand)

Report unavailable for watson: readable watson-report.md artifact not found.

🔮 Professor MORIARTY full report for ecommerce (click to expand)

Report unavailable for moriarty: readable moriarty-report.md artifact not found.


Schema Set reference

Plain-English Readout

  • Holmes (evidence investigation): The Holmes report is unavailable because the workflow finished without a readable holmes-report.json artifact.
  • Watson (independent verification): The Watson report is unavailable because the workflow finished without a readable watson-report.json artifact.
  • Moriarty (trend forecast): The Moriarty forecast is unavailable because the workflow finished without a readable moriarty-report.json artifact.

Suggested next actions

  1. Regenerate the HOLMES artifacts and make sure holmes-report.json is uploaded before trusting this PR summary.
  2. Regenerate the WATSON artifacts and make sure watson-report.json is uploaded before trusting this PR summary.
  3. Regenerate the MORIARTY artifacts and make sure moriarty-report.json is uploaded before trusting this PR summary.
🕵️ SHA-lock HOLMES full report for reference (click to expand)

Report unavailable for holmes: readable holmes-report.md artifact not found.

🩺 Dr. WATSON full report for reference (click to expand)

Report unavailable for watson: readable watson-report.md artifact not found.

🔮 Professor MORIARTY full report for reference (click to expand)

Report unavailable for moriarty: readable moriarty-report.md artifact not found.


📚 Glossary (what the Holmes terms mean)
  • HOLMES: Wesley’s main evidence investigation. It decides whether the cited proof is strong enough to justify shipping this commit.
  • WATSON: An independent verification pass. It checks Holmes’s citations and score math instead of trusting them blindly.
  • MORIARTY: A readiness forecast over time. It is advisory trend analysis, not the release gate itself.
  • Schema coverage score (SCS): How much of the schema has direct supporting evidence across generated artifacts and cited proof.
  • Test confidence index (TCI): How much test evidence exists for constraints, policies, relationships, and operations.
  • Migration risk index (MRI): How risky the schema change is to roll out. Lower is better.
  • Evidence trust: Whether the report is backed by exact citations, whole-file citations, or coarse references. Weak trust means the claim may be directionally right but not specific enough to trust blindly.
  • Citation quality: A count of exact line-span citations versus whole-file or coarse references.
  • ELEMENTARY: Ready to ship based on the current evidence.
  • REQUIRES INVESTIGATION: More work or review is needed before shipping.
  • YOU SHALL NOT PASS: Do not ship this change in its current state.

Machine-readable reports are grouped by schema set in workflow artifacts.


Filed at 221B Repository Street

@flyingrobots

Copy link
Copy Markdown
Owner Author

Code Lawyer self-audit findings

@codex second opinion requested.

# Severity Source Surface Finding Required disposition
1 P0 Critical Self scripts/pre-push-sanity.mjs / repo Bats The pre-push runner forwards hook-owned GIT_* repository context into child checks. test/ci-package-manager-policy.bats then runs git -C "$TMP_REPO" add . against the caller index, leaving the original #728 worktree with 729 staged deletions and only five fixture paths in its index after a nominally successful push. RED witness for leaked hook context; centrally remove repo-local Git variables before spawning every check; verify the sentinel index remains unchanged.
2 P4 Process Self PR body The current body predates the required Plain-English Walkthrough and claim-citation appendix. Rewrite the body against the reviewed final SHA after code closure.

The damaged worktree is preserved untouched at /Users/james/git/_wesley-728-generation-provenance. Review work continues from a clean worktree based on the pushed branch; no reset, restore, amend, rebase, force-push, or branch deletion has been used.

@flyingrobots

Copy link
Copy Markdown
Owner Author

Code Lawyer self-audit finding 2

@codex second opinion requested.

# Severity Source Surface Finding Required disposition
2 P1 High Self schemas/wesley-extension-generation-input-v1.schema.json The published input schema treats each operation as an unconstrained object, each Shape IR type as an unconstrained object, and Law IR as any object carrying only apiVersion. It therefore accepts payloads that cannot deserialize into the public Rust contract, weakening the advertised machine-readable boundary. Add deterministic rejection witnesses and compose the input schema with Wesley's canonical Shape/Law schemas plus an exact operation shape.

@flyingrobots

Copy link
Copy Markdown
Owner Author

@codex review please

@flyingrobots

Copy link
Copy Markdown
Owner Author

Code Lawyer Activity Summary

# Severity Source Surface Commit Outcome
1 P0 Critical Self Pre-push child Git context 595d5787 Removed all repository-local GIT_* variables before child checks. Unit RED/GREEN and a full leaked-context preflight/Bats run preserved the exact caller index tree.
2 P1 High Self Generation input JSON Schema dfdf6380 Composed canonical Law IR validation and defined exact nested Shape/operation structures. Empty operation/type and incomplete Law witnesses now fail.
3 P4 Process Self Changelog fdbf64ad, 38e74092 Recorded both workflow and schema contract corrections.
4 P4 Process Self PR explanation metadata Replaced the original body with the required progressive walkthrough, ownership diagram, claim tags, source/test citations, RED/GREEN evidence, and citation appendix.

No inline review threads existed at audit time. The original damaged worktree remains untouched with 729 staged deletions and five fixture index entries; all review/fix work occurred in a fresh clean worktree. No amend, reset, rebase, force-push, or branch deletion was used.

Final local gate: cargo xtask preflight green; workspace fmt/clippy/tests/doc-tests/CLI smoke green; dependency audit green; repo Bats green; generation contract 7/7; JSON artifact suite 6/6; leaked-hook environment before/after index tree identical.

@chatgpt-codex-connector chatgpt-codex-connector Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

💡 Codex Review

Here are some automated review suggestions for this pull request.

Reviewed commit: 38e74092f2

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

Comment thread schemas/wesley-extension-generation-input-v1.schema.json Outdated
Comment thread test/fixtures/extension-generation/README.md
Comment thread crates/wesley-core/src/domain/extension_generation.rs Outdated
Comment thread schemas/wesley-generation-provenance-manifest-v1.schema.json Outdated

@coderabbitai coderabbitai Bot left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Actionable comments posted: 1

🧹 Nitpick comments (3)
crates/wesley-core/tests/extension_generation.rs (1)

371-444: 📐 Maintainability & Code Quality | 🔵 Trivial | ⚡ Quick win

Consider adding a deserialize→revalidate round trip over the checked fixtures.

checked_generation_fixtures_match_public_api_and_published_schemas only exercises construct-in-Rust → serialize → compare-with-fixture. It never exercises the inverse path (serde_json::from_str::<ExtensionGenerationInputV1> / GenerationProvenanceManifestV1 / GenerationReviewV1 on the checked-in fixture, followed by .canonical_bytes()), which is the exact path external Rust consumers are expected to use per the PR's "external Rust consumption without invoking the CLI" objective. Adding this would catch asymmetries between Serialize/Deserialize and the normalized() revalidation logic that the current test can't detect.

🤖 Prompt for 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.

In `@crates/wesley-core/tests/extension_generation.rs` around lines 371 - 444,
Extend checked_generation_fixtures_match_public_api_and_published_schemas with a
deserialize→revalidate round trip for input.json, provenance.json, and
review.json. Deserialize each checked-in fixture into
ExtensionGenerationInputV1, GenerationProvenanceManifestV1, and
GenerationReviewV1, then compare each value’s canonical_bytes() with the
corresponding fixture bytes and preserve schema validation.
crates/wesley-core/src/domain/extension_generation.rs (2)

452-469: 🗄️ Data Integrity & Integration | 🔵 Trivial | ⚡ Quick win

authoritative invariant is only enforced in canonical_bytes(), not by the type.

The doc comment states authoritative is "Always false: this projection is never an authority artifact," but the field is pub bool and the struct derives Deserialize, so any code (including external consumers of this published crate) can construct or deserialize a GenerationReviewV1 with authoritative: true and serialize it with the default Serialize impl, bypassing the guarantee entirely — only canonical_bytes() (Lines 516-529) checks and rejects it.

Consider encapsulating the field (private field + pub fn authoritative(&self) -> bool { false } accessor, with a custom Deserialize that hard-codes/validates the value) so the non-authoritative guarantee is structural rather than dependent on always calling canonical_bytes() before trusting the value.

🤖 Prompt for 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.

In `@crates/wesley-core/src/domain/extension_generation.rs` around lines 452 -
469, The GenerationReviewV1 type exposes a mutable authoritative flag that can
violate its documented always-false invariant. Encapsulate authoritative, ensure
construction and deserialization cannot accept true, provide an
authoritative(&self) accessor returning false, and preserve serialization and
canonical_bytes() behavior without relying solely on runtime validation there.

170-233: 🚀 Performance & Scalability | 🔵 Trivial | ⚡ Quick win

Root cause: digest()/canonical_bytes() silently re-normalize, causing redundant full revalidation inside verify(), new(), and from_manifest().

ExtensionGenerationInputV1::digest() (Lines 174-177) calls canonical_bytes() which calls self.normalized() (Lines 179-233), which fully reconstructs the value via Self::new(...) — re-sorting/deduping every collection and, when Law IR is present, re-running validate_law_ir_v1_bindings and compute_law_hash_v1 from scratch.

Every downstream caller that already holds a normalized value calls .digest() afterward, paying this cost twice in one logical operation:

  • GenerationProvenanceManifestV1::new() (Lines 314-336): input.normalized() then input.digest().
  • GenerationProvenanceManifestV1::verify() (Lines 352-397): same pattern.
  • GenerationReviewV1::from_manifest() (Lines 471-512): same pattern for both input and manifest.

For inputs carrying non-trivial Law IR/Shape IR/operation catalogs, this doubles the cost of binding validation and hashing on every provenance build/verify/review call. Consider adding a private helper (e.g. fn digest_from_normalized(normalized: &Self) -> Result<String, ...>) that computes the domain digest directly from an already-normalized value, and have new()/verify()/from_manifest() call it instead of re-invoking .digest().

Also applies to: 293-450, 471-512

🤖 Prompt for 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.

In `@crates/wesley-core/src/domain/extension_generation.rs` around lines 170 -
233, The digest and canonical serialization paths redundantly normalize
already-normalized inputs, causing repeated sorting, validation, and hashing.
Add a private helper near ExtensionGenerationInputV1::digest, such as
digest_from_normalized, that canonicalizes and hashes without calling
normalized(); update GenerationProvenanceManifestV1::new,
GenerationProvenanceManifestV1::verify, and GenerationReviewV1::from_manifest to
use it after their existing normalization step, while preserving public digest()
behavior for unnormalized callers.
🤖 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/wesley-core/src/domain/extension_generation.rs`:
- Around line 552-616: The stable diagnostic classification is too broad:
normalize_strings and validate_token report arbitrary invalid strings as
InvalidCoordinate. Add and wire a distinct InvalidToken
GenerationContractErrorKind with its own machine-readable code for
normalize_strings/validate_token failures, while retaining InvalidCoordinate for
coordinate and version validation in validate_coordinate and
GeneratorIdentityV1::validate.

---

Nitpick comments:
In `@crates/wesley-core/src/domain/extension_generation.rs`:
- Around line 452-469: The GenerationReviewV1 type exposes a mutable
authoritative flag that can violate its documented always-false invariant.
Encapsulate authoritative, ensure construction and deserialization cannot accept
true, provide an authoritative(&self) accessor returning false, and preserve
serialization and canonical_bytes() behavior without relying solely on runtime
validation there.
- Around line 170-233: The digest and canonical serialization paths redundantly
normalize already-normalized inputs, causing repeated sorting, validation, and
hashing. Add a private helper near ExtensionGenerationInputV1::digest, such as
digest_from_normalized, that canonicalizes and hashes without calling
normalized(); update GenerationProvenanceManifestV1::new,
GenerationProvenanceManifestV1::verify, and GenerationReviewV1::from_manifest to
use it after their existing normalization step, while preserving public digest()
behavior for unnormalized callers.

In `@crates/wesley-core/tests/extension_generation.rs`:
- Around line 371-444: Extend
checked_generation_fixtures_match_public_api_and_published_schemas with a
deserialize→revalidate round trip for input.json, provenance.json, and
review.json. Deserialize each checked-in fixture into
ExtensionGenerationInputV1, GenerationProvenanceManifestV1, and
GenerationReviewV1, then compare each value’s canonical_bytes() with the
corresponding fixture bytes and preserve schema validation.
🪄 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: CHILL

Plan: Pro

Run ID: 55e63e9a-6784-4a8c-a5b2-4b256de2cd3c

📥 Commits

Reviewing files that changed from the base of the PR and between cabbfe2 and 38e7409.

📒 Files selected for processing (38)
  • CHANGELOG.md
  • crates/wesley-cli/tests/cli.rs
  • crates/wesley-core/README.md
  • crates/wesley-core/src/domain/extension_generation.rs
  • crates/wesley-core/src/domain/mod.rs
  • crates/wesley-core/src/lib.rs
  • crates/wesley-core/tests/extension_generation.rs
  • docs/reference/extension-generation.md
  • docs/topics/README.md
  • docs/topics/extension-modules.md
  • schemas/README.md
  • schemas/wesley-extension-generation-input-v1.schema.json
  • schemas/wesley-generation-provenance-manifest-v1.schema.json
  • schemas/wesley-generation-review-v1.schema.json
  • scripts/pre-push-sanity.mjs
  • scripts/pre-push-sanity.test.mjs
  • test/ci-package-manager-policy.bats
  • test/ci-workflows.bats
  • test/docs-governance.bats
  • test/docs-planning-boundary.bats
  • test/docs-whitespace.bats
  • test/domain-empty-boundary.bats
  • test/fixtures/README.md
  • test/fixtures/extension-generation/README.md
  • test/fixtures/extension-generation/generated-profile.json
  • test/fixtures/extension-generation/input.json
  • test/fixtures/extension-generation/provenance.json
  • test/fixtures/extension-generation/review.json
  • test/fixtures/extension-generation/schema.graphql
  • test/fixtures/extension-generation/semantic-source.json
  • test/ir-fixtures.bats
  • test/release-governance.bats
  • test/serve-static-e2e.bats
  • test/serve-static-relative-unit.bats
  • test/serve-static-unit.bats
  • test/serve-static.bats
  • test/technical-teardown.bats
  • test/weslaw-fixtures.bats

Comment thread crates/wesley-core/src/domain/extension_generation.rs
@flyingrobots

flyingrobots commented Jul 14, 2026

Copy link
Copy Markdown
Owner Author

@codex review please

Final review head: 36c8afe0523e94a4345054dcde7ac80995f37062 (four review follow-up commits pushed; all prior threads resolved).

@flyingrobots

flyingrobots commented Jul 14, 2026

Copy link
Copy Markdown
Owner Author

Code Lawyer Final Activity Summary

Supersedes the earlier activity summary. Final review head: a0d4b8712a24bf7da04c186e3b9c1b5d074df10c.

# Severity Source Surface Commit Outcome
1 P0 Critical Self Pre-push child Git context 595d5787 Removed repository-local GIT_* state; leaked-context end-to-end witness preserved the caller index.
2 P1 High Self Nested generation input schema dfdf6380 Enforced concrete Shape, operation, and Law structures.
3 P2 Codex Documented Shape arguments 1c75a932 Added a distinct field-argument schema with optional descriptions.
4 P2 Codex Generation fixture CI trigger d55de1e5 Added pull-request and main-push Rust preflight paths plus workflow evidence.
5 P2 Codex Operation coordinates 727f4555 Rejected malformed root, field, and argument names before canonicalization.
6 P2 Codex Schema token parity 36c8afe0 Aligned input, provenance, and review token rejection with Rust validation.
7 P2 CodeRabbit Stable diagnostic classification c5edf077 Added InvalidToken while preserving InvalidCoordinate for coordinate surfaces.
8 P3 CodeRabbit nit cluster Review deserialization integrity a0d4b871 Made authority private/read-only, rejected true on decode, and added three fixture round trips.
9 P4 Process Self/CodeRabbit PR explanation and template metadata Refreshed walkthrough, final-head citations, RED/GREEN record, risk, backout, testing, and checklist sections.

All five inline review threads were answered and resolved through GraphQL. The remaining normalization-performance nit was inspected and intentionally not implemented: no benchmark or budget demonstrates a problem, and adding a private path that assumes prior normalization would weaken validation-path clarity in this correctness PR. CodeRabbit docstring and scope warnings are addressed by the documented audit-containment rationale and the fact that all new public APIs carry Rustdoc; they are not executable gate failures.

Final local gate: pnpm run preflight green; cargo xtask legacy-preflight green; extension generation 12/12; generated JSON artifacts 6/6; workflow Bats 29/29; git diff --check clean; worktree clean. The damaged original worktree remains untouched. No amend, reset, rebase, force-push, or branch deletion was used.

@flyingrobots

Copy link
Copy Markdown
Owner Author

@codex review please

Final review head: a0d4b8712a24bf7da04c186e3b9c1b5d074df10c. All inline threads are resolved; local Rust and legacy preflights are green.

@flyingrobots
flyingrobots merged commit f66b81c into main Jul 14, 2026
20 checks passed
@flyingrobots
flyingrobots deleted the provider/728-generation-provenance branch July 14, 2026 05:23
@chatgpt-codex-connector

Copy link
Copy Markdown

Codex Review: Didn't find any major issues. 👍

Reviewed commit: a0d4b8712a

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

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

feat(extensions): publish canonical semantic-generation input and provenance contract

1 participant