PR_06_07_SAMPLE_LAUNCHER_FILTER_RESTORE & PR_07_04_NETWORK_RECONCILIATION

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,21 +1,21 @@
 MODEL: GPT-5.4
-REASONING: medium
+REASONING: high
 
 COMMAND:
-Implement PR_07_03_NETWORK_LATENCY_MODELING.
+Implement PR_07_04_NETWORK_RECONCILIATION.
 
 Goal:
-Add latency modeling to simulation.
+Add reconciliation to simulation.
 
 Steps:
-1. Define latency model (delay/jitter).
-2. Inject into simulation inputs.
-3. Validate behavior.
+1. Define authoritative vs local state.
+2. Detect divergence.
+3. Apply correction.
 
 Rules:
-- no networking
-- no reconciliation
-- no behavior changes outside latency simulation
+- no real networking
+- no prediction yet
+- no behavior changes outside simulation layer
 
 Return ZIP:
-<project folder>/tmp/PR_07_03_NETWORK_LATENCY_MODELING.zip
+<project folder>/tmp/PR_07_04_NETWORK_RECONCILIATION.zip

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-PR_07_03_NETWORK_LATENCY_MODELING
+PR_07_04_NETWORK_RECONCILIATION

docs/dev/reports/change_summary.txt

@@ -1 +1 @@
-Samples dependency cleanup package focused on removing non-public engine coupling and standardizing samples onto approved public/shared surfaces.
+Restore sample launcher phase dropdown and tag filter behavior with a surgical launcher-only fix.

docs/dev/reports/launcher_filter_fix_map.txt

@@ -0,0 +1,27 @@
+PR_06_07_SAMPLE_LAUNCHER_FILTER_RESTORE - fix map
+
+File: samples/index.html
+
+Targeted fixes:
+1) Added parseSampleLink(href)
+- New parser accepts canonical phase path variants via:
+  /(?:^|\/)phase-?(\d{2})\/(\d{4})\/index\.html$/i
+- Standardizes extraction for phase and sampleId used by phase dropdown + filtering.
+
+2) Added parseTagTokens(model)
+- Preserves data-tags behavior.
+- Adds data-primary as fallback/augmenting tag (deduplicated), restoring expected tag discoverability/filter interaction.
+
+3) Updated link model construction
+- Replaced inline strict href regex logic with parseSampleLink.
+- Replaced inline data-tags parsing with parseTagTokens.
+
+4) Removed duplicate resolveThumbnail declaration
+- Kept single canonical helper definition in launcher script to reduce regression risk.
+
+Validation evidence:
+- Live sample links parsed: 197/197
+- Unique parsed phases: 15 (01..15)
+- Unparsed live links: 0
+- Unique filter tags generated (tags + primary fallback): 351
+- Runtime smoke: node tests/runtime/LaunchSmokeAllEntries.test.mjs passed

docs/dev/reports/launcher_filter_regression_scan.txt

@@ -0,0 +1,22 @@
+PR_06_07_SAMPLE_LAUNCHER_FILTER_RESTORE - regression scan
+
+Scope:
+- samples/index.html launcher filter script/UI only
+
+Regression cause identified:
+1) Sample href parsing was too strict.
+- Previous parser accepted only: ./phase-XX/####/index.html
+- If launcher links are emitted in equivalent canonical variants (for example /samples/phase-XX/####/index.html or phaseXX), phase/sample IDs fail to parse.
+- Failed parse results in blank model.phase and model.sampleId, which prevents correct phase dropdown population and weakens filter matching.
+
+2) Tag extraction ignored primary concept fallback.
+- Tags were sourced only from data-tags.
+- When data-tags are incomplete but data-primary is present, expected tag filter discoverability is reduced.
+
+3) Duplicate helper declaration in filter script.
+- resolveThumbnail was declared twice.
+- Runtime behavior was not always broken, but duplicate declarations increase maintenance risk and regression susceptibility.
+
+Observed impact pattern:
+- phase dropdown can appear incomplete/empty under path variant drift.
+- tag filter discoverability can regress for entries relying on primary concept.

docs/dev/reports/validation_checklist.txt

@@ -1,3 +1,4 @@
-[ ] latency model defined
-[ ] latency injection applied
+[ ] reconciliation model defined
+[ ] divergence detection working
+[ ] correction applied
 [ ] validation complete

docs/pr/PR_06_07_SAMPLE_LAUNCHER_FILTER_RESTORE.md

@@ -0,0 +1,39 @@
+# PR_06_07_SAMPLE_LAUNCHER_FILTER_RESTORE
+
+## Purpose
+Restore the sample launcher phase dropdown and tag filter behavior without changing sample content or runtime behavior.
+
+## Scope
+- samples/index.html and only the direct assets/scripts/styles it depends on for launcher filter UI behavior
+- no sample runtime changes
+- no network simulation changes
+- no launcher content restructuring beyond what is required to restore filters
+
+## Required Work
+1. Identify why the phase dropdown no longer renders/behaves correctly.
+2. Identify why sample tags are no longer rendering/behaving correctly.
+3. Restore phase dropdown population/interaction.
+4. Restore tag rendering/filter interaction.
+5. Preserve existing sample entries, phase ordering, and link targets.
+6. Keep the fix surgical and execution-backed.
+
+## Constraints
+- no broad launcher redesign
+- no sample data model redesign
+- no behavior changes outside launcher filter restoration
+- no changes to phase/sample content except what is required to restore filters
+
+## Deliverables
+- docs/dev/reports/launcher_filter_regression_scan.txt
+- docs/dev/reports/launcher_filter_fix_map.txt
+- docs/dev/reports/validation_checklist.txt
+
+## Validation
+- phase dropdown renders and filters correctly
+- tags render and filter correctly
+- sample links remain intact
+- no broken phase/sample navigation
+- impacted smoke/manual validation passes
+
+## Output
+<project folder>/tmp/PR_06_07_SAMPLE_LAUNCHER_FILTER_RESTORE.zip

docs/pr/PR_07_04_NETWORK_RECONCILIATION.md

@@ -0,0 +1,27 @@
+# PR_07_04_NETWORK_RECONCILIATION
+
+## Purpose
+Introduce reconciliation model for Phase 13 simulation.
+
+## Scope
+- reconciliation logic only
+- no real networking
+- no prediction yet
+- no behavior changes outside simulation layer
+
+## Tasks
+1. Define reconciliation model (authoritative vs local state).
+2. Apply correction when divergence detected.
+3. Maintain deterministic baseline compatibility.
+
+## Deliverables
+- docs/dev/reports/reconciliation_model.txt
+- docs/dev/reports/validation_checklist.txt
+
+## Validation
+- divergence corrected deterministically
+- latency model still respected
+- no regressions
+
+## Output
+<project folder>/tmp/PR_07_04_NETWORK_RECONCILIATION.zip

samples/index.html

@@ -544,13 +544,10 @@ <h2>Phase 16 - 3D Games</h2>
       const linkModels = linkNodes.map((link) => {
         const labelText = String(link.textContent || '').trim();
         const href = String(link.getAttribute('href') || '');
-        const match = href.match(/^\\.\\/phase-(\\d{2})\\/(\\d{4})\\/index\\.html$/);
-        const phase = match ? match[1] : '';
-        const sampleId = match ? match[2] : '';
-        const tags = String(link.getAttribute('data-tags') || '')
-          .split(',')
-          .map((tag) => tag.trim().toLowerCase())
-          .filter(Boolean);
+        const parsed = parseSampleLink(href);
+        const phase = parsed.phase;
+        const sampleId = parsed.sampleId;
+        const tags = parseTagTokens({ link });
         const titleText = labelText.toLowerCase();
         const descriptionText = String(link.getAttribute('title') || '').trim().toLowerCase();
         const searchText = [sampleId, titleText, descriptionText, tags.join(' ')].join(' ');
@@ -639,6 +636,32 @@ <h2>Phase 16 - 3D Games</h2>
         return typeof value === 'string' ? value.trim() : '';
       }
 
+      function parseSampleLink(hrefValue) {
+        const href = String(hrefValue || '').trim();
+        const match = href.match(/(?:^|\/)phase-?(\d{2})\/(\d{4})\/index\.html$/i);
+        if (!match) {
+          return { phase: '', sampleId: '' };
+        }
+        return {
+          phase: String(match[1] || ''),
+          sampleId: String(match[2] || '')
+        };
+      }
+
+      function parseTagTokens(model) {
+        const tags = String(model.link.getAttribute('data-tags') || '')
+          .split(',')
+          .map((tag) => tag.trim().toLowerCase())
+          .filter(Boolean);
+        const primary = String(model.link.getAttribute('data-primary') || '')
+          .trim()
+          .toLowerCase();
+        if (primary && !tags.includes(primary)) {
+          tags.push(primary);
+        }
+        return tags;
+      }
+
       function ensureHoverCard() {
         if (hoverCard) {
           return hoverCard;
@@ -661,10 +684,6 @@ <h2>Phase 16 - 3D Games</h2>
         return hoverCard;
       }
 
-      function resolveThumbnail(model) {
-        return model.thumbnail || model.preview || FALLBACK_THUMBNAIL;
-      }
-
       function resolvePreview(model) {
         return model.preview || model.thumbnail || FALLBACK_PREVIEW;
       }

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

@@ -41,6 +41,10 @@ export default class FakeLoopbackNetworkModel {
     this.jitterMs = 3;
     this.replicationBacklog = 0;
     this.replicationTick = 0;
+    this.authoritativeFrame = 0;
+    this.localFrame = 0;
+    this.lastReconcileAtMs = null;
+    this.reconciliationCount = 0;
 
     this.autoPacketTimerSeconds = 0;
     this.autoPacketIntervalSeconds = 0.65;
@@ -205,6 +209,39 @@ export default class FakeLoopbackNetworkModel {
     this.replicationBacklog = Math.max(0, this.inFlightPackets.length);
   }
 
+  updateDivergenceState() {
+    this.authoritativeFrame = Math.max(0, Number(this.replicationTick) || 0);
+    const ackedFloor = Math.max(0, Number(this.ackedSequence) || 0);
+    if (this.localFrame < ackedFloor) {
+      this.localFrame = ackedFloor;
+    }
+    this.localFrame = clamp(this.localFrame, 0, this.authoritativeFrame);
+  }
+
+  applyReconciliation() {
+    if (this.phase !== "connected") {
+      return;
+    }
+
+    const divergence = Math.max(0, this.authoritativeFrame - this.localFrame);
+    const stableWindow = 2;
+    if (divergence <= stableWindow) {
+      return;
+    }
+
+    const correction = Math.min(2, divergence - stableWindow);
+    this.localFrame = clamp(this.localFrame + correction, 0, this.authoritativeFrame);
+    this.reconciliationCount += 1;
+    this.lastReconcileAtMs = Math.round(this.elapsedSeconds * 1000);
+
+    this.pushTrace("RECONCILE_APPLIED", {
+      correctionFrames: correction,
+      authoritativeFrame: this.authoritativeFrame,
+      localFrame: this.localFrame,
+      divergenceAfter: Math.max(0, this.authoritativeFrame - this.localFrame)
+    });
+  }
+
   update(dtSeconds, options = {}) {
     const safeDt = asPositiveNumber(dtSeconds, 1 / 60);
     this.elapsedSeconds += safeDt;
@@ -217,11 +254,17 @@ export default class FakeLoopbackNetworkModel {
     this.updatePhaseProgress(safeDt);
     this.updateLatencySnapshot();
     this.updateAcks();
+    this.updateDivergenceState();
+    this.applyReconciliation();
   }
 
   getSnapshot() {
     const traceTail = this.traceEvents.slice(-18);
 
+    const frameDelta = Math.max(0, this.authoritativeFrame - this.localFrame);
+    const divergenceStatus = frameDelta > 8 ? "diverged" : (frameDelta > 2 ? "drifting" : "stable");
+    const divergenceScore = frameDelta > 4 ? "warning" : "ok";
+
     return {
       sessionId: this.sessionId,
       connection: {
@@ -242,13 +285,18 @@ export default class FakeLoopbackNetworkModel {
         nextSequence: this.nextSequence,
         ackedSequence: this.ackedSequence,
         pendingPackets: this.pendingPackets,
-        backlog: this.replicationBacklog
+        backlog: this.replicationBacklog,
+        authoritativeFrame: this.authoritativeFrame,
+        localFrame: this.localFrame,
+        reconciliationCount: this.reconciliationCount,
+        lastReconcileAtMs: this.lastReconcileAtMs
       },
       divergence: {
-        status: "stable",
-        score: this.replicationBacklog > 4 ? "warning" : "ok",
-        serverFrame: this.replicationTick,
-        clientFrame: Math.max(0, this.replicationTick - this.replicationBacklog)
+        status: divergenceStatus,
+        score: divergenceScore,
+        frameDelta,
+        serverFrame: this.authoritativeFrame,
+        clientFrame: this.localFrame
       },
       trace: {
         totalEvents: this.traceEvents.length,