@spec append!(String.t(), t()) :: :ok

REAL append-only persistence: encodes receipt as one JSON line and appends it (File.write!/3 with [:append]) to path(base_dir, at) -- never truncates, never rewrites a prior line. Creates the receipts directory if needed. This is deliberately NOT atomic-rename like GgenIgniter.Manifest.persist!/2 -- an append-only log's failure mode (a torn last line on a real crash mid-write) is recoverable by discarding an incomplete final line, whereas manifest.json is a single point-in-time snapshot that atomic rename protects from ever being partially overwritten. See GgenIgniter.Reactors.ReconcileReactor's moduledoc for why this receipt append happens BEFORE, and independent of, any manifest promotion.

@spec compute_receipt_hash(t()) :: String.t()

A "sha256:" <> hex digest over receipt's own content (its to_json_map/1 form, MINUS the "receipt_hash" key itself -- a hash cannot cover its own output without being circular). This is what proves chain integrity at the single-receipt level: any bit of a persisted receipt (its standing, its files, its metadata, any PRD v2 field) changing after the fact changes this digest, exactly the same tamper-evidence property hash_entries/1/hash_files/1 already give the FILES a receipt describes, now given to the RECEIPT RECORD describing them.

new/2 calls this automatically to populate receipt_hash unless the caller explicitly supplied one (see new/2). Deterministic and order-independent: Jason.encode!/1 is called on the map sorted by key, so field-insertion order in the caller never affects the digest.

@spec dir(String.t()) :: String.t()

The receipts directory for consumer project base_dir: <base_dir>/.ggen_igniter/receipts.

@spec hash_entries([{String.t(), binary() | nil}]) :: String.t()

A "sha256:" <> hex digest over entries -- a list of {path, content_or_nil} pairs, nil meaning the path was absent. Sorted by path first so the digest is order-independent (the same file set always hashes the same way regardless of enumeration order). This is the primitive both hash_files/1 (reads current disk state) and GgenIgniter.Reactors.ReconcileReactor (hashing an already-captured pre-image, without re-reading disk) build on.

@spec hash_files([String.t()]) :: String.t()

A "sha256:" <> hex digest over the REAL, CURRENT on-disk content of paths (missing files hash as :absent, matching hash_entries/1). This is the real "project hash" (scoped to the exact files one attempt touches, not a whole-repository hash) the user's compensation narrative refers to as "resulting project hash".

@spec new(map() | keyword()) :: t()

Builds a new receipt struct. attrs is a plain map/keyword list; :standing is required and MUST be one of standings/0 (raises ArgumentError otherwise -- a receipt with an invented standing is a real correctness bug, refused loudly rather than silently persisted). :id is generated if not given; :started_at/:finished_at default to DateTime.utc_now/0 (ISO8601-encoded) if not given.

@spec new(
  map() | keyword(),
  keyword()
) :: t()

Same as new/1, plus an opts keyword list for PRD v2 chain-linking.

opts[:base_dir], when given together with a :recipe_key in attrs and no explicit :parent_hash in attrs, auto-derives parent_hash by reusing reconstruct_standing/2's own on-disk chain walk: the LAST receipt already persisted for this recipe_key (if any) has its receipt_hash copied into the new receipt's parent_hash, giving the same append-only, disk-verified chain-of-custody reconstruct_standing/2 already checks for pre_run_hash/post_run_hash, extended to the whole receipt content. No prior receipt ({:error, :no_receipts}, or the chain itself is broken) leaves parent_hash nil -- the honest "first/rootless receipt in this chain" state, never a raised error, since new/2 builds a struct and must not fail just because history-lookup found nothing.

tool_version defaults to this application's own Mix.Project version (tool_version/0) unless explicitly given. schema_version defaults to "1" (already the struct default) unless explicitly given.

receipt_hash is always (re)computed by compute_receipt_hash/1 over the fully-built struct UNLESS the caller explicitly supplied :receipt_hash in attrs (e.g. a receipt round-tripped from JSON that already carries its original hash) -- see compute_receipt_hash/1 for exactly what the hash covers.

@spec path(String.t(), DateTime.t()) :: String.t()

The date-partitioned JSONL path a receipt stamped at (default: now) is appended to -- <base_dir>/.ggen_igniter/receipts/<yyyy-mm-dd>.jsonl. Date partitioning keeps any single file bounded (an append-only log with no rotation would grow forever) while read_all!/1 transparently reads every partition back in order.

@spec read_all!(String.t()) :: [map()]

Reads every receipt line back from EVERY .jsonl partition under dir(base_dir), in file-then-line order (oldest date partition first; each partition is itself append-ordered, so this is the real chronological attempt history). Returns [] (not an error) when no receipts directory exists yet -- the honest "no attempts recorded yet" state, matching GgenIgniter.Manifest.load/1's same "first run" honesty.

@spec reconstruct_standing(String.t(), String.t()) ::
  {:ok, %{standing: standing(), receipt: map(), receipt_count: pos_integer()}}
  | {:error, :no_receipts}
  | {:error, {:chain_broken, map()}}

Reconstructs the CURRENT standing for one recipe (recipe_key) by re-reading the real, on-disk receipt chain under base_dir -- ZERO in-process state is consulted. This simulates exactly what a genuinely fresh BEAM process (no live GgenIgniter.Controller, no prior GenServer state -- e.g. after a real restart) would see: GgenIgniter.Controller's reconciliation_count/last_run_at are real, process-only knowledge (see that module's moduledoc) that this function makes NO attempt to recover; what IS durable, and what this function reconstructs, is the chain of admitted attempts and the standing the last one left behind.

recipe_key is the SAME (template_path, out_template) identity GgenIgniter.Manifest.recipe_key/2 builds and every GgenIgniter.Receipt persists verbatim in its "recipe_key" field (see GgenIgniter.Reactors.ReconcileReactor's render_target/2) -- the real, durable identity a receipt chain is keyed by on disk, in contrast to GgenIgniter.Controller's pack_key, which is an arbitrary, PURELY in-process caller-supplied term with no on-disk representation at all.

read_all!/1's full chronological history is filtered down to recipe_key's own receipts, then walked in order verifying REAL chain continuity: receipt N's pre_run_hash must equal the most recent prior receipt's post_run_hash whenever both sides recorded a hash. A :refused receipt records neither hash (nothing was ever actuated), so it is skipped as a continuity checkpoint -- it neither breaks nor extends the chain, it is simply not evidence about file content either way. A receipt whose pre_run_hash does NOT match the expected prior hash is real, located evidence that the on-disk history being trusted here does not check out -- either the stored receipt lines were tampered with, or some other, out-of-band write touched this recipe's target between two admitted attempts.

Returns:

• {:ok, %{standing: standing(), receipt: map(), receipt_count: pos_integer()}} -- chain verified intact end to end; standing/receipt describe the LAST receipt for recipe_key.
• {:error, :no_receipts} -- recipe_key has no receipts at all under base_dir (the honest "nothing to reconstruct" case, matching read_all!/1's own "no directory yet" honesty).

• {:error, {:chain_broken, %{at_index: non_neg_integer(), receipt_id: String.t(), expected_pre_run_hash: String.t() | nil, actual_pre_run_hash: String.t()}}} -- a real, located break: at_index is the 0-based position (within recipe_key's OWN filtered history, not the whole-directory history) of the FIRST receipt whose pre_run_hash fails to match the expected prior hash.

@spec standings() :: [standing(), ...]

The five real, closed-set standing atoms a receipt may carry.

@spec to_json_map(t()) :: map()

Converts a receipt struct to its plain, Jason-encodable, string-keyed map form.

@spec to_prd_status(t() | standing()) :: String.t()

Maps a receipt's real standing (standing/0) onto the PRD's status vocabulary (this repo's own no-overclaiming floor: ALIVE/PARTIAL_ALIVE/BLOCKED/BUILD_BROKEN/UNSUPPORTED/UNKNOWN), so a PRD-facing report can cite one receipt's standing without re-deriving the mapping ad hoc at every call site.

• :alive -> "ALIVE" -- the attempt fully succeeded.
• :refused -> "BLOCKED" -- nothing was actuated; a real precondition or guard is what's blocking, not a code defect.
• :compensated -> "PARTIAL_ALIVE" -- files were written, then restored after a (non-build) verification failure; the recipe partially executed before self-healing.
• :build_broken -> "BUILD_BROKEN" -- generated content itself did not compile/parse.
• :compensation_failed -> "PARTIAL_ALIVE" -- like :compensated, real actuation partially occurred before failing; PRD status vocabulary has no distinct "compensation itself also failed" category, so this maps to the same PARTIAL_ALIVE bucket as :compensated (both are "some real, incomplete progress occurred"), while receipt.metadata/receipt.reason retain the actual catastrophic detail this collapsed status label does not carry.
• Any other value (should be impossible given new/1's closed-set guard, but to_prd_status/1 accepts a bare atom, not just a t(), so a hand-built/decoded atom outside standings/0 is possible) -> "UNKNOWN" -- the honest fallback, never a raised error and never a silently wrong guess.

"UNSUPPORTED" is a real PRD status value with no standing/0 equivalent in this module today (no receipt is ever produced for an operation this pipeline doesn't support at all -- that's refused earlier, before any receipt-worthy attempt exists) and is therefore never returned by this mapping; it is listed above only because the PRD names it as part of the shared vocabulary this function's return values are drawn from.

@spec tool_version() :: String.t()

This application's own release version (Mix.Project.config()[:version]), used as t/0's tool_version default so every receipt records exactly which build of ggen_igniter produced it.