Apply network promotion build

Author: DavidQ

docs/dev/CODEX_COMMANDS.md

@@ -1,19 +1,2 @@
 MODEL: GPT-5.4-codex
-REASONING: high
-
-COMMAND:
-Create PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION
-
-Requirements:
-- Follow PLAN_PR + BUILD_PR + APPLY_PR
-- Docs-first
-- One PR per purpose
-- No engine core changes in this PLAN PR
-- Define promotion path for proven network debug capabilities
-- Prefer reusable ownership under engine/debug/network
-- Keep engine core limited to minimal contracts/hooks only
-- Keep sample-specific scenarios, feeds, and local adapters project-owned
-- Include target structure, ownership matrix, migration phases, validation strategy, risk controls, and rollout notes
-- Update roadmap references under docs/roadmaps/ with bracket-only edits only if needed
-- Write outputs under docs/pr and docs/dev/reports
-- Package to <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION_delta.zip
+COMMAND: APPLY_PR_DEBUG_SURFACES_NETWORK_PROMOTION

docs/dev/COMMIT_COMMENT.txt

@@ -1 +1 @@
-docs: plan network debug promotion into reusable engine-debug layer
+Apply network promotion build

docs/dev/NEXT_COMMAND.txt

@@ -1 +1 @@
-BUILD_PR_DEBUG_SURFACES_NETWORK_PROMOTION
+APPLY_PR_DEBUG_SURFACES_NETWORK_PROMOTION

docs/dev/reports/change_summary.txt

@@ -1,19 +1 @@
-PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION
-
-Summary:
-- Rebuilt the PLAN PR document as a docs-first network promotion plan with explicit:
-  - target structure
-  - ownership matrix
-  - migration phases
-  - validation strategy
-  - risk controls
-  - rollout notes
-- Preserved one-PR-purpose scope and no engine-core implementation changes.
-- Kept reusable ownership centered on `engine/debug/network` and restricted core to minimal contracts/hooks.
-- Kept sample-specific scenarios, synthetic feeds, and local adapters project-owned by design.
-- Updated roadmap reference in `docs/roadmaps/NETWORK_SAMPLES_PLAN.md` using bracket-only status change for promotion recommendation.
-
-Scope controls:
-- docs-first only
-- read-only debug data-flow expectations preserved
-- no dashboard coupling to console/overlay internals
+Network promotion build bundle.

docs/dev/reports/file_tree.txt

@@ -1,13 +1,2 @@
-HTML-JavaScript-Gaming/
-  docs/
-    pr/
-      PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md
-      BUILD_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md
-      APPLY_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md
-    dev/
-      reports/
-        file_tree.txt
-        change_summary.txt
-        validation_checklist.txt
-    roadmaps/
-      NETWORK_SAMPLES_PLAN.md
+docs/pr
+ docs/dev

docs/dev/reports/validation_checklist.txt

@@ -1,18 +1 @@
-PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION validation checklist
-
-[x] PLAN/BUILD/APPLY discipline is explicitly stated
-[x] PLAN PR is docs-first and one-purpose
-[x] No engine core implementation changes are introduced
-[x] Promotion path for proven network debug capabilities is defined
-[x] Reusable ownership preference under `engine/debug/network` is documented
-[x] Engine core remains limited to minimal contracts/hooks in plan boundaries
-[x] Sample-specific scenarios/feeds/adapters remain project-owned
-[x] Target structure is documented
-[x] Ownership matrix is documented
-[x] Migration phases are documented
-[x] Validation strategy is documented
-[x] Risk controls are documented
-[x] Rollout notes are documented
-[x] Roadmap reference update (if needed) used bracket-only edit
-[x] Reports are written under `docs/dev/reports`
-[x] ZIP target path defined at `<project folder>/tmp/PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION_delta.zip`
+Validate network promotion.

docs/pr/APPLY_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md

@@ -1,32 +1,36 @@
+Toolbox Aid
+David Quesenberry
+04/06/2026
+APPLY_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md
+
 # APPLY_PR_DEBUG_SURFACES_NETWORK_PROMOTION
 
 ## Purpose
-Apply the approved extraction and promotion of shared network debug capabilities into a reusable engine-debug network layer while preserving current behavior.
+Apply the approved network promotion by introducing shared reusable network debug modules and rebinding sample network plugins to shared bootstrap logic.
 
-## Execution Rules
-- Behavior parity first.
-- Extraction/relocation only unless explicitly required for wiring.
-- No unrelated refactors.
-- No engine core UI logic.
-- Keep sample-owned scenarios local.
+## Apply Rules
+- no engine core implementation changes
+- keep sample-specific feeds/scenarios/adapters project-owned
+- keep data flow read-only for network providers and dashboard pieces
+- keep dashboard decoupled from console/overlay internals
+- no combo-key behavior changes
 
-## Apply Steps
-1. Create minimal engine-core contract files.
-2. Create `engine/debug/network` structure.
-3. Move shared providers into `engine/debug/network/providers`.
-4. Move shared panels/renderers into `engine/debug/network/panels`.
-5. Move shared commands into `engine/debug/network/commands`.
-6. Move dashboard foundation/enhancement pieces into `engine/debug/network/dashboard`.
-7. Add bootstrap/composition wiring.
-8. Reconnect sample integrations through public registration.
-9. Validate end-to-end.
+## Ordered Apply Sequence
+1. Add `engine/debug/network` shared modules (shared/provider/panel/command/bootstrap).
+2. Add read-only dashboard and diagnostics helpers under `engine/debug/network`.
+3. Export shared network layer through `engine/debug/index.js`.
+4. Rebind Sample A/B/C debug plugin factories through shared network bootstrap.
+5. Run targeted import and smoke checks.
 
-## Required Validation
-- Existing network smoke checks still pass.
-- Server dashboard sections still render/update.
-- Unknown group/macro/network identifiers still fail safely.
-- No runtime mutations introduced.
-- No console/overlay regressions.
+## Validation
+- all added modules import successfully
+- Sample A/B/C plugins still return provider/panel/command packs
+- provider descriptors remain read-only
+- dashboard host run-once behavior succeeds with normalized snapshots
+- no changes to engine core APIs
 
-## Roadmap Notes
-Update roadmap trackers with bracket-only edits only after validation confirms promotion readiness milestones.
+## Rollback
+If promotion causes regressions:
+- revert `engine/debug/network` additions
+- restore direct plugin object construction in sample debug plugin files
+- keep sample-level behavior as pre-promotion baseline

docs/pr/BUILD_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md

@@ -1,65 +1,57 @@
+Toolbox Aid
+David Quesenberry
+04/06/2026
+BUILD_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md
+
 # BUILD_PR_DEBUG_SURFACES_NETWORK_PROMOTION
 
-## Purpose
-Translate the approved promotion plan into an executable build package describing the exact target structure, ownership map, migration order, validation checklist, and rollback rules for promoting network debug surfaces.
+## Build Summary
+Define the implementation shape for promoting reusable network debug capabilities into a shared `engine/debug/network` layer while keeping sample scenarios and adapters project-owned.
+
+## Workflow Discipline
+PLAN_PR -> BUILD_PR -> APPLY_PR
+
+## Scope
+- create reusable network debug modules under `engine/debug/network`
+- keep engine core unchanged in this slice
+- keep data flow read-only for providers/panels/dashboard
+- preserve sample-level integration for Sample A/B/C
 
-## Authoritative Target Structure
+## Target Structure
 ```text
-src/engine/debug/network/
+engine/debug/network/
+  index.js
+  shared/
+    networkDebugUtils.js
   providers/
+    networkDebugProviderRegistry.js
   panels/
+    networkDebugPanelRegistry.js
   commands/
+    networkDebugCommandPackBridge.js
+  bootstrap/
+    createNetworkDebugSurfaceIntegration.js
   dashboard/
+    serverDashboardHost.js
+    serverDashboardRegistry.js
+    serverDashboardProviders.js
+    serverDashboardRenderer.js
   diagnostics/
-  bootstrap/
+    divergenceDiagnosticsModel.js
+    latencyDiagnosticsModel.js
+    replicationDiagnosticsModel.js
 ```
 
-## Minimal Core Contract Area
-```text
-src/engine/core/debug/
-  NetworkDebugContracts.js
-  NetworkDebugRegistrationHooks.js
-  NetworkDebugGate.js
-```
-
-## Ownership Matrix
-| Component | Destination |
-|---|---|
-| Shared network providers | engine/debug/network |
-| Shared network panels | engine/debug/network |
-| Shared network commands | engine/debug/network |
-| Server dashboard host/registry/renderer | engine/debug/network/dashboard |
-| Divergence/trace presentation helpers | engine/debug/network/diagnostics |
-| Synthetic sample feeds | project/sample-owned |
-| Scenario wiring | project/sample-owned |
-| Reproduction docs | docs/pr + docs/roadmaps |
-| Minimal registration/gating hooks | engine/core/debug |
-
-## Migration Order
-1. Define minimal core contracts only.
-2. Extract shared providers.
-3. Extract shared panels/renderers.
-4. Extract shared commands.
-5. Extract dashboard foundation/enhancements.
-6. Add bootstrap/composition layer.
-7. Reconnect sample integrations through public registration.
-8. Run full validation across samples/dashboard.
-
-## Guardrails
-- No redesign during extraction.
-- No runtime feature expansion.
-- No server product UI work.
-- No console-overlay-dashboard coupling.
-- No sample-specific scenario logic in shared layers.
+## Ownership Model
+- shared reusable logic: `engine/debug/network`
+- sample-specific scenarios and local adapters: `games/network_sample_*`
+- engine core: no implementation changes in this promotion slice
 
-## Validation Checklist
-- Sample A passes.
-- Sample B passes.
-- Sample C passes.
-- Dashboard renders and refreshes.
-- Latency/trace/divergence outputs remain correct.
-- Public command paths remain intact.
-- Debug-only gating remains intact.
+## Validation Targets
+- network shared modules import successfully
+- Sample A/B/C debug plugins continue to expose providers/panels/commands
+- provider descriptors remain read-only
+- dashboard host/providers/renderer remain observational only
 
-## Rollback Rule
-If parity is broken, revert to sample-owned wiring and keep docs/history intact.
+## Apply Gate
+APPLY should wire sample plugin creation through shared network bootstrap and export the shared layer from `engine/debug/index.js` without changing combo-key behavior or core runtime contracts.

engine/debug/index.js

@@ -12,3 +12,4 @@ export { default as StatsTracker } from './StatsTracker.js';
 export { drawMinimap } from './Minimap.js';
 export { validateWorldEntities, drawValidationPanel } from './Validation.js';
 export * from './standard/threeD/index.js';
+export * from './network/index.js';

engine/debug/network/bootstrap/createNetworkDebugSurfaceIntegration.js

@@ -0,0 +1,75 @@
+/*
+Toolbox Aid
+David Quesenberry
+04/06/2026
+createNetworkDebugSurfaceIntegration.js
+*/
+
+import { createReadOnlyNetworkProviders } from "../providers/networkDebugProviderRegistry.js";
+import { asArray, asBoolean, asObject, sanitizeText, shallowCloneArray } from "../shared/networkDebugUtils.js";
+
+const DEFAULT_NETWORK_DEBUG_CAPABILITIES = Object.freeze([
+  Object.freeze({ capabilityId: "debug.overlay.panel", version: "1.0.0", required: true }),
+  Object.freeze({ capabilityId: "debug.command-pack", version: "1.0.0", required: true }),
+  Object.freeze({ capabilityId: "debug.diagnostics.snapshot", version: "1.0.0", required: true }),
+  Object.freeze({ capabilityId: "debug.overlay.provider", version: "1.0.0", required: true })
+]);
+
+function cloneCapabilities(capabilities) {
+  return asArray(capabilities).map((capability) => ({ ...asObject(capability) }));
+}
+
+function clonePanels(panels) {
+  return shallowCloneArray(panels);
+}
+
+function cloneCommandPacks(commandPacks) {
+  return asArray(commandPacks).map((pack) => ({
+    ...asObject(pack),
+    commands: shallowCloneArray(asObject(pack).commands)
+  }));
+}
+
+export function createNetworkDebugPluginDefinition(options = {}) {
+  const source = asObject(options);
+  const pluginId = sanitizeText(source.pluginId) || "network.debug";
+  const title = sanitizeText(source.title) || pluginId;
+  const featureFlag = sanitizeText(source.featureFlag) || "networkDebug";
+  const autoActivate = asBoolean(source.autoActivate, true);
+
+  const providerSource = typeof source.getProviders === "function"
+    ? source.getProviders()
+    : source.providers;
+  const panelSource = typeof source.getPanels === "function"
+    ? source.getPanels()
+    : source.panels;
+  const commandPackSource = typeof source.getCommandPacks === "function"
+    ? source.getCommandPacks()
+    : source.commandPacks;
+
+  const providers = createReadOnlyNetworkProviders(providerSource);
+  const panels = clonePanels(panelSource);
+  const commandPacks = cloneCommandPacks(commandPackSource);
+  const capabilities = cloneCapabilities(
+    asArray(source.capabilities).length > 0
+      ? source.capabilities
+      : DEFAULT_NETWORK_DEBUG_CAPABILITIES
+  );
+
+  return {
+    pluginId,
+    title,
+    featureFlag,
+    autoActivate,
+    capabilities,
+    getProviders() {
+      return createReadOnlyNetworkProviders(providers);
+    },
+    getPanels() {
+      return clonePanels(panels);
+    },
+    getCommandPacks() {
+      return cloneCommandPacks(commandPacks);
+    }
+  };
+}