# Reconstruction Pitfalls **Project:** Neutron GamePort **Reviewed:** 2026-11-12 **Scope:** Remaining full reconstruction; local documentation review only. No new original-binary investigation, execution, build or runtime comparison was performed. ## Evidence and confidence The risks below are cross-referenced repository findings, not externally researched ecosystem claims. Their supporting source/component observations have the bounds specified in the linked reports; their implications for phase ordering are planning inferences. Whole-game accuracy is unverified. The generic `classify-confidence --provider curated --verified` seam returned LOW for this local-source provider; that label must not be mistaken for a new certification of the original experiments. Use the underlying receipts and their explicit execution scope when deciding admission. ## Critical pitfalls ### 1. Promoting component parity into live gameplay fidelity **Failure:** A matching pair, normal-response or reclip fixture is wired into every scene as though actual actors, registry membership and task effects were recovered. **Warning signs:** Completion claims cite only fixture counts; synthetic callback endpoints are described as real soldier/Jimmy policies; serialized GAM records become the active physical-body count. **Prevention:** Require actual class construction, activation, physical order, derived response, enter/stay/leave consumers and shared context before expanding each live adapter. Keep lab/outside capsule compatibility until its replacement dependencies close. Compare complete callback events, flags and state snapshots, not just final positions. Soldier complete174 and Jimmy204 remain record-only endpoints in the normal-contact report. **Phase implication:** Physical lifecycle and derived callbacks precede broad actor, enemy and gadget collision expansion. Sources: [normal contacts](../../docs/checkpoint/actor-normal-contacts.md), [physical registration](../../docs/checkpoint/physical-registration.md), [pair lifecycle](../../docs/checkpoint/pair-lifecycle.md), [coverage](../../docs/checkpoint/coverage.md). ### 2. Fixing symptoms by changing legitimate original movement **Failure:** A universal angle reset, added damping or imported tuned movement masks an ownership/scheduling divergence and removes original behavior. **Warning signs:** Ordinary landing bank is called a bug; fresh direct-scene and TSK-backed retained entry are given the same input order; JN-Engine's tuned movement becomes the oracle. **Prevention:** Preserve current movement and the successful first-story TSK retained-input correction. Trace the first divergent owner and caller phase before changing arithmetic. Recheck neutral return, sustained idle, held input, both turn directions, natural/skip completion and repeated scenes. External decompiler indexes provide leads only. **Phase implication:** Movement, control/animation ownership and route handoffs remain the first implementation checkpoint. The Carl initialization correction is existing work, not an untouched future fix. Sources: [menu/player lifetime](../../docs/gameplay/main-menu-player-lifetime.md), [movement stabilization](../../docs/gameplay/jimmy-movement-stabilization.md), [next-work plan updates](../../docs/checkpoint/next-work-plan.md). ### 3. Flattening physical registration and retained lifetime **Failure:** Deduplication, snapshot traversal or a generic reset silently changes ordering across fresh load, retained LOAD and RETURN. **Warning signs:** Constructor registrations are treated as final active membership; Init and PostLoad run as two global passes; setting a flag is treated as deleting a node; helper reuse/cleanup is assumed from a constructor edge. **Prevention:** Keep ordinary registry and physical list independent. Common registration can append an existing pointer; Jimmy's outer guard is separate. Preserve Init-before-parent-append and per-object Init/PostLoad traversal that can visit new tails. Recover actual helper removal, activation and re-entry before representing retained lists. Compare complete ordered lists across scene transitions. **Phase implication:** Lifecycle closure must precede arbitrary retained saves, general dynamic contacts and full-level progression admission. Sources: [registration](../../docs/checkpoint/physical-registration.md), [generated helpers](../../docs/checkpoint/vr04-generated-bodies.md), [dynamic context](../../docs/checkpoint/dynamic-context.md). ### 4. Caching values across source callbacks **Failure:** A refactor snapshots radius, inhibition, geometry permission or velocity before callbacks, changing subsequent reclip and final publication. **Warning signs:** Accessors become constructor constants; a callback's root edit is assumed to survive final local-root publication; collision mode and class-specific controller state share an enum or layout. **Prevention:** Preserve source getter order and independent fields. Test callbacks that mutate radius, flags, Y velocity and roots, plus retained old-hit/last-polygon behavior. Distinguish XYZ writes from full XYZW setters. Do not apply inherited reflection to Jimmy ordinary374, which takes its own material-policy path. **Phase implication:** Response adapters require live getter and ownership contracts before integration. Sources: [normal contacts](../../docs/checkpoint/actor-normal-contacts.md), [populated reclip](../../docs/checkpoint/dynamic-reclip.md). ### 5. Treating mathematically equivalent arithmetic as source equivalent **Failure:** Double promotion, normalization changes, reordered operations, triangle winding fixes or a faster broadphase alter strict branches, ties and accumulated state. **Warning signs:** Double intermediates are called an x87 emulator; only root tolerance is checked; duplicated source cell visits are removed; heading wraps or unclamped damping are normalized to conventional behavior. **Prevention:** Preserve evidenced float-store boundaries, kernel A,C,B winding, strict comparisons and traversal order. Record the first exact differing field and kernel argument. Widening precision or optimizing needs new differential evidence; degenerate inputs outside the bounded contract remain explicit unknowns. **Phase implication:** Preserve numeric probes throughout collision, actors and rendering-transform work; optimize after equivalence and measured need. Sources: [dynamic reclip](../../docs/checkpoint/dynamic-reclip.md), [normal contacts](../../docs/checkpoint/actor-normal-contacts.md), [codebase concerns](../codebase/CONCERNS.md). ### 6. Mistaking successful rendering or audio transport for original presentation **Failure:** Zero Vulkan errors, identical port screenshots or SDL dummy-stream success are reported as visual/audible parity. **Warning signs:** Merged far-plane policy implies per-layer fog/clipping fidelity; queue-empty replaces the original software sound clock; fixed 60 Hz is called recovered original scheduling; a correct transform kernel implies exact final OMT visual decomposition. **Prevention:** Compare original reference frames and sound intervals at identified states. Keep lighting/fog/material/blend/culling, sprite/pivot/decomposition, morph clocks, camera handoff, sound-bank/channel duration/attenuation and physical listening as separate targets. Retain device-independent numeric and transport checks, but report their narrower guarantees. **Phase implication:** Presentation and audio need source-specific recovery and integrated comparisons; start reference acquisition early rather than leaving all fidelity checks until release. Sources: [coverage](../../docs/checkpoint/coverage.md), [compatibility](../../docs/compatibility.md), [air bridge](../../docs/gameplay/jimmy-air-bridge.md). ### 7. Shipping a different revision from the one verified **Failure:** Current source, historical GPU tests and an older local package are merged into one completion claim; Wine is presented as native Windows verification. **Warning signs:** No exact package identity; user Windows reports attributed to an agent-run current build; startup black frames treated as a playable original reference; source-only changes inherit old SDL coverage. **Prevention:** Bind every receipt to source commit, package provenance, resource hashes, platform, scenario and validation setting. Run the same integrated route/control/window/audio checks on clean standalone Linux and native Windows packages. Keep original-component Wine32, port Wine64, whole-original reference and native Windows evidence separate. A blocked original runtime comparison remains an open release obligation. **Phase implication:** Reference/native Windows access is an early dependency; final full-game acceptance requires current integrated evidence, not a cross-publish alone. Sources: [progress](../../docs/progress.md), [compatibility](../../docs/compatibility.md), [codebase concerns](../codebase/CONCERNS.md). ## Further risks during full reconstruction | Risk | Warning sign | Prevention / roadmap consequence | |------|--------------|----------------------------------| | Asset inventory mistaken for playable coverage | All GAMs parse, therefore all levels are called complete | Track each original route, mechanic, actor and script consumer through implementation and runtime verification. | | Unsupported missing-content conclusion | Level3B/E GAMs described as missing, or absent OMTs called a proven fatal normal-game blocker | GAMs exist; distinguish their referenced absent archives from proven reachability. Investigate hardcoded/serialized routes without inventing substitutes. See [resource evidence](../../docs/analysis/level-resource-mapping.md). | | Save round-trip mistaken for load fidelity | Binary equality substitutes for repeated task/entity callbacks and retained scene ownership | Recover full original load UI, callback multiplicity, placement and helper lifetimes; test loading at real progression boundaries. See [coverage SAVE](../../docs/checkpoint/coverage.md). | | Invalid copied-code evidence accepted | Partial captures or relocation scans are counted as source behavior | Preserve full REA replies, source/probe hashes, reviewed operand mappings and completion markers; exclude invalid captures. Provider errors remain errors. See [normal contacts](../../docs/checkpoint/actor-normal-contacts.md). | | Original evidence altered or published | Extraction/probes target Original, or package files enter source commits | Generated copies/output only; verify all 539 baseline hashes, stage explicit source/docs paths and keep assets/packages local. | | Old narratives override newer receipts | A solved Carl bug is reopened from an older section | Follow dated continuation updates and exact receipt scope; reconcile current reports before planning changes. | ## Phase-specific gates 1. **Core movement/lifetimes:** preserve baseline, close real response/helper/state owners and validate lab → VR04 → lab → outside before expansion. 2. **Actors/gadgets/combat:** recover actual callbacks, RNG/action policies, activation and physical order before broader admission; bounded training-scene behavior is not full-game coverage. 3. **Progression/save/menu:** exercise complete authored routes, fresh/load/RETURN paths and task callbacks; do not equate parsable resources with playable progression. 4. **Rendering/audio/UI:** obtain observable original references, then address named state/clock/transform differences with isolated and integrated evidence. 5. **Release:** identify exact clean builds and resource manifests; verify full original content and native Linux/Windows behavior, with no unverified fidelity claims hidden by successful packaging. These gates are dependency recommendations inferred from current findings. They are not new binary findings or implementation approvals.