Skip to content

ci: gate the v1 canonical projection against the Go emitter - #37

Merged
luckyPipewrench merged 3 commits into
mainfrom
feat/canonical-contract-gate
Jul 25, 2026
Merged

luckyPipewrench merged 3 commits into
mainfrom
feat/canonical-contract-gate

Conversation

@luckyPipewrench

@luckyPipewrench luckyPipewrench commented Jul 25, 2026 •

Copy link
Copy Markdown
Member

Why

The drift tests added alongside the parity fix compare this package against a checked-in copy of the emitter's field list that lives in this same repository. That pins nothing. A change on the Go side leaves both the projection and its guard untouched and equally wrong, which is exactly how the projection drifted far enough that every receipt from a current Pipelock failed verification while the suite stayed green.

The underlying cause was structural rather than careless. A cross-language parity effort covered the three reference verifiers vendored inside the Go repository and never reached this separate repository, which is the one people install.

What this adds

A check that fetches the emitter's signing projection directly and compares field set, order and omitempty against the projection this package actually uses. Branch and tag refs are resolved to a commit before fetching, so a failure names an exact source and is reproducible later.

It fails closed when it cannot fetch, cannot parse, or does not recognise the shape it found. A check that quietly passes when it could not run is the bug being fixed, not an acceptable fallback.

It runs on a schedule and on demand rather than as a required check on every pull request. A change on the Go side is not the pull request author's fault and should not turn an unrelated review red.

Proof it fails

A gate that cannot be shown failing is not a gate, so this was verified by breaking the thing it guards rather than by observing it pass.

Removing a single field from the live projection and running the check the way the workflow runs it, with a bare interpreter and nothing installed, exits non-zero with a diff naming the emitter source. Restoring the field returns it to a clean pass against the current emitter.

A defect found while verifying

As first written the workflow could never have run. It performs no install, and running a script under scripts/ puts that directory on the path and the repository root nowhere, so the import failed outright. Had the package been present by some other means it would have been worse than a crash: the check would have compared against that unrelated copy and reported a pass about code this repository does not ship.

The projection is now imported inside the function that needs it, from this checkout, so the check is deterministic regardless of what happens to be installed.

Kept

The checked-in mirror tests stay as the fast offline signal. They are labelled so it is clear which of the two is authoritative.

Summary by CodeRabbit

  • New Features

    • Added an automated daily check to detect differences between Python and Go canonical data contracts.
    • Added support for manual checks and configurable source references.
    • Checks fail safely when contracts differ, fields are reordered, or source data cannot be parsed or retrieved.
  • Tests

    • Added coverage for field ordering, optional-field handling, contract changes, malformed definitions, and source-read failures.
    • Clarified the role of the local canonical-field validation.

The existing drift tests compare this package against a checked-in copy of the emitter's field list that lives in this same repository, so a change on the Go side leaves both the code and its guard untouched and equally wrong. That is how the projection drifted far enough that every receipt from a current Pipelock failed verification while the suite stayed green.

Adds a check that fetches the emitter's signing projection directly and compares field set, order and omitempty against the projection this package actually uses. Branch and tag refs are resolved to a commit before fetching, so a failure names an exact source. It fails closed when it cannot fetch, cannot parse, or does not recognise the shape it found, because a check that quietly passes when it cannot run is the bug being fixed.

It runs on a schedule rather than as a required check on every pull request. A change on the Go side is not the pull request author's fault and should not turn an unrelated review red.

The projection is imported inside the function that needs it, from this checkout. Running a script under scripts/ puts that directory on the path and the repository root nowhere, so a top-level import either fails outright, as it did under the workflow as first written, or silently reads an unrelated installed copy and reports a pass about the wrong code.

The checked-in mirror tests are kept and labelled as the fast offline signal, with the fetched check authoritative.
@coderabbitai

coderabbitai Bot commented Jul 25, 2026 •

Copy link
Copy Markdown

Review Change Stack

Warning

Review limit reached

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

Next review available in: 54 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 8759799f-df3f-44fb-8b58-efebc39682b1

📥 Commits

Reviewing files that changed from the base of the PR and between 7448d03 and 5b21936.

📒 Files selected for processing (2)
  • scripts/check_go_canonical_contract.py
  • tests/test_go_canonical_contract_gate.py
📝 Walkthrough

Walkthrough

Adds a fail-closed Python checker that compares Python canonical JSON fields with pinned Go source, tests drift and parsing failures, and runs the check daily or manually through GitHub Actions.

Changes

Canonical contract drift detection

Layer / File(s) Summary
Contract models and source extraction
scripts/check_go_canonical_contract.py, tests/test_go_canonical_contract_gate.py
Defines contract field and error types, loads Python canonical fields, reads or fetches Go source, and extracts ordered JSON tags with omitempty handling.
Contract comparison and CLI execution
scripts/check_go_canonical_contract.py, tests/test_go_canonical_contract_gate.py
Compares contracts, reports unified diffs, supports ref/source/timeout arguments, and tests added, reordered, or modified fields plus fail-closed parsing behavior.
Scheduled gate and validation notes
.github/workflows/canonical-contract-drift.yml, tests/test_field_drift.py
Runs the checker daily or manually with Python 3.12, configurable Go ref, read-only permissions, and a five-minute timeout; documents the authoritative drift guard.

Estimated code review effort: 3 (Moderate) | ~25 minutes

Sequence Diagram(s)

sequenceDiagram
  participant Workflow as GitHub Actions
  participant Checker as Contract checker
  participant GitHub as GitHub source API
  participant Python as Python canonical contract
  participant Go as Go canonical source
  Workflow->>Checker: Run with configured Go ref
  Checker->>GitHub: Resolve ref and fetch canonical.go
  Checker->>Python: Load expected field projection
  Checker->>Go: Parse ordered field tags
  Checker->>Checker: Compare contracts
  Checker-->>Workflow: PASS or failure exit
Loading
🚥 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 clearly summarizes the main change: adding a CI gate that compares the v1 canonical projection with the Go emitter.
Docstring Coverage ✅ Passed No functions found in the changed files to evaluate docstring coverage. Skipping docstring coverage check.
Linked Issues check ✅ Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check ✅ Passed Check skipped because no linked issues were found for this pull request.
✨ Finishing Touches
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Commit unit tests in branch feat/canonical-contract-gate

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.

The self-scan flags any assignment whose name starts with a credential word, whether or not a URL is involved, so reading a GitHub token from the environment into a variable called token fails the security check on a false positive. Renaming it clears the check without excluding the file or relaxing the scan.

@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

🤖 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 `@scripts/check_go_canonical_contract.py`:
- Around line 30-40: Update the canonical struct discovery used by the script’s
parsing flow around GO_STRUCTS and the logic at lines 197 and 264 so it extracts
every *CanonicalV1 struct declared in canonical.go instead of filtering against
the predeclared tuple; preserve diff_contracts() as the mechanism that rejects
production-only extras. Add a regression test covering a newly discovered
canonical projection without a Python counterpart.
🪄 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: defaults

Review profile: CHILL

Plan: Pro Plus

Run ID: 4c316936-560f-4970-a964-e6a19ec5f0df

📥 Commits

Reviewing files that changed from the base of the PR and between d2e0d47 and 7448d03.

📒 Files selected for processing (4)
  • .github/workflows/canonical-contract-drift.yml
  • scripts/check_go_canonical_contract.py
  • tests/test_field_drift.py
  • tests/test_go_canonical_contract_gate.py

Comment thread scripts/check_go_canonical_contract.py Resolved
The parser walked a predeclared list of struct names, which made the unexpected-struct branch unreachable. A signing projection added on the Go side was skipped in silence and the gate reported a pass while this package had no counterpart for it at all, which is the same shape of hole the gate exists to close.

Every Go type named CanonicalV1 is now discovered and compared. Verified by appending a new projection to a copy of the emitter source and confirming the gate rejects it, and by removing the fix and watching the new test fail.
@luckyPipewrench
luckyPipewrench merged commit 3b700f1 into main Jul 25, 2026
14 checks passed
@luckyPipewrench
luckyPipewrench deleted the feat/canonical-contract-gate branch July 25, 2026 02:48
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.

1 participant