Skip to content

Commit dc3a7b1

Browse files
author
DavidQ
committed
docs: plan network debug promotion into reusable engine-debug layer
1 parent 47e093d commit dc3a7b1

10 files changed

Lines changed: 282 additions & 64 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 10 additions & 19 deletions
Original file line numberDiff line numberDiff line change
@@ -2,27 +2,18 @@ MODEL: GPT-5.4-codex
22
REASONING: high
33

44
COMMAND:
5-
Create BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_ENHANCEMENTS
5+
Create PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION
66

77
Requirements:
8-
- Follow PLAN_PR + BUILD_PR + APPLY_PR discipline
9-
- Build the zip automatically
8+
- Follow PLAN_PR + BUILD_PR + APPLY_PR
109
- Docs-first
11-
- No engine core changes
1210
- One PR per purpose
13-
- Keep implementation under tools/dev/server-dashboard
14-
- Keep integration sample-level
15-
- Extend the server dashboard foundation with:
16-
- player statistics view
17-
- latency view
18-
- rx bytes view
19-
- tx bytes view
20-
- connection/session counts
21-
- per-player status rows
22-
- refresh/update strategy
23-
- debug-only access rules
24-
- Keep all data flow read-only
25-
- Do not couple dashboard to console or overlay
11+
- No engine core changes in this PLAN PR
12+
- Define promotion path for proven network debug capabilities
13+
- Prefer reusable ownership under engine/debug/network
14+
- Keep engine core limited to minimal contracts/hooks only
15+
- Keep sample-specific scenarios, feeds, and local adapters project-owned
16+
- Include target structure, ownership matrix, migration phases, validation strategy, risk controls, and rollout notes
17+
- Update roadmap references under docs/roadmaps/ with bracket-only edits only if needed
2618
- Write outputs under docs/pr and docs/dev/reports
27-
- Put roadmap files under docs/roadmaps
28-
- Package to <project folder>/tmp/BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_ENHANCEMENTS_delta.zip
19+
- Package to <project folder>/tmp/PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION_delta.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
Build BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_ENHANCEMENTS docs-first bundle to extend server-dashboard read-only contracts (player stats, latency, RX/TX, session counts, per-player rows, refresh strategy, debug-only access) under tools/dev/server-dashboard with sample-level integration only.
1+
docs: plan network debug promotion into reusable engine-debug layer

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
APPLY_PR_DEBUG_SURFACES_SERVER_DASHBOARD_ENHANCEMENTS
1+
BUILD_PR_DEBUG_SURFACES_NETWORK_PROMOTION

‎docs/dev/reports/change_summary.txt‎

Lines changed: 16 additions & 21 deletions
Original file line numberDiff line numberDiff line change
@@ -1,24 +1,19 @@
1-
BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_ENHANCEMENTS
1+
PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION
22

33
Summary:
4-
- Finalized PLAN/BUILD/APPLY docs for the server dashboard enhancement slice.
5-
- Extended the BUILD contract to include:
6-
- player statistics view
7-
- latency view
8-
- RX bytes view
9-
- TX bytes view
10-
- connection/session counts
11-
- per-player status rows
12-
- refresh/update strategy
13-
- debug-only access rules
14-
- Reinforced read-only data-flow guardrails and no-coupling rules for console/overlay.
15-
- Extended `tools/dev/server-dashboard/README.md` with enhancement-slice documentation.
16-
- Updated `docs/roadmaps/NETWORK_SAMPLES_PLAN.md` Track T with bracket-state-only progress changes.
17-
- Refreshed report artifacts and packaged a repo-structured ZIP.
4+
- Rebuilt the PLAN PR document as a docs-first network promotion plan with explicit:
5+
- target structure
6+
- ownership matrix
7+
- migration phases
8+
- validation strategy
9+
- risk controls
10+
- rollout notes
11+
- Preserved one-PR-purpose scope and no engine-core implementation changes.
12+
- Kept reusable ownership centered on `engine/debug/network` and restricted core to minimal contracts/hooks.
13+
- Kept sample-specific scenarios, synthetic feeds, and local adapters project-owned by design.
14+
- Updated roadmap reference in `docs/roadmaps/NETWORK_SAMPLES_PLAN.md` using bracket-only status change for promotion recommendation.
1815

19-
Guardrails respected:
20-
- docs-first bundle
21-
- no engine core changes
22-
- one PR purpose only
23-
- sample-level integration only
24-
- dashboard flow remains read-only
16+
Scope controls:
17+
- docs-first only
18+
- read-only debug data-flow expectations preserved
19+
- no dashboard coupling to console/overlay internals

‎docs/dev/reports/file_tree.txt‎

Lines changed: 3 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,18 +1,13 @@
11
HTML-JavaScript-Gaming/
22
docs/
33
pr/
4-
PLAN_PR_DEBUG_SURFACES_SERVER_DASHBOARD_ENHANCEMENTS.md
5-
BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_ENHANCEMENTS.md
6-
APPLY_PR_DEBUG_SURFACES_SERVER_DASHBOARD_ENHANCEMENTS.md
4+
PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md
5+
BUILD_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md
6+
APPLY_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md
77
dev/
8-
commit_comment.txt
98
reports/
109
file_tree.txt
1110
change_summary.txt
1211
validation_checklist.txt
1312
roadmaps/
1413
NETWORK_SAMPLES_PLAN.md
15-
tools/
16-
dev/
17-
server-dashboard/
18-
README.md

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 17 additions & 13 deletions
Original file line numberDiff line numberDiff line change
@@ -1,14 +1,18 @@
1-
BUILD_PR_DEBUG_SURFACES_SERVER_DASHBOARD_ENHANCEMENTS validation checklist
1+
PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION validation checklist
22

3-
[x] PLAN/BUILD/APPLY discipline is preserved
4-
[x] BUILD bundle is docs-first
5-
[x] Enhancement inventory includes all requested views and rules
6-
[x] Data flow is explicitly read-only
7-
[x] Dashboard remains decoupled from console internals
8-
[x] Dashboard remains decoupled from overlay internals
9-
[x] No engine core changes included
10-
[x] Integration scope remains sample-level
11-
[x] Roadmap update is under docs/roadmaps
12-
[x] Roadmap changes are bracket-state-only for Track T items
13-
[x] Outputs written under docs/pr and docs/dev/reports
14-
[x] Delta zip generated under tmp/
3+
[x] PLAN/BUILD/APPLY discipline is explicitly stated
4+
[x] PLAN PR is docs-first and one-purpose
5+
[x] No engine core implementation changes are introduced
6+
[x] Promotion path for proven network debug capabilities is defined
7+
[x] Reusable ownership preference under `engine/debug/network` is documented
8+
[x] Engine core remains limited to minimal contracts/hooks in plan boundaries
9+
[x] Sample-specific scenarios/feeds/adapters remain project-owned
10+
[x] Target structure is documented
11+
[x] Ownership matrix is documented
12+
[x] Migration phases are documented
13+
[x] Validation strategy is documented
14+
[x] Risk controls are documented
15+
[x] Rollout notes are documented
16+
[x] Roadmap reference update (if needed) used bracket-only edit
17+
[x] Reports are written under `docs/dev/reports`
18+
[x] ZIP target path defined at `<project folder>/tmp/PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION_delta.zip`

‎docs/pr/APPLY_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
# APPLY_PR_DEBUG_SURFACES_NETWORK_PROMOTION
2+
3+
## Purpose
4+
Apply the approved extraction and promotion of shared network debug capabilities into a reusable engine-debug network layer while preserving current behavior.
5+
6+
## Execution Rules
7+
- Behavior parity first.
8+
- Extraction/relocation only unless explicitly required for wiring.
9+
- No unrelated refactors.
10+
- No engine core UI logic.
11+
- Keep sample-owned scenarios local.
12+
13+
## Apply Steps
14+
1. Create minimal engine-core contract files.
15+
2. Create `engine/debug/network` structure.
16+
3. Move shared providers into `engine/debug/network/providers`.
17+
4. Move shared panels/renderers into `engine/debug/network/panels`.
18+
5. Move shared commands into `engine/debug/network/commands`.
19+
6. Move dashboard foundation/enhancement pieces into `engine/debug/network/dashboard`.
20+
7. Add bootstrap/composition wiring.
21+
8. Reconnect sample integrations through public registration.
22+
9. Validate end-to-end.
23+
24+
## Required Validation
25+
- Existing network smoke checks still pass.
26+
- Server dashboard sections still render/update.
27+
- Unknown group/macro/network identifiers still fail safely.
28+
- No runtime mutations introduced.
29+
- No console/overlay regressions.
30+
31+
## Roadmap Notes
32+
Update roadmap trackers with bracket-only edits only after validation confirms promotion readiness milestones.

‎docs/pr/BUILD_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md‎

Lines changed: 65 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,65 @@
1+
# BUILD_PR_DEBUG_SURFACES_NETWORK_PROMOTION
2+
3+
## Purpose
4+
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.
5+
6+
## Authoritative Target Structure
7+
```text
8+
src/engine/debug/network/
9+
providers/
10+
panels/
11+
commands/
12+
dashboard/
13+
diagnostics/
14+
bootstrap/
15+
```
16+
17+
## Minimal Core Contract Area
18+
```text
19+
src/engine/core/debug/
20+
NetworkDebugContracts.js
21+
NetworkDebugRegistrationHooks.js
22+
NetworkDebugGate.js
23+
```
24+
25+
## Ownership Matrix
26+
| Component | Destination |
27+
|---|---|
28+
| Shared network providers | engine/debug/network |
29+
| Shared network panels | engine/debug/network |
30+
| Shared network commands | engine/debug/network |
31+
| Server dashboard host/registry/renderer | engine/debug/network/dashboard |
32+
| Divergence/trace presentation helpers | engine/debug/network/diagnostics |
33+
| Synthetic sample feeds | project/sample-owned |
34+
| Scenario wiring | project/sample-owned |
35+
| Reproduction docs | docs/pr + docs/roadmaps |
36+
| Minimal registration/gating hooks | engine/core/debug |
37+
38+
## Migration Order
39+
1. Define minimal core contracts only.
40+
2. Extract shared providers.
41+
3. Extract shared panels/renderers.
42+
4. Extract shared commands.
43+
5. Extract dashboard foundation/enhancements.
44+
6. Add bootstrap/composition layer.
45+
7. Reconnect sample integrations through public registration.
46+
8. Run full validation across samples/dashboard.
47+
48+
## Guardrails
49+
- No redesign during extraction.
50+
- No runtime feature expansion.
51+
- No server product UI work.
52+
- No console-overlay-dashboard coupling.
53+
- No sample-specific scenario logic in shared layers.
54+
55+
## Validation Checklist
56+
- Sample A passes.
57+
- Sample B passes.
58+
- Sample C passes.
59+
- Dashboard renders and refreshes.
60+
- Latency/trace/divergence outputs remain correct.
61+
- Public command paths remain intact.
62+
- Debug-only gating remains intact.
63+
64+
## Rollback Rule
65+
If parity is broken, revert to sample-owned wiring and keep docs/history intact.

‎docs/pr/PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md‎

Lines changed: 136 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,136 @@
1+
Toolbox Aid
2+
David Quesenberry
3+
04/06/2026
4+
PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION.md
5+
6+
# PLAN_PR_DEBUG_SURFACES_NETWORK_PROMOTION
7+
8+
## Purpose
9+
Define a docs-first promotion path for proven network debug capabilities into reusable ownership, while keeping engine core limited to minimal contracts/hooks and preserving sample-owned scenario logic.
10+
11+
## Workflow Discipline
12+
PLAN_PR -> BUILD_PR -> APPLY_PR
13+
14+
## PR Scope
15+
This PLAN PR is documentation only. It does not move implementation code.
16+
17+
## Goals
18+
- promote reusable network debug capability into shared ownership under `engine/debug/network`
19+
- keep engine core contract-only for minimal debug hooks/interfaces
20+
- keep sample-specific scenarios, feeds, and local adapters project-owned
21+
- preserve read-only data flow and debug-only access behavior
22+
- preserve console/overlay decoupling from dashboard internals
23+
24+
## Non-Goals
25+
- no engine core implementation changes
26+
- no runtime transport/protocol changes
27+
- no dashboard feature expansion beyond proven debug scope
28+
- no sample scenario promotion into shared layer
29+
- no containerization/deployment changes
30+
31+
## Target Structure (Promotion Direction)
32+
```text
33+
engine/
34+
core/
35+
debug/
36+
NetworkDebugContracts.js
37+
NetworkDebugRegistrationHooks.js
38+
NetworkDebugGateHooks.js
39+
debug/
40+
network/
41+
bootstrap/
42+
createNetworkDebugSurfaceIntegration.js
43+
providers/
44+
networkDebugProviderRegistry.js
45+
networkDebugSnapshotNormalizer.js
46+
panels/
47+
networkDebugPanelRegistry.js
48+
networkDebugPanelRenderer.js
49+
commands/
50+
networkDebugCommandPackBridge.js
51+
dashboard/
52+
serverDashboardHost.js
53+
serverDashboardRegistry.js
54+
serverDashboardProviders.js
55+
serverDashboardRenderer.js
56+
diagnostics/
57+
divergenceDiagnosticsModel.js
58+
latencyDiagnosticsModel.js
59+
replicationDiagnosticsModel.js
60+
61+
tools/
62+
dev/
63+
server-dashboard/
64+
(project-owned docs/integration notes and optional local adapters)
65+
66+
games/
67+
network_sample_*/
68+
(sample-specific scenarios, synthetic feeds, local adapters remain here)
69+
```
70+
71+
## Ownership Matrix
72+
| Area | Owner | Scope |
73+
|---|---|---|
74+
| Minimal contracts/hooks | `engine/core/debug` | registration hooks, environment gating, narrow interfaces only |
75+
| Reusable network debug implementation | `engine/debug/network` | shared providers/panels/commands/dashboard foundation/diagnostics helpers |
76+
| Sample scenarios and synthetic feeds | project/sample folders | Sample A/B/C deterministic scenarios and local adapters |
77+
| Tool-local helper glue | `tools/dev` + project | temporary adapters, local stubs, project-specific sections |
78+
| Engine core UI behavior | not allowed | core must not own console/overlay/dashboard rendering policy |
79+
80+
## Migration Phases
81+
1. Proven Capability Inventory
82+
Identify stable network debug pieces already validated in sample flow (panels, providers, commands, dashboard foundation).
83+
84+
2. Shared-vs-Local Split
85+
Tag each artifact as shared (`engine/debug/network`) or local (sample/project/tool) with explicit non-promotion exclusions.
86+
87+
3. Contract Freeze
88+
Define minimal core hook contracts required for shared registration/gating. Keep contracts narrow and implementation-free.
89+
90+
4. Shared Layer Assembly
91+
Define extraction map into `engine/debug/network` for providers, panels, command bridge, dashboard foundation, and diagnostics helpers.
92+
93+
5. Sample Rebind Strategy
94+
Define sample-level adapter rewiring to consume shared components while retaining local scenarios/feeds.
95+
96+
6. Promotion Readiness Review
97+
Run validation matrix and risk controls before BUILD/APPLY execution.
98+
99+
## Validation Strategy
100+
### Functional Parity
101+
- Sample A/B/C panels/providers/commands remain behavior-compatible after promotion path definition.
102+
103+
### Boundary Validation
104+
- shared layer consumes public selectors/events only
105+
- no private runtime mutation hooks introduced
106+
- dashboard remains independent from console/overlay internals
107+
108+
### Data Flow Validation
109+
- provider-to-renderer path remains read-only
110+
- dashboard/diagnostics views remain observational only
111+
112+
### Gating Validation
113+
- debug-only access contracts remain explicit
114+
- combo key behavior is unaffected by network promotion design
115+
116+
## Risk Controls
117+
### Risk: over-promoting sample-specific logic
118+
Control: require explicit ownership matrix tagging with non-promote list.
119+
120+
### Risk: core-layer scope creep
121+
Control: permit only minimal contract/hook surface in `engine/core/debug`.
122+
123+
### Risk: coupling dashboard with console/overlay internals
124+
Control: keep dashboard host/registry/providers/renderer isolated in `engine/debug/network/dashboard`.
125+
126+
### Risk: migration regressions across samples
127+
Control: phase-gated validation matrix with sample parity checks before APPLY.
128+
129+
## Rollout Notes
130+
- execute promotion incrementally by subsystem (providers -> panels -> commands -> dashboard -> diagnostics)
131+
- keep one PR per purpose in BUILD/APPLY sequence
132+
- preserve rollback checkpoints by phase
133+
- treat Sample C divergence/trace as proving consumer, not shared implementation source
134+
135+
## Next Command
136+
`BUILD_PR_DEBUG_SURFACES_NETWORK_PROMOTION`

‎docs/roadmaps/NETWORK_SAMPLES_PLAN.md‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -73,7 +73,7 @@ Track the staged network sample journey for debug surface support using a strict
7373
- [.] Sample-backed panel validation
7474
- [.] Operator command validation
7575
- [ ] Debug-only gating validation
76-
- [ ] Promotion recommendation
76+
- [.] Promotion recommendation
7777

7878
---
7979

0 commit comments

Comments
 (0)