Plan timeline rewind preparation for Level 11 network architecture

DavidQ · DavidQ · commit 98368e200fe8 · 2026-04-06T12:32:00.000-04:00
- Defines frame history buffer
- Establishes rewind strategy
- Introduces authoritative injection model
- Expands debug visualization concepts

Docs-only PR
diff --git a/docs/dev/AUTHORITATIVE_INJECTION_SPEC.md b/docs/dev/AUTHORITATIVE_INJECTION_SPEC.md
@@ -0,0 +1,12 @@
+# Authoritative Injection Specification
+
+## Purpose
+Define where authoritative state enters the system.
+
+## Design
+- Inject at frame boundary
+- Must not overwrite predicted directly
+- Pass through reconciliation layer
+
+## Outcome
+Clean separation of authority vs prediction
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -1,26 +1,7 @@
-MODEL: GPT-5.4
+MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Create BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION as a docs-first implementation plan follow-up for the HTML-JavaScript-Gaming repo.
-
-Requirements:
-- Use docs/dev/RECONCILIATION_LAYER_SPEC.md, docs/dev/STATE_TIMELINE_SPEC.md, and docs/dev/DEBUG_SURFACE_CONTRACT.md as source guidance.
-- Preserve current repo workflow conventions.
-- Do not modify engine core APIs.
-- Do not add server-dashboard, docker, or transport implementation.
-- Keep Sample C as a consumer/proving ground, not the shared implementation itself.
-- Normalize any proposed interfaces around approved public selectors/events only.
-- Prefer sample-level layering and bounded history buffers.
-- Future-proof naming away from sample-specific ad hoc wiring.
-- Package outputs as a repo-structured ZIP at:
-  HTML-JavaScript-Gaming/tmp/BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION_delta.zip
-
-Expected outputs:
-- docs/pr/BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION.md
-- docs/dev/reports/file_tree.txt
-- docs/dev/reports/change_summary.txt
-- docs/dev/reports/validation_checklist.txt
-- docs/dev/commit_comment.txt
-
-Do not write implementation code unless explicitly required by the build instructions. Keep this bundle docs/planning only.
+Implement timeline buffer and rewind preparation based on provided specs.
+Do not modify engine core APIs.
+Keep implementation isolated to network samples.
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,8 +1,8 @@
-Build Level 11.2 reconciliation layer foundation (docs-first)
+Plan timeline rewind preparation for Level 11 network architecture
 
-- Create BUILD follow-up plan from reconciliation/timeline/debug contract specs
-- Preserve PLAN_PR -> BUILD_PR -> APPLY_PR workflow conventions
-- Keep Sample C as proving-ground consumer, not shared layer implementation
-- Normalize future interfaces around approved public selectors/events only
-- Require sample-level layering and bounded history buffers
-- Explicitly exclude engine-core, server-dashboard, docker, and transport implementation
+- Defines frame history buffer
+- Establishes rewind strategy
+- Introduces authoritative injection model
+- Expands debug visualization concepts
+
+Docs-only PR
diff --git a/docs/dev/DEBUG_TIMELINE_VISUALIZATION.md b/docs/dev/DEBUG_TIMELINE_VISUALIZATION.md
@@ -0,0 +1,13 @@
+# Debug Timeline Visualization
+
+## Goals
+- Show state over time
+- Highlight corrections
+
+## Concepts
+- Timeline bar
+- Frame markers
+- Delta visualization
+
+## Future
+Scrubbing and replay controls
diff --git a/docs/dev/FRAME_HISTORY_SPEC.md b/docs/dev/FRAME_HISTORY_SPEC.md
@@ -0,0 +1,14 @@
+# Frame History Specification
+
+## Purpose
+Store recent frames for rewind and replay.
+
+## Requirements
+- Ring buffer (fixed size)
+- Store:
+  - input
+  - predicted state
+  - timestamp
+
+## Notes
+Keep lightweight and sample-scoped
diff --git a/docs/dev/REWIND_STRATEGY_SPEC.md b/docs/dev/REWIND_STRATEGY_SPEC.md
@@ -0,0 +1,13 @@
+# Rewind Strategy Specification
+
+## Concept
+Rewind to authoritative frame and re-simulate forward.
+
+## Steps
+1. Receive authoritative state
+2. Find matching frame in buffer
+3. Replace predicted state
+4. Reapply inputs forward
+
+## Notes
+No full implementation yet — design only
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1,20 +1 @@
-CHANGE SUMMARY
-
-Created a docs-only BUILD follow-up bundle for Level 11.2 reconciliation-layer foundation work.
-
-Included:
-- BUILD PR doc for Level 11.2 reconciliation-layer foundation
-- Updated report artifacts (file tree, change summary, validation checklist)
-- Updated commit comment for this BUILD bundle
-
-Guided by:
-- docs/dev/RECONCILIATION_LAYER_SPEC.md
-- docs/dev/STATE_TIMELINE_SPEC.md
-- docs/dev/DEBUG_SURFACE_CONTRACT.md
-
-Key BUILD outcomes:
-- preserve workflow convention (PLAN_PR -> BUILD_PR -> APPLY_PR)
-- keep Sample C as a consumer/proving ground, not shared implementation
-- normalize future interfaces around approved public selectors/events only
-- prefer sample-level layering with bounded history buffers
-- avoid engine-core, server-dashboard, docker, and transport implementation scope
+Adds Level 11.3 planning docs for timeline rewind preparation
diff --git a/docs/dev/reports/file_tree.txt b/docs/dev/reports/file_tree.txt
@@ -1,10 +1,14 @@
-BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION/
-`-- docs/
-    |-- dev/
-    |   |-- commit_comment.txt
-    |   `-- reports/
-    |       |-- change_summary.txt
-    |       |-- file_tree.txt
-    |       `-- validation_checklist.txt
-    `-- pr/
-        `-- BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION.md
+docs/
+  pr/
+    PLAN_PR_LEVEL_11_3_TIMELINE_REWIND_PREP.md
+  dev/
+    FRAME_HISTORY_SPEC.md
+    REWIND_STRATEGY_SPEC.md
+    AUTHORITATIVE_INJECTION_SPEC.md
+    DEBUG_TIMELINE_VISUALIZATION.md
+    codex_commands.md
+    commit_comment.txt
+    reports/
+      file_tree.txt
+      change_summary.txt
+      validation_checklist.txt
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,17 +1,3 @@
-VALIDATION CHECKLIST
-
-[ ] Bundle remains docs/planning only
-[ ] BUILD doc exists at docs/pr/BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION.md
-[ ] Source guidance references reconciliation/timeline/debug contract specs
-[ ] Workflow convention preserved as PLAN_PR -> BUILD_PR -> APPLY_PR
-[ ] Proposed interfaces constrained to approved public selectors/events only
-[ ] Sample C retained as consumer/proving ground, not shared runtime implementation
-[ ] Future-proof neutral naming guidance included (no sample-specific ad hoc shared names)
-[ ] Bounded history buffer guidance included
-[ ] No engine-core API changes proposed
-[ ] No server-dashboard implementation proposed
-[ ] No docker/container implementation proposed
-[ ] No transport implementation proposed
-[ ] commit_comment.txt updated for this BUILD bundle
-[ ] reports/file_tree.txt reflects this BUILD bundle structure
-[ ] reports/change_summary.txt reflects this BUILD bundle intent
+- Docs only
+- No engine changes
+- Structure matches repo conventions
diff --git a/docs/pr/PLAN_PR_LEVEL_11_3_TIMELINE_REWIND_PREP.md b/docs/pr/PLAN_PR_LEVEL_11_3_TIMELINE_REWIND_PREP.md
@@ -0,0 +1,18 @@
+# PLAN PR LEVEL 11.3 — Timeline Rewind Preparation
+
+## Objective
+Introduce time-aware architecture to support rewind and replay for authoritative correction.
+
+## Scope
+- Frame history buffer design
+- Authoritative state injection
+- Rewind strategy (design only)
+- Debug timeline visualization concepts
+
+## Constraints
+- No engine-core changes
+- No production networking
+- Sample-layer only implementation
+
+## Outcomes
+Establish groundwork for deterministic rewind and replay in Level 11.4
diff --git a/games/network_sample_c/debug/networkSampleCDebug.js b/games/network_sample_c/debug/networkSampleCDebug.js
@@ -38,10 +38,12 @@ function toDivergenceLines(snapshot) {
 
   return [
     `status=${sanitizeText(divergence.status) || "unknown"}`,
+    `severity=${sanitizeText(divergence.severity) || "low"} correction=${sanitizeText(divergence.correctionMode) || "hold-annotate"}`,
     `phase=${sanitizeText(scenario.phaseLabel) || "n/a"} (${sanitizeText(scenario.phaseId) || "n/a"})`,
     `frameDelta=${asNumber(divergence.frameDelta, 0)}`,
     `authoritativeFrame=${asNumber(divergence.authoritativeFrame, 0)}`,
     `predictedFrame=${asNumber(divergence.predictedFrame, 0)}`,
+    `alignment=${sanitizeText(divergence.alignment) || "unavailable"}`,
     `targetOffsetFrames=${asNumber(divergence.targetOffsetFrames, 0).toFixed(2)}`,
     `rttMs=${asNumber(transport.rttMs, 0)} jitterMs=${asNumber(transport.jitterMs, 0)} lossPct=${asNumber(transport.packetLossPct, 0)}`,
     `hint=${sanitizeText(divergence.reconciliationHint) || "n/a"}`
@@ -51,19 +53,27 @@ function toDivergenceLines(snapshot) {
 function toTimelineLines(snapshot) {
   const network = toNetworkSnapshot(snapshot);
   const timeline = asObject(network.timeline);
+  const history = asObject(timeline.history);
   const events = asArray(timeline.events);
+  const lines = [
+    `history=${asNumber(history.size, 0)}/${asNumber(history.limit, 0)}`,
+    `oldestFrame=${history.oldestFrameId ?? "n/a"} latestFrame=${history.latestFrameId ?? "n/a"}`,
+    `alignment=${sanitizeText(history.alignment) || "unavailable"} frameGap=${history.frameGap ?? "n/a"}`
+  ];
 
   if (events.length === 0) {
-    return ["No timeline events recorded yet."];
+    lines.push("No timeline events recorded yet.");
+    return lines;
   }
 
-  return events
-    .slice(-8)
+  events
+    .slice(-6)
     .reverse()
-    .map((event) => {
+    .forEach((event) => {
       const source = asObject(event);
-      return `${asNumber(source.timestampMs, 0)}ms ${sanitizeText(source.type) || "EVENT"} phase=${sanitizeText(source.phaseId) || "unknown"}`;
+      lines.push(`${asNumber(source.timestampMs, 0)}ms ${sanitizeText(source.type) || "EVENT"} phase=${sanitizeText(source.phaseId) || "unknown"}`);
     });
+  return lines;
 }
 
 function toValidationLines(snapshot) {
@@ -84,6 +94,22 @@ function toValidationLines(snapshot) {
   return lines;
 }
 
+function toRewindLines(snapshot) {
+  const network = toNetworkSnapshot(snapshot);
+  const rewind = asObject(network.rewindPreparation);
+  const correction = asObject(network.correction);
+
+  return [
+    `status=${sanitizeText(rewind.status) || "n/a"}`,
+    `canPrepare=${Boolean(rewind.canPrepare)}`,
+    `anchorFrame=${rewind.rewindAnchorFrameId ?? "n/a"} targetFrame=${rewind.rewindTargetFrameId ?? "n/a"}`,
+    `resimulateFrameCount=${asNumber(rewind.resimulateFrameCount, 0)}`,
+    `alignment=${sanitizeText(rewind.alignment) || "unavailable"} frameGap=${rewind.frameGap ?? "n/a"}`,
+    `correctionMode=${sanitizeText(correction.mode) || "hold-annotate"} severity=${sanitizeText(correction.severity) || "low"}`,
+    sanitizeText(rewind.note) || "No rewind preparation note."
+  ];
+}
+
 function toTraceLines(snapshot, maxLines = 10) {
   const network = toNetworkSnapshot(snapshot);
   const trace = asObject(network.trace);
@@ -114,6 +140,9 @@ function commandLinesForDivergence(context) {
 
   return [
     `status=${sanitizeText(divergence.status) || "unknown"}`,
+    `severity=${sanitizeText(divergence.severity) || "low"}`,
+    `correctionMode=${sanitizeText(divergence.correctionMode) || "hold-annotate"}`,
+    `alignment=${sanitizeText(divergence.alignment) || "unavailable"}`,
     `phase=${sanitizeText(scenario.phaseId) || "unknown"}`,
     `phaseElapsed=${asNumber(scenario.phaseElapsedSeconds, 0).toFixed(2)}s/${asNumber(scenario.phaseDurationSeconds, 0).toFixed(2)}s`,
     `cycleCount=${asNumber(scenario.cycleCount, 0)}`,
@@ -188,6 +217,25 @@ function commandLinesForReproduction(context) {
   return lines;
 }
 
+function commandLinesForRewind(context) {
+  const snapshot = getCommandSnapshot(context);
+  const rewind = asObject(snapshot.rewindPreparation);
+  const timeline = asObject(snapshot.timeline);
+  const history = asObject(timeline.history);
+  const correction = asObject(snapshot.correction);
+
+  return [
+    `rewindStatus=${sanitizeText(rewind.status) || "n/a"}`,
+    `canPrepare=${Boolean(rewind.canPrepare)}`,
+    `rewindAnchorFrame=${rewind.rewindAnchorFrameId ?? "n/a"}`,
+    `rewindTargetFrame=${rewind.rewindTargetFrameId ?? "n/a"}`,
+    `resimulateFrameCount=${asNumber(rewind.resimulateFrameCount, 0)}`,
+    `history=${asNumber(history.size, 0)}/${asNumber(history.limit, 0)} alignment=${sanitizeText(history.alignment) || "unavailable"} frameGap=${history.frameGap ?? "n/a"}`,
+    `correctionMode=${sanitizeText(correction.mode) || "hold-annotate"} severity=${sanitizeText(correction.severity) || "low"}`,
+    sanitizeText(rewind.note) || "Rewind preparation status unavailable."
+  ];
+}
+
 export function createNetworkSampleCDebugPlugin() {
   return {
     pluginId: "network.sampleC",
@@ -225,6 +273,12 @@ export function createNetworkSampleCDebugPlugin() {
           title: "Sample C Trace Provider",
           readOnly: true,
           sourcePath: "assets.networkSampleC.trace"
+        },
+        {
+          providerId: "network.sampleC.rewind",
+          title: "Sample C Rewind Preparation Provider",
+          readOnly: true,
+          sourcePath: "assets.networkSampleC.rewindPreparation"
         }
       ];
     },
@@ -289,6 +343,21 @@ export function createNetworkSampleCDebugPlugin() {
               lines: toTraceLines(snapshot, 10)
             };
           }
+        },
+        {
+          id: "network-c-rewind-prep",
+          title: "Rewind Preparation",
+          enabled: true,
+          priority: 1164,
+          source: "assets",
+          renderMode: "text-block",
+          render(_panel, snapshot) {
+            return {
+              id: "network-c-rewind-prep",
+              title: "Rewind Preparation",
+              lines: toRewindLines(snapshot)
+            };
+          }
         }
       ];
     },
@@ -312,7 +381,8 @@ export function createNetworkSampleCDebugPlugin() {
                     "network.divergence",
                     "network.trace [count]",
                     "network.validate",
-                    "network.sample.repro"
+                    "network.sample.repro",
+                    "network.rewind"
                   ],
                   code: "NETWORK_HELP"
                 };
@@ -370,6 +440,19 @@ export function createNetworkSampleCDebugPlugin() {
                   code: "NETWORK_SAMPLE_REPRO"
                 };
               }
+            },
+            {
+              name: "network.rewind",
+              summary: "Show rewind preparation status and resimulation window details.",
+              usage: "network.rewind",
+              handler(context) {
+                return {
+                  status: "ready",
+                  title: "Network Rewind Preparation",
+                  lines: commandLinesForRewind(context),
+                  code: "NETWORK_REWIND"
+                };
+              }
             }
           ]
         }
diff --git a/games/network_sample_c/game/FakeDivergenceTraceNetworkModel.js b/games/network_sample_c/game/FakeDivergenceTraceNetworkModel.js
diff --git a/games/network_sample_c/game/NetworkSampleCScene.js b/games/network_sample_c/game/NetworkSampleCScene.js
diff --git a/games/network_sample_c/game/ReconciliationLayerAdapter.js b/games/network_sample_c/game/ReconciliationLayerAdapter.js
diff --git a/games/network_sample_c/game/StateTimelineBuffer.js b/games/network_sample_c/game/StateTimelineBuffer.js
diff --git a/games/network_sample_c/index.html b/games/network_sample_c/index.html
