Files
Neutron/.planning/phases/01-reproducible-fidelity-baseline/01-RESEARCH.md
T

50 KiB
Raw Blame History

Phase 01: Reproducible Fidelity Baseline - Research

Researched: 2026-11-12 Domain: Local original/port capture, evidence provenance, comparison playback and native-platform receipts Confidence: HIGH for repository findings; MEDIUM for external capture approach; Windows execution remains unverified.

<user_constraints>

User Constraints (from CONTEXT.md)

The following decisions and discretion are copied verbatim. [VERIFIED: 01-CONTEXT.md, Implementation Decisions]

Implementation Decisions

Baseline journeys

  • D-01: Capture the continuous lab → VR04 → lab → outside journey and focused replays of specific moments, including dialogue return, banked jumps and landing.
  • D-02: Natural and skipped dialogue are equally required baseline cases.
  • D-03: Fresh entry and retained departure/return receive separate, equally required runs that preserve their respective lifetimes.
  • D-04: Include ordinary play and deliberate edge cases: held input through dialogue/return, banked jumps, landing and idle.

Comparison review

  • D-05: Open scenario results with paired original/port playback and links to corresponding images, audio and input/event traces.
  • D-06: Keep captures unobstructed by default; annotations and image differences are optional overlays.
  • D-07: Align key events while preserving actual recording speed and elapsed time; expose timing drift rather than concealing it through retiming.
  • D-08: Switch between original and port audio at corresponding moments, playing one recording at a time. Clearly label any review-only volume adjustment.

Evidence navigation

  • D-09: Browse the full-game ledger by gameplay capability (movement, contacts, gadgets, progression, visuals, audio), with links to scenarios, source evidence and platform receipts. Retain requirement traceability.
  • D-10: Each capability leads with what works, where it was verified, known differences and remaining acceptance conditions.
  • D-11: Show current applicable evidence first; retain expandable history with exact revisions and clear superseded labels.
  • D-12: Order discrepancies by player impact: blocking or visibly disruptive failures first, then subtler differences and missing verification. Missing evidence still leaves its acceptance open regardless of display order.

Original and Windows access

  • D-13: The user has a local Windows PC available to run prepared packages and return results. Availability does not itself establish successful native execution.
  • D-14: Prepare one local test bundle per checkpoint. A launcher collects source/package/resource identities, logs and captures, with clear user steps and local transfer instructions. Packages and captures remain local.
  • D-15: Run a separate generated copy of the original on that Windows PC through DxWnd. Record DxWnd version/configuration and execution/rendering limitations with each capture. Preserve wrapper provenance separately from native Windows port receipts; do not silently treat wrapper behavior as historical-platform parity.
  • D-16: Prepare all materials before one combined hands-on session per checkpoint, covering original-reference captures and port checks and collecting results together.

Carried-forward constraints

  • Preserve every original byte and never execute originals in place; verify against docs/original-manifest.json.
  • Preserve the implemented TSK-backed first-story input-order correction, fresh direct-scene order and legitimate landing bank. No invented leveling reset or replacement movement tuning.
  • Keep source recovery, inference, copied-original component execution, port runtime, Wine, DxWnd reference execution, cross-publish and native platform receipts explicitly distinguished.
  • Current Windows and original-reference acceptance remain open until new identified receipts demonstrate the required scenarios. A prepared bundle, wrapper launch or historical result alone cannot close them.
  • All builds/tests/captures/packages stay local. Push only verified source/tools/docs to the existing Gitea remote. Preserve current actor/collision admission gates and the lab/outside compatibility solver.

Agent discretion

No product decisions were explicitly delegated. Research/planning selects file formats, local viewer technology, capture tooling, event markers and bundle mechanics within the decisions above. The discussion does not require an external hosted website.

Deferred Ideas

None — discussion stayed within phase scope. Native execution and capture are future execution tasks, not results established by this discussion.

</user_constraints>

Summary

Build an evidence workflow around the established runtime. Extend preservation/capture orchestration, add identified scenario receipts and a capability ledger, and generate a local paired-media viewer. First prove one actual focused original/port comparison; then complete the full route and required case matrix. These are implementation recommendations within the explicit file-format/viewer/bundle discretion above.

The present reference harness captures three timed screenshots in isolated Wine, redirects ALSA to null and reuses an existing generated game directory. Its result is neither a continuous audible recording nor Windows/DxWnd execution. [VERIFIED: tools/recon/reference_capture.py:88-106,149-160] The package script records source revision, dirty state and package time, but those three fields are the scope of its identity block; extend them with hashes of executables, resources and captured artifacts. [VERIFIED: scripts/package.sh:48-52] Current reports explicitly keep original-game and native Windows verification open. [VERIFIED: docs/compatibility.md:3-24]

Primary recommendation: Use Python standard-library orchestration/validation, plain HTML/JavaScript playback, existing .NET/SDL replay hooks, a prepared local Windows launcher and an OBS recording preflight for the generated original through DxWnd and the native port separately. Do not change movement, collision admission or gameplay to make a capture pass.

Architectural Responsibility Map

The following is the recommended ownership boundary, not a claim about already implemented capture features.

Capability Primary Tier Secondary Tier Rationale
Preserve originals and stage execution copies Local tooling/filesystem Windows launcher Verify before copying; never use the source installation as working directory
Port input/event observations Application/platform boundary Local receipt collector Observe accepted input and scene/control changes at their actual owners
Original reference video/audio Windows recording tools Human operator Capture externally without pretending port instrumentation exists in the original
Event annotation and receipt validation Local tooling Human reviewer Separate manually observed events from instrumented state
Paired playback and capability browsing Browser/client Read-only loopback file service if needed No hosted application or database
Provenance and history Versioned JSON/Markdown plus local hashed artifacts Validator Source metadata is reviewable; large media stays local

Project Constraints (from AGENTS.md)

Actionable directives from the local and parent instructions and authoritative specification: [VERIFIED: AGENTS.md; ../AGENTS.md; ../prompt.MD]

  • Follow the parent instructions/specification; originals are authoritative, byte-identical, and never executed in place. Keep analysis, extraction, build and capture output separate.
  • Use shared C#/.NET 10, Silk.NET.Vulkan/Vulkan 1.3+ and SDL3 for Linux/Windows x64; keep builds/tests/packages local and the runtime offline.
  • Push only completed verified source/tools/docs to existing Gitea through the integrating primary; no original/package uploads, cloud CI or telemetry. This research assignment explicitly excludes committing/pushing.
  • Keep recovered source/data, inference, implementation, compilation, component execution, port runtime, Wine, wrapper reference and native verification distinct.
  • Preserve Jimmy movement, first-story TSK retained ordering, fresh direct-scene ordering and legitimate landing bank. Keep movement stabilization first; no new gadgets, movement replacement or invented angle reset.
  • Preserve live collision/helper/actor admission gates and lab/outside compatibility solver; do not equate isolated recovered components with live gameplay.
  • Use REA for any new original-binary investigation, preserve complete Evidence and cross-check bytes/addresses/provider gaps. This phase needs no new binary investigation.
  • Use bounded endian-aware parsing, portable/case-insensitive original paths, clear modules, deterministic tests and explicit unmanaged ownership. Build frequently if runtime changes.
  • Respect exclusive file ownership, at most three investigators alongside primary, primary integration, and unrelated working-tree files.
  • Update progress, tasks, decisions and compatibility evidence before transitions. Read checkpoint coverage/implementation and current reports before gameplay/package work.
  • Use local SDK environment and existing build/test/package entry points. Existing runtime claims require actual matching runtime evidence.

Phase Requirements

<phase_requirements>

Descriptions below are verbatim from the requirements file. [VERIFIED: .planning/REQUIREMENTS.md, Reference and Fidelity Baseline]

ID Description Research support
EVID-01 Every original file remains byte-identical to the recorded inventory throughout recovery, testing and release preparation; generated copies and outputs remain separate. Existing inventory; new bounded staging and pre/post identity guards
EVID-02 Reviewers can reproduce identified original-game reference scenarios from an isolated generated installation, with input/event, visual and audio captures where applicable; unresolved execution limitations are recorded and leave comparison acceptance open. Windows/DxWnd generated-copy procedure, external recording, event annotations, failure receipts
EVID-03 Reviewers can identify each capability's source evidence, implementation revision, runtime platform, current discrepancy and acceptance condition in a maintained full-game coverage ledger. Capability-led JSON/Markdown ledger, exact receipt references and explicit supersession
EVID-04 Testers can repeat the baseline movement/route scenarios on native Linux and native Windows with revision-specific receipts; cross-publish, Wine, component execution and native gameplay remain separately labeled. Shared scenario protocol, existing port hooks, separate native receipts and one combined Windows session

</phase_requirements>

Standard Stack

Do not add game or JavaScript packages for this phase. Existing package references are a constraint, not an instruction to upgrade dependencies.

Layer Use Version / evidence
Runtime Existing .NET and Vulkan implementation Project declarations verbatim: <TargetFramework>net10.0</TargetFramework>, <RuntimeIdentifiers>linux-x64;win-x64</RuntimeIdentifiers>, Include="Silk.NET.Vulkan" Version="2.23.0"; KHR/EXT references also declare Version="2.23.0". [VERIFIED: GamePort.csproj:4-17]
Evidence tooling Python stdlib: pathlib, hashlib, json, argparse, subprocess, unittest Python probe returned Python 3.12.3; inventory already uses these primitives. [VERIFIED: environment probe 2026-11-12; tools/recon/inventory.py:3-28]
Viewer Plain HTML, CSS, JavaScript and native media elements Media APIs expose time, rate, mute and playback; normal speed is 1.0. [CITED: https://html.spec.whatwg.org/multipage/media.html]
Recording OBS Studio locally on Windows; installed version recorded at execution Offline recording and MKV/remux workflow are documented; Windows Display Capture captures the monitor. [CITED: https://obsproject.com/kb/standard-recording-output-guide] [CITED: https://obsproject.com/kb/display-capture-sources]
Media inspection Existing ffprobe/ffmpeg locally; no automatic download Probe returned FFmpeg 6.1.1-3ubuntu5+esm15; ffprobe provides machine-readable stream/format inspection. [VERIFIED: environment probe 2026-11-12] [CITED: https://ffmpeg.org/ffprobe.html]
Original wrapper User's local DxWnd distribution/configuration, retained by hash and reported version Official project describes a Windows window hooker; no compatible Neutron profile was established here. [CITED: https://sourceforge.net/projects/dxwnd/]
Native launcher PowerShell/.cmd on Windows; shell/Python on Linux Recommendation: keep launch steps transparent; do not require the Windows user to install Python/.NET SDK for a self-contained port package

Installation: No npm/PyPI/NuGet additions proposed. Record actual Windows DxWnd/OBS/browser versions during preflight, rather than selecting a guessed latest version. Do not redistribute unreviewed third-party tools inside the checkpoint.

Alternatives Considered

Choice Alternative Decision
Plain local viewer React/Electron application Use plain media elements; component framework/desktop packaging adds no necessary capability here
External Windows recording Custom DirectDraw hook/injected original recorder Start externally; capture problems are observed limitations, not permission to modify original execution semantics
Read-only generated viewer tree Database/API service Use identified static records; no multi-user or remote persistence requirement
Manual focused original annotations Original input injection/whole-route automation Accept honestly labeled observed/manual markers initially; do not invent an original-side deterministic replay guarantee

Package Legitimacy Audit

Not applicable: no new ecosystem packages are recommended. Existing locked game dependencies remain unchanged. OBS/DxWnd/FFmpeg are external executables, so retain official provenance, actual versions and hashes during preparation rather than applying an npm existence check. This research neither installs nor runs them on Windows.

Existing Analogs and Verified Integration Points

Existing symbols/options below are quoted verbatim beside source citations. Proposed filenames later are explicitly recommendations, not existing paths.

Existing analog Verified fact and planning implication
Inventory def inventory(root): emits "path", "size", "sha256", "header"; mismatch raises "Original inventory differs from recorded baseline". Reuse the exact original manifest comparison; verify the copy before execution separately from legitimate post-run copy mutations. [VERIFIED: tools/recon/inventory.py:9-26]
Wine harness def inside(args):, def main():; timed for index in range(3):, time.sleep(args.seconds / 3); copy creation shutil.copytree(source, work/'game') only when absent. Preserve this narrow legacy path or separate Windows orchestration; do not relabel it. [VERIFIED: tools/recon/reference_capture.py:40-106,115-157]
Existing generated directories work.mkdir(parents=True, exist_ok=True), (work/'home').mkdir(exist_ok=True), default_output = 'artifacts/windows-smoke' if args.port_smoke else 'artifacts/asset-probe' if args.asset_probe else 'artifacts/reference'. These are created/selected by the harness, not a proposed new capture schema. [VERIFIED: tools/recon/reference_capture.py:152-160]
Package assembly out="dist/$rid", mkdir -p "$out/assets" (same line creates scene/audio/license/docs subdirectories), and > "$out/BUILD-INFO.txt". Its identity fields are source_commit=%s, source_dirty=%s, packaged_utc=%s. Hash a completed package tree and separate receipt; do not stamp a later docs HEAD onto an older DLL. [VERIFIED: scripts/package.sh:7-11,48-52]
Native CLI fixtures "--smoke-walk", "--smoke-jetpack", "--smoke-carl-cutscene", "--smoke-control-phases", "--smoke-practice-return". They are selected by explicit options; preserve their semantics and test identity. [VERIFIED: src/GamePort/Program.cs:263-283]
Idle regression LandWhileLocked and VerifyReturn execute bounded synthetic setup/resumption checks; they are not a human full-route recording. [VERIFIED: src/GamePort/Application/CutsceneIdleSmoke.cs:9-30]
Window regression WindowTransitionSmoke explicitly says "not a gameplay replay"; Directory.CreateDirectory(output); creates output. Use for resource/window lifetime, not route completion. [VERIFIED: src/GamePort/Application/WindowTransitionSmoke.cs:9-16]
Live observation seam var clock = Stopwatch.StartNew();, var stepClock = new FixedStepClock();, Sdl.SDL_PollEvent(out var e). Observe here and at transitions without altering update order. [VERIFIED: src/GamePort/Program.cs:819-826,1133-1148]
Scene continuation continuation = new(nextArgs.ToArray() carries the snapshot/retained state; log scene transition identity with one session lifetime spanning scene loops. [VERIFIED: src/GamePort/Program.cs:1846-1869]
Local test integration python3 -m unittest discover -s tests -p 'test_*.py' -v, managed projects and native/headless checks are composed in the existing script. [VERIFIED: scripts/test.sh:4-67]

Repository source files were opened directly in this session. Paths above identify inspected files; quoted generated-path expressions identify their actual creating code.

Architecture Patterns

System Architecture Diagram

Recommended data flow:

flowchart TD
  O[Immutable original installation] --> H[Preflight inventory verification]
  H -->|match| C[Fresh generated Windows reference copy]
  H -->|mismatch| F[Failure receipt; no execution]
  C --> D[DxWnd plus external recording]
  P[Identified offline port package] --> N[Native Linux or Windows play]
  N --> R[Port events, logs and external recording]
  D --> I[Local importer and artifact hash validation]
  R --> I
  I -->|valid and complete| E[Scenario receipts and capability ledger]
  I -->|missing or failed| U[Explicit open acceptance and discrepancy]
  E --> V[Paired local playback]
  U --> V
  V --> A[Human review with actual timing and one audio source]

These are NEW proposed files; the executor must create them explicitly:

  • Extend orchestration alongside the existing recon tools with a small capture-session/receipt validator module and command-line entry point.
  • Add a dedicated viewer source directory under tools/recon, containing static HTML/CSS/JS; generated local media/index belong below ignored artifacts output.
  • Add a versioned scenario protocol and capability-ledger JSON under docs/evidence, with a concise rendered Markdown entry point.
  • Add Windows preparation/collection scripts under scripts and Python regression coverage under tests.
  • Only add a focused application observation helper if required; keep runtime composition changes small and avoid growing the monolithic program with recorder policy.

These locations follow existing repository boundaries; all are proposed additions, not source-of-truth filesystem constants.

Pattern 1: Immutable session plus append-only observations

Recommended receipt model (new schema, not recovered source enums):

  • Versioned schema and stable scenario/session identity; case dimensions include dialogue policy, startup/entry lifetime, ordinary/edge input and route/focused scope.
  • Exact source revision, dirty flag/diff identity if applicable, package tree/executable hashes, original manifest hash, resource tree hash, launcher version/hash.
  • Platform OS/version, native versus Wine versus original-DxWnd classification; GPU/driver/Vulkan/SDL evidence for port; DxWnd binary/config hashes and actual settings for original.
  • Actual invocation, working directory, preflight/postflight inventory result, start/end monotonic and wall-clock timestamps, exit/abort result.
  • Per-artifact relative path, bytes, SHA-256, media duration/stream metadata and derivation chain. Keep raw recording and derived preview separately.
  • Event markers carry media timestamp, event identity, observation method, uncertainty and supporting frame/log; port simulation tick is a separate optional field. Never fill an original internal-state field from a component fixture.
  • Explicit missing artifacts, failure reason and remaining acceptance. An empty directory or exit-zero launcher cannot mean scenario pass.

Use a unique new directory per run and fail on accidental reuse. Check path containment before creating anything; resolve aliases/symlinks and reject overlap with originals in either direction. Verify original inventory before staging, verify pristine execution copy before running, and verify source originals after collection. Runtime writes in the generated copy are expected observations; preserve a pre-run identity manifest and post-run diff.

Pattern 2: One baseline protocol, multiple evidence methods

Recommended minimum matrix is fresh-session versus retained-entry × natural versus skipped dialogue, with ordinary and edge-input coverage in every combination. Make these explicit cells, not four loosely named recordings. The continuous journey must preserve real lab departure/VR04 return/outside progression; focused replays may use identified setups but cannot substitute for that continuity.

Define procedural checkpoints around: startup/control; dialogue entry; natural or skip boundary; first neutral and held-input resumed moments; left/right banked jump; support/landing; sustained idle; practice entry; VR04 use; RETURN/cleanup; lab exit and outside arrival. Log scene names, ownership and media markers as actually observed. Do not invent numeric timing tolerances: report raw deltas and annotation uncertainty pending original observations.

Record ordinary player input in native port sessions; existing injected smoke fixtures remain separate replay receipts. For the original minimum, use the same written input procedure plus manually annotated video/event intervals with uncertainty and held/released descriptions. Do not claim exact original key sampling without a proven original-side observer. If exact key transition recording is needed, add a bounded local recorder as a distinct instrumented run; preserve a clean visual/audio baseline.

Pattern 3: Two independent clocks, explicit alignment

Use native media elements at actual speed. Selecting an event pauses both sides and seeks each to its own observed event timestamp; resume at normal speed from there. Display both elapsed times and differences at later corresponding markers. Do not continuously seek the follower, alter playback rates or normalize run durations to manufacture agreement.

Separately show playback drift (browser rendering/buffering) and scenario event drift (actual recorded behavior). Buffering or missing media should pause the review and expose a warning; do not silently skip. Preserve asymmetric tails when one recording ends earlier. Mute both before changing audio selection; enable at most one. Keep any review gain visible and default to unadjusted audio. These are recommendations implementing D-05 through D-08; the underlying time/rate/mute interfaces are documented. [CITED: https://html.spec.whatwg.org/multipage/media.html]

Optional overlays must leave raw recordings available. Image differences require same viewport/aspect, crop metadata and matched event/frame provenance; numerical differences of lossy video are not a fidelity oracle. Use lossless identified stills for byte/difference assertions and label overlays as review aids.

Pattern 4: Capability ledger with explicit applicability

Create one structured authoritative ledger, and render its navigation rather than maintaining two independent status sources. Capability entries should retain requirement IDs and contain current behavior, scope/scene, source contract links, implementation revision, identified runtime receipts per platform, discrepancies by player impact, acceptance condition, and explicit supersedes/reason links.

Seed all full-game requirement categories, including unimplemented/unverified capabilities; do not limit the ledger to Phase 1 or to current movement fixtures. Retain detail rows or links from the existing checkpoint ledger. Its own legend explicitly distinguishes static/probe/managed/runtime scopes: **S**=static/data recovery, **P**=isolated original component probe, and **M**=managed port regression, **R**=port runtime. [VERIFIED: docs/checkpoint/coverage.md:63-66]

Current applicable evidence is selected by revision/content/scope/platform, not latest date. A docs-only revision does not invalidate matching unchanged runtime evidence; changed executable/resources require new applicability review. Keep contradictory/old claims in expandable history with explicit supersession, rather than rewriting history as if the defect never existed.

Minimum Viable Windows Recording and Bundle

Recommended executable sequence:

  1. Prepare one checkpoint root with a complete Windows port package, pristine generated original installation, original and package manifests, scenario instructions, a local result directory, launcher/collector, expected artifacts checklist and offline viewer. Include local transfer instructions only; no upload endpoint.
  2. Launcher preflight verifies bundled hashes and path separation, records OS/GPU/driver and tool identities, and asks the operator to select the actual DxWnd executable/profile and recording application. Reject missing dependencies with an actionable local receipt, without downloading tools automatically.
  3. Perform a short original-DxWnd and port video/audio preflight before the full route, within the same combined hands-on session. Check visible moving game content, intelligible game audio, correct capture area/aspect and elapsed-time behavior. Keep a failed preflight and its limitations.
  4. Start externally recorded sessions before game interaction. Use OBS Display Capture as the initial Windows method to avoid assuming old renderer hook compatibility; record only the intended monitor/game crop and retain raw frame/crop metadata. Use the applicable Linux OBS screen-capture source for Linux sessions. These source availability distinctions are documented. [CITED: https://obsproject.com/kb/display-capture-sources]
  5. Record locally to MKV and retain it; remux a separate browser-compatible preview if the tested browser needs it. Keep derivation command/tool version and original timestamps. OBS documents MKV and remux; ffprobe documents format/stream inspection. [CITED: https://obsproject.com/kb/standard-recording-output-guide] [CITED: https://ffmpeg.org/ffprobe.html]
  6. Run required continuous and focused cases in prescribed order, each with fresh/retained setup recorded. Preserve reference copy writes/settings per case. Native port output is collected separately from DxWnd wrapper output.
  7. Collector hashes recordings/logs/settings, writes structured per-run results and copies local annotations; record skipped/aborted cases honestly. Return one complete local result bundle; importing validates it before linking it into the ledger/viewer.
  8. Complete audible/visual review and inventory postflight, then update current receipts and open discrepancies. If original execution or native Windows fails, keep EVID-02/EVID-04 open and proceed only with independent permitted work.

DxWnd's project-maintainer logging procedure writes a log in the game execution folder. That makes a writable generated working directory essential; logging is not evidence the original behaved faithfully. [CITED: https://sourceforge.net/p/dxwnd/discussion/general/thread/6e4aa579/] Do not invent a working profile, forced renderer, speed limit or timer setting. Preserve the user's actual exported profile/config and identify any relocation edits. Rich diagnostic runs may perturb timing; label them separately.

Don't Hand-Roll

Problem Don't build Use instead Reason
Original-game recording New injected graphics/audio interception External recording preflight and explicit limitations Keeps Phase 1 bounded; original instrumentation has separate evidence costs
Media decode/playback Custom browser decoder or time stretcher Native video/audio elements Standard time/rate/mute APIs exist. [CITED: https://html.spec.whatwg.org/multipage/media.html]
Stream discovery File-extension inference ffprobe JSON output Stream/format metadata is inspectable. [CITED: https://ffmpeg.org/ffprobe.html]
Original integrity New incompatible inventory format Existing inventory helper and manifest Complete list equality is already enforced. [VERIFIED: tools/recon/inventory.py:21-26]
Gameplay route Scene swaps represented as completed route Human continuous capture plus existing bounded regressions Window fixture itself excludes gameplay replay. [VERIFIED: src/GamePort/Application/WindowTransitionSmoke.cs:9]
Evidence publication Cloud dashboard/CI/database Versioned metadata and local media Required by locked local-only decisions

Common Pitfalls

Failure Prevention and verification
Wine stills become original reference video Preserve execution category and require actual continuous audiovisual artifacts; harness uses three screenshots and null audio. [VERIFIED: tools/recon/reference_capture.py:90-106,159-160]
An old generated installation contaminates a fresh run Unique staging directories, pre-run copy hashes and explicit retained lifetimes; current harness only copies when the game directory is absent. [VERIFIED: tools/recon/reference_capture.py:157]
Native and cross-publish results collapse into one Windows status Validate receipt category, platform and scenario independently; current report explicitly excludes new Windows execution. [VERIFIED: docs/compatibility.md:18-24]
Identity says clean while captures came from other binaries Hash actual executable/resources and compare imported receipts; build script's source fields alone do not bind individual captures. [VERIFIED: scripts/package.sh:48-52]
Old Carl narrative reopens an implemented defect Apply later source-supported TSK correction; historical next-work prose is followed by explicit correction and open comparison boundaries. [VERIFIED: docs/checkpoint/next-work-plan.md:14-25]
Retained scenario restarts the process mid-route Carry one session/continuation identity through actual transitions; record real source lifetime and don't replace RETURN with a direct scene fixture
Viewer hides timing differences Fixed normal speed, explicit user-triggered event alignment, raw durations and visible drift
Silent/black recordings count as acceptance Preflight checks actual changing game content and audible output; metadata presence alone cannot prove either
Synthetic media/tests enter real ledger Require explicit synthetic designation and reject them as original/native acceptance; test fixtures may validate plumbing only

Code Examples

These are recommended new glue patterns, not existing repository APIs. No recovered game constants or schema enums are introduced.

Preservation command already supported

python3 tools/recon/inventory.py ../Original --verify docs/original-manifest.json

The positional root and "--verify" are implemented by the inventory command; mismatch exits before the success message. [VERIFIED: tools/recon/inventory.py:17-26] This exact invocation is mandated by project instructions. [VERIFIED: AGENTS.md, original preservation directive]

Paired audio selection and actual speed

// Recommended viewer glue; media APIs: WHATWG HTML media elements.
function selectAudio(original, port, useOriginal) {
  original.muted = true;
  port.muted = true;
  (useOriginal ? original : port).muted = false;
}
function alignAtObservedEvent(original, port, originalTime, portTime) {
  original.pause();
  port.pause();
  original.currentTime = originalTime;
  port.currentTime = portTime;
  original.playbackRate = port.playbackRate = 1;
}

Time, rate and mute controls are documented APIs. [CITED: https://html.spec.whatwg.org/multipage/media.html] Production glue must validate finite in-range marker times, await media readiness/seeking, expose play rejection/buffering and retain manual controls. No periodic resync is permitted by the recommended design.

Bounded Executable Slices

These are planning recommendations in dependency order. Each slice produces a usable part of the actual evidence workflow.

  1. Preserved session and receipt contract. Stage a generated original copy, verify original/copy hashes, collect an identified existing native port focused run and implement receipt validation. Include failing/stale/incomplete result paths. Define the full scenario matrix now; do not invent successful original captures.
  2. Local paired comparison vertical slice. Import one actual focused original-DxWnd/port pair when available and open it with media links, time markers, drift and exclusive audio selection. Until real original media arrives, labeled synthetic media exercises viewer plumbing only. Include a completed ready-to-run Windows preflight/bundle path so this is executable.
  3. Current full-game capability ledger. Reconcile current reports and checkpoint rows into capability-first entries covering every requirement category; link the working scenario viewer, actual receipts, discrepancies and expandable historical revisions. Run metadata validation without a GPU.
  4. Full route capture and native Linux baseline. Exercise continuous route and all required focused cases, including fresh/retained, natural/skipped and normal/edge inputs. Extend observation hooks only where needed without changing update order; repeat targeted protected movement/ownership checks if runtime composition changes.
  5. One Windows checkpoint and import/review. Finalize all materials before a single combined human session collecting original-DxWnd and native port cases; validate results locally, inspect audiovisual behavior, update evidence and leave explicit failures open. The phase cannot be fully accepted through a prepared bundle alone.

Dependencies: receipt format before viewer/import and launcher; real capture import before acceptance; ledger population and viewer work can otherwise progress independently with exclusive files. Human session happens after all independent preparation, not as repeated requests after each small task.

Environment Availability

Actual local probes on 2026-11-12; Windows availability is a user declaration, not a remote machine probe. [VERIFIED: environment probe this session] [VERIFIED: 01-CONTEXT.md, D-13 through D-16]

Dependency Available here Version / result Planner action
Python Yes 3.12.3 Use stdlib tooling/tests
Node Yes 24.22.1 Optional viewer pure-JS checks; do not add packages
Project SDK Yes after sourcing environment 10.0.402 Existing .NET 10 project and tests
ffmpeg / ffprobe Yes ffmpeg 6.1.1 distribution build Probe capabilities/version in receipt; do not silently assume codec availability
Chromium / Firefox Commands found Browser execution/version not tested here Verify actual playback and media decoding
OBS / PowerShell No command returned by command lookup here Windows installation not inspected Bundle dependency preflight; no execution guarantee
DxWnd on user's Windows Not inspected User's actual version/profile unknown Hands-on preflight and record provenance
Native Windows port/Vulkan Not executed this session Current report keeps acceptance open Human run required
Original installation Verified read-only inventory Output: Verified 539 unchanged original files Repeat before/after execution/package checkpoint
Knowledge graph Disabled Status response reported disabled Use direct source and current reports

No runtime suites, new original-binary probes, packages or native Windows captures were run for this research. Missing Windows execution is an explicit acceptance dependency; it does not block preparation, ledger or independent source-backed later work under the roadmap exception.

Validation Architecture

Validation is enabled in project configuration: "nyquist_validation": true and security "security_enforcement": true. [VERIFIED: .planning/config.json:23-25,49-51]

Test Framework

Property Value
Existing tooling tests Python stdlib unittest; existing tests import unittest and use temporary directories. [VERIFIED: tests/test_extractors.py:1-20]
Existing managed tests Standalone .NET console projects called through the local script. [VERIFIED: scripts/test.sh:6-54]
New quick command, proposed python3 -m unittest discover -s tests -p 'test_fidelity_*.py' -v
Pure viewer logic, proposed node --test tests/fidelity-viewer.test.mjs using built-in assertions/test runner; executor creates this file, no npm dependency
Existing full suite scripts/test.sh; native window option is NEUTRON_WINDOW_TEST=1 scripts/test.sh. [VERIFIED: docs/tasks.md:419-424]
Protected targeted checks source scripts/env.sh, then relevant existing managed Director/Checkpoint/BodyOwnership/Movement projects from script; no suite claimed run here

New quick-test filenames/commands are proposed Wave 0 additions, not present infrastructure. Keep their fixtures tiny so each quick command is bounded below 30 seconds; measure this rather than assuming the full original inventory or GPU suite meets that budget.

Phase Requirements → Test Map

Requirement Behavior Test type and command Existing?
EVID-01 Changed, missing and added original files fail; read-only staging leaves originals unchanged; copy identity verified before launch Proposed Python fidelity tests; existing real inventory command above at checkpoint Inventory yes; temporary-tree negative cases Wave 0
EVID-02 Valid run imports; bad hashes, missing media/audio, invalid/NaN/out-of-bounds markers, incomplete/failed launch remain open Proposed Python fidelity tests; media-probe tests with bounded fixtures Wave 0
EVID-02 Actual original game is visible/audible through identified DxWnd setup and required scenarios Human Windows capture/review plus receipt importer Explicit native/human dependency
EVID-03 Every requirement links to capability; missing evidence never becomes passed; current history selection respects content/platform/scope; dead/unsafe links rejected Proposed Python fidelity tests Wave 0
EVID-04 Reused session, package/resource mismatch and Wine labeled native are rejected Proposed Python fidelity tests Wave 0
EVID-04 Port native Linux and native Windows traverse matched full/focused cases with current revision Native play/replay, physical input/audio and review; existing smoke hooks supplement Hooks exist; new route receipts required
D-05–D-08 Event alignment, actual speed, timing drift, no mixed audio, asymmetric end/buffering/missing media Proposed Node pure-logic tests plus local browser integration/manual media review Wave 0

Meaningful Negative Cases

  • Source/output overlap in either direction; symlink escape; Windows drive/case/path traversal; reused session directory; filename containing shell metacharacters. Must fail before writing/launching.
  • One-byte changed copy/package/media; absent DLL/resource; unsupported receipt schema; source revision without actual package identity; cross-publish/Wine/component run offered as native gameplay. Reject promotion, retain diagnostic record.
  • Synthetic recording offered as original reference; null/missing audio offered as audible pass; zero-byte/black/frozen recordings. Metadata validator catches structural faults; humans check actual game visibility/audibility.
  • Fresh/retained and natural/skipped cells missing despite total clip count; full route replaced by unrelated scene snapshots; interrupted run silently marked complete.
  • Marker beyond duration, nonfinite time, absent corresponding event, different viewport or unknown media derivative; viewer must show missing state.
  • Audio switch while both playing, play promise rejection, decode failure, one video buffering/ending, and raw difference overlay enabled by default. Fail visibly without rate adjustment.

Sampling Rate

Per tooling commit run focused Python and viewer logic tests; per runtime observation change also run affected managed ownership/movement tests and a native focused replay. Per integrated checkpoint run the full existing local suite, original verification and identified native Linux route. Final Phase 1 acceptance additionally requires the combined Windows original/native session and actual media review. No automated fixture closes human acceptance.

Wave 0 Gaps

Create the proposed schema/validator tests, a tiny explicitly synthetic audiovisual fixture with known timestamps, viewer state tests and a completed Windows result/import checklist. Keep synthetic fixtures separated from real receipt indexes. Reuse the existing unittest and .NET conventions; no framework installation required.

Security Domain

This phase handles local binary/media paths and structured receipts, not accounts or remote application sessions. Recommended controls are narrowly scoped to that surface. OWASP's current published standard is ASVS 5.0.0; the inherited checklist's V2–V6 names refer to older numbering, so do not present them as current ASVS 5 chapter mappings. [CITED: https://asvs.owasp.org/]

Control domain (legacy checklist label) Applies Standard control
Authentication (V2) No accounts proposed Keep service local and read-only; no new authentication system
Session management (V3) No web login session Capture session identity is provenance, not an auth session
Access control (V4) Yes, filesystem boundary Allowlisted checkpoint root, resolved path containment, no original directory serving or write APIs
Input validation (V5) Yes Bounded JSON, finite timestamps, relative-path validation, media/receipt sizes, safe HTML text rendering
Cryptography (V6) Integrity only stdlib SHA-256 for artifact identity; hashes establish correspondence, not trust in arbitrary executables
Threat STRIDE Mitigation
Traversal/symlink or imported absolute path Disclosure/tampering Resolve under allowed root, reject escapes and overlaps before execution/import
Shell metacharacters in paths/config Tampering/elevation Argument arrays, no eval/shell interpolation; never execute a command supplied by a receipt
HTML/script in labels or report text Tampering textContent/escaped output; no untrusted HTML injection or remote resource URLs
Hash-valid but wrong evidence classification Spoofing/repudiation Typed receipt validation and human scope review; do not auto-promote by exit code
Local server exposes repository/originals Disclosure Serve only generated review tree on loopback, reject symlink escapes; no uploads
Unbounded JSON/media metadata or capture duration Denial of service Limits and explicit abort/error receipts; stream hashes and probe with timeouts

Python's standard handler follows symlinks outside the served directory, so merely choosing a directory is insufficient containment. [CITED: https://docs.python.org/3.12/library/http.server.html] Prefer a generated self-contained review tree or a bounded read-only handler. Test seeking behavior with the chosen server; do not assume all servers provide media byte ranges.

State of the Art

Existing/narrow approach Phase 1 delivery Evidence boundary
Wine still capture with null audio Continuous identified DxWnd recording on Windows Existing harness remains Wine evidence. [VERIFIED: tools/recon/reference_capture.py:90-106,159-160]
Build identity text Hashed source/package/resource/session binding Existing identity fields remain preserved. [VERIFIED: scripts/package.sh:48-52]
Chronological reports and bounded coverage rows Capability-led current applicability with history Existing legend already distinguishes S/P/M/R. [VERIFIED: docs/checkpoint/coverage.md:63-66]

No dependency modernization or runtime architecture migration is proposed.

Assumptions Log

# Claim Section Risk if wrong
A1 [ASSUMED] Windows external recording can capture this DxWnd game with usable audio and acceptable timing overhead Windows workflow Must be tested in preflight; failed capture keeps acceptance open
A2 [ASSUMED] A browser on each review machine can decode the selected preview format with usable seeking Viewer Test actual files/browser; retain raw recording and choose a verified derivative if necessary

These are execution hypotheses, not locked compatibility claims. Do not gate independent implementation on a vague preference question; resolve through the prescribed preflight/native acceptance checkpoint before claiming success.

Open Questions — RESOLVED planning dispositions

Each policy below is resolved for planning. Actual future capture/native outcomes remain execution acceptance dependencies; RESOLVED does not claim a successful Windows run.

  1. RESOLVED — Actual DxWnd version/config and original launch behavior: collect the user's actual executable/version/profile hashes and settings through plan 01-05 preflight, then record launch, visibility and audibility during plan 01-07's combined session. No guessed profile or compatibility guarantee is required to implement the collector. Failed/missing original execution keeps EVID-02 open.
  2. RESOLVED — Windows capture/audio/browser availability: use a local dependency checklist and short recording/decode/audio preflight in the prepared combined session (plans 01-05/01-07). Record observed versions/devices and blockers; do not automatically download tools or silently substitute black/silent media. Unavailable dependencies remain explicit pending capture acceptance.
  3. RESOLVED — Original input precision: use procedural inputs plus manually observed event markers, each labeled with method and uncertainty (plans 01-01/01-05/01-07). Port observations remain separately instrumented. No claim of exact original input sampling or deterministic original replay is made. Further instrumentation requires a concrete comparison need and the existing original-binary evidence rules.
  4. RESOLVED — Timing/image/audio tolerances: preserve actual-speed raw captures, elapsed values and drift without a blanket numeric parity threshold (plans 01-02/01-07). Record discrepancies/uncertainty; later system owners derive any acceptance tolerances from authoritative evidence. Tool acceptance tests validate timing/audio controls, not unestablished whole-game parity.
  5. RESOLVED — Historical applicability: bind claims to content/source/platform/scenario identity, preserve explicit supersession and reject ambiguous conflicting current evidence (plans 01-01/01-03/01-07). Report date/order alone never promotes historical packages to current proof. Missing underlying artifacts remain missing/historical rather than receiving fabricated identity.

Sources

Primary repository evidence (HIGH)

Directly opened this session: local/parent instructions and full specification; phase context/requirements/state/roadmap/config/project; current progress/compatibility/tasks/decisions; checkpoint next-work, coverage and implementation plan; main-menu player lifetime and Jimmy movement stabilization; REA report; codebase testing/conventions/structure; original manifest; inventory/reference tools; package/test/environment/window scripts; project declaration; Program and native fixtures. Inline citations give exact inspected anchors for implementation claims.

Official external documentation (MEDIUM)

Metadata

  • Standard stack confidence HIGH for existing repository/environment; MEDIUM for external recording workflow pending real-device verification.
  • Architecture confidence HIGH for inspected integration boundaries; proposed workflow requires implementation and end-to-end verification.
  • Pitfalls confidence HIGH where directly demonstrated in code; MEDIUM for browser/device capture risks.
  • Research-plan seam selected websearch for three external questions; classify-confidence returned LOW without verification and MEDIUM with verified official-source cross-check. External claims therefore use CITED tags.
  • Research-store persistence was attempted for all three digests but failed with ENOENT: no such file or directory, mkdir '/home/cristian/.gsd/research-cache'. No cache write claimed; research sources remain in this document. Do not change global home/config or unrelated repository files to repair a research cache.
  • Project graph disabled; no graph relationships used. No project agent skills configured.
  • Original verification run this session: Verified 539 unchanged original files. This is preservation evidence, not new gameplay execution.
  • No native Windows, DxWnd, original gameplay, browser playback or new gameplay compatibility claimed. No commit/push performed by this agent per exclusive assignment.
  • Research date 2026-11-12; revisit local evidence applicability whenever runtime/resources change; external recording guidance should be rechecked during Windows preflight.