# 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 (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.
## 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
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 |
## 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: `net10.0`, `linux-x64;win-x64`, `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:
```mermaid
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]
```
### Recommended Project Structure
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
```bash
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
```javascript
// 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
1. **Actual DxWnd version/config and original launch behavior:** no successful Windows reference run is supplied by context. Prepare profile collection and preflight; retain limitations rather than inventing settings.
2. **Windows capture/audio/browser availability:** user's PC is available, but tools/devices are unprobed. Include dependency checklist and one short test inside the combined session.
3. **Original input precision:** minimum procedural input plus manual observed markers is honest but not exact original sampling. Label the method/uncertainty; add instrumentation only if a concrete comparison requires it.
4. **Timing/image/audio tolerances:** no universal numeric parity threshold is established. Capture raw values and uncertainty first; later system owners justify thresholds from original evidence.
5. **Historical applicability:** current reports contain historical package/runtime revisions and superseded defect narratives. Bind ledger claims by actual content and source report scope, not date or prose order.
## 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)
- https://sourceforge.net/projects/dxwnd/ — official wrapper project identity.
- https://sourceforge.net/p/dxwnd/discussion/general/thread/6e4aa579/ — project-maintainer logging procedure; historical guidance, not a tested current Neutron profile.
- https://obsproject.com/kb/standard-recording-output-guide — offline recording, MKV and remux (dated 2023-05-26).
- https://obsproject.com/kb/display-capture-sources — platform-specific display recording methods (dated 2022-01-11).
- https://html.spec.whatwg.org/multipage/media.html — native media time/rate/mute/playback; living standard checked 2026-11-12.
- https://ffmpeg.org/ffprobe.html — media format/stream inspection.
- https://docs.python.org/3.12/library/http.server.html — local serving and symlink caveat.
- https://asvs.owasp.org/ — current ASVS release identity.
## 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.