Files
Neutron/.planning/codebase/CONCERNS.md
T
2026-11-12 11:06:58 -05:00

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: 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