Is the Draft That Passed the Gate the Same One You Published?

Issuing the Receipt

Here is the issuing side. It runs the gates, and writes a receipt only when all of them pass.

#!/usr/bin/env python3
"""gate_receipt.py — run quality gates and, on success, issue a digest-bound receipt."""
from __future__ import annotations
 
import hashlib
import json
import os
import subprocess
import sys
import time
from pathlib import Path
 
RECEIPT_NAME = ".gate-receipt.json"
 
 
def digest(path: Path) -> str:
    h = hashlib.sha256()
    with path.open("rb") as f:
        for chunk in iter(lambda: f.read(65536), b""):
            h.update(chunk)
    return h.hexdigest()
 
 
def run_gate(script: Path, targets: list[Path]) -> tuple[bool, str]:
    """Run a single gate. Returns (passed, combined output)."""
    proc = subprocess.run(
        [sys.executable, str(script), *[str(t) for t in targets]],
        capture_output=True,
        text=True,
        timeout=300,
    )
    output = (proc.stdout + proc.stderr).strip()
    return proc.returncode == 0, output
 
 
def issue(repo: Path, gates: list[Path], targets: list[Path]) -> int:
    results = {}
    for gate in gates:
        passed, output = run_gate(gate, targets)
        results[gate.name] = {
            "passed": passed,
            "gate_digest": digest(gate),
            "tail": output.splitlines()[-3:],
        }
        print(f"{'PASS' if passed else 'FAIL'} {gate.name}")
        if not passed:
            print(output)
 
    if not all(r["passed"] for r in results.values()):
        # Issue nothing, and actively invalidate any receipt left behind.
        (repo / RECEIPT_NAME).unlink(missing_ok=True)
        print("No receipt issued. Do not publish.")
        return 1
 
    receipt = {
        "version": 1,
        "run_id": os.environ.get("PIPELINE_RUN_ID", str(os.getpid())),
        "issued_at_wall": time.time(),
        "issued_at_mono": time.monotonic(),
        "gates": results,
        "artifacts": {
            str(t.relative_to(repo)): digest(t) for t in targets
        },
    }
    (repo / RECEIPT_NAME).write_text(json.dumps(receipt, indent=2, sort_keys=True))
    print(f"Receipt issued for {len(receipt['artifacts'])} files")
    return 0
 
 
if __name__ == "__main__":
    repo_root = Path(sys.argv[1]).resolve()
    gate_dir = Path(sys.argv[2]).resolve()
    files = [Path(p).resolve() for p in sys.argv[3:]]
    sys.exit(issue(repo_root, sorted(gate_dir.glob("*_gate.py")), files))

Three details in there are deliberate.

First, a failing gate deletes any existing receipt. If last night's receipt survives, tonight's failure gets masked by yesterday's success. A receipt carries meaning simply by existing, so forgetting to invalidate it is the worst possible bug.

Second, the receipt records a digest of each gate script. Rewrite a gate and leave an old receipt valid, and you have lost the answer to "passed according to which standard?"

Third, both a wall clock and a monotonic clock are recorded. Wall clocks step backwards under NTP correction and timezone handling. Monotonic clocks do not. Freshness checks use the monotonic value.

Verifying Before You Publish

The verifying side runs immediately before git push, or before a deploy.

#!/usr/bin/env python3
"""verify_receipt.py — verify a gate receipt. Exit non-zero on any mismatch."""
from __future__ import annotations
 
import json
import sys
import time
from pathlib import Path
 
from gate_receipt import RECEIPT_NAME, digest
 
MAX_AGE_SECONDS = 900  # a receipt is good for 15 minutes
 
 
def verify(repo: Path) -> int:
    receipt_path = repo / RECEIPT_NAME
    if not receipt_path.exists():
        print("FAIL: no receipt. Run the gates first.")
        return 1
 
    receipt = json.loads(receipt_path.read_text())
 
    age = time.monotonic() - receipt["issued_at_mono"]
    if age < 0 or age > MAX_AGE_SECONDS:
        print(f"FAIL: receipt is stale ({age:.0f}s old). Re-run the gates.")
        return 1
 
    failures = []
    for rel, expected in receipt["artifacts"].items():
        target = repo / rel
        if not target.exists():
            failures.append(f"{rel}: missing")
            continue
        if digest(target) != expected:
            failures.append(f"{rel}: contents changed")
 
    for name, meta in receipt["gates"].items():
        gate_path = repo / "_gates" / name
        if gate_path.exists() and digest(gate_path) != meta["gate_digest"]:
            failures.append(f"{name}: the gate itself was modified")
 
    if failures:
        print("FAIL: receipt does not match what is on disk:")
        for f in failures:
            print(f"  - {f}")
        return 1
 
    print(f"PASS: receipt verified ({len(receipt['artifacts'])} files, {age:.0f}s old)")
    return 0
 
 
if __name__ == "__main__":
    sys.exit(verify(Path(sys.argv[1]).resolve()))

Treating age < 0 as a failure is not paranoia. time.monotonic() has a per-process origin, so a negative age means the receipt came from a different process than the one verifying it. The check makes "valid only within a single run" explicit rather than assumed.

I chose fifteen minutes because in my pipelines the median gate-to-push interval is 40 seconds and the longest observed is about 6 minutes. That distribution differs per pipeline. Measure yours for a week, and I recommend setting the window at roughly twice your observed maximum.

How One Big Shell Command Erases the Observation Point

There is a second, deeper problem worth naming.

When the gate and the publish live in the same shell invocation, nobody — human or agent — gets to observe what happened in between. The agent reads only the final exit code and concludes the run succeeded.

Laying out the shell operators makes the risk concrete.

set -euo pipefail mitigates rows two and three. I still separate the invocations, for a simple reason: separation keeps the act of reading the result structurally present. In any step delegated to an agent, whether an opportunity to read exists maps almost directly onto how often things go wrong.

The receipt is the adhesive that makes separation safe. A verdict bound to contents survives the boundary between invocations.

Measured Results

As an indie developer I run unattended publishing pipelines across four repositories. Comparing 90 days before receipts and 90 days after:

All three pre-receipt incidents were discovered afterwards, by readers. The eleven blocked publishes would have followed the same route.

The cost is 0.41 seconds — under 0.3% of a single pipeline run. sha256 is fast relative to file I/O, and for tens-of-kilobytes text files it disappears into the noise. Seeing that number, I felt a pang about how long I had gone without it.

Rolling It Out in Four Stages

You do not need to switch everything on at once. This is the order that worked.

1. Measure. Log the gate's finish time and the publish's start time. That distribution tells you what freshness window to set. If you find a surprisingly long tail, suspect a concurrent process right there.
2. Issue only. Write receipts but do not block. Run for a week and watch how often mismatches appear. In my case, roughly one per week surfaced at this stage.
3. Warn. Print loudly on mismatch, still without blocking. This is where you find false positives. If CI regenerates derived artifacts, they will trip here — exclude them, or digest only the sources that precede generation.
4. Enforce. Let verify_receipt.py fail the publish, and split the gate and the push into separate invocations.

Do not skip stage three. Advancing to enforcement with generated artifacts still in the digest set will stop every legitimate publish. I wiped out a full night of runs learning that.

What Running It Taught Me

Modification times are not a substitute. My first attempt recorded mtimes instead of digests. It misses same-second rewrites, and granularity varies by filesystem. Digests leave no ambiguity.

Tools with a --fix mode leave more behind than the files they fixed. An integrity checker once left .bak siblings that git add -A happily committed. A receipt only protects the files it inspected — so bind the publish set itself into the receipt and reconcile it against git status --porcelain.

Keep the receipt out of the working tree. Otherwise it lands in a commit. Either .gitignore it or write it outside the repository, into a directory named for the run ID. I prefer the latter. A receipt is an artifact of the run, not of the product.

Decide Based on Reversibility

Not every pipeline needs this.

The axis is reversibility. A URL you published and then removed lives on in search indexes and in the memory of whoever read it. Against that kind of irreversibility, 0.41 seconds is remarkably cheap insurance.

Where to Start

Start by measuring. Log the gate's exit time and the publish's start time in your own pipeline — nothing more. Watch that gap for a week, and you will see exactly how wide the window is that you have been leaving open.

It took me months to notice the window existed at all. If this spares even one person the same quiet kind of failure, that is enough. Thank you for reading.