PR_07_03_NETWORK_LATENCY_MODELING

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,20 +2,20 @@ MODEL: GPT-5.4
 REASONING: medium
 
 COMMAND:
-Implement PR_07_02_NETWORK_SIMULATION_BASELINE.
+Implement PR_07_03_NETWORK_LATENCY_MODELING.
 
 Goal:
-Establish deterministic simulation baseline.
+Add latency modeling to simulation.
 
 Steps:
-1. Define simulation tick model.
-2. Ensure deterministic update loop.
-3. Validate consistency.
+1. Define latency model (delay/jitter).
+2. Inject into simulation inputs.
+3. Validate behavior.
 
 Rules:
 - no networking
-- no latency modeling
-- no behavior changes
+- no reconciliation
+- no behavior changes outside latency simulation
 
 Return ZIP:
-<project folder>/tmp/PR_07_02_NETWORK_SIMULATION_BASELINE.zip
+<project folder>/tmp/PR_07_03_NETWORK_LATENCY_MODELING.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-PR_07_02_NETWORK_SIMULATION_BASELINE
+PR_07_03_NETWORK_LATENCY_MODELING

docs/dev/reports/validation_checklist.txt

@@ -1,3 +1,3 @@
-[ ] simulation tick model defined
-[ ] deterministic loop confirmed
-[ ] consistency validated
+[ ] latency model defined
+[ ] latency injection applied
+[ ] validation complete

docs/pr/PR_07_03_NETWORK_LATENCY_MODELING.md

@@ -0,0 +1,27 @@
+# PR_07_03_NETWORK_LATENCY_MODELING
+
+## Purpose
+Introduce latency modeling for Phase 13 simulation.
+
+## Scope
+- latency simulation only
+- no real networking
+- no reconciliation yet
+- no behavior changes
+
+## Tasks
+1. Define latency injection model (delay, jitter).
+2. Apply latency to simulation inputs/events.
+3. Validate delayed state propagation.
+
+## Deliverables
+- docs/dev/reports/latency_model.txt
+- docs/dev/reports/validation_checklist.txt
+
+## Validation
+- latency effects observable
+- deterministic baseline preserved when disabled
+- no regressions
+
+## Output
+<project folder>/tmp/PR_07_03_NETWORK_LATENCY_MODELING.zip

samples/phase-13/1316/game/FakeLoopbackNetworkModel.js

@@ -7,6 +7,7 @@ FakeLoopbackNetworkModel.js
 
 import { clamp } from "/src/engine/utils/index.js";
 import { asPositiveNumber } from '../../../_shared/numberUtils.js';
+import { createLatencyModel } from "/samples/phase-13/_shared/latencyModel.js";
 
 const MAX_TRACE_EVENTS = 80;
 
@@ -43,7 +44,12 @@ export default class FakeLoopbackNetworkModel {
 
     this.autoPacketTimerSeconds = 0;
     this.autoPacketIntervalSeconds = 0.65;
-    this.lastAckTimerSeconds = 0;
+    this.inFlightPackets = [];
+    this.latencyModel = createLatencyModel({
+      baseRttMs: 30,
+      jitterMs: 4,
+      minOneWayMs: 8
+    });
 
     this.traceEvents = [];
 
@@ -92,7 +98,7 @@ export default class FakeLoopbackNetworkModel {
     if (normalizedNext === "disconnected") {
       this.pendingPackets = 0;
       this.replicationBacklog = 0;
-      this.lastAckTimerSeconds = 0;
+      this.inFlightPackets = [];
     }
   }
 
@@ -122,11 +128,20 @@ export default class FakeLoopbackNetworkModel {
     this.sentPackets += 1;
     this.pendingPackets += 1;
     this.replicationTick += 1;
+    const oneWayDelayMs = this.latencyModel.sampleOneWayDelayMs(this.elapsedSeconds, sequence);
+    this.inFlightPackets.push({
+      sequence,
+      label,
+      deliverAtSeconds: this.elapsedSeconds + (oneWayDelayMs / 1000),
+      oneWayDelayMs
+    });
+    this.inFlightPackets.sort((left, right) => left.deliverAtSeconds - right.deliverAtSeconds);
 
     this.pushTrace("PACKET_SENT", {
       label,
       sequence,
-      pendingPackets: this.pendingPackets
+      pendingPackets: this.pendingPackets,
+      oneWayDelayMs
     });
 
     return true;
@@ -162,37 +177,32 @@ export default class FakeLoopbackNetworkModel {
       this.jitterMs = 0;
       return;
     }
-
-    const waveform = Math.sin(this.elapsedSeconds * 1.8);
-    const harmonic = Math.sin(this.elapsedSeconds * 0.45);
-    this.rttMs = Math.round(30 + (waveform * 7) + (harmonic * 3));
-    this.rttMs = clamp(this.rttMs, 16, 70);
-
-    this.jitterMs = Math.round(Math.abs(Math.cos(this.elapsedSeconds * 2.2)) * 4);
-    this.jitterMs = clamp(this.jitterMs, 1, 8);
+    const snapshot = this.latencyModel.sampleSnapshot(this.elapsedSeconds, this.nextSequence);
+    this.rttMs = snapshot.rttMs;
+    this.jitterMs = snapshot.jitterMs;
   }
 
-  updateAcks(dtSeconds) {
+  updateAcks() {
     if (this.phase !== "connected") {
       return;
     }
-
-    this.lastAckTimerSeconds += dtSeconds;
-    const ackInterval = 0.22 + (this.jitterMs / 1000);
-
-    if (this.pendingPackets > 0 && this.lastAckTimerSeconds >= ackInterval) {
-      this.lastAckTimerSeconds = 0;
-      this.pendingPackets -= 1;
-      this.ackedSequence += 1;
+    while (this.inFlightPackets.length > 0 && this.inFlightPackets[0].deliverAtSeconds <= this.elapsedSeconds) {
+      const delivered = this.inFlightPackets.shift();
+      if (!delivered) break;
+      if (this.pendingPackets > 0) {
+        this.pendingPackets -= 1;
+      }
+      this.ackedSequence = Math.max(this.ackedSequence, Number(delivered.sequence) || 0);
       this.receivedPackets += 1;
 
       this.pushTrace("PACKET_ACKED", {
         sequence: this.ackedSequence,
-        pendingPackets: this.pendingPackets
+        pendingPackets: this.pendingPackets,
+        oneWayDelayMs: Number(delivered.oneWayDelayMs || 0)
       });
     }
 
-    this.replicationBacklog = Math.max(0, this.pendingPackets - 1);
+    this.replicationBacklog = Math.max(0, this.inFlightPackets.length);
   }
 
   update(dtSeconds, options = {}) {
@@ -206,7 +216,7 @@ export default class FakeLoopbackNetworkModel {
 
     this.updatePhaseProgress(safeDt);
     this.updateLatencySnapshot();
-    this.updateAcks(safeDt);
+    this.updateAcks();
   }
 
   getSnapshot() {

samples/phase-13/_shared/latencyModel.js

@@ -0,0 +1,33 @@
+import { clamp } from "/src/engine/utils/index.js";
+
+export function createLatencyModel(options = {}) {
+  const baseRttMs = clamp(Number(options.baseRttMs) || 30, 16, 250);
+  const jitterMs = clamp(Number(options.jitterMs) || 4, 0, 40);
+  const minOneWayMs = clamp(Number(options.minOneWayMs) || 8, 1, 200);
+
+  function sampleOneWayDelayMs(elapsedSeconds, sequence = 0) {
+    const t = Math.max(0, Number(elapsedSeconds) || 0);
+    const seq = Math.max(0, Number(sequence) || 0);
+    const phase = t * 1.9 + (seq * 0.17);
+    const harmonic = Math.sin(phase) * jitterMs;
+    const microJitter = Math.sin((t * 0.53) + (seq * 0.11)) * (jitterMs * 0.5);
+    const oneWayMs = (baseRttMs * 0.5) + harmonic + microJitter;
+    return clamp(Math.round(oneWayMs), minOneWayMs, 200);
+  }
+
+  function sampleSnapshot(elapsedSeconds, sequence = 0) {
+    const oneWayMs = sampleOneWayDelayMs(elapsedSeconds, sequence);
+    const estimatedRttMs = clamp(Math.round(oneWayMs * 2), 0, 400);
+    const estimatedJitterMs = clamp(Math.round(Math.abs(oneWayMs - (baseRttMs * 0.5))), 0, 120);
+    return {
+      oneWayMs,
+      rttMs: estimatedRttMs,
+      jitterMs: estimatedJitterMs
+    };
+  }
+
+  return {
+    sampleOneWayDelayMs,
+    sampleSnapshot
+  };
+}