# OpenSpec Change: enterprise-gaming-game-persistence

- **Change ID**: enterprise-gaming-game-persistence
- **Package**: `@suaveplan/game-persistence`
- **Category**: gaming/engine
- **Target path**: `gaming/engine/game-persistence`
- **Status**: PROPOSED
- **Date**: 2026-04-24
- **Reference spec**: `/mnt/s/web/suaveplan/enterprise/game-persistence.md`

---

## Summary

Deliver `@suaveplan/game-persistence` on the genesis branch from scratch at enterprise quality. The package provides save/load game state with versioned migrations — a universal persistence substrate for both client-side saves and server-side session snapshots. A `SaveManager` holds named slots per player, auto-increments version on re-save, enforces configurable slot-count and size limits, and fires `@suaveplan/events` lifecycle events. A `MigrationRunner` upgrades older saves through a registered migration chain. Genesis adds Zod schemas, `@suaveplan/serialize` for binary/JSON round-trips, OTel instrumentation, structured errors, and full 100% coverage.

---

## Current-state audit (genesis)

Package does not exist on genesis yet — fresh build.

---

## Available workspace deps on genesis

| Package | Role |
|---|---|
| `@suaveplan/error` (`workspace:^`) | `GamePersistenceError`; `SAVE.*` error codes |
| `@suaveplan/types` (`workspace:^`) | `StorageLike`, `Clock` |
| `@suaveplan/events` (`workspace:^`) | Save lifecycle events |
| `@suaveplan/serialize` (`workspace:^`) | Tagged JSON + MessagePack round-trip for save data |
| `zod` (`catalog:forms`) | `SaveSlot`, `MigrationConfig` schemas |
| `@opentelemetry/api` (`catalog:observability`) | Save/load span instrumentation |

---

## Public API surface

```ts
function createSaveManager(options: SaveManagerOptions): SaveManager

interface SaveManagerOptions {
  maxSlotsPerPlayer?: number     // default 10
  maxSizeBytes?: number          // default 1MB per slot
  autosaveSlot?: string          // default 'autosave'
  storage?: StorageLike          // pluggable; default: in-memory Map
  clock?: Clock
  migrations?: Migration[]
}

interface SaveManager {
  save(playerId: string, slotId: string, data: unknown): Promise<SaveSlot>
  load(playerId: string, slotId: string): Promise<SaveSlot>
  delete(playerId: string, slotId: string): Promise<void>
  listSlots(playerId: string): Promise<SaveSlot[]>
  autosave(playerId: string, data: unknown): Promise<SaveSlot>
  hasSlot(playerId: string, slotId: string): Promise<boolean>
}

interface SaveSlot {
  id: string
  playerId: string
  version: number
  createdAt: number
  updatedAt: number
  sizeBytes: number
  data: unknown
}

// Migration
interface Migration {
  fromVersion: number
  toVersion: number
  migrate(data: unknown): unknown
}

function createMigrationRunner(migrations: Migration[]): MigrationRunner

interface MigrationRunner {
  run(data: unknown, fromVersion: number, toVersion: number): unknown
  canMigrate(fromVersion: number, toVersion: number): boolean
}
```

### Error codes

```ts
type SaveErrorCode =
  | 'SAVE_SLOT_NOT_FOUND'
  | 'SAVE_SLOT_LIMIT_EXCEEDED'
  | 'SAVE_SIZE_EXCEEDED'
  | 'SAVE_MIGRATION_FAILED'
  | 'SAVE_SERIALIZATION_FAILED'
  | 'SAVE_STORAGE_ERROR'
```

---

## New additions for genesis

1. **Binary serialization** — `@suaveplan/serialize` MessagePack profile for compact save blobs; JSON fallback.
2. **Migration chain validation** — `MigrationRunner` validates no gaps or cycles in version sequence at construction time.
3. **OTel** — `save.write_duration_ms` and `save.read_duration_ms` histograms; `save.slot_count` gauge.
4. **Events** — `save:created`, `save:updated`, `save:loaded`, `save:deleted`, `save:autosave`, `save:migration_applied`.

---

## File layout

```text
gaming/engine/game-persistence/
  package.json
  tsconfig.json
  vitest.config.ts
  src/
    index.ts
    error-codes.ts
    constants/index.ts
    types/common.ts
    types/common.md
    core/
      save-manager/
        save-manager.ts
        save-manager.md
        save-manager.types.ts
        save-manager.test.ts
        index.ts
      migration-runner/
        migration-runner.ts
        migration-runner.md
        migration-runner.types.ts
        migration-runner.test.ts
        index.ts
  tests/
    integration.test.ts
```

---

## Impact

**Downstream**: `@suaveplan/api-plugin-game-persistence` wraps this in HTTP routes. Prerequisites: `@suaveplan/error`, `@suaveplan/types`, `@suaveplan/events`, `@suaveplan/serialize`.