docs(01): create verified fidelity baseline plans

This commit is contained in:
UnixNight committed 2026-11-12 17:38:34 -05:00
1 parent 36f24e4474
commit cf64b8ce18
21 files changed
+1473 -32

No files matched your search

@@ -0,0 +1,349 @@
# Phase 01: Reproducible Fidelity Baseline - Pattern Map
**Mapped:** 2026-11-12
**Files analyzed:** 22 candidate new/modified files (names below are planning recommendations)
**Analogs found:** 16 / 22, including partial matches; five primary source analogs
## Scope and naming
CONTEXT.md locks behavior, not new filenames. RESEARCH.md proposes recon orchestration/receipt validation, a static viewer, scenario/ledger documents, Windows scripts, Python/JavaScript tests and an optional application observer. The concrete names below make that scope assignable; the planner may consolidate modules. Existing reference capture behavior must keep its Wine identity. Optional runtime/package edits are conditional on a demonstrated observation/identity gap, not authorization to change gameplay.
No project-local `.codex/skills/` or `.agents/skills/` directory was found. Read local/parent AGENTS.md, the parent specification, context and research. All five primary source analog paths below were verified by nonempty `git ls-files -- <path>` output. The two documentary sources were also tracked. No runtime/install mirror is used.
## File Classification
| New/Modified File | Role | Data Flow | Closest Analog | Match Quality |
|---|---|---|---|---|
| `tools/recon/fidelity.py` | utility | file-I/O, batch | `tools/recon/reference_capture.py` | role-match |
| `tools/recon/fidelity_receipts.py` | model, utility | transform, file-I/O | `tools/recon/inventory.py` | partial: identity transform only |
| `tools/recon/fidelity_viewer/index.html` | component | event-driven | — | none |
| `tools/recon/fidelity_viewer/viewer.js` | component | event-driven | — | none |
| `tools/recon/fidelity_viewer/style.css` | config | transform | — | none |
| `docs/evidence/scenarios.json` | config | batch | — | none: new protocol |
| `docs/evidence/capabilities.json` | model | transform | `docs/checkpoint/coverage.md` | partial: domain content, no JSON schema |
| `docs/evidence/README.md` | config (documentation) | transform | `docs/checkpoint/coverage.md` | role-match |
| `scripts/prepare-fidelity-checkpoint.sh` | utility | batch, file-I/O | `scripts/package.sh` | role-match |
| `scripts/collect-fidelity-windows.ps1` | utility | event-driven, file-I/O | — | none: new native collector |
| `scripts/collect-fidelity-windows.cmd` | utility | request-response | `scripts/package.sh` | partial: generated launcher stub |
| `tests/test_fidelity_sessions.py` | test | file-I/O | `tests/test_extractors.py` | role-match |
| `tests/test_fidelity_receipts.py` | test | transform | `tests/test_extractors.py` | role-match |
| `tests/test_fidelity_ledger.py` | test | transform | `tests/test_extractors.py` | role-match |
| `tests/fidelity-viewer.test.mjs` | test | event-driven | — | none: no tracked JS test suite |
| `src/GamePort/Application/FidelityObservation.cs` (optional) | service | event-driven, file-I/O | `src/GamePort/Program.cs` | partial: observation seams only |
| `src/GamePort/Program.cs` (optional) | controller | event-driven | `src/GamePort/Program.cs` | exact: existing owner |
| `scripts/package.sh` (optional) | utility | batch, file-I/O | `scripts/package.sh` | exact: existing owner |
| `docs/progress.md` | config (documentation) | transform | `docs/compatibility.md` | role-match |
| `docs/tasks.md` | config (documentation) | transform | `docs/compatibility.md` | role-match |
| `docs/decisions.md` | config (documentation) | transform | `docs/compatibility.md` | role-match |
| `docs/compatibility.md` | config (documentation) | transform | `docs/compatibility.md` | exact: existing owner |
Generated `artifacts/` sessions, media, review indexes and `dist/` checkpoint bundles are outputs, not tracked source targets. `docs/original-manifest.json` is an input that must not be regenerated to accommodate changes.
## Pattern Assignments
### `tools/recon/fidelity.py` — capture/staging/import/review CLI
**Analog:** `tools/recon/reference_capture.py`.
**Imports** (lines 8–16):
```python
import argparse
import ctypes
import hashlib
import json
import os
from pathlib import Path
import shutil
import subprocess
import time
```
Copy only needed stdlib imports; a passive collector does not need the legacy X11 injection helper.
**Path guard** (lines 150–157):
```python
project = Path(__file__).resolve().parents[2]
source = project.parent/'Original'
default_output = 'artifacts/windows-smoke' if args.port_smoke else 'artifacts/asset-probe' if args.asset_probe else 'artifacts/reference'
work = (args.output or project/default_output).resolve()
if work.is_relative_to(source.resolve()) or source.resolve().is_relative_to(work):
p.error('Output must be separate from originals')
work.mkdir(parents=True, exist_ok=True)
if not args.port_smoke and not (work/'game').exists(): shutil.copytree(source, work/'game')
```
Reuse the resolved two-direction overlap rejection. Replace the legacy reuse semantics in new sessions: a session directory must be new, and copy identity must be verified before execution. Add imported relative-path containment, symlink/alias checks and original pre/post verification. Do not simply copy `exist_ok=True` into the new session allocator.
**Bounded subprocess/error pattern** (lines 206–207):
```python
print('Running isolated Windows port' if args.port_smoke else 'Running copied original', 'with no network and no original-directory mount:', work, flush=True)
subprocess.run(cmd, check=True, timeout=args.seconds + 40)
```
Use argument arrays and bounded timeouts. New orchestration must retain failure/abort receipts when launch/probe/import fails; the old top-level exception behavior alone does not supply that contract. Never execute commands read from a receipt.
**Evidence classification** (lines 213–216):
```python
if result['captures'][-1]['wineExit'] != 0 or not evidence_ok:
raise SystemExit('Windows port smoke did not pass; inspect wine.log (native Windows remains unverified)')
print('Windows port audio lifecycle passed under Wine; native Windows validation is still required' if args.port_cutscene_audio
else 'Windows port rendered under Wine; native Windows validation is still required')
```
Preserve the explicit platform qualifier. The harness takes three timed stills (90–106) and installs null audio (159–160); it is not an audiovisual/native/DxWnd capture template. Keep that path separate or unchanged.
### `tools/recon/fidelity_receipts.py` — identities and validation
**Partial analog:** `tools/recon/inventory.py`; no existing complete receipt/ledger schema was found.
**Imports and stable identity** (lines 3–13):
```python
import argparse
import hashlib
import json
from pathlib import Path
def inventory(root):
return [{"path": p.relative_to(root).as_posix(), "size": p.stat().st_size,
"sha256": hashlib.sha256(p.read_bytes()).hexdigest(),
"header": p.read_bytes()[:16].hex()}
for p in sorted(root.rglob("*")) if p.is_file()]
```
Reuse deterministic relative POSIX paths and SHA-256 meaning. Stream large media hashes rather than copying this small-original-file `read_bytes()` approach. Keep session/schema/case/platform/package/resource/artifact/marker validation in a small explicit module; these types are new tooling contracts, not recovered game enums.
**Fail-closed preservation** (lines 21–26):
```python
files = inventory(args.root)
if args.verify:
previous = json.loads(args.verify.read_text())["files"]
if files != previous:
raise SystemExit("Original inventory differs from recorded baseline")
print(f"Verified {len(files)} unchanged original files")
```
Keep the mandated command `python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json`. Validate pristine staged-copy identity separately; post-run writes in that copy are observations, not permission to change the original manifest. Reject incomplete media/audio, nonfinite/out-of-range marker times, mismatched identities and false native classifications; metadata success alone does not establish visual/audible parity.
### `scripts/prepare-fidelity-checkpoint.sh` and optional `scripts/package.sh`
**Analog:** `scripts/package.sh`.
**Entrypoint and offline layout** (lines 1–9):
```bash
#!/usr/bin/env bash
set -euo pipefail
source "$(dirname "$0")/env.sh"
scripts/build-linux.sh
scripts/build-windows.sh
python3 tools/extractors/prepare.py --all-scenes --audio sounds musicsecretlab
for rid in linux-x64 win-x64; do
out="dist/$rid"
mkdir -p "$out/assets" "$out/scenes/level1b" "$out/scenes/VR01" "$out/scenes/animations" "$out/scenes/actors" "$out/scenes/ui" "$out/audio/sounds" "$out/licenses" "$out/docs"
```
Reuse local SDK/build/resource entry points and quoted portable paths; checkpoint preparation should consume an identified completed package rather than silently rebuild a different one on import. The reference installation and capture tools stay separate from the port resources.
**Current provenance** (lines 48–52):
```bash
{
printf 'source_commit=%s\n' "$(git rev-parse HEAD)"
printf 'source_dirty=%s\n' "$(if [[ -n "$(git status --porcelain)" ]]; then echo yes; else echo no; fi)"
printf 'packaged_utc=%s\n' "$(date -u +%FT%TZ)"
} > "$out/BUILD-INFO.txt"
```
Retain these fields and bind completed executable/resource/package bytes in a separate manifest/receipt. A later documentation HEAD is not the older package's build identity. Avoid self-referential hashing: define manifest membership before hashing. Preparation produces one complete local bundle and transfer instructions before the combined human session; it does not close Windows acceptance.
### `scripts/collect-fidelity-windows.cmd` and `.ps1`
**Partial analog for `.cmd` only:** `scripts/package.sh` lines 144–145 contain generated launcher content:
```bat
@echo off
"%~dp0GamePort.exe" --assets "%~dp0assets" --scene "%~dp0scenes\level1b\scene.json" --level gam/level1b.gam --walk %*
```
Reuse script-relative quoted port paths. This stub does not collect hashes, OBS/DxWnd versions/settings, GPU/driver data, media or structured results. No tracked `.ps1` or standalone `.cmd` analog was returned by `git ls-files`. The new PowerShell collector requires a new bounded design from RESEARCH.md: preflight, generated-copy separation, explicit local tool selection, external recording checklist, separate original-DxWnd/native-port receipts, postflight and abort paths. Do not invent a working DxWnd profile or claim this stub proves Windows collection.
### Python test files
**Applies to:** `tests/test_fidelity_sessions.py`, `tests/test_fidelity_receipts.py`, `tests/test_fidelity_ledger.py`.
**Analog:** `tests/test_extractors.py`.
**Imports/root convention** (lines 1–12):
```python
import json
from pathlib import Path
import struct
import sys
import tempfile
import unittest
import zlib
ROOT = Path(__file__).resolve().parents[1]
ORIGINAL = ROOT.parent / 'Original'
sys.path.insert(0, str(ROOT / 'tools' / 'extractors'))
from omt import Database, FormatError, Reader, export_scene, read_canvas, read_material, read_shape, unpack_row, validate_output, write_png
```
Use only required imports and adapt the import directory to `tools/recon`; do not pull extractor modules into receipt tests.
**Small failing inputs** (lines 17–20):
```python
class BoundedReaders(unittest.TestCase):
def test_read_bounds_and_negative_size(self):
for size in (-1, 2):
with self.assertRaises(FormatError): Reader(b'x').take(size)
```
**Temporary output and real assertion** (lines 46–52):
```python
def test_png_roundtrip_payload(self):
rgba = bytes((4,5,6,255,10,20,30,0))
with tempfile.TemporaryDirectory() as t:
path = Path(t)/'test.png'
write_png(path, 2, 1, rgba)
data = path.read_bytes()
self.assertEqual(data[:8], b'\x89PNG\r\n\x1a\n')
```
Use temporary tiny original/copy/package/media trees for overlap, reuse, symlink escape, changed/missing/added file, bad marker, evidence classification and stale applicability failures. Keep synthetic media labeled and outside real receipt indexes. Unlike original-resource integration tests, quick negative tests should run without a local game installation/GPU. Proposed discovery remains `python3 -m unittest discover -s tests -p 'test_fidelity_*.py' -v`; measure bounded runtime. `tests/fidelity-viewer.test.mjs` has no same-language analog; use the research's built-in Node test approach for independent playback/audio state behavior.
### Optional `FidelityObservation.cs` and `Program.cs`
**Analog/integration owner:** `src/GamePort/Program.cs`. This is an application-boundary match, not an existing recorder API.
**Imports** (lines 1–8):
```csharp
using System.Diagnostics;
using System.Numerics;
using GamePort.Assets;
using GamePort.Application;
using GamePort.Audio;
using GamePort.Game;
using GamePort.Platform;
using GamePort.Rendering.Vulkan;
```
**Session lifetime** (lines 18–30):
```csharp
using var presentation = new RenderSession();
OriginalSave? carriedSave = null;
PlayerLevelState? carriedPlayer = null;
var returning = false;
var diagnostics = new DebugDiagnostics { Enabled = args.Contains("--debug-overlay") };
var energy = new PlayerEnergy();
var grapplerMemory = new GrapplerMemory();
while (true)
{
var result = Run(args, carriedSave, carriedPlayer, returning, diagnostics, presentation, energy, grapplerMemory, out var continuation);
if (result != 0 || continuation == null) return result;
args = continuation.Args; carriedSave = continuation.Save; returning = continuation.Returning;
carriedPlayer = continuation.Player;
```
A continuous-route observation owner belongs across this outer loop. Creating an unrelated new session for each `Run` would lose the retained departure/return relationship.
**Clock/event anchors:** line 819 starts `var clock = Stopwatch.StartNew();`; line 826 creates `var stepClock = new FixedStepClock();`; line 1133 polls `while (!headless && Sdl.SDL_PollEvent(out var e))`. Record monotonic elapsed time separately from simulation ticks; raw polled events and accepted gameplay input are different observations. Focus/debug/menu filtering occurs afterward, so polling alone is not an accepted-input trace.
**Retained transition publication** (lines 1866–1869):
```csharp
continuation = new(nextArgs.ToArray(), (debugCheckpointToLoad ?? interactions!.Snapshot()) with {
StartPoint = transitionRequest.StartPoint, StoredVector = debugCheckpointToLoad?.StoredVector ?? returnRoot }, transitionRequest.Returning,
debugCheckpointToLoad == null ? simulation?.CaptureLevelState(interactions!.Inventory.SelectedGadget) : null);
Console.WriteLine($"Loading original destination: {transitionRequest.LevelFile}, start={transitionRequest.StartPoint}; fade behavior remains unreconstructed.");
```
Observe at actual transition/input owners without changing these payloads or update order. TSK retained first-story order, fresh direct-scene order, landing bank, actor admission and lab/outside compatibility remain protected. Add the helper only if existing logs and external recording cannot supply required evidence. Preserve smoke-fixture classification; injected fixtures cannot replace ordinary full-route input.
**Existing application error boundary** (line 33):
```csharp
catch (Exception error) { Console.Error.WriteLine(error); return 1; }
```
A new optional observer needs explicit output ownership/disposal and bounded buffering. Do not add asynchronous gameplay ownership or a hidden retry/reset to achieve capture success.
### Ledger/protocol/viewer and durable reports
**Applies to:** `docs/evidence/scenarios.json`, `docs/evidence/capabilities.json`, `docs/evidence/README.md`, the three viewer sources, and `docs/progress.md`, `docs/tasks.md`, `docs/decisions.md`, `docs/compatibility.md`.
**Documentary analog:** tracked `docs/checkpoint/coverage.md` lines 63–66:
```markdown
**S**=static/data recovery, **P**=isolated original component probe,
**M**=managed port regression, **R**=port runtime. No row has full original-game
runtime comparison. Coverage does not mean implementation completeness.
```
Its table header at line 100 is `| ID / system | Recovered contract / anchors | Port implementation | Evidence / remaining gap | Next bounded action |`. Reuse the separation of source contract, implementation, actual evidence and remaining action. JSON schemas are new; keep requirement IDs, scope/platform/content identities, current applicability, discrepancies, acceptance and explicit supersession in one authoritative ledger, then render the Markdown/viewer. Historical dates alone cannot select valid current receipts.
**Status-report pattern:** tracked `docs/compatibility.md` lines 5–10:
```markdown
The user has a local Windows PC for combined reference/port checkpoint sessions.
Original-game reference execution is planned through DxWnd on a generated copy;
record Windows, DxWnd version/settings and capture limitations. Native Windows
port results remain distinct. This is setup availability and a discussion decision,
not a new launch, capture, original-comparison or native Windows verification
receipt. Existing verification claims and open acceptance dependencies remain.
```
Apply this evidence precision to all four durable status files. State what actually ran, on which revision/platform, and what remains open; do not copy old success totals into a new checkpoint.
There is no tracked HTML/CSS/JS viewer analog. Use RESEARCH.md's native media design: unobstructed paired playback, separately observed event seeks, rate 1, visible scenario/playback drift, exclusive audio, explicit buffering/decode/missing-media/asymmetric-end states, optional overlays and visible review gain. Use text rendering for imported labels. If a server is necessary, expose only the generated review tree on loopback with validated containment and tested seeking; never serve originals/the repository as the viewer root. The protocol must encode fresh/retained × natural/skipped × ordinary/edge and full-route/focused distinctions.
## Shared Patterns
### Filesystem boundary replaces authentication concerns
There is no account/authentication flow in this phase. Apply the `reference_capture.py:150–155` path guard to staging/import/review generation, then strengthen it for unique sessions and symlink-safe relative references. No hosted service or write API is required.
### Identity and failure remain separate from acceptance
Apply `inventory.py:21–26` fail-closed comparison to original preservation and `package.sh:48–52` build identity to packaging. Add actual byte hashes and typed evidence classifications; exit zero, valid JSON, a compiled binary, a prepared bundle and synthetic media cannot independently close original/native acceptance. Retain error receipts and diagnostic artifacts.
### Local outputs and bounded tools
Reuse `reference_capture.py` argument arrays, explicit cwd/log outputs and timeouts, and `test_extractors.py` temporary-fixture structure. Keep packages/media/generated review indexes local and ignored. No npm/PyPI additions or cloud storage are implied. Preserve the unrelated untracked `tools.yaml`.
### Movement and execution gates
All capture work observes the existing runtime. No movement reset, retiming, body admission, solver replacement or original-in-place execution is part of this map. Real Windows original-DxWnd and native-port results remain a combined human checkpoint after independent preparation is complete. If unavailable/failed, receipts retain open acceptance while independent source-backed work can continue.
## No Analog Found
| File | Role | Data Flow | Reason / fallback |
|---|---|---|---|
| `tools/recon/fidelity_viewer/index.html` | component | event-driven | No tracked web UI; use research's native media layout and actual local playback review |
| `tools/recon/fidelity_viewer/viewer.js` | component | event-driven | No paired player/state machine; implement/test explicit timing and audio rules |
| `tools/recon/fidelity_viewer/style.css` | config | transform | No established viewer stylesheet/design system |
| `docs/evidence/scenarios.json` | config | batch | New baseline protocol and required case matrix |
| `scripts/collect-fidelity-windows.ps1` | utility | event-driven, file-I/O | No native Windows preflight/collector; package launch stub is insufficient |
| `tests/fidelity-viewer.test.mjs` | test | event-driven | No tracked JavaScript testing pattern; use Node built-ins per research |
`fidelity_receipts.py` and `capabilities.json` also have no exact schema analog; their partial matches only cover identity and evidence vocabulary. `.cmd` has only the partial generated stub above. None of these gaps should be presented to the planner as an existing API.
## Metadata
**Analog search scope:** tracked `tools/recon`, `scripts`, `tests`, `src/GamePort/Program.cs`, checkpoint coverage and compatibility reports; repository-wide tracked `*.html`, `*.js`, `*.mjs`, `*.css`, `*.ps1`, `*.cmd` search returned no paths.
**Primary source analogs:** five: inventory, reference capture, package assembly, extractor tests, Program application boundary. Documentary inputs: coverage and compatibility.
**Coverage:** 3 exact-owner matches, 9 role matches, 4 partial matches, 6 without an analog (16 / 22 with some match).
**Pattern extraction date:** 2026-11-12.
**Validation:** tracked paths and line anchors inspected read-only; no runtime tests, original execution, build, package, commit or push performed. PATTERNS.md is the only write.