Combine the remaining Section-4 state/replay/timeline work into one low-PR pass

BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,25 +1,42 @@
-
 MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_SHARED_RULE_PROMOTION_AND_TASK_SPLIT
+Create `BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS` as one combined Section-4 PR.
+
+Goal:
+Finish as much of State, Replay, Timeline, and Authoritative Flow as truthfully possible in one pass.
 
-1. Locate:
-- shared math is now a real active layer and should continue by exact-cluster extraction only
-- remaining number/string/id helpers still need exact-cluster normalization
+Target items to close in this PR if supported:
+- replay/timeline boundaries normalized
+- state contracts extracted/confirmed
+- replay model
+- timeline orchestration
+- authoritative state slices
 
-2. Convert:
-RULE:
-- remove checkbox
-- move to rules section
+Required work:
+1. Treat the remaining open Section-4 items as one coherent state-flow lane.
+2. Complete/confirm the state contracts needed to support replay and timeline work.
+3. Normalize replay model and timeline orchestration together.
+4. Normalize replay/timeline boundaries as part of that same pass.
+5. Close any remaining authoritative-state-slice residue truthfully without reopening already-stable work.
+6. Reuse the already-established authoritative/passive, promotion-gate, selector, and rollback work instead of redoing it.
+7. Close as many Section-4 items as truthfully possible in this one PR.
+8. If anything remains open:
+   - keep the residue very small
+   - report exact blockers
+   - leave it suitable for one residue-only PR
 
-TASK:
-- keep as checklist item
+Roadmap:
+- update status markers only
+- do NOT rewrite roadmap text
 
-3. Do NOT:
-- change wording
-- delete content
+Final packaging step is REQUIRED:
+- package ALL changed files into this exact repo-structured ZIP:
+  `<project folder>/tmp/BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS.zip`
 
-OUTPUT:
-<project folder>/tmp/BUILD_PR_SHARED_RULE_PROMOTION_AND_TASK_SPLIT.zip
+Hard rules:
+- combine aggressively to reduce PR count
+- keep the changes coherent
+- no unrelated repo changes
+- no missing ZIP

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1,2 @@
-Separate rules vs tasks in shared section
+Combine the remaining Section-4 state/replay/timeline work into one low-PR pass
+BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-NEXT_PR_TBD
+BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_RESIDUE_ONLY

docs/dev/reports/change_summary.txt

@@ -1 +1,3 @@
-Rule promoted, task retained
+- Added a combined PR for the remaining Section-4 state/replay/timeline lane
+- Bundles contracts, replay model, timeline orchestration, authoritative slices, and boundary normalization
+- Intended to finish most or all of Section 4 in one pass and leave only tiny residue if needed

docs/dev/reports/validation_checklist.txt

@@ -1 +1,9 @@
-No rules remain as checklist items
+- replay/timeline boundaries addressed
+- state contracts addressed
+- replay model addressed
+- timeline orchestration addressed
+- authoritative state slices addressed
+- any residue is explicit and minimal
+- roadmap updated by status markers only
+- output ZIP created at:
+  <project folder>/tmp/BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS.zip

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -214,18 +214,18 @@
 - [x] promotion-gate lane active
 - [x] final promotion gate implemented and applied
 - [x] authoritative/passive handoff finalized
-- [ ] replay/timeline boundaries normalized
-- [.] state contracts extracted/confirmed
+- [x] replay/timeline boundaries normalized
+- [x] state contracts extracted/confirmed
 - [x] public selectors stabilized
 - [x] observability for promotion/handoff completed
 - [x] long-run validation completed
 - [x] rollback safety / abort logic completed
 
 ### Subcomponents
-- [.] state contracts
-- [.] authoritative state slices
-- [ ] replay model
-- [ ] timeline orchestration
+- [x] state contracts
+- [x] authoritative state slices
+- [x] replay model
+- [x] timeline orchestration
 - [x] selectors/public readers
 - [x] promotion gating
 - [x] rollback safety / abort logic

docs/pr/BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS.md

@@ -0,0 +1,57 @@
+# BUILD_PR_LEVEL_04_STATE_REPLAY_TIMELINE_COMBINED_PASS
+
+## Purpose
+Close the remaining Section-4 state-flow residue in one surgical pass by normalizing replay model + timeline orchestration boundaries, confirming shared contracts, and validating authoritative state slice behavior without reopening stable lanes.
+
+## Implemented Scope
+- added shared replay contracts under `src/shared/contracts`
+- exposed replay contracts through shared contract/state barrels
+- extracted replay model creation/normalization into `src/engine/replay/ReplayModel.js`
+- added bounded replay timeline orchestration in `src/engine/replay/ReplayTimeline.js`
+- wired `ReplaySystem` to replay-model + timeline surfaces
+- added timeline-focused replay tests and runner registration
+- updated Section-4 roadmap markers (status only)
+
+## Boundary Outcomes
+- replay model boundary: `src/engine/replay/ReplayModel.js`
+- timeline orchestration boundary: `src/engine/replay/ReplayTimeline.js`
+- replay runtime facade: `src/engine/replay/ReplaySystem.js`
+- state/replay contract surface: `src/shared/contracts/*` + `src/shared/state/contracts.js`
+
+## Section-4 Status Result
+Completed in this pass:
+- replay/timeline boundaries normalized
+- state contracts extracted/confirmed
+- replay model
+- timeline orchestration
+- authoritative state slices (validated with focused authoritative tests)
+
+Residual blockers:
+- none identified in the targeted Section-4 lane
+
+## Validation Run
+### Node parse checks
+- `node --check` on all touched JS/MJS files: pass
+
+### Focused state-flow checks
+- `tests/replay/ReplaySystem.test.mjs`: pass
+- `tests/replay/ReplayTimeline.test.mjs`: pass
+- `tests/world/WorldGameStateSystem.test.mjs`: pass
+- `tests/world/WorldGameStateAuthoritativeHandoff.test.mjs`: pass
+- `tests/world/WorldGameStateAuthoritativeScore.test.mjs`: pass
+
+### Not run in this focused Node-only invocation
+- `tests/games/GravityWellReplay.test.mjs` depends on browser-style absolute `/src/...` imports in the game scene module and does not execute in the direct Node ESM call used here.
+
+## Changed Files
+- `src/shared/contracts/replayContracts.js`
+- `src/shared/contracts/index.js`
+- `src/shared/state/contracts.js`
+- `src/engine/replay/ReplayModel.js`
+- `src/engine/replay/ReplayTimeline.js`
+- `src/engine/replay/ReplaySystem.js`
+- `src/engine/replay/index.js`
+- `tests/replay/ReplaySystem.test.mjs`
+- `tests/replay/ReplayTimeline.test.mjs`
+- `tests/run-tests.mjs`
+- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`

src/engine/replay/ReplayModel.js

@@ -0,0 +1,62 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/14/2026
+ReplayModel.js
+*/
+import {
+  SHARED_REPLAY_MODEL_CONTRACT_VERSION,
+} from "../../shared/contracts/index.js";
+
+function cloneOrNull(value) {
+  return value === undefined || value === null ? null : structuredClone(value);
+}
+
+function cloneFrames(frames) {
+  if (!Array.isArray(frames)) {
+    return [];
+  }
+  const out = [];
+  for (let i = 0; i < frames.length; i += 1) {
+    out.push(structuredClone(frames[i]));
+  }
+  return out;
+}
+
+function createReplayModel({ metadata = null, initialState = null } = {}) {
+  return {
+    version: SHARED_REPLAY_MODEL_CONTRACT_VERSION,
+    metadata: cloneOrNull(metadata),
+    initialState: cloneOrNull(initialState),
+    frames: [],
+    finalState: null,
+  };
+}
+
+function normalizeReplayModel(input) {
+  if (!input || typeof input !== "object") {
+    return createReplayModel();
+  }
+
+  return {
+    version: Number.isFinite(Number(input.version))
+      ? Number(input.version)
+      : SHARED_REPLAY_MODEL_CONTRACT_VERSION,
+    metadata: cloneOrNull(input.metadata),
+    initialState: cloneOrNull(input.initialState),
+    frames: cloneFrames(input.frames),
+    finalState: cloneOrNull(input.finalState),
+  };
+}
+
+function withFinalState(replay, finalState = null) {
+  const normalized = normalizeReplayModel(replay);
+  normalized.finalState = cloneOrNull(finalState);
+  return normalized;
+}
+
+export {
+  createReplayModel,
+  normalizeReplayModel,
+  withFinalState,
+};

src/engine/replay/ReplaySystem.js

@@ -4,42 +4,49 @@ David Quesenberry
 03/22/2026
 ReplaySystem.js
 */
+import { asNonNegativeInteger } from '../../shared/math/numberNormalization.js';
+import { createReplayModel, normalizeReplayModel, withFinalState } from './ReplayModel.js';
+import { ReplayTimeline } from './ReplayTimeline.js';
+
 export default class ReplaySystem {
-  constructor() {
-    this.replay = this.createReplay();
+  constructor({ timelineWindowFrames } = {}) {
+    this.replay = createReplayModel();
     this.frames = this.replay.frames;
     this.playbackIndex = 0;
     this.recording = false;
     this.playing = false;
+    this.timeline = new ReplayTimeline({ maxFrames: timelineWindowFrames });
   }
 
   createReplay({ metadata = null, initialState = null } = {}) {
-    return {
-      version: 1,
-      metadata: metadata ? structuredClone(metadata) : null,
-      initialState: initialState ? structuredClone(initialState) : null,
-      frames: [],
-      finalState: null,
-    };
+    return createReplayModel({ metadata, initialState });
+  }
+
+  rebuildTimelineFromFrames() {
+    this.timeline.loadFromSnapshots(this.frames);
   }
 
   startRecording({ metadata = null, initialState = null } = {}) {
-    this.replay = this.createReplay({ metadata, initialState });
+    this.replay = createReplayModel({ metadata, initialState });
     this.frames = this.replay.frames;
+    this.timeline.clear();
     this.recording = true;
     this.playing = false;
     this.playbackIndex = 0;
   }
 
   recordFrame(frame) {
     if (this.recording) {
-      this.frames.push(structuredClone(frame));
+      const clonedFrame = structuredClone(frame);
+      this.frames.push(clonedFrame);
+      this.timeline.pushSnapshot(this.frames.length - 1, clonedFrame);
     }
   }
 
   stopRecording({ finalState = null } = {}) {
     this.recording = false;
-    this.replay.finalState = finalState ? structuredClone(finalState) : null;
+    this.replay = withFinalState(this.replay, finalState);
+    this.frames = this.replay.frames;
     return [...this.frames];
   }
 
@@ -48,8 +55,9 @@ export default class ReplaySystem {
   }
 
   loadReplay(replay) {
-    this.replay = replay ? structuredClone(replay) : this.createReplay();
+    this.replay = normalizeReplayModel(replay);
     this.frames = this.replay.frames;
+    this.rebuildTimelineFromFrames();
     this.playbackIndex = 0;
     this.recording = false;
     this.playing = false;
@@ -72,6 +80,39 @@ export default class ReplaySystem {
     return true;
   }
 
+  getTimeline() {
+    return this.timeline.toArray();
+  }
+
+  getTimelineSnapshot(frameId) {
+    return this.timeline.getSnapshot(frameId);
+  }
+
+  getNearestTimelineSnapshot(frameId) {
+    return this.timeline.getNearestSnapshot(frameId);
+  }
+
+  replaceReplayFromFrame(frameId, frames = []) {
+    const normalizedFrameId = asNonNegativeInteger(frameId, this.frames.length);
+    const prefix = this.frames.slice(0, normalizedFrameId);
+    const replacementFrames = Array.isArray(frames)
+      ? frames.map((frame) => structuredClone(frame))
+      : [];
+    const nextFrames = [...prefix, ...replacementFrames];
+
+    this.replay = normalizeReplayModel({
+      ...this.replay,
+      frames: nextFrames
+    });
+    this.frames = this.replay.frames;
+    this.timeline.replaceFromFrame(normalizedFrameId, replacementFrames);
+    if (this.playbackIndex > this.frames.length) {
+      this.playbackIndex = this.frames.length;
+    }
+
+    return this.getReplay();
+  }
+
   nextFrame() {
     if (!this.playing || this.playbackIndex >= this.frames.length) {
       this.playing = false;