Skip to content

Commit 1d334bd

Browse files
author
DavidQ
committed
Plan Level 11.2 reconciliation layer foundation
- Define reconciliation-layer responsibilities and boundaries - Define bounded state timeline/history expectations - Define a reusable debug-surface contract for future samples - Preserve Sample C as proving ground rather than shared implementation - Explicitly prohibit engine-core, server-dashboard, and docker work in this planning step
1 parent eba94ff commit 1d334bd

11 files changed

Lines changed: 544 additions & 35 deletions

‎docs/dev/CODEX_COMMANDS.md‎

Lines changed: 22 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,26 @@
1-
MODEL: GPT-5.4-codex
1+
MODEL: GPT-5.4
22
REASONING: high
33

44
COMMAND:
5-
Create PR_DEBUG_SURFACES_NETWORK_SAMPLE_C_FULL.
5+
Create BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION as a docs-first implementation plan follow-up for the HTML-JavaScript-Gaming repo.
66

7-
PURPOSE:
8-
Implement Network Sample C - Divergence / Trace Validation, add its Level 11 games hub card using the existing debug-showcase card format, update NETWORK_SAMPLES_PLAN.md to Track P in progress, and update BIG_PICTURE_ROADMAP.md to remove broken icons and keep plain-text Track T / Track U headings. Do not add a new top section to games/index.html. Do not include engine-core, server-dashboard, or docker implementation in this PR.
7+
Requirements:
8+
- Use docs/dev/RECONCILIATION_LAYER_SPEC.md, docs/dev/STATE_TIMELINE_SPEC.md, and docs/dev/DEBUG_SURFACE_CONTRACT.md as source guidance.
9+
- Preserve current repo workflow conventions.
10+
- Do not modify engine core APIs.
11+
- Do not add server-dashboard, docker, or transport implementation.
12+
- Keep Sample C as a consumer/proving ground, not the shared implementation itself.
13+
- Normalize any proposed interfaces around approved public selectors/events only.
14+
- Prefer sample-level layering and bounded history buffers.
15+
- Future-proof naming away from sample-specific ad hoc wiring.
16+
- Package outputs as a repo-structured ZIP at:
17+
HTML-JavaScript-Gaming/tmp/BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION_delta.zip
18+
19+
Expected outputs:
20+
- docs/pr/BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION.md
21+
- docs/dev/reports/file_tree.txt
22+
- docs/dev/reports/change_summary.txt
23+
- docs/dev/reports/validation_checklist.txt
24+
- docs/dev/commit_comment.txt
25+
26+
Do not write implementation code unless explicitly required by the build instructions. Keep this bundle docs/planning only.

‎docs/dev/COMMIT_COMMENT.txt‎

Lines changed: 8 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1 +1,8 @@
1-
docs(network-sample-c): plan Level 11 divergence/trace sample and roadmap cleanup
1+
Build Level 11.2 reconciliation layer foundation (docs-first)
2+
3+
- Create BUILD follow-up plan from reconciliation/timeline/debug contract specs
4+
- Preserve PLAN_PR -> BUILD_PR -> APPLY_PR workflow conventions
5+
- Keep Sample C as proving-ground consumer, not shared layer implementation
6+
- Normalize future interfaces around approved public selectors/events only
7+
- Require sample-level layering and bounded history buffers
8+
- Explicitly exclude engine-core, server-dashboard, docker, and transport implementation

‎docs/dev/DEBUG_SURFACE_CONTRACT.md‎

Lines changed: 82 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,82 @@
1+
# DEBUG_SURFACE_CONTRACT
2+
3+
## Objective
4+
Define a small, explicit contract for network/debug surfaces so future samples and tools do not invent incompatible overlay wiring.
5+
6+
## Principles
7+
- Optional attachment
8+
- Read-mostly behavior
9+
- No hard dependency from core runtime onto debug surfaces
10+
- Consistent terminology across samples
11+
12+
## Contract Shape
13+
A debug surface should be attachable to a scene/model/reconciliation provider through a documented interface rather than through direct private mutation.
14+
15+
## Recommended Capability Areas
16+
### 1. Attach / Detach
17+
```text
18+
attachDebugSurface(context)
19+
detachDebugSurface()
20+
```
21+
22+
### 2. State Reads
23+
The debug surface may read:
24+
- predicted summary
25+
- authoritative summary
26+
- divergence report
27+
- correction plan
28+
- timeline status
29+
30+
### 3. Render / Update Hooks
31+
The debug surface may:
32+
- render textual diagnostics
33+
- render markers/paths/vectors
34+
- highlight corrected entities
35+
- show current correction mode and severity
36+
37+
The debug surface should not:
38+
- own game logic
39+
- directly change authoritative truth
40+
- require engine-core changes to exist
41+
42+
## Recommended Context Shape
43+
```text
44+
{
45+
scene,
46+
getPredictedState,
47+
getAuthoritativeState,
48+
getLatestDivergenceReport,
49+
getCorrectionPlan,
50+
getTimelineStatus
51+
}
52+
```
53+
54+
Exact names may vary, but this shape should remain conceptually stable.
55+
56+
## Toggle Strategy
57+
Allowed activation patterns:
58+
- hardcoded sample-dev flag during early development
59+
- URL/query flag later
60+
- hub/dev menu toggle later
61+
62+
Disallowed pattern:
63+
- unconditional permanent coupling that forces debug rendering in normal runtime paths
64+
65+
## Visual Guidance
66+
Debug surfaces should prefer:
67+
- clear text labels
68+
- simple vector/marker overlays
69+
- severity cues through shape/placement, not fragile assumptions
70+
71+
Avoid over-design or making the sample unreadable.
72+
73+
## Sample C Role
74+
Sample C acts as the proving ground for this contract. It should be refactored toward the contract over time, not treated as the final shared solution.
75+
76+
## Future Extension Points
77+
The same contract should later support:
78+
- server dashboard mirrors
79+
- transport latency indicators
80+
- reconciliation counters
81+
- history scrubbers
82+
- replay comparison overlays

‎docs/dev/RECONCILIATION_LAYER_SPEC.md‎

Lines changed: 119 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,119 @@
1+
# RECONCILIATION_LAYER_SPEC
2+
3+
## Objective
4+
Define a reusable, sample-safe reconciliation layer for Level 11 progression. This layer compares predicted client-side simulation state with authoritative updates and determines how corrections should be surfaced and applied.
5+
6+
## Design Principles
7+
- Layered, not invasive
8+
- Sample-safe first
9+
- Public-boundary only
10+
- Debug-friendly by design
11+
- No direct engine-core rewrites
12+
13+
## Core Terms
14+
### Predicted State
15+
The locally simulated state advanced by the client/sample before authoritative confirmation arrives.
16+
17+
### Authoritative State
18+
The state accepted as source-of-truth from an approved upstream authority.
19+
20+
### Divergence
21+
The measurable difference between predicted state and authoritative state for one entity, one frame, or one logical update.
22+
23+
### Correction
24+
The action chosen to reduce or resolve divergence.
25+
26+
## Responsibilities
27+
The reconciliation layer should:
28+
- accept predicted snapshots
29+
- accept authoritative snapshots or events
30+
- align comparable state units
31+
- compute deltas
32+
- choose a correction strategy
33+
- expose correction metadata to debug surfaces
34+
35+
The reconciliation layer should not:
36+
- own rendering
37+
- directly own transport/networking
38+
- mutate engine internals through private hooks
39+
- become a hidden replacement for game scene logic
40+
41+
## Suggested Data Flow
42+
1. Sample/game simulation advances predicted state.
43+
2. Snapshot is recorded into a bounded history buffer.
44+
3. Authoritative update arrives through an approved source boundary.
45+
4. Reconciliation layer matches update to a frame/tick/entity.
46+
5. Divergence is computed.
47+
6. Correction policy decides snap, smooth correction, or debug-hold.
48+
7. Debug contract receives normalized divergence/correction data.
49+
50+
## Candidate Interfaces
51+
```text
52+
recordPredictedSnapshot(snapshot)
53+
receiveAuthoritativeSnapshot(snapshot)
54+
reconcileLatest()
55+
getLatestDivergenceReport()
56+
getCorrectionPlan()
57+
```
58+
59+
Exact naming may vary, but the functional responsibilities should remain stable.
60+
61+
## Correction Modes
62+
### 1. Snap
63+
Use when:
64+
- divergence is severe
65+
- object count is low
66+
- clarity is more important than feel
67+
- debug mode explicitly requests hard truth
68+
69+
### 2. Smooth Settle / Lerp
70+
Use when:
71+
- divergence is modest
72+
- visual continuity matters
73+
- the sample is teaching correction behavior
74+
75+
### 3. Hold + Annotate
76+
Use when:
77+
- goal is observability
78+
- immediate correction would hide the problem
79+
- the sample/debug overlay needs to show the mismatch clearly
80+
81+
## Normalized Divergence Fields
82+
Recommended normalized fields for debug/reporting:
83+
- `entityId`
84+
- `predictedFrame`
85+
- `authoritativeFrame`
86+
- `positionDelta`
87+
- `velocityDelta`
88+
- `stateFlagsDelta`
89+
- `correctionMode`
90+
- `severity`
91+
92+
## Severity Guidance
93+
Suggested severity bands:
94+
- low: informational
95+
- medium: visible mismatch, correction recommended
96+
- high: state invalidation or obvious desync
97+
98+
## Boundary Rules
99+
- No new engine-core dependency from shared engine code into sample code.
100+
- No private scene mutation shortcuts.
101+
- No transport assumptions baked into reconciliation interfaces.
102+
- Shared logic should remain consumable by multiple future samples.
103+
104+
## Migration Guidance from Sample C
105+
Sample C should remain:
106+
- a teaching sample
107+
- a divergence visualization surface
108+
- an early consumer of the contract
109+
110+
Sample C should not become:
111+
- the shared reconciliation implementation itself
112+
- a dumping ground for generic runtime logic
113+
114+
## Future Expansion
115+
This spec should later support:
116+
- rollback/resimulation experiments
117+
- server trace visualization
118+
- deterministic replay comparison
119+
- multi-entity correction batching

‎docs/dev/STATE_TIMELINE_SPEC.md‎

Lines changed: 84 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,84 @@
1+
# STATE_TIMELINE_SPEC
2+
3+
## Objective
4+
Define the history/timeline model needed to support Level 11 reconciliation work without altering engine-core timing systems.
5+
6+
## Why a Timeline Exists
7+
A reconciliation layer needs more than “latest state.” It needs a bounded memory of recent predicted frames so authoritative updates can be aligned to the correct historical point.
8+
9+
## Timeline Responsibilities
10+
- store recent predicted snapshots
11+
- associate snapshots with frame/tick identifiers
12+
- support lookup by frame/tick/entity
13+
- expose enough history for debug and future replay concepts
14+
- remain bounded and disposable
15+
16+
## Non-Goals
17+
- replacing the engine game loop
18+
- implementing full rollback netcode in this track
19+
- persisting long-term session history
20+
21+
## Recommended Model
22+
### Snapshot Record
23+
Each record should minimally include:
24+
- frame or tick id
25+
- timestamp if available through approved boundary
26+
- entity snapshot payload
27+
- optional input marker / local action marker
28+
29+
### Bounded Buffer
30+
Use a bounded history window sized for sample-scale debugging and reconciliation.
31+
32+
Suggested starting guidance:
33+
- keep the newest N frames only
34+
- prune oldest entries predictably
35+
- avoid unbounded arrays/maps
36+
37+
Exact N can be implementation-defined, but should be documented in code comments and debug UI if visible.
38+
39+
## Lookup Scenarios
40+
The timeline should support:
41+
1. latest predicted snapshot for an entity
42+
2. predicted snapshot matching authoritative frame/tick
43+
3. nearest prior predicted snapshot when exact match is absent
44+
4. compact debug summary for recent divergence events
45+
46+
## Alignment Strategy
47+
### Preferred
48+
Match authoritative update to exact frame/tick id.
49+
50+
### Acceptable fallback
51+
Match to nearest earlier predicted frame and mark alignment as approximate.
52+
53+
### Avoid
54+
Silently comparing unrelated frames with no annotation.
55+
56+
## Timeline Contract Concepts
57+
```text
58+
pushSnapshot(frameId, snapshot)
59+
getSnapshot(frameId)
60+
getNearestSnapshot(frameId)
61+
getLatestSnapshot()
62+
pruneOldSnapshots()
63+
```
64+
65+
## Debug/Observability Hooks
66+
Timeline data should make it possible to show:
67+
- current predicted frame
68+
- last authoritative frame received
69+
- frame gap
70+
- number of unresolved divergence entries
71+
- whether alignment was exact or approximate
72+
73+
## Risks Controlled by This Spec
74+
- comparing incompatible frames
75+
- hiding staleness in authoritative data
76+
- memory growth from unlimited history
77+
- mixing scene runtime state directly with archived history objects
78+
79+
## Future Compatibility
80+
This model should remain compatible with later:
81+
- authoritative replay experiments
82+
- server-trace comparison tools
83+
- lag simulation demos
84+
- deterministic verification samples

‎docs/dev/reports/change_summary.txt‎

Lines changed: 17 additions & 6 deletions
Original file line numberDiff line numberDiff line change
@@ -1,9 +1,20 @@
1-
Prepared a docs-only continuation bundle for the next repo workflow step.
1+
CHANGE SUMMARY
2+
3+
Created a docs-only BUILD follow-up bundle for Level 11.2 reconciliation-layer foundation work.
24

35
Included:
4-
- PLAN/BUILD/APPLY PR docs for PR_DEBUG_SURFACES_NETWORK_SAMPLE_C_FULL
5-
- refreshed NETWORK_SAMPLES_PLAN with Sample C in progress and T/U reset to future work
6-
- big-picture roadmap patch guidance to remove broken icons
7-
- codex command, commit comment, next command, and validation/report files
6+
- BUILD PR doc for Level 11.2 reconciliation-layer foundation
7+
- Updated report artifacts (file tree, change summary, validation checklist)
8+
- Updated commit comment for this BUILD bundle
9+
10+
Guided by:
11+
- docs/dev/RECONCILIATION_LAYER_SPEC.md
12+
- docs/dev/STATE_TIMELINE_SPEC.md
13+
- docs/dev/DEBUG_SURFACE_CONTRACT.md
814

9-
No implementation code is included.
15+
Key BUILD outcomes:
16+
- preserve workflow convention (PLAN_PR -> BUILD_PR -> APPLY_PR)
17+
- keep Sample C as a consumer/proving ground, not shared implementation
18+
- normalize future interfaces around approved public selectors/events only
19+
- prefer sample-level layering with bounded history buffers
20+
- avoid engine-core, server-dashboard, docker, and transport implementation scope

‎docs/dev/reports/file_tree.txt‎

Lines changed: 10 additions & 15 deletions
Original file line numberDiff line numberDiff line change
@@ -1,15 +1,10 @@
1-
docs/
2-
dev/
3-
BIG_PICTURE_ROADMAP.md
4-
NETWORK_SAMPLES_PLAN.md
5-
codex_commands.md
6-
commit_comment.txt
7-
next_command.txt
8-
reports/
9-
change_summary.txt
10-
file_tree.txt
11-
validation_checklist.txt
12-
pr/
13-
APPLY_PR_DEBUG_SURFACES_NETWORK_SAMPLE_C_FULL.md
14-
BUILD_PR_DEBUG_SURFACES_NETWORK_SAMPLE_C_FULL.md
15-
PLAN_PR_DEBUG_SURFACES_NETWORK_SAMPLE_C_FULL.md
1+
BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION/
2+
`-- docs/
3+
|-- dev/
4+
| |-- commit_comment.txt
5+
| `-- reports/
6+
| |-- change_summary.txt
7+
| |-- file_tree.txt
8+
| `-- validation_checklist.txt
9+
`-- pr/
10+
`-- BUILD_PR_LEVEL_11_2_RECONCILIATION_LAYER_FOUNDATION.md

0 commit comments

Comments
 (0)