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

182 lines
15 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# 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.
- C3 control continuation: gated movement/input independently of eligible body and
fire; explicit CAM/MCA/AI raw-owner preparations and body-before-STOP order;
initial MCA target-none returns, later shots do not repeat preparation. Scripted
player transforms synchronize into body state. Grounded ordinary radius is outside
the control gate. Full wrapper/base/ceiling/class effects remain open.
- Same binding is exercised by the input-only lab route; modern replay now brakes
before large turns instead of coasting past the narrow door. Task/score/inventory/
contact assertions remain. The observed corner behavior is retained as C4 input.
- Local REA/Ghidra/full-JDK setup and batch Evidence/snapshot workflow verified.
Five selected source procedures cross-check gates/base calls. Missing analyzed
fire entry is recorded; no target execution or client registration change.
- Final C3 integration: full scripts/test.sh passes with93 Python checks,24 movement
groups, remaining managed checks and the binding-based input-only lab route,
27 zero-error enabled-validation GPU renders, SDL dummy lifecycle and539 hashes.
Native GTX1070 Carl/control/F1/F3 commands pass; native Windows remains separate.
- C3 release evidence: both self-contained packages identify clean c285b57;
standalone Linux from /tmp passes airborne control/body/fire and nondefault
tutorial/RETURN assertions. Release validation unavailable; enabled-validation
checks above remain separate. Baseline untouched; Windows cross-published only.
Logs: artifacts/uncontrolled-phases/package*.log. Next work is full wrapper/base
ownership, C4 collision/root response and shared camera handoff.
- C4 bounded kernel: REA/byte cross-checks recover47BD80 and helpers, with ten
isolated original Wine32 synthetic cases and a managed numeric-reference module.
Live capsule replacement remains gated on grid traversal/order, negative-Y split,
normal callbacks, support/friction and dynamic reclipping. No source generic
recursive capsule slide was found in the inspected dispatcher.
- C3/C4 wrapper: root+150 upward query and min(−0.6Vy,−85) response now run before
Jimmy movement/fire, regardless of ownership; mode1 cancellation preserves hold
and independent queued/body work. Fresh/retained input boundaries preserved;
camera-only debug switch cannot disable physical query. Other scene filters,
sound and selected-gadget cleanup remain separate.
- Registration: retained registry objects have49E cleared, then physical Init/list
registration repeats Init before placement. Shared-eye capture/pre-update aim
is source-guarded but C5 runtime correction remains next. Detailed reports:
collision-response.md, ceiling-wrapper.md, body-root-registration.md,
camera-handoff.md; complete REA results and provider gaps retained on disk.
- Final C4 bounded continuation validation:104 Python plus HUD,25 movement/five
sphere and remaining managed groups,27 zero-error enabled-validation GPU renders,
SDL dummy lifecycle and539 unchanged originals. Four native GTX1070 window
commands pass (five scene renders). Full capsule replacement, complete camera
state and original whole-game/native Windows validation remain separate gates.
- C4 continuation release: both self-contained packages identify clean57dfcc6
(source_dirty=no); standalone Linux from /tmp passes control/body/fire and
nondefault tutorial/RETURN checks. Release validation unavailable, enabled
source/native checks separate. Package logs in artifacts/collision-response/;
baseline untouched and Windows cross-published only.
- C4 static composition: independent REA grid/contact investigations recover
FIFO duplicate traversal, reachable retries, normal/landing ownership, signed
material archive IDs, separate published160 speed and friction/suppression.
Seven isolated original dispatcher fixtures match the managed component's
positions/counts/callbacks. Ten copied479D20/support fixtures completed; no
managed whole-body equivalent is claimed yet. Reports: collision-body-probe.md,
collision-grid-traversal.md, collision-contact-callbacks.md and independent review.
- Prepared scenes now retain material IDs and completeness; legacy metadata cannot
masquerade as ordinary-only. Actual VR04 has no special contacts; LV1B/LEV1 do.
Geometry-disabled publication/retained callback and strict initial support
distance are explicit. Original geometry-off branch supersedes C3's earlier
support-hit gravity-cancellation inference. Playable body remains baseline.
- Next C4 chunk: ordinary-body composition and ten numeric comparisons, negative-Y
horizontal-first split,370, landing-before-velocity-clear, published160 friction
and suppression; then VR04 live root/input/ceiling/RETURN checks. Trace special
callbacks and dynamic reclip/global context before lab/outside replacement.
- C4 ordinary-body composition implemented and matched against all ten copied
body references. VR04 now selects the source static subset with live radius
60/100, separate published160, control-independent body work and source landing/
friction order. Twenty managed groups and native/headless300-frame jetpack
replay pass; lab/outside capsule retained. Source and independent review:
collision-body-composition-source.md, collision-body-implementation.md and
collision-body-implementation-review.md. Other original VR04 dynamic class
eligibility, special Player callbacks and shared dynamic contexts remain open.