Audit Logging & Immutability: Write-Once, Hash-Chained Ledgers for Production Finance

Every defensible number on a production draws its authority from the same place: a record that proves how it was computed and that nobody touched it afterward. A residual accrual, a turnaround penalty, a fringe remittance, and a cost-to-complete projection are all just figures until an examiner can reconstruct each one from an unbroken, tamper-evident trail. That trail is the shared spine underneath the entire Core Production Architecture & Taxonomy — the append-only, hash-chained ledger that every calculating engine on the platform writes to and that a completion guarantor or a union auditor reads back months later. This page specifies that spine: how a payload is canonically serialized and fingerprinted with SHA-256, how each entry is chained to the one before it so a retroactive edit cannot hide, how write-once storage keeps history from being silently rewritten, and how the whole chain is verified by recomputation. Get this layer right and audit readiness stops being a quarterly scramble; get it wrong and no downstream figure can be trusted even when it happens to be correct.

The distinction that matters is between logging and an audit ledger. Ordinary application logs are mutable, unordered, and best-effort — fine for debugging, useless for proving anything. An audit ledger is the opposite by design: append-only, ordered, cryptographically linked, and reproducible. It does not merely record that a figure was computed; it records the exact bytes that produced the figure, a hash over those bytes, and a link to the prior entry, so that the ledger as a whole either verifies cleanly or points precisely at the entry where it was broken.

Prerequisites and Expected Inputs

The reference implementation targets Python 3.11+, for standard-library zoneinfo timezone handling and modern union-type syntax. The dependency set is deliberately narrow so the audit path has as few moving parts as possible: Pydantic v2 for boundary schema validation and immutable models via model_validate, field_validator, and ConfigDict(frozen=True), as documented in the Pydantic v2 reference; the standard-library hashlib, json, decimal, and zoneinfo modules for fingerprinting, canonical serialization, currency-safe arithmetic, and timezone-aware timestamps; and, at production scale, SQLAlchemy to persist the ledger to an append-only table or polars to stream and re-verify large historical batches. Money is always Decimal, built from strings as Decimal(str(x)) — as the Python decimal module documentation explains, only fixed-point arithmetic gives the deterministic rounding a trust-fund remittance or a bond cost statement requires, and a float that slips into a hashed payload makes the fingerprint itself non-reproducible.

This spine assumes it is being written to, not read from, by the calculating engines. It does not compute residuals, penalties, or projections; it accepts an already-computed result plus its provenance and commits it immutably. Every record that lands here has already resolved to a taxonomic key through the classification model established across the wider Core Production Architecture & Taxonomy, so an audit entry ties back to exactly one budget line, one department, and one accountable operator.

Architecture: One Spine, Many Writers

The design principle is single-writer discipline in reverse: many engines write, but they all write through one narrow, uniform interface, and that interface is the only thing that ever appends to the ledger. The SAG-AFTRA Residuals Logic engine emits a ledger entry per resolved disbursement; the DGA Overtime & Turnaround Rules engine emits one per evaluated rest window; the Pension & Health Fund Calculations engine emits one per fringe remittance; and the variance and cost-to-complete figures assembled in Completion Bond Reporting & Guarantor Analytics are themselves reported against entries drawn from this same store. None of them owns its own private history. They hand a computed result and its inputs to the spine, which canonically serializes the payload, computes a SHA-256 over it, links it to the previous entry’s hash, and appends the sealed record.

The diagram below shows how heterogeneous engines converge on one canonical serialize-and-hash step, how each sealed entry links to its predecessor, and how a verifier recomputes the chain independently to prove nothing was altered after the fact.

Shared audit spine with many writers and one verifier Four calculating engines — SAG-AFTRA residuals, DGA turnaround penalties, pension and health fringe, and completion-bond variance reports — each hand a computed result to one shared canonical serialize-and-hash step. That step produces a sealed entry whose SHA-256 fingerprint links to the previous entry, and the sealed entry is appended to a write-once, hash-chained ledger. A verifier reads the ledger and recomputes every hash and link to confirm the chain is intact, following a dashed compare path back to the ledger. SAG-AFTRA residuals one entry per disbursement DGA turnaround one entry per rest window Pension & health fringe one entry per remittance Bond variance reports reported against entries Canonical serialize sorted JSON + SHA-256 + prev_hash Append-only ledger write-once · hash-chained no in-place update Verifier recompute every hash & link recompute & compare — mismatch names the broken entry

Two properties make this architecture defensible rather than merely tidy. First, the interface is uniform: whether the writer is a residuals calculator or a bond variance report, the entry carries the same envelope — a payload, a payload hash, the prior hash, an operator identity, and a timezone-aware timestamp — so a verifier never needs to know which engine produced an entry to validate it. Second, the append is total order: every entry knows its predecessor, so the ledger is not a bag of independent records but a single chain whose integrity is a global property. Break one link and every entry after it fails verification, which is exactly the behavior a guarantor wants — silent partial tampering is impossible.

Core Implementation

The spine is three cooperating pieces: a canonical serializer that turns any payload into stable bytes, a frozen entry model that seals a result with its fingerprint and its link to the prior entry, and an append-only ledger that enforces the chain on write. The serializer is the load-bearing part — if two runs of the same input can produce different bytes, the hash is worthless — so it sorts keys, strips incidental whitespace, and renders every value through a total, deterministic encoder.

import hashlib
import json
from datetime import datetime
from decimal import Decimal
from typing import Any
from zoneinfo import ZoneInfo

from pydantic import BaseModel, ConfigDict, Field, field_validator

GENESIS_HASH = "0" * 64  # the prev_hash of the very first entry


def canonical_bytes(payload: dict[str, Any]) -> bytes:
    """Deterministic serialization: sorted keys, no incidental whitespace,
    Decimals rendered as their exact string form so the hash is stable."""
    def default(value: Any) -> str:
        if isinstance(value, Decimal):
            return str(value)
        if isinstance(value, datetime):
            if value.tzinfo is None:
                raise ValueError("datetimes in an audit payload must be tz-aware")
            return value.isoformat()
        raise TypeError(f"unserializable audit value: {type(value).__name__}")

    return json.dumps(
        payload, sort_keys=True, separators=(",", ":"), default=default
    ).encode("utf-8")


def payload_hash(payload: dict[str, Any]) -> str:
    return hashlib.sha256(canonical_bytes(payload)).hexdigest()


class AuditEntry(BaseModel):
    """One sealed, immutable link in the audit chain."""
    model_config = ConfigDict(frozen=True)

    sequence: int = Field(ge=0)
    source: str                 # which engine wrote this, e.g. "sag_residuals"
    subject_id: str             # performer, crew member, cost code, etc.
    payload_sha256: str
    prev_hash: str              # SHA-256 of the previous entry's record
    entry_hash: str             # SHA-256 sealing this entry to the chain
    operator_id: str            # "SYS_AUTO" or a real user id for overrides
    recorded_at: str            # ISO-8601, timezone-aware (UTC)

    @field_validator("payload_sha256", "prev_hash", "entry_hash")
    @classmethod
    def _is_sha256(cls, v: str) -> str:
        if len(v) != 64 or any(c not in "0123456789abcdef" for c in v):
            raise ValueError("expected a lowercase hex SHA-256 digest")
        return v


def _seal(sequence: int, source: str, subject_id: str, payload_digest: str,
          prev_hash: str, operator_id: str, recorded_at: str) -> str:
    """Hash the fields that define the entry's place in the chain. The
    prev_hash is included, so any edit anywhere upstream changes this digest."""
    material = canonical_bytes({
        "sequence": sequence,
        "source": source,
        "subject_id": subject_id,
        "payload_sha256": payload_digest,
        "prev_hash": prev_hash,
        "operator_id": operator_id,
        "recorded_at": recorded_at,
    })
    return hashlib.sha256(material).hexdigest()


class AuditLedger:
    """Append-only, hash-chained ledger. The only mutation is append()."""

    def __init__(self) -> None:
        self._entries: list[AuditEntry] = []

    @property
    def head_hash(self) -> str:
        return self._entries[-1].entry_hash if self._entries else GENESIS_HASH

    def append(self, source: str, subject_id: str, payload: dict[str, Any],
               operator_id: str = "SYS_AUTO") -> AuditEntry:
        digest = payload_hash(payload)
        prev = self.head_hash
        sequence = len(self._entries)
        recorded_at = datetime.now(tz=ZoneInfo("UTC")).isoformat()
        entry_hash = _seal(
            sequence, source, subject_id, digest, prev, operator_id, recorded_at,
        )
        entry = AuditEntry(
            sequence=sequence,
            source=source,
            subject_id=subject_id,
            payload_sha256=digest,
            prev_hash=prev,
            entry_hash=entry_hash,
            operator_id=operator_id,
            recorded_at=recorded_at,
        )
        # In production the persist step targets write-once storage; the
        # in-memory list here stands in for that append-only table.
        self._entries.append(entry)
        return entry

    def __iter__(self):
        return iter(self._entries)

Three deliberate choices carry the audit weight. ConfigDict(frozen=True) makes a sealed AuditEntry immutable in the process, so no downstream caller can quietly reassign a hash or an operator after the record is committed. The prev_hash is folded into the material that produces entry_hash, which is what turns a list of independent hashes into a chain: an edit to entry five changes entry five’s entry_hash, which was the prev_hash of entry six, which changes entry six’s entry_hash, and so on to the head — so tampering is not a local event but a chain-wide one. And canonical_bytes refuses to serialize a naive datetime or an unrecognized type at all, because the failure mode you cannot tolerate is a hash that silently depends on dictionary ordering or platform float formatting. The mechanics of the append-only store itself — object-lock storage versus an event-sourced table — are developed in Designing Write-Once Audit Ledgers in Python, and the chaining and recomputation logic in depth in Hash-Chaining Cost Ledger Entries for Tamper Evidence.

What a Guild and a Bond Auditor Actually Verify

An audit spine exists to satisfy two distinct readers, and their questions differ. A trust-fund examiner from the Screen Actors Guild – American Federation of Television and Radio Artists (SAG-AFTRA), the Directors Guild of America (DGA), the Writers Guild of America (WGA), or the International Alliance of Theatrical Stage Employees (IATSE) is asking a contribution question: did every hour that generated an obligation produce a remittance at the contractual rate, and can you prove the figure was not adjusted after the reporting deadline passed? A completion guarantor is asking a reserve question: is the cost-to-complete you are reporting reconstructable from primary records, and can you prove no draw against contingency was backdated to make a covenant test pass? Both questions reduce to the same technical guarantee — an entry, once written, is fingerprinted, chained, and immutable — but they read different fields.

For the guild reader, the entry’s subject_id, source, payload_sha256, and recorded_at establish that a specific person’s specific obligation was computed at a specific time under a specific engine, and the operator_id distinguishes an automated run from a human override. For the bond reader, the chain property is the point: because Completion Bond Reporting & Guarantor Analytics reports variance and cost-to-complete against entries in this ledger rather than against a mutable working total, a guarantor can pin a reported figure to a sequence range and re-verify that range independently. The immutable modeling this depends on is the same one specified in Production Schema Design — a new versioned record for every change, never an in-place update — so the audit spine and the transactional schema tell one consistent story rather than two that must be reconciled.

The bond dimension is not decoration. A guarantor releases reserves against evidence, and the single fastest way to freeze a release is a report whose underlying figures cannot be reproduced. When a variance report says a category ran over by a given amount, the guarantor’s analyst wants to walk from that number to the exact ledger entries that compose it and confirm none was altered after the cost report was cut. A hash-chained spine makes that walk mechanical: the report cites sequence numbers, the analyst recomputes the chain over that span, and either it verifies or it names the entry that does not.

Error Handling and Quarantine

Not every record that reaches the spine is fit to be sealed. A payload carrying a float money field, a naive datetime, a subject_id that does not resolve to a known cost code, or a source the ledger does not recognize is not an audit entry — it is a defect, and sealing it would poison the chain with an unreproducible fingerprint. The discipline mirrors the boundary contract used across the platform: the ledger append validates the payload’s serializability first, and a payload that cannot be canonically serialized is diverted to a quarantine store rather than chained. Critically, the quarantined record still gets a SHA-256 hash of its raw bytes and a reason code, so a production accountant can triage the exact rejected payload without it ever contaminating the append-only ledger.

The diagram below shows the split: a serializable, well-formed payload is sealed and chained onto the ledger, while a payload that fails the serialization or resolution gate is diverted verbatim — with its own hash and a reason code — to a separate exception store that the ledger’s verifier never has to reason about.

Sealing a valid payload versus quarantining a defective one An incoming audit payload hits a serializability and resolution gate. A valid payload is canonically serialized, sealed with a SHA-256 fingerprint and the previous entry's hash, and appended to the write-once hash-chained ledger. A defective payload — one carrying a float money field, a naive datetime, an unknown source, or an unresolved subject id — is diverted to a separate exception store that keeps the raw bytes, their SHA-256 hash, and a reason code. A barred, dashed link shows the quarantined payload never enters the chained ledger. SEAL & CHAIN QUARANTINE Incoming audit payload Serializable? subject resolves? valid defect Canonical serialize + SHA-256 Seal with prev_hash Append-only chained ledger Payload defect • float monetary field • naive (non-aware) datetime • unknown source engine • unresolved subject id exception store · raw bytes · SHA-256 · reason_code never chained

The reason a quarantined payload still gets hashed is forensic. A rejected record is evidence too: it proves the platform saw a malformed input and refused it rather than silently coercing it, and the hash lets an examiner confirm the quarantined bytes are the exact ones the engine emitted. This is the same quarantine contract enforced upstream at ingestion, so a defect caught at the audit boundary is triaged the same way as one caught at parse time — reason code, original bytes, hash — and never re-enters the ledger by a side door.

Verification

An audit ledger is only worth its storage cost if it can be checked without trusting the process that wrote it. Verification recomputes the chain from a known anchor and confirms three invariants for every entry: that the entry’s payload_sha256 still matches an independent re-hash of its payload, that its prev_hash equals the previous entry’s entry_hash, and that its entry_hash equals a fresh _seal over its own fields. A single mismatch is not a soft warning — it is a proof that either a payload or a link was altered after sealing, and the verifier reports the first sequence at which the chain breaks so the tampering is localized rather than merely detected.

def verify_chain(entries: list[AuditEntry],
                 payloads: dict[int, dict]) -> None:
    """Recompute the whole chain. Raises at the first broken link, naming
    the sequence — so a guarantor's analyst gets a pointer, not a verdict."""
    expected_prev = GENESIS_HASH
    for entry in entries:
        seq = entry.sequence
        # 1. The payload still hashes to what was sealed.
        if payload_hash(payloads[seq]) != entry.payload_sha256:
            raise ValueError(f"payload tampered at sequence {seq}")
        # 2. The link to the predecessor is intact.
        if entry.prev_hash != expected_prev:
            raise ValueError(f"broken chain link at sequence {seq}")
        # 3. The entry seals its own fields correctly.
        recomputed = _seal(
            entry.sequence, entry.source, entry.subject_id,
            entry.payload_sha256, entry.prev_hash,
            entry.operator_id, entry.recorded_at,
        )
        if recomputed != entry.entry_hash:
            raise ValueError(f"entry hash mismatch at sequence {seq}")
        expected_prev = entry.entry_hash

Beyond the chain check, a healthy audit posture surfaces a small set of period metrics that read as an early-warning signal rather than a post-mortem: the count of entries sealed per source, the count and reason-code distribution of quarantined payloads awaiting triage, and the number of entries carrying a real operator_id rather than SYS_AUTO — because a spike in human overrides is precisely the pattern a guarantor wants explained before it cuts a report. A run whose chain verifies end to end, whose quarantine tail is short and explained, and whose override count is accountable is a run a completion guarantor and a union examiner can both sign off without a reserve hold. That is the whole purpose of the spine: to convert every production-finance figure from an assertion into a reproducible, tamper-evident fact.

Up: Core Production Architecture & Taxonomy