Skip to content

Parity Evidence

Jump to bottom
github-actions[bot] edited this page Aug 25, 2026 · 13 revisions

Parity Evidence

Status reviewed 2026-08-25. Evidence is cross-game and bounded. A green parser or fixture test is not automatically a real-media runtime claim.

What Are Pass Documents?

The parity-evidence/ directory contains source-lock evidence documents, each named pass{NNN}_{description}.md. Each document anchors a specific behavioral claim to:

  1. A reference source location (ReDMCSB function/file/line or skproject symbol)
  2. A binary offset or data table in the original executable
  3. A runnable verification path (test binary or probe command)

Pass documents are numbered sequentially. The repository currently contains thousands of checked-in evidence documents; use git ls-files parity-evidence/ | wc -l when an exact local count is needed.

Purpose

Source-lock evidence serves three functions:

  • Proves parity: documents that Firestaff's implementation matches the original engine's behavior at a specific decision point
  • Prevents regression: each pass document names a test that can be re-run to verify the claim still holds
  • Records provenance: captures exactly which reference source location or binary offset justifies each implementation choice

Structure of a Pass Document

A typical pass document contains:

# pass{NNN}: {title}

## Claim

{What this document proves}

## Source Reference

{ReDMCSB file:line, skproject symbol, or binary offset}

## Evidence

{How the claim was verified — binary analysis, source comparison, test output}

## Verification

{Exact command to re-run the proof}

Categories

DM1 PC34 Compatibility (*_pc34_compat.md)

764 documents covering:

  • Viewport wall/door/ornament routing
  • Movement completion matrix
  • Inventory slot placement and drag/drop
  • Combat timelines
  • Champion panel material
  • Original-transcript capture gates
  • Creature info table decode (G0243)

CSB PC34 Compatibility

Documents covering DSA opcode core, startup presentation, entrance/credits, HUD, viewport geometry, thing/sensor runtime, combat, saves, and media.

The native Atari STX route additionally has a real-media M12→M11 proof for the 50 Hz ANIMATE.SCR/ANIMATE.DAT title cadence, FTLCODE handoff and first runtime HUD/viewport frame. This is bounded startup evidence, not a claim of full campaign parity.

Its native Enter/Accept command reaches that authenticated FTLCODE handoff; CSB --platform pc instead fails closed before selecting media, since no original DOS/PC edition exists.

DM2

Documents covering GDAT material families, G1 record graphs, creature occupancy, combat drops, sound decode.

The authentic Amiga archive route additionally verifies its source-clipped RAW4 CHARSHEET frame (121×72 to 119×70) through the native GDAT/palette path. This is bounded inventory evidence, not full Amiga campaign parity.

Theron's Quest

Documents covering Track 02 IPL/stage-two handoff, the authentic JP Rev 1 MODE1/2352 initial Akutuba runtime handoff, level envelope and multi-level object tables. The JP runtime proof is bounded; it does not claim later-level or full gameplay parity.

The same real Track 02 is also bound by a source-only public consumer to all seven campaign dungeons (2,266 source objects total), including Drator/dungeon 2 (eight maps and 291 objects). It deliberately does not infer the transition, presentation, AI, combat or item-action semantics.

Nexus

Documents covering DGN geometry, MNS materials, Structure2/3, PRS3 topology, SAL/MAP audio, SLEV scripts and retail CUE→BIN CDDA source ownership. The CDDA evidence binds media only; native decoding/playback remains unproven.

The captured NBG1 receipt proves an enabled 256-colour bitmap layer, BMPNA palette bank 0 and hardware scroll origin (0,0). It is intentionally not a retail asset-to-VDP join; STABG stays no-draw until that separate proof exists. The full 512×256 indexed NBG1 span and its 256-entry CRAM are also decoded from that authentic capture in native code, but remain capture-only evidence.

Naming Convention

pass{NNN}_{game}_{version}_{feature}_{suffix}.md
  • {NNN}: sequential pass number (e.g., 1101)
  • {game}: dm1, csb, dm2, theron, nexus
  • {version}: v1 (V1 compatibility layer)
  • {feature}: descriptive feature name in snake_case
  • {suffix}: typically pc34_compat for PC 3.4 compatibility claims

What Pass Documents Are Not

  • They are not design documents or specifications
  • They are not test plans (the tests exist independently)
  • They do not substitute a synthetic capture for original evidence
  • They do not claim completeness — each document covers one specific point

Verification

To verify all pass documents' associated tests:

ctest --test-dir build -j4

Individual pass documents name their specific verification command in the ## Verification section.

Clone this wiki locally