Repository navigation
feat(receipt): one receipt for each learning update, with a Nickel contract (E0-09) - #1161
Conversation
…ntract (E0-09) Hypatia now writes a receipt for each row that the gate reads (a qualified row and an audit row) and for each qualified neural update, in the form that the ruled design of E0-08 defines (docs/design/e0-receipt.adoc): canonical JSON (sorted keys, ASCII, no numbers), receipts/YYYY-MM.jsonl under the data root of the row, a receipt_sha256 over every other field, and a Nickel contract (schema/receipt.ncl) that derives the verdict from the gate and refuses a receipt that claims more than its evidence. Every row carries an event_id (an Elixir implementation of ADR-008 profile T) that a caller cannot choose. The row is the commit; a failed receipt write is logged as receipt_pending and written when the recipe is next recomputed. Co-Authored-By: Claude <noreply@anthropic.com>
|
Caution Review failedThe pull request is closed. Summary
Merge Risk:
|
…09 branch CI on the receipt emitter failed two checks, both caused by that change: * readme-claims: lib/ holds 172 source files (the emitter adds lib/hypatia/receipt.ex and lib/hypatia/event_id.ex) and README.adoc said 170. The count is corrected; scripts/check-readme-claims.sh and its self-test (7 of 7) pass. * governance / UUID v8 conformance (and its v7 alias): check-uuid-v8.sh --strict reads source text and has no exemption, and it refused three deliberately wrong UUID literals in the tests (a version 7 id, and a version 8 id with variant c). The tests now make each wrong id from a version 8 id by changing one nibble, and check that putting the nibble back gives the valid id again, so the nibble that valid?/1 and the Nickel contract refuse is the one that changed. The contract case now also re-seals the receipt and checks that the refusal names event_id. Mutation checks (each restored byte-identical): the contract accepting version 7 fails the contract test; valid?/1 accepting version 7, and accepting variant c, each fail the valid?/1 test. Co-Authored-By: Claude <noreply@anthropic.com>
Codex Review Summary: ✅ CompletedThis 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. |
|
There was a problem hiding this comment.
💡 Codex Review
Here are some automated review suggestions for this pull request.
Reviewed commit: 0ad4eb22d8
ℹ️ 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".
| record_neural_outcome(finding, outcome_str, server) | ||
| write_neural_receipt(to_string(pattern), to_string(repo), outcome_str, verification) |
There was a problem hiding this comment.
Write the receipt only when neural queueing succeeds
When the coordinator is unavailable or returns an error, record_neural_outcome/3 converts that failure to {:error, ...}, but this return value is ignored and the next line still emits a receipt. In that scenario no update was queued, yet the receipt records a credited_success or credited_failure and therefore falsely claims that the event changed the learner; branch on :queued before writing it.
Useful? React with 👍 / 👎.
| {:error, reason} -> | ||
| Logger.warning( | ||
| "receipt_pending event_id=#{Map.get(record, "event_id")} reason=#{inspect(reason)}" | ||
| ) |
There was a problem hiding this comment.
Ensure failed fleet receipts enter a repair path
If appending a receipt temporarily fails for a fleet-imported row, this branch only logs the failure. The source import is then acknowledged, while LearningScheduler.process_local_complete_lines/4 explicitly skips rows whose origin is gitbot-fleet (lines 686–690), so that recipe is never passed through the public update_recipe_confidence/1 call that invokes repair_receipts/1. The committed fleet row can therefore remain without a receipt permanently after a transient filesystem error.
Useful? React with 👍 / 👎.
| else | ||
| {:error, reason} -> | ||
| Logger.warning("receipt_pending event_id=#{event_id} reason=#{inspect(reason)}") | ||
| end |
There was a problem hiding this comment.
Retain failed neural receipts for later repair
When neural queueing succeeds but the receipt append fails transiently, this handler records only a log message and discards the event ID and evidence. Unlike outcome-log rows, the neural event has no durable row that Receipt.repair/2 can discover, so no later cycle can ever create the missing receipt and the promised one-receipt-per-learning-update invariant is permanently broken.
Useful? React with 👍 / 👎.
| else if claimed == "false_positive" | ||
| && std.array.elem qualification ["still_present", "verified", "rollback_requested"] then | ||
| "credited_false_positive" |
There was a problem hiding this comment.
Require batch evidence before certifying a rollback
A receipt with claimed_outcome: "false_positive", qualification: "rollback_requested", and verdict: "credited_false_positive" satisfies this contract, but the actual gate in OutcomeTracker.qualified_outcome_counts/1 credits that qualification only when the row also has caused_by: "batch_rollback" and a nonempty batch_id (lines 762–769). Because the receipt schema neither carries nor checks those conditions, the contract can certify a rollback that the learning gate would ignore.
Useful? React with 👍 / 👎.
| |> Map.drop(@receipt_context_keys), | ||
| true, | ||
| :local_caller |
There was a problem hiding this comment.
Preserve rescan provenance on still-present outcomes
When record_and_verify/5 detects :still_present, it writes both the claimed-success row and the credited false-positive row through record_outcome/5, so this forced kind labels them local_caller even though their qualification came from Hypatia's rescan. Receipt.observations/2 includes the rescan observation only for local_rescan, causing the resulting false-positive receipt to omit the observation that justified its credit and to misstate its source; those rescan-produced rows need the trusted rescan kind.
Useful? React with 👍 / 👎.
| with {:ok, event_id} <- fetch_event_id(row), | ||
| false <- exists?(data_root, event_id), | ||
| {:ok, ctx} <- context(data_root, row, opts), | ||
| receipt = build(row, ctx), | ||
| {:ok, line} <- encode(receipt) do | ||
| append(data_root, line) |
There was a problem hiding this comment.
Serialize the receipt existence check and append
The replay guard is a check-then-append sequence with no lock or atomic uniqueness mechanism. If the immediate writer and a repair cycle, or any two replaying callers, process the same event concurrently, both can observe exists?/2 == false before either append and then write two receipt lines for one event_id; the sequential replay test does not cover this race, and it violates the exactly-one receipt invariant.
Useful? React with 👍 / 👎.
| evidence = %{ | ||
| "file" => ".", | ||
| "outcome" => outcome, | ||
| "recipe_id" => pattern, | ||
| "repo" => repo, | ||
| "verification" => verification | ||
| } |
There was a problem hiding this comment.
Hash the complete neural training input
The coordinator trains MoE, LSM, and the sequence model from the entire finding map, including fields such as fix_type, confidence, and any other features, but this receipt hashes only pattern, repo, outcome, and verification. Two updates with different model inputs can therefore have the same row_sha256, and changes to the fields that actually influence training are invisible to the receipt, so it does not name the exact evidence on which the neural update rested.
Useful? React with 👍 / 👎.
| case :persistent_term.get(@key, nil) do | ||
| nil -> | ||
| ref = :atomics.new(1, signed: false) | ||
| :persistent_term.put(@key, ref) | ||
| :persistent_term.get(@key) |
There was a problem hiding this comment.
Initialize the shared event counter atomically
On the first concurrent calls to generate/0, multiple processes can all observe a missing persistent term, create separate atomics references, and overwrite each other's reference. A process that generated its first ID from the displaced reference can then generate its next ID from the replacement counter starting at zero, so IDs within that process are no longer guaranteed to increase as the profile and module documentation require; the one-time initialization needs synchronization rather than an unconditional put.
Useful? React with 👍 / 👎.
| assertion | ||
| | { claimed_outcome | claimed_outcome_c, file | ascii_c, recipe_id | ascii_c, repo | ascii_c }, | ||
| chain_version | std.contract.Equal "e0-receipt/1", | ||
| event_id | event_id_c | optional, |
There was a problem hiding this comment.
Reject receipts without an event ID
Marking event_id optional allows a receipt with no stable identity to pass the contract as long as missing_evidence names event_id. The ruled design explicitly says that a legacy row without an ID gets no receipt at all, and receipt replay, repair, causality, and withdrawal all depend on that ID, so the schema currently accepts an object that cannot participate in the receipt protocol.
Useful? React with 👍 / 👎.
… test (E0-10) (#1164) ## What An Idris2 model of the E0 receipt, `src/Hypatia/ABI/Receipt.idr`, that states and proves the five properties of `docs/design/e0-receipt.adoc` section 8. The verdict gate (`scripts/check-verdicts.sh`) checks it, with fixtures that it must accept and fixtures that it must refuse. A mirror test holds the emitter of E0-09 to the model. Work order: E0-10. Depends on E0-09 (merged, #1161). ## Status of each property (machine register) Kernel: Idris 2 0.7.0, `idris2 --build src/abi/hypatia-abi.ipkg` with `--total` and `%default total`. Holes: none. Axioms and postulates: none. A grep for `believe_me`, `assert_total`, `postulate`, `partial`, `covering` in the new files finds nothing. | Property | Model (kernel-checked) | Run time | |---|---|---| | P1 no two receipts share an `event_id` | VERIFIED: `appendRefusesDuplicate`, `appendFresh`, `appendKeepsUnique` | TESTED by the mirror test | | P2 no claim beyond the evidence | VERIFIED: `verdictIsGate`, `verifiedHasEvidence`, `noVerifiedWithoutObservations`, `creditedSuccessIsEvidenced`, `withdrawnHasParent`, `gateNeverWithdrawn`, `gateSuccessInverse` | TESTED, with one known difference (below) | | P3 a revision keeps the history | VERIFIED: `appendKeepsHistory`, `reviseKeepsHistory`, `reviseKeepsClaim` | none: no run-time code builds a revision yet (E0-07) | | P4 a fill never overwrites | VERIFIED: `fillNeverOverwrites`, `fillChangesOnlyGaps`, `fillValueIsFromExtra`, `reviseNeverOverwrites` | none, as for P3 | | P5 `missing_evidence` is exact | VERIFIED: `missingIff`, `missingEmptyIff`, `receiptMissingExact` | TESTED over all 32 combinations of observations | Trust base: the Idris 2 kernel, and `base` (`Data.List`, `Data.List.Elem`, `Data.Maybe`). The model uses no library `DecEq`: event ids are naturals with a structural equality written in the module (a first draft used `isElem` and could not be evaluated by the fixtures, so I replaced it). The Prelude's Nat literal elaboration contains an `assert_total`, visible in a compiler diagnostic; it is library trust, not a use by this module. ## What the model is not * **Not the Elixir run time.** An `event_id`, a digest and a field value are naturals. The real values are ADR-008 strings. The ledger row of each property says so. * **Not retraction.** `Retraction.idr` retracts by position and the run time by name. This module has no retraction. A withdrawal is a revision (an appended receipt with verdict `Withdrawn` and a parent), by `event_id`. Neither the positional nor the named retraction is proved, and idempotence or order-independence of a withdrawal is not claimed (the design says so too). * **Not order or duplicates in `missing_evidence`.** The model proves membership and emptiness. Sortedness and absence of duplicates are checked by the Nickel contract and the mirror test. * **Nothing about confidence.** A withdrawal of a failure row raises it. ## Two differences between the model and the run time (please rule) The stop rule of the work order says to report a property that does not hold, and not to weaken it. I have not weakened anything. Both are pinned as tests of their own, so a change is noticed. 1. **P1, "refused".** `Receipt.write/3` of an `event_id` that already has a receipt writes nothing and returns `:ok` (an idempotent replay). The model answers `Left DuplicateEventId`. The ledger is unchanged in both, which is the property. If you want a refusal to be an error at run time, that is a decision for E0-07's replay rules. 2. **P2, `build/2` is not a smart constructor.** The model cannot build a `verified` receipt without a row digest and an observation, and the Nickel contract refuses one. But `Receipt.build/2` on a hand-made `verified` row with no hit counts and no rescan returns `observations == %{}`. **Counter-example at the run time:** `build(row("verified", "success"), ctx)`. No production entry point makes such a row: a fleet row classifies as `verified` only with `before_hits > 0` and `after_hits == 0` (the mirror test runs 3 x 3 x 3 x 2 x 6 = 324 fleet records through `classify_fleet_record` and checks every `verified` one), a rescan-verified local row carries `rescan`, `record_outcome/5` rewrites a caller's `verified`, and the neural path's trusted verification is `nil` today. But the guarantee is held by the callers and by the contract, not by `build/2` or `write/3`. A guard in `write/3` (refuse, log `receipt_pending`) is about ten lines. I did not add it: E0-10 is the model, and what a refused receipt does to the repair loop is your call. ## Evidence * `bash scripts/check-verdicts.sh`: `PASS: ABI package, 11 positive control(s), 21 expected rejection(s)`. Before: 5 and 15, as the work order measured. Also run from a clean `git archive` of the commit. * Fixtures: 6 accepted, 6 refused; each property has at least one of each. `ReceiptP2GateTable` pins all 24 entries of the gate to `verdict_for` of `schema/receipt.ncl`. Each refusal is a false claim about one property, refused at its `invalid` declaration with a recorded diagnostic. * `mix test`: 3487 tests, 0 failures (246 excluded). `test/receipt_model_mirror_test.exs`: 12 tests, in the run. Elixir 1.19.4 (see process notes). * `scripts/proof-ledger.sh check`, `render --check` and `claims`: pass. 53 rows (6 new). * `mix format --check-formatted` on the new test; `check-uuid-v8.sh --strict` on a clean export: exit 0; `scripts/check-readme-claims.sh`: pass; self-scan: the same 15 `structured_format` findings as `main`, none on a changed file. ### Mutation checks Model (Idris), each restored byte-identical: | Mutation | Result | |---|---| | fill prefers the new value | kernel refuses (`fillNeverOverwrites`) | | a duplicate id is accepted | kernel refuses (`appendRefusesDuplicate`, `appendKeepsUnique`) | | a present field is named missing | kernel refuses (`elemGapIfKeeps`, `gapIfElem`) | | `verified` needs no observation | kernel refuses (`credit`, `verifiedHasEvidence`) | | a row of the gate table is changed | **kernel accepts the module**; only the new `ReceiptP2GateTable` fixture catches it. I added that fixture because of this result: the theorems hold of any table that never answers `Withdrawn`, and the table itself was not pinned. | Mirror test, each restored: an Idris gate row changed, a field dropped from `allFields`, the emitter no longer crediting false positives, the emitter no longer naming `tool_version`, and `write/3` no longer checking for an existing receipt. All five fail a test. ## Not done / differences from the work order * The work order's file list does not include `README.adoc`, `AFFIRMATION.adoc` and `EXPLAINME.adoc`. I changed only the census phrase in each (27 proven of 47 -> 33 of 53), because `scripts/proof-ledger.sh claims` fails otherwise. No licence file or SPDX header is touched. * The Nickel contract tests need `nickel`, which CI does not install (the receipt contract tests skip loudly there). Not changed here. * The mirror test does not and cannot cover P3 and P4 (no run-time counterpart). It says so. ## Process notes * `scripts/api-agents/run-work-order.sh E0-10 --dry-run` exits 0 and would run `--agent e0-supervisor --model opus --effort high --max-budget-usd 25 --max-turns 250`, which is what this session is. * Idris 2 0.7.0 was installed with `scripts/dev/install-toolchain.sh --with-idris2` (the pinned, checksum-verified source build). That script also moved the local Elixir from 1.17.3 to 1.19.4 (its current pin, which is CI's); the format gate now matches CI. * **Cost: unknown to me.** I cannot see spend. Please read it in the Anthropic Console. * Draft. Not merged, approved or marked ready by me. Co-authored-by: Claude <noreply@anthropic.com>



What
Work order E0-09. Hypatia writes one receipt for each learning update, in the form that the ruled design of E0-08 defines, and a Nickel contract refuses a receipt that claims more than its evidence.
lib/hypatia/receipt.ex: build, canonical encoding, append, replay check, repair, orphan report.lib/hypatia/event_id.ex: an Elixir implementation of the ADR-008 profile T layout (owner ruling R5-A). NoSystem.cmd.schema/receipt.ncl: the contract.OutcomeTracker.persist_outcome/6(every local and imported row) and the neural call ofFleetDispatcher.Why
Issue 984, step 10 and acceptance A7, and the rulings of 2026-11-15 recorded in
docs/design/e0-receipt.adoc(RULED, section 9a).How it works (the rules that matter)
event_idand by the SHA-256 of the exact evidence bytes, never a count.{:error, :row_not_in_log}).{:ok, record}to the caller (R3), logsreceipt_pending event_id=..., andupdate_recipe_confidence/1writes the missing receipts the next time the recipe is recomputed.event_idor any context field: the public entry strips them, and only the trusted fleet import may bring a producer's id. Receipts are deduplicated byevent_id, so a chosen duplicate would have silenced a real receipt.verdictaudit_only(R1).verdictis derived from the gate by the contract.scripts/proof-ledger.sh: a number is a decimal string; text outside printable ASCII is written%XX(and%as%25) so the receipt stays ASCII and decodable.Evidence
2bf46b95schema/receipt.ncl,ReceiptandEventIdwere written before their own tests (I wrote the contract and the module together). The integration tests oftest/receipt_test.exs(29 tests) were written before the call sites were wired, and with the three call sites set aside they gave:mix test test/receipt_test.exsgave29 tests, 0 failures;mix test test/event_id_test.exs7 tests, 0 failures;mix test(LANG=C.UTF-8) gave3713 tests, 0 failures, 246 excluded.audit_only; a replay writes no second receipt (the scheduler three times, andReceipt.writetwice); the receipt goes to the store of its row when the data root changes; the 3 failure points (row write fails: no receipt and nothing else; receipt write fails:{:ok, record},receipt_pending, repaired by the next recompute, exactly once; derived update fails: the receipt stays one); no receipt before its row, and an orphan is reported; nothing is back-filled for a row with noevent_id.test/fixtures/receipt/e0-receipt-line.jsonlbyte for byte, andjq -cS . fixtureprints the same bytes (tested).escript-soundness.ymlpins), SHA-256d40cd32b...verified, run bytest/receipt_test.exs: the emitter's receipts satisfy it (the fixture, and the 3 that the integration test writes), and 8 changes are each refused: a verdict that is not the gate's answer,verifiedwith no observations,missing_evidencenot exact, a qualification outside the closed set, a malformed digest, a number where a string belongs, a wrong chain version, an event id that is not version 8.Mutation M2 first survived: my test passed with the stripping removed, because
event_idis overwritten anyway for a local row. The stripping is what keeps a caller's made-upsource_line,source_row_sha256andsource_botout of stored rows, so I added that assertion and M2 now fails as shown.mix format --check-formatted: exit 0 for the 3 changedlib/files (formatted on main), the 2 new modules and the 2 new test files.mix escript.build && ./hypatia scan . --format json: 17 findings in total, 0 on the changed files.ls ~/Documentsafter the suite: nothing written there.Not done, and deviations you should see
lib/learning_scheduler.ex(one function and one call) as well as the two call sites. The fleet import is the only place that knows the source line, the digest of the exact source bytes and the producing bot, and the receipt needs them. Without it a fleet receipt would hash the stored row and not the evidence the producer wrote.event_idminted by Hypatia (provenance.event_id_sourceishypatia), because no fleet row carries a producer id yet. Replay is still safe: the row is deduplicated byfleet_import_idbefore it is written, so no second row and no second receipt. When E0-11 and E0-12 give rows a producer id, the import will pass it and the source becomesproducer.update_recipe_confidence/1), not on a schedule of its own. A recipe whose receipt is pending and that gets no new row and no confidence retry waits. A hook in the scheduler cycle would be a third call site; I did not add it. Say so if you want it.nickelis absent. TheIntegration Testsjob has no Nickel, so the contract is not checked in CI by this change. Adding a Nickel step (pinned, with its SHA-256, asescript-soundness.ymldoes) is a workflow change that is outside this work order's paths; I have not made it.exists?/2andrepair/2read the receipt and outcome logs;lineof a local row is found by scanning for itsevent_id. Fine at today's volumes; a per-recipe high-water mark is the fix if it grows. Not measured.pattern_idandmatch_kindare named inmissing_evidenceuntil E0-18 gives rows those fields.head_sha,subject_id,tool_version,scan_digestandtest_digestare named as gaps, as the design says.event_id,event_id_sourceandsource_kind(additive; the gate ignores them).mainformats under 1.19.4 (chore(elixir): move to Elixir 1.19.4 and gate formatting in CI #1151); a difference in the formatter is possible on a file I wrote.Cost
E0-09, cap $18. Cost unknown: the launch script was not run for real and I cannot see my own spend. Check the Console.CI fix (commit 859995b)
The first CI run failed 4 checks, all caused by this change. Fixed in a second commit:
readme-claimssaidlib/had 170 files; this PR addslib/hypatia/receipt.exandlib/hypatia/event_id.ex, so 172. README corrected. Local:scripts/check-readme-claims.shexit 0;tests/readme-claims-test.sh7 passed, 0 failed (CI had 5 passed, 2 failed).check-uuid-v8.sh --strict(frommetadatastician/standards, pinned7641c7f) has no exemption mechanism and refused three deliberately wrong UUID literals in my tests. The tests now derive each wrong id from a v8 id by changing one nibble (and check that restoring the nibble gives the valid id). I did not touch the estate script. On a clean export, the gate fails on the old commit with exactly those 3 findings and passes on the new one.valid?/1accepting v7, andvalid?/1accepting variantceach fail a test.nickelon PATH: 3713 tests, 0 failures, 246 excluded.Observed, not mine: asciidoctor reports
unterminated table blockinverification/PROOF-STATUS.adoc(line 758 before #1160, 788 now). It is non-fatal and pre-existing. CodeRabbit is rate-limited, so no automated review happened.