@rpgm-tools/neo-angband-core 0.19.0 → 0.20.0

package/dist/session/save.js

@@ -38,9 +38,12 @@
  *                                    ported - mon/lore-file.ts - and is laid
  *                                    over this on load, exactly as upstream's
  *                                    startup order does. The save keeps carrying
- *                                    the whole record because narrowing it is a
- *                                    SAVE_VERSION change, and a bump reads as
- *                                    corruption to an existing character.)
+ *                                    the whole record; narrowing it would be a
+ *                                    SAVE_VERSION change with nothing to gain.
+ *                                    The observed SPELL set is written by NAME
+ *                                    as of version 5 (SavedLore.spellsKnown) and
+ *                                    the known race FLAGS as of version 6
+ *                                    (SavedLore.flagsKnown).)
  *   wr_object_memory (save.c:377)  -> flavor.aware / .tried, everseen.kinds,
  *                                    ignore.kindAware / .kindUnaware
  *   wr_quests        (save.c:405)  -> player.quests
@@ -77,15 +80,22 @@ import { loc } from "../loc.js";
 import { FlagSet } from "../bitflag.js";
 import { Chunk, SQUARE_SIZE } from "../world/chunk.js";
 import { objectNew, tvalIsMoney } from "../obj/object.js";
+import { ELEMENT_NAMES, OBJ_MOD_NAMES } from "../obj/bind.js";
+import { ELEM_MAX, OBJ_MOD_MAX, OF_SIZE, newElemInfo } from "../obj/types.js";
 import { buildRuneList, runeKey } from "../obj/knowledge.js";
 import { blankMonster, GROUP_MAX } from "../mon/monster.js";
+import { RF_FLAG_NAMES } from "../mon/lore-file.js";
+import { MFLAG, MON_TMD, OF, SQUARE_FLAG_ENTRIES, STAT, TMD, TRF, } from "../generated/index.js";
+import { MFLAG_SIZE, RF_SIZE } from "../mon/types.js";
+import { rsfMax, rsfSize, spellIndexOf, spellNameAt, } from "../mon/spell-registry.js";
 import { blankPlayer } from "../player/player.js";
 import { playerQuestsReset } from "../game/quest.js";
+import { TRF_SIZE } from "../world/trap.js";
 import { MessageLog } from "../msg.js";
 import { newKnownMap } from "../game/known.js";
 import { fnv1aIntegrity, stampSavefile, verifyStampedSavefile, } from "../save/integrity.js";
 import { applyCodec, findCodec, stripCodec } from "../save/compress.js";
-import { PY_MAX_LEVEL, TMD_MAX } from "../player/types.js";
+import { PY_MAX_LEVEL, SKILL, SKILL_MAX, STAT_MAX, TMD_MAX, } from "../player/types.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/
@@ -93,7 +103,38 @@ import { PY_MAX_LEVEL, TMD_MAX } from "../player/types.js";
  * 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.
+ * (save.c:586-605) arrived with them. Version 5 started on the POSITIONS a save
+ * held: monster lore recorded which spells the player had seen as RSF bit
+ * positions, so `MON_SPELL_ENTRIES` could never grow without renumbering an
+ * existing character's memory. It is written by name now
+ * (`SavedLore.spellsKnown`).
+ *
+ * Version 5's own comment claimed that was the LAST position a save held. It was
+ * not, and version 6 (#273) finished the count: race lore still wrote RF bit
+ * positions, and every object-property carrier in the document - `SavedObject`,
+ * `SavedPlayer.objKnown`, `SavedMonster.knownPstate` - wrote OF bit positions,
+ * OBJ_MOD indices and ELEM indices. All four tables are persisted by NAME now;
+ * see "Position-free persistence" below.
+ *
+ * VERSION 6'S COMMENT MADE THE SAME CLAIM, and version 7 (#274) is the count
+ * actually finishing. Seven more tables were still persisted by position, and
+ * V5_TO_V6's own discriminator comment named two of them as "out of scope":
+ *
+ *   MFLAG   `SavedMonster.mflag`        -> `mflagNames`         (bit positions)
+ *   TRF     `SavedTrap.flags`           -> `trapFlagNames`      (bit positions)
+ *   SQUARE  every chunk's per-grid info -> `squareInfoLegend`   (bit positions)
+ *   MON_TMD `SavedMonster.mTimed`       -> `monsterTimed`       (dense indices)
+ *   TMD     `SavedPlayer.timed`         -> `timedValues`        (dense indices)
+ *   SKILL   `SavedPlayer.skills`        -> `skillValues`        (dense indices)
+ *   STAT    `SavedPlayer.stat*`         -> `stat*Values` / `statMapNames`
+ *
+ * plus `SavedPlayer.objKnownModifiers`, the version-1 legacy rune block, which
+ * every migration since has carried forward untouched as a dense OBJ_MOD array
+ * (`objKnownModifierValues` now). Version 6 converted the modern spelling of
+ * that field and left the legacy one behind, which is precisely the shape of
+ * defect this ticket exists to end.
+ *
+ * SQUARE IS THE ONE THAT IS NOT A LIST OF NAMES. See `SQUARE_INFO_LEGEND`.
  *
  * OLDER SAVES ARE MIGRATED, NOT REJECTED. Every version below this one has a
  * conversion step in session/save-migrate.ts, and `saveMigrationsAreComplete()`
@@ -103,7 +144,561 @@ import { PY_MAX_LEVEL, TMD_MAX } from "../player/types.js";
  * character into "Could not read the save; starting a new game", which in a
  * permadeath game reads as "your character is gone".
  */
-export const SAVE_VERSION = 4;
+export const SAVE_VERSION = 7;
+/* ------------------------------------------------------------------ *
+ * Position-free persistence for the generated tables.
+ *
+ * A save that stores a flag as its BIT POSITION - or a value at its enum's
+ * INDEX - can only be read by a build whose table has the identical length and
+ * order. Remove or reorder one entry and every existing character's data
+ * silently re-points at a different flag; that is why `MON_SPELL_ENTRIES` could
+ * not be opened to mods until #269 (MOD_REACH row 22), and it was equally true
+ * of `MON_RACE_FLAG_ENTRIES`, `OBJECT_FLAG_ENTRIES`, `OBJECT_MODIFIER_ENTRIES`
+ * and `ELEMENT_ENTRIES` until #273 - and of `MON_TEMP_FLAG_ENTRIES`,
+ * `TRAP_FLAG_ENTRIES`, `SQUARE_FLAG_ENTRIES`, `MON_TIMED_ENTRIES`,
+ * `PLAYER_TIMED_ENTRIES`, `SKILL` and `STAT_ENTRIES` until #274.
+ *
+ * Names have no position. A build whose table is larger, smaller or reordered
+ * reads back exactly what was written, and a name it no longer has is DROPPED
+ * rather than mis-resolved - the same rule `deserializeLore` already applies to
+ * a race whose mod is gone. session/save-flag-names.test.ts is the control:
+ * it renumbers each table and reads the same data under both schemes.
+ *
+ * TWO ENCODINGS, AND THE RULE FOR PICKING ONE.
+ *
+ *   A FLAG SET writes `string[]` - the set flags, ascending, so an unchanged
+ *   entity writes identical bytes. Absence is the whole meaning of an unset
+ *   flag, so there is nothing to write for one.
+ *
+ *   A DENSE VALUE ARRAY writes `Record<name, value>`. Where zero genuinely
+ *   means "no such effect" (`timed`, `mTimed`, the object modifiers) the zeroes
+ *   are omitted and the block stays proportional to what the entity HAS rather
+ *   than to the table's length. Where the vector is small and always fully
+ *   populated (`skills`, the four stat arrays) every entry is written, because
+ *   zero there is a value and not an absence; omitting it would round-trip
+ *   correctly today and read as a lie the first time someone inspects a save.
+ *
+ * AND ONE THAT IS NEITHER: see `SQUARE_INFO_LEGEND`, where a name per grid was
+ * measured and rejected.
+ * ------------------------------------------------------------------ */
+/**
+ * A flag/enum value -> name table, INVERTED FROM THE ENUM rather than read off
+ * the generated entry tuple.
+ *
+ * THE THREE ENTRY TUPLES DO NOT SHARE A BASE, and every call site that reaches
+ * for one has to know which it is holding:
+ * `MON_RACE_FLAG_ENTRIES[flag]` (RF_NONE kept at [0]), `OBJECT_FLAG_ENTRIES
+ * [flag - 1]` (OF_NONE dropped), `OBJECT_MODIFIER_ENTRIES[value - 5]` (the five
+ * list-stats.h entries come first). The enum is generated from the same header
+ * as the values themselves, so inverting it cannot be off by one in any
+ * direction - and save-flag-names.test.ts pins each inverted table against its
+ * own ENTRIES tuple AT ITS OWN BASE, because a comment claiming a base is
+ * exactly the kind of thing that has been wrong here before.
+ */
+function nameTable(en) {
+    const out = [];
+    for (const [name, value] of Object.entries(en))
+        out[value] = name;
+    return out;
+}
+/**
+ * OF_ names by flag number. [0] is the OF_NONE sentinel, [OF.MAX] is the "MAX"
+ * one. Nothing in the tree exported this before; RF_FLAG_NAMES and
+ * RSF_FLAG_NAMES (mon/lore-file.ts) are its siblings and are built the same way.
+ */
+export const OF_FLAG_NAMES = nameTable(OF);
+/*
+ * OBJ_MOD and ELEM already have exported name tables - `OBJ_MOD_NAMES` and
+ * `ELEMENT_NAMES` in obj/bind.ts, the port of the C `obj_mods[]` and
+ * `element_names[]` string arrays, both indexed by the enum VALUE. A second
+ * copy here would be a second thing to keep right, so this file uses those; the
+ * inverted enum is applied to them AS A CHECK in save-flag-names.test.ts
+ * instead, which is the only place the two derivations can be compared.
+ */
+/**
+ * The set object flags as OF_ names, ascending by flag number so the save is
+ * byte-stable for an unchanged object.
+ *
+ * The bound is OF.MAX for the reason serializeLoreSpells bounds on RSF.MAX:
+ * OF_SIZE rounds 39 flags up to 5 bytes, so a set has 40 addressable bits and
+ * index 39 reads back as the enum's own `"MAX"` sentinel. Writing that would
+ * put a non-flag in the save and, on the way back, set a bit no property owns.
+ */
+export function serializeObjectFlags(flags) {
+    const out = [];
+    for (const flag of flags) {
+        if (flag >= OF.MAX)
+            break;
+        const name = OF_FLAG_NAMES[flag];
+        if (name !== undefined)
+            out.push(name);
+    }
+    return out;
+}
+/**
+ * The inverse: an OF_SIZE FlagSet with exactly the named flags on. A name this
+ * build does not have (a mod's property, uninstalled - or the `"MAX"` sentinel)
+ * is dropped, which is how the whole scheme stays safe: an unknown NAME cannot
+ * land on some other flag's bit the way an out-of-range index would.
+ */
+export function deserializeObjectFlags(names) {
+    const set = new FlagSet(OF_SIZE);
+    for (const name of names ?? []) {
+        const flag = OF_FLAG_NAMES.indexOf(name);
+        if (flag > 0 && flag < OF.MAX)
+            set.on(flag);
+    }
+    return set;
+}
+/**
+ * The known race flags as RF_ names, ascending.
+ *
+ * RF has NO `MAX` member - the enum stops at NO_SLOW and `RF_SIZE` is
+ * `flagSize(MON_RACE_FLAG_ENTRIES.length)`, so a set has a few unnamed padding
+ * bits above the last flag and nothing else. `RF_FLAG_NAMES[flag] === undefined`
+ * is therefore the entire bound, and it is derived from the table rather than
+ * from a hand-written constant that could part company with it.
+ */
+export function serializeLoreFlags(flags) {
+    const out = [];
+    for (const flag of flags) {
+        const name = RF_FLAG_NAMES[flag];
+        if (name !== undefined)
+            out.push(name);
+    }
+    return out;
+}
+/**
+ * The inverse: an RF_SIZE FlagSet with exactly the named flags on. Index 0 is
+ * upstream's RF_NONE, which is never set, so `flag > 0` excludes it; every
+ * other named flag fits by construction, because RF_SIZE is sized from the very
+ * table the name was looked up in.
+ */
+export function deserializeLoreFlags(names) {
+    const set = new FlagSet(RF_SIZE);
+    for (const name of names ?? []) {
+        const flag = RF_FLAG_NAMES.indexOf(name);
+        if (flag > 0)
+            set.on(flag);
+    }
+    return set;
+}
+/**
+ * The non-zero modifiers as an OBJ_MOD_ name -> value map, in ascending index
+ * order so an unchanged object writes identical bytes.
+ *
+ * NOT A FLAG SET: index 0 is OBJ_MOD_STR, a real modifier, so there is no
+ * sentinel to skip at either end and the `flag > 0` guard the flag helpers use
+ * would silently drop every strength bonus in the game. A zero IS the absence
+ * of a modifier everywhere it is read (`obj.modifiers[k] ?? 0`), so omitting
+ * zeroes loses nothing and keeps the block proportional to what the object
+ * actually has rather than to the table's length.
+ */
+export function serializeObjectModifiers(mods) {
+    const out = {};
+    for (let i = 0; i < mods.length; i++) {
+        const value = mods[i] ?? 0;
+        if (value === 0)
+            continue;
+        const name = OBJ_MOD_NAMES[i];
+        if (name !== undefined)
+            out[name] = value;
+    }
+    return out;
+}
+/**
+ * The inverse: a full-length OBJ_MOD array, zero wherever the save said
+ * nothing. The length comes from THIS build's table, never from the document -
+ * a save written against a longer table hands back an array the engine's own
+ * loops would run off the end of.
+ */
+export function deserializeObjectModifiers(saved) {
+    const out = new Array(OBJ_MOD_MAX).fill(0);
+    for (const [name, value] of Object.entries(saved ?? {})) {
+        const i = OBJ_MOD_NAMES.indexOf(name);
+        if (i >= 0 && i < out.length && typeof value === "number")
+            out[i] = value;
+    }
+    return out;
+}
+/**
+ * The element info as an ELEM_ name -> {resLevel, flags} map, ascending, with
+ * the untouched elements omitted. `flags` stays a raw number: EL_INFO_HATES /
+ * EL_INFO_IGNORE are hand-written constants in obj/types.ts, not a generated
+ * list, so nothing a mod can do renumbers them.
+ */
+export function serializeObjectElements(elInfo) {
+    const out = {};
+    for (let i = 0; i < elInfo.length; i++) {
+        const e = elInfo[i];
+        if (e === undefined || (e.resLevel === 0 && e.flags === 0))
+            continue;
+        const name = ELEMENT_NAMES[i];
+        if (name !== undefined)
+            out[name] = { resLevel: e.resLevel, flags: e.flags };
+    }
+    return out;
+}
+/** The inverse: a zeroed ELEM_MAX array with the named elements filled in. */
+export function deserializeObjectElements(saved) {
+    const out = newElemInfo();
+    for (const [name, e] of Object.entries(saved ?? {})) {
+        const i = ELEMENT_NAMES.indexOf(name);
+        if (i < 0 || i >= out.length || e === null || typeof e !== "object")
+            continue;
+        out[i] = { resLevel: e.resLevel ?? 0, flags: e.flags ?? 0 };
+    }
+    return out;
+}
+/**
+ * The el_info[].res_level half on its own, for the one carrier that stores
+ * resistance levels without the EL_INFO_ flags beside them: a monster's
+ * `knownPstate.elInfo`, which is an Int16Array (mon/monster.ts).
+ */
+export function serializeElementLevels(levels) {
+    const out = {};
+    for (let i = 0; i < levels.length; i++) {
+        const value = levels[i] ?? 0;
+        if (value === 0)
+            continue;
+        const name = ELEMENT_NAMES[i];
+        if (name !== undefined)
+            out[name] = value;
+    }
+    return out;
+}
+/** The inverse: a zeroed ELEM_MAX array of resistance levels. */
+export function deserializeElementLevels(saved) {
+    const out = new Array(ELEM_MAX).fill(0);
+    for (const [name, value] of Object.entries(saved ?? {})) {
+        const i = ELEMENT_NAMES.indexOf(name);
+        if (i >= 0 && i < out.length && typeof value === "number")
+            out[i] = value;
+    }
+    return out;
+}
+/* ------------------------------------------------------------------ *
+ * #274: the seven remaining position-persisted tables.
+ * ------------------------------------------------------------------ */
+/**
+ * MFLAG_ names by flag number. [0] is upstream's MFLAG_NONE; there is no MAX
+ * member, so "has a name" is the whole bound, exactly as for RF.
+ */
+export const MFLAG_NAMES = nameTable(MFLAG);
+/** TRF_ names by flag number. [0] is TRF_NONE; no MAX member, as for MFLAG. */
+export const TRF_NAMES = nameTable(TRF);
+/**
+ * MON_TMD_ names by index. Unlike TMD, this enum DOES carry its own `MAX`
+ * member (mon-timed.h ends with MON_TMD_MAX), and `mon.mTimed` is exactly
+ * `MON_TMD.MAX` long - so index `MON_TMD.MAX` is the sentinel and never a slot.
+ */
+export const MON_TMD_NAMES = nameTable(MON_TMD);
+/**
+ * TMD_ names by index. The player-timed enum has NO sentinel at either end:
+ * `TMD_MAX` is `PLAYER_TIMED_ENTRIES.length` rather than an enum member, so
+ * every index in the table names a real effect.
+ */
+export const TMD_NAMES = nameTable(TMD);
+/** SKILL_ names by index. No sentinels; `SKILL_MAX` is a hand-written 10. */
+export const SKILL_NAMES = nameTable(SKILL);
+/** STAT_ names by index. No sentinels; five entries, from list-stats.h. */
+export const STAT_NAMES = nameTable(STAT);
+/**
+ * A FlagSet -> ascending names, bounded by "this build has a name for it".
+ * Index 0 is the NONE sentinel in every table that has one and is never set,
+ * so it costs nothing to let the name table decide.
+ */
+function flagNames(flags, names) {
+    const out = [];
+    for (const flag of flags) {
+        if (flag === 0)
+            continue;
+        const name = names[flag];
+        if (name !== undefined)
+            out.push(name);
+    }
+    return out;
+}
+/** The inverse. An unknown name is dropped, never landed on another bit. */
+function flagsFromNames(saved, names, size) {
+    const set = new FlagSet(size);
+    for (const name of saved ?? []) {
+        const flag = names.indexOf(name);
+        if (flag > 0 && flag < size * 8)
+            set.on(flag);
+    }
+    return set;
+}
+/**
+ * A dense value array -> a name -> value map, ascending by index, omitting
+ * zeroes. `all` writes every named slot instead, for the vectors where zero is
+ * a value rather than an absence (see the encoding rule above).
+ */
+function valuesByName(values, names, all = false) {
+    const out = {};
+    for (let i = 0; i < values.length; i++) {
+        const value = values[i] ?? 0;
+        if (!all && value === 0)
+            continue;
+        const name = names[i];
+        if (name !== undefined)
+            out[name] = value;
+    }
+    return out;
+}
+/**
+ * The inverse: a full-length array, zero where the document said nothing. The
+ * LENGTH IS THIS BUILD'S, never the document's - a save written against a
+ * longer table would otherwise hand back an array the engine's own loops run
+ * off the end of.
+ */
+function valuesFromNames(saved, names, length) {
+    const out = new Array(length).fill(0);
+    for (const [name, value] of Object.entries(saved ?? {})) {
+        const i = names.indexOf(name);
+        if (i >= 0 && i < length && typeof value === "number")
+            out[i] = value;
+    }
+    return out;
+}
+/**
+ * MFLAG: a monster's transient flags (save.c:228-229, one byte per MFLAG_SIZE).
+ *
+ * Upstream reads exactly `mflag_size` bytes - THIS build's size, off a stream
+ * that was written with the writing build's - so a table that grew by one flag
+ * desynchronises the whole rest of the monster block rather than merely
+ * mis-naming a flag. There is no discard rule to preserve here because upstream
+ * has no notion of a flag it does not recognise; the name form gives it one.
+ */
+export function serializeMonsterFlags(flags) {
+    return flagNames(flags, MFLAG_NAMES);
+}
+/** The inverse: an MFLAG_SIZE FlagSet with exactly the named flags on. */
+export function deserializeMonsterFlags(names) {
+    return flagsFromNames(names, MFLAG_NAMES, MFLAG_SIZE);
+}
+/** TRF: a trap instance's flags (save.c:275-276, rd_trap at load.c:376-377). */
+export function serializeTrapFlags(flags) {
+    return flagNames(flags, TRF_NAMES);
+}
+/** The inverse: a TRF_SIZE FlagSet with exactly the named flags on. */
+export function deserializeTrapFlags(names) {
+    return flagsFromNames(names, TRF_NAMES, TRF_SIZE);
+}
+/**
+ * MON_TMD: a monster's timed effects (save.c:223-226).
+ *
+ * Zero means "not affected" everywhere `m_timed` is read, so zeroes are
+ * omitted. UPSTREAM HAS NO DISCARD RULE HERE AND THAT IS A BUG, not a
+ * behaviour to reproduce: save.c:223 writes `MON_TMD_MAX` and load.c:290-292
+ * reads that count straight into `mon->m_timed[j]`, which is `MON_TMD_MAX`
+ * long in the READING build - a longer table overruns the array. Names cannot
+ * overrun anything, so the port's reader simply drops an effect it does not
+ * have, which is what upstream's rd_player does two blocks later for the
+ * player's own timed effects and evidently meant to do here.
+ */
+export function serializeMonsterTimed(timed) {
+    return valuesByName(timed, MON_TMD_NAMES);
+}
+/** The inverse: a MON_TMD.MAX-long array, zero where the save said nothing. */
+export function deserializeMonsterTimed(saved) {
+    return valuesFromNames(saved, MON_TMD_NAMES, MON_TMD.MAX);
+}
+/**
+ * TMD: the player's timed effects (save.c:508-511).
+ *
+ * THE ONE FIELD WITH AN EXPLICIT UPSTREAM DISCARD RULE. load.c:811-829 reads
+ * the saved count and, when it exceeds TMD_MAX, keeps the ones it supports,
+ * strips the rest and notes "Discarded unsupported timed effects" - an extra
+ * timed effect is not an error. `valuesFromNames` drops an unrecognised name
+ * for exactly that reason, and the pre-#274 reader's `slice(0, TMD_MAX)` said
+ * the same thing positionally.
+ */
+export function serializePlayerTimed(timed) {
+    return valuesByName(timed, TMD_NAMES);
+}
+/** The inverse: a TMD_MAX-long array, zero where the save said nothing. */
+export function deserializePlayerTimed(saved) {
+    return valuesFromNames(saved, TMD_NAMES, TMD_MAX);
+}
+/**
+ * SKILL: the derived level-based skills.
+ *
+ * NOT AN UPSTREAM FIELD AT ALL - `grep -i skill save.c load.c` is empty, and
+ * player->state.skills is rebuilt by calc_bonuses on every load. The port
+ * persists them anyway (player/player.ts `skills`), so the same position
+ * defect applied; there is no upstream discard rule to match because there is
+ * no upstream block. Every slot is written: a skill of 0 is a value, and the
+ * whole vector is ten entries.
+ */
+export function serializePlayerSkills(skills) {
+    return valuesByName(skills, SKILL_NAMES, true);
+}
+/** The inverse: a SKILL_MAX-long array. */
+export function deserializePlayerSkills(saved) {
+    return valuesFromNames(saved, SKILL_NAMES, SKILL_MAX);
+}
+/**
+ * STAT: one of stat_max / stat_cur / stat_birth (save.c:443-446).
+ *
+ * Upstream's rule is NOT the timed one: load.c:723-727 reads the saved count
+ * and FAILS THE LOAD when it exceeds STAT_MAX ("Too many stats (%d)."), while
+ * a shorter count is read as far as it goes and the rest left at their blank
+ * values. So "extra" is an error there and "missing" is not. By name that
+ * becomes: a stat this build does not have contributes nothing (it has no slot
+ * to corrupt), and a stat the document does not mention keeps its blank value.
+ * Refusing the load over a name would be strictly worse than upstream, which
+ * only refuses because a longer array would overrun a fixed C buffer.
+ */
+export function serializeStatValues(stats) {
+    return valuesByName(stats, STAT_NAMES, true);
+}
+/** The inverse: a STAT_MAX-long array. */
+export function deserializeStatValues(saved) {
+    return valuesFromNames(saved, STAT_NAMES, STAT_MAX);
+}
+/**
+ * STAT, THE PERMUTATION. `player->stat_map` (save.c:445) is the trap in this
+ * set: it is the only one of the four stat arrays whose VALUES are themselves
+ * stat indices rather than magnitudes.
+ *
+ * player-util.c player_scramble_stats/player_fix_scramble is the authority -
+ * `new_cur[stat_map[i]] = stat_cur[i]`, so slot `i` currently holds the value
+ * that belongs to stat `stat_map[i]`, and at birth the map is the identity.
+ * Naming only the KEYS would have left every value a raw STAT index, so a
+ * reordered stat table would still have re-pointed a scrambled character's
+ * strength at their intelligence. Both halves are names: `{ STR: "INT" }` reads
+ * "the value in the STR slot really belongs to INT".
+ *
+ * A name this build does not have leaves that slot at the identity, which is
+ * what player_fix_scramble resets it to anyway.
+ */
+export function serializeStatMap(map) {
+    const out = {};
+    for (let i = 0; i < map.length; i++) {
+        const from = STAT_NAMES[i];
+        const to = STAT_NAMES[map[i] ?? i];
+        if (from !== undefined && to !== undefined)
+            out[from] = to;
+    }
+    return out;
+}
+/**
+ * The inverse, with a permutation check.
+ *
+ * A HALF-APPLIED MAP IS WORSE THAN NO MAP. Dropping one unresolvable name from
+ * a permutation leaves two slots pointing at the same stat and one at none, and
+ * player_fix_scramble would then duplicate one stat's value and lose another's
+ * - a silent, permanent stat loss. So the result is validated as a permutation
+ * of 0..STAT_MAX-1 and falls back WHOLE to the identity if it is not, which is
+ * the value the map legitimately holds for every unscrambled character.
+ */
+export function deserializeStatMap(saved) {
+    const out = Array.from({ length: STAT_MAX }, (_, i) => i);
+    if (saved === undefined)
+        return out;
+    for (const [from, to] of Object.entries(saved)) {
+        const i = STAT_NAMES.indexOf(from);
+        const j = STAT_NAMES.indexOf(to);
+        if (i >= 0 && i < STAT_MAX && j >= 0 && j < STAT_MAX)
+            out[i] = j;
+    }
+    const seen = new Set(out);
+    if (seen.size !== STAT_MAX)
+        return Array.from({ length: STAT_MAX }, (_, i) => i);
+    return out;
+}
+/* ------------------------------------------------------------------ *
+ * SQUARE: the one table a per-entity name list could not carry.
+ * ------------------------------------------------------------------ */
+/**
+ * THE MEASUREMENT, AND WHY THIS ONE IS A LEGEND.
+ *
+ * Every other table in #273/#274 belongs to an entity there are tens or
+ * hundreds of. `square.info` belongs to a GRID, and a 63x188 level is 11,844 of
+ * them - written once for the level in play, once for the Town, and once more
+ * for every level in the birth_levels_persist cache.
+ *
+ * Measured on a real generated level (seed 4242, depth 3, 11,844 grids):
+ *
+ *   numeric, 3 bytes/grid, as written today          97,731 bytes
+ *   one name list per grid, freshly generated        76,624 bytes
+ *   one name list per grid, EXPLORED                462,289 bytes  (4.7x)
+ *   one name list per grid, every flag set        2,463,553 bytes  (25x)
+ *   this build's whole ordered name list, ONCE          214 bytes
+ *
+ * The freshly-generated figure is the trap: an unexplored level averages 0.49
+ * set flags per grid, so `[]` beats `[0,0,0]` and the name form looks FREE. It
+ * is not. The instant a character walks the level, MARK / GLOW / ROOM / SEEN /
+ * VIEW land on most grids and the same encoding costs 4.7x - a third of a
+ * megabyte per level, on a web build whose storage risk is already the reason
+ * saves are compressed at all.
+ *
+ * So the per-grid payload stays numeric and the DOCUMENT carries the legend:
+ * the ordered SQUARE_ names, once, alongside the bits that index into them. The
+ * legend travels with the save, so it describes the WRITING build's numbering
+ * no matter which build reads it - which is the whole property names were
+ * bought for, at 0.2% of one level's cost instead of 470%.
+ *
+ * Upstream reached the same shape by accident and stopped one step short:
+ * save.c:967 writes `SQUARE_SIZE` into the file and load.c:1512 reads it back
+ * into a file-scope `square_size` that rd_dungeon_aux then uses as its loop
+ * bound (load.c:1306). The file already describes its own square encoding
+ * there; it just describes the LENGTH and not the ORDER, so a reordered table
+ * still lands every flag somewhere else.
+ */
+export const SQUARE_INFO_LEGEND = SQUARE_FLAG_ENTRIES.map((e) => e.name);
+/**
+ * A saved legend -> this build's bit numbering, or `null` when the two agree
+ * and every byte can be taken as-is (the overwhelmingly common case: the same
+ * build, or any build whose SQUARE table has not moved).
+ *
+ * An absent legend also reads as `null`. That is deliberate and it is safe for
+ * one reason only: `V6_TO_V7` stamps the legend onto every document it
+ * converts, and no build that could have reordered SQUARE can have written a
+ * document at version 6 or below - the same argument `savedFlagSet` rests on in
+ * save-migrate.ts.
+ */
+export function buildSquareInfoRemap(legend) {
+    if (legend === undefined)
+        return null;
+    let moved = false;
+    const remap = [];
+    for (let bit = 0; bit < legend.length; bit++) {
+        const name = legend[bit];
+        const now = name === undefined ? -1 : SQUARE_INFO_LEGEND.indexOf(name);
+        remap[bit] = now < 0 ? undefined : now;
+        if (now !== bit)
+            moved = true;
+    }
+    if (!moved && legend.length === SQUARE_INFO_LEGEND.length)
+        return null;
+    return remap;
+}
+/**
+ * One grid's info bytes, re-expressed in this build's bit numbering. A bit
+ * whose name this build no longer has is dropped, exactly as an unknown flag
+ * NAME is dropped everywhere else in this file.
+ */
+export function remapSquareInfo(bytes, remap) {
+    const out = new Array(SQUARE_SIZE).fill(0);
+    for (let b = 0; b < bytes.length; b++) {
+        const byte = bytes[b] ?? 0;
+        if (byte === 0)
+            continue;
+        for (let k = 0; k < 8; k++) {
+            if ((byte & (1 << k)) === 0)
+                continue;
+            const now = remap[b * 8 + k];
+            if (now === undefined)
+                continue;
+            const target = now >> 3;
+            if (target < SQUARE_SIZE)
+                out[target] = (out[target] ?? 0) | (1 << (now & 7));
+        }
+    }
+    return out;
+}
 export function serializeObject(obj, ids) {
     return {
         kindId: ids.kindId(obj.kind.kidx),
@@ -121,9 +716,9 @@ export function serializeObject(obj, ids) {
         toA: obj.toA,
         toH: obj.toH,
         toD: obj.toD,
-        flags: Array.from(obj.flags.bits),
-        modifiers: [...obj.modifiers],
-        elInfo: obj.elInfo.map((e) => ({ ...e })),
+        flagNames: serializeObjectFlags(obj.flags),
+        modifierValues: serializeObjectModifiers(obj.modifiers),
+        elementInfo: serializeObjectElements(obj.elInfo),
         brands: serializeBrandList(obj.brands, ids),
         slays: serializeSlayList(obj.slays, ids),
         curses: serializeCurseList(obj.curses, ids),
@@ -221,9 +816,9 @@ export function deserializeObject(data, reg, ids) {
         toA: data.toA,
         toH: data.toH,
         toD: data.toD,
-        flags: new FlagSet(Uint8Array.from(data.flags)),
-        modifiers: [...data.modifiers],
-        elInfo: data.elInfo.map((e) => ({ ...e })),
+        flags: deserializeObjectFlags(data.flagNames),
+        modifiers: deserializeObjectModifiers(data.modifierValues),
+        elInfo: deserializeObjectElements(data.elementInfo),
         brands: deserializeBrandList(data.brands, reg, ids),
         slays: deserializeSlayList(data.slays, reg, ids),
         curses: deserializeCurseList(data.curses, reg, ids),
@@ -309,11 +904,11 @@ export function serializeMonster(mon, ids) {
         grid: { x: mon.grid.x, y: mon.grid.y },
         hp: mon.hp,
         maxhp: mon.maxhp,
-        mTimed: Array.from(mon.mTimed),
+        monsterTimed: serializeMonsterTimed(mon.mTimed),
         mspeed: mon.mspeed,
         energy: mon.energy,
         cdis: mon.cdis,
-        mflag: Array.from(mon.mflag.bits),
+        mflagNames: serializeMonsterFlags(mon.mflag),
         mimickedObj: mon.mimickedObj,
         heldObj: mon.heldObj.map((o) => serializeObject(o, ids)),
         attr: mon.attr,
@@ -324,8 +919,8 @@ export function serializeMonster(mon, ids) {
         groupInfo: mon.groupInfo.map((g) => ({ ...g })),
         minRange: mon.minRange,
         bestRange: mon.bestRange,
-        knownPstateFlags: Array.from(mon.knownPstate.flags.bits),
-        knownPstateElInfo: Array.from(mon.knownPstate.elInfo),
+        knownPstateFlagNames: serializeObjectFlags(mon.knownPstate.flags),
+        knownPstateElementRes: serializeElementLevels(mon.knownPstate.elInfo),
     };
 }
 /** rd_monster (load.c:259), over JSON instead of the binary block. */
@@ -343,18 +938,18 @@ export function deserializeMonster(data, monsters, objects, ids) {
     mon.grid = loc(data.grid.x, data.grid.y);
     mon.hp = data.hp;
     mon.maxhp = data.maxhp;
-    mon.mTimed.set(data.mTimed);
+    mon.mTimed.set(deserializeMonsterTimed(data.monsterTimed));
     mon.mspeed = data.mspeed;
     mon.energy = data.energy;
     mon.cdis = data.cdis;
-    mon.mflag.bits.set(data.mflag);
-    if (data.knownPstateFlags) {
+    mon.mflag.copy(deserializeMonsterFlags(data.mflagNames));
+    if (data.knownPstateFlagNames) {
         /* load.c:302 restores known_pstate.flags before the monster goes live. */
-        mon.knownPstate.flags.bits.set(data.knownPstateFlags);
+        mon.knownPstate.flags.copy(deserializeObjectFlags(data.knownPstateFlagNames));
     }
-    if (data.knownPstateElInfo) {
+    if (data.knownPstateElementRes) {
         /* load.c:305 restores known_pstate.el_info[].res_level before live use. */
-        mon.knownPstate.elInfo.set(data.knownPstateElInfo);
+        mon.knownPstate.elInfo.set(deserializeElementLevels(data.knownPstateElementRes));
     }
     mon.mimickedObj = data.mimickedObj;
     mon.heldObj = data.heldObj.map((o) => deserializeObject(o, objects, ids));
@@ -397,11 +992,11 @@ export function serializePlayer(p, ids) {
         msp: p.msp,
         csp: p.csp,
         cspFrac: p.cspFrac,
-        statMax: [...p.statMax],
-        statCur: [...p.statCur],
-        statMap: [...p.statMap],
-        statBirth: [...p.statBirth],
-        timed: Array.from(p.timed),
+        statMaxValues: serializeStatValues(p.statMax),
+        statCurValues: serializeStatValues(p.statCur),
+        statMapNames: serializeStatMap(p.statMap),
+        statBirthValues: serializeStatValues(p.statBirth),
+        timedValues: serializePlayerTimed(p.timed),
         spellFlags: [...p.spellFlags],
         spellOrder: [...p.spellOrder],
         playerHp: [...p.playerHp],
@@ -422,22 +1017,22 @@ export function serializePlayer(p, ids) {
         })),
         equipment: [...p.equipment],
         objKnown: {
-            modifiers: [...p.objKnown.modifiers],
+            modifierValues: serializeObjectModifiers(p.objKnown.modifiers),
             toA: p.objKnown.toA,
             toH: p.objKnown.toH,
             toD: p.objKnown.toD,
             dd: p.objKnown.dd,
             ds: p.objKnown.ds,
             ac: p.objKnown.ac,
-            elInfo: p.objKnown.elInfo.map((e) => ({ ...e })),
-            flags: Array.from(p.objKnown.flags.bits),
+            elementInfo: serializeObjectElements(p.objKnown.elInfo),
+            flagNames: serializeObjectFlags(p.objKnown.flags),
             /* The learned runes save as the ids of the known brands/slays/curses. */
             brands: serializeBrandList(p.objKnown.brands, ids) ?? [],
             slays: serializeSlayList(p.objKnown.slays, ids) ?? [],
             curses: serializeKnownCurseList(p.objKnown.curses, ids),
         },
         shapeName: p.shape ? p.shape.name : null,
-        skills: [...p.skills],
+        skillValues: serializePlayerSkills(p.skills),
         /* THE THREE DECLARED FIELDS, NAMED. `{ ...p.upkeep }` wrote whatever the live
          * object happened to hold, which is not what the type above says: `notice`,
          * `dropping`, `repeatPrevAllowed` and `lastCmdUsedFloorItem` are transients
@@ -500,12 +1095,15 @@ quests) {
     p.msp = data.msp;
     p.csp = data.csp;
     p.cspFrac = data.cspFrac;
-    p.statMax = [...data.statMax];
-    p.statCur = [...data.statCur];
-    p.statMap = [...data.statMap];
-    p.statBirth = [...data.statBirth];
-    /* load.c:807-823 reads only supported timed entries and discards extras. */
-    p.timed.set(data.timed.slice(0, TMD_MAX));
+    /* load.c:723-732: a saved stat this build does not have contributes nothing,
+     * and one the save omits keeps its blank value - see serializeStatValues. */
+    p.statMax = deserializeStatValues(data.statMaxValues);
+    p.statCur = deserializeStatValues(data.statCurValues);
+    p.statMap = deserializeStatMap(data.statMapNames);
+    p.statBirth = deserializeStatValues(data.statBirthValues);
+    /* load.c:811-829 reads only supported timed entries and discards extras. By
+     * name that is a name this build does not have, dropped without complaint. */
+    p.timed.set(deserializePlayerTimed(data.timedValues));
     p.spellFlags = [...data.spellFlags];
     p.spellOrder = [...data.spellOrder];
     p.playerHp = [...data.playerHp];
@@ -545,7 +1143,7 @@ quests) {
     p.equipment = [...data.equipment];
     if (data.objKnown) {
         p.objKnown = {
-            modifiers: [...data.objKnown.modifiers],
+            modifiers: deserializeObjectModifiers(data.objKnown.modifierValues),
             toA: data.objKnown.toA,
             toH: data.objKnown.toH,
             toD: data.objKnown.toD,
@@ -554,22 +1152,23 @@ quests) {
             dd: data.objKnown.dd ?? 1,
             ds: data.objKnown.ds ?? 1,
             ac: data.objKnown.ac ?? 1,
-            elInfo: data.objKnown.elInfo.map((e) => ({ ...e })),
-            flags: new FlagSet(Uint8Array.from(data.objKnown.flags)),
+            elInfo: deserializeObjectElements(data.objKnown.elementInfo),
+            flags: deserializeObjectFlags(data.objKnown.flagNames),
             brands: deserializeBrandList(data.objKnown.brands, objReg, ids) ?? [],
             slays: deserializeSlayList(data.objKnown.slays, objReg, ids) ?? [],
             curses: deserializeKnownCurseList(data.objKnown.curses, objReg, ids),
         };
     }
-    else if (data.objKnownModifiers) {
-        /* Legacy pre-#13 save: only the modifier runes were tracked. */
-        p.objKnown.modifiers = [...data.objKnownModifiers];
+    else if (data.objKnownModifierValues) {
+        /* Legacy pre-#13 save: only the modifier runes were tracked. By name as of
+         * version 7, through the same helper the modern field uses. */
+        p.objKnown.modifiers = deserializeObjectModifiers(data.objKnownModifierValues);
     }
     p.shape =
         data.shapeName !== null
             ? (players.shapes.find((s) => s.name === data.shapeName) ?? null)
             : null;
-    p.skills = [...data.skills];
+    p.skills = deserializePlayerSkills(data.skillValues);
     /* notice is NOT in the savefile, exactly as upstream's is not: it is a queue
      * of work owed within a turn, and a save can only happen with the queue
      * drained. A loaded character therefore starts it at 0 rather than at
@@ -699,6 +1298,43 @@ function deserializeKnownObject(m, floor, reg, ids) {
     obj.grid = null;
     return { obj, sensed: m.sensed === true };
 }
+/**
+ * The observed spell set as RSF_ names, ascending by flag number so the save is
+ * byte-stable for an unchanged record.
+ *
+ * The bound is rsfMax() (live, including a mod's spells), not the module-load
+ * RSF.MAX. spellNameAt returns null for an unknown index the same way the old
+ * RSF_FLAG_NAMES array returned undefined - including the MAX sentinel when no
+ * mod occupies that slot - so a non-spell never reaches the save.
+ */
+export function serializeLoreSpells(spellFlags) {
+    const out = [];
+    for (const flag of spellFlags) {
+        if (flag >= rsfMax())
+            break;
+        const name = spellNameAt(flag);
+        if (name !== null)
+            out.push(name);
+    }
+    return out;
+}
+/**
+ * The inverse: a lore-sized FlagSet with exactly the named spells on. A name
+ * this build does not have (a mod's spell, uninstalled - or the `"MAX"`
+ * sentinel) is dropped, which is how the whole scheme stays safe: an unknown
+ * NAME cannot land on some other spell's bit the way an out-of-range index
+ * would. spellIndexOf returns -1 for unknown, matching the existing flag > 0
+ * guard's intent.
+ */
+export function deserializeLoreSpells(names) {
+    const set = new FlagSet(rsfSize());
+    for (const name of names ?? []) {
+        const flag = spellIndexOf(name);
+        if (flag > 0 && flag < rsfMax())
+            set.on(flag);
+    }
+    return set;
+}
 /** Build the feature legend for every fidx appearing in the terrain grids. */
 function buildFeatLegend(feats, known, ids) {
     const present = new Set();
@@ -762,7 +1398,7 @@ export function serializeGame(state, flavor, seedFlavor, ids, randartSeed = 0, e
                 grid: { x: t.grid.x, y: t.grid.y },
                 power: t.power,
                 timeout: t.timeout,
-                flags: Array.from(t.flags.bits),
+                trapFlagNames: serializeTrapFlags(t.flags),
             })),
         });
     }
@@ -793,6 +1429,10 @@ export function serializeGame(state, flavor, seedFlavor, ids, randartSeed = 0, e
     const runeNotes = runeNoteEntries.length > 0 ? runeNoteEntries : undefined;
     return {
         version: SAVE_VERSION,
+        /* Written unconditionally, including for a dead save that carries no
+         * chunk: a legend costs 214 bytes and a document that describes its own
+         * square encoding in only some cases is a document with two rules. */
+        squareInfoLegend: [...SQUARE_INFO_LEGEND],
         player: serializePlayer(state.actor.player, ids),
         actor: {
             grid: { x: state.actor.grid.x, y: state.actor.grid.y },
@@ -950,8 +1590,8 @@ export function serializeGame(state, flavor, seedFlavor, ids, randartSeed = 0, e
                 castSpell: l.castSpell,
                 blowTimesSeen: [...l.blowTimesSeen],
                 blowKnown: [...l.blowKnown],
-                flags: Array.from(l.flags.bits),
-                spellFlags: Array.from(l.spellFlags.bits),
+                flagsKnown: serializeLoreFlags(l.flags),
+                spellsKnown: serializeLoreSpells(l.spellFlags),
                 allKnown: l.allKnown,
                 armourKnown: l.armourKnown,
                 dropKnown: l.dropKnown,
@@ -985,8 +1625,8 @@ export function deserializeLore(data, ids) {
             castSpell: l.castSpell,
             blowTimesSeen: [...l.blowTimesSeen],
             blowKnown: [...l.blowKnown],
-            flags: new FlagSet(Uint8Array.from(l.flags)),
-            spellFlags: new FlagSet(Uint8Array.from(l.spellFlags)),
+            flags: deserializeLoreFlags(l.flagsKnown),
+            spellFlags: deserializeLoreSpells(l.spellsKnown),
             allKnown: l.allKnown,
             armourKnown: l.armourKnown,
             dropKnown: l.dropKnown,
@@ -1222,7 +1862,7 @@ export function deserializeTraps(data, kinds, width, ids, onDecoy) {
                 grid,
                 power: t.power,
                 timeout: t.timeout,
-                flags: new FlagSet(Uint8Array.from(t.flags)),
+                flags: deserializeTrapFlags(t.trapFlagNames),
             };
         }));
     }
@@ -1338,7 +1978,7 @@ export function serializeStoredLevel(depth, level, ids) {
                 grid: { x: t.grid.x, y: t.grid.y },
                 power: t.power,
                 timeout: t.timeout,
-                flags: Array.from(t.flags.bits),
+                trapFlagNames: serializeTrapFlags(t.flags),
             })),
         });
     }