--- last_mapped_commit: bdca29d3aa31face0c0023537ff98783716dbc45 last_mapped_at: 2026-11-12 --- # Codebase Concerns **Analysis Date:** 2026-11-12 Scope: tracked GamePort source and documented findings. Source HEAD is `bdca29d`; integrated SDL/GPU evidence belongs to `bf876e9`, while distributed local packages identify `924ad2f`. These are distinct validation targets, as recorded in `docs/progress.md` and `docs/compatibility.md`. This mapping performs no new builds, tests, binary execution or runtime comparison. ## Tech Debt **Standalone collision contracts await supported live admission:** - Issue: `OriginalPairCollision` requires caller-owned physical order and real callbacks; `OriginalNormalContacts` implements inherited response without providing Jimmy's override or scene admission. Dynamic/static composition remains test-only. - Files: `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`, `src/GamePort/Game/DynamicSceneCollision.cs`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/actor-normal-contacts.md`. - Impact: passing component snapshots cannot establish general NPC interaction, live dynamic collision or game/task side effects. Replacing existing collision directly would skip unresolved owners. - Fix approach: recover soldier complete174 and helper membership/order first; then bind a bounded response adapter to explicitly supported actor states. Preserve late inhibition, radius, geometry and42C reads. Do not cache pre-callback fields or apply inherited reflection to Jimmy ordinary374. **Physical registration and retained helper lifecycle are incomplete:** - Issue:72 serialized VR04 records/13 interfaces and21 helper edges establish source construction/registration contracts, not a full active body list. Common append permits duplicate pointers, Jimmy49E guards its whole bridge, and per-object Init/PostLoad visits newly appended tails. - Files: `docs/checkpoint/physical-registration.md`, `docs/checkpoint/vr04-generated-bodies.md`, `docs/checkpoint/dynamic-context.md`, `tools/binary/physical_registration.py`, `tools/binary/helper_teardown.py`. - Impact: constructor-only helpers, Jeep child cleanup, activation and LOAD/RETURN reuse can change physical order and contact effects. Counting serialized records or deduplicating registration would misrepresent the original. - Fix approach: trace actual helper removal/re-entry/activation and cleanup mutations across fresh load, retained load and RETURN. Compare complete ordered registry snapshots before enabling additional physical members. **Compatibility adapters remain explicit movement boundaries:** - Issue: the lab/outside capsule, floor-derived visual sole correction and fixed60Hz scheduling are port policies. Bounded source-body integration does not cover every special material or dynamic actor path. - Files: `src/GamePort/Game/LabSimulation.cs`, `src/GamePort/Game/SceneCollision.cs`, `src/GamePort/Game/FixedStepClock.cs`, `src/GamePort/Game/OriginalBodyPhysics.cs`, `docs/gameplay/jimmy-movement-stabilization.md`, `docs/checkpoint/body-contact-implementation.md`. - Impact: existing navigation/playability and recovered scalar motion are not full original-body or scheduler parity. - Fix approach: retain the current Jimmy baseline while recovering successful hazard/FENCE/LADDER paths, support ownership, actor mode/facing and real callback publication. Use original evidence to replace one named adapter at a time; JN-Engine replacement movement is not authoritative. **Partial camera/audio/UI/save ownership:** - Issue: the coverage ledger identifies separate scripted/chase eyes, merged clip policy, independent file-based audio streams, a subset of objective/UI dispatch and a fresh-director save-load path that differs from original repeated task/entity callbacks. - Files: `docs/checkpoint/coverage.md`, `src/GamePort/Application/OrbitCamera.cs`, `src/GamePort/Audio/SceneAudio.cs`, `src/GamePort/Game/ObjectivePanel.cs`, `src/GamePort/Game/SceneDirector.cs`, `src/GamePort/Assets/OriginalSave.cs`. - Impact: recovered route behavior does not establish arbitrary save/load, full camera handoff, audio bank/clock lifecycle or all UI flags. - Fix approach: follow the ownership/probe gates in `docs/checkpoint/next-work-plan.md`; recover dispatcher transitions and repeated callbacks before expanding UI, progression or gadget behavior. ## Known Bugs **No newly reproduced runtime bug in this source-only mapping:** - Symptoms: current docs retain earlier failure narratives alongside resolved checkpoint entries. The post-Carl neutral-bank failure has a supported TSK startup ordering correction and documented first-input/300-idle regression results; it must not be listed as an unfixed current bug. - Files: `docs/progress.md`, `docs/tasks.md`, `docs/compatibility.md`, `docs/gameplay/main-menu-player-lifetime.md`, `docs/checkpoint/coverage.md`. - Trigger: the corrected path is successful TSK story entry, whose retained background Jimmy precedes new level input; direct fresh-GAM ordering is a separate case. - Workaround: preserve the correction and fresh/retained distinction. Ordinary landing residual bank is user-confirmed original behavior; do not add a universal leveling/reset workaround. Whole-original Carl comparison remains unverified. ## Security Considerations **Preservation and generated-probe isolation:** - Risk: extraction or instrumentation directed into originals could destroy authoritative evidence; incorrect relocation operands can invalidate a copied-code experiment. - Files: `AGENTS.md`, `tools/binary/actor_contact.py`, `tools/recon/inventory.py`, `docs/original-manifest.json`, `docs/checkpoint/actor-normal-contacts.md`. - Current mitigation: the actor-contact generator rejects overlapping original/output directories and generated symlinks; reviewed operands, complete source/probe identities and completion markers guard capture acceptance. The documented cross-instruction relocation failure affects an invalid private probe, not original behavior. - Recommendations: retain operand-specific regression guards and hash verification; keep invalid partial captures excluded. Never execute or patch original files in place. **Local asset parsing and path boundary:** - Risk: malformed local assets require bounded decoding, and portable case lookup must reject ambiguous names rather than silently load another file. - Files: `src/GamePort/Assets/AssetPath.cs`, `src/GamePort/Assets/GamLevel.cs`, `src/GamePort/Assets/PngImage.cs`, `tests/GamePort.DataTests/Program.cs`, `tests/test_extractors.py`. - Current mitigation: paths reject dot/parent components and require one case-insensitive match; GAM validates counts, remaining spans, finite scalars and duplicate properties; image parsing enforces supported formats and size limits. - Recommendations: preserve these checks when adding formats and test malformed/truncated inputs. This source review identifies no reproduced exploit and makes no claim that these checks constitute a general filesystem sandbox. ## Performance Bottlenecks **No measured bottleneck established by this mapping:** - Problem: pair enumeration and source cell/FIFO traversal have scaling costs, but there is no new timing measurement here. - Files: `src/GamePort/Game/OriginalPairCollision.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Application/DebugDiagnostics.cs`. - Cause: `Step` enumerates an upper triangular body list, giving quadratic candidate growth; static traversal deliberately retains cell duplicates and retries. This is source complexity evidence, not a measured live slowdown; the pair component is not live. - Improvement path: measure candidate counts, NodeVisits, TriangleTests and frame timings on supported scenes before optimizing. Preserve asymmetric exclusions, duplicate visits, tie order and callback timing; do not introduce an order-changing broadphase without equivalence evidence. ## Fragile Areas **Callback-mutated context and late getters:** - Files: `src/GamePort/Game/OriginalNormalContacts.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/dynamic-reclip.md`, `docs/checkpoint/actor-normal-contacts.md`. - Why fragile: callbacks can alter inhibition/radius/geometry/force state before reclip; retained last polygon can issue another callback; final local-root publication can overwrite callback root edits. Getter timing is observable behavior. - Safe modification: retain accessor order, independent state channels, XYZ/full-Vec4 setter distinctions and explicit context ownership. Test full snapshots/event order rather than final root alone. - Test coverage:30 normal-contact fixtures include synthetic mutations. They do not execute real soldier174/Jimmy204 policy or establish reentrant linked-list mutation. **Source arithmetic and finite-domain boundaries:** - Files: `src/GamePort/Game/OriginalSphereResponse.cs`, `src/GamePort/Game/OriginalHeading.cs`, `src/GamePort/Game/OriginalNormalContacts.cs`, `src/GamePort/Game/OriginalStaticCollision.cs`, `docs/checkpoint/dynamic-reclip.md`. - Why fragile: float-store boundaries, source triangle winding, heading wrap and strict comparisons affect complete state even where final positions agree. Double intermediates are not a universal x87 emulator. - Safe modification: require original instruction/store evidence and exact fixture comparisons for arithmetic changes. Keep unsupported zero-horizontal normalization explicit instead of silently inventing a policy. - Test coverage: populated reclip has14 complete observations/12 kernel steps; inherited normal response has30 bounded snapshots. Degenerate inputs, arbitrary normals and broad x87 equivalence are not certified. **Story entry and ordinary landing:** - Files: `src/GamePort/Program.cs`, `src/GamePort/Game/LabSimulation.cs`, `docs/gameplay/main-menu-player-lifetime.md`, `docs/gameplay/jimmy-landing-rotation-source.md`. - Why fragile: TSK-backed retained order and fresh direct-scene order differ; a generic neutral-angle reset would erase legitimate landing bank while masking scheduler errors. - Safe modification: preserve first-story retained player-before-input classification and baseline movement algorithms. Recheck first resumed neutral frame, sustained idle, held input, Left/Right bank, natural completion/skip and repeated scenes after lifecycle changes. - Test coverage: eight managed trajectories and integrated Linux evidence are documented; original full Carl runtime and current native Windows comparison remain separate gaps. ## Scaling Limits **Bounded solver contracts:** - Current capacity: `OriginalStaticCollision.Move` permits256 retries and throws beyond its verified finite-motion domain; `OriginalPairCollision.Step` requires a stable input list during the pass. - Files: `src/GamePort/Game/OriginalStaticCollision.cs`, `src/GamePort/Game/OriginalPairCollision.cs`. - Limit: source recursive retry behavior and callback-driven linked-list insertion/deletion are not fully represented by these bounded APIs. The256 guard is an implementation boundary, not measured original capacity. - Scaling path: recover problematic repeated-contact cases and list-mutation semantics before widening the contract; preserve explicit failure rather than return an invented final position. **Scene admission is deliberately restricted:** - Current capacity: static route construction admits LV1B, VR01, VR02, VR04, VR05, VR07, VR08 and LEV1; this is not a claim of complete gameplay in those eight scenes. Prepared resources cover33 available scenes according to the project ledger. - Files: `src/GamePort/Game/OriginalStaticCollision.cs`, `docs/tasks.md`, `docs/checkpoint/coverage.md`. - Limit: asset availability and class binding do not establish live physics, AI or progression coverage in other scenes. - Scaling path: recover scene-specific consumers and ownership before broadening admission; keep unsupported scenes on their documented compatibility path. ## Dependencies at Risk **No package-specific obsolescence or migration risk established:** - Risk: this mapping provides no evidence that .NET10, SDL3 or Silk.NET.Vulkan requires replacement. The material dependency is runtime/platform validation, not a speculative package migration. - Files: `GamePort.csproj`, `scripts/build-windows.sh`, `scripts/package.sh`, `docs/compatibility.md`. - Impact: a successful Windows cross-publish and resource match do not establish current native Windows execution, audible behavior or driver compatibility. - Migration plan: not applicable. Run the same route/control/window/audio scenarios on native Windows and record exact source/package identity before claiming platform equivalence. ## Missing Critical Features **Real derived actor response and game/task contact consumers:** - Problem: soldier409590 mode10 calls complete174→4098C0, whose RNG/target/action policy is not executed by the bounded fixture; Jimmy204 is likewise a record-only endpoint. Enter/stay/leave gameplay consumers remain separate from normal response. - Files: `docs/checkpoint/actor-normal-contacts.md`, `tools/binary/actor_contact.py`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/tasks.md`. - Blocks: general dynamic actor admission and faithful enemy/contact behavior. Recover complete caller/callee state and RNG progression before wiring supported adapters. **Full reconstruction beyond bounded playable routes:** - Problem: animation playback/completion/interrupt timing, shared camera/input ownership, full audio bank lifecycle, arbitrary retained LOAD/save and broader progression remain open in the coverage ledger. New gadget expansion is paused behind movement/core-system gates. - Files: `docs/checkpoint/coverage.md`, `docs/checkpoint/next-work-plan.md`, `docs/tasks.md`, `docs/gameplay/jimmy-movement-stabilization.md`. - Blocks: full-game completion and blanket fidelity claims. Prioritize the interacting lab→VR04→lab→outside route and remove specific documented assumptions with original evidence. ## Test Coverage Gaps **Whole-original gameplay comparison and native Windows:** - What's not tested: current source as a complete original-game Carl sequence and native Windows equivalent of the integrated Linux route. Black-frame original Wine startup/allocation observations do not supply visual gameplay comparison; earlier Wine64 port evidence belongs to `ea04210`. - Files: `docs/compatibility.md`, `docs/gameplay/original-startup-diagnostic.md`, `docs/gameplay/main-menu-player-lifetime.md`, `docs/reference-testing.md`. - Risk: component correctness and Linux replay success can coexist with differences in original timing, visuals, audio and Windows behavior. - Priority: High. Capture a working copied-original banked-entry/skip/neutral-return interval and native Windows route evidence, identifying exact binaries and limitations. **Real helper lifecycle and reentrant collision integration:** - What's not tested: full fresh/retained active physical lists, helper cleanup/re-entry during LOAD/RETURN, real soldier RNG response, actual contact-driven task mutations and callback list mutation during a pair pass. - Files: `tests/GamePort.PairLifecycleTests/Program.cs`, `tests/GamePort.ActorContactTests/Program.cs`, `docs/checkpoint/physical-registration.md`, `docs/checkpoint/vr04-generated-bodies.md`, `docs/checkpoint/actor-normal-contacts.md`. - Risk: synthetic endpoint and stable-list tests can pass while real admission produces incorrect order or side effects. - Priority: High. Add original-supported complete ordered-state fixtures, then bounded integration regressions before enabling actors. **Source/package evidence divergence:** - What's not tested: latest standalone normal-contact source changes as a new SDL/GPU/native Windows package checkpoint. Current source `bdca29d`, integrated runtime `bf876e9` and packaged `924ad2f` must remain separately identified. - Files: `docs/progress.md`, `docs/compatibility.md`, `scripts/package.sh`. - Risk: citing earlier package readbacks as verification of later source overstates coverage. - Priority: Medium. At the next authorized integration checkpoint, validate the complete intended source, rebuild clean packages and record identities, resource hashes and platform-specific execution receipts. --- *Concerns audit: 2026-11-12*