Repository navigation
contracts: two immutable-revision downstream integration contracts - #138
Merged
Merged
Conversation
…racts
Downstream repositories had no stable surface to integrate against: the action
README documented pins, but nothing said which subcommands are in contract, what
"green" means, or when a submitted test-evidence document may be believed.
contracts/squabble — squabble-contract/1.0.0
* read-only invocation surface (fetch, diagnose, verify-satisfied, chains);
fight --apply / board / inbox-sweep are out of contract and the consumer
audit refuses them
* required GitHub permissions (six reads, plus the administration: read that
github.token cannot hold), and the write-search refusal
* machine-readable gate / verdict / envelope / verdict-verdict schemas and
deterministic output
* exit semantics, and the decision procedure for legitimate_green: a
commit-bound envelope whose EVERY required check has run "passed".
verify-satisfied's exit 0 is ruleset-legitimate — a skipped required check
satisfies GitHub and carries no evidence, and a pending required check is
not even an agent item — so it can never certify green.
* bin/legitimate-green (the oracle), bin/bind-gate, and
bin/audit-consumer-workflow.sh (E-UNPINNED-ACTION, E-WRITE-PERMISSION,
E-MASKED-STEP, E-BYPASS-COMMAND, ...)
* negative fixtures for missing, skipped, cancelled, failed, pending,
unknown-state, empty-requirement-set, replayed-at-another-head and
branch-name-as-commit; positive controls so the refusals mean something
* 27-case conformance suite
contracts/proven-tests — proven-tests-evidence/1.0.0
* how a Rust repository submits real executed-test evidence, without Idris2:
one JSON document, produced by bin/collect-evidence.sh from one captured
libtest run, gated by bin/verify-evidence
* example / property / proof evidence told apart by kind with the tier
evidence each requires; sampling cannot claim actually_proven
* coverage derived only from executed, passing, non-debt records at typed
coordinates (17x14), with a typed taxonomy pinned in the revision; a
coverage_claim that outruns the derivation is refused
* rules R0-R11 with ids, including R1 (a pass is a run: timestamps, argv,
exit status, log digest) and R11 (aggregate exit vs per-test records)
* toolchain: submitter needs bash/jq/coreutils; the Idris2 0.7.0 + chez + GMP
path documented for building the framework itself
* 26 evidence fixtures, 7 recorded-log producer cases, minimal downstream
Rust fixture with coords, fixtures and a pinned workflow
* 35-case conformance suite
Both contracts pin by revision id + sha256 SHASUMS manifest (bin/verify-pin.sh),
never by a branch, and both suites count planned cases so an unexercised case is
a refusal rather than a pass. Neither tool writes, merges, re-runs or overrides.
Known limits, stated in the documents: the Rust fixture crate has not been
compiled here (no Rust toolchain in this environment), so the suites exercise
the producer and gate against recorded logs; and wiring contract-test into CI
needs an actions.lock regeneration, which is left to a follow-up.
Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
Codex Review SummaryThis comment shows the latest Codex review activity on this pull request.
ℹ️ About Codex in GitHubYour team has set up Codex to review pull requests in this repo. Reviews are triggered when you
Codex reacts with 👀 while any review is running, comments if it has suggestions, and reacts with 👍 once all reviews finish with no findings. |
|
You have reached your Codex usage limits for code reviews. You can see your limits in the Codex usage dashboard. |
Contributor
|
Important Review skippedToo many files! This PR contains 102 files, which is 2 over the limit of 100. To get a review, reduce the PR to 100 files or fewer by splitting it into smaller PRs or changing its base branch. Upgrade to a paid plan to raise the limit. This review couldn't start because sufficient usage credits or metered capacity aren't available. Add credits or update usage-based reviews in the billing tab, then retry.
 |
The root-shape gate failed on the new top-level entry. contracts/ is a published component, not documentation: a consumer clones this tree at a pinned commit and runs contracts/bin/ from it, so the path is part of the contract's surface and moving it would break every downstream pin. Added with the same justification-comment style the allowlist already uses for the other declared entries. Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
The estate's reusable CI gates moved from the hyperpolymath user account to the
metadatastician organization. Every workflow that called them by the old name
stopped starting: GitHub could not resolve the reference at plan time, so the
runs have zero jobs, and the run is even labelled with its own file path instead
of its `name:` field.
Evidence, from this repository's own run history:
run 39700543957 (2026-10-22, before the move)
name: "Secret Scanner"
referenced_workflows: [hyperpolymath/standards/.../secret-scanner-reusable.yml@75bd5994]
run 40227232833 (2026-10-25, main, after the move)
name: ".github/workflows/secret-scanner.yml"
referenced_workflows: [] <- the reusable was never resolved
Thirteen runs across five workflows (secret-scanner, hypatia-scan, governance,
rust-ci, standards-pipeline) were dead this way, all with jobs=0. Because a run
that creates no jobs also creates no check run, `gh pr checks` still showed 25
passing and nothing failing - the failure this repository's crates/squabble-core
gate names MissingCause::DeadActionPin.
The move is a transfer, not a rename: repo_id 1116521501 is unchanged, owner_id
goes 6759885 -> 297579217, and the new owner's own description is "Canon for the
hyperpolymath estate ... the reusable CI gates that enforce them". The reusables'
content was diffed old -> new: 34 changed lines in secret-scanner-reusable.yml
(the estate gitleaks baseline is now staged only for consumers without their own
.gitleaks.toml, per echidnabot#185) and no change to any `permissions:` block in
any of the seven reusables - so the callee-subset-of-caller constraint that makes
a caller fail at plan time is still satisfied.
metadatastician/standards@75bd5994 -> @8e48b1ca (main, 2026-10-24)
Actions lock: hand-edited, because `gh actions-lock` cannot be installed in this
environment (its release asset host is not reachable from the sandbox). The edit
follows the generator's own shape: the seven workflows: entries re-pointed, the
superseded dependencies: records for 75bd5994 and 427eb35c removed, a record
added for the new pin with owner_id/repo_id taken from the API, and the closure
re-derived from the callee files themselves rather than from memory - which is
what surfaced two action bumps carried in with the move
(dtolnay/rust-toolchain@e2a55d2 -> 683b588c, ossf/scorecard-action@2d114668 ->
fa7117db, the latter getting a new record) and the one nested standards ref that
ci-pipeline.yml@8e48b1ca still pins under the old owner (d55304a0, record added).
Verified with a clause-for-clause port of scripts/check-lock-sync.sh (clauses 1-4
incl. transitive closure), which was itself first validated by passing on the
pre-change tree; scripts/check-lock-sync.sh needs gawk, which is not installed
here, so CI remains the authority.
Known limit, disclosed rather than papered over: ci-pipeline.yml at the new pin
still nests metadatastician/standards@d55304a0 internally, so standards-pipeline.yml
may remain unresolvable until upstream re-points its own internal refs. That is
upstream's edit, not ours.
hyperpolymath/smtp-notify-action is untouched: it still lives under the same
account and did not move.
Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
…efore merge) Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
Result recorded in the PR, not in the tree: a same-owner reusable call from this repository resolves and creates 5 jobs, while the cross-owner call to metadatastician/standards creates none - so the remaining block is cross-owner resolution, not the pin, not permissions, and not the callee's contract. Co-authored-by: arena-agent <297053741+arena-agent@users.noreply.github.com>
hyperpolymath
enabled auto-merge
October 25, 2026 21:00
|
Contributor
|
Add Carrot credits or activate Agent usage billing to use Autofix |
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Publishes the two integration contracts the estate's downstream repositories have been missing. Both are consumed by revision id + sha256 manifest, never by a branch, and both ship a conformance suite that counts planned cases, so an unexercised case is a refusal rather than a pass.
contracts/squabble—squabble-contract/1.0.0fetch,diagnose,verify-satisfied,chains.fight --apply,boardandinbox-sweepare out of contract; the consumer audit refuses them.administration: readthatgithub.tokencannot hold (App / fine-grained PAT). Any*: writeis a contract violation and a finding.install.sh); the contract pinned by revision +SHASUMS.done: true), gate-satisfied, andlegitimate_green— a commit-bound envelope whose every required check has runpassed.verify-satisfied's exit 0 can never certify green: a skipped required check satisfies GitHub with no evidence, and a pending required check is not even an agent item.bash contracts/squabble/tests/run-conformance.sh.contracts/proven-tests—proven-tests-evidence/1.0.0bin/collect-evidence.shfrom one captured libtest run, gated bybin/verify-evidence. Submitting needsbash,jq, coreutils — not Idris2; the Idris2 0.7.0 + chez + GMP path is documented for building the framework itself.example/property/proofwith the tier evidence each requires (property needs a generator, shrinker,cases_run ≥ 1,failures: 0; proof needs a checker that ran, and ≥ 1 witnessed rung — mirroringList1 Witnessed). Sampling can never claimactually_proven.coverage_claimthat outruns the derivation is refused. Debt-marked records are excluded entirely (TEST-DOCTRINE B.4).bash contracts/proven-tests/tests/run-conformance.sh.Bypass resistance, in both
E-UNPINNED-ACTION,E-MOVING-REF,E-WRITE-PERMISSION,E-MASKED-STEP,E-BYPASS-COMMAND,E-PRIVILEGED-TRIGGER,E-NO-ORACLE— with a good workflow fixture that passes, so the refusals aren't vacuous. The audit is a lint; the real boundary is the read-only token, and the contract says so.Known limits (stated in the documents, not just here)
contract-testinto CI needs anactions.lockregeneration, which needsgh actions-lock; left as a follow-up.just contract-testruns both suites today (needs only bash + jq).hyperpolymath/proven-tests-and-benches;contracts/proven-tests/LANDING.adocis the landing checklist (what to copy, what not to edit, what to record).Testing