Skip to content

Commit a0490cb

Browse files
author
DavidQ
committed
define target move-map for network directory normalization — PLAN_PR_LEVEL_12_8_NETWORK_DIRECTORY_NORMALIZATION & normalize network directory structure with validated import rewiring — BUILD_PR_LEVEL_12_8_NETWORK_DIRECTORY_NORMALIZATION
1 parent 3d88761 commit a0490cb

28 files changed

Lines changed: 334 additions & 46 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 15 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,7 +1,18 @@
11
MODEL: GPT-5.4
2-
REASONING: medium
2+
REASONING: high
33
COMMAND:
4-
Finalize APPLY_PR_LEVEL_12_7_REAL_NETWORK_COMPLETION_GATE with real execution evidence.
4+
Implement BUILD_PR_LEVEL_12_8_NETWORK_DIRECTORY_NORMALIZATION exactly as defined from the reviewed src.zip baseline.
5+
Apply the exact move-map under src/engine/network/.
6+
Keep scope to directory normalization only.
57
Do not add features.
6-
Update docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md by markers only.
7-
Advance `promotion/readiness gate` from [.] to [x] only if every validation area passed.
8+
Do not leave duplicate legacy files behind.
9+
Update imports and src/engine/network/index.js so the export surface remains stable where possible.
10+
Run real validation:
11+
- import/path resolution
12+
- network runtime smoke boot
13+
- transport/session lifecycle smoke
14+
- authoritative runtime boot
15+
- replication/apply smoke
16+
- focused 2D regression smoke
17+
Update docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md by changing status markers only.
18+
Do not modify roadmap wording, structure, add content, or delete content.

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
apply real-network completion gate with evidence; advance marker only on full pass — APPLY_PR_LEVEL_12_7_REAL_NETWORK_COMPLETION_GATE
1+
normalize network directory structure with validated import rewiring — BUILD_PR_LEVEL_12_8_NETWORK_DIRECTORY_NORMALIZATION

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 5 additions & 9 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,5 @@
1-
- transport/session validated
2-
- authoritative determinism validated
3-
- client replication validated
4-
- playable slice validated
5-
- hosting/runtime validated
6-
- remote deployment validated
7-
- 2D regressions: none
8-
- evidence attached
9-
- roadmap markers updated only
1+
- reviewed actual src.zip baseline
2+
- exact move-map defined
3+
- scope limited to network directory normalization
4+
- testable validation requirements included
5+
- roadmap update constrained to marker-only progression

‎docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -671,3 +671,5 @@
671671
[ ] Arrange docs into classification buckets.
672672
[ ] Any doc that is only move/rename/etc. should be deleted (verify content is in the correct doc before deleting).
673673
[ ] Consolidate PRs for easier one-stop review, so one capability does not require reading many docs (for example, bezel/background); focus on what the capability does.
674+
[ ] Remove imports to export (should not be import x, export x)
675+
[ ] other than templates (games/samples/tools), remove the .keep file, if the folder is empty, delete

‎docs/pr/BUILD_PR_LEVEL_12_8_NETWORK_DIRECTORY_NORMALIZATION.md‎

Lines changed: 162 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,162 @@
1+
# BUILD_PR_LEVEL_12_8_NETWORK_DIRECTORY_NORMALIZATION
2+
3+
## Build Scope
4+
Normalize the current flat `src/engine/network/` layout into explicit network subfolders using the reviewed `src.zip` file set.
5+
6+
## One PR Purpose Only
7+
Network directory normalization only.
8+
9+
## Testable PR Requirement
10+
This PR is not commit-only.
11+
The implementation must:
12+
1. move files into the new structure
13+
2. update imports/exports
14+
3. keep runtime behavior unchanged
15+
4. pass real boot/smoke validation
16+
5. update roadmap markers only if execution-backed validation succeeds
17+
18+
## Source Baseline Used
19+
Reviewed from uploaded `src.zip`.
20+
21+
## Current Files Confirmed
22+
- `src/engine/network/AuthoritativeInputIngestionContract.js`
23+
- `src/engine/network/AuthoritativeServerRuntime.js`
24+
- `src/engine/network/ChatPresenceLayer.js`
25+
- `src/engine/network/ClientReconciliationStrategy.js`
26+
- `src/engine/network/ClientReplicationApplicationLayer.js`
27+
- `src/engine/network/HandshakeSimulator.js`
28+
- `src/engine/network/HostServerBootstrap.js`
29+
- `src/engine/network/InterestManager.js`
30+
- `src/engine/network/LobbySessionManager.js`
31+
- `src/engine/network/LoopbackTransport.js`
32+
- `src/engine/network/NetworkConditionSimulator.js`
33+
- `src/engine/network/NetworkDebugOverlay.js`
34+
- `src/engine/network/NetworkingLayer.js`
35+
- `src/engine/network/PredictionReconciler.js`
36+
- `src/engine/network/RemoteInterpolationBuffer.js`
37+
- `src/engine/network/ReplicationMessageContract.js`
38+
- `src/engine/network/RollbackDiagnostics.js`
39+
- `src/engine/network/Serializer.js`
40+
- `src/engine/network/SessionLifecycleContract.js`
41+
- `src/engine/network/StateReplication.js`
42+
- `src/engine/network/TransportContract.js`
43+
- `src/engine/network/index.js`
44+
45+
## Target Structure
46+
```text
47+
src/engine/network/
48+
index.js
49+
transport/
50+
TransportContract.js
51+
LoopbackTransport.js
52+
NetworkConditionSimulator.js
53+
Serializer.js
54+
session/
55+
SessionLifecycleContract.js
56+
HandshakeSimulator.js
57+
LobbySessionManager.js
58+
ChatPresenceLayer.js
59+
server/
60+
AuthoritativeServerRuntime.js
61+
AuthoritativeInputIngestionContract.js
62+
InterestManager.js
63+
RollbackDiagnostics.js
64+
client/
65+
ClientReplicationApplicationLayer.js
66+
ClientReconciliationStrategy.js
67+
PredictionReconciler.js
68+
RemoteInterpolationBuffer.js
69+
replication/
70+
ReplicationMessageContract.js
71+
StateReplication.js
72+
bootstrap/
73+
HostServerBootstrap.js
74+
NetworkingLayer.js
75+
debug/
76+
NetworkDebugOverlay.js
77+
```
78+
79+
## Exact Move Map
80+
- `src/engine/network/TransportContract.js` -> `src/engine/network/transport/TransportContract.js`
81+
- `src/engine/network/LoopbackTransport.js` -> `src/engine/network/transport/LoopbackTransport.js`
82+
- `src/engine/network/NetworkConditionSimulator.js` -> `src/engine/network/transport/NetworkConditionSimulator.js`
83+
- `src/engine/network/Serializer.js` -> `src/engine/network/transport/Serializer.js`
84+
85+
- `src/engine/network/SessionLifecycleContract.js` -> `src/engine/network/session/SessionLifecycleContract.js`
86+
- `src/engine/network/HandshakeSimulator.js` -> `src/engine/network/session/HandshakeSimulator.js`
87+
- `src/engine/network/LobbySessionManager.js` -> `src/engine/network/session/LobbySessionManager.js`
88+
- `src/engine/network/ChatPresenceLayer.js` -> `src/engine/network/session/ChatPresenceLayer.js`
89+
90+
- `src/engine/network/AuthoritativeServerRuntime.js` -> `src/engine/network/server/AuthoritativeServerRuntime.js`
91+
- `src/engine/network/AuthoritativeInputIngestionContract.js` -> `src/engine/network/server/AuthoritativeInputIngestionContract.js`
92+
- `src/engine/network/InterestManager.js` -> `src/engine/network/server/InterestManager.js`
93+
- `src/engine/network/RollbackDiagnostics.js` -> `src/engine/network/server/RollbackDiagnostics.js`
94+
95+
- `src/engine/network/ClientReplicationApplicationLayer.js` -> `src/engine/network/client/ClientReplicationApplicationLayer.js`
96+
- `src/engine/network/ClientReconciliationStrategy.js` -> `src/engine/network/client/ClientReconciliationStrategy.js`
97+
- `src/engine/network/PredictionReconciler.js` -> `src/engine/network/client/PredictionReconciler.js`
98+
- `src/engine/network/RemoteInterpolationBuffer.js` -> `src/engine/network/client/RemoteInterpolationBuffer.js`
99+
100+
- `src/engine/network/ReplicationMessageContract.js` -> `src/engine/network/replication/ReplicationMessageContract.js`
101+
- `src/engine/network/StateReplication.js` -> `src/engine/network/replication/StateReplication.js`
102+
103+
- `src/engine/network/HostServerBootstrap.js` -> `src/engine/network/bootstrap/HostServerBootstrap.js`
104+
- `src/engine/network/NetworkingLayer.js` -> `src/engine/network/bootstrap/NetworkingLayer.js`
105+
106+
- `src/engine/network/NetworkDebugOverlay.js` -> `src/engine/network/debug/NetworkDebugOverlay.js`
107+
108+
## Keep In Place
109+
- `src/engine/network/index.js`
110+
111+
## index.js Requirement
112+
Update `src/engine/network/index.js` so the public export surface remains stable after file moves.
113+
Prefer re-export compatibility so existing import sites keep working where possible.
114+
115+
## Import Update Rule
116+
- update all imports impacted by moved files
117+
- do not leave stale paths
118+
- do not leave duplicate shadow copies behind
119+
- do not widen scope outside this move-map unless required by import resolution
120+
121+
## Validation Requirements
122+
The BUILD implementation must be testable and must validate all of the following:
123+
124+
### Path / Import Validation
125+
- all moved module imports resolve
126+
- `src/engine/network/index.js` exports resolve
127+
- no broken relative imports remain
128+
129+
### Runtime Smoke Validation
130+
- existing network sample/runtime boot still works
131+
- transport/session lifecycle still works
132+
- authoritative runtime still boots
133+
- replication/apply path still works
134+
135+
### Regression Protection
136+
- focused 2D smoke path still boots
137+
- no engine API breakage caused by path rewiring
138+
139+
## Roadmap Update Rule
140+
Update:
141+
`docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md`
142+
143+
Allowed:
144+
- status markers only: `[ ]` `[.]` `[x]`
145+
146+
Forbidden:
147+
- wording edits
148+
- structure edits
149+
- additions
150+
- deletions
151+
152+
## Marker Progress
153+
This BUILD is execution-backed and testable.
154+
Advance the related normalization marker only when the move-map is implemented and validated successfully.
155+
156+
## Acceptance Criteria
157+
- exact file move-map applied
158+
- imports updated
159+
- stable network export surface preserved
160+
- no duplicate legacy copies left behind
161+
- runtime smoke checks pass
162+
- roadmap updated by marker only

‎docs/pr/PLAN_PR_LEVEL_12_8_NETWORK_DIRECTORY_NORMALIZATION.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# PLAN_PR_LEVEL_12_8_NETWORK_DIRECTORY_NORMALIZATION
2+
3+
## Purpose
4+
Normalize the current flat `src/engine/network/` module layout into a clearer directory structure without changing network scope or adding features.
5+
6+
## Reason For This PR
7+
Current network modules are functionally present, but the flat layout makes ownership and test mapping harder to follow.
8+
This PR creates the directory-structure plan first so the next BUILD can be executed against the actual updated `src` you provide.
9+
10+
## One PR Purpose Only
11+
Network directory normalization only.
12+
13+
## Scope
14+
Define the target homes for existing network modules under:
15+
- `src/engine/network/transport/`
16+
- `src/engine/network/session/`
17+
- `src/engine/network/server/`
18+
- `src/engine/network/client/`
19+
- `src/engine/network/replication/`
20+
- `src/engine/network/debug/`
21+
- `src/engine/network/bootstrap/`
22+
23+
## In Scope
24+
- move-map for existing files only
25+
- import update expectations
26+
- public export/index expectations
27+
- validation expectations for path-safe normalization
28+
- roadmap status-marker update rule
29+
30+
## Out Of Scope
31+
- no new network features
32+
- no protocol redesign
33+
- no message-format changes
34+
- no gameplay changes
35+
- no 3D work
36+
- no broad engine cleanup beyond this move-map
37+
38+
## Current Flat Modules Expected For Classification
39+
Examples already identified in the current flat layout:
40+
- `src/engine/network/index.js`
41+
- `src/engine/network/TransportContract.js`
42+
- `src/engine/network/SessionLifecycleContract.js`
43+
- `src/engine/network/HandshakeSimulator.js`
44+
- `src/engine/network/AuthoritativeServerRuntime.js`
45+
- `src/engine/network/AuthoritativeInputIngestionContract.js`
46+
- `src/engine/network/ReplicationMessageContract.js`
47+
- `src/engine/network/ClientReplicationApplicationLayer.js`
48+
- `src/engine/network/ClientReconciliationStrategy.js`
49+
- `src/engine/network/StateReplication.js`
50+
- `src/engine/network/LoopbackTransport.js`
51+
- `src/engine/network/HostServerBootstrap.js`
52+
- `src/engine/network/LobbySessionManager.js`
53+
54+
## Proposed Target Structure
55+
```text
56+
src/engine/network/
57+
index.js
58+
transport/
59+
TransportContract.js
60+
LoopbackTransport.js
61+
session/
62+
SessionLifecycleContract.js
63+
HandshakeSimulator.js
64+
LobbySessionManager.js
65+
server/
66+
AuthoritativeServerRuntime.js
67+
AuthoritativeInputIngestionContract.js
68+
client/
69+
ClientReplicationApplicationLayer.js
70+
ClientReconciliationStrategy.js
71+
RemoteInterpolationBuffer.js
72+
PredictionReconciler.js
73+
replication/
74+
ReplicationMessageContract.js
75+
StateReplication.js
76+
bootstrap/
77+
HostServerBootstrap.js
78+
NetworkingLayer.js
79+
debug/
80+
NetworkDebugOverlay.js
81+
```
82+
83+
## Move-Map Rules
84+
- keep file names unless a rename is required for clarity
85+
- preserve behavior
86+
- update imports exactly
87+
- do not leave duplicate legacy copies behind
88+
- maintain a stable `src/engine/network/index.js` export surface if possible
89+
90+
## Validation Requirements
91+
The BUILD/APPLY that follows this PLAN must be testable and must validate:
92+
1. imports resolve after moves
93+
2. local network sample/runtime still boots
94+
3. transport/session lifecycle still works
95+
4. authoritative server runtime still boots
96+
5. client replication/application still works
97+
6. no cross-lane 2D regression from import-path changes
98+
99+
## Testability Requirement
100+
This normalization PR must not be commit-only.
101+
The BUILD must include real import/path validation and runtime smoke validation so roadmap markers can move through real execution-backed progression.
102+
103+
## Roadmap Rule
104+
Any roadmap update must be marker-only:
105+
- `[ ]`
106+
- `[.]`
107+
- `[x]`
108+
109+
Do not change wording, structure, add content, or delete content.
110+
111+
## Expected Next Step
112+
After you provide the updated `src`, generate:
113+
- `BUILD_PR_LEVEL_12_8_NETWORK_DIRECTORY_NORMALIZATION`
114+
115+
## Acceptance Criteria
116+
- target directory structure defined
117+
- move-map boundaries defined
118+
- non-scope protected
119+
- BUILD prepared to be one-pass executable after updated `src` is provided

src/engine/network/HostServerBootstrap.js renamed to src/engine/network/bootstrap/HostServerBootstrap.js

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -4,7 +4,7 @@ David Quesenberry
44
03/22/2026
55
HostServerBootstrap.js
66
*/
7-
import LobbySessionManager from './LobbySessionManager.js';
7+
import LobbySessionManager from '../session/LobbySessionManager.js';
88

99
export default class HostServerBootstrap {
1010
constructor({ lobby = null } = {}) {

src/engine/network/NetworkingLayer.js renamed to src/engine/network/bootstrap/NetworkingLayer.js

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -4,8 +4,8 @@ David Quesenberry
44
03/22/2026
55
NetworkingLayer.js
66
*/
7-
import LoopbackTransport from './LoopbackTransport.js';
8-
import NetworkConditionSimulator from './NetworkConditionSimulator.js';
7+
import LoopbackTransport from '../transport/LoopbackTransport.js';
8+
import NetworkConditionSimulator from '../transport/NetworkConditionSimulator.js';
99

1010
function clone(value) {
1111
return JSON.parse(JSON.stringify(value));

src/engine/network/ClientReconciliationStrategy.js renamed to src/engine/network/client/ClientReconciliationStrategy.js

File renamed without changes.

src/engine/network/ClientReplicationApplicationLayer.js renamed to src/engine/network/client/ClientReplicationApplicationLayer.js

Lines changed: 2 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -7,8 +7,8 @@ ClientReplicationApplicationLayer.js
77
import ClientReconciliationStrategy, {
88
REPLICATION_IGNORE_REASONS,
99
} from './ClientReconciliationStrategy.js';
10-
import ReplicationMessageContract from './ReplicationMessageContract.js';
11-
import StateReplication from './StateReplication.js';
10+
import ReplicationMessageContract from '../replication/ReplicationMessageContract.js';
11+
import StateReplication from '../replication/StateReplication.js';
1212

1313
function clone(value) {
1414
return JSON.parse(JSON.stringify(value));
@@ -122,4 +122,3 @@ export default class ClientReplicationApplicationLayer {
122122
};
123123
}
124124
}
125-

0 commit comments

Comments
 (0)