Skip to content

Commit c5d1e88

Browse files
author
DavidQ
committed
define client replication and application contracts — PLAN_PR_LEVEL_12_3_REPLICATION_CLIENT_APPLICATION
1 parent f0fb37c commit c5d1e88

6 files changed

Lines changed: 153 additions & 11 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 2 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,4 @@
11
MODEL: GPT-5.3-codex
2-
REASONING: low
2+
REASONING: high
33
COMMAND:
4-
Finalize APPLY_PR_LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME.
5-
Additionally:
6-
- Update docs/dev/roadmaps/MASTER_ROADMAP_HIGH_LEVEL.md
7-
- Only update status markers [ ] [.] [x]
8-
- Do not modify wording, structure, or add/remove content
4+
Prepare implementation plan for client replication and application layer per PLAN_PR_LEVEL_12_3_REPLICATION_CLIENT_APPLICATION. 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 authoritative server runtime and validate — APPLY_PR_LEVEL_12_2_AUTHORITATIVE_SERVER_RUNTIME
1+
define client replication and application contracts — PLAN_PR_LEVEL_12_3_REPLICATION_CLIENT_APPLICATION

‎docs/dev/reports/validation_checklist.txt‎

Lines changed: 3 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,4 +1,3 @@
1-
- Apply completed
2-
- Validation passed
3-
- Roadmap status updated (status markers only)
4-
- Ready for next PR
1+
- Replication contract defined
2+
- Client application defined
3+
- Reconciliation rules defined

‎docs/pr/BUILD_PR_LEVEL_12_3_REPLICATION_CLIENT_APPLICATION.md‎

Lines changed: 63 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,63 @@
1+
# BUILD_PR_LEVEL_12_3_REPLICATION_CLIENT_APPLICATION
2+
3+
## Purpose
4+
Implement the Level 12.3 client replication and authoritative application layer on top of the Level 12.1/12.2 network foundation with no engine API breakage.
5+
6+
## Scope
7+
Primary target files:
8+
- `src/engine/network/ReplicationMessageContract.js`
9+
- `src/engine/network/ClientReplicationApplicationLayer.js`
10+
- `src/engine/network/ClientReconciliationStrategy.js`
11+
- `src/engine/network/index.js`
12+
- `tests/final/MultiplayerNetworkingStack.test.mjs`
13+
- `docs/pr/LEVEL_12_3_REPLICATION_CLIENT_APPLICATION_CONTRACTS.md`
14+
15+
Allowed nearby reads:
16+
- `src/engine/network/StateReplication.js`
17+
- `src/engine/network/AuthoritativeServerRuntime.js`
18+
- `src/engine/network/AuthoritativeInputIngestionContract.js`
19+
- `src/engine/network/HandshakeSimulator.js`
20+
- `docs/pr/LEVEL_12_1_REAL_NETWORK_FOUNDATION_CONTRACTS.md`
21+
22+
## Required implementation
23+
- Define a replication message contract for server-to-client authoritative snapshots.
24+
- Implement a client-side application layer that:
25+
- accepts validated replication envelopes
26+
- applies authoritative snapshots into client-owned replicated state
27+
- rejects stale/out-of-order updates deterministically
28+
- Implement a reconciliation/update strategy for Level 12.3 without prediction/rollback:
29+
- authoritative-first apply
30+
- stale snapshot ignore rules
31+
- deterministic metadata updates (`lastAppliedTick`, `appliedSequence`)
32+
- Export new symbols additively from `src/engine/network/index.js` only.
33+
- Extend `tests/final/MultiplayerNetworkingStack.test.mjs` to validate:
34+
- replication envelope validation
35+
- client authoritative apply behavior
36+
- stale update rejection
37+
- existing handshake and server-runtime coverage still passing
38+
39+
## Acceptance criteria
40+
- Replication contract documented and implemented.
41+
- Client application model defined and implemented.
42+
- Reconciliation rules established and enforced by tests.
43+
- No existing engine network exports are removed or renamed.
44+
- Existing Level 12.1 and 12.2 networking tests remain green.
45+
46+
## Validation
47+
Run only:
48+
- `node --check src/engine/network/ReplicationMessageContract.js`
49+
- `node --check src/engine/network/ClientReplicationApplicationLayer.js`
50+
- `node --check src/engine/network/ClientReconciliationStrategy.js`
51+
- `node --input-type=module -e "import('./tests/final/MultiplayerNetworkingStack.test.mjs').then(async ({ run }) => { await run(); console.log('PASS MultiplayerNetworkingStack'); })"`
52+
- `node --input-type=module -e "import('./tests/production/EnginePublicBarrelImports.test.mjs').then(async ({ run }) => { await run(); console.log('PASS EnginePublicBarrelImports'); })"`
53+
54+
## Non-goals
55+
- no client prediction implementation
56+
- no rollback implementation
57+
- no gameplay-specific coupling
58+
- no UI/debug expansion
59+
- no engine core API redesign
60+
- no repo-wide cleanup or unrelated refactor
61+
62+
## Working tree rule
63+
If the tree is already dirty, ignore unrelated files and modify only the scoped files for this PR purpose.

‎docs/pr/LEVEL_12_3_REPLICATION_CLIENT_APPLICATION_PREP.md‎

Lines changed: 60 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,60 @@
1+
# LEVEL_12_3_REPLICATION_CLIENT_APPLICATION_PREP
2+
3+
## Goal
4+
Prepare an implementation-ready plan for Level 12.3 client replication/application so APPLY can execute in one pass with additive network APIs only.
5+
6+
## Replication Message Contract (Planned)
7+
8+
Server-to-client replication envelope:
9+
10+
- `sessionId` string
11+
- `replicationSequence` non-negative integer
12+
- `authoritativeTick` non-negative integer
13+
- `snapshotType` string (`full` or `delta`)
14+
- `snapshot` plain object payload
15+
- `sentAtMs` finite number
16+
17+
Contract behavior:
18+
19+
- reject malformed envelopes deterministically
20+
- reject envelopes with server-owned field mutation attempts in client metadata payloads
21+
- normalize accepted envelopes to a canonical read-safe shape
22+
23+
## Client Application Model (Planned)
24+
25+
`ClientReplicationApplicationLayer` should expose:
26+
27+
- `ingestReplicationEnvelope(envelope)`
28+
- `applyPendingReplication()`
29+
- `getReplicatedStateSnapshot()`
30+
- `getReplicationStatus()`
31+
32+
State ownership:
33+
34+
- authoritative source is server replication envelope only
35+
- client layer owns local replicated cache + apply metadata
36+
- gameplay systems remain consumers, not writers, in Level 12.3 scope
37+
38+
## Reconciliation / Update Strategy (Planned)
39+
40+
Level 12.3 reconciliation is authoritative-first with no prediction/rollback:
41+
42+
- apply newest valid authoritative envelope in deterministic order
43+
- ignore stale envelopes (`authoritativeTick` lower than last applied tick)
44+
- for equal tick, apply highest `replicationSequence` only
45+
- persist reasons for ignored envelopes (`stale_tick`, `stale_sequence`, `invalid_envelope`)
46+
47+
## API Compatibility Guardrails
48+
49+
- no removal/rename of existing exports in `src/engine/network/index.js`
50+
- new exports are additive only
51+
- preserve Level 12.1 handshake simulation behavior
52+
- preserve Level 12.2 server runtime/input-ingestion behavior
53+
54+
## Validation Focus for APPLY
55+
56+
- replication envelope validation passes for valid/invalid cases
57+
- client apply path updates state correctly for ordered envelopes
58+
- stale/out-of-order envelopes are rejected deterministically
59+
- existing multiplayer networking stack tests remain green
60+
- public engine barrel import test remains green

‎docs/pr/PLAN_PR_LEVEL_12_3_REPLICATION_CLIENT_APPLICATION.md‎

Lines changed: 24 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,24 @@
1+
# PLAN_PR_LEVEL_12_3_REPLICATION_CLIENT_APPLICATION
2+
3+
## Purpose
4+
Introduce client-side replication and application layer for authoritative server model.
5+
6+
## Scope
7+
- Define replication message contract
8+
- Define client application of authoritative state
9+
- Define reconciliation/update strategy
10+
11+
## Non-Scope
12+
- No prediction/rollback yet
13+
- No gameplay-specific logic
14+
- No UI/debug expansion
15+
16+
## Testability
17+
- Client receives replication data
18+
- Client applies authoritative updates correctly
19+
- State divergence minimized under controlled conditions
20+
21+
## Acceptance Criteria
22+
- Replication contract documented
23+
- Client application model defined
24+
- Reconciliation rules established

0 commit comments

Comments
 (0)