From 2bf46b955701ef5b6c61e96bd338e6ea6973375d Mon Sep 17 00:00:00 2001 From: e0-agent Date: Sun, 15 Nov 2026 13:22:50 +0000 Subject: [PATCH 1/2] feat(receipt): one receipt for each learning update, with a Nickel contract (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 --- lib/fleet_dispatcher.ex | 43 ++ lib/hypatia/event_id.ex | 95 +++ lib/hypatia/receipt.ex | 491 ++++++++++++++ lib/learning_scheduler.ex | 20 +- lib/outcome_tracker.ex | 90 ++- schema/receipt.ncl | 200 ++++++ test/event_id_test.exs | 75 +++ test/fixtures/receipt/e0-receipt-line.jsonl | 1 + test/receipt_test.exs | 695 ++++++++++++++++++++ 9 files changed, 1703 insertions(+), 7 deletions(-) create mode 100644 lib/hypatia/event_id.ex create mode 100644 lib/hypatia/receipt.ex create mode 100644 schema/receipt.ncl create mode 100644 test/event_id_test.exs create mode 100644 test/fixtures/receipt/e0-receipt-line.jsonl create mode 100644 test/receipt_test.exs diff --git a/lib/fleet_dispatcher.ex b/lib/fleet_dispatcher.ex index ae5cdc95..4253e199 100644 --- a/lib/fleet_dispatcher.ex +++ b/lib/fleet_dispatcher.ex @@ -699,6 +699,48 @@ defmodule Hypatia.FleetDispatcher do # place for it is this function. defp trusted_verification(_finding), do: nil + # The receipt of a neural learning update (E0-09, owner ruling D2). The evidence + # is the qualified outcome that was handed to the coordinator; there is no row + # in a log, so the receipt names the digest of that evidence in canonical form. + # It never raises: a receipt that cannot be written is logged as receipt_pending. + # There is no row to rebuild it from, so nothing repairs it later. + defp write_neural_receipt(pattern, repo, outcome, verification) do + data_root = Path.expand(Hypatia.Paths.verisimdb_data()) + + evidence = %{ + "file" => ".", + "outcome" => outcome, + "recipe_id" => pattern, + "repo" => repo, + "verification" => verification + } + + event_id = Hypatia.EventId.generate() + + with {:ok, bytes} <- Hypatia.Receipt.encode(evidence), + row = + Map.merge(evidence, %{ + "event_id" => event_id, + "event_id_source" => "hypatia", + "source_kind" => "neural_path" + }), + ctx = %{ + kind: :neural_path, + log: "neural/outcome-queue", + line: "0", + row_sha256: :crypto.hash(:sha256, bytes) |> Base.encode16(case: :lower) + }, + :ok <- Hypatia.Receipt.write(data_root, row, ctx: ctx) do + :ok + else + {:error, reason} -> + Logger.warning("receipt_pending event_id=#{event_id} reason=#{inspect(reason)}") + end + rescue + error -> + Logger.warning("receipt_pending reason=#{Exception.message(error)}") + end + # :queued records a volatile source-bound submission, never completed learning. @doc false def record_neural_outcome(finding, outcome, server \\ Hypatia.Neural.Coordinator) do @@ -766,6 +808,7 @@ defmodule Hypatia.FleetDispatcher do "verification" => verification }) do record_neural_outcome(finding, outcome_str, server) + write_neural_receipt(to_string(pattern), to_string(repo), outcome_str, verification) else Logger.info( "Learning loop: outcome for pattern '#{pattern}' in #{repo} not learned: " <> diff --git a/lib/hypatia/event_id.ex b/lib/hypatia/event_id.ex new file mode 100644 index 00000000..581cc0ac --- /dev/null +++ b/lib/hypatia/event_id.ex @@ -0,0 +1,95 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +defmodule Hypatia.EventId do + @moduledoc """ + The identity of an event: an ADR-008 version 8 identifier under profile T + (the time-ordered profile), written by Hypatia itself (owner ruling R5-A of + 2026-11-15, `docs/design/e0-receipt.adoc`). It makes no call to an external + command, so there is no tool that can be missing. + + The layout is the one ADR-008 fixes (`metadatastician/standards`, + `docs/decisions/ADR-008-uuid-v8-estate-standard.adoc`): + + 48 bits unix_ts_ms big-endian Unix epoch milliseconds + 4 bits ver 0b1000 (8) + 12 bits rand_a a counter that makes ids increase within a millisecond + 2 bits var 0b10 + 62 bits rand_b from a cryptographic random source + + The text is lowercase `8-4-4-4-12`. The field that holds an `event_id` + declares profile T. The timestamp is never an audited event time and never a + basis for authorisation (ADR-008). + + The counter is shared by the whole node (an `:atomics` word that holds the + millisecond and the counter together), so ids increase within one process and + are distinct across processes. If the clock goes backwards, ids keep + increasing: the counter carries into the millisecond instead. + """ + + import Bitwise + + @key {__MODULE__, :state} + @text ~r/\A[0-9a-f]{8}-[0-9a-f]{4}-8[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/ + + @doc "Mint an id: lowercase `8-4-4-4-12` text, version 8, variant `10`, profile T." + @spec generate() :: String.t() + def generate do + packed = next_packed() + ms = packed >>> 12 + counter = packed &&& 0xFFF + <> = :crypto.strong_rand_bytes(8) + + format(<>) + end + + @doc "The 16 bytes of an id in the text form." + @spec to_binary(String.t()) :: <<_::128>> + def to_binary(text) when is_binary(text) do + text |> String.replace("-", "") |> Base.decode16!(case: :lower) + end + + @doc "Is this a valid `event_id`: a string in the text form, version 8, variant `10`?" + @spec valid?(term()) :: boolean() + def valid?(text) when is_binary(text), do: Regex.match?(@text, text) + def valid?(_other), do: false + + # The shared word holds `(milliseconds << 12) | counter`. A new millisecond + # resets the counter; the same or an earlier one adds 1, which carries into the + # millisecond when the 12 bits overflow, so the value only ever increases. + defp next_packed do + ref = state() + now = System.system_time(:millisecond) <<< 12 + advance(ref, now) + end + + defp advance(ref, now) do + current = :atomics.get(ref, 1) + next = if now > current, do: now, else: current + 1 + + case :atomics.compare_exchange(ref, 1, current, next) do + :ok -> next + _changed -> advance(ref, now) + end + end + + defp state do + case :persistent_term.get(@key, nil) do + nil -> + ref = :atomics.new(1, signed: false) + :persistent_term.put(@key, ref) + :persistent_term.get(@key) + + ref -> + ref + end + end + + defp format( + <> + ) do + [a, b, c, d, e] + |> Enum.map_join("-", &Base.encode16(&1, case: :lower)) + end +end diff --git a/lib/hypatia/receipt.ex b/lib/hypatia/receipt.ex new file mode 100644 index 00000000..b608c172 --- /dev/null +++ b/lib/hypatia/receipt.ex @@ -0,0 +1,491 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) + +defmodule Hypatia.Receipt do + @moduledoc """ + The E0 receipt (`docs/design/e0-receipt.adoc`, RULED 2026-11-15; contract + `schema/receipt.ncl`). + + A receipt says: this event changed what a learner holds, and here is the exact + evidence that it rested on. It is an index into the log that is kept: it names a + row by its `event_id` and the digest of its bytes, never a count. It is + append-only. A receipt is a pure function of the stored row (and of where the row + sits in its log), so a missing receipt can be written again later, identically. + + ## Order of writes (design section 5.3) + + The log row is the commit of the event. A receipt is written only for a row that + is in the log: `write/3` refuses a row it cannot find. A failed receipt write + never hides a committed event from the caller; `OutcomeTracker.persist_outcome/6` + logs `receipt_pending` and `repair/2` writes the receipt the next time the recipe + is recomputed. + + ## Canonical form (design section 6) + + One receipt on each line of `receipts/YYYY-MM.jsonl` under the data root of the + row. Keys sorted, no whitespace, one final LF, ASCII only, no JSON numbers: the + profile of `scripts/proof-ledger.sh`, in which `jq -cS` is the canonical form. A + field that holds text outside printable ASCII is written with `%XX` for each + such byte (and for `%` itself), so that the receipt stays ASCII and can be + decoded again. + + `receipt_sha256` is the SHA-256 (lowercase hex) of the canonical form of all the + other fields, so no field can change without the digest changing. + """ + + require Logger + + alias Hypatia.EventId + alias Hypatia.OutcomeTracker + + @chain_version "e0-receipt/1" + @fleet_log "shared-context/learning/fix-outcomes.jsonl" + @rescans ~w(verified still_present scan_failed scan_skipped) + @qualifications ~w(verified failed incomplete still_present) + + # ── Building ─────────────────────────────────────────────────────────── + + @doc """ + Build the receipt of a stored row. + + `row` is the row as the log holds it (string keys, with an `event_id`). `ctx` says + where the evidence sits: `:kind`, `:log` (a path relative to the data root, or a + label for a source that is not a file), `:line` (a decimal string) and + `:row_sha256` (the digest of the exact evidence bytes). + """ + @spec build(map(), map()) :: map() + def build(row, ctx) when is_map(row) and is_map(ctx) do + event_id = Map.fetch!(row, "event_id") + kind = ctx.kind + verdict = verdict_of(row) + observations = observations(row, kind) + + proof_or_test_ref = %{"row_sha256" => ctx.row_sha256} + + provenance = %{ + "event_id_source" => event_id_source(row), + "producer" => ascii(producer(row, kind)), + "writer" => "hypatia" + } + + present = fn map, key -> Map.has_key?(map, key) end + + missing = + (["head_sha", "match_kind", "pattern_id", "subject_id", "subject_identity"] ++ + for( + key <- ~w(after_hits before_hits exit_code rescan verdict), + not present.(observations, key), + do: key + ) ++ + ["scan_digest", "test_digest", "tool_version"]) + |> Enum.sort() + |> Enum.uniq() + + body = %{ + "assertion" => %{ + "claimed_outcome" => claimed_outcome(row), + "file" => ascii(to_text(Map.get(row, "file", ""))), + "recipe_id" => ascii(to_text(Map.get(row, "recipe_id", ""))), + "repo" => ascii(to_text(Map.get(row, "repo", ""))) + }, + "chain_version" => @chain_version, + "event_id" => event_id, + "missing_evidence" => missing, + "observations" => observations, + "parent_event_ids" => [], + "proof_or_test_ref" => proof_or_test_ref, + "provenance" => provenance, + "qualification" => qualification_of(row, verdict), + "source" => %{"kind" => Atom.to_string(kind), "line" => ctx.line, "log" => ctx.log}, + "verdict" => verdict + } + + {:ok, digest} = digest(body) + Map.put(body, "receipt_sha256", digest) + end + + # What the single gate does with the row. + defp verdict_of(row) do + case OutcomeTracker.qualified_outcome_counts([row]) do + %{successes: 1} -> "credited_success" + %{failures: 1} -> "credited_failure" + %{false_positives: 1} -> "credited_false_positive" + _ -> "audit_only" + end + end + + # The verification as the gate reads it. A rollback that the gate does not credit + # (no batch fields) is "unqualified", so the verdict can be derived from the pair. + defp qualification_of(row, verdict) do + case Map.get(row, "verification") do + v when v in @qualifications -> v + "rollback_requested" when verdict == "credited_false_positive" -> "rollback_requested" + _ -> "unqualified" + end + end + + defp claimed_outcome(row) do + case Map.get(row, "outcome") do + o when o in ["success", "failure", "false_positive"] -> o + _ -> "unknown" + end + end + + # Only a non-negative integer is an observation; anything else is absent and is + # named in missing_evidence. + defp observations(row, kind) do + hits = + for key <- ~w(after_hits before_hits exit_code), + value = Map.get(row, key), + is_integer(value) and value >= 0, + into: %{}, + do: {key, Integer.to_string(value)} + + base = + case Map.get(row, "verdict") do + v when is_binary(v) -> Map.put(hits, "verdict", ascii(v)) + _ -> hits + end + + case {kind, Map.get(row, "verification")} do + {:local_rescan, v} when v in @rescans -> Map.put(base, "rescan", v) + _ -> base + end + end + + defp producer(row, :fleet_import), do: to_text(Map.get(row, "source_bot", "unknown")) + defp producer(_row, _kind), do: "hypatia" + + defp event_id_source(row) do + if Map.get(row, "event_id_source") == "producer", do: "producer", else: "hypatia" + end + + defp to_text(value) when is_binary(value), do: value + defp to_text(nil), do: "" + defp to_text(value) when is_atom(value), do: Atom.to_string(value) + defp to_text(value), do: inspect(value) + + # Printable ASCII stays; every other byte, and "%", becomes %XX. + @doc false + def ascii(text) when is_binary(text) do + for <>, into: "" do + if byte >= 0x20 and byte <= 0x7E and byte != ?% do + <> + else + "%" <> String.upcase(Base.encode16(<>)) + end + end + end + + # ── Encoding ─────────────────────────────────────────────────────────── + + @doc """ + The canonical line of a receipt (no final LF): keys sorted, no whitespace, ASCII + only, no numbers. `{:error, reason}` for a value that is not allowed. + """ + @spec encode(map()) :: {:ok, binary()} | {:error, term()} + def encode(value) do + {:ok, encode!(value)} + catch + {:not_canonical, reason} -> {:error, {:not_canonical, reason}} + end + + defp encode!(map) when is_map(map) do + body = + map + |> Enum.map(fn {k, v} when is_binary(k) -> {k, encode!(v)} end) + |> Enum.sort_by(&elem(&1, 0)) + |> Enum.map_join(",", fn {k, v} -> string!(k) <> ":" <> v end) + + "{" <> body <> "}" + end + + defp encode!(list) when is_list(list), do: "[" <> Enum.map_join(list, ",", &encode!/1) <> "]" + defp encode!(text) when is_binary(text), do: string!(text) + defp encode!(other), do: throw({:not_canonical, {:not_a_string_array_or_object, other}}) + + defp string!(text) do + escaped = + for <>, into: "" do + case byte do + ?" -> + "\\\"" + + ?\\ -> + "\\\\" + + ?\b -> + "\\b" + + ?\t -> + "\\t" + + ?\n -> + "\\n" + + ?\f -> + "\\f" + + ?\r -> + "\\r" + + b when b < 0x20 -> + "\\u" <> String.downcase(String.pad_leading(Integer.to_string(b, 16), 4, "0")) + + b when b > 0x7E -> + throw({:not_canonical, {:not_ascii, text}}) + + b -> + <> + end + end + + "\"" <> escaped <> "\"" + end + + defp digest(body_without_digest) do + with {:ok, line} <- encode(body_without_digest) do + {:ok, :crypto.hash(:sha256, line) |> Base.encode16(case: :lower)} + end + end + + # ── Storage ──────────────────────────────────────────────────────────── + + @doc "The receipt file of a month: `receipts/YYYY-MM.jsonl` under the data root." + def path(data_root, %Date{year: year, month: month}) do + month = String.pad_leading(Integer.to_string(month), 2, "0") + Path.join([data_root, "receipts", "#{year}-#{month}.jsonl"]) + end + + @doc "Does a receipt for this `event_id` exist under the data root?" + @spec exists?(String.t(), String.t()) :: boolean() + def exists?(data_root, event_id) do + needle = ~s("event_id":"#{event_id}") + + data_root + |> receipt_files() + |> Enum.any?(fn file -> + file + |> File.stream!() + |> Enum.any?(fn line -> + String.contains?(line, needle) and + match?({:ok, %{"event_id" => ^event_id}}, Jason.decode(line)) + end) + end) + end + + @doc "All receipts under the data root, oldest file first." + def all(data_root) do + for file <- receipt_files(data_root), + line <- file |> File.read!() |> String.split("\n", trim: true), + do: Jason.decode!(line) + end + + defp receipt_files(data_root) do + dir = Path.join(data_root, "receipts") + + case File.ls(dir) do + {:ok, names} -> + names + |> Enum.filter(&String.ends_with?(&1, ".jsonl")) + |> Enum.sort() + |> Enum.map(&Path.join(dir, &1)) + + {:error, _} -> + [] + end + 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). + + `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: + a receipt is never written before its row). `opts` may carry `:ctx` for a source + that is not in the log (the neural path). + """ + @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, ctx} <- context(data_root, row, opts), + receipt = build(row, ctx), + {:ok, line} <- encode(receipt) do + append(data_root, line) + else + true -> :ok + {:error, _reason} = error -> error + end + end + + defp fetch_event_id(row) do + case Map.get(row, "event_id") do + id when is_binary(id) -> + if EventId.valid?(id), do: {:ok, id}, else: {:error, :invalid_event_id} + + _ -> + {:error, :no_event_id} + end + end + + defp append(data_root, line) do + path = path(data_root, Date.utc_today()) + + with :ok <- File.mkdir_p(Path.dirname(path)) do + File.write(path, line <> "\n", [:append, :utf8]) + end + end + + # ── Context: where the evidence sits ─────────────────────────────────── + + defp context(data_root, row, opts) do + case Keyword.fetch(opts, :ctx) do + {:ok, ctx} -> {:ok, ctx} + :error -> context_from_row(data_root, row) + end + end + + defp context_from_row(data_root, row) do + case source_kind(row) do + :fleet_import -> + {:ok, + %{ + kind: :fleet_import, + log: @fleet_log, + line: decimal(Map.get(row, "source_line")), + row_sha256: digest_or_row(row, data_root) + }} + + kind -> + case locate(data_root, Map.fetch!(row, "event_id")) do + {:ok, log, line, bytes} -> + {:ok, %{kind: kind, log: log, line: Integer.to_string(line), row_sha256: sha(bytes)}} + + :error -> + {:error, :row_not_in_log} + end + end + end + + defp source_kind(row) do + case Map.get(row, "source_kind") do + "fleet_import" -> :fleet_import + "local_rescan" -> :local_rescan + "neural_path" -> :neural_path + "local_caller" -> :local_caller + _ -> if Map.get(row, "origin") == "gitbot-fleet", do: :fleet_import, else: :local_caller + end + end + + defp decimal(value) when is_binary(value) do + if Regex.match?(~r/\A[0-9]+\z/, value), do: value, else: "0" + end + + defp decimal(_), do: "0" + + # The digest of the SOURCE row if the import recorded it; else of the stored row. + defp digest_or_row(row, data_root) do + case Map.get(row, "source_row_sha256") do + d when is_binary(d) and byte_size(d) == 64 -> + d + + _ -> + case locate(data_root, Map.fetch!(row, "event_id")) do + {:ok, _log, _line, bytes} -> sha(bytes) + :error -> sha(Jason.encode!(row)) + end + end + end + + defp sha(bytes), do: :crypto.hash(:sha256, bytes) |> Base.encode16(case: :lower) + + # Find the line of the outcome log that holds this event: {relative log path, + # line number, exact line bytes}. + @doc false + def locate(data_root, event_id) do + dir = Path.join(data_root, "outcomes") + needle = ~s("event_id":"#{event_id}") + + case File.ls(dir) do + {:ok, names} -> + names + |> Enum.filter(&String.ends_with?(&1, ".jsonl")) + |> Enum.sort() + |> Enum.find_value(:error, fn name -> + dir + |> Path.join(name) + |> File.stream!() + |> Stream.with_index(1) + |> Enum.find_value(fn {line, number} -> + line = String.trim_trailing(line, "\n") + if String.contains?(line, needle), do: {:ok, "outcomes/" <> name, number, line} + end) + end) + + {:error, _} -> + :error + end + end + + # ── Repair ───────────────────────────────────────────────────────────── + + @doc """ + Write the receipt of every row of a recipe that has an `event_id` and no receipt. + Rows with no `event_id` (written before E0-09) get none: nothing is back-filled. + Returns `{written, failed}`. A receipt whose `event_id` has no row in the log is + not touched; `orphans/1` reports it. + """ + @spec repair(String.t(), String.t()) :: {non_neg_integer(), non_neg_integer()} + def repair(data_root, recipe_id) do + rows_of_recipe(data_root, recipe_id) + |> Enum.reduce({0, 0}, fn row, {written, failed} -> + id = Map.get(row, "event_id") + + cond do + not is_binary(id) -> + {written, failed} + + exists?(data_root, id) -> + {written, failed} + + true -> + case write(data_root, row) do + :ok -> + {written + 1, failed} + + {:error, reason} -> + Logger.warning("receipt_pending event_id=#{id} reason=#{inspect(reason)}") + {written, failed + 1} + end + end + end) + end + + defp rows_of_recipe(data_root, recipe_id) do + dir = Path.join(data_root, "outcomes") + + case File.ls(dir) do + {:ok, names} -> + for name <- names |> Enum.filter(&String.ends_with?(&1, ".jsonl")) |> Enum.sort(), + line <- dir |> Path.join(name) |> File.stream!(), + String.contains?(line, recipe_id), + {:ok, %{"recipe_id" => ^recipe_id} = row} <- [ + Jason.decode(String.trim_trailing(line, "\n")) + ], + do: row + + {:error, _} -> + [] + end + end + + @doc "Event ids that have a receipt and no row in the outcome log (corrupt, reported loudly)." + @spec orphans(String.t()) :: [String.t()] + def orphans(data_root) do + for %{"event_id" => id, "source" => %{"kind" => kind}} <- all(data_root), + kind in ["local_rescan", "local_caller", "fleet_import"], + locate(data_root, id) == :error, + do: id + end +end diff --git a/lib/learning_scheduler.ex b/lib/learning_scheduler.ex index 8cd9dc38..21075f85 100644 --- a/lib/learning_scheduler.ex +++ b/lib/learning_scheduler.ex @@ -820,6 +820,24 @@ defmodule Hypatia.LearningScheduler do defp audit_outcome("failure"), do: :failure defp audit_outcome(_other), do: :unknown + # What the receipt of a fleet row needs (E0-09): the audit fields of the source row + # and where the evidence sits: its line number, the digest of its exact bytes and + # the bot that wrote it. The row is stored with them, so the receipt can be + # written again identically. + defp fleet_receipt_context(record, line, line_number) do + bot = + case Map.get(record, "bot") do + b when is_binary(b) -> b + _ -> "unknown" + end + + Map.merge(fleet_audit_fields(record), %{ + "source_line" => Integer.to_string(line_number), + "source_row_sha256" => :crypto.hash(:sha256, line) |> Base.encode16(case: :lower), + "source_bot" => bot + }) + end + # The audit fields of a source row that a stored fleet row keeps. defp fleet_audit_fields(record) when is_map(record) do Map.take(record, ["verdict", "exit_code", "before_hits", "after_hits"]) @@ -935,7 +953,7 @@ defmodule Hypatia.LearningScheduler do outcome, id, verification, - fleet_audit_fields(record) + fleet_receipt_context(record, line, line_number) ) do # An audit row is stored and acknowledged, and it is not # counted as a processed outcome. diff --git a/lib/outcome_tracker.ex b/lib/outcome_tracker.ex index d7e721b5..a6aed60c 100644 --- a/lib/outcome_tracker.ex +++ b/lib/outcome_tracker.ex @@ -24,6 +24,19 @@ defmodule Hypatia.OutcomeTracker do # without this marker are NOT trusted even if the counts happen to match. @annealing_evidence_version 1 + # The fields that tie a row to its receipt (design section 3, E0-09). They are + # set by Hypatia, or by the trusted fleet import, never by a caller of the public + # entry: a caller who could choose an `event_id` could make the receipt of a + # later event look like a replay, and no receipt would be written for it. + @receipt_context_keys [ + "event_id", + "event_id_source", + "source_kind", + "source_line", + "source_row_sha256", + "source_bot" + ] + @doc """ Record an outcome from a fix attempt. @@ -48,8 +61,12 @@ defmodule Hypatia.OutcomeTracker do repo, file, outcome, - metadata |> canonical_fields() |> untrusted_verification(), - true + metadata + |> canonical_fields() + |> untrusted_verification() + |> Map.drop(@receipt_context_keys), + true, + :local_caller ) end @@ -164,7 +181,8 @@ defmodule Hypatia.OutcomeTracker do "origin" => "gitbot-fleet", "verification" => verification }), - false + false, + :fleet_import ) end @@ -221,7 +239,15 @@ defmodule Hypatia.OutcomeTracker do end) end - defp persist_outcome(recipe_id, repo, file, outcome, metadata, publish_to_fleet?) do + defp persist_outcome( + recipe_id, + repo, + file, + outcome, + metadata, + publish_to_fleet?, + kind \\ :local_caller + ) do store = capture_outcome_store() now = DateTime.utc_now() |> DateTime.to_iso8601() outcome_str = Atom.to_string(outcome) @@ -236,10 +262,17 @@ defmodule Hypatia.OutcomeTracker do "bot" => "hypatia" } - record = Map.merge(metadata, base) + record = metadata |> Map.merge(base) |> with_event_identity(kind) case write_outcome_log(record, store) do :ok -> + # The row is the commit of the event; its receipt is written next, into the + # store that the row was written into, and before the derived updates. A + # failed receipt write never hides the committed event from the caller: it + # is logged as receipt_pending and written when the recipe is next + # recomputed (`update_recipe_confidence/1`). + write_receipt(store, record) + if publish_to_fleet?, do: write_fleet_outcome(record) if qualified_outcome?(record) do @@ -285,6 +318,50 @@ defmodule Hypatia.OutcomeTracker do end end + # Every row carries the identity of its event and where it came from. The id is + # minted by Hypatia (profile T, `Hypatia.EventId`). Only the trusted fleet import + # may bring a producer's id, and only a valid one. + defp with_event_identity(record, kind) do + producer_id = Map.get(record, "event_id") + + {id, source} = + if kind == :fleet_import and Hypatia.EventId.valid?(producer_id), + do: {producer_id, "producer"}, + else: {Hypatia.EventId.generate(), "hypatia"} + + record + |> Map.put("event_id", id) + |> Map.put("event_id_source", source) + |> Map.put("source_kind", Atom.to_string(kind)) + end + + defp write_receipt(store, record) do + case Hypatia.Receipt.write(store.data_root, record) do + :ok -> + :ok + + {:error, reason} -> + Logger.warning( + "receipt_pending event_id=#{Map.get(record, "event_id")} reason=#{inspect(reason)}" + ) + end + rescue + error -> + Logger.warning( + "receipt_pending event_id=#{Map.get(record, "event_id")} reason=#{Exception.message(error)}" + ) + end + + # Write the receipts that a failed write left missing, into the store that the + # recipe is recomputed in. It never raises. + defp repair_receipts(recipe_id) do + store = capture_outcome_store() + Hypatia.Receipt.repair(store.data_root, recipe_id) + rescue + error -> + Logger.warning("receipt repair failed for #{recipe_id}: #{Exception.message(error)}") + end + # A row that the fleet import stored without qualifying it. defp fleet_audit_row?(record) do Map.get(record, "origin") == "gitbot-fleet" and not qualified_outcome?(record) @@ -559,7 +636,7 @@ defmodule Hypatia.OutcomeTracker do # The one path that may stamp "verified": `record_and_verify/5` calls it only # after `verify_fix/3` found the weak point of a named category gone. defp record_rescanned_outcome(recipe_id, repo, file, outcome, metadata) do - persist_outcome(recipe_id, repo, file, outcome, metadata, true) + persist_outcome(recipe_id, repo, file, outcome, metadata, true, :local_rescan) end @doc """ @@ -574,6 +651,7 @@ defmodule Hypatia.OutcomeTracker do but cannot redirect that operation to B. """ def update_recipe_confidence(recipe_id) do + repair_receipts(recipe_id) update_recipe_confidence(recipe_id, fn -> :ok end) end diff --git a/schema/receipt.ncl b/schema/receipt.ncl new file mode 100644 index 00000000..02f9dde2 --- /dev/null +++ b/schema/receipt.ncl @@ -0,0 +1,200 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# Hypatia E0 receipt schema: the contract of one receipt line +# (receipts/YYYY-MM.jsonl). The design is docs/design/e0-receipt.adoc +# (RULED 2026-11-15); this file transcribes its field table and its rules. +# +# A receipt says: this event changed what a learner holds, and here is the exact +# evidence that it rested on. It names a row by id and never a count. The +# contract refuses a receipt that claims more than its evidence: +# +# * `verdict` is DERIVED. It must be the answer of the single gate +# (OutcomeTracker.qualified_outcome_counts/1) for the claimed outcome and the +# qualification, so a receipt cannot call an ignored row a credited one. +# `withdrawn` is the one other value and needs a parent receipt. +# * `qualification` "verified" needs an evidence reference and observations. +# * `missing_evidence` is EXACT: a field that is absent is named, and a field +# that is named is absent. An empty list does not mean "complete", it means +# nothing is known to be missing. +# * No JSON number occurs anywhere (the profile of scripts/proof-ledger.sh, in +# which `jq -cS` is the canonical form): counts and hit numbers are decimal +# strings. +# +# Check a file: scripts/check-receipt-schema.sh +# Self-test: scripts/check-receipt-schema.sh --self-test + +let one_of = fun allowed => + std.contract.from_predicate (fun value => std.array.elem value allowed) +in + +let sha256_c = + std.contract.from_predicate (fun s => std.is_string s && std.string.is_match "^[0-9a-f]{64}$" s) +in + +# ADR-008: version 8, variant 10, lowercase 8-4-4-4-12. +let event_id_c = + std.contract.from_predicate (fun s => + std.is_string s + && std.string.is_match "^[0-9a-f]{8}-[0-9a-f]{4}-8[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" s) +in + +let decimal_c = + std.contract.from_predicate (fun s => std.is_string s && std.string.is_match "^[0-9]+$" s) +in + +# A path relative to the data root, with no way out of it. +let rel_path_c = + std.contract.from_predicate (fun s => + std.is_string s + && std.string.is_match "^[A-Za-z0-9_.-]+(/[A-Za-z0-9_.-]+)*$" s + && !(std.string.contains ".." s)) +in + +let ascii_c = + std.contract.from_predicate (fun s => std.is_string s && std.string.is_match "^[ -~]*$" s) +in + +let qualification_c = + one_of ["verified", "failed", "incomplete", "still_present", "rollback_requested", "unqualified"] +in + +let verdict_c = + one_of ["credited_success", "credited_failure", "credited_false_positive", "audit_only", "withdrawn"] +in + +let claimed_outcome_c = one_of ["success", "failure", "false_positive", "unknown"] in + +let source_kind_c = one_of ["fleet_import", "local_rescan", "local_caller", "neural_path"] in + +let event_id_source_c = one_of ["producer", "hypatia"] in + +let rescan_c = one_of ["verified", "still_present", "scan_failed", "scan_skipped"] in + +# The closed set of names that missing_evidence can hold. +let missing_names = [ + "after_hits", "before_hits", "event_id", "exit_code", "head_sha", "match_kind", "pattern_id", + "rescan", "scan_digest", "subject_id", "subject_identity", "test_digest", "tool_version", + "verdict", +] in + +let sorted_unique = fun arr => + let cmp = fun a b => + if a == b then 'Equal else if (std.string.compare a b) == 'Lesser then 'Lesser else 'Greater + in + let seen = std.array.fold_left (fun acc x => if std.array.elem x acc then acc else acc @ [x]) [] arr in + (std.array.sort cmp arr) == arr && (std.array.length seen) == (std.array.length arr) +in + +let sorted_unique_c = std.contract.from_predicate (fun arr => std.is_array arr && sorted_unique arr) in + +let missing_evidence_c = + std.contract.from_predicate (fun arr => + std.is_array arr + && sorted_unique arr + && std.array.all (fun x => std.array.elem x missing_names) arr) +in + +let parent_ids_c = + std.contract.from_predicate (fun arr => + std.is_array arr + && sorted_unique arr + && std.array.all (fun x => std.is_string x && std.string.is_match "^[0-9a-f]{8}-[0-9a-f]{4}-8[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}$" x) arr) +in + +# What the gate does with a row: the same four-way answer as +# OutcomeTracker.qualified_outcome_counts/1 (one row, one bucket). +let verdict_for = fun qualification claimed => + if claimed == "success" && qualification == "verified" then + "credited_success" + else if claimed == "failure" && std.array.elem qualification ["failed", "incomplete", "verified"] then + "credited_failure" + else if claimed == "false_positive" + && std.array.elem qualification ["still_present", "verified", "rollback_requested"] then + "credited_false_positive" + else + "audit_only" +in + +# A field that may be absent: present exactly when it is not in missing_evidence. +let gap_exact = fun name present missing => (present == !(std.array.elem name missing)) in + +let receipt_fields_c = { + 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, + head_sha | std.contract.from_predicate (fun s => std.is_string s && std.string.is_match "^[0-9a-f]{40}$" s) | optional, + match_kind | one_of ["exact", "category", "fuzzy"] | optional, + missing_evidence | missing_evidence_c, + observations + | { + after_hits | decimal_c | optional, + before_hits | decimal_c | optional, + exit_code | decimal_c | optional, + rescan | rescan_c | optional, + verdict | ascii_c | optional, + }, + parent_event_ids | parent_ids_c, + pattern_id | ascii_c | optional, + proof_or_test_ref + | { + row_sha256 | sha256_c, + scan_digest | sha256_c | optional, + test_digest | sha256_c | optional, + }, + provenance + | { event_id_source | event_id_source_c, producer | ascii_c, tool_version | ascii_c | optional, writer | std.contract.Equal "hypatia" }, + qualification | qualification_c, + receipt_sha256 | sha256_c, + source | { kind | source_kind_c, line | decimal_c, log | rel_path_c }, + subject_id | event_id_c | optional, + verdict | verdict_c, +} +in + +let receipt_rules_c = std.contract.custom (fun label r => + let m = r.missing_evidence in + let has = fun f obj => std.record.has_field f obj in + # verdict is derived, or a withdrawal with a parent + let verdict_ok = + if r.verdict == "withdrawn" then + (std.array.length r.parent_event_ids) > 0 + else + r.verdict == (verdict_for r.qualification r.assertion.claimed_outcome) + in + # verified needs evidence and observations + let verified_ok = + r.qualification != "verified" || (r.observations != {} && has "row_sha256" r.proof_or_test_ref) + in + # missing_evidence is exact + let gaps_ok = + (gap_exact "event_id" (has "event_id" r) m) + && (gap_exact "head_sha" (has "head_sha" r) m) + && (gap_exact "subject_id" (has "subject_id" r) m) + && (gap_exact "pattern_id" (has "pattern_id" r) m) + && (gap_exact "match_kind" (has "match_kind" r) m) + && (gap_exact "after_hits" (has "after_hits" r.observations) m) + && (gap_exact "before_hits" (has "before_hits" r.observations) m) + && (gap_exact "exit_code" (has "exit_code" r.observations) m) + && (gap_exact "rescan" (has "rescan" r.observations) m) + && (gap_exact "verdict" (has "verdict" r.observations) m) + && (gap_exact "scan_digest" (has "scan_digest" r.proof_or_test_ref) m) + && (gap_exact "test_digest" (has "test_digest" r.proof_or_test_ref) m) + && (gap_exact "tool_version" (has "tool_version" r.provenance) m) + # no stable finding identity exists yet (issue 984, E1) + && (std.array.elem "subject_identity" m) + in + if !verdict_ok then + 'Error { message = "verdict is not the answer of the gate for this qualification and claimed outcome (and is not a withdrawal with a parent)" } + else if !verified_ok then + 'Error { message = "qualification verified needs observations and an evidence reference" } + else if !gaps_ok then + 'Error { message = "missing_evidence is not exact: a field that is absent is not named, or a field that is named is present" } + else + 'Ok r) +in + +let receipt_c = std.contract.Sequence [receipt_fields_c, receipt_rules_c] in + +{ Receipt = receipt_c } diff --git a/test/event_id_test.exs b/test/event_id_test.exs new file mode 100644 index 00000000..d7d2e79c --- /dev/null +++ b/test/event_id_test.exs @@ -0,0 +1,75 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# E0-09 (owner ruling R5-A): Hypatia mints the event_id of a row itself, with an +# Elixir implementation of the ADR-008 profile T layout, and makes no +# `System.cmd` call. These tests check the layout that ADR-008 fixes. +defmodule Hypatia.EventIdTest do + use ExUnit.Case, async: true + + alias Hypatia.EventId + + @text ~r/\A[0-9a-f]{8}-[0-9a-f]{4}-8[0-9a-f]{3}-[89ab][0-9a-f]{3}-[0-9a-f]{12}\z/ + + test "the text is the lowercase 8-4-4-4-12 form, version 8, variant 10" do + for _ <- 1..200 do + assert EventId.generate() =~ @text + end + end + + test "the version nibble is 8 and the variant bits are 10, in the bytes" do + <<_ts::48, version::4, _a::12, variant::2, _b::62>> = EventId.to_binary(EventId.generate()) + assert version == 8 + assert variant == 0b10 + end + + test "the first 48 bits are the Unix time in milliseconds, big-endian" do + before_ms = System.system_time(:millisecond) + id = EventId.generate() + after_ms = System.system_time(:millisecond) + + <> = EventId.to_binary(id) + # The monotonic counter may carry into the millisecond, so allow 1 ms of slack. + assert ts >= before_ms and ts <= after_ms + 1 + end + + test "ids increase within one process, as text and as bytes" do + ids = for _ <- 1..5_000, do: EventId.generate() + assert ids == Enum.sort(ids) + assert length(Enum.uniq(ids)) == 5_000 + + bins = Enum.map(ids, &EventId.to_binary/1) + assert bins == Enum.sort(bins) + end + + test "ids from many processes are distinct" do + ids = + 1..8 + |> Task.async_stream(fn _ -> for _ <- 1..500, do: EventId.generate() end) + |> Enum.flat_map(fn {:ok, ids} -> ids end) + + assert length(Enum.uniq(ids)) == 4_000 + end + + test "valid?/1 accepts an id and refuses what is not one" do + assert EventId.valid?(EventId.generate()) + + for bad <- [ + "", + nil, + 42, + "0198a7b2-6f0c-7000-8000-000000000000", + "0198a7b2-6f0c-8000-c000-000000000000", + "0198A7B2-6F0C-8000-8000-000000000000", + "0198a7b2-6f0c-8000-8000-00000000000" + ] do + refute EventId.valid?(bad) + end + end + + test "the module makes no call to an external command" do + source = File.read!("lib/hypatia/event_id.ex") + refute source =~ "System.cmd" + refute source =~ ":os.cmd" + end +end diff --git a/test/fixtures/receipt/e0-receipt-line.jsonl b/test/fixtures/receipt/e0-receipt-line.jsonl new file mode 100644 index 00000000..37c1c7af --- /dev/null +++ b/test/fixtures/receipt/e0-receipt-line.jsonl @@ -0,0 +1 @@ +{"assertion":{"claimed_outcome":"success","file":"src/a.ex","recipe_id":"recipe-fixture","repo":"owner/repo"},"chain_version":"e0-receipt/1","event_id":"0198a7b2-6f0c-8000-8000-0123456789ab","missing_evidence":["head_sha","match_kind","pattern_id","rescan","scan_digest","subject_id","subject_identity","test_digest","tool_version"],"observations":{"after_hits":"0","before_hits":"2","exit_code":"0","verdict":"verified"},"parent_event_ids":[],"proof_or_test_ref":{"row_sha256":"abababababababababababababababababababababababababababababababab"},"provenance":{"event_id_source":"hypatia","producer":"robot-repo-automaton","writer":"hypatia"},"qualification":"verified","receipt_sha256":"f1f42d2d82603c175323f77e8ee88649d3fbf6ada6772104cd6428f7d5296487","source":{"kind":"fleet_import","line":"7","log":"shared-context/learning/fix-outcomes.jsonl"},"verdict":"credited_success"} diff --git a/test/receipt_test.exs b/test/receipt_test.exs new file mode 100644 index 00000000..61cf7066 --- /dev/null +++ b/test/receipt_test.exs @@ -0,0 +1,695 @@ +# SPDX-License-Identifier: MPL-2.0 +# Copyright (c) 2026 Jonathan D.A. Jewell (hyperpolymath) +# +# E0-09: the receipt. Design: docs/design/e0-receipt.adoc (RULED 2026-11-15). +# Contract: schema/receipt.ncl. +defmodule Hypatia.ReceiptTest do + use ExUnit.Case, async: false + + import ExUnit.CaptureLog + + alias Hypatia.EventId + alias Hypatia.FleetDispatcher + alias Hypatia.LearningScheduler + alias Hypatia.OutcomeTracker + alias Hypatia.Receipt + + @moduletag timeout: 120_000 + + # ── Setup: a runtime store in a temporary directory, a fake scanner, a fake + # neural coordinator. Nothing is written outside the temporary directory. + + setup do + keys = [:verisimdb_data_path, :annealing_state_path, :fleet_path] + original = for key <- keys, do: {key, Application.fetch_env(:hypatia, key)} + old_path = System.get_env("PATH") + old_mode = System.get_env("FAKE_PA_MODE") + + root = Path.join(System.tmp_dir!(), "hypatia_receipt_#{System.unique_integer([:positive])}") + data = Path.join(root, "data") + bin = Path.join(root, "bin") + File.mkdir_p!(bin) + + script = Path.join(bin, "panic-attack") + + File.write!(script, """ + #!/bin/sh + case "$FAKE_PA_MODE" in + clean) echo '{"weak_points":[]}' ;; + present) echo '{"weak_points":[{"category":"cat-x"}]}' ;; + *) exit 1 ;; + esac + """) + + File.chmod!(script, 0o755) + + Application.put_env(:hypatia, :verisimdb_data_path, data) + Application.put_env(:hypatia, :annealing_state_path, Path.join(root, "annealing")) + Application.put_env(:hypatia, :fleet_path, Path.join(root, "fleet")) + System.put_env("PATH", bin <> ":" <> (old_path || "")) + System.put_env("FAKE_PA_MODE", "clean") + + on_exit(fn -> + for {key, value} <- original do + case value do + {:ok, previous} -> Application.put_env(:hypatia, key, previous) + :error -> Application.delete_env(:hypatia, key) + end + end + + System.put_env("PATH", old_path || "") + + if old_mode, + do: System.put_env("FAKE_PA_MODE", old_mode), + else: System.delete_env("FAKE_PA_MODE") + + File.rm_rf!(root) + end) + + %{root: root, data: data} + end + + defp rows(data) do + dir = Path.join(data, "outcomes") + + case File.ls(dir) do + {:ok, files} -> + for f <- files, + String.ends_with?(f, ".jsonl"), + line <- File.read!(Path.join(dir, f)) |> String.split("\n", trim: true), + do: Jason.decode!(line) + + _ -> + [] + end + end + + defp fleet_row(recipe, verdict, extra \\ %{}) do + Map.merge( + %{ + "recipe_id" => recipe, + "repo" => "owner/repo", + "file" => "a.txt", + "bot" => "robot-repo-automaton", + "outcome" => if(verdict == "failed", do: "failure", else: "success"), + "verdict" => verdict, + "exit_code" => 0, + "before_hits" => 2, + "after_hits" => 0 + }, + extra + ) + end + + defp write_fleet(root, rows) do + file = Path.join([root, "fleet", "shared-context/learning/fix-outcomes.jsonl"]) + File.mkdir_p!(Path.dirname(file)) + File.write!(file, Enum.map_join(rows, "", &(Jason.encode!(&1) <> "\n"))) + end + + defp fake_coordinator do + test = self() + name = :"fake_coordinator_#{System.unique_integer([:positive])}" + + pid = + spawn_link(fn -> + loop = fn loop -> + receive do + {:source_bound, _s, {:outcome, f, o}} -> + send(test, {:coordinator, f, o}) + loop.(loop) + end + end + + loop.(loop) + end) + + Process.register(pid, name) + name + end + + defp neural(root, verification, success \\ true) do + FleetDispatcher.ingest_fix_outcome( + %{type: :fix_outcome, pattern: "recipe-neural", repo: "owner/repo", success: success}, + server: fake_coordinator(), + learning_file: Path.join(root, "learning.jsonl"), + trusted_verification: fn _ -> verification end + ) + end + + # ── The canonical form ────────────────────────────────────────────────── + + @event_id "0198a7b2-6f0c-8000-8000-0123456789ab" + @fixture "test/fixtures/receipt/e0-receipt-line.jsonl" + + defp fixture_row do + %{ + "event_id" => @event_id, + "event_id_source" => "hypatia", + "source_kind" => "fleet_import", + "source_line" => "7", + "source_row_sha256" => String.duplicate("ab", 32), + "source_bot" => "robot-repo-automaton", + "origin" => "gitbot-fleet", + "recipe_id" => "recipe-fixture", + "repo" => "owner/repo", + "file" => "src/a.ex", + "outcome" => "success", + "verification" => "verified", + "verdict" => "verified", + "exit_code" => 0, + "before_hits" => 2, + "after_hits" => 0 + } + end + + defp fixture_ctx do + %{ + kind: :fleet_import, + log: "shared-context/learning/fix-outcomes.jsonl", + line: "7", + row_sha256: String.duplicate("ab", 32) + } + end + + describe "the canonical form" do + test "the encoded line is byte-identical to the committed fixture" do + assert {:ok, line} = Receipt.encode(Receipt.build(fixture_row(), fixture_ctx())) + assert line <> "\n" == File.read!(@fixture) + end + + test "the fixture is in canonical form: jq -cS prints the same bytes" do + {out, 0} = System.cmd("jq", ["-cS", ".", @fixture]) + assert out == File.read!(@fixture) + end + + test "keys are sorted, there is no whitespace and no number" do + {:ok, line} = Receipt.encode(%{"b" => "1", "a" => %{"d" => ["x"], "c" => "y"}}) + assert line == ~s({"a":{"c":"y","d":["x"]},"b":"1"}) + end + + test "a number, an atom or a non-ASCII string is refused, never written" do + assert {:error, {:not_canonical, _}} = Receipt.encode(%{"a" => 1}) + assert {:error, {:not_canonical, _}} = Receipt.encode(%{"a" => :x}) + assert {:error, {:not_canonical, _}} = Receipt.encode(%{"a" => "é"}) + end + + test "a field with text outside printable ASCII is written with %XX, and % too" do + row = fixture_row() |> Map.put("file", "src/é 100%.ex") + receipt = Receipt.build(row, fixture_ctx()) + assert receipt["assertion"]["file"] == "src/%C3%A9 100%25.ex" + assert {:ok, _} = Receipt.encode(receipt) + end + + test "receipt_sha256 covers every other field" do + receipt = Receipt.build(fixture_row(), fixture_ctx()) + {digest, body} = Map.pop(receipt, "receipt_sha256") + {:ok, line} = Receipt.encode(body) + assert digest == :crypto.hash(:sha256, line) |> Base.encode16(case: :lower) + + changed = put_in(body, ["assertion", "file"], "other.ex") + {:ok, other} = Receipt.encode(changed) + refute :crypto.hash(:sha256, other) |> Base.encode16(case: :lower) == digest + end + end + + # ── The contract (needs the nickel binary; skipped, loudly, without it) ── + + describe "the Nickel contract" do + @nickel System.get_env("NICKEL") || System.find_executable("nickel") + + defp check_contract(receipt) do + dir = Path.join(System.tmp_dir!(), "receipt_ncl_#{System.unique_integer([:positive])}") + File.mkdir_p!(dir) + json = Path.join(dir, "r.json") + ncl = Path.join(dir, "c.ncl") + File.write!(json, Jason.encode!(receipt)) + schema = Path.expand("schema/receipt.ncl") + File.write!(ncl, "let s = import \"#{schema}\" in (import \"#{json}\") | s.Receipt\n") + result = System.cmd(@nickel, ["export", "--format", "json", ncl], stderr_to_stdout: true) + File.rm_rf!(dir) + result + end + + defp good, do: Receipt.build(fixture_row(), fixture_ctx()) + + # Re-seal a receipt after a change, so the contract refuses the CHANGE and + # not a stale digest. + defp reseal(receipt) do + body = Map.delete(receipt, "receipt_sha256") + {:ok, line} = Receipt.encode(body) + Map.put(body, "receipt_sha256", :crypto.hash(:sha256, line) |> Base.encode16(case: :lower)) + end + + if @nickel == nil do + @tag skip: "nickel is not installed: the contract was NOT checked" + end + + test "a receipt that the emitter builds satisfies the contract" do + assert {_, 0} = check_contract(good()) + end + + if @nickel == nil do + @tag skip: "nickel is not installed: the contract was NOT checked" + end + + test "the contract refuses a receipt that claims more than its evidence" do + # 1. a verdict that is not the answer of the gate + {out, code} = check_contract(good() |> Map.put("verdict", "audit_only") |> reseal()) + assert code != 0 + assert out =~ "verdict is not the answer of the gate" + + # 2. verified, with no observations + bad = good() |> Map.put("observations", %{}) |> reseal() + {out, code} = check_contract(bad) + assert code != 0 + assert out =~ "verified needs observations" + + # 3. a field that is absent but not named, and one that is named but present + bad = good() |> Map.update!("missing_evidence", &(&1 -- ["head_sha"])) |> reseal() + {out, code} = check_contract(bad) + assert code != 0 + assert out =~ "missing_evidence is not exact" + + # 4. a qualification outside the closed set + {_, code} = check_contract(good() |> Map.put("qualification", "great") |> reseal()) + assert code != 0 + + # 5. a malformed digest + {_, code} = check_contract(good() |> Map.put("receipt_sha256", "xyz")) + assert code != 0 + + # 6. a number where a string belongs + {_, code} = check_contract(good() |> put_in(["observations", "after_hits"], 0)) + assert code != 0 + + # 7. a wrong chain version, and an event_id that is not version 8 + {_, code} = check_contract(good() |> Map.put("chain_version", "e0-receipt/2")) + assert code != 0 + + {_, code} = + check_contract(good() |> Map.put("event_id", "0198a7b2-6f0c-7000-8000-0123456789ab")) + + assert code != 0 + end + + if @nickel == nil do + @tag skip: "nickel is not installed: the contract was NOT checked" + end + + test "every receipt that the integration tests below write satisfies the contract", %{ + data: data + } do + OutcomeTracker.record_fleet_outcome("recipe-c1", "o/r", "f", :success, "s1", "verified", %{ + "verdict" => "verified", + "before_hits" => 2, + "after_hits" => 0, + "exit_code" => 0 + }) + + OutcomeTracker.record_fleet_outcome("recipe-c2", "o/r", "f", :success, "s2", "unqualified") + + OutcomeTracker.record_outcome("recipe-c3", "o/r", "f", :failure, %{ + "verification" => "failed" + }) + + receipts = Receipt.all(data) + assert length(receipts) == 3 + for r <- receipts, do: assert({_, 0} = check_contract(r)) + end + end + + # ── The learning paths: one receipt each ──────────────────────────────── + + describe "one receipt for each learning update" do + test "a verified update on the local rescan path", %{data: data} do + File.mkdir_p!(Path.join(data, "recipes")) + + {:ok, record, :verified} = + OutcomeTracker.record_and_verify("recipe-r1", "o/r", "f", :success, + verify: true, + category: "cat-x", + repo_path: data + ) + + assert [r] = Receipt.all(data) + assert r["event_id"] == record["event_id"] + assert r["verdict"] == "credited_success" + assert r["qualification"] == "verified" + assert r["source"]["kind"] == "local_rescan" + assert r["observations"]["rescan"] == "verified" + assert r["provenance"]["event_id_source"] == "hypatia" + assert EventId.valid?(r["event_id"]) + end + + test "a verified update on the fleet import path (through the scheduler)", %{ + root: root, + data: data + } do + write_fleet(root, [fleet_row("recipe-f1", "verified")]) + assert {1, _} = LearningScheduler.ingest_fleet_outcomes(nil) + + assert [r] = Receipt.all(data) + assert r["verdict"] == "credited_success" + assert r["source"]["kind"] == "fleet_import" + assert r["source"]["line"] == "1" + assert r["source"]["log"] == "shared-context/learning/fix-outcomes.jsonl" + assert r["provenance"]["producer"] == "robot-repo-automaton" + + assert r["observations"] == %{ + "after_hits" => "0", + "before_hits" => "2", + "exit_code" => "0", + "verdict" => "verified" + } + + # The digest is that of the exact source line. + [source_line] = + Path.join([root, "fleet", "shared-context/learning/fix-outcomes.jsonl"]) + |> File.read!() + |> String.split("\n", trim: true) + + assert r["proof_or_test_ref"]["row_sha256"] == + :crypto.hash(:sha256, source_line) |> Base.encode16(case: :lower) + end + + test "a verified update on the neural path", %{root: root, data: data} do + neural(root, "verified") + assert_receive {:coordinator, _, "success"}, 500 + + assert [r] = Receipt.all(data) + assert r["verdict"] == "credited_success" + assert r["source"]["kind"] == "neural_path" + end + + test "a qualified failure on the local rescan path (a caller's own failed claim)", %{ + data: data + } do + {:ok, record} = + OutcomeTracker.record_outcome("recipe-r2", "o/r", "f", :failure, %{ + "verification" => "failed" + }) + + assert [r] = Receipt.all(data) + assert r["event_id"] == record["event_id"] + assert r["verdict"] == "credited_failure" + assert r["qualification"] == "failed" + assert r["source"]["kind"] == "local_caller" + end + + test "a qualified failure on the fleet import path", %{root: root, data: data} do + write_fleet(root, [fleet_row("recipe-f2", "failed", %{"exit_code" => 2})]) + assert {1, _} = LearningScheduler.ingest_fleet_outcomes(nil) + + assert [r] = Receipt.all(data) + assert r["verdict"] == "credited_failure" + assert r["qualification"] == "failed" + assert r["observations"]["exit_code"] == "2" + end + + test "a qualified failure on the neural path", %{root: root, data: data} do + neural(root, "failed", false) + assert_receive {:coordinator, _, "failure"}, 500 + + assert [r] = Receipt.all(data) + assert r["verdict"] == "credited_failure" + end + + test "an audit row (owner ruling R1) writes a receipt with verdict audit_only", %{ + root: root, + data: data + } do + write_fleet(root, [fleet_row("recipe-f3", "no_op", %{"before_hits" => 0})]) + assert {0, _} = LearningScheduler.ingest_fleet_outcomes(nil) + + assert [r] = Receipt.all(data) + assert r["verdict"] == "audit_only" + assert r["qualification"] == "unqualified" + end + + test "the neural path writes no receipt when nothing is learned", %{root: root, data: data} do + neural(root, nil) + refute_receive {:coordinator, _, _}, 100 + assert Receipt.all(data) == [] + end + end + + # ── Identity ──────────────────────────────────────────────────────────── + + describe "the identity of an event" do + test "a row carries the event_id that its receipt names", %{data: data} do + {:ok, record} = + OutcomeTracker.record_outcome("recipe-i1", "o/r", "f", :failure, %{ + "verification" => "failed" + }) + + assert [row] = rows(data) + assert row["event_id"] == record["event_id"] + assert row["source_kind"] == "local_caller" + assert [%{"event_id" => id}] = Receipt.all(data) + assert id == row["event_id"] + end + + test "a caller cannot choose an event_id or any field of the receipt context", %{data: data} do + chosen = EventId.generate() + + for _ <- 1..2 do + {:ok, record} = + OutcomeTracker.record_outcome("recipe-i2", "o/r", "f", :failure, %{ + "verification" => "failed", + "event_id" => chosen, + "event_id_source" => "producer", + "source_kind" => "fleet_import", + "source_line" => "99", + "source_row_sha256" => String.duplicate("0", 64), + "source_bot" => "somebody" + }) + + refute record["event_id"] == chosen + assert record["event_id_source"] == "hypatia" + assert record["source_kind"] == "local_caller" + + # The context a caller made up is not stored at all. + for key <- ["source_line", "source_row_sha256", "source_bot"] do + refute Map.has_key?(record, key) + end + end + + # Two events, two receipts: a chosen id cannot silence a later receipt. + assert length(Receipt.all(data)) == 2 + end + + test "two events with identical content have different ids and two receipts", %{data: data} do + for _ <- 1..2 do + OutcomeTracker.record_outcome("recipe-i3", "o/r", "f", :failure, %{ + "verification" => "failed" + }) + end + + ids = Receipt.all(data) |> Enum.map(& &1["event_id"]) + assert length(Enum.uniq(ids)) == 2 + end + end + + # ── Replay, the store, and the failure rule ───────────────────────────── + + describe "replay" do + test "a replay of the same event writes no second receipt", %{root: root, data: data} do + write_fleet(root, [fleet_row("recipe-p1", "verified")]) + assert {1, signature} = LearningScheduler.ingest_fleet_outcomes(nil) + assert {0, _} = LearningScheduler.ingest_fleet_outcomes(signature) + assert {0, _} = LearningScheduler.ingest_fleet_outcomes(nil) + + assert length(rows(data)) == 1 + assert length(Receipt.all(data)) == 1 + end + + test "writing the receipt of a row twice writes one", %{data: data} do + {:ok, _} = + OutcomeTracker.record_outcome("recipe-p2", "o/r", "f", :failure, %{ + "verification" => "failed" + }) + + [row] = rows(data) + assert :ok = Receipt.write(data, row) + assert :ok = Receipt.write(data, row) + assert length(Receipt.all(data)) == 1 + end + end + + describe "the store of the row" do + test "a receipt goes into the store of its row, also after the data root changes", %{ + root: root, + data: data + } do + {:ok, _} = + OutcomeTracker.record_outcome("recipe-s1", "o/r", "f", :failure, %{ + "verification" => "failed" + }) + + File.rm_rf!(Path.join(data, "receipts")) + assert Receipt.all(data) == [] + + # The configuration now points at another store. + other = Path.join(root, "other") + Application.put_env(:hypatia, :verisimdb_data_path, other) + + assert {1, 0} = Receipt.repair(data, "recipe-s1") + assert length(Receipt.all(data)) == 1 + assert Receipt.all(other) == [] + refute File.exists?(Path.join(other, "receipts")) + end + end + + describe "the failure rule" do + test "the row write fails: nothing else runs and no receipt is written", %{ + root: root, + data: data + } do + File.mkdir_p!(data) + :ok = File.ln_s(Path.join(root, "nowhere"), Path.join(data, "outcomes")) + + capture_log(fn -> + assert {:error, {:outcome_log_write, _}} = + OutcomeTracker.record_outcome("recipe-w1", "o/r", "f", :failure, %{ + "verification" => "failed" + }) + end) + + assert Receipt.all(data) == [] + refute File.exists?(Path.join(data, "receipts")) + end + + test "the receipt write fails: the caller still gets {:ok, record}, the log says receipt_pending, and the next cycle writes it", + %{root: root, data: data} do + File.mkdir_p!(data) + :ok = File.ln_s(Path.join(root, "nowhere"), Path.join(data, "receipts")) + + log = + capture_log(fn -> + assert {:ok, record} = + OutcomeTracker.record_outcome("recipe-w2", "o/r", "f", :failure, %{ + "verification" => "failed" + }) + + send(self(), {:record, record}) + end) + + assert_received {:record, record} + assert log =~ "receipt_pending" + assert log =~ record["event_id"] + assert length(rows(data)) == 1 + + # The obstacle goes. The next time the recipe is recomputed, the receipt is written. + File.rm!(Path.join(data, "receipts")) + assert Receipt.all(data) == [] + OutcomeTracker.update_recipe_confidence("recipe-w2") + assert [%{"event_id" => id}] = Receipt.all(data) + assert id == record["event_id"] + + # And once only. + OutcomeTracker.update_recipe_confidence("recipe-w2") + assert length(Receipt.all(data)) == 1 + end + + test "the derived update fails: the row and its receipt exist, the next cycle repeats the update, and the receipt stays one", + %{root: root, data: data} do + # The annealing state cannot be written: its directory is a regular file. + blocker = Path.join(root, "blocker") + File.write!(blocker, "x") + Application.put_env(:hypatia, :annealing_state_path, Path.join(blocker, "annealing")) + + capture_log(fn -> + assert {:ok, _} = + OutcomeTracker.record_outcome("recipe-w3", "o/r", "f", :failure, %{ + "verification" => "failed" + }) + end) + + assert length(rows(data)) == 1 + assert length(Receipt.all(data)) == 1 + + File.rm!(blocker) + Application.put_env(:hypatia, :annealing_state_path, Path.join(root, "annealing")) + OutcomeTracker.update_recipe_confidence("recipe-w3") + assert length(Receipt.all(data)) == 1 + end + + test "no receipt is written before its row, and an orphan receipt is reported", %{data: data} do + row = + Map.put( + %{ + "recipe_id" => "recipe-o1", + "repo" => "o/r", + "file" => "f", + "outcome" => "failure", + "verification" => "failed", + "source_kind" => "local_caller" + }, + "event_id", + EventId.generate() + ) + + assert {:error, :row_not_in_log} = Receipt.write(data, row) + assert Receipt.all(data) == [] + + # A receipt whose row is not in the log (made by hand) is an orphan. + receipt = + Receipt.build(row, %{ + kind: :local_caller, + log: "outcomes/2026-11.jsonl", + line: "1", + row_sha256: String.duplicate("a", 64) + }) + + {:ok, line} = Receipt.encode(receipt) + File.mkdir_p!(Path.join(data, "receipts")) + File.write!(Receipt.path(data, Date.utc_today()), line <> "\n") + assert Receipt.orphans(data) == [row["event_id"]] + end + + test "after the next run each row has exactly one receipt and no receipt is without its row", + %{data: data} do + for n <- 1..3 do + OutcomeTracker.record_outcome("recipe-w4", "o/r", "f#{n}", :failure, %{ + "verification" => "failed" + }) + end + + # Lose two of the three receipts, as a failed write would. + [first | _] = Receipt.all(data) + File.rm_rf!(Path.join(data, "receipts")) + File.mkdir_p!(Path.join(data, "receipts")) + {:ok, line} = Receipt.encode(first) + File.write!(Receipt.path(data, Date.utc_today()), line <> "\n") + + assert {2, 0} = Receipt.repair(data, "recipe-w4") + assert {0, 0} = Receipt.repair(data, "recipe-w4") + + ids = Receipt.all(data) |> Enum.map(& &1["event_id"]) |> Enum.sort() + row_ids = rows(data) |> Enum.map(& &1["event_id"]) |> Enum.sort() + assert ids == row_ids + assert Receipt.orphans(data) == [] + end + + test "a row with no event_id (written before E0-09) gets no receipt: nothing is back-filled", + %{data: data} do + dir = Path.join(data, "outcomes") + File.mkdir_p!(dir) + + File.write!( + Path.join(dir, "2026-01.jsonl"), + Jason.encode!(%{ + "recipe_id" => "recipe-l1", + "repo" => "o/r", + "file" => "f", + "outcome" => "failure", + "verification" => "failed" + }) <> "\n" + ) + + assert {0, 0} = Receipt.repair(data, "recipe-l1") + assert Receipt.all(data) == [] + end + end +end From 859995b8885a1faf430634e27dc737239338cd7b Mon Sep 17 00:00:00 2001 From: Claude Date: Sun, 15 Nov 2026 13:42:08 +0000 Subject: [PATCH 2/2] fix(ci): satisfy the README count and the estate UUID gate on the E0-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 --- README.adoc | 2 +- test/event_id_test.exs | 24 +++++++++++++++++++++--- test/receipt_test.exs | 12 +++++++++--- 3 files changed, 31 insertions(+), 7 deletions(-) diff --git a/README.adoc b/README.adoc index c84f4000..c986f5dc 100644 --- a/README.adoc +++ b/README.adoc @@ -76,7 +76,7 @@ PatternRegistry ──> TriangleRouter ──> FleetDispatcher ──> DispatchM [cols="1,3"] |=== -| `lib/` | 170 Elixir source files — pipeline, rules, VCL, neural, safety, web, merge orchestration +| `lib/` | 172 Elixir source files — pipeline, rules, VCL, neural, safety, web, merge orchestration | `lib/rules/` | 44 source files: rule modules and their helpers; see link:docs/rules/catalogue.adoc[the catalogue] | `lib/neural/` | 8 networks + blackboard, coordinator, persistence, rebalancer | `lib/vcl/` | VCL query layer over verisim-data: parser, file executor, cache, federation diff --git a/test/event_id_test.exs b/test/event_id_test.exs index d7d2e79c..b94dac0b 100644 --- a/test/event_id_test.exs +++ b/test/event_id_test.exs @@ -51,15 +51,33 @@ defmodule Hypatia.EventIdTest do assert length(Enum.uniq(ids)) == 4_000 end + # The estate UUID gate (`check-uuid-v8.sh --strict`, ADR-008) reads source text + # and has no exemption, so a deliberately wrong id cannot be written here as a + # literal. It is made from a version 8 id by changing one nibble: the character + # at index 14 is the version and the one at index 19 is the variant. + defp with_nibble(id, index, nibble) do + binary_part(id, 0, index) <> nibble <> binary_part(id, index + 1, byte_size(id) - index - 1) + end + test "valid?/1 accepts an id and refuses what is not one" do - assert EventId.valid?(EventId.generate()) + id = EventId.generate() + assert EventId.valid?(id) + + # Each wrong id differs from the valid one in exactly one nibble, so it is + # that nibble that valid?/1 refuses. Putting the nibble back gives the valid + # id again. + version_7 = with_nibble(id, 14, "7") + variant_c = with_nibble(id, 19, "c") + assert String.at(version_7, 14) == "7" and String.at(variant_c, 19) == "c" + assert with_nibble(version_7, 14, String.at(id, 14)) == id + assert with_nibble(variant_c, 19, String.at(id, 19)) == id for bad <- [ "", nil, 42, - "0198a7b2-6f0c-7000-8000-000000000000", - "0198a7b2-6f0c-8000-c000-000000000000", + version_7, + variant_c, "0198A7B2-6F0C-8000-8000-000000000000", "0198a7b2-6f0c-8000-8000-00000000000" ] do diff --git a/test/receipt_test.exs b/test/receipt_test.exs index 61cf7066..f39524b5 100644 --- a/test/receipt_test.exs +++ b/test/receipt_test.exs @@ -283,14 +283,20 @@ defmodule Hypatia.ReceiptTest do {_, code} = check_contract(good() |> put_in(["observations", "after_hits"], 0)) assert code != 0 - # 7. a wrong chain version, and an event_id that is not version 8 + # 7. a wrong chain version, and an event_id that is not version 8. The estate + # UUID gate (`check-uuid-v8.sh --strict`) refuses a non-v8 literal in source, + # so the wrong id is made from the version 8 one by changing its version + # nibble (the character at index 14). {_, code} = check_contract(good() |> Map.put("chain_version", "e0-receipt/2")) assert code != 0 - {_, code} = - check_contract(good() |> Map.put("event_id", "0198a7b2-6f0c-7000-8000-0123456789ab")) + version_7 = binary_part(@event_id, 0, 14) <> "7" <> binary_part(@event_id, 15, 21) + assert String.at(version_7, 14) == "7" + assert binary_part(version_7, 0, 14) <> "8" <> binary_part(version_7, 15, 21) == @event_id + {out, code} = check_contract(good() |> Map.put("event_id", version_7) |> reseal()) assert code != 0 + assert out =~ "event_id" end if @nickel == nil do