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

9.3 KiB

Phase 1: Reproducible Fidelity Baseline - Context

Gathered: 2026-11-12 Status: Ready for planning

## Phase Boundary

Establish reproducible original/port comparison scenarios, original-file preservation, a full-game coverage ledger and revision-specific native Linux/Windows baseline receipts (EVID-01 through EVID-04). Build on existing implementation and evidence. This phase establishes comparison infrastructure and captures; movement fixes and broader gameplay admission retain their later phase gates. Unavailable execution keeps affected acceptance open under the roadmap's source-backed-work exception.

## 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.

<canonical_refs>

Canonical References

Downstream agents MUST read these before planning or implementing.

Scope and preservation

  • .planning/PROJECT.md — full reconstruction goal, constraints and existing foundations.
  • .planning/REQUIREMENTS.md — EVID-01 through EVID-04 and full-game acceptance definitions.
  • .planning/ROADMAP.md — Phase 1 boundary, access exception and later phase dependencies.
  • AGENTS.md — current fidelity, source-control, REA and gameplay admission rules.
  • ../AGENTS.md — parent project requirements and evidence preservation.
  • ../prompt.MD — authoritative reconstruction specification; later push authorization supersedes older Git restrictions.
  • docs/original-manifest.json — original-file identity baseline.

Current evidence and protected behavior

  • docs/progress.md — implementation and revision-specific verification status.
  • docs/compatibility.md — platform receipts and explicit verification limitations.
  • docs/tasks.md — existing work and open gates.
  • docs/decisions.md — durable project decisions.
  • docs/checkpoint/next-work-plan.md — movement/recovery and route verification sequence.
  • docs/checkpoint/coverage.md — existing coverage/admission ledger.
  • docs/checkpoint/implementation-plan.md — reconstruction dependencies and remaining gates.
  • docs/gameplay/main-menu-player-lifetime.md — implemented TSK-backed startup-order correction.
  • docs/gameplay/jimmy-movement-stabilization.md — movement baseline and stabilization priority.

Reusable infrastructure

  • .planning/codebase/TESTING.md — local tests, fixtures and runtime evidence boundaries.
  • .planning/codebase/CONVENTIONS.md — bounded tooling and evidence-reporting conventions.
  • .planning/codebase/STRUCTURE.md — source, tool and documentation integration locations.
  • docs/rea.md — original-binary investigation workflow when needed.

No user-supplied DxWnd configuration document was provided; capture the actual local version/settings during preparation and execution, without inventing them. </canonical_refs>

<code_context>

Existing Code Insights

Reusable Assets

  • tools/recon/inventory.py — hash verification using the recorded manifest.
  • tools/recon/reference_capture.py — existing copied-original isolated Wine capture and port smoke infrastructure; useful starting evidence/tooling, not proof of Windows/DxWnd support.
  • scripts/test.sh — consolidated local Python, managed, rendering/audio and original-hash checks.
  • scripts/test-window-transitions.sh — existing local native window/transition verification.
  • scripts/package.sh, scripts/build-linux.sh, scripts/build-windows.sh — existing offline package/build paths and provenance foundations.
  • src/GamePort/Application/CutsceneIdleSmoke.cs, src/GamePort/Application/WindowTransitionSmoke.cs — existing native scenario fixture patterns; reuse suitable behavior instead of claiming component fixtures are gameplay.

Established Patterns

  • Python standard-library tooling and standalone .NET 10 console regression projects.
  • Saved original observations and full-state/event comparisons are distinct from integrated native captures.
  • Generated resources, screenshots, traces and packages stay in ignored local output, outside originals and source commits.
  • Durable reports identify exact revisions, supporting source evidence and bounded verification scope.

Integration Points

  • tools/recon/ for inventory/reference orchestration; scripts/ for local launch/test/package entry points.
  • src/GamePort/Program.cs and existing application fixtures expose bounded port capture routes; gameplay algorithms remain protected by current gates.
  • Existing docs/checkpoint/coverage.md and root status reports provide ledger inputs; reconcile current/superseded receipts rather than assuming report order establishes current proof.
  • A local comparison viewer connects scenario captures, optional overlays, timing markers, audio selection and capability-ledger links. Its implementation is a planning choice. </code_context>
## Specific Ideas

The user explicitly clarified: “Local testing on my windows machine will have the original game running via dxwnd”. Use that setup for the planned Windows original reference sessions. Compare original and port without simultaneous mixed audio or hidden timing correction. Prepare a complete, reviewable local checkpoint bundle before requesting hands-on execution.

## Deferred Ideas

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


Phase: 01-reproducible-fidelity-baseline Context gathered: 2026-11-12