Archaeology
Regtest reference set
Sixty-three frozen scene captures the regtest harness compares against to detect drift.
~4 min read · 1210 words
The regtest reference set is the harness’s notion of what each scene
should look like, today, when nothing has drifted. It is a directory
per scene — sixty-three of them, indexed by ADS family and tag —
and each directory contains the frozen capture metadata, the
per-frame outcome record, and a self-contained HTML viewer. The frame BMPs themselves
(the actual pixels) live alongside this archaeology in
regtest-references/<SCENE>/frames/, which is gitignored to keep the
repository tractable. The files in docs/ps1/archaeology/regtest-references/
are the bookkeeping.
On this page
What this is
When a host engine produces a scene capture — say, a fresh recording of FISHING 1 against the host build at HEAD — the regtest harness compares that capture against the reference set. If the boot string matches, the seed matches, the frame count matches, and the per-frame state hashes match, the scene’s behaviour has not drifted. If anything fails to match, the harness reports which frame disagrees and points at the offending byte range.
The references were captured on 2026-03-28, against a known-good host build, with deterministic seed forcing and the host-side audio path silenced. They are deliberately frozen. New host changes that break this set are expected to either explain themselves (and roll the references forward, deliberately) or roll back. They are not auto-refreshed. The point of pinning them to a date is that drift can be detected by comparing against a fixed point.
The naming
Each directory is named <ADS>-<tag> — FISHING-1, BUILDING-7,
STAND-15. The ADS prefix matches the original Sierra animation script
file (FISHING.ADS, BUILDING.ADS, etc.) and the tag is the scene’s
position within that ADS, one-indexed. This is the same scheme the
project uses everywhere else: in the
scene ledger,
in the boot strings, in the bringup status reports.
The ten ADS families are:
- ACTIVITY — ten scenes (ACTIVITY-1 through ACTIVITY-12, with gaps).
- BUILDING — seven scenes.
- FISHING — eight scenes.
- JOHNNY — six scenes.
- MARY — five scenes.
- MISCGAG — two scenes.
- STAND — fourteen scenes (with non-contiguous numbering — STAND-13 and STAND-14 do not exist).
- SUZY — two scenes.
- VISITOR — six scenes (VISITOR-2 is intentionally absent).
- WALKSTUF — three scenes.
Sixty-three directories total, one per scene the project recognises
(matching the 63-row scene ledger).
There is no VISITOR-2 directory because Sierra’s VISITOR.ADS
skips tag 2 in the original game — it is not a captureable scene
the project chose to drop, it is a tag the source bytecode never
defined.
What’s in each directory
Each of the sixty-three scene directories contains exactly three files in
docs/ps1/archaeology/regtest-references/<SCENE>/:
-
metadata.json— the frozen capture’s identity. This holds the ADS name, tag, scene index, status (verified), the boot string used to launch the scene (window nosound story single 17 seed 1for FISHING 1, for example), the capture mode (scene-default), the forced seed, the forced island position and tide values when those were used to make the capture deterministic, the capture date (2026-03-28T15:30:44Z), the frame count (82 for FISHING 1), and the full ordered list of BMP filenames fromframe_00000.bmponward. -
result.json— the run outcome. This includes the capture configuration (frame budget, interval, timeout, CPU mode, forced seed), the outcome (exit code, frames captured, the rolling state hash, the scene-marker booleanslaunched/bmp_ok/bmp_fail/sprite_count_estimate, the visual-batch summary), and the absolute paths to the frames directory and the visual.json/visual-batch.json on the originating workstation. The state hash is the load-bearing field for regtest comparison. -
review.html— a self-contained HTML viewer that renders each frame as an<img>element with a sticky header for the boot string and frame budget. Opening this file in a browser walks the scene frame by frame; FISHING 1’s review is 24 KB and renders 82 frames at native size. The PNGs the viewer references are atframes-png/frame_NNNNN.png— sibling to the BMPs — and live alongside the archaeology rather than inside it.
The frame BMPs and PNGs themselves are not in the
docs/ps1/archaeology/ tree. They are checked-out as needed at the
sibling path regtest-references/<SCENE>/frames/ and
regtest-references/<SCENE>/frames-png/. Both directories are
gitignored. A clone of the repo gives you the metadata and the viewers;
running the regtest reference capture script regenerates the frame
images on demand.
How references get refreshed
Deliberately, when the host engine itself moves under them.
There are two times the references roll forward. The first is when a
host-side change is intentional and known to alter rendering — for
example, when the dirty-rect bookkeeping was rewritten and the per-tile
clear ordering shifted. In that case, the operator runs
scripts/capture-host-scene.sh against each affected scene, the new
metadata.json/result.json/review.html are written, and the diff against
the previous version of the metadata is what gets reviewed in code
review. Frame state hashes change, frame counts may change, the
rationale lives in the commit message.
The second is when the boot-string contract itself changes — when a new forced parameter is added or a default is renamed. That kind of change touches every scene at once. The reference set rolls in a single commit, and the commit message says why.
Outside those two cases, the references are frozen. If a fresh capture disagrees, the assumption is the fresh capture is wrong, not the reference. That is the entire point of having a reference set.
How regtest uses these
The regtest harness reads each scene’s metadata.json to know what boot string to issue and what frame count to expect. It reads result.json to get the state hash to compare against. The harness does not need to look at review.html; that file is for the human auditor.
The fast path is state_hash comparison: if the new run’s hash matches
the reference’s, the scene passed. The slow path, used when the hash
disagrees, is per-frame BMP diffing, which is what produces the
side-by-side review HTML the operator looks at to figure out what
changed. That slow-path diffing is documented in
the regtest docs along with the
exit codes and the harness invocation.
Each preserved reference also has a generated shelf page under /archaeology/regtest-references/cases/. Those pages expose the boot string, frame count, state hash, source artifacts, and links back to the corresponding scene ledger entry.
The sixty-three scenes
Each row links to the scene’s narrative page. The “ADS” column is the
animation script the scene comes from; the “Tag” column is its index
within that script. Status verified means the scene captured cleanly
on 2026-03-28 against the host build of that day.
Cross-links
- Regtest documentation — the harness that consumes this set.
- Per-case reference shelf — one generated page per frozen host baseline.
- Per-scene ledger — the same scenes with their bringup status, narrative, and screenshots.
- Devlog — entries that walk through reference roll-forwards when they happened.
- Era timeline — context for why the references were captured on 2026-03-28 specifically.