Combine remaining network debug, promotion readiness, and server dashboard work into one low-PR pass

BUILD_PR_LEVEL_07_NETWORK_DEBUG_AND_SERVER_DASHBOARD_COMBINED_CLOSEOUT

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -2,29 +2,48 @@ MODEL: GPT-5.4
 REASONING: high
 
 COMMAND:
-Create `BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS` as one combined Section-6 PR.
+Create `BUILD_PR_LEVEL_07_NETWORK_DEBUG_AND_SERVER_DASHBOARD_COMBINED_CLOSEOUT` as one combined network-debug and server-dashboard closeout PR.
 
 Goal:
-Finish as much of the Samples Program lane as truthfully possible in one pass.
+Finish as much of the remaining network debug / readiness / dashboard lane as truthfully possible in one pass.
 
 Target items to close in this PR if supported:
-- phase grouping normalized
-- `samples/shared` boundaries defined and used
-- sample-to-engine dependency cleanup completed
-- sample curriculum progression validated
+
+Track Q:
+- Latency / RTT panel
+- Replication state viewer
+
+Track R:
+- network.help
+- network.replication
+- network.sample.*
+
+Track S:
+- Sample-backed provider validation
+- Sample-backed panel validation
+- Operator command validation
+- Debug-only gating validation
+- Promotion recommendation
+
+Track T:
+- Server dashboard shell
+- Player statistics view
+- Latency view
+- RX bytes view
+- TX bytes view
+- Connection/session counts
+- Per-player status rows
+- Refresh/update strategy
+- Debug-only access rules
 
 Required work:
-1. Treat the remaining open Section-6 items as one coherent lane.
-2. Complete phase grouping normalization where still incomplete.
-3. Define and apply `samples/shared` boundaries:
-   - what belongs in `samples/shared`
-   - what stays sample-owned
-   - what must not leak into engine/shared incorrectly
-4. Clean up sample-to-engine dependencies truthfully and surgically.
-5. Validate curriculum progression after grouping/boundary cleanup.
-6. Reuse established numbering/formatting/index work instead of redoing it.
-7. Close as many Section-6 items as truthfully possible in this one PR.
-8. If anything remains open:
+1. Treat the remaining open items as one coherent network-observability lane.
+2. Complete the remaining debug panels/commands.
+3. Bundle the readiness-to-promote validations together.
+4. Build the dashboard as one shell-plus-views slice.
+5. Reuse existing connection/divergence/trace/status/latency work instead of redoing it.
+6. Close as many remaining items as truthfully possible in this one PR.
+7. If anything remains open:
    - keep the residue very small
    - report exact blockers
    - leave it suitable for one residue-only PR
@@ -35,7 +54,7 @@ Roadmap:
 
 Final packaging step is REQUIRED:
 - package ALL changed files into this exact repo-structured ZIP:
-  `<project folder>/tmp/BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS.zip`
+  `<project folder>/tmp/BUILD_PR_LEVEL_07_NETWORK_DEBUG_AND_SERVER_DASHBOARD_COMBINED_CLOSEOUT.zip`
 
 Hard rules:
 - combine aggressively to reduce PR count

docs/dev/COMMIT_COMMENT.txt

@@ -1,2 +1,2 @@
-Combine the remaining Section-6 Samples Program work into one low-PR pass
-BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS
+Combine remaining network debug, promotion readiness, and server dashboard work into one low-PR pass
+BUILD_PR_LEVEL_07_NETWORK_DEBUG_AND_SERVER_DASHBOARD_COMBINED_CLOSEOUT

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_RESIDUE_ONLY
+BUILD_PR_LEVEL_07_NETWORK_DEBUG_AND_SERVER_DASHBOARD_RESIDUE_ONLY

docs/dev/reports/change_summary.txt

@@ -1,3 +1,3 @@
-- Added a combined PR for the remaining Section-6 Samples Program lane
-- Bundles phase grouping, samples/shared boundaries, dependency cleanup, and curriculum validation
-- Intended to finish most or all of Section 6 in one pass and leave only tiny residue if needed
+- Added a combined PR for the remaining network debug panels, commands, promotion readiness, and server dashboard lane
+- Bundles dashboard shell/views with replication/RTT/debug completion and readiness validation
+- Intended to finish most or all of the lane in one pass and leave only tiny residue if needed

docs/dev/reports/validation_checklist.txt

@@ -1,8 +1,13 @@
-- phase grouping addressed
-- samples/shared boundaries addressed
-- sample-to-engine dependency cleanup addressed
-- sample curriculum progression addressed
+- Latency / RTT panel addressed
+- Replication state viewer addressed
+- network.help addressed
+- network.replication addressed
+- network.sample.* addressed
+- sample-backed provider/panel/operator validations addressed
+- debug-only gating validation addressed
+- promotion recommendation addressed
+- server dashboard shell/views addressed
 - any residue is explicit and minimal
 - roadmap updated by status markers only
 - output ZIP created at:
-  <project folder>/tmp/BUILD_PR_LEVEL_06_SAMPLES_PROGRAM_COMBINED_PASS.zip
+  <project folder>/tmp/BUILD_PR_LEVEL_07_NETWORK_DEBUG_AND_SERVER_DASHBOARD_COMBINED_CLOSEOUT.zip

docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md

@@ -274,8 +274,8 @@
 
 ### Track G - Network / Multiplayer Debug
 - [x] Connection status panel
-- [.] Latency / RTT panel
-- [ ] Replication state viewer
+- [x] Latency / RTT panel
+- [x] Replication state viewer
 - [x] Client/server divergence inspector
 - [.] Event tracing
 - [.] PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT
@@ -364,37 +364,37 @@
 
 ### Track Q - Network Debug Panels
 - [x] Connection status panel
-- [.] Latency / RTT panel
-- [ ] Replication state viewer
+- [x] Latency / RTT panel
+- [x] Replication state viewer
 - [x] Client/server divergence inspector
 - [x] Event tracing panel
 
 ### Track R - Network Debug Commands
-- [ ] network.help
+- [x] network.help
 - [x] network.status
 - [x] network.latency
-- [.] network.replication
+- [x] network.replication
 - [x] network.divergence
 - [x] network.trace
-- [.] network.sample.*
+- [x] network.sample.*
 
 ### Track S - Readiness To Promote
-- [.] Sample-backed provider validation
-- [.] Sample-backed panel validation
-- [.] Operator command validation
-- [ ] Debug-only gating validation
-- [ ] Promotion recommendation
+- [x] Sample-backed provider validation
+- [x] Sample-backed panel validation
+- [x] Operator command validation
+- [x] Debug-only gating validation
+- [x] Promotion recommendation
 
 ### Track T - Server Dashboard
-- [ ] Server dashboard shell
-- [ ] Player statistics view
-- [ ] Latency view
-- [ ] RX bytes view
-- [ ] TX bytes view
-- [ ] Connection/session counts
-- [ ] Per-player status rows
-- [ ] Refresh/update strategy
-- [ ] Debug-only access rules
+- [x] Server dashboard shell
+- [x] Player statistics view
+- [x] Latency view
+- [x] RX bytes view
+- [x] TX bytes view
+- [x] Connection/session counts
+- [x] Per-player status rows
+- [x] Refresh/update strategy
+- [x] Debug-only access rules
 
 ### Track U - Server Containerization
 - [x] Dockerfile for server
@@ -413,9 +413,9 @@
 - [x] Sample B
 - [x] Replication + authority + divergence
 - [x] Sample C
-- [ ] Server dashboard
+- [x] Server dashboard
 - [x] Server containerization
-- [ ] Promotion review
+- [x] Promotion review
 
 ---
 

docs/pr/BUILD_PR_LEVEL_07_NETWORK_DEBUG_AND_SERVER_DASHBOARD_COMBINED_CLOSEOUT.md

@@ -0,0 +1,56 @@
+# BUILD_PR_LEVEL_07_NETWORK_DEBUG_AND_SERVER_DASHBOARD_COMBINED_CLOSEOUT
+
+## Purpose
+Close the remaining network-observability lane in one coherent pass across debug panels, operator commands, promotion-readiness validation, and server dashboard behavior.
+
+## Scope Implemented
+- added reusable latency/RTT and replication-state panel factories under `src/engine/debug/network/panels`
+- expanded network command bridge with reusable `network.replication` and `network.sample.*` command builders
+- hardened dashboard host with explicit debug-only access gating
+- surfaced debug access state in dashboard command/status output
+- added shared promotion recommendation helper for readiness decisions
+- added one focused closeout test that validates Tracks Q/R/S/T together
+- updated roadmap status markers only
+
+## Track Closure Mapping
+
+### Track Q
+- Latency / RTT panel: closed via `createLatencyRttPanel`
+- Replication state viewer: closed via `createReplicationStatePanel`
+
+### Track R
+- `network.help`: closed via default help command coverage
+- `network.replication`: closed via `createNetworkReplicationCommand`
+- `network.sample.*`: closed via `createNetworkSampleCommand`
+
+### Track S
+- Sample-backed provider validation: covered in closeout test
+- Sample-backed panel validation: covered in closeout test
+- Operator command validation: covered in closeout test
+- Debug-only gating validation: covered in closeout test with denied dashboard host
+- Promotion recommendation: closed via `createNetworkPromotionRecommendation`
+
+### Track T
+- Server dashboard shell + views + counts + per-player rows + refresh strategy were already present and are now validated in one closeout test
+- Debug-only access rules closed by dashboard host gating and validation
+
+## Residue
+- no additional functional residue identified in the target Track Q/R/S/T lane
+
+## Validation Performed
+- `node --check` on all touched source/test files
+- focused run:
+  - `tests/final/MultiplayerNetworkingStack.test.mjs`
+  - `tests/final/NetworkDebugAndServerDashboardCloseout.test.mjs`
+
+## Changed Files
+- `src/engine/debug/network/panels/networkObservabilityPanels.js`
+- `src/engine/debug/network/commands/networkDebugCommandPackBridge.js`
+- `src/engine/debug/network/dashboard/serverDashboardHost.js`
+- `src/engine/debug/network/dashboard/registerDashboardCommands.js`
+- `src/engine/debug/network/diagnostics/networkPromotionRecommendation.js`
+- `src/engine/debug/network/shared/hostReadUtils.js`
+- `src/engine/debug/network/index.js`
+- `tests/final/NetworkDebugAndServerDashboardCloseout.test.mjs`
+- `tests/run-tests.mjs`
+- `docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`

src/engine/debug/network/commands/networkDebugCommandPackBridge.js

@@ -6,6 +6,7 @@ networkDebugCommandPackBridge.js
 */
 
 import { asArray, asObject, sanitizeText } from "../shared/networkDebugUtils.js";
+import { createReplicationDiagnosticsModel } from "../diagnostics/replicationDiagnosticsModel.js";
 
 function normalizeCommandDescriptor(descriptor) {
   const source = asObject(descriptor);
@@ -32,6 +33,11 @@ function normalizeCommandDescriptor(descriptor) {
 export function createNetworkHelpCommand(options = {}) {
   const source = asObject(options);
   const lines = asArray(source.lines).map((line) => String(line));
+  const fallbackLines = [
+    "network.help",
+    "network.replication",
+    "network.sample.status"
+  ];
 
   return {
     name: sanitizeText(source.name) || "network.help",
@@ -41,13 +47,90 @@ export function createNetworkHelpCommand(options = {}) {
       return {
         status: "ready",
         title: sanitizeText(source.title) || "Network Help",
-        lines,
+        lines: lines.length > 0 ? lines : fallbackLines,
         code: sanitizeText(source.code) || "NETWORK_HELP"
       };
     }
   };
 }
 
+function readNetworkSnapshot(context = {}, sampleKey = "network") {
+  const source = asObject(context);
+  const assets = asObject(source.assets);
+  return asObject(assets[sampleKey]);
+}
+
+function createReplicationLines(context = {}, sampleKey = "network") {
+  const model = createReplicationDiagnosticsModel(readNetworkSnapshot(context, sampleKey));
+  const lines = [
+    `hostTick=${model.hostTick}`,
+    `highestBacklog=${model.highestBacklog}`,
+    `divergenceWarnings=${model.divergenceWarnings}`,
+    `hasPressure=${model.hasPressure}`
+  ];
+
+  model.clients.slice(0, 8).forEach((client) => {
+    const row = asObject(client);
+    lines.push(
+      `${String(row.peerId || "client")} tick=${Number(row.tick) || 0} pending=${Number(row.pendingPackets) || 0} backlog=${Number(row.backlog) || 0} delta=${Number(row.tickDeltaFromHost) || 0}`
+    );
+  });
+  return lines;
+}
+
+export function createNetworkReplicationCommand(options = {}) {
+  const source = asObject(options);
+  const sampleKey = sanitizeText(source.sampleKey) || "network";
+  const linesFactory = typeof source.createLines === "function"
+    ? source.createLines
+    : (context) => createReplicationLines(context, sampleKey);
+
+  return {
+    name: sanitizeText(source.name) || "network.replication",
+    summary: sanitizeText(source.summary) || "Show replication state and backlog diagnostics.",
+    usage: sanitizeText(source.usage) || "network.replication",
+    handler(context = {}) {
+      return {
+        status: "ready",
+        title: sanitizeText(source.title) || "Network Replication",
+        lines: asArray(linesFactory(context)).map((line) => String(line)),
+        code: sanitizeText(source.code) || "NETWORK_REPLICATION"
+      };
+    }
+  };
+}
+
+export function createNetworkSampleCommand(options = {}) {
+  const source = asObject(options);
+  const sampleCommandId = sanitizeText(source.sampleCommandId) || "status";
+  const commandName = sanitizeText(source.name) || `network.sample.${sampleCommandId}`;
+  const sampleKey = sanitizeText(source.sampleKey) || "network";
+  const linesFactory = typeof source.createLines === "function"
+    ? source.createLines
+    : (context = {}) => {
+      const snapshot = readNetworkSnapshot(context, sampleKey);
+      const keys = Object.keys(snapshot);
+      return [
+        `sampleKey=${sampleKey}`,
+        `fields=${keys.length > 0 ? keys.join(",") : "none"}`
+      ];
+    };
+
+  return {
+    name: commandName,
+    summary: sanitizeText(source.summary) || "Show sample-specific network diagnostics.",
+    usage: sanitizeText(source.usage) || commandName,
+    handler(context = {}, args = []) {
+      return {
+        status: "ready",
+        title: sanitizeText(source.title) || "Network Sample Diagnostics",
+        lines: asArray(linesFactory(context, asArray(args))).map((line) => String(line)),
+        code: sanitizeText(source.code) || "NETWORK_SAMPLE"
+      };
+    }
+  };
+}
+
 export function createNetworkCommandPack(options = {}) {
   const source = asObject(options);
   const commands = asArray(source.commands)

src/engine/debug/network/dashboard/registerDashboardCommands.js

@@ -26,6 +26,8 @@ function formatStatusLines(status) {
   return [
     `running=${Boolean(status.running)}`,
     `mode=${sanitizeText(status.mode) || "normal"}`,
+    `debugOnly=${status.debugOnly !== false}`,
+    `debugAccessEnabled=${status.debugAccessEnabled !== false}`,
     `refreshIntervalMs=${Number(status.refreshIntervalMs) || 0}`,
     `refreshCount=${Number(status.refreshCount) || 0}`,
     `lastRefreshTimestampMs=${Number(status.lastRefreshTimestampMs) || 0}`,