docs: specify mod storage and checkpoint APIs

docs/modding.md

@@ -140,6 +140,55 @@ default** (1x front, 2x back).
   ball-to-pic grow multiplies your scale through each stage, so a rescaled
   mon still grows into place from the ball, grounded the whole way.
 
+## Durable tool storage and runtime checkpoints
+
+`mod.save` remains the right place for state that should travel with the next
+normal Pokémon SAVE. Tools that need independently written, larger data-only
+records can use `mod.storage`; the engine scopes every logical key by game
+version, opaque playthrough identity, and mod id, and routes it through the same
+standard or portable persistence backend as saves:
+
+```lua
+local context, code, message = mod.storage:context(game)
+local ok, code, message = mod.storage:write(game, "history/quick/q0001", {
+  format = 1, createdAt = os.time(), payload = { money = 3000 },
+})
+local value, code, message = mod.storage:read(game, "history/quick/q0001")
+local keys, code, message = mod.storage:list(game, "history/quick")
+local deleted, code, message = mod.storage:delete(game, "history/quick/q0001")
+```
+
+Values must be tables containing serializable data only. Keys are conservative
+slash-separated segments (letters, digits, `_`, `-`); paths and filesystem
+handles are never exposed. Writes are staged and decode-verified, reads recover
+from a valid staged/backup generation, and methods return structured errors for
+normal data or I/O failures. The playthrough identity is allocated lazily on the
+first storage/checkpoint call, so an unused API changes no save bytes.
+
+`mod.checkpoints` captures and reconstructs engine-owned semantic runtime state:
+
+```lua
+local capability = mod.checkpoints:inspect(game)
+if capability.canCapture then
+  local checkpoint, code, message = mod.checkpoints:capture(game)
+  -- Store the detached data-only checkpoint through mod.storage.
+end
+
+local ok, code, message = mod.checkpoints:restore(game, checkpoint)
+```
+
+Checkpoint format 1 supports settled overworld control only: the overworld must
+be topmost, the player stationary on a tile, and no transition, menu, script,
+queued script movement, or partial field animation may be active. Refusals carry
+a stable `reason` and readable `message`. Capture excludes global options and
+runtime objects. Restore validates format, game/playthrough identity, content,
+and coordinates before mutation; preserves current options; suppresses normal
+map-entry/save-load side effects; verifies a recapture; and rolls back in memory
+if reconstruction fails. Callers that need crash recovery should durably capture
+their own recovery checkpoint before restore.
+
+See RFC 0003 and RFC 0004 for exact contracts and error codes.
+
 ## Developer console
 
 Boot with developer mode on to unlock the in-game console and hot-reload

docs/rfcs/0003-playthrough-storage.md

@@ -0,0 +1,123 @@
+# RFC 0003 — Playthrough-scoped mod storage
+
+## Status
+
+Proposed. Engine: `SaveData.lua`, `SaveSerializer.lua`, `Storage.lua`,
+`Loader.lua`. Tests: `playthrough_identity.lua`, `storage.lua`, the existing
+save-slot and mod-save suites.
+
+## Motivation
+
+`mod.save` intentionally lives inside the normal progress record. That is the
+right home for quest state, but not for independent tool data such as replay
+captures, checkpoint histories, or recovery records: writing it would require a
+normal Pokémon SAVE, and storing copies of progress beneath `save.modData` would
+recursively embed the save that contains them.
+
+Mods also cannot safely infer which launcher slot or portable filesystem backs
+the active playthrough. Direct filesystem access would expose private paths and
+make isolation dependent on engine implementation details.
+
+## The decision it extends
+
+Extends the per-mod persistence contract documented in `docs/modding.md` and the
+wiki's Save Model. `mod.save` and `mod.options` keep their existing behavior.
+
+## The exact API delta
+
+Backward-compatible, additive-only. `Loader:_api` binds a new `mod.storage`
+facade to the calling mod id. Mods receive logical keys and decoded values, never
+filesystem handles or physical paths.
+
+### Lazy opaque playthrough identity
+
+`SaveData.ensurePlaythroughId(save[, fs]) -> id | nil` allocates an opaque
+32-hex-character identity without consuming gameplay RNG. It is called only when
+`mod.storage` or `mod.checkpoints` first needs a scope; New Game, ordinary SAVE,
+and ordinary load remain byte-compatible when no caller uses either API.
+
+The id is stored in `save.meta.playthroughId` after allocation. Until the next
+ordinary SAVE writes it into progress, a mapping in `options.lua` keeps legacy
+saves stable by game version and active launcher slot (or the legacy flat-save
+scope). A newly created playthrough never adopts the previous playthrough's
+mapping for that slot.
+
+`SaveData.persistenceFs([fs])` is engine-only routing used by the storage
+implementation. It follows the same standard/portable backend as progress and
+honors injected test filesystems; it is not exposed on the mod object.
+
+### `mod.storage:context(game)`
+
+Returns:
+
+```lua
+{ gameVersion = "red", playthroughId = "..." }
+```
+
+or `nil, code, message`. It intentionally omits launcher slot ids and paths.
+
+### `mod.storage:write(game, key, value)`
+
+Accepts a data-only table and returns `true`, or
+`false, code, message`. Keys are nonempty slash-separated segments containing
+letters, digits, underscore, or dash. Empty segments, leading/trailing slash,
+`.`/`..`, and other characters are rejected.
+
+The engine encodes deterministically, stages and decodes a `.tmp` witness,
+preserves the previous valid generation, writes and decodes the main record,
+then rolls the verified bytes to `.bak`. A failed stage or replacement leaves a
+verified prior generation readable.
+
+### `mod.storage:read(game, key)`
+
+Returns a freshly decoded table, or `nil, code, message`. It tries main, staged,
+then backup data. A valid staged/backup value is returned and promoted
+best-effort; corrupt bytes are never executed.
+
+### `mod.storage:list(game[, prefix])`
+
+Returns sorted logical keys beneath a valid prefix, an exact key when the prefix
+names one, or `nil, code, message`. Physical witness filenames are hidden.
+
+### `mod.storage:delete(game, key)`
+
+Deletes only that key's main, backup, and staged witnesses. Returns `true`, or
+`false, code, message`.
+
+### Scope and errors
+
+Physical records are scoped as:
+
+`persistence root / mod_storage / game version / playthrough id / mod id`
+
+Stable error codes are `not_in_playthrough`, `storage_unavailable`,
+`invalid_key`, `encode_failed`, `write_failed`, `verify_failed`, and
+`not_found`. Ordinary data and I/O failures are return values, not callback-
+terminating errors.
+
+The restricted serializer's recursive writer runs outside LuaJIT traces. A
+1,000-process GC stress regression found compiled recursion could intermittently
+drop a newly inserted nested identity entry and produce undecodable bytes; save
+encoding is infrequent and I/O-bound, so interpreter execution is the safe
+boundary.
+
+## Migration note for existing mods
+
+**Nothing.** No API is removed, no manifest field changes, and no storage path or
+playthrough id is created unless a mod invokes `mod.storage` or
+`mod.checkpoints`. Existing save bytes remain unchanged on the no-caller path.
+
+## Parity tests
+
+- **No-mod:** New Game plus ordinary save/load creates no identity or storage
+  file; the existing save-slot and mod-save suites remain green.
+- **Engine identity:** lazy allocation, save/load preservation, stable legacy
+  mapping, fresh-playthrough replacement, and version/slot isolation.
+- **Public Mod API:** two real API-2 entry chunks prove data-only roundtrip,
+  deterministic listing, key rejection, mod/game/playthrough isolation,
+  corrupt-main recovery, failure retention, exact delete, and no-mod no-write.
+
+## Deprecation etiquette
+
+Nothing deprecated. The additions are one bound public facade and engine-private
+persistence/identity helpers.

docs/rfcs/0004-runtime-checkpoints.md

@@ -0,0 +1,124 @@
+# RFC 0004 — Stable runtime checkpoints for mods
+
+## Status
+
+Proposed. Engine: `Checkpoint.lua`, `Game.lua`, `OverworldController.lua`,
+`Loader.lua`. Tests: `checkpoints.lua`, existing world and engine suites.
+
+## Motivation
+
+Mods can observe world events and request semantic actions, but no supported API
+can capture canonical progress at a proven-safe runtime boundary or reconstruct
+the overworld without replaying map-entry scripts. Reaching into the state stack,
+controller, ScriptRunner, or save restore internals would bind distributable mods
+to private objects and can duplicate story side effects.
+
+The engine is the only component that can authoritatively decide whether the
+runtime is settled and rebuild its controller objects. A generic checkpoint seam
+lets tools store data-only records while keeping those responsibilities private.
+
+## The decision it extends
+
+Extends the public world/tool surfaces in `docs/modding.md`. It does not change
+`mod.world`, normal CONTINUE, vanilla SAVE, or save lifecycle hooks/events.
+
+## The exact API delta
+
+Backward-compatible, additive-only. `Loader:_api` binds `mod.checkpoints`; mods
+never receive `Game`, StateStack, controller, coroutine, renderer, or filesystem
+internals inside a checkpoint.
+
+### `mod.checkpoints:inspect(game)`
+
+Returns a capability record. Stable overworld control returns:
+
+```lua
+{ canCapture = true, canRestore = true, kind = "overworld" }
+```
+
+A refusal returns the same booleans as `false` plus `kind`, `reason`, and a
+player-readable `message`. Format-1 supports only an overworld whose controller
+is topmost, player movement has settled on a tile, and no transition, foreground
+or parallel ScriptRunner, queued script, scripted move, engagement, emote,
+teleport, field animation, or similar partial controller mutation is active.
+
+Refusal reasons are `not_in_playthrough`, `not_overworld`, `screen_busy`,
+`transition_busy`, `script_busy`, `animation_busy`, and `movement_busy`.
+Identity allocation is lazy and happens only after an active topmost overworld
+has been established.
+
+### `mod.checkpoints:capture(game)`
+
+Returns a detached data-only format-1 checkpoint, or
+`nil, code, message`:
+
+```lua
+{
+  format = 1,
+  kind = "overworld",
+  identity = { gameVersion = "red", playthroughId = "..." },
+  save = { -- canonical dynamic progress, excluding global options },
+  runtime = { overworld = {
+    map = "PALLET_TOWN", x = 5, y = 6,
+    facing = "down", surfing = false,
+  } },
+}
+```
+
+Capture deep-copies through the restricted serializer before and after
+`OverworldController:captureSave` synchronizes live map, tile, facing, and surf
+state. It excludes `save.options`, functions, userdata, threads, metatables as
+behavior, controller instances, and static content registries. Failure code
+`capture_failed` covers non-data progress and synchronization errors.
+
+### `mod.checkpoints:restore(game, checkpoint)`
+
+Returns `true`, or `false, code, message`. Before mutation it requires the current
+runtime to be capturable and validates a detached copy of the complete record:
+format, kind, internal identity consistency, current game/playthrough identity,
+map availability, integral in-bounds tile, facing, surfing, and synchronized save
+position.
+
+Validation codes are `invalid_checkpoint`, `unsupported_format`,
+`unsupported_runtime_kind`, `wrong_game`, `wrong_playthrough`, `invalid_map`, and
+`invalid_position`, in addition to the capability refusal reasons.
+
+The engine captures an in-memory rollback checkpoint, preserves current global
+options, then reconstructs semantic overworld state through
+`Game:restoreCheckpointSave`. Checkpoint entry suppresses normal map exit/entry
+events, `onEnter` scripts, forced-movement/current checks, and last-map rewrites;
+it does not emit normal `save.loading`/`save.loaded` lifecycle events. After
+reconstruction, the engine recaptures and byte-compares normalized data. A failed
+apply rolls back and returns `restore_failed`; failure of that rollback returns
+`rollback_failed`.
+
+Durable recovery remains a caller responsibility: in-memory rollback handles a
+runtime exception, not process termination.
+
+## Runtime boundary and future kinds
+
+Format 1 intentionally rejects battles, menus, transitions, animations, and
+suspended/queued scripts. Future battle or explicit script-checkpoint kinds must
+have separate inventories, validation, reconstruction, deterministic RNG, and
+differential tests; they are not implied by this RFC.
+
+## Migration note for existing mods
+
+**Nothing.** No existing hook, event, save, controller, or world action changes
+when `mod.checkpoints` is unused. The reconstruction path is called only by a
+successful public restore after validation.
+
+## Parity tests
+
+- **No-mod:** the complete ROM-free engine suite and existing world behavior stay
+  green; ordinary New Game/save/load allocates no checkpoint identity.
+- **Public Mod API:** a real API-2 entry chunk proves stable inspection and every
+  unsafe refusal, detached data-only capture, exact map/tile/facing/surf sync,
+  `A -> mutate B -> restore A -> recapture A2` equality across representative
+  progress, settings preservation, compatibility rejection without mutation,
+  map-side-effect suppression, and injected reconstruction rollback.
+
+## Deprecation etiquette
+
+Nothing deprecated. This adds one public facade and a checkpoint-only semantic
+reconstruction route.