Skip to content

Commit c4cc294

Browse files
ToolboxAidToolboxAid
committed
define authoritative server runtime contracts — PLAN_PR_LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME
1 parent e9537e3 commit c4cc294

6 files changed

Lines changed: 152 additions & 6 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 2 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,4 @@
11
MODEL: GPT-5.3-codex
2-
REASONING: low
2+
REASONING: high
33
COMMAND:
4-
No further implementation. APPLY complete.
4+
Prepare for implementation of authoritative server runtime per PLAN_PR_LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME. No engine API breakage.

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1 @@
1-
apply transport/session foundation and validate — APPLY_PR_LEVEL_12_1_REAL_NETWORK_FOUNDATION
1+
define authoritative server runtime contracts — PLAN_PR_LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 3 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -1,3 +1,3 @@
1-
- Apply completed
2-
- Validation passed
3-
- Ready for next PR
1+
- Server loop defined
2+
- Input ingestion defined
3+
- Ownership boundaries defined

‎docs/pr/BUILD_PR_LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME.md‎

Lines changed: 55 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,55 @@
1+
# BUILD_PR_LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME
2+
3+
## Purpose
4+
Implement the first authoritative server runtime slice on top of Level 12.1 transport/session contracts with no engine API breakage.
5+
6+
## Scope
7+
Primary target files:
8+
- `src/engine/network/AuthoritativeServerRuntime.js`
9+
- `src/engine/network/AuthoritativeInputIngestionContract.js`
10+
- `src/engine/network/index.js`
11+
- `tests/final/MultiplayerNetworkingStack.test.mjs`
12+
- `docs/pr/LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME_CONTRACTS.md`
13+
14+
Allowed nearby reads:
15+
- `src/engine/network/TransportContract.js`
16+
- `src/engine/network/SessionLifecycleContract.js`
17+
- `src/engine/network/HandshakeSimulator.js`
18+
- `src/engine/network/HostServerBootstrap.js`
19+
- `docs/pr/LEVEL_12_1_REAL_NETWORK_FOUNDATION_CONTRACTS.md`
20+
21+
## Required implementation
22+
- Add an authoritative server runtime contract with an isolated tick loop that can run independently of gameplay code.
23+
- Add a client input ingestion contract that validates and normalizes input envelopes before queueing.
24+
- Enforce server-owned state boundaries so only server runtime code mutates authoritative state snapshots.
25+
- Keep handshake simulation compatible and testable with Level 12.1 foundations.
26+
- Export new runtime/contract symbols additively from `src/engine/network/index.js` only.
27+
- Extend `tests/final/MultiplayerNetworkingStack.test.mjs` with focused assertions for:
28+
- runtime loop start/step/stop behavior
29+
- input ingestion acceptance and rejection paths
30+
- server ownership boundary protection
31+
- existing handshake simulation still passing
32+
33+
## Acceptance criteria
34+
- Server runtime contract documented and implemented.
35+
- Input ingestion contract documented and implemented.
36+
- Authoritative ownership boundaries are enforced by runtime behavior and tests.
37+
- No existing engine network exports are removed or renamed.
38+
- Existing handshake simulation remains green.
39+
40+
## Validation
41+
Run only:
42+
- `node --check src/engine/network/AuthoritativeServerRuntime.js`
43+
- `node --check src/engine/network/AuthoritativeInputIngestionContract.js`
44+
- `node --input-type=module -e "import('./tests/final/MultiplayerNetworkingStack.test.mjs').then(async ({ run }) => { await run(); console.log('PASS MultiplayerNetworkingStack'); })"`
45+
- `node --input-type=module -e "import('./tests/production/EnginePublicBarrelImports.test.mjs').then(async ({ run }) => { await run(); console.log('PASS EnginePublicBarrelImports'); })"`
46+
47+
## Non-goals
48+
- no replication implementation
49+
- no gameplay coupling
50+
- no UI/debug expansion
51+
- no engine core API redesign
52+
- no repo-wide cleanup or unrelated refactor
53+
54+
## Working tree rule
55+
If the tree is already dirty, ignore unrelated files and modify only the scoped files for this PR purpose.

‎docs/pr/LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME_PREP.md‎

Lines changed: 67 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,67 @@
1+
# LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME_PREP
2+
3+
## Goal
4+
Define implementation-ready boundaries for Level 12.2 authoritative server runtime so APPLY can be executed in one pass without engine API breakage.
5+
6+
## Runtime Contract Shape (Planned)
7+
8+
`AuthoritativeServerRuntime` should expose:
9+
10+
- `start({ sessionId, tickRateHz })`
11+
- `stop(reason)`
12+
- `step(dtSeconds)`
13+
- `ingestClientInput(envelope)`
14+
- `drainAcceptedInputs()`
15+
- `getSnapshot()`
16+
17+
Runtime ownership:
18+
19+
- Owns authoritative tick/time counters.
20+
- Owns authoritative input queue.
21+
- Owns authoritative session status for runtime state.
22+
- Does not mutate gameplay state directly in Level 12.2.
23+
24+
## Client Input Ingestion Contract (Planned)
25+
26+
`AuthoritativeInputIngestionContract` validates inbound envelopes with a stable shape:
27+
28+
- `sessionId` string
29+
- `clientId` string
30+
- `sequence` non-negative integer
31+
- `inputType` string
32+
- `payload` plain object
33+
- `sentAtMs` finite number
34+
35+
Validation behavior:
36+
37+
- Reject malformed envelopes with deterministic codes.
38+
- Normalize accepted envelopes to a server-safe canonical shape.
39+
- Preserve ingestion metadata for diagnostics (`acceptedAtTick`, `acceptedAtMs`).
40+
41+
## Server-Owned State Boundaries (Planned)
42+
43+
State fields that must be server-owned:
44+
45+
- `authoritativeTick`
46+
- `runtimePhase` (`idle`, `running`, `stopped`, `failed`)
47+
- `connectedClients` registry
48+
- `acceptedInputQueue`
49+
50+
Boundary rules:
51+
52+
- Client-originated packets cannot directly mutate authoritative runtime fields.
53+
- All mutation enters through `ingestClientInput` and `step`.
54+
- External consumers receive read-only snapshots.
55+
56+
## Compatibility Guardrails
57+
58+
- Keep Level 12.1 handshake flow (`hello -> accept -> confirm`) intact and testable.
59+
- Maintain existing exports; add new exports only.
60+
- Avoid changes outside `src/engine/network/*` and targeted network tests.
61+
62+
## APPLY Readiness Checklist
63+
64+
- BUILD doc exists with exact targets and exact validation commands.
65+
- Runtime and ingestion contracts have concrete method signatures.
66+
- Ownership boundaries are explicit enough for deterministic tests.
67+
- Handshake regression checks remain in validation path.

‎docs/pr/PLAN_PR_LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# PLAN_PR_LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME
2+
3+
## Purpose
4+
Introduce authoritative server runtime layer on top of transport/session foundation.
5+
6+
## Scope
7+
- Define authoritative server loop
8+
- Define server-owned state boundaries
9+
- Define client input ingestion contract
10+
11+
## Non-Scope
12+
- No full replication system
13+
- No gameplay coupling
14+
- No UI/debug expansion
15+
16+
## Testability
17+
- Server loop runs independently
18+
- Input ingestion validated
19+
- State ownership enforced
20+
21+
## Acceptance Criteria
22+
- Server runtime contract documented
23+
- Input ingestion contract defined
24+
- Authoritative ownership boundaries enforced

0 commit comments

Comments
 (0)