Files
Neutron/docs/checkpoint/next-work-plan.md
T

146 lines
8.0 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.
# Next work plan: recover interactions, then implement verified changes
2026-11-05. Proposed execution order following the user's request for a plan.
Gameplay expansion remains paused. Current research checkpoint68154df preserves
runtime a2e89c6 and packaged runtime dae13ac. This plan does not mark the remaining
post-skip tilt fixed or authorize an unsupported rotation reset.
Execution update2026-11-06: [integrated lifecycle findings](../gameplay/jimmy-cutscene-lifecycle.md)
add292 bounded original-code cases, complete DEFAULT recovery and a working
read-only copied-original observer. Steps1–2 remain open at the actual original
Carl entry/resumed-frame observation. Step3 has not begun; source composition
agrees with the port's stale writer under the same synthetic order/state.
## Objective
Establish the original ownership and timing of player state across gameplay,
contact, cutscenes, landing and level return, then correct the port in small,
verified chunks. Start with the concrete reported failure: jump while banked,
enter Carl's lab conversation, skip, release controls, remain upright afterward.
Ordinary landing bank must remain faithful to the original, as the user confirmed.
## 1. Close the original Carl skip-to-idle sequence
Trace the actual supplied route: physical contact → Carl talk activation →
neutron1a activation → accepted skip → Carlwalk → DEFAULT → first idle input
and player update. Follow direct callers, virtual targets and registry positions
through REA, checking the authoritative bytes and GAM records.
Record support, raw control owner, movement mode, stored turn, current Euler,
destination Euler, dirty flag, skip state, action latch, input suppression and
frame delta at every boundary. Include contact/support state before entry: the
port's grouped contacts might start the scene with different retained state.
Investigate the concrete remaining gaps: skip input-latch consumption and release,
per-camera completion order, same-frame control changes, and fresh/retained actor
ordering. Reuse the three new pseudocode results and existing instruction Evidence.
Keep the unresolved DEFAULT procedure boundary explicit; use its guarded assembly
and a changed analysis strategy where necessary rather than repeat failed queries.
**Deliverable:** an annotated original event/state trace and a clear explanation
of where the original prevents the stale airborne bank from being republished.
A local no-reset result or another plausible hypothesis does not close this gate.
## 2. Compare the original sequence with the reproducible port failure
Extend the existing48-case diagnostic around the original boundaries. Use an
isolated original-code composition with explicit synthetic dependencies and/or
an original-game runtime capture from a generated copy where the available
runtime supports it. Record limitations, including any callbacks not executed.
Compare fresh and retained ordering; grounded and airborne entry; Left/Right
bank; neutral and held input; Escape/Space skip and natural completion. Natural
completion is a separate comparison—the user's confirmed failure concerns skip.
Keep source viewport seconds, morph/engine timing and the port's60Hz policy
explicit rather than assuming they share one clock.
**Deliverable:** a differential trace naming the first meaningful divergence,
its owner and its consequences. Expected outcomes must agree with original
instructions/composition and the user's observation. If they conflict, specify
the exact missing observation before changing gameplay.
## 3. Implement the supported cutscene correction
Resume runtime work once steps1–2 establish the missing transition or ordering.
Change the smallest coherent owner/lifecycle boundary, retaining the existing
playable movement baseline. Preserve normal landing bank, heading, queued body
work and the separately recovered fire/control lifecycles.
Convert the reported skipped-Carl/neutral-return scenario into a regression that
fails on the current baseline. Cover the first resumed frame and sustained idle,
both insertion orders, natural completion, held-input return, and repeated scenes.
**Done when:** the source explanation and implementation agree; Jimmy remains
upright after skipping Carl; legitimate landing bank remains; targeted movement,
Director, jetpack and visual checks pass. State any remaining approximation.
## 4. Deepen the remaining movement interaction contracts
After closing Carl's lifecycle, prioritize the existing core-system gaps:
1. **Body/contact ownership:** real Jimmy callbacks, dynamic pair eligibility,
support admission, callback-mutated root/modes and successful fence/ladder or
hazard paths. Preserve the lab/outside capsule until its replacement gate closes.
2. **Animation lifecycle:** original action acceptance, playback clocks, completion
callbacks and interruption across jump, land, STOP, talk, skip and control return.
3. **Shared camera/input state:** final scripted eye, first resumed follow update,
clipping, pause/menu/input gates and retained scene ordering.
Use each recovered transition to update the coverage map and remove a named
assumption. Existing original arithmetic fixtures remain regression evidence;
JN-Engine supplies original-decompiler leads, not replacement movement tuning.
**Deliverable:** per-system state/ownership contracts with addresses, file offsets,
callers, dependencies, confidence and unresolved questions, plus bounded source
probes where needed. Implement each supported correction as its own verified chunk.
## 5. Validate the route as one interacting system
Exercise lab → VR04 → lab → outside with fresh entry and RETURN. Include normal
and skipped conversations, banked jumps, landing/idle, jetpack cleanup, held input,
objectives, music/speech, camera handoff and persistent/reset state.
Run targeted checks for each change and the full suite at the integrated route
checkpoint. Validate native Linux SDL/Vulkan, then obtain native Windows build
feedback for the same scenarios. Compare original behavior where observed;
managed tests, original components, Linux rendering and Windows execution remain
separate evidence categories.
**Done when:** the route and reported bug pass the defined scenarios, original
hashes remain unchanged, platform results/limits are recorded, and both packages
identify a clean verified runtime commit. Push source/tools/docs to the approved
Gitea remote; keep originals, generated traces and packages local.
## 6. Choose the next reconstruction checkpoint from the updated coverage map
Once movement and route handoffs are stable, rank the remaining audio/music,
UI, progression/save-load and actor/AI gaps by how much existing gameplay they
block. Recover and implement them in that dependency order. New gadgets and
level-specific features stay behind the core movement/route checkpoint.
**Deliverable:** a short next-chunk plan based on measured gaps, with a concrete
source question, implementation boundary and validation condition for each item.
Do not require understanding every level before executing a supported core change.
## Parallel work and ownership
Use two independent investigators when the questions are substantial:
- Original input/skip/state ownership: jimmy-cutscene-return source report and
its named binary analysis helpers.
- Contact/registry/script ordering: jimmy-cutscene-chain-order source report and
its named binary analysis helpers.
Primary owns the port diagnostic, integrated trace, coverage/status documents,
runtime/test integration and commits. Establish exclusive ownership before work;
review shared conclusions before editing gameplay. No investigator changes
another's files or commits shared work.
## Checkpoint discipline
Every checkpoint reports recovered facts, inference, current implementation,
verification and open questions separately. Save Evidence/probe identities and
findings on disk. Commit and push completed, verified milestones. Gameplay work
remains paused until the Carl source/differential gate above is satisfied; this
plan itself introduces no gameplay or package changes.