16 KiB
last_mapped_commit, last_mapped_at
| last_mapped_commit | last_mapped_at |
|---|---|
bdca29d3aa |
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:
OriginalPairCollisionrequires caller-owned physical order and real callbacks;OriginalNormalContactsimplements 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:
Stepenumerates 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.Movepermits256 retries and throws beyond its verified finite-motion domain;OriginalPairCollision.Steprequires 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 runtimebf876e9and packaged924ad2fmust 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