Skip to content

Commit f3b4727

Browse files
author
DavidQ
committed
docs: bundle network support plan/build/apply for debug surfaces
1 parent 149247c commit f3b4727

11 files changed

Lines changed: 318 additions & 45 deletions

‎docs/dev/BIG_PICTURE_ROADMAP.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -69,11 +69,14 @@ Do NOT change structure or wording.
6969

7070
# 🌐 TRACK G — NETWORK / MULTIPLAYER DEBUG
7171

72-
- [ ] Connection status panel
72+
- [.] Connection status panel
7373
- [ ] Latency / RTT panel
7474
- [ ] Replication state viewer
7575
- [ ] Client/server divergence inspector
7676
- [ ] Event tracing
77+
- [x] PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT
78+
- [x] BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT
79+
- [.] APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT
7780

7881
---
7982

‎docs/dev/CODEX_COMMANDS.md‎

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

44
COMMAND:
5-
Apply APPLY_PR_DEBUG_SURFACES_3D_SUPPORT
5+
Create PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT, BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT, and APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT as a bundled docs pack
66

77
Requirements:
8-
- Execute the 3D support APPLY step only
9-
- Create summary-level shared 3D providers, shared 3D panels, and optional shared 3D presets
10-
- Keep renderer-specific adapters and scene extraction outside the shared layer
11-
- Preserve existing provider/panel/preset conventions
12-
- Do not add deep inspectors, renderer-specific implementations, or network support
13-
- Validate with a 3D sample or local adapter harness
8+
- Follow PLAN_PR -> BUILD_PR -> APPLY_PR
9+
- Docs-first only
10+
- One PR purpose per document, but package all three together
11+
- Plan/build/apply the first reusable network support layer for the debug surfaces platform
12+
- Define shared network panels, shared network providers, optional shared network presets, adapter boundaries, adoption models, naming conventions, and target structure
13+
- Keep the first version summary-level and opt-in
14+
- Exclude protocol-specific implementations, packet inspectors, auth/matchmaking tooling, and deep inspectors from this bundle
15+
- Keep transport/protocol adapters outside the shared layer
1416
- Update BIG_PICTURE_ROADMAP.md by changing bracket states only
1517
- Include ROADMAP_GUARDRAILS.md unchanged
16-
- Package to <project folder>/tmp/APPLY_PR_DEBUG_SURFACES_3D_SUPPORT_delta.zip
18+
- Package to <project folder>/tmp/DEBUG_SURFACES_NETWORK_SUPPORT_BUNDLE.zip

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
apply: shared 3D debug support layer
1+
docs: bundle network support PLAN/BUILD/APPLY contracts for debug surfaces

‎docs/dev/NETWORK_SAMPLE_ADAPTER_HARNESS.md‎

Lines changed: 16 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,16 @@
1+
# NETWORK_SAMPLE_ADAPTER_HARNESS
2+
3+
## Purpose
4+
Provide a low-risk validation path for shared network debug support without hard-coding a specific transport or protocol into the shared layer.
5+
6+
## Harness Responsibilities
7+
- expose connection summaries
8+
- expose latency/RTT summaries
9+
- expose replication summaries
10+
- expose divergence summaries
11+
- expose event stream summaries
12+
13+
## Harness Rules
14+
- adapters remain project-local
15+
- shared network panels/providers stay generic
16+
- no protocol internals in shared layer

‎docs/dev/NEXT_COMMAND.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,2 @@
11
Next:
2-
PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT
2+
PLAN_PR_DEBUG_SURFACES_GAME_INTEGRATION

‎docs/dev/reports/change_summary.txt‎

Lines changed: 14 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,13 +1,16 @@
1-
Created APPLY bundle for shared 3D debug support.
1+
Created a docs-only bundled pack for network support planning/build/apply contracts.
22

3-
Included:
4-
- apply PR doc
5-
- codex command
6-
- roadmap guardrails
7-
- updated BIG_PICTURE_ROADMAP.md (brackets only)
8-
- 3D sample adapter harness notes
9-
- reports
3+
Updated:
4+
- PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
5+
- BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
6+
- APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
7+
- docs/dev command + commit artifacts
8+
- docs/dev/reports summary/checklist/tree
9+
- BIG_PICTURE_ROADMAP.md bracket states only
1010

11-
Primary intent:
12-
- add summary-level, renderer-agnostic shared 3D support
13-
- keep adapters local
11+
Scope enforced:
12+
- docs-first only
13+
- one purpose per document
14+
- summary-level + opt-in
15+
- transport/protocol specifics remain local
16+
- packet inspectors, auth/matchmaking, deep inspectors excluded

‎docs/dev/reports/file_tree.txt‎

Lines changed: 11 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,11 @@
1-
APPLY_PR_DEBUG_SURFACES_3D_SUPPORT_delta/
2-
└── docs/
3-
├── dev/
4-
│ ├── BIG_PICTURE_ROADMAP.md
5-
│ ├── ROADMAP_GUARDRAILS.md
6-
│ ├── codex_commands.md
7-
│ ├── commit_comment.txt
8-
│ ├── next_command.txt
9-
│ ├── 3D_SAMPLE_ADAPTER_HARNESS.md
10-
│ └── reports/
11-
│ ├── change_summary.txt
12-
│ ├── validation_checklist.txt
13-
│ └── file_tree.txt
14-
└── pr/
15-
└── APPLY_PR_DEBUG_SURFACES_3D_SUPPORT.md
1+
DEBUG_SURFACES_NETWORK_SUPPORT_BUNDLE.zip
2+
- docs/pr/PLAN_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
3+
- docs/pr/BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
4+
- docs/pr/APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md
5+
- docs/dev/BIG_PICTURE_ROADMAP.md
6+
- docs/dev/ROADMAP_GUARDRAILS.md
7+
- docs/dev/codex_commands.md
8+
- docs/dev/commit_comment.txt
9+
- docs/dev/reports/change_summary.txt
10+
- docs/dev/reports/validation_checklist.txt
11+
- docs/dev/reports/file_tree.txt

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 17 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,19 @@
11
Validation Checklist
22

3-
[ ] Shared 3D providers created
4-
[ ] Shared 3D panels consume provider data only
5-
[ ] Optional shared 3D presets created
6-
[ ] Renderer-specific adapters remain local
7-
[ ] No deep inspectors added
8-
[ ] No renderer-specific logic added to shared layer
9-
[ ] BIG_PICTURE_ROADMAP.md changed by brackets only
10-
[ ] 3D sample/adapters validate successfully
3+
[x] PLAN/BUILD/APPLY docs are all present
4+
[x] One PR purpose per document is clear
5+
[x] Workflow PLAN -> BUILD -> APPLY is explicit in all docs
6+
[x] Shared network panel inventory is explicit
7+
[x] Shared network provider inventory is explicit
8+
[x] Optional shared network presets are explicit
9+
[x] Adapter boundaries are explicit
10+
[x] Adoption models are included
11+
[x] Naming conventions are included
12+
[x] Target structure is included
13+
[x] Transport/protocol adapters are outside shared layer
14+
[x] Protocol-specific implementation excluded
15+
[x] Packet inspector scope excluded
16+
[x] Auth/matchmaking tooling excluded
17+
[x] Deep inspector scope excluded
18+
[x] BIG_PICTURE_ROADMAP.md changed by bracket states only
19+
[x] ROADMAP_GUARDRAILS.md included unchanged

‎docs/pr/APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md‎

Lines changed: 61 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,61 @@
1+
# APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT
2+
3+
## Purpose
4+
Apply the approved shared network support layer in a small, boundary-safe implementation step.
5+
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
8+
9+
## PR Purpose
10+
One PR purpose only: implement summary-level shared network providers, panels, and optional presets.
11+
12+
## Apply Scope
13+
### Create shared providers
14+
- `provider.net.connection.snapshot`
15+
- `provider.net.latency.snapshot`
16+
- `provider.net.replication.snapshot`
17+
- `provider.net.divergence.snapshot`
18+
- `provider.net.events.snapshot`
19+
20+
### Create shared panels
21+
- `panel.net.connection`
22+
- `panel.net.latency`
23+
- `panel.net.replication`
24+
- `panel.net.divergence`
25+
- `panel.net.events`
26+
27+
### Create optional shared presets
28+
- `preset.net.status`
29+
- `preset.net.replication`
30+
- `preset.net.diagnostics`
31+
32+
### Keep local
33+
- transport/protocol adapters
34+
- authority extraction
35+
- stack-specific scene/debug mappings
36+
37+
## Execution Order
38+
1. providers
39+
2. panels (provider-driven only)
40+
3. optional presets
41+
4. shared registration entry points
42+
5. local adapter harness validation
43+
44+
## Rules
45+
- preserve existing provider/panel/preset conventions
46+
- keep adoption opt-in
47+
- keep shared layer transport-agnostic
48+
- no deep inspectors
49+
- no protocol-specific implementation
50+
- no packet inspectors
51+
- no auth/matchmaking tooling
52+
53+
## Validation
54+
- run syntax checks for touched modules
55+
- validate with local adapter harness or sample integration
56+
- verify shared layer consumes provider snapshots only
57+
58+
## Apply Outcome Contract
59+
- additive, non-destructive changes only
60+
- no engine-core rewrites
61+
- no project-specific adapter logic moved into shared layer

‎docs/pr/BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT.md‎

Lines changed: 81 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,81 @@
1+
# BUILD_PR_DEBUG_SURFACES_NETWORK_SUPPORT
2+
3+
## Purpose
4+
Build an authoritative docs-only bundle for shared network support implementation readiness.
5+
6+
## Workflow
7+
PLAN_PR -> BUILD_PR -> APPLY_PR
8+
9+
## PR Purpose
10+
One PR purpose only: define implementation-ready network support contracts for APPLY.
11+
12+
## Build Scope
13+
- shared network panel inventory
14+
- shared network provider inventory
15+
- optional shared network presets
16+
- adapter boundaries and ownership
17+
- adoption modes and naming rules
18+
- validation and rollback strategy
19+
20+
## Authoritative Shared Inventory
21+
Panels:
22+
- `panel.net.connection`
23+
- `panel.net.latency`
24+
- `panel.net.replication`
25+
- `panel.net.divergence`
26+
- `panel.net.events`
27+
28+
Providers:
29+
- `provider.net.connection.snapshot`
30+
- `provider.net.latency.snapshot`
31+
- `provider.net.replication.snapshot`
32+
- `provider.net.divergence.snapshot`
33+
- `provider.net.events.snapshot`
34+
35+
Optional presets:
36+
- `preset.net.status`
37+
- `preset.net.replication`
38+
- `preset.net.diagnostics`
39+
40+
## Target Structure
41+
```text
42+
engine/
43+
debug/
44+
standard/
45+
network/
46+
index.js
47+
shared/
48+
providers/
49+
panels/
50+
presets/
51+
```
52+
53+
## Boundary Contract
54+
Shared layer:
55+
- transport/protocol-agnostic descriptors and registration entry points.
56+
57+
Local adapters:
58+
- all protocol and transport extraction logic.
59+
- all authority-model specifics.
60+
61+
## Hard Exclusions
62+
- protocol-specific implementations
63+
- packet inspectors
64+
- auth tooling
65+
- matchmaking tooling
66+
- deep inspectors
67+
68+
## Validation Targets
69+
- panel/provider/preset ids are deterministic and namespaced
70+
- shared docs remain transport-agnostic
71+
- adapter boundaries are explicit and enforceable
72+
- apply sequence remains additive and non-destructive
73+
74+
## Rollback Strategy
75+
If APPLY scope grows beyond summary-level:
76+
1. keep ids and target structure stable
77+
2. reduce to connection + latency first
78+
3. defer replication/divergence/events details to follow-on PR
79+
80+
## Next Command
81+
`APPLY_PR_DEBUG_SURFACES_NETWORK_SUPPORT`

0 commit comments

Comments
 (0)