geno_lewm.provenance.receipt

receipt

Receipt writer / reader (RFC-0011).

Receipt schema v1.0.0. The on-disk format is canonical JSON so two identical Python Receipt objects produce byte-stable disk content; the loader rejects malformed receipts and unknown top-level keys. checksum_only is the only accepted provenance kind.

ReceiptOutput dataclass

ReceiptOutput(sigma_raw: float, sigma_calibrated: float, bucket_id: str, confidence: float, low_confidence: bool)

Score-call output committed by the receipt.

ReceiptRuntime dataclass

ReceiptRuntime(backend: str, device: str, geno_lewm_version: str, carbon_revision: str)

Runtime / environment block.

ReceiptProvenance dataclass

ReceiptProvenance(kind: str, details: dict[str, Any] | None = None)

Checksum provenance block serialized as provenance in v1 JSON.

Receipt dataclass

Receipt(schema_version: str, model_id: str, input_commitment: str, output: ReceiptOutput, output_commitment: str, calibration_hash: str, runtime: ReceiptRuntime, timestamp: str, provenance: ReceiptProvenance)

Top-level receipt (RFC-0011 §3.3).

compute_output_commitment

compute_output_commitment(output: ReceiptOutput) -> str

Compute the output-commitment hash for an output block.

Separated from Receipt so callers can pre-compute the commitment before assembling the receipt.

Source code in geno_lewm/provenance/receipt.py

def compute_output_commitment(output: ReceiptOutput) -> str:
    """Compute the output-commitment hash for an output block.

    Separated from ``Receipt`` so callers can pre-compute the
    commitment before assembling the receipt.
    """
    return canonical_json_sha256(asdict(output))

write_receipt

write_receipt(receipt: Receipt, path: str | Path) -> Path

Write a receipt as canonical JSON; round-trip byte-stable.

Source code in geno_lewm/provenance/receipt.py

def write_receipt(receipt: Receipt, path: str | Path) -> Path:
    """Write a receipt as canonical JSON; round-trip byte-stable."""
    p = Path(path)
    p.parent.mkdir(parents=True, exist_ok=True)
    p.write_bytes(receipt.to_canonical_json())
    return p

read_receipt

read_receipt(path: str | Path) -> Receipt

Load and validate a receipt from disk.

Source code in geno_lewm/provenance/receipt.py

def read_receipt(path: str | Path) -> Receipt:
    """Load and validate a receipt from disk."""
    p = Path(path)
    raw = p.read_bytes()
    try:
        d = json.loads(raw.decode("utf-8"))
    except json.JSONDecodeError as exc:
        raise ReceiptSchemaError(
            "receipt is not valid JSON",
            details={"path": str(p), "error": str(exc)},
        ) from exc

    if not isinstance(d, dict):
        raise ReceiptSchemaError(
            "receipt top-level must be an object",
            details={"path": str(p), "type": type(d).__name__},
        )
    return parse_receipt_payload(d)

parse_receipt_payload

parse_receipt_payload(payload: Any) -> Receipt

Validate a decoded receipt payload.

Source code in geno_lewm/provenance/receipt.py

def parse_receipt_payload(payload: Any) -> Receipt:
    """Validate a decoded receipt payload."""
    if not isinstance(payload, dict):
        raise ReceiptSchemaError(
            "receipt top-level must be an object",
            details={"type": type(payload).__name__},
        )

    _require_keys("receipt", payload, _REQUIRED_TOP)

    out = payload["output"]
    if not isinstance(out, dict):
        raise ReceiptSchemaError("output must be an object", details={"got": type(out).__name__})
    _require_keys("output", out, _REQUIRED_OUTPUT)

    rt = payload["runtime"]
    if not isinstance(rt, dict):
        raise ReceiptSchemaError("runtime must be an object", details={"got": type(rt).__name__})
    _require_keys("runtime", rt, _REQUIRED_RUNTIME)

    provenance = payload["provenance"]
    if (
        not isinstance(provenance, dict)
        or set(provenance) - {"kind", "details"}
        or "kind" not in provenance
    ):
        raise ReceiptSchemaError(
            "receipt provenance must be an object with 'kind' (and optional 'details')",
            details={"provenance": provenance},
        )

    return Receipt(
        schema_version=payload["schema_version"],
        model_id=payload["model_id"],
        input_commitment=payload["input_commitment"],
        output=ReceiptOutput(
            sigma_raw=out["sigma_raw"],
            sigma_calibrated=out["sigma_calibrated"],
            bucket_id=out["bucket_id"],
            confidence=out["confidence"],
            low_confidence=out["low_confidence"],
        ),
        output_commitment=payload["output_commitment"],
        calibration_hash=payload["calibration_hash"],
        runtime=ReceiptRuntime(
            backend=rt["backend"],
            device=rt["device"],
            geno_lewm_version=rt["geno_lewm_version"],
            carbon_revision=rt["carbon_revision"],
        ),
        timestamp=payload["timestamp"],
        provenance=ReceiptProvenance(
            kind=provenance["kind"],
            details=provenance.get("details"),
        ),
    )