jpmschweitzerandClaude Opus 4.6
0dd33690f7
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>
98 lines
5.3 KiB
Markdown
98 lines
5.3 KiB
Markdown
# 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 |
|