Inspection Readiness & Audit-Trail Reporting

Every other domain in this platform writes to the append-only audit log; this one is what turns that log into evidence. An inspector does not ask to see your database — they ask for the complete, attributable history of one submission, one signature, or one deviation, in a form they can read without a Python interpreter, and they expect you to prove that history has not been altered after the fact. That proof is not a formatting exercise. It requires recomputing a cryptographic hash chain across every event tied to the record in question and showing that no link has been broken, reordered, or silently edited.

This area sits inside Core Architecture & Regulatory Mapping for Clinical Trials, downstream of every domain that emits an event into the append-only audit log — the IRB/ethics workflow transitions, the fallback routing deferrals, and the assembly and transport stages of the submission gateway. Reconstructing a defensible history therefore means querying across domains, not just one table. The concrete export a site coordinator or regulatory-affairs lead can hand an inspector is built step by step in Generating an Inspection-Ready Audit-Trail Export.

What inspection readiness actually requires #

An inspection finding rarely originates from a missing record — it originates from a record an inspector cannot trust, either because it lacks an identifiable author, because its timestamp cannot be pinned to when the event actually occurred, or because there is no way to prove nothing was deleted or reordered afterward. ALCOA+ names the properties a defensible record must hold: attributable to a specific person or system, legible, contemporaneous with the event, original (or a verified true copy), accurate, and — the property this domain exists to prove — complete and available on demand. A report generator that only formats rows from a table satisfies legibility and availability; it says nothing about completeness or about whether the underlying rows were tampered with. Verifying the hash chain is what closes that gap.

Decision flow #

Turning a raw event stream into inspection-ready evidence is a fixed sequence: query every event tied to the subject under inspection, order them chronologically, recompute and verify the hash chain across that ordered sequence, redact anything that must never leave the compliance boundary, and render the result as a human-readable report.

Note the loop implied by the dashed lines: the act of generating an inspection report is itself an event worth recording, so a reporting run appends its own provenance record — who ran it, over what date range, against how many events — back into the same log it just read.

Library and tooling landscape #

The chain-verification logic is small and security-sensitive enough that it belongs in reviewable, dependency-free code; the rendering step is where a templating or document library earns its place.

Deprecated dependency: PyPDF2 is end-of-life and its final releases simply re-export pypdf. If the rendered report is stamped, watermarked, or merged with a cover letter as a PDF, depend on pypdf directly and pin it, so the toolchain that produced an inspection export can itself be reconstructed later.

Core data model #

The domain operates on one immutable event type and two derived results: a verification outcome and a rendered report. Keeping verification and rendering as separate, composable steps means a broken chain is caught and reported clearly rather than silently formatted into a report that looks authoritative but is not.

"""Typed model for audit events and their verification result."""
from __future__ import annotations

from dataclasses import dataclass
from datetime import datetime


@dataclass(frozen=True)
class AuditEvent:
    """One immutable, hash-chained entry from the append-only log."""

    event_id: str
    subject_id: str          # the submission, sequence, or record under inspection
    ts: datetime              # timezone-aware, UTC
    actor: str                # attributable identity — never blank
    action: str                # fixed vocabulary, e.g. "sequence_assembled"
    prev_hash: str
    entry_hash: str
    fields: dict               # structured detail, PHI-free by construction


@dataclass(frozen=True)
class ChainBreak:
    """One detected discontinuity in the hash chain."""

    index: int
    event_id: str
    reason: str


@dataclass(frozen=True)
class ChainVerificationResult:
    """Outcome of verifying an ordered sequence of AuditEvent records."""

    subject_id: str
    event_count: int
    verified: bool
    breaks: tuple[ChainBreak, ...]
    verified_at: datetime

fields is deliberately typed as PHI-free “by construction” — the emitting domains are responsible for never writing protected health information into an audit event body, and this domain’s job is to trust that boundary and still redact defensively before anything reaches an inspector.

Step-by-step implementation #

1. Query every event tied to the subject, in a deterministic order #

Reconstruction starts from a single subject identifier — a sequence number, a submission ID, a subject enrollment ID — and pulls every event referencing it across all emitting domains, ordered by the append sequence rather than by wall-clock timestamp, since a clock can be wrong in ways an append order cannot.

"""Retrieve an ordered audit trail for one subject."""
from __future__ import annotations

from typing import Protocol


class AuditStore(Protocol):
    def events_for_subject(self, subject_id: str) -> list["AuditEvent"]:
        """Return every event referencing subject_id, in append order."""
        ...


def load_ordered_trail(store: AuditStore, subject_id: str) -> list[AuditEvent]:
    events = store.events_for_subject(subject_id)
    # Defense in depth: even if the store's contract guarantees append
    # order, re-sort explicitly so a reordering bug elsewhere cannot
    # silently corrupt the reconstruction.
    return sorted(events, key=lambda e: e.event_id)

Sorting by event_id assumes the identifier itself is monotonically assigned at append time (for example a ULID or a database sequence number) — never sort a hash-chained trail by ts alone, since a clock skew between writers could reorder events that the hash chain itself disagrees with.

2. Recompute the hash chain and detect any break #

The chain’s integrity guarantee rests entirely on one property: each event’s entry_hash is a deterministic function of its own fields plus the previous event’s entry_hash. Verification recomputes that function for every event and confirms both that the recomputed hash matches the stored one and that each event’s prev_hash matches its predecessor’s entry_hash.

"""Recompute and verify a hash-chained sequence of audit events."""
from __future__ import annotations

import hashlib
import json
from datetime import datetime, timezone


def _recompute_entry_hash(event: AuditEvent) -> str:
    body = {
        "event_id": event.event_id,
        "subject_id": event.subject_id,
        "ts": event.ts.isoformat(),
        "actor": event.actor,
        "action": event.action,
        "prev_hash": event.prev_hash,
        "fields": event.fields,
    }
    serialized = json.dumps(body, sort_keys=True, separators=(",", ":"))
    return hashlib.sha256(serialized.encode()).hexdigest()


def verify_chain(subject_id: str, events: list[AuditEvent]) -> ChainVerificationResult:
    breaks: list[ChainBreak] = []
    previous_hash = ""
    for index, event in enumerate(events):
        if event.prev_hash != previous_hash:
            breaks.append(ChainBreak(
                index=index, event_id=event.event_id,
                reason=f"prev_hash mismatch: expected {previous_hash!r}, got {event.prev_hash!r}",
            ))
        recomputed = _recompute_entry_hash(event)
        if recomputed != event.entry_hash:
            breaks.append(ChainBreak(
                index=index, event_id=event.event_id,
                reason="entry_hash does not match recomputed value — record may be altered",
            ))
        previous_hash = event.entry_hash

    return ChainVerificationResult(
        subject_id=subject_id,
        event_count=len(events),
        verified=not breaks,
        breaks=tuple(breaks),
        verified_at=datetime.now(timezone.utc),
    )

previous_hash starts as the empty string, which is the documented genesis value the first event in any chain must reference; a chain whose first event’s prev_hash is anything else is itself a detectable anomaly. Both checks — the prev_hash link and the recomputed entry_hash — are necessary: an attacker who edits one event’s fields and updates its own entry_hash to match is still caught, because every subsequent event’s prev_hash now points at a value that no longer appears anywhere in the corrected chain.

3. Redact anything that must never leave the compliance boundary #

Even though emitting domains are expected to keep PHI out of audit event bodies, the reporting stage applies a second, defensive redaction pass before anything is rendered — defense in depth against an emitting bug rather than a substitute for it.

"""Defensive redaction pass before rendering an inspection report."""
from __future__ import annotations

import re

_PHI_LIKE_KEYS = frozenset({"patient_name", "dob", "mrn", "ssn", "address"})
_EMAIL_PATTERN = re.compile(r"[^@\s]+@[^@\s]+\.[^@\s]+")


def redact_fields(fields: dict) -> dict:
    redacted = {}
    for key, value in fields.items():
        if key in _PHI_LIKE_KEYS:
            redacted[key] = "[REDACTED]"
        elif isinstance(value, str) and _EMAIL_PATTERN.search(value):
            redacted[key] = _EMAIL_PATTERN.sub("[REDACTED-EMAIL]", value)
        else:
            redacted[key] = value
    return redacted

A redaction that silently drops a field is worse than one that visibly marks it: an inspector must be able to see that something existed and was withheld for a stated reason, not encounter a gap indistinguishable from missing data.

4. Render an attributable, timestamped, human-readable report #

The final stage turns the verified, redacted event sequence into a document an inspector can read without tooling — a per-event table with actor, action, and timestamp, plus a summary block naming the verification outcome itself.

"""Render a verified audit trail into a plain-text inspection report."""
from __future__ import annotations

from datetime import datetime, timezone


def render_report(
    subject_id: str,
    events: list[AuditEvent],
    verification: ChainVerificationResult,
    generated_by: str,
) -> str:
    lines = [
        f"Inspection audit trail — subject {subject_id}",
        f"Generated by: {generated_by}",
        f"Generated at (UTC): {datetime.now(timezone.utc).isoformat()}",
        f"Events: {verification.event_count}",
        f"Chain verified: {'YES' if verification.verified else 'NO — see breaks below'}",
        "",
    ]
    for event in events:
        lines.append(
            f"[{event.ts.isoformat()}] {event.actor} — {event.action} "
            f"(event_id={event.event_id})"
        )
    if verification.breaks:
        lines.append("")
        lines.append("CHAIN INTEGRITY BREAKS DETECTED:")
        for brk in verification.breaks:
            lines.append(f"  index={brk.index} event_id={brk.event_id}: {brk.reason}")
    return "\n".join(lines)

The report states its own verification outcome in its first lines rather than burying it — an inspector should never have to independently re-run the chain check to learn whether the document in front of them is trustworthy.

Validation and audit-trail integration #

The reporting pipeline is unusual in this platform because its own execution is itself a regulated event: generating an inspection export is an action an inspector may later ask about — who ran it, for which subject, and did the run itself report a clean chain. Emit that provenance record into the same append-only audit log the report was built from, using the same event shape as every other domain so a report-generation event is itself later reconstructable.

"""Emit provenance for a completed inspection report run."""
from __future__ import annotations

import json
import logging

logger = logging.getLogger("inspection.reporting")


def record_report_generated(
    subject_id: str, generated_by: str, verification: ChainVerificationResult
) -> None:
    event = {
        "action": "inspection_report_generated",
        "subject_id": subject_id,
        "generated_by": generated_by,
        "event_count": verification.event_count,
        "chain_verified": verification.verified,
    }
    logger.info(json.dumps(event, sort_keys=True))

Because every domain in the platform — assembly and transport, ethics review, fallback routing — writes to the same log with the same event shape, a single reconstruction query joins across all of them by subject identifier, which is what lets an inspector ask “show me everything that happened to this submission” and get one coherent answer instead of five disconnected exports.

Error categorization and recovery #

A broken hash chain and a missing event are both alarming, but they demand different responses, and a reporting tool that treats every anomaly identically either cries wolf on routine data-entry gaps or, worse, quietly hides a genuine tampering signal inside a wall of warnings.

The governing principle is that anything touching chain integrity halts the report outright, while structural and informational anomalies are surfaced transparently inside a report that otherwise proceeds — an inspector should never receive a document that silently omits a known problem.

Compliance checklist #

• Every audit event carries an attributable actor, a UTC timestamp, and a fixed-vocabulary action name
• Events are ordered by append sequence for reconstruction, never by wall-clock timestamp alone
• The hash chain is verified by recomputing both the entry hash and the previous-hash link for every event
• A detected chain break halts report generation with a prominent, unmissable warning rather than a silent note
• A defensive redaction pass runs before rendering, independent of the emitting domain’s own PHI discipline
• The rendered report states its own verification outcome before listing individual events
• Generating an inspection report is itself recorded as an audit event, including whether the chain verified clean
• The reconstruction query spans every emitting domain by subject identifier, not a single table

FAQ #

What exactly does verifying the hash chain prove? #

It proves that no event in the sequence was altered or removed after the fact without leaving a detectable discontinuity. Recomputing each event’s own hash catches an edited field; checking that each event’s previous-hash link matches its predecessor catches a deleted or reordered event, because removing or changing one record breaks the link every later record depends on.

Why sort by append sequence instead of timestamp? #

Timestamps come from whichever system or worker emitted the event, and clocks can disagree by seconds or more across writers. The append sequence — a monotonically assigned identifier at write time — reflects the order events actually entered the log, which is the order the hash chain itself encodes; sorting by timestamp instead can silently present events out of the order the chain proves they occurred in.

What happens if the chain verification fails? #

Report generation halts and the failure is surfaced as the headline finding of the report rather than a footnote — the output states plainly that the chain did not verify, names the specific event index and reason, and treats the situation as a potential integrity incident requiring investigation, not something a re-run can quietly paper over.

Does the report ever include protected health information? #

It should not, by two independent controls: the emitting domains are expected to keep PHI out of audit event bodies in the first place, and the reporting pipeline applies its own defensive redaction pass before rendering. A field that still looks PHI-like after redaction is treated as a data-handling incident in its own right, separate from any chain-integrity finding.

Related #

• Up one level: Core Architecture & Regulatory Mapping for Clinical Trials
• Generating an Inspection-Ready Audit-Trail Export
• IRB/Ethics Workflow Mapping
• Fallback Routing for Portal Outages
• Electronic Submission Gateway & E-Signature Automation