@rpgm-tools/neo-angband-core 0.10.0

package/dist/session/save.d.ts

@@ -0,0 +1,847 @@
+/**
+ * JSON save/load (PORT_PLAN.md decision 9): the entity serializers that
+ * turn a live GameState into plain JSON and back. The format is the port's
+ * own (the C binary blocks of save.c/load.c are replaced by design); WHAT
+ * is saved follows upstream savefile semantics - notably the RNG state is
+ * persisted (save.c wr_randomizer), which is what the no-save-scum posture
+ * rides on (decisions 16/22): reloading resumes the same stream.
+ *
+ * References into bound registries (races, kinds, egos, artifacts, trap
+ * kinds, classes) are saved as stable indices/names and re-resolved against
+ * the pack on load, so a save is data + pack, never code. Raw effect chains
+ * and kind-owned text re-point at the kind on load rather than being
+ * copied into the save.
+ *
+ * Integrity: serializeGame produces the JSON payload; callers stamp/verify
+ * bytes with save/integrity.ts (stampSavefile / verifyStampedSavefile),
+ * the decision-16b tamper deterrent.
+ *
+ * BLOCK MAP (save.c wr_* / load.c rd_* -> the field this file writes). There is
+ * deliberately no per-block function pair: the C block table is replaced by one
+ * JSON document, so W1's question is field coverage, not symbol presence. Each
+ * row is proved by save-fields.test.ts, the C-derived coverage guard.
+ *
+ *   wr_description   (save.c:49)   -> not a FIELD: the exact string is ported in
+ *                                    save/description.ts and derived from
+ *                                    fullName / lev / race / class / depth,
+ *                                    which this document already carries. In a
+ *                                    JSON save it need not be stored at all, and
+ *                                    storing it would create the second source
+ *                                    of truth upstream's own readers avoid by
+ *                                    scanning a directory and asking each file.
+ *   wr_randomizer    (save.c:286)  -> SavedGame.rng
+ *   wr_options       (save.c:314)  -> SavedGame.options (SIDEBAR_MODE is UI)
+ *   wr_messages      (save.c:339)  -> SavedGame.messages
+ *   wr_monster_memory(save.c:356)  -> SavedGame.lore (whole record, not just
+ *                                    pkills/thefts: the port has no lore.txt)
+ *   wr_object_memory (save.c:377)  -> flavor.aware / .tried, everseen.kinds,
+ *                                    ignore.kindAware / .kindUnaware
+ *   wr_quests        (save.c:405)  -> player.quests
+ *   wr_player        (save.c:418)  -> SavedPlayer + SavedGame.actor / arena /
+ *                                    nameSuffix / skipCmdCoercion / unignoring /
+ *                                    restingTurn
+ *   wr_ignore        (save.c:514)  -> SavedGame.ignore, .autoinscriptions,
+ *                                    everseen.egos. GAP: the rune-note block
+ *                                    (save.c:589-605) has no counterpart -
+ *                                    rune_note is a ledgered deferral.
+ *   wr_misc          (save.c:610)  -> randartSeed, seedFlavor, player.totalWinner,
+ *                                    player.noscore, isDead, turn, player.objKnown
+ *   wr_artifacts     (save.c:674)  -> artifactsCreated / Seen / Everseen
+ *   wr_player_hp     (save.c:692)  -> player.playerHp
+ *   wr_player_spells (save.c:702)  -> player.spellFlags / .spellOrder
+ *   wr_gear_aux      (save.c:715)  -> gear (+ player.equipment slot map)
+ *   wr_gear          (save.c:737)  -> ditto; the gear_k known twin is N/A
+ *   wr_stores        (save.c:744)  -> SavedGame.stores
+ *   wr_dungeon_aux   (save.c:774)  -> ChunkSquaresData (+ currentJoins)
+ *   wr_objects_aux   (save.c:873)  -> SavedGame.floor
+ *   wr_monsters_aux  (save.c:915)  -> SavedGame.monsters / .groups
+ *   wr_traps_aux     (save.c:933)  -> SavedGame.traps
+ *   wr_dungeon       (save.c:959)  -> dungeonDepth, daycount, actor.grid
+ *   wr_objects       (save.c:980)  -> floor      (player->cave twin N/A)
+ *   wr_monsters      (save.c:986)  -> monsters   (player->cave twin N/A)
+ *   wr_traps         (save.c:992)  -> traps      (player->cave twin N/A)
+ *   wr_chunks        (save.c:1001) -> levelCache + townChunk
+ *   wr_history       (save.c:1048) -> player.hist
+ *   wr_item          (save.c:69)   -> SavedObject      (obj->oidx N/A)
+ *   wr_monster       (save.c:201)  -> SavedMonster
+ *   wr_trap          (save.c:261)  -> SavedTrap
+ */
+import type { Loc } from "../loc.js";
+import type { RngState } from "../rng.js";
+import type { RandomValue } from "../rng.js";
+import { Chunk } from "../world/chunk.js";
+import type { ChunkSquaresData } from "../world/chunk.js";
+import type { GameObject } from "../obj/object.js";
+import type { ObjRegistry } from "../obj/bind.js";
+import type { ElementInfo } from "../obj/types.js";
+import type { AutoinscriptionRegistry } from "../obj/knowledge.js";
+import type { IgnoreSettingsData } from "../obj/ignore.js";
+import type { Monster, MonsterGroupInfo } from "../mon/monster.js";
+import type { MonsterLore } from "../mon/lore.js";
+import type { MonsterRegistry } from "../mon/bind.js";
+import type { Player, PlayerQuest } from "../player/player.js";
+import type { PlayerRegistry } from "../player/bind.js";
+import type { TrapKind } from "../world/trap.js";
+import type { GameState, MonsterGroup, StoredLevel } from "../game/context.js";
+import { MessageLog } from "../msg.js";
+import type { Trap } from "../game/trap.js";
+import type { Gear } from "../game/gear.js";
+import type { Store } from "../store/store.js";
+import type { BoundStore } from "../store/types.js";
+import type { KnownMap } from "../game/known.js";
+import type { SaveIntegrity } from "../save/integrity.js";
+import type { SaveCodec } from "../save/compress.js";
+import type { ContentIdResolver } from "../mod/ids.js";
+import type { ModBag, OrphanStore, SaveManifest } from "../mod/save-blocks.js";
+/**
+ * The save format version this build writes. Version 2 replaced every numeric
+ * content index (kidx/eidx/aidx/ridx/tidx/feat, and the positional curse/
+ * brand/slay arrays) with the namespaced string ids of mod/ids.ts, the
+ * load-bearing rule of the mod substrate (MOD_LIFECYCLE decision 1). Version 3
+ * finished that job: `flavor`, `everseen` and `ignore` were the last blocks
+ * still keyed by raw kidx/eidx, and the rune-autoinscription block of wr_ignore
+ * (save.c:586-605) arrived with them. Older saves are not migrated: the game is
+ * pre-1.0 and the save format is still settling, so loadGame rejects them and
+ * the host starts a fresh game.
+ */
+export declare const SAVE_VERSION = 3;
+export interface SavedObject {
+    /** Namespaced kind id (mod/ids.ts), e.g. "core:sword:dagger". */
+    kindId: string;
+    /** Ego id, or null when the object has no ego. */
+    egoId: string | null;
+    /** Artifact id, or null when the object is not an artifact. */
+    artifactId: string | null;
+    grid: {
+        x: number;
+        y: number;
+    } | null;
+    tval: number;
+    sval: number;
+    pval: number;
+    knownPval?: number;
+    weight: number;
+    dd: number;
+    ds: number;
+    ac: number;
+    toA: number;
+    toH: number;
+    toD: number;
+    flags: number[];
+    modifiers: number[];
+    elInfo: ElementInfo[];
+    /** Brand ids present on the object (the sparse form of the boolean array). */
+    brands: string[] | null;
+    /** Slay ids present on the object. */
+    slays: string[] | null;
+    /** Curse ids with their rolled power/timeout (sparse form). */
+    curses: Array<{
+        id: string;
+        power: number;
+        timeout: number;
+    }> | null;
+    time: RandomValue;
+    timeout: number;
+    number: number;
+    notice: number;
+    heldMIdx: number;
+    mimickingMIdx: number;
+    origin: number;
+    originDepth: number;
+    /** Origin monster race id, or null when there is no origin race. */
+    originRaceId: string | null;
+    note: string | null;
+    /** C wr_item's effect-present byte (save.c:113-118). */
+    effectPresent?: boolean;
+    /** C wr_item's saved activation index (save.c:184-188). */
+    activationIndex?: number;
+}
+export declare function serializeObject(obj: GameObject, ids: ContentIdResolver): SavedObject;
+export declare function deserializeObject(data: SavedObject, reg: ObjRegistry, ids: ContentIdResolver): GameObject;
+export interface SavedMonster {
+    /** Namespaced monster race id, e.g. "core:kobold". */
+    raceId: string;
+    /** Original race id (for a polymorphed/shaped monster), or null. */
+    originalRaceId: string | null;
+    midx: number;
+    grid: {
+        x: number;
+        y: number;
+    };
+    hp: number;
+    maxhp: number;
+    mTimed: number[];
+    mspeed: number;
+    energy: number;
+    cdis: number;
+    mflag: number[];
+    mimickedObj: number;
+    heldObj: SavedObject[];
+    attr: number;
+    target: {
+        grid: {
+            x: number;
+            y: number;
+        };
+        midx: number;
+    };
+    groupInfo: MonsterGroupInfo[];
+    minRange: number;
+    bestRange: number;
+    /** C wr_monster's known_pstate.flags (save.c:231-232). */
+    knownPstateFlags?: number[];
+    /** C wr_monster's known_pstate.el_info[].res_level (save.c:234-235). */
+    knownPstateElInfo?: number[];
+}
+export declare function serializeMonster(mon: Monster, ids: ContentIdResolver): SavedMonster;
+/** rd_monster (load.c:259), over JSON instead of the binary block. */
+export declare function deserializeMonster(data: SavedMonster, monsters: MonsterRegistry, objects: ObjRegistry, ids: ContentIdResolver): Monster;
+export interface SavedPlayer {
+    raceName: string;
+    clsName: string;
+    hitdie: number;
+    expFactor: number;
+    age: number;
+    ht: number;
+    wt: number;
+    au: number;
+    maxLev: number;
+    lev: number;
+    maxExp: number;
+    exp: number;
+    expFrac: number;
+    /** Recall / descent state (absent in older saves; default 0). */
+    maxDepth?: number;
+    recallDepth?: number;
+    wordRecall?: number;
+    deepDescent?: number;
+    mhp: number;
+    chp: number;
+    chpFrac: number;
+    msp: number;
+    csp: number;
+    cspFrac: number;
+    statMax: number[];
+    statCur: number[];
+    statMap: number[];
+    statBirth: number[];
+    timed: number[];
+    spellFlags: number[];
+    spellOrder: number[];
+    playerHp: number[];
+    auBirth: number;
+    htBirth: number;
+    wtBirth: number;
+    /**
+     * full_name (save.c:422): the character's name. Optional: absent in saves
+     * written before the field, which load with an empty name (buildScore falls
+     * back to the empty string exactly as before this field existed).
+     */
+    fullName?: string;
+    /**
+     * died_from (save.c:424): the cause-of-death string. Optional: absent saves
+     * load with an empty string.
+     */
+    diedFrom?: string;
+    /**
+     * noscore (save.c:623, wr_u16b): the cheater bit mask. Optional: absent saves
+     * load as 0 (a clean, scored character).
+     */
+    noscore?: number;
+    history: string;
+    /**
+     * hist (player-history.h struct player_history): the runtime auto-history
+     * event log - absent in saves predating this field, which load as an
+     * empty log (SAVEFILE_IMPORT-tolerant posture, matching load.c's
+     * best-effort read of older savefiles).
+     */
+    hist?: SavedHistoryInfo[];
+    equipment: number[];
+    /**
+     * obj_k, every rune variety (wr_player's object knowledge). Older saves
+     * (pre rune learn-by-use) carried only objKnownModifiers; the reader
+     * accepts both.
+     */
+    objKnown?: {
+        modifiers: number[];
+        toA: number;
+        toH: number;
+        toD: number;
+        /**
+         * obj_k->dd / ds / ac (the "know dice"/"know ac" runes). Optional: saves
+         * written before these fields existed omit them; the reader defaults each
+         * to 1 (obvious birth knowledge, always correct - see player_outfit).
+         */
+        dd?: number;
+        ds?: number;
+        ac?: number;
+        elInfo: ElementInfo[];
+        flags: number[];
+        /** Ids of the brand runes the player has learned. */
+        brands: string[];
+        /** Ids of the slay runes the player has learned. */
+        slays: string[];
+        /** Ids of the curse runes the player has learned. */
+        curses: string[];
+    };
+    /** Legacy (save version 1 pre-#13): modifier runes only. */
+    objKnownModifiers?: number[];
+    shapeName: string | null;
+    skills: number[];
+    upkeep: {
+        playing: boolean;
+        newSpells: number;
+        totalWeight: number;
+    };
+    /**
+     * quests (player-quest.h): the per-character quest history. Optional: absent
+     * in saves written before the quest system, which reload with no quests (and
+     * hence no win condition until re-birthed) - the SAVEFILE_IMPORT-tolerant
+     * posture matching the other late-added fields.
+     */
+    quests?: PlayerQuest[];
+    /** total_winner: the victory flag. Optional; absent saves load as false. */
+    totalWinner?: boolean;
+}
+/** Serialized history entry; C save.c:1063-1067 writes the artifact NAME. */
+export interface SavedHistoryInfo {
+    type: number;
+    dlev: number;
+    clev: number;
+    artifactName: string;
+    turn: number;
+    event: string;
+    /** Legacy JSON saves used a numeric aIdx; never written by this version. */
+    aIdx?: number;
+}
+export declare function serializePlayer(p: Player, ids: ContentIdResolver): SavedPlayer;
+export declare function deserializePlayer(data: SavedPlayer, players: PlayerRegistry, objReg: ObjRegistry, ids: ContentIdResolver): Player;
+export interface SavedTrap {
+    /** Namespaced trap-kind id, e.g. "core:trap-door". */
+    trapId: string;
+    grid: {
+        x: number;
+        y: number;
+    };
+    power: number;
+    timeout: number;
+    flags: number[];
+}
+export interface SavedGame {
+    version: number;
+    player: SavedPlayer;
+    actor: {
+        grid: {
+            x: number;
+            y: number;
+        };
+        energy: number;
+        totalEnergy: number;
+    };
+    gear: {
+        next: number;
+        pack: number[];
+        store: Array<[number, SavedObject]>;
+    };
+    /** Omitted for dead saves, matching save.c:873-1045. */
+    chunk?: ChunkSquaresData;
+    /**
+     * Feature legend: every terrain index that appears in chunk.feats or
+     * known.feat, paired with its namespaced feature id. The grid stays a
+     * compact numeric array (one small legend, not a string per cell); on load
+     * the numeric feats are remapped through the legend to the current pack's
+     * indices, so terrain references survive pack changes exactly like every
+     * other content reference (MOD_LIFECYCLE decision 1). Optional only for the
+     * degenerate empty-level case.
+     */
+    featLegend?: Array<[number, string]>;
+    monsters?: Array<SavedMonster | null>;
+    groups?: Array<MonsterGroup | null>;
+    /** Floor piles in pile order (head first), keyed by grid. */
+    floor?: Array<{
+        x: number;
+        y: number;
+        objs: SavedObject[];
+    }>;
+    traps?: Array<{
+        x: number;
+        y: number;
+        traps: SavedTrap[];
+    }>;
+    /** The dungeon header retained by C even when the player is dead. */
+    dungeonDepth?: number;
+    rng: RngState;
+    turn: number;
+    playing: boolean;
+    isDead: boolean;
+    /**
+     * kind->aware / kind->tried (wr_object_memory, save.c:399-401), by namespaced
+     * kind id. Upstream writes these positionally by kidx and rd_object_memory
+     * reads them back positionally (load.c:602-620), so a data change that
+     * re-orders k_info silently re-targets them; the port's format keys every
+     * content reference by id instead (SAVE_VERSION 3).
+     */
+    flavor: {
+        aware: string[];
+        tried: string[];
+    };
+    /**
+     * kind->everseen / ego->everseen (save.c L397, L533): the per-game "ever
+     * seen" flags for object kinds and egos, by namespaced id (see `flavor`).
+     * Optional: absent in saves written before everseen tracking, which reload
+     * with an empty set (the object browser then falls back to flavour-aware
+     * membership only).
+     */
+    everseen?: {
+        kinds: string[];
+        egos: string[];
+    };
+    /**
+     * seed_flavor (game-world.c): the seed flavor_init used to assign object
+     * colours/titles. Optional: absent in saves written before flavour
+     * assignment, which reload with a stable seed-0 assignment.
+     */
+    seedFlavor?: number;
+    /**
+     * The player's map knowledge (game/known.ts). Optional: absent in
+     * version-1 saves written before the knowledge layer, which load with
+     * an all-unknown map.
+     */
+    known?: SavedKnown;
+    /**
+     * Monster memory (mon/lore.ts), keyed by monster race id. Optional: absent
+     * in saves written before lore, which load with no memory. Upstream splits
+     * this between the savefile (pkills/thefts) and the user lore file; the
+     * JSON save carries the whole record.
+     */
+    lore?: Array<[string, SavedLore]>;
+    /**
+     * Single combat in progress (upkeep->arena_level + player->old_grid).
+     * The stashed pre-arena level does not survive the save boundary:
+     * winning after a reload exits to a fresh level of the same depth.
+     */
+    arena?: {
+        oldGrid: {
+            x: number;
+            y: number;
+        };
+    };
+    /**
+     * The town stores (store.c wr_stores, save.c:744-765): every shop's current
+     * proprietor and full stock, in registry order - including FEAT_HOME, whose
+     * stock is the player's home stash (gap 12.1: the home stash must survive
+     * save/load). Optional: absent in saves written before store persistence and
+     * in saves taken before the player ever reached town, which reload and
+     * re-stock fresh (the pre-fix behaviour). See serializeStores.
+     */
+    stores?: SavedStore[];
+    /**
+     * daycount (game-world.c / save.c:963): store turnovers accrued while in the
+     * dungeon, consumed by store_update on the return to town (gap 12.3). Optional
+     * / 0 when no days have elapsed.
+     */
+    daycount?: number;
+    /**
+     * player->resting_turn (save.c:507; wr_player): the cumulative count of player
+     * turns spent resting. Gap 12.6. Optional / omitted when 0 (a character that
+     * has never rested), which loads back as 0. See GameState.restingTurn.
+     */
+    restingTurn?: number;
+    /**
+     * player->skip_cmd_coercion (save.c:490; wr_player): the bloodlust command
+     * -coercion skip state (0/1/2). Gap 12.6. Optional / omitted when 0.
+     */
+    skipCmdCoercion?: number;
+    /**
+     * player->unignoring (save.c:491; wr_player): the temporary "show ignored
+     * items" toggle. Gap 12.6. Optional / omitted when 0 (ignoring active).
+     */
+    unignoring?: number;
+    /**
+     * player->opts.name_suffix (save.c:432; wr_player): the numeric name suffix
+     * for the high-score table. Gap 12.6. Optional / omitted when 0.
+     */
+    nameSuffix?: number;
+    /**
+     * The rolling message log (wr_messages/rd_messages, save.c:339-353 /
+     * load.c:471-495). Gap 12.8. Each entry is text + MSG_* type, in the savefile's
+     * oldest-first order and capped at the 80 newest messages (save.c:345). The
+     * per-entry repeat count is NOT persisted - upstream wr_messages writes only
+     * message_str/message_type, so a reload collapses through message_add and every
+     * count resets to 1 (the quirk is preserved). Optional / omitted for an empty
+     * log and in saves written before message persistence, which load empty.
+     */
+    messages?: SavedMessage[];
+    /**
+     * The player's ignore settings (obj-ignore.c). Optional: absent in saves
+     * written before ignoring, which load with everything shown.
+     */
+    ignore?: SavedIgnoreSettings;
+    /**
+     * The player option store (option.c): every option value, hitpoint_warn /
+     * delay_factor, and the immutable birth-option snapshot. Optional: absent in
+     * saves written before the option store, which load with the table defaults.
+     */
+    options?: import("../player/options.js").OptionStateData;
+    /**
+     * randart_seed (obj-randart.c): the seed do_randart used when birth_randarts
+     * is on. Optional / 0 when the standard artifact set is in use. Persisted so
+     * a reload rebuilds the identical random artifact set.
+     */
+    randartSeed?: number;
+    /**
+     * aup_info[] (obj-make.c): the ids of the artifacts already created. Stored
+     * as an id list (not a by-aidx boolean array) so the created set survives
+     * pack changes. Optional / absent in saves written before artifact
+     * generation landed, which load with an all-false set.
+     */
+    artifactsCreated?: string[];
+    /** aup_info[].seen (save.c:684-685). */
+    artifactsSeen?: string[];
+    /** aup_info[].everseen (save.c:685-686). */
+    artifactsEverseen?: string[];
+    /**
+     * The manifest block (mod/save-blocks.ts, P7.2): the pack set + resolved load
+     * order + core-owned determinism mode that produced this save - its profile
+     * fingerprint. Optional: absent in saves written before the mod substrate,
+     * which load as core-only + deterministic (coreOnlyManifest).
+     */
+    manifest?: SaveManifest;
+    /**
+     * Per-mod private bags (mod:<id>), keyed by pack id: opaque JSON the engine
+     * never interprets, versioned by each mod's saveSchema. Absent when no mod
+     * persisted state. Round-tripped verbatim; migrated only by the owning mod.
+     */
+    mods?: Record<string, ModBag>;
+    /**
+     * The orphans store (orphans:<id>@<version>): entities quarantined because
+     * their defining pack is missing or shadowed (mod/save-blocks.ts). Frozen and
+     * inert, restored by rehydrateSave when the pack returns. Absent when nothing
+     * is quarantined.
+     */
+    orphans?: OrphanStore;
+    /**
+     * decision-8 seam: whether the one-time keep/purge orphan prompt has already
+     * been shown for this save. Core computes the orphan count; the UI shows the
+     * prompt once and sets this so it never nags again. Absent = not yet shown.
+     */
+    orphansAcknowledged?: boolean;
+    /**
+     * birth_levels_persist (#30) frozen-level cache (game/context.ts StoredLevel),
+     * one entry per cached depth, reusing the same chunk / monster / floor / trap /
+     * known serializers as the current level. Optional / absent when the option is
+     * off (the default) or no level has been frozen: older and default saves load
+     * with an empty cache (back-compat, like every other optional field here).
+     */
+    levelCache?: SavedStoredLevel[];
+    /**
+     * GameState.currentJoins: the in-play level's stair connectors (chunk->join,
+     * generate.c L1203-1214), so a first-visit persistent level can align stairs
+     * with the level just left. Absent when the option is off / no joins recorded.
+     */
+    currentJoins?: Array<{
+        x: number;
+        y: number;
+        feat: number;
+        info?: number[];
+    }>;
+    /**
+     * The per-kind autoinscription registry (obj-ignore.c note_aware/note_unaware,
+     * obj/knowledge.ts AutoinscriptionRegistry). Keyed by the namespaced kind id
+     * (like every other content reference, MOD_LIFECYCLE decision 1) so notes
+     * survive pack reordering. Optional / absent when nothing is registered:
+     * older saves and the default (no autoinscriptions) load with an empty
+     * registry, back-compat like every other optional field here.
+     */
+    autoinscriptions?: SavedAutoinscription[];
+    /**
+     * The per-RUNE autoinscriptions (rune_list[i].note; wr_ignore save.c:586-605,
+     * rd_ignore load.c:937-945). Keyed by runeKey (obj/knowledge.ts), the
+     * pack-stable form of the raw index upstream writes (`wr_s16b(k)`,
+     * save.c:600); the runtime registry is still index-keyed like rune_list.
+     * Absent when no rune carries a note.
+     */
+    runeNotes?: Array<[string, string]>;
+    /**
+     * Terrain-only Town chunk (wr_chunks always saves the Town entry even when
+     * birth_levels_persist is OFF; generate.c:1371-1373 / save.c:1001-1044).
+     * Present after leaving depth 0 without persist; consumed on town re-entry.
+     * Optional / absent in older saves and before the player has left town.
+     */
+    townChunk?: ChunkSquaresData;
+    /** Feature legend for townChunk feats (same remap contract as levelCache). */
+    townFeatLegend?: Array<[number, string]>;
+}
+/** One serialized per-kind autoinscription entry (namespaced kind id + notes). */
+export interface SavedAutoinscription {
+    kindId: string;
+    aware?: string;
+    unaware?: string;
+}
+/**
+ * One serialized message-log entry (wr_messages, save.c:350-351): the message
+ * text and its MSG_* type. The repeat count is intentionally NOT stored -
+ * upstream persists only message_str/message_type, so counts do not survive a
+ * reload (see SavedGame.messages).
+ */
+export interface SavedMessage {
+    str: string;
+    type: number;
+}
+/**
+ * Serialize the rolling message log (wr_messages, save.c:339-353): the newest
+ * `cap` messages (default 80, the upstream limit) written oldest-first, each as
+ * text + type. Returns undefined for an empty / absent log so a clean save omits
+ * the block. Faithful to the C: the per-entry repeat count is dropped, so a
+ * reload recollapses through MessageLog.add and every count resets to 1.
+ */
+export declare function serializeMessages(log: MessageLog | undefined, cap?: number): SavedMessage[] | undefined;
+/**
+ * Rebuild a message log from its saved form (rd_messages, load.c:471-495):
+ * re-add each entry oldest-first via MessageLog.add, exactly as upstream calls
+ * message_add in a forward loop. An absent block (older save / empty log) yields
+ * a fresh empty log.
+ */
+export declare function deserializeMessages(data: SavedMessage[] | undefined): MessageLog;
+/** Serialized map knowledge (remembered terrain and floor objects). */
+export interface SavedKnown {
+    feat: number[];
+    objects: Array<[number, {
+        ch: string | null;
+        attr: string;
+    }]>;
+}
+/** One serialized race-lore record. */
+export interface SavedLore {
+    sights: number;
+    deaths: number;
+    pkills: number;
+    thefts: number;
+    tkills: number;
+    wake: number;
+    ignore: number;
+    dropGold: number;
+    dropItem: number;
+    castInnate: number;
+    castSpell: number;
+    blowTimesSeen: number[];
+    blowKnown: boolean[];
+    flags: number[];
+    spellFlags: number[];
+    allKnown: boolean;
+    armourKnown: boolean;
+    dropKnown: boolean;
+    sleepKnown: boolean;
+    spellFreqKnown: boolean;
+    innateFreqKnown: boolean;
+}
+/** Serialize a live game (state + flavor knowledge) into plain JSON data. */
+export declare function serializeGame(state: GameState, flavor: {
+    snapshot(): {
+        aware: number[];
+        tried: number[];
+    };
+}, seedFlavor: number, ids: ContentIdResolver, randartSeed?: number, everseen?: {
+    snapshot(): {
+        kinds: number[];
+        egos: number[];
+    };
+}): SavedGame;
+/** Rebuild the monster memory (absent in older saves: none). */
+export declare function deserializeLore(data: SavedGame["lore"], ids: ContentIdResolver): Map<number, MonsterLore>;
+/**
+ * Serialize the per-kind autoinscription registry (obj/knowledge.ts): every
+ * kind with a registered note, keyed by its namespaced kind id (mod-stable,
+ * like serializeObject). Returns undefined when nothing is registered, so a
+ * clean game omits the block entirely. A kind whose id no longer resolves
+ * (unbound in this pack) is dropped.
+ */
+export declare function serializeAutoinscriptions(registry: AutoinscriptionRegistry, ids: ContentIdResolver): SavedAutoinscription[] | undefined;
+/**
+ * Restore serialized autoinscriptions into a registry (absent in older saves:
+ * nothing to restore). A kind whose id is gone (its defining pack was removed)
+ * is dropped, exactly like deserializeLore drops a removed race's memory.
+ */
+export declare function deserializeAutoinscriptions(data: SavedAutoinscription[], registry: AutoinscriptionRegistry, ids: ContentIdResolver): void;
+/**
+ * The player's ignore settings as they appear in the savefile: the wr_ignore /
+ * wr_object_memory choices with every content reference converted to its
+ * namespaced id.
+ *
+ * Upstream stores all three of these positionally - ignore_level[] by itype,
+ * ego_ignore_types[] by eidx (save.c:530-541 / load.c:872-892), and the per-kind
+ * ignore bits by kidx (save.c:399-407 / load.c:602-620) - so a data change that
+ * re-orders e_info or k_info silently re-targets the player's choices onto
+ * different items. `ignore_level` is genuinely keyed by the ITYPE_* enum, which
+ * is compiled-in in both trees, so it stays an array; the ego and kind keys
+ * become ids, matching every other content reference in the document
+ * (MOD_LIFECYCLE decision 1).
+ */
+export interface SavedIgnoreSettings {
+    /** ignore_level[itype] (save.c:522-523), keyed by the compiled ITYPE_* enum. */
+    level: number[];
+    /** ego_ignore_types: one [namespaced ego id, itype] pair per set bit. */
+    ego: Array<[string, number]>;
+    /** kind_is_ignored_aware, by namespaced kind id. */
+    kindAware: string[];
+    /** kind_is_ignored_unaware, by namespaced kind id. */
+    kindUnaware: string[];
+    /** player->unignoring (save.c L491). Optional: absent in older saves. */
+    unignoring?: boolean;
+}
+/**
+ * Convert an IgnoreSettings.snapshot() (raw kidx/eidx, the runtime keying
+ * upstream also uses) into the id-keyed savefile form. A kind or ego the
+ * running pack no longer binds is dropped, like deserializeAutoinscriptions.
+ */
+export declare function serializeIgnore(data: IgnoreSettingsData, ids: ContentIdResolver): SavedIgnoreSettings;
+/** The inverse of serializeIgnore; an id the pack no longer binds is dropped. */
+export declare function deserializeIgnore(data: SavedIgnoreSettings, ids: ContentIdResolver): IgnoreSettingsData;
+/** Restore the id-keyed flavor block into the raw-kidx form FlavorKnowledge takes. */
+export declare function deserializeFlavor(data: {
+    aware: string[];
+    tried: string[];
+}, ids: ContentIdResolver): {
+    aware: number[];
+    tried: number[];
+};
+/** Restore the id-keyed everseen block into the raw-index form it takes. */
+export declare function deserializeEverseen(data: {
+    kinds: string[];
+    egos: string[];
+}, ids: ContentIdResolver): {
+    kinds: number[];
+    egos: number[];
+};
+/**
+ * Build the feature index remap from a save's legend: each saved fidx maps to
+ * the current pack's index for the same feature id. When the save and the
+ * running pack agree (the common case), every entry is the identity; the map
+ * is still applied so a re-ordered or extended terrain set loads correctly.
+ * Throws on a legend id the current pack cannot resolve (a removed terrain -
+ * graceful degradation is a Phase 2 quarantine concern).
+ */
+export declare function buildFeatRemap(legend: Array<[number, string]> | undefined, ids: ContentIdResolver): Map<number, number>;
+/** Rebuild the map knowledge (absent in older saves: all unknown). */
+export declare function deserializeKnown(data: SavedKnown | undefined, width: number, height: number, featRemap: Map<number, number>): KnownMap;
+/** Rebuild a Gear store from its saved form. */
+export declare function deserializeGear(data: SavedGame["gear"], reg: ObjRegistry, ids: ContentIdResolver): Gear;
+/** Rebuild the floor pile map (grid-keyed, pile order preserved). */
+export declare function deserializeFloor(data: SavedGame["floor"], reg: ObjRegistry, width: number, ids: ContentIdResolver): Map<number, GameObject[]>;
+/**
+ * Rebuild the trap map from saved instances against the bound kinds. This is
+ * rd_trap (load.c:359) plus its caller rd_traps_aux (L1473): the per-trap read
+ * is not a separate function here because the port stores traps per grid rather
+ * than as a linked list off the square.
+ */
+export declare function deserializeTraps(data: SavedGame["traps"], kinds: readonly TrapKind[], width: number, ids: ContentIdResolver, onDecoy?: (grid: Loc) => void): Map<number, Trap[]>;
+/** One serialized store: its proprietor index and its full stock, in order. */
+export interface SavedStore {
+    /** store->owner->oidx (save.c:754): the current proprietor's index. */
+    ownerIndex: number;
+    /** store->stock (save.c:761), head-first; the home stash for FEAT_HOME. */
+    stock: SavedObject[];
+}
+/**
+ * Serialize the live town stores (wr_stores): each shop's proprietor and stock,
+ * in registry order. Returns undefined when the game has no stores yet (never
+ * reached town), so a fresh dungeon-start save omits the block entirely.
+ */
+export declare function serializeStores(stores: readonly Store[] | undefined, ids: ContentIdResolver): SavedStore[] | undefined;
+/**
+ * Rebuild the live town stores (rd_stores): re-bind each store's immutable
+ * tables from the pack (owners, stocking tables, buy list, bounds) and overlay
+ * the saved proprietor + stock. Matches upstream's positional keying (store i
+ * <-> saved i). Draws NO RNG - the caller has already restored the exact
+ * stream, so store restore must not perturb it (decision 22). A saved store
+ * beyond the current registry length is dropped; a registry store with no saved
+ * counterpart keeps an empty, default-owner shell (re-stocked on town entry).
+ */
+export declare function deserializeStores(bound: readonly BoundStore[], saved: SavedStore[] | undefined, reg: ObjRegistry, ids: ContentIdResolver, storeInvenMax: number): Store[];
+/** aup_info id list -> the boolean[] by aidx that ArtifactState.restore wants. */
+export declare function deserializeArtifactsCreated(saved: string[] | undefined, length: number, ids: ContentIdResolver): boolean[];
+/** Restore one aup_info boolean field from stable artifact ids. */
+export declare function deserializeArtifactFlags(saved: string[] | undefined, length: number, ids: ContentIdResolver): boolean[];
+/**
+ * Rebuild a chunk of the saved dimensions and restore its squares, remapping
+ * the terrain grid through the save's feature legend so feature references
+ * survive a pack change.
+ */
+export declare function deserializeChunk(data: ChunkSquaresData, features: Chunk["features"], featRemap: Map<number, number>): Chunk;
+/** One serialized frozen level: the same field-set as the current level. */
+export interface SavedStoredLevel {
+    depth: number;
+    /** Game turn the level was frozen at (restore_monsters recovery baseline). */
+    turn: number;
+    chunk: ChunkSquaresData;
+    featLegend?: Array<[number, string]>;
+    monsters: Array<SavedMonster | null>;
+    groups: Array<MonsterGroup | null>;
+    floor: Array<{
+        x: number;
+        y: number;
+        objs: SavedObject[];
+    }>;
+    traps: Array<{
+        x: number;
+        y: number;
+        traps: SavedTrap[];
+    }>;
+    known: SavedKnown;
+    decoy?: {
+        x: number;
+        y: number;
+    } | null;
+    /** chunk->join stair connectors (generate.c L1203-1214); absent in old saves. */
+    join?: Array<{
+        x: number;
+        y: number;
+        feat: number;
+        info?: number[];
+    }>;
+}
+/** Serialize the whole frozen-level cache (empty / absent => omitted). */
+export declare function serializeLevelCache(cache: Map<number, StoredLevel> | undefined, ids: ContentIdResolver): SavedStoredLevel[] | undefined;
+/**
+ * Rebuild the frozen-level cache (absent in older / default saves: empty).
+ * Reuses the current-level deserializers so a cached level round-trips exactly
+ * like the live one, including per-level feature-legend remapping.
+ */
+export declare function deserializeLevelCache(data: SavedStoredLevel[] | undefined, features: Chunk["features"], monsters: MonsterRegistry, objects: ObjRegistry, traps: readonly TrapKind[] | null | undefined, ids: ContentIdResolver): Map<number, StoredLevel>;
+/**
+ * JSON-encode a save, optionally compress it, and stamp it with the integrity
+ * trailer (16b).
+ *
+ * ORDER: JSON -> codec -> stamp. The digest therefore covers the bytes that are
+ * actually stored, and the trailer stays findable without running a decompressor
+ * first - which matters because an unknown codec must still be diagnosable.
+ * Passing no codec writes the bare JSON every earlier build wrote.
+ */
+export declare function encodeSavedGame(save: SavedGame, provider?: SaveIntegrity, codec?: SaveCodec): Uint8Array;
+/** The decoded form of a stamped save. */
+export interface DecodedSave {
+    save: SavedGame | null;
+    /** The integrity digest matched. */
+    verified: boolean;
+    /** No trailer was present at all. */
+    unstamped: boolean;
+    /** The codec that wrote it, or null for an uncompressed save. */
+    codecId?: string | null;
+    /**
+     * Set when the save names a codec this build does not have - a save from a
+     * NEWER build, which is a different thing from a corrupt one and must be
+     * reported differently: nothing is wrong with the file, and telling the player
+     * it is damaged would invite them to delete a perfectly good character.
+     */
+    unknownCodec?: string;
+}
+/**
+ * Verify and parse stamped save bytes. A failed digest still parses (the
+ * warn-and-label posture of decision 16b - the deterrent is honest, not a
+ * lock), with verified=false for the caller to surface.
+ *
+ * `codecs` are the compressors this build can run. An uncompressed save needs
+ * none, so a caller that never compresses can keep ignoring this argument.
+ */
+export declare function decodeSavedGame(bytes: Uint8Array, provider?: SaveIntegrity, codecs?: readonly SaveCodec[]): DecodedSave;
+//# sourceMappingURL=save.d.ts.map