Plan multi-entity rewind and reconciliation support for Level 11

DavidQ · DavidQ · commit cc50f8de545b · 2026-04-06T12:54:18.000-04:00
- Defines per-entity timeline buffers
- Establishes entity-scoped reconciliation
- Introduces selective rewind strategy
- Expands debug visualization to multi-entity context

Docs-only PR
diff --git a/docs/dev/CODEX_COMMANDS.md b/docs/dev/CODEX_COMMANDS.md
@@ -2,15 +2,14 @@ MODEL: GPT-5.3-codex
 REASONING: high
 
 COMMAND:
-Apply and validate the existing Level 11.4 rewind execution implementation in `games/network_sample_c` only.
+Implement multi-entity timeline and selective rewind support in network_sample_c only.
 
-Perform:
-- targeted import checks
-- targeted smoke checks for rewind prep and replay
-- manual validation support for W/X controls and debug outputs
-- surgical fixes only if validation reveals a defect
+- Introduce per-entity timeline buffers
+- Update reconciliation to operate per entity
+- Implement selective rewind execution
+- Extend debug visualization for multiple entities
 
 DO NOT:
-- modify engine core APIs
-- create or edit documentation
-- expand scope beyond `network_sample_c`
+- Modify engine core APIs
+- Create or edit documentation
+- Expand beyond sample scope
diff --git a/docs/dev/COMMIT_COMMENT.txt b/docs/dev/COMMIT_COMMENT.txt
@@ -1,12 +1,8 @@
-Apply Level 11.4 rewind execution candidate for Sample C
+Plan multi-entity rewind and reconciliation support for Level 11
 
-- Validates rewind execution and deterministic replay in network_sample_c
-- Confirms timeline truncation and replay repopulation behavior
-- Confirms replay status is surfaced through debug outputs
-- Preserves strict sample-only scope with no engine-core changes
+- Defines per-entity timeline buffers
+- Establishes entity-scoped reconciliation
+- Introduces selective rewind strategy
+- Expands debug visualization to multi-entity context
 
-Validation:
-- imports pass
-- rewind prep reaches ready
-- replay executes successfully
-- bounded timeline remains correct after replay
+Docs-only PR
diff --git a/docs/dev/DEBUG_MULTI_ENTITY_SPEC.md b/docs/dev/DEBUG_MULTI_ENTITY_SPEC.md
@@ -0,0 +1,9 @@
+# Debug Multi-Entity Spec
+
+## Additions
+- Per-entity timeline view
+- Divergence markers per entity
+- Replay visualization per entity
+
+## Goal
+Clear visibility of entity-specific corrections
diff --git a/docs/dev/ENTITY_RECONCILIATION_SPEC.md b/docs/dev/ENTITY_RECONCILIATION_SPEC.md
@@ -0,0 +1,12 @@
+# Entity Reconciliation Spec
+
+## Concept
+Reconciliation operates per entity instead of globally.
+
+## Requirements
+- Compute divergence per entity
+- Generate correction plans independently
+- Allow multiple corrections in same frame
+
+## Outcome
+No cross-entity contamination
diff --git a/docs/dev/MULTI_ENTITY_TIMELINE_SPEC.md b/docs/dev/MULTI_ENTITY_TIMELINE_SPEC.md
@@ -0,0 +1,14 @@
+# Multi-Entity Timeline Spec
+
+## Approach Options
+1. Per-entity timeline buffers (preferred)
+2. Shared timeline with entity partitions
+
+## Requirements
+- Each entity maintains:
+  - input history
+  - predicted state history
+  - frame id linkage
+
+## Recommendation
+Start with per-entity buffers for simplicity and isolation
diff --git a/docs/dev/SELECTIVE_REWIND_SPEC.md b/docs/dev/SELECTIVE_REWIND_SPEC.md
@@ -0,0 +1,12 @@
+# Selective Rewind Spec
+
+## Goal
+Only rewind entities that diverged.
+
+## Flow
+1. Identify entities with divergence
+2. Rewind only those entities to anchor frame
+3. Replay inputs forward per entity
+
+## Benefit
+Improves performance and avoids unnecessary corrections
diff --git a/docs/dev/reports/change_summary.txt b/docs/dev/reports/change_summary.txt
@@ -1 +1 @@
-Adds APPLY_PR bundle for Level 11.4 rewind execution validation and guarded integration in Sample C.
+Adds Level 11.5 planning docs for multi-entity rewind and reconciliation
diff --git a/docs/dev/reports/file_tree.txt b/docs/dev/reports/file_tree.txt
@@ -1,10 +1,11 @@
 docs/
   pr/
-    APPLY_PR_LEVEL_11_4_REWIND_EXECUTION_CANDIDATE.md
+    PLAN_PR_LEVEL_11_5_MULTI_ENTITY_SUPPORT.md
   dev/
-    APPLY_VALIDATION_SPEC.md
-    INTEGRATION_NOTES.md
-    ROLLBACK_GUARDRAILS.md
+    MULTI_ENTITY_TIMELINE_SPEC.md
+    ENTITY_RECONCILIATION_SPEC.md
+    SELECTIVE_REWIND_SPEC.md
+    DEBUG_MULTI_ENTITY_SPEC.md
     codex_commands.md
     commit_comment.txt
     reports/
diff --git a/docs/dev/reports/validation_checklist.txt b/docs/dev/reports/validation_checklist.txt
@@ -1,5 +1,4 @@
-- Docs-only APPLY bundle
-- No engine-core scope
-- No documentation delegated to Codex
-- Validation focused on Sample C rewind execution only
-- Repo structure preserved
+- Docs only
+- No engine changes
+- Sample-scoped design
+- Matches repo conventions
diff --git a/docs/pr/PLAN_PR_LEVEL_11_5_MULTI_ENTITY_SUPPORT.md b/docs/pr/PLAN_PR_LEVEL_11_5_MULTI_ENTITY_SUPPORT.md
@@ -0,0 +1,18 @@
+# PLAN PR LEVEL 11.5 — Multi-Entity Support
+
+## Objective
+Extend the rewind/replay system from single-entity to multi-entity while preserving determinism and isolation.
+
+## Scope
+- Per-entity timeline tracking
+- Entity-scoped reconciliation
+- Selective rewind (affected entities only)
+- Debug visualization per entity
+
+## Constraints
+- No engine-core changes
+- Sample-layer only (network_sample_c)
+- Maintain deterministic replay rules
+
+## Outcome
+System supports multiple entities with independent timelines and corrections without global side effects
diff --git a/docs/roadmaps/BIG_PICTURE_ROADMAP.md b/docs/roadmaps/BIG_PICTURE_ROADMAP.md
diff --git a/docs/roadmaps/NETWORK_SAMPLES_PLAN.md b/docs/roadmaps/NETWORK_SAMPLES_PLAN.md
diff --git a/docs/roadmaps/PRODUCTIZATION_ROADMAP.md b/docs/roadmaps/PRODUCTIZATION_ROADMAP.md
diff --git a/docs/roadmaps/big_picture_roadmap_text.md b/docs/roadmaps/big_picture_roadmap_text.md
diff --git a/games/network_sample_c/game/ReconciliationLayerAdapter.js b/games/network_sample_c/game/ReconciliationLayerAdapter.js
@@ -51,6 +51,16 @@ function cloneSnapshot(snapshot) {
   };
 }
 
+function cloneEntitySnapshot(entity) {
+  const source = entity && typeof entity === "object" ? entity : {};
+  return {
+    ...source,
+    position: source.position ? { ...source.position } : undefined,
+    velocity: source.velocity ? { ...source.velocity } : undefined,
+    stateFlags: source.stateFlags ? { ...source.stateFlags } : undefined
+  };
+}
+
 function computeVectorDelta(predictedVector, authoritativeVector) {
   const predictedX = asFiniteNumber(predictedVector?.x);
   const predictedY = asFiniteNumber(predictedVector?.y);
@@ -125,6 +135,7 @@ export default class ReconciliationLayerAdapter {
 
     this.maxAuthoritativeHistory = asPositiveInteger(options.maxAuthoritativeHistory, 60);
     this.authoritativeHistory = [];
+    this.entityTimelineBuffers = new Map();
     this.latestAuthoritativeSnapshot = null;
     this.latestEventEnvelope = null;
     this.latestDivergenceReport = null;
@@ -144,13 +155,70 @@ export default class ReconciliationLayerAdapter {
     };
   }
 
+  getOrCreateEntityTimelineBuffer(entityId) {
+    const normalizedEntityId = sanitizeText(entityId);
+    if (!normalizedEntityId) {
+      return null;
+    }
+
+    if (!this.entityTimelineBuffers.has(normalizedEntityId)) {
+      this.entityTimelineBuffers.set(normalizedEntityId, new StateTimelineBuffer({
+        maxFrames: this.timelineBuffer.getMaxFrames()
+      }));
+    }
+    return this.entityTimelineBuffers.get(normalizedEntityId);
+  }
+
+  listEntityTimelineIds() {
+    return Array.from(this.entityTimelineBuffers.keys());
+  }
+
+  extractEntityFromSnapshot(snapshot, entityId) {
+    const entities = Array.isArray(snapshot?.entities) ? snapshot.entities : [];
+    return entities.find((entity) => sanitizeText(entity?.entityId) === entityId) || null;
+  }
+
+  buildEntityPredictedRecord(frameId, timestampMs, entity, snapshotMeta) {
+    return {
+      frameId,
+      timestampMs,
+      entity: cloneEntitySnapshot(entity),
+      meta: snapshotMeta && typeof snapshotMeta === "object"
+        ? { ...snapshotMeta }
+        : undefined
+    };
+  }
+
   recordPredictedSnapshot(snapshot = {}) {
     const source = cloneSnapshot(snapshot);
     const frameId = asFiniteNumber(source.frameId, NaN);
     if (!Number.isFinite(frameId)) {
       return false;
     }
-    return this.timelineBuffer.pushSnapshot(frameId, source);
+
+    const normalizedFrameId = Math.floor(frameId);
+    const pushedGlobal = this.timelineBuffer.pushSnapshot(normalizedFrameId, source);
+
+    const entities = Array.isArray(source.entities) ? source.entities : [];
+    entities.forEach((entity) => {
+      const entityId = sanitizeText(entity?.entityId);
+      if (!entityId) {
+        return;
+      }
+
+      const entityTimeline = this.getOrCreateEntityTimelineBuffer(entityId);
+      entityTimeline?.pushSnapshot(
+        normalizedFrameId,
+        this.buildEntityPredictedRecord(
+          normalizedFrameId,
+          asFiniteNumber(source.timestampMs, Date.now()),
+          entity,
+          source.meta
+        )
+      );
+    });
+
+    return pushedGlobal;
   }
 
   receiveAuthoritativeSnapshot(snapshot = {}, envelope = {}) {
@@ -175,6 +243,31 @@ export default class ReconciliationLayerAdapter {
     return true;
   }
 
+  resolvePredictedEntityMatch(entityId, authoritativeFrameId, globalMatch) {
+    const entityTimeline = this.getOrCreateEntityTimelineBuffer(entityId);
+    const entityMatch = entityTimeline?.getNearestSnapshot(authoritativeFrameId) || null;
+    if (entityMatch) {
+      return {
+        frameId: entityMatch.frameId,
+        alignment: entityMatch.alignment || "approximate",
+        entity: cloneEntitySnapshot(entityMatch.snapshot?.entity),
+        source: "entity-timeline"
+      };
+    }
+
+    const fallbackEntity = this.extractEntityFromSnapshot(globalMatch?.snapshot, entityId);
+    if (fallbackEntity) {
+      return {
+        frameId: globalMatch?.frameId ?? null,
+        alignment: globalMatch?.alignment || "approximate",
+        entity: cloneEntitySnapshot(fallbackEntity),
+        source: "global-fallback"
+      };
+    }
+
+    return null;
+  }
+
   reconcileLatest() {
     const authoritative = this.latestAuthoritativeSnapshot;
     if (!authoritative || !Number.isFinite(Number(authoritative.frameId))) {
@@ -220,17 +313,8 @@ export default class ReconciliationLayerAdapter {
 
     const predictedFrameId = predictedMatch.frameId;
     const alignment = predictedMatch.alignment || "approximate";
-    const predictedSnapshot = predictedMatch.snapshot || {};
-    const predictedEntities = new Map();
     const authoritativeEntities = new Map();
 
-    (Array.isArray(predictedSnapshot.entities) ? predictedSnapshot.entities : []).forEach((entity) => {
-      const entityId = sanitizeText(entity?.entityId);
-      if (entityId) {
-        predictedEntities.set(entityId, entity);
-      }
-    });
-
     (Array.isArray(authoritative.entities) ? authoritative.entities : []).forEach((entity) => {
       const entityId = sanitizeText(entity?.entityId);
       if (entityId) {
@@ -239,21 +323,24 @@ export default class ReconciliationLayerAdapter {
     });
 
     const allEntityIds = new Set([
-      ...predictedEntities.keys(),
+      ...this.listEntityTimelineIds(),
       ...authoritativeEntities.keys()
     ]);
 
     let highestSeverity = "low";
     const entityReports = [];
     allEntityIds.forEach((entityId) => {
-      const predictedEntity = predictedEntities.get(entityId) || {};
+      const predictedMatchForEntity = this.resolvePredictedEntityMatch(entityId, authoritativeFrameId, predictedMatch);
+      const predictedEntity = predictedMatchForEntity?.entity || {};
       const authoritativeEntity = authoritativeEntities.get(entityId) || {};
       const positionDelta = computeVectorDelta(predictedEntity.position, authoritativeEntity.position);
       const velocityDelta = computeVectorDelta(predictedEntity.velocity, authoritativeEntity.velocity);
       const stateFlagsDelta = computeStateFlagsDelta(predictedEntity.stateFlags, authoritativeEntity.stateFlags);
-      const frameGap = Math.max(0, authoritativeFrameId - predictedFrameId);
+      const frameGap = predictedMatchForEntity && Number.isFinite(Number(predictedMatchForEntity.frameId))
+        ? Math.max(0, authoritativeFrameId - Number(predictedMatchForEntity.frameId))
+        : null;
       const severity = severityFromDeltas({
-        frameGap,
+        frameGap: frameGap ?? 999,
         positionMagnitude: positionDelta.magnitude,
         velocityMagnitude: velocityDelta.magnitude,
         flagsDeltaCount: stateFlagsDelta.length
@@ -262,12 +349,15 @@ export default class ReconciliationLayerAdapter {
 
       entityReports.push({
         entityId,
-        predictedFrame: asFiniteNumber(predictedEntity.frameValue, predictedFrameId),
+        predictedFrame: asFiniteNumber(predictedEntity.frameValue, predictedMatchForEntity?.frameId ?? predictedFrameId),
         authoritativeFrame: asFiniteNumber(authoritativeEntity.frameValue, authoritativeFrameId),
+        matchedPredictedFrameId: predictedMatchForEntity?.frameId ?? null,
+        alignment: predictedMatchForEntity?.alignment || "unavailable",
+        frameGap,
         positionDelta,
         velocityDelta,
         stateFlagsDelta,
-        correctionMode: correctionModeFromSeverity(severity, alignment),
+        correctionMode: correctionModeFromSeverity(severity, predictedMatchForEntity?.alignment || alignment),
         severity
       });
     });
@@ -284,7 +374,8 @@ export default class ReconciliationLayerAdapter {
         authoritativeFrameId,
         frameGap,
         highestSeverity,
-        unresolvedCount
+        unresolvedCount,
+        entityCount: entityReports.length
       },
       entityReports,
       envelope: this.latestEventEnvelope
@@ -295,7 +386,13 @@ export default class ReconciliationLayerAdapter {
       severity: highestSeverity,
       reason: this.toCorrectionReason(correctionMode, alignment),
       targetFrameId: authoritativeFrameId,
-      applyAtFrameId: authoritativeFrameId + (correctionMode === "snap" ? 0 : 1)
+      applyAtFrameId: authoritativeFrameId + (correctionMode === "snap" ? 0 : 1),
+      entityModes: entityReports.map((entity) => ({
+        entityId: entity.entityId,
+        severity: entity.severity,
+        correctionMode: entity.correctionMode,
+        frameGap: entity.frameGap
+      }))
     };
 
     this.latestRewindPreparation = this.buildRewindPreparation({

Original file line number	Diff line number	Diff line change
`@@ -1 +1 @@`
`1`		`-Adds APPLY_PR bundle for Level 11.4 rewind execution validation and guarded integration in Sample C.`
	`1`	`+Adds Level 11.5 planning docs for multi-entity rewind and reconciliation`