Files

21 KiB
Raw Permalink Blame History

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):

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):

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):

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):

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):

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):

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):

#!/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):

{
    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:

@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):

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):

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):

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):

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):

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):

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):

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:

**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:

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.