Files
Neutron/docs/checkpoint/implementation-plan.md
T

108 lines
10 KiB
Markdown

# Evidence-based continuation
Checkpoint exit is architecture coverage, not full-game completion. Preserve
baseline69d0187 and original hashes, finish reports/byte checks, then execute these
chunks in dependency order. Each chunk gets its own evidence, regression result
and local milestone; a failed gate triggers further bounded investigation rather
than invented behavior or new levels/features.
| Chunk | Concrete change / evidence gate | Verification and completion condition |
|---|---|---|
| C1 |45F990: notify objectives before changing task records; then dispatch actors. Expose explicit pre-assignment boundary. | Byte assertions45FB5B/7F/D9; observers see old task during objective selection and new task during actor notification; repeat/missing tasks still broadcast. Run Data/Interaction/Director/route regressions. |
| C2 | Preserve per-actor virtual task override boundary. Generic activation then Carl override413F30 before advancing to next actor, rather than applying all Carl overrides after all actors. | Confirm base/derived call bytes; check actor notification sees final per-actor state and authored marker; regression task50→60 conversation/control and lab route. Do not add other class overrides without evidence. |
| C3 | Build original registry/construction/input/frame phase oracle for lab. Split pending motion/controller/effect phases only when registration order and engine callback bridge are recovered. | Assert physics before normal object update, next-node timing, transform sync after callbacks. Compare input→impulse→next-physics→ground/pose trace; test pause/control loss/return. Keep cadence as unresolved policy until engine timer evidence. |
| C4 | Recover47BD80 and Jimmy root/body fields. Replace provisional capsule/feet and wall response behind bounded source adapter. Depends on C3 phase semantics. | Isolated original collision probes plus deterministic wall/step/ceiling/floor/dynamic-body cases; no invisible NC terrain; lab/tutorial route and visual root checks. |
| C5 | Recover follow ray47C210 filtering and coefficients, then implement shared viewport handoff/DEFAULT snap and follow43B820. | Source byte/probe predicate, below/equal/above1000 eye-distance boundary (snap strictly above), obstruction hit adjustment, controlled/scripted/return camera continuity, per-level projection. Port GPU checks remain separate from original visual comparison. |
| C6 | Recover source allocation/failure and sound+44 duration conversion. Source slot14 uses software duration milliseconds and repeat+30, not hardware status. Model that channel state plus current SFX bank/default gate, then connect CAM/MCA completion. | Strict elapsed>duration boundary, repeat/stop/invalid handle/clock pause; bank unload/reload/default/scene disposal. SDL dummy tests validate transport only; queue-empty is not source timing. Physical/native Windows output remains separate. |
| C7 | Queued TSK load460E70→460EA0→4603F0: repeated task424 and all-entity420 post-task hooks. Ordinary scene placement separately uses46E61A→Jimmy40C423610. Recover enclosing loader, RETURN flags/root/STRT and acquired-reset gate50988A. | C1/C2 first. Trace source duplicate-callback effect before adopting; original12-save byte round-trip; fresh load vs RETURN vs practice No/Yes; persistent arrays/score/energy/strings vs reset timers/handles/actors. |
| C8 | Morph playback flags/rate/end events and UI dispatcher mode/layout gates. | Original clip/end-state probes; action interruption/landing/cutscene restoration; objective/practice controls. Preserve modern widescreen/debug policy and test pointer anchors separately. |
Implementation expansion into later levels, gadgets/combat, menus and full save UI
resumes only after these core contracts support it. Later-level investigation is
allowed where it resolves a core-system question, without waiting for every level.
## Execution ledger
- Entry: baseline69d0187 preserved;539 original hashes verified. Dedicated
investigators assigned independent loop/motion, script/state and camera/audio/UI
files. Main loop findings integrated by primary after investigator usage limit.
- C1: implemented pre-assignment objective boundary. Data/Interaction/Director,
input-only lab route and RETURN regressions pass. Source45FB5B/7F/D9 checked
independently and retained in the script/state helper. No scheduler changes.
- C2: captured SCENE before generic activation, moved LV1B Carl override into the
same per-actor director callback, and removed the interactions-layer batch fix.
Original413F3D/413F4E/414068..414118 independently checked. Director callback
observers now see the final derived state before later actors. Director,
Interaction and input-only lab route regressions pass; broader checks pending.
- C3 investigation: input/frame bridge and fresh lab partial construction order
recovered and byte-checked. Fresh game input→Jimmy controller→fire runs after
global physics. Retained registry/lifecycle remains the integration gate; no
speculative global reorder applied.
- C6 investigation: `voice-clock.md` resolves derived slot14 to inherited software
elapsed/duration and+30 to repeat. Replaced the proposed hardware/SDL-playing
interpretation before changing runtime. Original bytes and one new regression pass.
- C5 investigation: `camera-ray-predicate.md` recovers static grid registration,
wall priority, FIFO first-hit and source kernel, with four order/data regressions.
A static adapter is now justified; complete camera handoff still needs its state.
- C7 investigation: `scene-loader.md` closes app deferred request→teardown→GAM→
per-object initialization/PostLoad. Jimmy/Goddard retention/reuse is proven;
per-field reset/old-game/helper lifetime remains a bounded next trace. Editor R
reset distinguished from ordinary load. Consistency review leaves old-game
removal/eligibility explicit rather than treating current pointer overwrite as
deletion. Five evidence regressions pass. This is the next C3/C7 integration gate.
- Exit review: core architecture checkpoint documented in `review.md`; feature
expansion remains paused. C1/C2 full integration passes; final follow-up Python
discovery and original hashes recorded under artifacts/re-checkpoint/.
- C3/C7 gate closed: normal Init copies stored+11 to live+139, restoring the
level game's deletion predicate. Destructor explicitly unlinks its registry
node. `level-game-lifetime.md` and three byte regressions retain that proof.
- C3 first implementation: controlled player physics consumes prior motion/queued
impulse before input/player/fire callbacks. Fresh versus retained input order
follows proven registration; stored mode and same-frame landing reset are
explicit. Twenty movement groups, input-only routes and GPU RETURN pass targeted
checks. Full-scene scheduling, uncontrolled-body and collision response remain open.
- C5 static adapter implemented/integrated for LV1B/VR04/LEV1: source cell/FIFO/
wall-first predicate and single-triangle kernel, source eye adjustment/gain,
one query per input callback. Eleven camera groups and existing support groups
pass; full camera handoff/input state remains open.
- C7 availability correction: level entry enables state4→1 for the recovered eight
gadgets, then VR01..08 disables owned1→4. Unknown states/other groups preserved;
tutorial bypass unchanged. Source anchors and boundary/round-trip tests cover it.
Arbitrary retained scalar/mode/fire state is still gated by the streamer/lifecycle
fixture; no blanket carry was introduced.
- Full integration passes: artifacts/implementation/integration-final.log.
Seventy Python checks, all managed groups including20 movement/11 camera/
13 support, GPU story/route/practice/RETURN/jetpack/animation with zero validation
errors, SDL dummy lifecycle and539 unchanged hashes. RETURN also verifies
retained input order and tutorial availability normalization. Packages rebuilt
after the implementation milestone; platform runtime claims remain separate.
- Packages: clean09cf117 Linux/Windows self-contained outputs; Linux launch from
/tmp passes practice/RETURN and outside scene load. Release validation layers
unavailable; source full integration validated above. Package evidence recorded
separately without changing runtime. Continue the remaining source-state and
shared-camera/control/collision gates rather than resuming feature expansion.
- Retained-field continuation2026-10-26: property extraction has no hidden reset
callback; generic Init re-applies authored body vectors, final preparation clears
velocity/speed, Jimmy jump state resets separately from mode/hold/fire. Bounded
route/no-gadget/jetpack PlayerLevelState now carries only those three scalars
through ordinary transitions, never TSK loads. Companion/shadow reset fields and
same-state AI guard are documented; body registration/new-helper timing remain.
- Corrected C7 prefix-only availability: full VR01..08 tails re-enable the practice
gadget0..7, so owned VR04 jetpack finishes1. LV1B disables gadgets1/7. Managed
state boundaries/unknown values and GPU practice/RETURN guard the correction.
Other level-specific selection/availability tails remain an explicit gate.
- Retained continuation validation:84 Python,22 movement plus remaining managed
groups,26 enabled-validation GPU renders, final nondefault tutorial/RETURN
boundary replay, four final SDL dummy checks and539 original hashes pass.
Original43A750/vector leaf component probe passes in isolated Wine32; this is
separate from whole-loader/original-game/native-Windows validation. Next gates:
uncontrolled body/controller/fire scheduling, body registration/helper traversal,
C4 response/root and shared camera handoff. See progress.md for sampling-check details.
- Release evidence: both self-contained packages from clean9ad5a8e; standalone
Linux launch from /tmp verifies nondefault tutorial/RETURN scalar boundaries and
body resets. Release validation unavailable; source GPU checks enabled. Native
Windows runtime remains unverified for this chunk. Preserved baseline untouched.