docs(sprints): add Sprint 19: Persist briefings
Server (7), client (5), CI (4) briefings plus joint integration plan. Save/load with D-085 per-game dirs, tier eviction/scope, test infra. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
This commit is contained in:
Claude Opus 4.6
@@ -0,0 +1,97 @@
|
||||
# Sprint 19: Persist — Joint Briefing
|
||||
|
||||
**Goal:** The player can save and resume a game session with per-game directories; the simulation tier system gains eviction and scope pinning; and the first test infrastructure ships with information boundary validation and IPC hardening.
|
||||
|
||||
**Sprint:** 19
|
||||
**Status:** planning → active
|
||||
|
||||
## Pre-Sprint
|
||||
|
||||
Before implementation begins, no schema work is needed — `SaveStateV1` is already defined (#256, done). However, the following IPC protocol additions must be agreed between server and client **before either side implements**:
|
||||
|
||||
| Item | Owner | Needed by |
|
||||
|------|-------|-----------|
|
||||
| `HandshakeMessage` wire format | server (#555) | client (#556) |
|
||||
| `SaveCommand` / `LoadCommand` IPC message variants | server (#553) | client (#554) |
|
||||
| `SaveComplete` / `LoadComplete` response format | server (#553) | client (#554) |
|
||||
| Fixture file format and field names | ci (#271) | all teams |
|
||||
|
||||
Server team: define these in `server/src/bridge/types.rs` first (as Rust structs + serde). CI team + client team: implement against the published definitions. Do not start #556 or #554 until #555 and #553 respectively reach review.
|
||||
|
||||
## Team Allocation
|
||||
|
||||
| Team | Tickets | Count |
|
||||
|------|---------|-------|
|
||||
| server | #553, #96, #97, #98, #200, #272, #555 | 7 |
|
||||
| client | #554, #258, #205, #206, #348 | 5 |
|
||||
| ci | #270, #556, #342, #271 | 4 |
|
||||
|
||||
## Cross-Team Dependencies
|
||||
|
||||
```
|
||||
server #555 (handshake: server)
|
||||
→ ci #556 (handshake: client)
|
||||
→ ci #342 (IPC benchmark)
|
||||
|
||||
server #553 (ECS extraction)
|
||||
→ client #554 (save/load UI)
|
||||
|
||||
server #200 (test module org)
|
||||
→ server #272 (info boundary tests)
|
||||
|
||||
client #205 (GDScript test framework)
|
||||
→ client #206 (scene testing utilities)
|
||||
→ ci #271 (fixture files need GDScript reader)
|
||||
|
||||
ci #270 (test runner scripts)
|
||||
→ ci #271 (fixture tests invoked by run-ipc-fixtures)
|
||||
```
|
||||
|
||||
## Sprint Completion Proof
|
||||
|
||||
When Sprint 19 is done, the following must all be observable:
|
||||
|
||||
1. **Save/load round-trip**: Press F5 in-game → file appears at `user://saves/<game-id>/quicksave.sav` in MessagePack format. Press F6 → game state restored from file (tick, entities, player knowledge match pre-save state).
|
||||
|
||||
2. **Per-game directory**: Starting a New Game creates `user://saves/<timestamp>-<seed>/` before any save occurs. The loading screen lists this directory.
|
||||
|
||||
3. **Tier eviction**: Spawn 90+ NPCs (above Active cap of 80). `ActiveSim` count stabilizes at ≤80 with the excess evicted to `BackgroundSim`/`StateSaved`. Scope-tagged NPCs (KnownContact, Colleague) remain Active regardless.
|
||||
|
||||
4. **Protocol handshake**: Starting the server subprocess: first IPC message is a `HandshakeMessage`. Version mismatch (force by temporarily changing server `PROTOCOL_VERSION`) produces an error and clean shutdown — no crash.
|
||||
|
||||
5. **Test infrastructure**: `tests/run-all` exits 0 with all suites passing. `tests/run-ipc-fixtures` reads committed `.msgpack` files and validates both Rust and GDScript decode them identically. `cargo test` in `server/` includes information boundary negative tests that assert absence of leakage.
|
||||
|
||||
6. **Debug overlay**: F3 in-game toggles the debug canvas showing vision cone arcs, entity LOS rays, NPC knowledge confidence labels, and tick timing graph.
|
||||
|
||||
## Test Plan (D-030)
|
||||
|
||||
| Layer | Runner | Tickets | When |
|
||||
|-------|--------|---------|------|
|
||||
| Layer 1: Fixture serialization | `tests/run-ipc-fixtures` | #271, #200 | Every edit |
|
||||
| Layer 1: Unit tests (Rust) | `tests/run-rust` | #272, #96, #97, #98 | Every edit |
|
||||
| Layer 1: Unit tests (GDScript) | `tests/run-godot` | #205, #206 | Every edit |
|
||||
| Layer 2: Mock protocol | `tests/run-ipc-protocol` | #555, #556 | Every PR |
|
||||
| Layer 3: Real subprocess | `tests/run-ipc-integration` | #342, #553/#554 | Daily/pre-merge |
|
||||
|
||||
All layers must pass before any PR merges. `make ci` invokes `tests/run-all`.
|
||||
|
||||
## Key Decisions Reference
|
||||
|
||||
| Decision | Domain file | Relevant to |
|
||||
|----------|------------|-------------|
|
||||
| D-010: Determinism + info boundaries | architecture.md | #272, #96, #553 |
|
||||
| D-020: IPC architecture, MessagePack | architecture.md | #553, #554, #555, #556, #342, #271 |
|
||||
| D-026: Simulation tiers, timestamp eviction, scope tags | architecture.md | #96, #97, #98 |
|
||||
| D-030: Three-layer test architecture | architecture.md | #200, #270, #271, #272, #342 |
|
||||
| D-085: Per-game save directory structure | architecture.md | #554, #258, #553 |
|
||||
| Q-029: Save file format (open) | questions.md | #553 (quick-and-dirty MessagePack for now) |
|
||||
|
||||
## Risk Register
|
||||
|
||||
| Risk | Probability | Impact | Mitigation |
|
||||
|------|------------|--------|------------|
|
||||
| ECS extraction misses components (#553) | Medium | High | #272 info boundary tests catch leakage; fixture roundtrip (#271) catches missing fields |
|
||||
| IPC protocol mismatch between #555 and #556 | Low | High | Define wire types in Rust first, share definition doc before client implements |
|
||||
| GUT framework incompatible with Godot 4.x version in use (#205) | Low | Medium | Verify GUT version before full installation; fallback to hand-rolled test runner |
|
||||
| Save file bloat (SaveStateV1 larger than ~1-2 KB/NPC) | Low | Low | Q-029 tracks compression — deferred. Profile with #342 benchmark if flagged |
|
||||
| Scope tag assignment races with eviction (#97/#98) | Low | Medium | Eviction runs after scope tag system in schedule order; schedule ordering test in #97 |
|
||||
Reference in New Issue
Block a user