Module receipt 

tatara-receipt/v1 — the typed receipt envelope every pleme-io Job emits to prove its work was done.

Today’s consumers (and the only ones supported on tatara-receipt/v1):

• closed-loop auth probes — kind = "closed-loop-auth". Stamps that a system’s bundled identity issuer authenticated its bundled client. The substrate primitive every closed-loop-testable product composes (an issuer↔client pair, future: identity providers, message brokers, databases that can issue creds to themselves).
• schema/migration runs — kind = "db-migration". shinka emits one per applied migration; pillars carry the diff hash.
• test suites — kind = "test-suite". kenshi-runner et al.
• nix builds — kind = "nix-build". Carries the store-path pillar as artifact_hash.
• Anything else — operators register new kind strings; the schema is open by design (the shape is fixed; the kind is data).

Lives in tatara-process so ReceiptEnvelope → ProcessAttestation is a local typed bridge — the reconciler’s verifier and any future Process consumer share one parse.

Wire format (snake_case to match the existing ConfigMap payload shape the closed-loop-probe chart writes):

version: tatara-receipt/v1
kind: closed-loop-auth
composed_root: <26-char hex>
intent_hash:   <hex>
artifact_hash: <hex>
control_hash:  <hex>
generated_at:  2026-05-19T22:00:00Z
process_ref:   "demo-test/ephemeral-demo"   # optional
evidence:      { ... }                              # optional, free-form

Structs

ReceiptEnvelope

Typed receipt envelope. Any Job in pleme-io that wants its result to chain into a Process’s status.attestation writes one of these.

UnknownReceiptKind

Enums

ReceiptError

Why a receipt is rejected. Kept as a typed enum so callers can pattern-match on the failure mode and surface targeted operator messages.

ReceiptKind

Closed-set typed identifier for the four known ReceiptEnvelope::kind strings the substrate emits today — Self::ClosedLoopAuth → "closed-loop-auth", Self::DbMigration → "db-migration", Self::TestSuite → "test-suite", Self::NixBuild → "nix-build" — as a Rust enum, so the (variant, canonical kebab-case kind, semantic role) triple binds at ONE site on the typed algebra rather than at the four byte-identical string-literal sites scattered across the closed-loop probe binary (default_value on --receipt-kind), the reconciler’s receipt-parser tests, the ephemeral_pipeline integration test, and the future shinka / kenshi / nix-build Job authors that compose ReceiptEnvelope::build.

ReceiptWireForm

Wire-form encoding a ReceiptEnvelope payload was serialized in — the closed set of on-disk shapes the reader accepts.

Constants

RECEIPT_CM_KEYS

The primary-first closed-set of data keys the substrate’s receipt-CM readers look up in order. RECEIPT_JSON_KEY takes precedence over RECEIPT_YAML_KEY — every reader-side lookup gate (extract_receipt_payload_json composes the canonical gate) iterates this table and returns the first hit as &str; every writer emits BOTH entries so the primary-first ordering the reader prefers matches the JSON form the probe wrote as its source-of-truth payload.

RECEIPT_CM_MISSING_KEY_MSG

Operator-facing diagnostic message the substrate’s receipt-CM reader-side lookup gate returns when neither RECEIPT_JSON_KEY nor RECEIPT_YAML_KEY is present as a string-valued entry on the ConfigMap’s data map. Named through the substrate so the message stays coherent with RECEIPT_CM_KEYS — a rename at either key const would leave this message spelling the pre-rename literals verbatim, so both this const AND the two key consts live at ONE substrate site and any future re-shape sweeps them together.

RECEIPT_CM_SUFFIX

Suffix appended to a Job’s name to compose its default receipt- ConfigMap name. The substrate convention is that any Job which emits a ReceiptEnvelope writes it to a ConfigMap in the Job’s own namespace whose name is <job_name>-receipt unless the caller supplies an explicit override.

RECEIPT_JSON_KEY

Canonical data key on a receipt-carrying ConfigMap for the JSON wire form of a ReceiptEnvelope — the substrate’s PRIMARY payload key. Peer to RECEIPT_YAML_KEY on the same wire-form axis; RECEIPT_CM_KEYS fixes the primary-first ordering the reader-side lookup gate binds to.

RECEIPT_VERSION

Canonical version string. Bump → tatara-receipt/v2 if the wire shape changes; parsers refuse anything else for the v1 reader.

RECEIPT_YAML_KEY

Canonical data key on a receipt-carrying ConfigMap for the YAML wire form of a ReceiptEnvelope — the substrate’s operator-facing FALLBACK payload key. Peer to RECEIPT_JSON_KEY on the same wire-form axis; RECEIPT_CM_KEYS fixes the primary-first ordering that pins the JSON form ahead of the YAML twin.

Functions

default_receipt_config_map_name

Compose the canonical receipt-ConfigMap name for a Job named job_name — the substrate’s default when no explicit receiptConfigMap override is supplied on a postcondition’s params or when a renderer builds a Job whose receipt CM name is derived from the Job’s own name.

extract_receipt_payload_json

Primary-first reader-side lookup gate for a receipt-CM’s data map — the substrate primitive that owns the (primary, fallback) key-precedence chain every receipt-CM reader threads through.

resolve_receipt_config_map_name

Resolve the receipt-ConfigMap name a JobAttested / ClosedLoopAuth postcondition (or any future postcondition that consumes a receipt) reads — honoring an operator-supplied receiptConfigMap: override verbatim when present, otherwise falling back to the substrate’s canonical default_receipt_config_map_name composer over job_name.

Type Aliases

RequiredPillar

One entry in the ReceiptEnvelope::REQUIRED_PILLARS closed-set table — the pair (diagnostic field name, wire-form accessor) that composes ONE required-pillar rejection through the shared [require_nonempty] peer. The alias gives the tuple a nameable type so downstream consumers (tatara-check receipt-inspector, an LSP hover on the const, per-pillar dashboard columns) bind to “one pillar’s descriptor” as a first-class handle rather than re-typing the underlying (&'static str, fn(&ReceiptEnvelope) -> &str) tuple at every consumer.