---
title: "Sprint 19 — Joint Briefing"
description: "Save/load IPC protocol coordination, handshake wire format, fixture file format"
type: sprint
status: archived
sprint: 19
team: "joint"
---

# 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 |