shrike/save.py

Part of SHRIKE.

"""Persistence: the permanent meta profile and the one-slot suspend save.

Two files live under the player's data directory, both written through the
engine's :class:`~simvx.core.SaveManager` so they inherit its atomic write and
two-deep backup rotation:

``profile.sav``
    Everything section 9 of the design says persists: Cores and the doctrine
    tree, quills and Fletchings, Lure fragments and quill-tech blueprints,
    unlocked hulls, the Codex, module-pool expansions, Hunt Ranks, the
    milestone flags that drive the first five runs, and a personal best score
    per hull. Written whenever a run ends and whenever the tree is respent.

``suspend.sav``
    One slot, holding a full mid-sector run state. Written when the player
    quits mid-run and **deleted the moment it is read**, so it catches the run
    that outgrew the lunch break without ever becoming a save-scum button. The
    delete takes the rotated backups with it: leaving ``suspend.sav.bak`` on
    disk would hand back the very undo the single slot exists to deny.

Both payloads are plain dictionaries carried on one :class:`SaveRecord`
Property, not a snapshot of the live scene tree. Runs are permadeath and a
sector is regenerated from its seed, so what has to survive a quit is a small,
explicit state description rather than a serialised world.

Versioning
==========

There are two independent version numbers and they answer different questions.
``SaveRecord.__save_version__`` versions the *envelope* (one node, one dict
Property) and is expected never to move. ``payload["schema_version"]`` versions
the *game* schema below, and is the one that changes as the game grows.
:data:`PROFILE_MIGRATIONS` and :data:`SUSPEND_MIGRATIONS` map a version to the
function that lifts a payload one step forward; loading walks the chain until
the payload is current, and refuses a payload from a newer build outright.

Missing keys are filled from the current defaults on every load, so a migration
is only needed when a key is *renamed* or its meaning changes, never when one
is added.

Profile schema (version 1)
==========================

.. code-block:: text

    schema_version: int
    cores:          int                      Cores banked, the meta currency
    doctrine:       owned: [node_id]         bought doctrine nodes
                    active_keystones: [id]   at most balance.DOCTRINE_MAX_ACTIVE_KEYSTONES
    quills:         int                      sheared from the hide or forged
    fletchings:     int                      balance.FLETCHINGS_PER_QUILL forge one quill
    runs_since_last_quill: int               drives the herald drop-rate ramp
    lure:           fragments: {biome: int}  log-fragment caches, per biome type
                    assembled: bool
    quill_tech:     [blueprint_id]           mirror-lantern, quill-tipped rounds
    hulls:          unlocked: [hull_id]      feat-gated trophies
                    selected: hull_id
    hunt_rank:      int                      one ascension tier per Roost kill
    roost:          phases_defeated: int     phases stay defeated across attempts
                    attempts: int
    codex:          log_fragments / signal_events / enemies / biomes: [id]
                    "enemies" is also onboarding's first-sighting record, one
                    entry per archetype this profile has ever been shown
    lessons:        {lesson_id: bool}        onboarding's once-per-profile cards
    module_pool:    purchased_rares: [id]    first purchase of a rare module...
                    expansions: [id]         ...adds its sibling to the world pool
    milestones:     {milestone_id: bool}     the first-five-runs bounty flags
    kit:            kit_id                   the Doctrine Kit this profile took
                                             at its first dock; "" until then
    best_scores:    {hull_id: int}           per-hull personal bests
    runs_started:   int
    runs_extracted: int

Suspend schema (version 1)
==========================

Nine sections, each a dictionary; :func:`blank_suspend` returns the template
that ``flow.py`` fills in. ``run`` carries the run identity and the sector seed,
``ship`` the hull, plane state and fittings (weapons by hardpoint with their
magazines, the ammo locker, modules by socket, and any stowed weapons, so a
mid-run purchase survives the quit), ``resources`` the four survival meters
plus carried scrap, ``signature`` / ``notoriety`` / ``hunter`` the three
pressure gauges and the arrival ladder's position, ``sector`` the per-object
harvest progress that a seed cannot reproduce, ``chart`` the route and the Wake
front, and ``ledger`` the run tally the death and extraction screens read.
"""

from __future__ import annotations

import logging
import os
from collections.abc import Callable
from copy import deepcopy
from datetime import UTC, datetime
from pathlib import Path

from simvx.core import Node, Property, SaveManager, Signal

from . import balance

log = logging.getLogger(__name__)

# ============================================================================
# Slots, versions and defaults
# ============================================================================

#: Slot names, which become ``<slot>.sav`` inside :func:`data_dir`.
PROFILE_SLOT = "profile"
SUSPEND_SLOT = "suspend"

#: Game-schema versions, stored as ``payload["schema_version"]``.
PROFILE_SCHEMA_VERSION = 1
SUSPEND_SCHEMA_VERSION = 1

#: The starter hull, unlocked from the first boot. The other three in
#: ``balance.HULL_SOCKETS`` are feat-gated trophies.
STARTER_HULL = "vagrant"

#: Milestone ids paired with their Core bounty. The ids are named here because
#: balance.py prices the bounties without naming them; flow.py reads this map
#: to pay a milestone the first time its flag flips.
MILESTONE_CORES: dict[str, int] = {
    "first_extraction": balance.MILESTONE_FIRST_EXTRACTION,
    "first_vault": balance.MILESTONE_FIRST_VAULT,
    "first_elite_kill": balance.MILESTONE_FIRST_ELITE_KILL,
    "first_act3_entry": balance.MILESTONE_FIRST_ACT3_ENTRY,
    "first_arrival_survived": balance.MILESTONE_FIRST_ARRIVAL_SURVIVED,
}

#: Codex categories, one list of seen ids each.
CODEX_CATEGORIES = ("log_fragments", "signal_events", "enemies", "biomes")

#: The suspend save's top-level sections. Every one must be present in a
#: run state handed to :meth:`SaveSystem.write_suspend`.
SUSPEND_SECTIONS = (
    "run",
    "ship",
    "resources",
    "signature",
    "notoriety",
    "hunter",
    "sector",
    "chart",
    "ledger",
)


class SaveError(RuntimeError):
    """Base class for every failure this module raises."""


class SaveSchemaError(SaveError):
    """A payload's ``schema_version`` cannot be brought to the current one."""


class ProfileLoadError(SaveError):
    """The profile exists but could not be read.

    Raised rather than swallowed: silently handing back a fresh profile would
    erase a player's whole progression at boot. The rotated ``.bak`` and
    ``.bak2`` files beside it are the manual recovery path, and the message
    names them.
    """


def default_profile() -> dict:
    """A fresh meta profile: nothing unlocked, nothing banked."""
    return {
        "schema_version": PROFILE_SCHEMA_VERSION,
        "cores": 0,
        "doctrine": {"owned": [], "active_keystones": []},
        "quills": 0,
        "fletchings": 0,
        "runs_since_last_quill": 0,
        "lure": {"fragments": {}, "assembled": False},
        "quill_tech": [],
        "hulls": {"unlocked": [STARTER_HULL], "selected": STARTER_HULL},
        "hunt_rank": 0,
        "roost": {"phases_defeated": 0, "attempts": 0},
        "codex": {category: [] for category in CODEX_CATEGORIES},
        "lessons": {},
        "module_pool": {"purchased_rares": [], "expansions": []},
        "milestones": dict.fromkeys(MILESTONE_CORES, False),
        "kit": "",
        "best_scores": {},
        "runs_started": 0,
        "runs_extracted": 0,
    }


def blank_suspend() -> dict:
    """The suspend template, with every section present and empty.

    ``flow.py`` starts from this and fills it, so a section added here reaches
    every writer without touching the writer.
    """
    return {
        "schema_version": SUSPEND_SCHEMA_VERSION,
        "saved_at": "",
        "run": {
            "run_number": 0,
            "seed": 0,
            "elapsed_s": 0.0,
            "kit": "",
            "keystones": [],
            "assists": {},
            "sector_index": 0,
            "sector_seed": 0,
            "biome_id": "",
        },
        "ship": {
            "hull_id": STARTER_HULL,
            "hull": balance.HULL_MAX_STARTER,
            "hull_max": balance.HULL_MAX_STARTER,
            "open_breaches": 0,
            "position": [0.0, 0.0],
            "velocity": [0.0, 0.0],
            "heading": 0.0,
            "shield_arc_centre": 0.0,
            "shield_charge": 0.0,
            # The fittings: what is bolted where, with the magazines as they
            # stood. Empty lists mean "keep the rebuilt starter fit", which is
            # also what a payload written before these were captured says.
            "weapons": [],
            "ammo_boxes": {},
            "modules": [],
            "stowed_weapons": [],
        },
        "resources": {
            "capacitor": 0.0,
            "capacitor_max": 0.0,
            "fuel": 0.0,
            "o2": 0.0,
            "scrap": 0.0,
            "cores_banked_this_run": 0.0,
        },
        "signature": {"value": 0.0, "act": 1, "silent_running": False},
        "notoriety": {"value": 0},
        "hunter": {
            "arrivals_this_run": 0,
            "state": "absent",
            "telegraph_stage": "",
            "seconds_to_arrival": 0.0,
            "quills_this_run": 0,
        },
        "sector": {"deposits": [], "wrecks": [], "vaults": [], "hazards": [], "seen_events": [], "event_draws": 0},
        "chart": {
            "seed": 0,
            "current_node": "",
            "visited": [],
            "wake_column": 0,
            "jumps_taken": 0,
        },
        "ledger": {"scrap_earned": 0.0, "kills": 0, "milestones": [], "deepest_sector": 0},
    }


# ============================================================================
# Migrations
# ============================================================================

#: ``{from_version: upgrade}``. Each entry lifts a payload exactly one version;
#: the loader walks the chain. Adding a key needs no entry, because loading
#: fills unknown keys from the current defaults. Renaming one does.
PROFILE_MIGRATIONS: dict[int, Callable[[dict], dict]] = {}

#: The same, for the suspend slot. A suspend save that cannot be migrated is
#: discarded rather than surfaced: it is a convenience, not a progression.
SUSPEND_MIGRATIONS: dict[int, Callable[[dict], dict]] = {}


def _migrate(payload: dict, migrations: dict[int, Callable[[dict], dict]], current: int, label: str) -> dict:
    """Walk *payload* up the migration chain until it reaches *current*."""
    version = payload.get("schema_version")
    if not isinstance(version, int):
        raise SaveSchemaError(f"{label} has no integer 'schema_version' (got {version!r})")
    if version > current:
        raise SaveSchemaError(
            f"{label} is at schema version {version} but this build only understands up to "
            f"{current}; it was written by a newer version of the game"
        )
    while version < current:
        step = migrations.get(version)
        if step is None:
            raise SaveSchemaError(
                f"{label} is at schema version {version} and no migration to {version + 1} is registered"
            )
        payload = step(payload)
        if not isinstance(payload, dict):
            raise SaveSchemaError(f"{label} migration from version {version} returned {type(payload).__name__}")
        version += 1
        payload["schema_version"] = version
    return payload


def _fill_defaults(payload: dict, template: dict) -> dict:
    """Return *payload* with every key missing against *template* filled in.

    Recurses into nested dictionaries whose template is itself non-empty, which
    leaves open-keyed maps (``best_scores``, ``lure.fragments``, per-hull and
    per-biome tallies) untouched. Unknown keys are kept: a profile written by a
    newer build and read back by an older one loses nothing it was not asked
    about.
    """
    result = dict(payload)
    for key, default in template.items():
        if key not in result:
            result[key] = deepcopy(default)
        elif isinstance(default, dict) and default and isinstance(result[key], dict):
            result[key] = _fill_defaults(result[key], default)
    return result


def migrate_profile(payload: dict) -> dict:
    """Bring a stored profile to :data:`PROFILE_SCHEMA_VERSION`."""
    return _fill_defaults(_migrate(payload, PROFILE_MIGRATIONS, PROFILE_SCHEMA_VERSION, "Profile"), default_profile())


def migrate_suspend(payload: dict) -> dict:
    """Bring a stored suspend save to :data:`SUSPEND_SCHEMA_VERSION`."""
    migrated = _migrate(payload, SUSPEND_MIGRATIONS, SUSPEND_SCHEMA_VERSION, "Suspend save")
    return _fill_defaults(migrated, blank_suspend())


# ============================================================================
# Where the files live
# ============================================================================


def data_dir() -> Path:
    """The directory the two save files live in.

    ``SHRIKE_DATA_DIR`` wins outright when set, which is what tests and
    portable installs use. Otherwise the XDG data directory applies, falling
    back to ``~/.local/share`` when ``XDG_DATA_HOME`` is unset or, as the
    specification requires, not absolute. Nothing is ever written into the game
    directory.
    """
    override = os.environ.get("SHRIKE_DATA_DIR")
    if override:
        return Path(override).expanduser()
    xdg = os.environ.get("XDG_DATA_HOME")
    base = Path(xdg) if xdg and Path(xdg).is_absolute() else Path.home() / ".local" / "share"
    return base / "simvx" / "shrike"


# ============================================================================
# The record node and the save system
# ============================================================================

#: The record node's name. It is part of the on-disk format: SaveManager stores
#: node paths, so renaming this invalidates existing files.
RECORD_NAME = "ShrikeSave"


class SaveRecord(Node):
    """Carrier for one save payload.

    A detached, single-node tree whose only persisted Property is the payload
    dictionary. Keeping it out of the scene means its stored path is always
    ``/ShrikeSave``, independent of where the :class:`SaveSystem` singleton
    happens to sit.
    """

    __save_version__ = 1

    payload = Property(default_factory=dict, persist=True, save_version=1)


class SaveSystem(Node):
    """The game's only door to disk, added as the ``Services.SAVE`` singleton.

    Both slots round-trip plain dictionaries. The profile is the permanent
    progression; the suspend save is a single mid-run snapshot that
    :meth:`take_suspend` consumes.
    """

    profile_loaded = Signal(dict)  # SignalNames.PROFILE_LOADED
    profile_saved = Signal()  # SignalNames.PROFILE_SAVED

    # -- locations --------------------------------------------------------

    def data_dir(self) -> Path:
        """The save directory, resolved fresh so an env change is honoured."""
        return data_dir()

    def profile_path(self) -> Path:
        """Where the meta profile is written."""
        return self.data_dir() / f"{PROFILE_SLOT}.sav"

    def suspend_path(self) -> Path:
        """Where the suspend save is written."""
        return self.data_dir() / f"{SUSPEND_SLOT}.sav"

    def _manager(self) -> SaveManager:
        return SaveManager(self.data_dir())

    # -- the meta profile -------------------------------------------------

    def load_profile(self) -> dict:
        """Read the profile, migrating it forward; a fresh one if none exists.

        Emits ``PROFILE_LOADED`` with the profile either way, so the first boot
        and every later one take the same path through meta.py.
        """
        path = self.profile_path()
        if not path.exists():
            profile = default_profile()
            self.profile_loaded.emit(profile)
            return profile

        try:
            payload = self._read(PROFILE_SLOT)
        except SaveError:
            raise
        except Exception as exc:
            raise ProfileLoadError(
                f"Could not read the profile at {path}: {exc}. The previous two writes are "
                f"beside it as {path.name}.bak and {path.name}.bak2; rename one over it to recover."
            ) from exc

        profile = migrate_profile(payload)
        self.profile_loaded.emit(profile)
        return profile

    def save_profile(self, profile: dict) -> None:
        """Write *profile* atomically and emit ``PROFILE_SAVED``.

        The payload is deep-copied, so the caller may keep mutating its own
        dictionary without disturbing what landed on disk.
        """
        if not isinstance(profile, dict):
            raise TypeError(f"save_profile expects a dict, got {type(profile).__name__}")
        payload = deepcopy(profile)
        payload["schema_version"] = PROFILE_SCHEMA_VERSION
        self._write(PROFILE_SLOT, payload)
        self.profile_saved.emit()

    # -- the suspend slot -------------------------------------------------

    def has_suspend(self) -> bool:
        """Whether a suspended run is waiting to be resumed."""
        return self.suspend_path().exists()

    def write_suspend(self, run_state: dict) -> None:
        """Capture a mid-sector run, replacing whatever the one slot held.

        Every section in :data:`SUSPEND_SECTIONS` must be present and a
        dictionary; keys missing inside a section are filled from
        :func:`blank_suspend`. A half-described run is a resume that silently
        loses the player's fuel or their vault progress, so it raises here
        instead.
        """
        if not isinstance(run_state, dict):
            raise TypeError(f"write_suspend expects a dict, got {type(run_state).__name__}")
        missing = [name for name in SUSPEND_SECTIONS if not isinstance(run_state.get(name), dict)]
        if missing:
            raise ValueError(f"Run state is missing the section(s) {', '.join(missing)}; start from blank_suspend()")

        payload = _fill_defaults(deepcopy(run_state), blank_suspend())
        payload["schema_version"] = SUSPEND_SCHEMA_VERSION
        payload["saved_at"] = datetime.now(UTC).isoformat()
        self._write(SUSPEND_SLOT, payload)

    def take_suspend(self) -> dict | None:
        """Consume the suspended run, or ``None`` when there is none.

        The slot and its rotated backups are deleted before the state is
        returned, so a resumed run can never be replayed from the same save.
        A slot that cannot be read is discarded the same way: it is a
        convenience, and refusing to boot over it would be a worse trade than
        losing it.
        """
        if not self.suspend_path().exists():
            return None
        try:
            payload = self._read(SUSPEND_SLOT)
            run_state = migrate_suspend(payload)
        except Exception as exc:
            log.warning("Discarding unreadable suspend save at %s: %s", self.suspend_path(), exc)
            self.clear_suspend()
            return None
        self.clear_suspend()
        return run_state

    def clear_suspend(self) -> None:
        """Delete the suspend slot and both rotated backups."""
        path = self.suspend_path()
        for candidate in (path, path.with_name(path.name + ".bak"), path.with_name(path.name + ".bak2")):
            try:
                candidate.unlink()
            except FileNotFoundError:
                pass

    # -- SaveManager plumbing ---------------------------------------------

    def _write(self, slot: str, payload: dict) -> Path:
        record = SaveRecord(name=RECORD_NAME)
        record.payload = payload
        return self._manager().save(record, slot)

    def _read(self, slot: str) -> dict:
        record = SaveRecord(name=RECORD_NAME)
        self._manager().apply(record, self._manager().load(slot))
        payload = record.payload
        if not isinstance(payload, dict):
            raise SaveError(f"Slot {slot!r} holds a {type(payload).__name__}, expected a dict")
        return payload


def stored_settings() -> dict:
    """The profile's settings block, read before there is a tree to read it in.

    One caller: the window options the App is constructed with cannot wait for
    the run to load the profile through the tree, because they are fixed before
    the loop starts. Nothing is written here and nothing is migrated beyond
    what :meth:`SaveSystem.load_profile` already does.

    A profile that will not load answers with the defaults rather than raising.
    The load ``flow.py`` runs a moment later hits the same file and reports it
    properly, with the screen up to say it on; failing here would replace that
    message with a traceback and no window.
    """
    try:
        settings = SaveSystem().load_profile().get("settings")
    except Exception:
        return {}
    return dict(settings) if isinstance(settings, dict) else {}