# PostgreSQL TOAST read coverage

Status: tested research package for review, not a deployed article.

Question: can count/length/prefix probes and successful structural checks miss
a changed externally stored value? The actual PostgreSQL experiment answers
yes for a precisely bounded fixture and explains which stronger checks detect it.

## Contents

- synthesis.md: source-linked publication draft and implications.
- source-review.md: primary-source mapping, pinned source and runtime provenance.
- experiment.py: original executable experiment; accepts binary and scratch
  directories, never an existing data directory or remote database.
- results-1.json and results-2.json: raw stdout, stderr and return codes.
- test_experiment.py: mutation, oracle, replay and negative-control tests.
- verify.py and summary.json: evidence validation and derived result matrix.

## Replay without running a database

Use Python 3.12 (the recorded runtime was 3.12.3):

    cd content/research/postgresql-toast-coverage
    python3 -m unittest -v test_experiment.py
    python3 verify.py

Do not use python -O; assertions form part of the verification.

## Reproduce the actual experiment

Use an unprivileged account with PostgreSQL 16 server binaries, matching client
tools and the amcheck extension installed or extracted from the same distribution.
The measured package and hashes are in source-review.md. No Python packages are
needed. Prepare a short scratch directory under your own workspace and run:

    python3 experiment.py --server-bin /path/to/server/bin --client-bin /path/to/client/bin --scratch-root /path/to/scratch --output rerun.json

The harness creates private temporary clusters with local-only sockets, no TCP
listener, rejected host authentication, no inherited PG connection configuration,
and a fixed synthetic payload. It changes one byte only after a clean shutdown.
It stops its servers before removing only its own generated fixtures. The
generated result contains no production data. Never adapt it to mutate a live
or valuable database.

Each invocation executes 40 online probes and four offline utility calls.
Two recorded invocations produced the same semantic results. Repetition here
checks reproducibility, not statistical uncertainty or a population failure rate.

The full payload digest is computed by PostgreSQL and compared with Python's
independent expected digest. A successful hash query and a successful digest
comparison are deliberately separate outcomes.

## Integration boundary

This PR intentionally contains research evidence and a publication draft only.
After review, adapt synthesis.md to an Observatory article, publish code/results
and terminology on the corpus, and cross-link the existing checksum/restore
analyses. Do not claim the new result is already public, deployed or indexed.
No dependencies, UI templates, production data or deployment settings change.