Epic: Phase 1 Save Schema and Migration Foundation

[keepithandy]

Phase

Phase 1 — Foundation

Goal

Define the first real save contract for Depth Engine so future examples, loaders, and extension points do not corrupt player state.

This issue should turn the current lightweight save repair path into a documented foundation without building a heavy migration framework too early.

Why this matters

The moment Depth Engine supports multiple examples, changing content ids, or extension hooks, saves become the easiest place to accidentally create spooky bugs. This issue keeps save behavior understandable before the engine grows teeth.

Proposed work

• Document the current save shape.
• Define required save fields versus optional/repairable fields.
• Decide how example identity should be represented in future saves.
• Clarify what happens when a save was made for a different example.
• Add smoke coverage for malformed saves and legacy floor/currentFloor fields.
• Add smoke coverage for inventory/equipment references that no longer exist in content.
• Decide whether save version should remain global or become example-aware later.
• Add a short migration policy doc for future changes.

Acceptance checks

• Save shape is documented in docs/.
• Current Rat Cellar saves still load.
• Legacy stage/floor repair behavior remains covered.
• Malformed inventory/equipment/log fields are repaired safely.
• Future example-switching risks are documented, not silently ignored.
• No breaking save reset is introduced.

Guardrails

• Do not build a full migration framework yet unless a separate implementation issue is opened.
• Do not change Rat Cellar's saveKey casually.
• Do not introduce remote storage or accounts.
• Do not make save repair content-specific inside js/engine/.

Suggested follow-up slices

• Save schema documentation only.
• Save repair smoke hardening.
• Example identity save strategy design.
• Future migration helper prototype.