Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions docs/operations/e0-closeout/README.adoc
Original file line number Diff line number Diff line change
Expand Up @@ -124,6 +124,7 @@ function name is the stable locator. Measure again before you edit.
|E0-26 |The rescan judges a fix by its category and its file |S |sonnet |$8 |none
|E0-27 |Only BatchRollback can record a rollback_requested row |S |sonnet |$5 |none
|E0-28 |Cross-repo transfer is smoothed and anomalies report false positives |M |sonnet |$8 |none
|E0-29 |The receipt writer refuses what the model refuses |S |sonnet |$8 |none
|===

The caps of `E0-01` to `E0-17` add up to $151. The estimate for that
Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,77 @@
// SPDX-License-Identifier: CC-BY-SA-4.0
// Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) <j.d.a.jewell@open.ac.uk>
= E0-29: The receipt writer refuses what the model refuses
:wo-id: E0-29
:wo-repo: hyperpolymath/hypatia
:wo-size: small
:wo-agent: e0-executor
:wo-model: sonnet
:wo-effort: medium
:wo-cap-usd: 8
:wo-max-turns: 140
:wo-branch: fix/e0-29-receipt-write-refusals
:wo-depends: none

== Goal

`Receipt.write/3` answers an error for an `event_id` that already has a receipt, and
refuses to write a `verified` receipt that has no observation. These are the two
differences between the running writer and the Idris2 model of `E0-10` that the owner
has ruled on.

== Authority

Owner rulings of 2026-11-15 on the review of the pull request of `E0-10` (pull request
1164): 1A, "a duplicate receipt write returns an error"; and 2A, "add the guard in
`Receipt.write`". Related: `docs/design/e0-receipt.adoc`, section 8 (P1 and P2).

== Facts measured

Commit `4de4d69f`, measured on 2026-11-15 on a clean tree.

* Read: `lib/hypatia/receipt.ex`, `write/3`: when `exists?/2` is true the `with` falls to
`true -> :ok`, so a second write for the same `event_id` writes nothing and returns `:ok`.
The model answers `Left DuplicateEventId` (`append` in `src/Hypatia/ABI/Receipt.idr`).
* Read: `build/2` always sets `proof_or_test_ref.row_sha256` and sets `observations` only
from the row. A `verified` row with no hit counts and a source other than a rescan gives
`observations == %{}`. The model cannot build it (`verifiedOk`) and `schema/receipt.ncl`
refuses it. `test/receipt_model_mirror_test.exs` pins both differences as known differences.
* Read: callers of `Receipt.write/3`: `OutcomeTracker.write_receipt/2` and
`Receipt.repair/2` (which checks `exists?/2` first) log `receipt_pending` on an error, and
`FleetDispatcher.write_neural_receipt/4` does the same.
* Read: no production entry point makes a `verified` row without observations (the mirror
test runs every fleet classification).

== Steps

. Measure the facts again. Stop if one no longer holds.
. Write the tests first: (a) a second `write/3` for an `event_id` returns
`{:error, :duplicate_event_id}` and the receipt log is unchanged; (b) `check/1` refuses a
`verified` receipt with no observation and accepts one with an observation and a row
digest, and accepts a receipt that is not `verified`; (c) `write/3` returns
`{:error, :verified_without_evidence}` for such a row and writes nothing; (d) a fleet row
whose producer `event_id` is the id of an existing receipt is stored, its receipt is
refused, and the log says `receipt_refused` and not `receipt_pending`. See them fail.
. Add `Receipt.check/1`. Make `write/3` return the two errors, and stop returning `:ok` for a
duplicate.
. Name a refusal in the log as `receipt_refused`, with the `event_id` and the reason, in the
three callers. A write that failed for another reason stays `receipt_pending`.
. Change the tests that pinned the two differences. Update the trust-boundary text of the P1
and P2 rows of `verification/proof-ledger.jsonl`, the header comment of
`src/Hypatia/ABI/Receipt.idr` and the module doc of the mirror test. Run
`scripts/proof-ledger.sh check` and `render --write`, and `scripts/check-verdicts.sh`.

== Acceptance

* The new tests pass, and (a) to (d) failed before step 3. Give both outputs.
* `mix test` has 0 failures. No file that was formatted before the change is unformatted after it.
* A mutation check: remove the duplicate refusal and test (a) fails; remove the guard and
tests (b) and (c) fail.
* `scripts/check-verdicts.sh`, `scripts/proof-ledger.sh check` and `render --check` pass.

== Stop and ask

* A caller relies on `:ok` for a duplicate.
* A production path makes a `verified` row without an observation. Report it and do not
guard it away.
* The cost reaches the cap before the acceptance checks pass.
2 changes: 1 addition & 1 deletion lib/fleet_dispatcher.ex
Original file line number Diff line number Diff line change
Expand Up @@ -734,7 +734,7 @@ defmodule Hypatia.FleetDispatcher do
:ok
else
{:error, reason} ->
Logger.warning("receipt_pending event_id=#{event_id} reason=#{inspect(reason)}")
Hypatia.Receipt.report_failure(event_id, reason)
end
rescue
error ->
Expand Down
57 changes: 50 additions & 7 deletions lib/hypatia/receipt.ex
Original file line number Diff line number Diff line change
Expand Up @@ -318,8 +318,14 @@ defmodule Hypatia.Receipt do
end

@doc """
Write the receipt of a stored row, once. A second call for the same `event_id`
writes nothing and returns `:ok` (a replay writes no second receipt).
Write the receipt of a stored row, once. It refuses, and writes nothing, in the two
cases that the Idris2 model of `src/Hypatia/ABI/Receipt.idr` refuses (E0-29, owner
rulings 1A and 2A):

* `{:error, :duplicate_event_id}`: the `event_id` already has a receipt (P1; the
model's `Left DuplicateEventId`). A replay writes no second receipt, and says so.
* `{:error, :verified_without_evidence}`: the receipt is `verified` and has no
observation or no row digest (P2; see `check/1`).

`row` is the row as the log holds it. For a row of the local outcome log the row
is looked up by its `event_id` (`{:error, :row_not_in_log}` if it is not there:
Expand All @@ -329,17 +335,54 @@ defmodule Hypatia.Receipt do
@spec write(String.t(), map(), keyword()) :: :ok | {:error, term()}
def write(data_root, row, opts \\ []) when is_binary(data_root) and is_map(row) do
with {:ok, event_id} <- fetch_event_id(row),
false <- exists?(data_root, event_id),
:ok <- not_yet_written(data_root, event_id),
{:ok, ctx} <- context(data_root, row, opts),
receipt = build(row, ctx),
:ok <- check(receipt),
{:ok, line} <- encode(receipt) do
append(data_root, line)
else
true -> :ok
{:error, _reason} = error -> error
end
end

defp not_yet_written(data_root, event_id) do
if exists?(data_root, event_id), do: {:error, :duplicate_event_id}, else: :ok
end

@doc """
A receipt cannot claim more than its evidence (P2 of the design). A `verified`
receipt must have at least one observation and a row digest; the Nickel contract of
`schema/receipt.ncl` and the model's `verifiedOk` say the same. `build/2` builds
whatever the row gives; this is what refuses it before it is written.
"""
@spec check(map()) :: :ok | {:error, :verified_without_evidence}
def check(%{"qualification" => "verified"} = receipt) do
observations = Map.get(receipt, "observations")
digest = get_in(receipt, ["proof_or_test_ref", "row_sha256"])

if is_map(observations) and map_size(observations) > 0 and is_binary(digest) and
Regex.match?(~r/\A[0-9a-f]{64}\z/, digest),
do: :ok,
else: {:error, :verified_without_evidence}
end

def check(receipt) when is_map(receipt), do: :ok

@doc false
# Say what happened to a receipt that was not written. A refusal is final for that
# receipt (the row is stored and the log says why); any other failure is pending and
# is written when the recipe is next recomputed.
def report_failure(event_id, reason)
when reason in [:duplicate_event_id, :verified_without_evidence] do
Logger.warning(
"receipt_refused event_id=#{event_id} reason=#{inspect(reason)}: the row is stored; " <>
"no receipt is written for it"
)
end

def report_failure(event_id, reason) do
Logger.warning("receipt_pending event_id=#{event_id} reason=#{inspect(reason)}")
end

defp fetch_event_id(row) do
case Map.get(row, "event_id") do
id when is_binary(id) ->
Expand Down Expand Up @@ -476,7 +519,7 @@ defmodule Hypatia.Receipt do
{written + 1, failed}

{:error, reason} ->
Logger.warning("receipt_pending event_id=#{id} reason=#{inspect(reason)}")
report_failure(id, reason)
{written, failed + 1}
end
end
Expand Down
4 changes: 1 addition & 3 deletions lib/outcome_tracker.ex
Original file line number Diff line number Diff line change
Expand Up @@ -376,9 +376,7 @@ defmodule Hypatia.OutcomeTracker do
:ok

{:error, reason} ->
Logger.warning(
"receipt_pending event_id=#{Map.get(record, "event_id")} reason=#{inspect(reason)}"
)
Hypatia.Receipt.report_failure(Map.get(record, "event_id"), reason)
end
rescue
error ->
Expand Down
10 changes: 6 additions & 4 deletions src/Hypatia/ABI/Receipt.idr
Original file line number Diff line number Diff line change
Expand Up @@ -33,10 +33,12 @@
-- NAME. This module proves neither. It has no retraction: a withdrawal is a
-- revision (an appended receipt with verdict `Withdrawn` and a parent), so what
-- is proved here is about the append, by event_id.
-- * The runtime `Receipt.write` does not return an error for a duplicate
-- event_id: it writes nothing and returns :ok (an idempotent replay). The
-- model's `Left DuplicateEventId` is "the ledger is unchanged"; that is the
-- property, and the return value is a difference.
-- * The runtime `Receipt.write` answers `{:error, :duplicate_event_id}` for a
-- duplicate event_id and writes nothing, as the model's `Left DuplicateEventId`
-- (E0-29, owner ruling 1A; before it, the writer returned :ok). It also
-- refuses a verified receipt with no observation (`Receipt.check/1`, ruling
-- 2A), as `verifiedOk` makes the model unable to build one. `Receipt.build/2`
-- is still not a smart constructor: it builds the receipt, `check/1` refuses it.
--
-- The gate table `gate` is the table of `verdict_for` in schema/receipt.ncl, which
-- is the one-row case of OutcomeTracker.qualified_outcome_counts/1.
Expand Down
40 changes: 20 additions & 20 deletions test/receipt_model_mirror_test.exs
Original file line number Diff line number Diff line change
Expand Up @@ -15,16 +15,15 @@ defmodule Hypatia.ReceiptModelMirrorTest do
The gate table and the list of fields are READ FROM `Receipt.idr`, not copied,
so the model and this test cannot drift apart without a failure.

Two differences between the model and the run time are pinned below as
tests of their own, so that a change to either is noticed:

* `Receipt.write/3` of an event_id that has a receipt writes nothing and
returns `:ok`; the model's `append` answers `Left DuplicateEventId`. The
ledger is unchanged in both, which is the property.
* `Receipt.build/2` does not refuse a `verified` row that has no
observations. The model cannot build one (`verifiedOk`), and the Nickel
contract refuses it. The production entry points never make one (see the
P2 tests); `build/2` is not a smart constructor.
Since E0-29 (owner rulings 1A and 2A) the writer refuses what the model refuses:

* `Receipt.write/3` of an event_id that has a receipt returns
`{:error, :duplicate_event_id}` and writes nothing, as the model's `append`
answers `Left DuplicateEventId`.
* `Receipt.write/3` refuses a `verified` receipt that has no observation, as the
model cannot build one (`verifiedOk`) and the Nickel contract refuses it.
`Receipt.build/2` itself is still not a smart constructor: it builds the
receipt, and `Receipt.check/1` is what refuses it.
"""
use ExUnit.Case, async: true

Expand Down Expand Up @@ -256,16 +255,16 @@ defmodule Hypatia.ReceiptModelMirrorTest do
assert receipt["proof_or_test_ref"]["row_sha256"] =~ ~r/\A[0-9a-f]{64}\z/
end

test "KNOWN DIFFERENCE: build/2 does not refuse a verified row with no observation" do
test "build/2 still builds a verified row with no observation; check/1 and write/3 refuse it" do
receipt = Receipt.build(row("QVerified", "CSuccess"), @ctx)

# The model cannot build this (`verifiedOk`) and the Nickel contract refuses
# it ("qualification verified needs observations and an evidence reference").
# No production entry point makes such a row; build/2 is not a smart
# constructor. If build/2 or write/3 gains a guard, change this test and the
# trust-boundary text of the P2 row in verification/proof-ledger.jsonl.
# build/2 is not a smart constructor, so it still builds it; the writer does
# not write it (E0-29, owner ruling 2A).
assert receipt["qualification"] == "verified"
assert receipt["observations"] == %{}
assert {:error, :verified_without_evidence} = Receipt.check(receipt)
end
end

Expand Down Expand Up @@ -366,7 +365,7 @@ defmodule Hypatia.ReceiptModelMirrorTest do
{:ok, root: root}
end

test "a second write for an event_id adds nothing, and returns :ok (a known difference)", %{
test "a second write for an event_id adds nothing, and is an error, as in the model", %{
root: root
} do
row = row("QFailed", "CFailure")
Expand All @@ -375,19 +374,20 @@ defmodule Hypatia.ReceiptModelMirrorTest do
before = Receipt.all(root)
assert length(before) == 1

# The model answers Left DuplicateEventId; the run time returns :ok and
# leaves the ledger as it was.
assert :ok = Receipt.write(root, row, ctx: @ctx)
# The model answers Left DuplicateEventId; so does the writer (E0-29, ruling 1A).
assert {:error, :duplicate_event_id} = Receipt.write(root, row, ctx: @ctx)
assert Receipt.all(root) == before
end

test "many receipts keep distinct event_ids, and a replay of any of them adds nothing", %{
test "many receipts keep distinct event_ids, and a replay of any of them is refused", %{
root: root
} do
rows = for _ <- 1..40, do: row("QFailed", "CFailure")

for r <- rows, do: assert(:ok = Receipt.write(root, r, ctx: @ctx))
for r <- Enum.take_random(rows, 15), do: assert(:ok = Receipt.write(root, r, ctx: @ctx))

for r <- Enum.take_random(rows, 15),
do: assert({:error, :duplicate_event_id} = Receipt.write(root, r, ctx: @ctx))

ids = Receipt.all(root) |> Enum.map(& &1["event_id"])
assert length(ids) == 40
Expand Down
Loading
Loading