# Reconstruction Architecture and Dependency Gates **Project:** Neutron GamePort **Researched:** 2026-11-12 **Scope:** Local repository research for the remaining full reconstruction; no binary analysis, source execution, implementation changes or new runtime verification. ## Recommendation Extend the existing explicit scene composition and recovered component architecture. Preserve the distinction between a recovered algorithm, a synthetic original-component comparison, a live scene adapter and verified whole-game behavior. Complete movement and interacting lifetimes before expanding gameplay. The architecture already supports playable scenes; replacing it with a new engine or a speculative universal solver would discard the source-order contracts that existing evidence establishes. This is a dependency analysis of current project reports and selected code, not independent certification of their original-binary findings. The generic CLI confidence classifier returns LOW for the `curated` provider label; it has no repository-evidence provider. Therefore the conclusions below state their documentary basis and limits rather than claiming a provider-certified HIGH confidence result. ## Existing Boundaries to Preserve | Owner | Existing responsibility | Remaining architectural obligation | |-------|-------------------------|-------------------------------------| | `Program.Main` / `RenderSession` | Persistent native window/Vulkan device and session diagnostics; scene replacement | Keep resource replacement separate from original object retention; retain explicit cleanup and native ownership | | `Program.Run` | Concrete scene composition, held input, fixed-step policy and callback scheduling | Extend actual per-object registry order, live mutation and phase ownership rather than treating grouped updates as original semantics | | `LabSimulation` / `PlayerSceneBinding` | Player body/controller/fire/control boundaries; fresh versus retained input ordering; script and vehicle bridges | Preserve independent control, body and effect eligibility, retained scalar ownership and authored transform publications | | `OriginalBodyPhysics`, static/dynamic/pair/normal components | Bounded recovered numeric and callback contracts | Admit only actor states whose membership, callbacks, live reads and helper lifetime have been recovered | | `SceneDirector` / interactions / tasks | Script actions, task broadcasts, cutscene control, contacts and transitions | Recover remaining real derived callbacks, action acceptance/completion and complete progression consumers | | `Assets` / offline extractors | Original-format decoding and prepared render/audio resources | Preserve source identity/material metadata, explicit missing resources and immutable originals | | Application visuals / renderer | Morphs, sprites, UI, camera projection and Vulkan resources | Replace named approximations with source-backed transforms, playback, materials, layers and render states | | `SceneAudio` / `SdlAudio` | Scene music/speech/effects and native stream ownership | Separate original handle/bank/software clocks from SDL transport; complete positional/lifecycle policies | Source: [codebase architecture](../codebase/ARCHITECTURE.md), [coverage](../../docs/checkpoint/coverage.md), [implementation ledger](../../docs/checkpoint/implementation-plan.md). ## Physical Scene Admission Is the Immediate Gate The physical list and the ordinary object registry have separate ownership. Common registration repeats transform/zero/Init work and appends without identity deduplication; Jimmy's outer `49E` guard encloses the whole bridge. A scene-wide two-pass Init/PostLoad abstraction or a snapshot of registry membership would disagree with the recorded same-pass appended-child behavior. Serialized class counts and vtable identities cannot be treated as actual active-body counts. The registration report inventories all 72 VR04 records/13 interfaces and compares 12 original-component registration/loader cases. Generated-helper edges are catalogued, but constructor/re-entry, conditional creation, removal, activation and retained LOAD/RETURN membership still need full ownership traces. The next integration must recover the actual ordered participants, not simply append every serialized actor or infer eligibility from its presence in the GAM file. Normal response is also distinct from pair enter/stay/leave notification. Thirty original/C# normal-contact snapshots establish inherited response, Jimmy's ordinary bypass, live accessor order and bounded derived endpoints. Soldier mode10's complete `174` call is only a recorded endpoint; its RNG/action/target policy remains open. The grappler-related Jimmy `204` endpoint is likewise not a recovered universal cleanup policy. The dynamic query/reclip components already compare empty and populated synthetic contexts, but sequential fixed actors are not a live mutable dispatcher. Post-callback inhibition, geometry permission, radius and `42C` reads must stay live; callback root mutation can be overwritten by final query-local publication. Do not cache constructor values or insert an unevidenced context reset. Preserve old nearest/hit/last-polygon state where recovered. **Integration order:** real derived responses and game/task consumers → helper activation/removal/re-entry and fresh/retained physical order → shared mutable query context/accessors → bounded response adapter for explicitly supported VR04 states → route and platform verification → broader special-material actors and lab/outside admission. Sources: [registration](../../docs/checkpoint/physical-registration.md), [helpers](../../docs/checkpoint/vr04-generated-bodies.md), [normal contacts](../../docs/checkpoint/actor-normal-contacts.md), [dynamic context](../../docs/checkpoint/dynamic-context.md), [populated reclip](../../docs/checkpoint/dynamic-reclip.md), [pair lifecycle](../../docs/checkpoint/pair-lifecycle.md). ## Camera, Animation and Retained State - **Shared camera state:** The source report establishes a shared viewport eye read by both scripted camera writes and follow input, strict DEFAULT snapping only above distance1000, and aim computed from the pre-update eye. Current `Program.cs` selects director versus simulation cameras and `LabSimulation` retains its own `CameraEye`; partial gadget bridges do not establish complete shared viewport semantics. Model the owner explicitly after validating the remaining callers. Keep projection, layer masks/fog, noclip and modern orbit policy separate. - **Animation:** Existing morph assets and deterministic visual checks do not establish the original action acceptance, playback clock, repeat/end events or interruption policy. Recover these across jump/land/STOP/talk/skip/control return before relying on them to drive actor transitions or progression. The port's fixed60Hz simulation policy must not become an assumed oracle for every original animation or script clock. - **Retained scene state:** Ordinary LOAD/RETURN, TSK loading, debug reset and fresh direct-GAM startup are different paths. Preserve original tasks/items/root state separately from session diagnostics and scene GPU/audio recreation. Current bounded retained player scalars are not permission to carry arbitrary helpers, timers, modes or handles through every transition. - **Sound clocks:** Original software elapsed/duration, strict completion boundaries, repeat and bank ownership govern cutscene behavior; transport queue-empty and dummy-stream success prove narrower properties. Integrate source channel state before broad playback-dependent script completion. Sources: [camera handoff](../../docs/checkpoint/camera-handoff.md), [coverage](../../docs/checkpoint/coverage.md), [implementation ledger C5–C8](../../docs/checkpoint/implementation-plan.md), [next-work plan](../../docs/checkpoint/next-work-plan.md). ## Solved Checkpoints Versus Remaining Work | Reuse as established bounded work | Still required | |----------------------------------|----------------| | C1 pre-task objective notification and C2 per-actor Carl task override | Other real derived task/contact policies and full progression | | Controlled player body-before-callback order, fresh/retained input distinction | Broader object scheduler, mutable helpers and actor-specific eligibility | | TSK-backed first-story retained Jimmy ordering correction; first-neutral/300-idle regression | Whole-original Carl runtime reference and native Windows comparison; broader handoffs | | Static camera ray/FIFO/wall-first adapter and per-level far limits | Complete shared eye/aim handoff, special follow branches and visual comparison | | VR04 ordinary source static body and bounded body publication/mode components | Dynamic registry/response, successful Jimmy hazards/climbs, lab/outside source admission | | Dynamic query and populated reclip component comparisons | Real actors/accessors and shared ordered scene context | | Bounded gadget/vehicle scenes and retained scalar bridges | Broader levels, special interactions, helper cleanup and arbitrary save/load lifetimes | Historical prose in `next-work-plan.md` still says the Carl correction has not begun; later updates and `docs/tasks.md` establish that the source startup-order classification and port correction are already implemented. Do not reopen that defect as untouched work or add an invented leveling reset. Similarly, the old C4 kernel-only checkpoint has been superseded by ordinary-body integration and later component reports, while its broader admission gate remains. ## Dependency Order for the Full Reconstruction 1. **Close the movement/route checkpoint:** real callbacks, helper lifetime/physical order, shared reclip, animation/control/camera handoffs and an integrated lab→VR04→lab→outside regression. Retain the existing playable baseline until each replacement gate closes. 2. **Complete shared actor/gameplay contracts:** source damage/hazards, AI/action/RNG, interactions, gadgets/vehicles and their activation/cleanup. Derive scope from original resources and consumers; existing bounded scenes are reusable implementations, not proof of universal support. 3. **Complete original progression and persistence:** load/RETURN and task/item state, every reachable level/mission, authored scripts and win/loss paths. Add full menu/configuration/save UI once their state ownership is recovered. Level inspection/rendering is insufficient. 4. **Complete presentation and audio contracts:** animation/pivots, material/light/fog/alpha/culling/layers, shared camera and UI; bank/handle clocks, positional mixing and effects. Independent static research can run alongside earlier work, but live integration must respect gameplay and lifetime dependencies. 5. **Verify complete journeys and release packages:** original comparison across representative and full-game routes, native Linux and native Windows gameplay/input/audio/rendering, offline package resource/provenance checks and reproducible discrepancy triage. These are dependency groups, not a demand to defer all rendering/audio work until the end. Resolve a presentation or sound contract earlier when it blocks a verified gameplay route. Keep the roadmap within the selected standard granularity while allowing phase plans to subdivide evidence gates. ## Verification Architecture For each admitted capability, maintain an evidence chain: authoritative binary/asset identity → addresses/offsets and REA Evidence or documented provider gap → bounded source contract/probe → managed regression → live scene replay → native platform/package result → whole-original comparison where observable. Preserve complete snapshots and hashes locally. A successful level render, synthetic callback endpoint or cross-publish closes only its named gate. Use deterministic source/component checks for phase and numeric differences; GPU readbacks for pose/camera/material differences; actual SDL input for integrated ownership and controls; physical/native audio checks for audible behavior; original-format round-trips and live reload for persistence. Define a discrepancy ledger with original/port scenario, first divergence, evidence, fix and remaining uncertainty. Never certify full fidelity from matching a few constants or rendered scenes. Both packages must identify a clean verified runtime commit and contain matching original/prepared resources. Execute from a standalone directory without source/SDK/development-library paths. Reverify original hashes. Windows cross-publish, Wine compatibility, historical user reports and new native Windows execution remain separate receipts. Push only source/tools/docs to approved Gitea; original assets, generated traces and packages stay local. ## Open Questions for Phase Research - Complete soldier RNG/action/target response and real enter/stay/leave task effects. - Constructor-only/conditional helper activation, cleanup mutation and retained physical ordering. - General live/reentrant scalar getter and shared context ownership beyond fixed synthetic probes. - Successful Jimmy FENCE/LADDER/hazard paths and multi-frame mode/animation effects. - Complete shared viewport handoff, source aim quantization and special follow branches. - Playback clocks/end callbacks, original sound bank lifecycle and full save/menu callers. - A usable whole-original reference environment and current native Windows verification. ## Sources and Limits Primary local planning inputs: [PROJECT.md](../PROJECT.md), [architecture map](../codebase/ARCHITECTURE.md), [tasks](../../docs/tasks.md), [coverage](../../docs/checkpoint/coverage.md), [implementation ledger](../../docs/checkpoint/implementation-plan.md), and [next-work plan](../../docs/checkpoint/next-work-plan.md). Selected current code checks: `src/GamePort/Program.cs` camera selection and `src/GamePort/Game/LabSimulation.cs` camera ownership. Specialized evidence reports are linked beside their findings above. No original files were modified or executed. No current build, platform execution or original-runtime comparison was performed for this report. Architectural recommendations are inference from documented contracts; exact remaining original behavior must be recovered in phase-specific investigation.