@rpgm-tools/neo-angband-core 0.10.0

package/dist/session/game.js

@@ -0,0 +1,2880 @@
+/**
+ * New-game assembly: pack in, a live GameState the turn loop can run.
+ *
+ * bootLevel (boot.ts) produces the world and the spot the player would
+ * occupy; this adds the missing half - birthing a player character and
+ * wiring it, the generated monsters, and the action registry into the
+ * GameState the loop operates on. It is the smallest "start a playable
+ * game" entry point and, like the rest of the boot seam, is headless and
+ * takes already-parsed pack JSON so it serves tests and any front end.
+ *
+ * It composes public domain APIs only and adds no rules: generatePlayer
+ * (birth), calcBonuses (derived combat/defence), and the context helpers
+ * that place the player and register the monsters.
+ *
+ * Race and class default to Human Warrior; pass raceName/className to
+ * override. Decision 6.2 stream order matches C player-birth.c:1269-1292 +
+ * ui-game.c:757-760: store_reset, seed_randart, seed_flavor (back-to-back),
+ * then prepare_next_level generation.
+ */
+import { loc } from "../loc.js";
+import { MessageLog } from "../msg.js";
+import { SKILL, STAT_MAX } from "../player/types.js";
+import { EF, ELEM, HIST, OF, PF, RF, STAT, TMD } from "../generated/index.js";
+import { bindPlayer } from "../player/bind.js";
+import { generatePlayer, optionsInitCheat, flavorSetAllAware, } from "../player/birth.js";
+import { bonusChangeMessages, calcBonuses, calcHitpoints, toCombatState, toDefenderState, } from "../player/calcs.js";
+import { playerBestDiggerDigging, playerBestDiggerWithClause, } from "../player/best-digger.js";
+import { playerExpGain, playerKillExp } from "../player/exp.js";
+import { historyAdd, historyFindArtifact, historyLoseArtifact } from "../player/history.js";
+import { artifactHistoryName, historyStamp } from "../game/history.js";
+import { makePlayerSideEffects, makeIncCheckQueries } from "../game/player-side.js";
+import { makeTakeHitHooks } from "../game/take-hit-hooks.js";
+import { makeMonBlowEnv } from "../game/mon-side.js";
+import { adj_dex_safe } from "../player/calcs.js";
+import { processCurseTimeouts } from "../game/curse-tick.js";
+import { buildEffectContext } from "../game/effect-env.js";
+import { attachGameEnv } from "../game/effect-game-env.js";
+import { sourceMonster, sourceNone, sourcePlayer } from "../effects/interpreter.js";
+import { DEFAULT_GAME_CONSTANTS, addMonster, deleteMonster, placePlayer, squareMonster, updateMonsterDistances, } from "../game/context.js";
+import { Chunk } from "../world/chunk.js";
+import { chunkWriteTerrain } from "../gen/cave.js";
+import { FEAT, SQUARE } from "../generated/index.js";
+import { blankMonster } from "../mon/monster.js";
+import { MON_GROUP } from "../mon/types.js";
+import { monsterGroupAssign, monsterGroupsVerify } from "../game/mon-group.js";
+import { floorCarry, floorObjectForUse, floorPile } from "../game/floor.js";
+import { installPickup } from "../game/pickup.js";
+import { IgnoreSettings, ignoreItemOk } from "../obj/ignore.js";
+import { EffectRegistry } from "../effects/interpreter.js";
+import { registerCoreHandlers } from "../effects/handlers.js";
+import { registerAttackHandlers } from "../game/effect-attack.js";
+import { registerGeneralHandlers } from "../game/effect-general.js";
+import { registerMonsterHandlers } from "../game/effect-monster.js";
+import { registerTeleportHandlers, teleportMonster } from "../game/effect-teleport.js";
+import { registerTerrainHandlers, wizLightLevel } from "../game/effect-terrain.js";
+import { registerItemHandlers } from "../game/effect-item.js";
+import { registerMeleeHandlers } from "../game/effect-melee.js";
+import { registerSummonHandlers } from "../game/effect-summon.js";
+import { registerDetectHandlers } from "../game/effect-detect.js";
+import { becomeAware, caveIlluminateKnown, caveKnown, newKnownMap, noteSpots, viewerStateOf, } from "../game/known.js";
+import { updateView } from "../world/view.js";
+import { PY_EXERT, compactMonsters, isDaytime, playerOverExert } from "../game/world.js";
+import { restoreMonsters } from "../game/scheduler.js";
+import { newTargetState, targetSetMonster } from "../game/target.js";
+import { getLore, loreCountU16, loreLearnFlagIfVisible, loreLearnSpellIfVisible, loreUpdate, } from "../mon/lore.js";
+import { monsterIsVisible } from "../mon/predicate.js";
+import { countMonsterRaces, multiplyMonster, pickAndPlaceDistantMonster, squareIsEmptyLive, wipeMonsterCounts, } from "../game/mon-place.js";
+import { SummonTable } from "../mon/summon.js";
+import { MonAllocTable } from "../mon/make.js";
+import { thrustAway } from "../game/thrust.js";
+import { basicPlayerActor } from "../game/project-cast.js";
+import { installMonsterCasting } from "../game/mon-ranged.js";
+import { buildMonSpellHooks, buildFailRuneEnv } from "../game/mon-cast.js";
+import { installMonCommand } from "../game/mon-cmd.js";
+import { monsterChangeShape, monsterRevertShape } from "../game/mon-shape.js";
+import { installMonTimedLore } from "../mon/timed.js";
+import { applyAutoinscription, autoinscribeGround, autoinscribePack, installObjCommands, packOverflow, } from "../game/obj-cmd.js";
+import { displayFeeling, installCaveCommands, movementAutoDig } from "../game/cave-cmd.js";
+import { installSteal } from "../game/steal.js";
+import { calcUnlockingChance, installChunkFeatHook, installTrap, installTraps, playerIsTrapsafe, squareDoorPower, squareIsPlayerTrap, squareIsWarded, squareIsWebbed, squareRemoveAllTraps, squareSetDoorLock, trapPredicates, } from "../game/trap.js";
+import { lookupTrap } from "../world/trap.js";
+import { calcMana, calcSpells, cumberArmorFrom, playerSpellsInit, registerBookKinds, } from "../player/spell.js";
+import { installSpellCommands, makeSpellChanceEnv } from "../game/spell-cmd.js";
+import { installRangedCommands } from "../game/ranged-cmd.js";
+import { markNoscore, NOSCORE } from "../game/wizard.js";
+import { createTownStores, storeUpdate, storeWillBuy } from "../store/store.js";
+import { homeCarry, homeRetrieve, homeStash, storeBuy, storeSell, storeSellFloor, } from "../store/transact.js";
+import { storeCheckNum } from "../store/store.js";
+import { priceItem } from "../store/price.js";
+import { formatMonsterMessage, formatMonsterMessageByName, formatMonsterMessageShowDamage, formatPainMessage, formatPainMessageShowDamage, monMessageSoundType, painMessageCode, } from "../game/mon-message.js";
+import { AutoinscriptionRegistry, RuneNoteRegistry, buildRuneList, runeKey, FlavorKnowledge, EverseenKnowledge, equipLearnElement, makeRuneEnv, NOOP_FLAVOR_AWARE_DEPS, OBJ_NOTICE, objectLearnOnWield, playerLearnInnate, playerLearnAllRunes, } from "../obj/knowledge.js";
+import { flavorInit } from "../obj/flavor.js";
+import { ELEM_MAX } from "../obj/types.js";
+import { ArtifactState, ObjAllocState } from "../obj/make.js";
+import { monsterDeath, installNonplayerHitDeps } from "../game/mon-death.js";
+import { newGear, outfitPlayer, gearGet, calcInventory, minusAc as applyMinusAc, objectCopyAmt, } from "../game/gear.js";
+import { objectValue as computeObjectValue } from "../obj/value.js";
+import { buildCurseTimedFoil } from "../obj/object.js";
+import { createDefaultRegistry, installMeleeSideEffects, search } from "../game/player-turn.js";
+import { buildTempBrandSlay, playerIncCheck } from "../player/timed.js";
+import { disturb, installRunning } from "../game/player-path.js";
+import { bindCore, bootLevel, genDeps } from "./boot.js";
+import { dungeonGetNextLevel, isQuest, playerQuestsReset, questCheck, } from "../game/quest.js";
+import { Rng } from "../rng.js";
+import { OptionState } from "../player/options.js";
+import { doRandart, RANDNAME_TOLKIEN } from "../obj/randart.js";
+import { makeActivationSummarizer } from "../obj/effects-info.js";
+import { generateLevel, getJoinInfo } from "../gen/generate.js";
+import { iToGrid } from "../gen/util.js";
+import { SAVE_VERSION, deserializeAutoinscriptions, deserializeEverseen, deserializeFlavor, deserializeIgnore, deserializeChunk, deserializeFloor, buildFeatRemap, deserializeArtifactsCreated, deserializeArtifactFlags, deserializeGear, deserializeKnown, deserializeLevelCache, deserializeLore, deserializeMessages, deserializeMonster, deserializePlayer, deserializeStores, deserializeTraps, serializeGame, } from "./save.js";
+import { ContentIdResolver } from "../mod/ids.js";
+import { coreOnlyManifest, quarantineSave, rehydrateSave, } from "../mod/save-blocks.js";
+/**
+ * The getItem seam body (cmd_get_item's "tgtitem" fast path, cmd-core.c L1060):
+ * resolve the shell's preset target (a gear handle or a floor-pile index) to a
+ * live object. If it resolves and passes the request's tester, consume the
+ * one-shot preset and return it; otherwise record the unfulfilled request and
+ * return null - the faithful cancel/abort (C falls through a filter-failing
+ * preset to the blocking prompt, which the port cannot do mid-turn). Draws no
+ * RNG.
+ */
+export function resolveTargetItem(state, req) {
+    const ref = state.itemTarget;
+    let obj = null;
+    if (ref) {
+        if ("handle" in ref) {
+            obj = gearGet(state.gear, ref.handle);
+        }
+        else {
+            obj = floorPile(state, state.actor.grid)[ref.floor] ?? null;
+        }
+    }
+    if (obj && req.tester(obj)) {
+        /* One-shot: clear so a two-prompt effect cannot reuse the same object. */
+        state.itemTarget = null;
+        return obj;
+    }
+    state.itemRequest = req;
+    return null;
+}
+/**
+ * The chooseCurse seam body (get_curse, effect-handler-general.c): return the
+ * shell's preset curse index when it is one of the removable curses, else the
+ * first removable one (upstream get_curse's default highlight), else null. No
+ * RNG - get_curse is a pure menu.
+ */
+export function resolveTargetCurse(state, removable) {
+    const preset = state.curseTarget;
+    if (preset !== null && preset !== undefined && removable.includes(preset)) {
+        return preset;
+    }
+    return removable[0] ?? null;
+}
+/**
+ * The real, in-play FlavorAwareDeps for object_flavor_aware's ignore fix
+ * (obj-knowledge.c L2276-2279, #89): reads the live ignore settings so a
+ * kind ignored while unaware keeps being ignored once identified, and flags
+ * player->upkeep->notice's PN_IGNORE (state.noticeIgnore) so a later
+ * ignore_drop() pass (#25 UI, not yet wired) can react. Shared by the two
+ * in-play becomes-aware sites: game/obj-cmd.ts's item-use knowledge gain
+ * (installObjCommands below) and store/transact.ts's buy/sell (makeStoreApi).
+ */
+function flavorAwareDeps(state) {
+    return {
+        isIgnoredUnaware: (kidx) => state.ignore.kindIsIgnoredUnaware(kidx),
+        ignoreWhenAware: (kidx) => state.ignore.kindIgnoreWhenAware(kidx),
+        requestIgnoreNotice: () => {
+            state.noticeIgnore = true;
+        },
+    };
+}
+/**
+ * Install every command and effect-stack seam on a constructed GameState:
+ * pickup, the effect interpreter (monster casting, item use, player
+ * spells), traps (disarm + the step hook) and the cave commands with the
+ * lock seams. Shared by startGame and loadGame; the same state object is
+ * captured by every closure, so a level change may swap the state's chunk
+ * and entity stores in place without rewiring.
+ */
+function wireGame(state, reg, players, pstate, seedFlavor, pack) {
+    // Rolling message log (message.c file-statics; gap 12.8). Shared producer for
+    // both new-game and load paths: startGame arrives with no log so this creates
+    // it; loadGame already restored one via deserializeMessages, so preserve it
+    // (??=) rather than clobber. The shell's message sink (state.msg) appends here
+    // in addition to its existing routing.
+    state.messages ??= new MessageLog();
+    // Live commands over the floor piles: 'g'et + autopickup on stepping.
+    const registry = createDefaultRegistry();
+    const flavor = new FlavorKnowledge(reg.objects.ordinaryKindCount);
+    // kind/ego everseen (object_kind/ego_item everseen): one per-game store, read
+    // by the object + ego knowledge browsers and marked on live describes via
+    // knownDescOf (game/describe.ts) and for bought start items (startGame).
+    const everseen = new EverseenKnowledge();
+    state.everseen = everseen;
+    // flavor_init (obj-util.c): assign each flavoured kind a colour/adjective and
+    // mark the non-flavoured ordinary kinds aware. Deterministic in seedFlavor,
+    // so a save/reload reproduces identical flavours. The assignment feeds the
+    // object_desc name seams below (state.hasFlavor / state.flavorText).
+    const flavorAssignment = flavorInit(seedFlavor, flavor, {
+        kinds: reg.objects.kinds,
+        flavors: reg.objects.flavors,
+        ordinaryKindCount: reg.objects.ordinaryKindCount,
+        nameSections: reg.nameSections,
+        /* OPT(player, birth_randarts): scrub the fixed flavours so the randart
+         * set's items are not pre-identified by their standard colour/adjective. */
+        birthRandarts: state.options?.get("birth_randarts") ?? false,
+    });
+    state.hasFlavor = (kind) => flavorAssignment.hasFlavor(kind);
+    state.flavorText = (kind) => flavorAssignment.text(kind);
+    state.flavorGlyph = (kind) => flavorAssignment.get(kind);
+    // ignore_item_ok (obj-ignore.c): the player's ignore settings resolved with
+    // live flavor awareness. Everything reads it through state.isIgnored so the
+    // floor / pickup / running / projection paths need no flavor coupling.
+    state.isIgnored = (obj) => ignoreItemOk(obj, state.ignore, flavor.isAware(obj.kind));
+    // object_flavor_is_aware (obj-knowledge.c): the presentation view models
+    // (obj-list.c, #25) read kind awareness through this seam, keeping them
+    // decoupled from the flavor store just like isIgnored.
+    state.isAware = (kind) => flavor.isAware(kind);
+    // The flavor store + its object_flavor_aware side-channel, exposed so the
+    // game-layer knowledge sweep (game/known.ts updatePlayerObjectKnowledge, the
+    // port of update_player_object_knowledge) can flip a kind aware when a
+    // rune-learn completes a carried jewel's runes (KN-03).
+    state.flavorKnown = flavor;
+    state.flavorAwareDeps = flavorAwareDeps(state);
+    installPickup(state, registry, {
+        constants: reg.constants,
+        env: { isIgnored: (obj) => state.isIgnored(obj) },
+        /* PU_INVEN after inven_carry (see PickupDeps.refreshInventory): route
+         * picked-up ammo into the quiver. Same calc_inventory opts as the store
+         * refreshQuiver and object-command paths. */
+        refreshInventory: () => {
+            calcInventory(state.gear, reg.constants, {
+                store: false,
+                /* earlier_object reads player->state.ammo_tval off the global player
+                 * (player-calcs.c:954-959), so EVERY caller must supply the live value
+                 * -- omitting it here silently sorted the quiver as if no launcher were
+                 * wielded, so a picked-up usable arrow lost its precedence over
+                 * unusable ammo. Same source calcInvOpts uses (obj-cmd.ts:168). */
+                ammoTval: state.playerState?.ammoTval ?? 0,
+                objectValue: (obj) => computeObjectValue(reg.objects, obj, 1, true),
+                rogueLike: state.options?.get("rogue_like_commands") ?? false,
+                characterDungeon: true,
+                msg: (text) => state.msg?.(text),
+            });
+        },
+    });
+    // Rune learning (obj-knowledge.c learn-by-use): the registry tables plus
+    // live equipment access. Reads through the state object so level changes
+    // and gear swaps need no rewiring.
+    state.runeEnv = makeRuneEnv((slot) => state.gear.store.get(state.actor.player.equipment[slot] ?? 0) ?? null, (v) => state.rng.randcalcVaries(v), {
+        brands: reg.objects.brands,
+        slays: reg.objects.slays,
+        curses: reg.objects.curses,
+        properties: reg.objects.properties,
+        ...(reg.projections
+            ? {
+                elementNames: reg.projections
+                    .slice(0, ELEM_MAX)
+                    .map((p) => p.name),
+            }
+            : {}),
+        flavor,
+    });
+    // The live derived state (upstream p->state). refreshDerived is the
+    // port's PU_BONUS | PU_HP | PU_MANA: recompute from the current gear,
+    // refresh the actor (including the wielded weapon), re-derive hitpoints
+    // from the rolled hitdice and mana from the armor encumbrance. Installed
+    // as state.updateBonuses so equipment commands trigger it.
+    let derived = pstate;
+    // Expose the live derived state so update_mon reads the current OF flags
+    // (telepathy / see-invisible) and see_infra. refreshDerived reassigns it.
+    state.playerState = derived;
+    // A stable live copy of state->stat_ind: refreshDerived replaces the whole
+    // derived PlayerState (new statInd array), so anything that captured
+    // pstate.statInd would freeze at birth values. This array keeps the same
+    // reference and is refreshed in place, so the casting math and a shell's
+    // fail-chance display always read the current stats.
+    const liveStatInd = [...pstate.statInd];
+    state.statInd = liveStatInd;
+    const refreshDerived = () => {
+        const p = state.actor.player;
+        const equipment = p.equipment.map((h) => h ? gearGet(state.gear, h) : null);
+        const daytime = isDaytime(state.turn, state.z.dayLength);
+        /* p->state before the memcpy at the end of calc_bonuses: the encumbrance
+         * notices below diff against it (player-calcs.c:2412-2453). */
+        const before = derived;
+        derived = calcBonuses(p, {
+            equipment,
+            timedEffects: players.timed,
+            curses: reg.objects.curses,
+            update: true,
+            depth: state.chunk.depth,
+            isDaytime: daytime,
+        });
+        state.playerState = derived;
+        /* calc_light's town-daytime branch (player-calcs.c 1608-1611) flags
+         * PU_UPDATE_VIEW | PU_MONSTERS before returning; reinstate that refresh so
+         * ambient town light tracks the day/night cycle. */
+        if (state.chunk.depth === 0 && daytime)
+            state.updateFov?.(state);
+        for (let i = 0; i < liveStatInd.length; i++) {
+            liveStatInd[i] = derived.statInd[i] ?? 0;
+        }
+        const combat = toCombatState(derived);
+        state.actor.combat = combat;
+        state.actor.defense = toDefenderState(derived);
+        state.actor.speed = derived.speed;
+        state.actor.light = derived.curLight;
+        state.actor.unlight = derived.pflags.has(PF.UNLIGHT);
+        state.actor.stealth = combat.skills[SKILL.STEALTH] ?? 0;
+        const weaponSlot = p.body.slots.findIndex((s) => s.type === "WEAPON");
+        state.actor.weapon =
+            weaponSlot >= 0 ? (equipment[weaponSlot] ?? null) : null;
+        /* calc_hitpoints from the rolled hitdice (CON may have changed). */
+        p.mhp = calcHitpoints(p.playerHp[p.lev - 1] ?? p.hitdie, p.lev, derived.statInd[STAT.CON] ?? 0);
+        if (p.chp > p.mhp)
+            p.chp = p.mhp;
+        /* calc_mana with the worn-armor encumbrance. It owns state->cumber_armor
+         * (player-calcs.c:1503, :1528), so record it before the diff below reads
+         * it - upstream's calc_mana runs inside calc_bonuses, ahead of the
+         * notices. */
+        derived.cumberArmor = calcMana(p, derived.statInd, wornArmorWeight(p, equipment));
+        if (p.csp > p.msp)
+            p.csp = p.msp;
+        /* The state-change notices at the end of calc_bonuses (2412-2453). Emitted
+         * last because cumber_armor is only known once calc_mana has run. */
+        const weaponSlotIdx = p.body.slots.findIndex((s) => s.type === "WEAPON");
+        const bowSlotIdx = p.body.slots.findIndex((s) => s.type === "BOW");
+        for (const text of bonusChangeMessages(before, derived, {
+            hasWeapon: weaponSlotIdx >= 0 && !!equipment[weaponSlotIdx],
+            hasLauncher: bowSlotIdx >= 0 && !!equipment[bowSlotIdx],
+        })) {
+            state.msg?.(text);
+        }
+    };
+    state.updateBonuses = refreshDerived;
+    /**
+     * update_stuff's PU_UPDATE_VIEW arm (player-calcs.c:2608), as the DEFAULT.
+     *
+     * `state.updateFov` is a host seam that core already calls from ~25 sites - the
+     * level-entry flood, the after-action refresh in player-turn.ts, every terrain
+     * and light effect. All of them are `?.`, and core supplied no default, so a
+     * host that did not install one got silence from every one of them. Measured on
+     * a fresh startGame boot with no host wiring: of 12740 cells, `known` was true
+     * for 0 and `inView` for 0, including the player's own square. The engine was
+     * complete and every caller was wired; the DEFAULT was the missing piece, and
+     * an agent driving the frozen agent API therefore had no map at all.
+     *
+     * Invisible until something drove it: the web shell installs its own (main.ts,
+     * routing view events at its sound bus) and the Borg's tests use a hand-built
+     * fake AgentView, so no test in the repository ever ran core's perceive path
+     * with nothing installed.
+     *
+     * `??=` rather than `=`: a host that wants its own events bus or light sources
+     * still replaces this, and the web does. Wired in wireGame so startGame and
+     * loadGame both get it - a resumed character has the same right to a map as a
+     * new one.
+     *
+     * The viewer fields come from `viewerStateOf` (game/known.ts) rather than being
+     * spelled out again here, because spelling them out twice is how both hosts came
+     * to pass `chunk.depth` where cave-view.c:778 reads `p->lev`.
+     */
+    state.updateFov ??= (s) => {
+        updateView(s.chunk, viewerStateOf(s), { maxSight: reg.constants.maxSight, feelingNeed: reg.constants.feelingNeed }, [], s.events);
+        noteSpots(s);
+    };
+    /* game-world.c:941-947: the C refreshes upkeep->inven[] before its
+     * catch-all pack_overflow(NULL).  This closure has the same live
+     * calc_inventory inputs used by pickup and command paths, preserving the
+     * earlier_object order of the derived gear.inven view. */
+    state.overflowPack = () => {
+        const calcInv = {
+            ammoTval: state.playerState?.ammoTval ?? 0,
+            objectValue: (obj) => computeObjectValue(reg.objects, obj, 1, true),
+            rogueLike: state.options?.get("rogue_like_commands") ?? false,
+            characterDungeon: true,
+            ...(state.msg ? { msg: state.msg } : {}),
+        };
+        /* notice_stuff()/handle_stuff() precede pack_overflow(NULL) at
+         * game-world.c:941-947; materialize the current upkeep->inven[] analogue
+         * before selecting its final entry. */
+        calcInventory(state.gear, reg.constants, calcInv);
+        packOverflow(state, 0, reg.constants, {
+            calcInv,
+            ...(state.msg ? { msg: state.msg } : {}),
+        });
+    };
+    /* Stash the class list so refreshTownStores can expand the bookseller's
+     * town-book always lines (object_kind_to_book, store.c:208-231). */
+    state.classes = players.classes;
+    // player_best_digger (player-util.c L744): digging temporarily wields the
+    // pack's best digger and recomputes calc_bonuses (update=false, no RNG) to
+    // read its DIGGING; this closes over the same calc_bonuses options as
+    // refreshDerived so the swapped derive matches upstream. Feeds the existing
+    // randint0(1600) dig roll (game/cave-cmd.ts tunnelAux, game/player-path.ts
+    // rubblePenalty) without adding or reordering any draw.
+    state.bestDiggerDigging = () => {
+        const p = state.actor.player;
+        const equipment = p.equipment.map((h) => h ? gearGet(state.gear, h) : null);
+        const weaponSlot = p.body.slots.findIndex((s) => s.type === "WEAPON");
+        const daytime = isDaytime(state.turn, state.z.dayLength);
+        return playerBestDiggerDigging(equipment, [...state.gear.store.values()], weaponSlot, (equip) => calcBonuses(p, {
+            equipment: equip,
+            timedEffects: players.timed,
+            curses: reg.objects.curses,
+            update: false,
+            depth: state.chunk.depth,
+            isDaytime: daytime,
+        }).skills[SKILL.DIGGING] ?? 0);
+    };
+    /* The same swap decision as a string, for tunnel_aux's with_clause
+     * (cmd-cave.c:541, :552) - "with your hands" / "with your weapon" / "with
+     * your swap digger". Shares bestDiggerSwap with the roll above so the
+     * message and the chance can never disagree. */
+    const digWithClause = () => {
+        const p = state.actor.player;
+        const equipment = p.equipment.map((h) => h ? gearGet(state.gear, h) : null);
+        const weaponSlot = p.body.slots.findIndex((s) => s.type === "WEAPON");
+        const daytime = isDaytime(state.turn, state.z.dayLength);
+        return playerBestDiggerWithClause(equipment, [...state.gear.store.values()], weaponSlot, (equip) => calcBonuses(p, {
+            equipment: equip,
+            timedEffects: players.timed,
+            curses: reg.objects.curses,
+            update: false,
+            depth: state.chunk.depth,
+            isDaytime: daytime,
+        }).skills[SKILL.DIGGING] ?? 0);
+    };
+    // Experience (player.c): a level change recomputes the derived state
+    // (upstream's PU_BONUS | PU_HP | PU_SPELLS), and a player kill rewards
+    // mexp * rlev / plev with the fractional carry.
+    const expDeps = {
+        rng: state.rng,
+        /* msgt(MSG_LEVEL, "Welcome to level %d.") (player.c L250). This sink was
+         * missing, so every level-up was silent: the level and max HP simply
+         * changed on the status line with no message at all. */
+        msg: (text, type) => state.msg?.(text, type),
+        onLevelChange: (p) => {
+            refreshDerived();
+            /* Casters learn/forget spells at the new level; calcSpells announces the
+             * new allowance ("You can learn N more spells.") on a change, as C's
+             * calc_bonuses->calc_spells does (player-calcs.c:1465). */
+            calcSpells(p, derived.statInd, (text) => state.msg?.(text));
+        },
+        /* history_add(HIST_GAIN_LEVEL) (player.c L246-247), fired from inside
+         * adjustLevel's up-loop before the "Welcome to level" message. */
+        onGainLevel: (p, lev) => {
+            const stamp = historyStamp(state);
+            historyAdd(p, `Reached level ${lev}`, HIST.GAIN_LEVEL, stamp.dlev, lev, stamp.turn);
+        },
+    };
+    // Monster-death loot deps (mon_create_drop + monster_death, game/mon-death.ts).
+    // Assigned inside the projections block below once makeDeps, the object
+    // registry, the shared floorEnv and the trap predicates are all available;
+    // onPlayerKill / onMonsterDeath run only after wireGame has finished, so the
+    // deferred assignment is always resolved by the time they fire.
+    let deathDeps;
+    /* become_aware (mon-util.c L711, game/known.ts): reveal a camouflaged
+     * mimic. Installed once here and threaded into every hit / cast / melee
+     * site below so a camouflaged monster unmasks wherever upstream calls
+     * become_aware, instead of the flag never clearing. */
+    state.becomeAware = (mon) => becomeAware(state, mon);
+    state.onPlayerKill = (mon) => {
+        /* Experience comes from the killed form (player_kill_monster computes
+         * new_exp before monster_death's revert). */
+        const expRace = mon.race;
+        /* Shapechanged monsters revert on death (mon-util.c L1027). */
+        monsterRevertShape(state, mon);
+        /* player_kill_monster: dead uniques stay dead (max_num = 0). The flag
+         * is session-lifetime; persisting it rides the save format (ledgered). */
+        if (mon.race.flags.has(RF.UNIQUE)) {
+            /* bug-fixes #4245 ("Unique coming back to life?"): a unique can produce
+             * multiple "Killed X" kill-history entries via shape-change / projection
+             * death paths (the misleading death MESSAGE was fixed by PR #6245, in the
+             * 4.2.6 baseline, but its author states that does NOT fix the multiple-
+             * history-entries defect). With bugfix.uniqueKillHistory on, a second kill
+             * of an already-dead unique (race.maxNum already 0) does not log a duplicate
+             * entry; faithful 4.2.6 logs one per lethal blow. Read BEFORE max_num=0. */
+            const alreadyDead = mon.race.maxNum === 0;
+            mon.race.maxNum = 0;
+            /* history_add(HIST_SLAY_UNIQUE) (mon-util.c L1099-1101), read BEFORE
+             * playerKillExp below so p.lev is the pre-kill level, matching
+             * upstream's history_add-before-player_exp_gain order. MDESC_DIED_FROM
+             * for a unique is just the race name (no article/pronoun swap), so no
+             * MDESC subsystem is needed here. */
+            /* The history seam (mod/hooks.ts historyAdd). Faithful 4.2.6 logs one entry
+             * per lethal blow, duplicates included, so with no hook installed the
+             * `?? true` below IS the faithful answer. `duplicate` tells a mod what it
+             * needs to decide without core deciding anything. */
+            const what = `Killed ${mon.race.name}`;
+            const wanted = state.modHooks?.historyAdd?.({
+                what,
+                type: HIST.SLAY_UNIQUE,
+                duplicate: alreadyDead,
+            }) ?? true;
+            if (wanted) {
+                const stamp = historyStamp(state);
+                historyAdd(state.actor.player, what, HIST.SLAY_UNIQUE, stamp.dlev, stamp.clev, stamp.turn);
+            }
+        }
+        /* Generate treasure (monster_death, mon-util.c L1108) BEFORE the pkills /
+         * tkills lore counting (L1118), so loreUpdate below sees any drop_gold /
+         * drop_item that loreTreasure records. */
+        if (deathDeps)
+            monsterDeath(state, mon, deathDeps);
+        /* quest_check (player-quest.c L219, called at the end of monster_death,
+         * mon-util.c L1005): a slain guardian may finish a quest, build the
+         * escape stairs, and - when the last quest falls (Morgoth) - win the
+         * game. Placed here so every player-kill path (melee, ranged, spells,
+         * effects) triggers it exactly once through this single seam. */
+        questCheck(state, state.actor.player, mon);
+        /* Recall even invisible uniques (mon-util.c L1118): count the kill
+         * and refresh the derived lore (monster_race_track rides #25). */
+        if (monsterIsVisible(mon) || mon.race.flags.has(RF.UNIQUE)) {
+            const lore = getLore(state.lore, mon.race);
+            loreCountU16(lore, "pkills");
+            loreCountU16(lore, "tkills");
+            loreUpdate(mon.race, lore);
+        }
+        playerKillExp(state.actor.player, expRace, expDeps);
+    };
+    const expGain = (amount) => playerExpGain(state.actor.player, amount, expDeps);
+    // object_touch's history_find_artifact (obj-knowledge.c L960-972): fires
+    // when an artifact enters the pack (pickup.ts's playerPickupAux). The
+    // name builder is RNG-free (game/history.ts artifactHistoryName).
+    state.onArtifactFound = (art) => {
+        const stamp = historyStamp(state);
+        historyFindArtifact(state.actor.player, art, stamp.dlev, stamp.clev, stamp.turn, (a) => artifactHistoryName(state, reg.objects, reg.constants, a));
+    };
+    // history_lose_artifact (player-history.c L246): an artifact is destroyed,
+    // abandoned on a regenerated level, or discarded by a store. RNG-free name.
+    state.onArtifactLost = (art) => {
+        const stamp = historyStamp(state);
+        historyLoseArtifact(state.actor.player, art, stamp.dlev, stamp.clev, stamp.turn, (a) => artifactHistoryName(state, reg.objects, reg.constants, a));
+    };
+    // The effect stack: with bound projections, monsters cast spells on
+    // their turns (make_ranged_attack), items are usable (cmd-obj.c), the
+    // player casts (player-spell.c) and traps fire (trap.c) - all through
+    // the same effect interpreter.
+    let trapDeps = null;
+    let chestDeps = null;
+    /* Hoisted so the wired result can surface it to the host (W2.2 mod facade);
+     * assigned inside the projections block below, null on a worldless boot. */
+    let effectRegistry = null;
+    /* The wizard/debug effect bundle (WP-14): the same effect_simple stack items
+     * and spells run through, assembled once the block's locals exist. undefined
+     * on a worldless boot, where the wizard effect commands are inert anyway. */
+    let wizardEffect = undefined;
+    /* obj_kind_can_browse(kind) for the birthed class (obj-tval.c): the set of
+     * this character's readable spellbook kinds (tval,sval), stamped by
+     * registerBookKinds. make_object uses it to reject unreadable books (gap 3.5).
+     * Empty for a non-caster class, so it rejects every book (faithful). */
+    const classBookKeys = new Set(state.actor.player.cls.magic.books.map((b) => `${b.tvalIdx},${b.sval}`));
+    const makeDeps = {
+        reg: reg.objects,
+        alloc: new ObjAllocState(reg.objects, reg.constants),
+        constants: reg.constants,
+        artifacts: state.artifacts ?? new ArtifactState(reg.objects.artifacts.length),
+        noArtifacts: state.options?.get("birth_no_artifacts") ?? false,
+        /* The mod behaviour seam: read state.modHooks LIVE, not captured, so a mod
+         * that installs a hook at boot (after wireGame builds this) is still seen.
+         * Absent => makeArtifact's faithful branch, which is the only branch. */
+        get hooks() {
+            return state.modHooks;
+        },
+        /* append_object_curse TIMED_INC foil (obj-curse.c L159-188, gap 3.2):
+         * reject a curse an existing item property would foil, built from the bound
+         * player-timed fail tables. */
+        timedFoil: buildCurseTimedFoil(players.timed),
+        /* obj_kind_can_browse book rejection (obj-make.c L1187-1194, gap 3.5). */
+        canBrowseBook: (kind) => classBookKeys.has(`${kind.tval},${kind.sval}`),
+        /* make_gold birth_no_selling 5x dungeon inflation (obj-make.c L1310-1312,
+         * gap 3.7). */
+        noSelling: state.options?.get("birth_no_selling") ?? false,
+    };
+    /* The one complete player take_hit consequences object, shared by every
+     * damage site (projections, melee via mon-side, effects via envDeps, DoT /
+     * terrain via state.world). Defined out here so both the projections block
+     * and the state.world assignment below reference the same object. Wiring
+     * onDeath is what finally records died_from + clears total_winner on death
+     * (audit 01 P1 CRITICAL). wizardEffect.current is filled once the effect
+     * stack exists so EVENT_CHEAT_DEATH can call wizCheatDeath (W2-009). */
+    const wizardEffectHolder = {
+        current: undefined,
+    };
+    const sharedTakeHitHooks = makeTakeHitHooks(state, {
+        wizardEffect: wizardEffectHolder,
+    });
+    /* on_begin_effect / on_end_effect dispatch for timed transitions (audit 01
+     * T2, player-timed.c:873-891). Assigned inside the projections block where the
+     * effect registry + env exist, and read by the world-clock timedHooks
+     * (function-body scope, like sharedTakeHitHooks). Undefined when no effect
+     * stack is built (headless save inspection); then transitions run no chain. */
+    let runTimedTransition;
+    if (reg.projections) {
+        const effects = new EffectRegistry();
+        effectRegistry = effects;
+        registerCoreHandlers(effects);
+        registerAttackHandlers(effects);
+        registerMonsterHandlers(effects);
+        registerTeleportHandlers(effects);
+        registerGeneralHandlers(effects);
+        registerTerrainHandlers(effects);
+        registerItemHandlers(effects);
+        registerMeleeHandlers(effects);
+        registerSummonHandlers(effects);
+        registerDetectHandlers(effects);
+        // The trap-backed square predicates feed every consumer that stubbed
+        // them (teleport landing checks, drop placement) once traps exist.
+        const preds = reg.traps ? trapPredicates(state) : null;
+        // The shared floor drop environment (drop_near's ignore / trap rules),
+        // used by both the object commands and monster-death loot so a kill's
+        // drops land under the same placement rules as any other floor drop.
+        const floorEnv = {
+            isIgnored: (obj) => state.isIgnored(obj),
+            ...(preds ? { isTrap: preds.isTrap } : {}),
+        };
+        // Monster-death loot deps: makeDeps builds the objects, reg.objects looks
+        // up specified drops, floorEnv places them, state.lore feeds the theft
+        // reduction and loreTreasure.
+        deathDeps = {
+            makeDeps,
+            reg: reg.objects,
+            floorEnv,
+            lore: state.lore,
+        };
+        const teleport = preds
+            ? {
+                isPlayerTrap: preds.isPlayerTrap,
+                isWarded: preds.isWarded,
+                isWebbed: preds.isWebbed,
+                /* is_quest (player-quest.c L140): the real implementation behind the
+                 * force_descend / teleport-level guards (effect-general.ts,
+                 * effect-teleport.ts, effect-terrain.ts) - a quest level cannot be
+                 * skipped or recalled away from. */
+                isQuest: (depth) => isQuest(state.actor.player, depth),
+                /* dungeon_get_next_level (player-util.c:1147). This seam existed but
+                 * nothing ever wired it, so every consumer silently degraded to a
+                 * bare `depth + dir` - no stair_skip, no max_depth clamp and, worst,
+                 * no quest scan. */
+                getNextLevel: (from, dir) => dungeonGetNextLevel(state.actor.player, from, dir, state.z),
+                changeLevel: (targetDepth) => {
+                    state.targetDepth = targetDepth;
+                    state.generateLevel = true;
+                },
+                /* player_handle_post_move eval_trap half (player-util.c:1627-1629):
+                 * immediate traps at the landing grid after teleport / thrust. */
+                onPlayerPostMove: (_byMonster) => {
+                    state.onPlayerMoved?.(state, state.actor.grid);
+                },
+            }
+            : undefined;
+        // Glyph / web creation needs the trap system; trapDeps joins below
+        // once it is built (the mutual reference is deliberate). The stat
+        // adjectives (desc_stat) come from the bound object properties, and
+        // experience gains ripple level changes through expDeps.
+        const general = {
+            properties: reg.objects.properties,
+            expDeps,
+            shapes: players.shapes,
+        };
+        // Item-targeting seams: the ego / curse tables, arrow generation, and the
+        // get_item / get_curse choosers. The shell pre-resolves the target object
+        // (async item menu) and rides it on the command as state.itemTarget; these
+        // closures are the sync side of cmd_get_item's "tgtitem" fast path
+        // (cmd-core.c L1060), turning the preset back into a live object without
+        // blocking the turn loop. Absent a preset, the choosing effect aborts (the
+        // upstream cancel path) and records the unfulfilled request for the shell.
+        const item = {
+            reg: reg.objects,
+            makeDeps,
+            getItem: (req) => resolveTargetItem(state, req),
+            chooseCurse: (_obj, removable) => resolveTargetCurse(state, removable),
+        };
+        // Summoning: the bound summon table, the session's live allocation
+        // table (get_mon_num over the full race registry) and the placement
+        // deps. The summonNameToIdx injection lets effect chains resolve
+        // "SUMMON:UNDEAD"-style subtypes at build time.
+        const summons = new SummonTable(reg.monsters.summons, reg.monsters.bases);
+        const summon = {
+            summons,
+            place: {
+                table: new MonAllocTable(reg.monsters.races, {
+                    maxDepth: reg.constants.maxDepth,
+                    oodChance: reg.constants.oodMonsterChance,
+                    oodAmount: reg.constants.oodMonsterAmount,
+                }),
+                groupMax: reg.constants.monsterGroupMax,
+                groupDist: reg.constants.monsterGroupDist,
+                ...(preds ? { preds } : {}),
+            },
+        };
+        const inject = {
+            summonNameToIdx: (name) => summons.nameToIdx(name),
+            /* shape_name_to_idx (player-util.c L987) over lookup_player_shape (L971).
+             * NOTE: upstream matches with streq (z-util.h:157 = strcmp), i.e. CASE
+             * SENSITIVELY, unlike the my_stricmp used by stat_name_to_idx /
+             * proj_name_to_idx. Core shape names ("Pukel-man") are cited with exact
+             * case in class.txt so the two agree on stock data; this stays
+             * case-insensitive because narrowing it would reject mod data the port has
+             * always accepted, and the parity-visible behaviour is identical.
+             * lookup_player_shape's msg("Could not find %s shape!") on failure is a
+             * diagnostic the -1 return covers. */
+            shapeNameToIdx: (name) => players.shapes.findIndex((s) => s.name.toLowerCase() === name.toLowerCase()),
+            /* W2.3 vocabulary extension: resolve effect NAMES beyond the upstream EF
+             * set so a mod can name its own effect codes in pack/effect text. Only
+             * reached after effect_lookup fails (a non-core name), so core effect
+             * text is byte-identical; a string EffectCode dispatches to itself via
+             * the EffectRegistry (mods register string codes through the W2.2
+             * ModRegistryHost.effects facade). Unknown names still return null ->
+             * PARSE_ERROR_INVALID_EFFECT, exactly as before. */
+            lookupEffect: (name) => (effects.isRegistered(name) ? name : null),
+        };
+        // project_o / project_f world access; trapDeps joins it below once the
+        // trap system is wired (the mutual reference is deliberate).
+        const worldEnv = { makeDeps };
+        /* The projection view reads the LIVE derived state, so worn resistance
+         * gear reduces projection damage and equipment swaps take effect. */
+        const playerActor = basicPlayerActor(state, {
+            resistLevel: (t) => derived.elInfo[t]?.resLevel ?? 0,
+            reduction: () => ({
+                damRed: derived.damRed,
+                percDamRed: derived.percDamRed,
+            }),
+            /* minus_ac (obj-gear.c L376-438 / project-player.c L69): a live acid hit
+             * damages a random worn armour piece and halves the damage (gap 6.2/4.2).
+             * Called by project_p only inside adjust_dam's PROJ_ACID branch, so the
+             * armour-damage side effect and its RNG draws fire exactly as upstream. */
+            minusAc: () => applyMinusAc(state.actor.player, state.gear, state.rng, {
+                msg: (text) => state.msg?.(text),
+                updateBonuses: () => state.updateBonuses?.(),
+            }),
+        });
+        const cast = {
+            projections: reg.projections,
+            maxRange: reg.constants.maxRange,
+            playerActor,
+            worldEnv,
+            hooks: {
+                monster: {
+                    /* Spell/device kills reward experience like melee kills. */
+                    onKill: (m) => state.onPlayerKill?.(m),
+                    /* become_aware: reveal a camouflaged monster hit by a projection
+                     * (project_m) or that stopped an effect (PROJECT_STOP). */
+                    becomeAware: (m) => state.becomeAware?.(m),
+                    /* monster_death for a monster-vs-monster kill: no player reward, just
+                     * drops (project-mon.c fires monster_death for these too). */
+                    onMonsterDeath: (m) => {
+                        if (deathDeps)
+                            monsterDeath(state, m, deathDeps);
+                    },
+                    /* add_monster_message: "the kobold dies", "wakes up", "catches
+                     * fire" - the MON_MSG grammar, routed to the game's message sink so
+                     * a shell shows ranged/spell/status monster messages the same way
+                     * melee shows "You hit/slay the X". The projection already gates on
+                     * visibility before calling this. */
+                    message: (m, msgCode, _delay, damage) => {
+                        /* add_monster_message_show_damage (mon-msg.c:288) when the driver
+                         * passed a damage total, else add_monster_message (L252). */
+                        const text = damage === undefined
+                            ? formatMonsterMessage(m, msgCode)
+                            : formatMonsterMessageShowDamage(m, msgCode, damage);
+                        const type = monMessageSoundType(msgCode, m.race);
+                        if (text)
+                            state.msg?.(text, type);
+                        state.sound?.(type);
+                    },
+                    /* OPT(player, show_damage): project_m_player_attack's display_dam
+                     * (project-mon.c:1111) picks the *_show_damage message variants. */
+                    showDamage: state.options?.get("show_damage") ?? false,
+                    /* message_pain: the graded "shrugs off the attack" / "cries out in
+                     * pain" line for a monster hurt but not killed. */
+                    messagePain: (m, dam, showDamage) => {
+                        const text = showDamage
+                            ? formatPainMessageShowDamage(m, dam)
+                            : formatPainMessage(m, dam);
+                        const type = monMessageSoundType(painMessageCode(m, dam), m.race);
+                        if (text)
+                            state.msg?.(text, type);
+                        state.sound?.(type);
+                    },
+                    /* mon_set_timed's queued status messages (slowed, confused, held). */
+                    timedMessage: (m, note) => {
+                        const text = formatMonsterMessageByName(m, note);
+                        if (text)
+                            state.msg?.(text);
+                    },
+                    /* Lore learning when a projection's outcome is seen. */
+                    learnRaceFlag: (m, flag) => loreLearnFlagIfVisible(getLore(state.lore, m.race), m, flag),
+                    learnSpellFlag: (m, flag) => loreLearnSpellIfVisible(getLore(state.lore, m.race), m, flag),
+                    /* monster_revert_shape on death / MON_DRAIN (mon-shape.ts). */
+                    revertShape: (m) => {
+                        monsterRevertShape(state, m);
+                    },
+                    /* PROJ_AWAY_ALL teleports and PROJ_FORCE knockback for monsters. */
+                    teleport: (m, dist) => teleportMonster(state, m.midx, dist, teleport ?? {}),
+                    /* project-mon.c:183-185 / 208-212 + player thrust landing. */
+                    thrustAway: (centre, target, gridsAway) => thrustAway(state, centre, target, gridsAway, {
+                        onPlayerPostMove: () => {
+                            state.onPlayerMoved?.(state, state.actor.grid);
+                        },
+                    }),
+                },
+                /* The per-PROJ player side effects (project-player.c handlers). */
+                player: {
+                    /* OPT(player, show_damage): the extra "you take N damage" lines. */
+                    showDamage: state.options?.get("show_damage") ?? false,
+                    /* project_p's own messages ("You are hit by ...!") and disturb, plus
+                     * the full take_hit consequences. Without these a breath / spell that
+                     * damaged or killed the player was silent and never recorded the
+                     * killer (audit 01 P1 CRITICAL). */
+                    message: (text) => state.msg?.(text),
+                    onDisturb: () => disturb(state),
+                    takeHit: sharedTakeHitHooks,
+                    onSideEffects: makePlayerSideEffects(state, {
+                        timed: players.timed,
+                        actor: playerActor,
+                        projections: reg.projections,
+                        expDeps,
+                        lifeDrainPercent: reg.constants.lifeDrainPercent,
+                        ...(teleport ? { teleport } : {}),
+                    }),
+                    /* adjust_dam(actual=true) equip_learn_element (project-player.c
+                     * L60-62, audit 01 P5): being hit by an element teaches the resist
+                     * rune on worn gear. No RNG. */
+                    equipLearnElement: (resType) => equipLearnElement(state.actor.player, state.runeEnv, resType),
+                },
+                /* health_track (project.c:971-980): a player projection that affected
+                 * exactly one monster, without jumping, recalls and health-tracks it.
+                 *
+                 * This hook was DECLARED in world/project.ts, fired with the right gate,
+                 * and threaded through project-cast.ts - and no production caller ever
+                 * supplied it. Only two tests did, which is exactly why it read as live:
+                 * the call-site census counts references, so a hook referenced only by a
+                 * test is indistinguishable from a wired one. The visible symptom was that
+                 * no bolt or ball spell ever put a monster on the health bar.
+                 *
+                 * project.ts has already applied the one-monster / no-JUMP / player-source
+                 * gate and confirmed a monster is on the grid, so this must not re-check
+                 * them. The gate here is VISIBLE, not obvious - project.c uses
+                 * monster_is_visible. */
+                onTrackMonster: (grid) => {
+                    const mon = squareMonster(state, grid);
+                    if (mon && monsterIsVisible(mon))
+                        state.healthWho = mon;
+                },
+            },
+        };
+        /* player_inc_check resolvers (player-timed.c:945-953, gaps 2.8/6.11): read
+         * the LIVE derived state so EF_TIMED_INC on the player is foiled by a worn
+         * resist ("You resist the effect!") and the resisted LIGHT/SOUND messages
+         * are gated. Absent, every increase was allowed. Same shape as
+         * buildFailRuneEnv / makePlayerSideEffects. */
+        const incQueries = makeIncCheckQueries(state);
+        const envDeps = {
+            timedTable: players.timed,
+            // Effect status/damage messages ("You feel better", "You feel yourself
+            // yanked upwards!") route to the game's message sink so a shell shows
+            // them; absent, they would drop.
+            onMessage: (text, msgt) => state.msg?.(text, msgt),
+            incQueries,
+            /* on_begin_effect / on_end_effect (audit 01 T2): the interpreter timed
+             * path (a SCRAMBLE / SPRINT potion or spell) must run the chain too, not
+             * just the world clock. The thunk reads runTimedTransition (assigned just
+             * below) at call time, so SCRAMBLE_STATS fires when the potion lands. */
+            timedHooks: {
+                onTransition: (idx, begin, canDisturb) => runTimedTransition?.(idx, begin, canDisturb),
+            },
+            /* The shared take_hit consequences, so effect-driven player damage (traps,
+             * EF_DAMAGE, activations, monster casts via mon-cast) shows the message
+             * chain and records died_from on death, exactly like melee/projection. */
+            takeHitHooks: sharedTakeHitHooks,
+        };
+        /* on_begin_effect / on_end_effect chain runner (audit 01 T2): dispatch the
+         * bound chain of the timed effect at `idx` through the live effect stack.
+         * Upstream (player-timed.c:878-889) uses source_none() when can_disturb is
+         * true and source_player() otherwise, so any TIMED_INC in the chain honors
+         * disturbance. Runs SCRAMBLE's SCRAMBLE_STATS / UNSCRAMBLE_STATS and
+         * SPRINT's ending TIMED_INC_NO_RES:SLOW; a no-op for effects with no chain. */
+        runTimedTransition = (idx, begin, canDisturb) => {
+            const eff = players.timed[idx];
+            const chain = begin ? eff?.onBeginEffect : eff?.onEndEffect;
+            if (!chain)
+                return;
+            const origin = canDisturb ? sourceNone() : sourcePlayer();
+            for (const step of chain) {
+                /* The chain effects (SCRAMBLE_STATS etc.) read the full game env, so the
+                 * context must be attachGameEnv-wrapped exactly like the trap/obj-cmd
+                 * paths - a bare buildEffectContext leaves gameEnv() null and they no-op. */
+                const ctx = attachGameEnv(buildEffectContext(state, envDeps), {
+                    state,
+                    cast,
+                    takeHitHooks: sharedTakeHitHooks,
+                    ...(teleport ? { teleport } : {}),
+                    general,
+                    item,
+                    summon,
+                });
+                effects.effectSimple(step.effect, ctx, {
+                    origin,
+                    subtype: step.subtype,
+                    ...(step.dice !== undefined ? { diceString: step.dice } : {}),
+                });
+            }
+        };
+        /* The wizard/debug effect bundle (WP-14): identical to the object-command
+         * and trap effect bundles - registry + the game-env pieces effect_simple
+         * needs. The interactive debug commands (cure/detect/map/teleport/summon-
+         * random/hit-los) run their effect_simple calls over exactly this stack. */
+        wizardEffect = {
+            registry: effects,
+            cast,
+            envDeps,
+            inject,
+            ...(teleport ? { teleport } : {}),
+            general,
+            item,
+            summon,
+        };
+        /* Fill the take_hit cheat-death holder so wizCheatDeath can clear timers
+         * (W2-009; ui-display.c EVENT_CHEAT_DEATH). */
+        wizardEffectHolder.current = wizardEffect;
+        /* monster_change_shape / monster_revert_shape, driving the
+         * MON_TMD_CHANGED timer (the SHAPECHANGE monster spell). */
+        const monShape = {
+            change: (m) => monsterChangeShape(state, m, {
+                summon,
+                spells: reg.monsters.spells,
+                ...(teleport ? { teleport } : {}),
+            }),
+            revert: (m) => monsterRevertShape(state, m),
+        };
+        /* spell_message {type}/{oftype} tags resolve the caster's lash projection
+         * name to its lash_desc (mon-spell.c L47-274 tag substitution). */
+        const projLashDesc = new Map();
+        for (const proj of reg.projections)
+            projLashDesc.set(proj.name, proj.lashDesc);
+        const monSpellDeps = {
+            registry: effects,
+            cast,
+            spells: reg.monsters.spells,
+            envDeps,
+            saveSkill: pstate.skills[SKILL.SAVE] ?? 0,
+            inject,
+            ...(teleport ? { teleport } : {}),
+            general,
+            summon,
+            monShape,
+            /* do_mon_spell UI/lore hooks (8.1/8.2/8.11): announce the cast
+             * (spell_message, mon-spell.c L369), print the save message, and learn
+             * the foil rune on a save (spell_check_for_fail_rune, L383). Without this
+             * a monster's spells were silent. */
+            hooks: buildMonSpellHooks(state, {
+                lashDesc: (name) => projLashDesc.get(name) ?? null,
+                failRune: buildFailRuneEnv(state, players.timed),
+            }),
+        };
+        installMonsterCasting(state, monSpellDeps, {
+            /* become_aware: a hidden caster reveals itself (mon-attack.c L454). */
+            becomeAware: (midx) => {
+                const caster = state.monsters[midx];
+                if (caster)
+                    state.becomeAware?.(caster);
+            },
+        });
+        /* do_cmd_mon_command: EF_COMMAND possession drives the monster. */
+        installMonCommand(state, monSpellDeps);
+        /* mon_take_nonplayer_hit deps (mon-util.c L1193, gaps 5.1/7.2): monster-vs-
+         * monster and terrain (lava) damage route through the full non-player hit
+         * path - die/pain messages, loot via monster_death, fear rolls. The
+         * scheduler reads these for monster_take_terrain_damage; without them
+         * terrain damage was inert. */
+        installNonplayerHitDeps(state, {
+            ...deathDeps,
+            message: (text) => state.msg?.(text),
+        });
+        /* does_resist lore (mon-timed.c L107-110, gap 8.6): when a monster resists a
+         * timed effect via a race flag, learn that flag into visible lore. The
+         * timed layer has no deps param (get_lore is a global upstream), so register
+         * the session's lore store against its Rng. */
+        installMonTimedLore(state.rng, state.lore);
+        /* make_attack_normal's blow-effect environment (game/mon-side.ts): the
+         * monster-melee analog of the player onSideEffects hook, so a melee blow
+         * applies its full elemental / status / stat / theft / terrain
+         * consequences in upstream RNG order. EF_EARTHQUAKE (SHATTER) routes
+         * through the effect interpreter so its internal draws are shared. */
+        state.monBlowEnv = makeMonBlowEnv(state, {
+            timed: players.timed,
+            actor: playerActor,
+            projections: reg.projections,
+            expDeps,
+            lifeDrainPercent: reg.constants.lifeDrainPercent,
+            adjDexSafe: adj_dex_safe,
+            packSize: reg.constants.packSize,
+            makeDeps,
+            ...(teleport ? { teleport } : {}),
+            earthquake: (mon, radius) => {
+                effects.effectSimple(EF.EARTHQUAKE, buildEffectContext(state, envDeps), {
+                    origin: sourceMonster(mon.midx),
+                    subtype: 0,
+                    radius,
+                });
+            },
+            msg: (text, msgt) => state.msg?.(text, msgt),
+        });
+        const objCmdDeps = {
+            constants: reg.constants,
+            registry: effects,
+            cast,
+            envDeps,
+            flavor,
+            flavorDeps: flavorAwareDeps(state),
+            /* get_autoinscription (obj-ignore.c L229): read the per-game per-kind
+             * note registry so a note registered through the knowledge-menu manager
+             * is applied by applyAutoinscription. */
+            autoNote: (kind, aware) => state.autoinscribe?.get(kind.kidx, aware) ?? null,
+            inject,
+            ...(teleport ? { teleport } : {}),
+            general,
+            item,
+            summon,
+            floorEnv,
+            /* object_learn_on_use XP (obj-knowledge.c L1925-1936, gap 4.3): a first
+             * identify-by-use rewards experience via the same ExpDeps hook as
+             * spell/trap/chest use. */
+            expGain,
+            /* calc_inventory quiver inputs (gap 4.1a): the earlier_object ammo value
+             * tiebreak (object_value, ammo is always aware), the preferred_quiver_slot
+             * keyset (rogue_like_commands) and the character_dungeon re-arrange
+             * message gate (true in live play). ammoTval falls back to the live
+             * derived state.playerState.ammoTval inside calcInvOpts. */
+            objectValue: (obj) => computeObjectValue(reg.objects, obj, 1, true),
+            rogueLike: state.options?.get("rogue_like_commands") ?? false,
+            characterDungeon: true,
+            // Route object/effect messages (msg / msgt / activation_message) to the
+            // game's message sink so a shell shows them; absent, they would drop.
+            env: { msg: (text) => state.msg?.(text) },
+        };
+        installObjCommands(registry, objCmdDeps);
+        /* apply_autoinscription / autoinscribe_ground + autoinscribe_pack as seams,
+         * so the upstream call sites that have no ObjCmdDeps can reach them:
+         * inven_carry (obj-gear.c:868), store selling (store.c:1977) and
+         * update_player_object_knowledge's tail (obj-knowledge.c:1245-1247). */
+        state.autoinscribeObject = (obj) => {
+            applyAutoinscription(state, obj, objCmdDeps);
+        };
+        state.autoinscribeAll = () => {
+            autoinscribeGround(state, objCmdDeps);
+            autoinscribePack(state, objCmdDeps);
+        };
+        /* Player melee blow side effects (player-attack.c:669-1012, gap 2.5/3.6):
+         * the OF_IMPACT earthquake (effect_simple(EF_EARTHQUAKE, source_player, 10)
+         * L688) and the temporary brand/slay predicate (player_has_temporary_brand/
+         * slay over the live timed array, obj-slays.c:287-317). Without these the
+         * quake never fired and brand/slay potions gave no melee multiplier. The
+         * brand/slay directives live in the player_timed pack records (untyped on
+         * PlayerTimedRecordJson but present in the data), in TMD index order. */
+        installMeleeSideEffects(state, {
+            earthquake: () => {
+                effects.effectSimple(EF.EARTHQUAKE, buildEffectContext(state, envDeps), {
+                    origin: sourcePlayer(),
+                    subtype: 0,
+                    radius: 10,
+                });
+            },
+            temp: buildTempBrandSlay(state.actor.player, pack.player.timed, reg.objects.brands, reg.objects.slays),
+        });
+        // Player spellcasting (cast / study) for casting classes.
+        installSpellCommands(registry, {
+            effects: {
+                registry: effects,
+                cast,
+                envDeps,
+                inject,
+                ...(teleport ? { teleport } : {}),
+                general,
+                item,
+                summon,
+            },
+            statInd: liveStatInd,
+            env: {
+                expGain,
+                msg: (text) => state.msg?.(text),
+                // spell_chance fear + PF_UNLIGHT inputs (player-spell.c:417,424),
+                // shared with the fail-chance DISPLAY path so the shown rate matches
+                // the cast rate (see makeSpellChanceEnv).
+                ...makeSpellChanceEnv(state),
+                // spell_cast overcast (player-spell.c L552-553): once mana empties,
+                // player_over_exert twice in the exact upstream order - FAINT then CON -
+                // so the RNG stream draws faithfully (playerOverExert draws per flag).
+                overExert: (oops) => {
+                    playerOverExert(state, PY_EXERT.FAINT, 100, 5 * oops + 1);
+                    playerOverExert(state, PY_EXERT.CON, 50, 0);
+                },
+            },
+        });
+        // Player ranged attacks (fire launcher + ammo, throw an object). The hit
+        // math is combat/ranged.ts; the front-end walks the missile's path and
+        // routes hit / death messages through state.msg like the other commands.
+        installRangedCommands(registry);
+        // Traps: disarm + the step-onto-trap hook; a trapdoor drops a level.
+        if (reg.traps) {
+            trapDeps = {
+                kinds: reg.traps,
+                effects: {
+                    registry: effects,
+                    cast,
+                    envDeps,
+                    inject,
+                    ...(teleport ? { teleport } : {}),
+                    general,
+                    item,
+                    summon,
+                },
+                env: {
+                    expGain,
+                    msg: (text) => state.msg?.(text),
+                    /* player_of_has for trap saves / OF_TRAP_IMMUNE (trap.c:515-539). */
+                    playerHasFlag: (flag) => state.playerState?.flags.has(flag) ?? false,
+                    changeLevel: (s) => {
+                        /* trap.c:579-582: a TRF_DOWN trapdoor drops you through
+                         * dungeon_get_next_level, not blindly one level. */
+                        s.targetDepth = dungeonGetNextLevel(s.actor.player, s.chunk.depth, 1, s.z);
+                        s.generateLevel = true;
+                    },
+                    /* disturb(player) before trap effects (trap.c:525-526). */
+                    disturb: () => disturb(state),
+                },
+            };
+            installTraps(state, registry, trapDeps);
+            installChunkFeatHook(state);
+            worldEnv.trapDeps = trapDeps;
+            general.trapDeps = trapDeps;
+        }
+        // Curse periodic effects (DECISION E, do_curse_effect / decrease_timeouts):
+        // once per game turn each equipped item's curse timeouts count down and fire
+        // when they reach zero, running the curse's effect through the same bundle.
+        state.curseTick = () => {
+            processCurseTimeouts(state, {
+                curses: reg.objects.curses,
+                effects: {
+                    registry: effects,
+                    cast,
+                    envDeps,
+                    inject,
+                    ...(teleport ? { teleport } : {}),
+                    general,
+                    item,
+                    summon,
+                },
+            });
+        };
+        // Chests (gap #49): reuse the exact effect bundle traps/objects use, so
+        // chest_trap's dice draws (poison/paralysis/summon/explosion) share the
+        // interpreter, RNG stream and summon wiring with every other effect
+        // source, and floorEnv so a chest's loot lands under the same drop
+        // rules as any other floor drop.
+        chestDeps = {
+            makeDeps,
+            floorEnv,
+            effects: {
+                registry: effects,
+                cast,
+                envDeps,
+                inject,
+                ...(teleport ? { teleport } : {}),
+                general,
+                item,
+                summon,
+            },
+            env: {
+                expGain,
+                msg: (text) => state.msg?.(text),
+            },
+        };
+    }
+    // Cave commands (open / close / tunnel / alter / stair checks); rubble
+    // finds and gold veins pay out through the object generator, door locks
+    // resolve through the trap system when it is live, and chests (gap #49)
+    // open/disarm through game/chest.ts when the effect stack is live.
+    const lockKind = trapDeps ? lookupTrap(trapDeps.kinds, "door lock") : null;
+    const deps = trapDeps; // narrow for the closures
+    const caveDeps = {
+        makeDeps,
+        ...(deps ? { trapDeps: deps } : {}),
+        env: {
+            // Route open/close/tunnel/chest messages to the game's message sink
+            // (matching installObjCommands/installSpellCommands/installTraps);
+            // absent, door/tunnel/chest messages would silently drop.
+            msg: (text) => state.msg?.(text),
+            /* player_is_trapsafe (player-util.c:1073-1077) via trap.ts:86. */
+            isTrapsafe: playerIsTrapsafe,
+            digWithClause,
+            /* get_check for do_cmd_go_down's force_descend quest warning
+             * (cmd-cave.c:126). The shell has no synchronous prompt inside a turn,
+             * so this takes the same default as the effect handlers' confirm seam:
+             * an unprompted terminal auto-accepts. */
+            confirm: () => true,
+            ...(deps && lockKind
+                ? {
+                    isLockedDoor: (grid) => squareDoorPower(state, grid, deps) > 0,
+                    pickLock: (grid) => {
+                        const power = squareDoorPower(state, grid, deps);
+                        const chance = calcUnlockingChance(state, power);
+                        if (state.rng.randint0(100) < chance) {
+                            squareRemoveAllTraps(state, grid, lockKind.tidx);
+                            return true;
+                        }
+                        return false;
+                    },
+                }
+                : {}),
+        },
+        ...(chestDeps ? { chestDeps } : {}),
+    };
+    installCaveCommands(registry, caveDeps);
+    // The walk-into-a-wall seam (mod/hooks.ts walkBlockedByDiggable). walkAction
+    // consults this before its no-energy bump; movementAutoDig returns null having
+    // drawn no RNG when no mod installed a hook, so faithful play is byte-identical.
+    // null, not 0: zero is a mod handling the walk for free, which is a different
+    // answer from no mod handling it at all.
+    state.autoDigStep = (s, grid) => movementAutoDig(s, grid, caveDeps);
+    // steal (cmd-cave.c do_cmd_steal): the rogue / PF_STEAL lift-from-monster
+    // command. The PF_STEAL gate reads the live derived state (state.playerState).
+    installSteal(registry, {
+        constants: reg.constants,
+        msg: (text) => state.msg?.(text),
+    });
+    // Running (player-path.c): the corridor / open-area running engine. It
+    // re-queues itself onto state.cmdQueue, which processPlayer drains.
+    installRunning(registry);
+    // process_world upkeep environment (game/world.ts): the bound timed table so
+    // decrease_timeouts / digestion route through the grade / message machinery,
+    // the DoT take_hit hooks (rng is threaded in by worldTakeHit), and the
+    // ambient-monster spawn using the same allocation-table placement path as
+    // normal generation so its variable RNG draws stay faithful.
+    const worldPreds = reg.traps ? trapPredicates(state) : null;
+    const ambientPlaceDeps = {
+        table: new MonAllocTable(reg.monsters.races, {
+            maxDepth: reg.constants.maxDepth,
+            oodChance: reg.constants.oodMonsterChance,
+            oodAmount: reg.constants.oodMonsterAmount,
+        }),
+        groupMax: reg.constants.monsterGroupMax,
+        groupDist: reg.constants.monsterGroupDist,
+        ...(worldPreds ? { preds: worldPreds } : {}),
+        /* mon_create_drop at live placement (summons, breeders, ambient spawns,
+         * wizard): build the held pile so monster_death spills it. makeDeps makes
+         * the objects; lore feeds the unique theft reduction. */
+        makeDeps,
+        lore: state.lore,
+    };
+    // monster_turn_multiply's multiply_monster (mon-move.c): a breeder spawns a
+    // copy through the live placement path (reusing ambientPlaceDeps so the
+    // scatter / createMonster draws stay faithful). monster_turn_multiply itself
+    // (the cap / crowd / chance rolls) lives in game/monster-turn.ts.
+    state.monsterMultiply = (m) => multiplyMonster(state, m, ambientPlaceDeps);
+    // Door-lock seams for monster_turn_can_move's locked-door branch: locks are
+    // "door lock" traps (#21), so these route through the trap system when live.
+    if (deps && lockKind) {
+        state.doorLockPower = (grid) => squareDoorPower(state, grid, deps);
+        state.setDoorLock = (grid, power) => squareSetDoorLock(state, grid, power, deps);
+        state.removeDoorLock = (grid) => {
+            squareRemoveAllTraps(state, grid, lockKind.tidx);
+        };
+    }
+    /* player_inc_check for the world clock's over-exertion / DoT timed increases
+     * (audit 01 T1, player-timed.c:1056): the game-turn callers (world.ts inc with
+     * check=true - fainting SCRAMBLE, over-cast CONFUSED/IMAGE) previously passed
+     * hooks lacking incCheck, so timed.ts defaulted to ALLOW and PROT_CONF /
+     * RES_CHAOS / RES_NEXUS were ignored on that path. Shares makeIncCheckQueries
+     * with the effect-interpreter env, reading the live derived state. */
+    const worldIncQueries = makeIncCheckQueries(state);
+    state.world = {
+        timedTable: players.timed,
+        timedHooks: {
+            onMessage: (text, msgt) => state.msg?.(text, msgt),
+            onNotify: (_idx, canDisturb) => {
+                if (canDisturb)
+                    disturb(state);
+            },
+            incCheck: (idx) => {
+                const eff = players.timed[idx];
+                return eff ? playerIncCheck(eff, worldIncQueries) : true;
+            },
+            /* on_begin_effect / on_end_effect dispatch (audit 01 T2): when a timed
+             * effect starts or lapses on the world clock (e.g. SPRINT ends -> SLOW,
+             * SCRAMBLE ends -> UNSCRAMBLE_STATS), run its bound chain. */
+            onTransition: (idx, begin, canDisturb) => {
+                runTimedTransition?.(idx, begin, canDisturb);
+            },
+            /* print_custom_message weapon substitution (obj-util.c:1118, gap 2.9):
+             * the {name}/{kind}/{s}/{is} tags in weapon-related timed messages (the
+             * temporary-brand on-begin/on-end lines) resolve against the CURRENTLY
+             * wielded weapon, so a getter keeps it live across wield/takeoff. name /
+             * kind use the ODESC_BASE approximation (kind name) already adopted across
+             * the port (obj-knowledge.ts). No weapon => the obj == NULL tag forms. */
+            get weapon() {
+                const w = state.actor.weapon;
+                /* No weapon => the obj == NULL tag forms. A sentinel with name/kind
+                 * "hands" and number 2 reproduces substituteTimedMessage's obj == NULL
+                 * output byte-for-byte ({name}/{kind} -> "hands", {s} -> "", {is} ->
+                 * "are"), so exactOptionalPropertyTypes is satisfied without a getter
+                 * that returns undefined. */
+                if (!w)
+                    return { name: "hands", kind: "hands", number: 2 };
+                return { name: w.kind.name, kind: w.kind.name, number: w.number };
+            },
+        },
+        /* The same shared consequences drive the world clock's DoT ticks, terrain
+         * (lava) damage and over-exertion, so poison / a fatal wound / starvation
+         * death records died_from and shows the full chain too. */
+        takeHitHooks: sharedTakeHitHooks,
+        expDeps,
+        spawnAmbientMonster: (s) => pickAndPlaceDistantMonster(s, s.actor.grid, s.z.maxSight + 5, true, s.chunk.depth, ambientPlaceDeps),
+        // cave_illuminate on the town dawn/nightfall boundary (game-world.c,
+        // called from processWorld in game/loop.ts): relights SQUARE_GLOW and
+        // updates player map knowledge (square_memorize/square_forget) to match.
+        caveIlluminate: (s, dawn) => caveIlluminateKnown(s, dawn),
+        /* player_take_terrain_damage's adjust_dam(PROJ_FIRE) needs the projection
+         * table to scale lava damage by the player's fire resistance. */
+        ...(reg.projections ? { projections: reg.projections } : {}),
+    };
+    /* Surface the wizard/debug engine bundles (WP-14): all four locals are in
+     * scope here (makeDeps L731, expDeps L603, trapDeps hoisted, wizardEffect
+     * assigned in the projections block, ambientPlaceDeps the live MonPlaceDeps).
+     * Null bundles are omitted so WizardDeps' optional fields stay absent. */
+    const wizardBundles = {
+        makeDeps,
+        expDeps,
+        monPlace: ambientPlaceDeps,
+        ...(wizardEffect ? { effect: wizardEffect } : {}),
+        ...(trapDeps ? { trapDeps } : {}),
+    };
+    return { registry, trapDeps, flavor, everseen, effects: effectRegistry, wizardBundles };
+}
+/**
+ * Register a generated level's content on the live state: place the player,
+ * the monsters (rebuilding groups from the generation group_info, exactly
+ * as upstream rebuilds from a savefile), the floor piles, and instantiate
+ * the marked traps and rolled door locks.
+ */
+function populateFromLevel(state, level, trapDeps) {
+    const spot = level.playerSpot ?? loc(1, 1);
+    state.actor.grid = spot;
+    placePlayer(state, spot);
+    /* Track the deepest level reached (player->max_depth). */
+    if (level.depth > state.actor.player.maxDepth) {
+        state.actor.player.maxDepth = level.depth;
+    }
+    /* A new level clears the decoy (glyph traps do not persist the swap). */
+    state.decoy = null;
+    for (const pm of level.monsters) {
+        pm.mon.grid = pm.grid;
+        addMonster(state, pm.mon);
+    }
+    for (let i = 1; i < state.monsters.length; i++) {
+        const mon = state.monsters[i];
+        if (mon)
+            monsterGroupAssign(state, mon, mon.groupInfo, true);
+    }
+    monsterGroupsVerify(state);
+    updateMonsterDistances(state);
+    /* Count racial occurrences (generation tracks uniques level-locally; the
+     * live cur_num starts here and placement / deleteMonster maintain it). */
+    countMonsterRaces(state);
+    // Register the generated floor objects as live piles (floor_carry), so
+    // pickup / drop / projections operate on the same objects the level laid
+    // down.
+    for (const po of level.objects) {
+        floorCarry(state, po.grid, po.obj);
+    }
+    // Instantiate generation-marked traps on the live cave. Kind+power were
+    // chosen at gen time (level.traps / place_trap); install without a second
+    // pick/power draw (trap.c:356-394). Every C place_trap site must record a
+    // GenTrap. Bare trapGrids markers are a gen bug - fail loudly rather than
+    // re-drawing on the play stream or silently dropping them.
+    if (trapDeps) {
+        const descriptors = level.traps ?? [];
+        const covered = new Set(descriptors.map((t) => t.grid.y * state.chunk.width + t.grid.x));
+        for (const grid of level.trapGrids) {
+            const key = grid.y * state.chunk.width + grid.x;
+            if (!covered.has(key)) {
+                throw new Error(`populateFromLevel: bare trap marker at (${grid.x},${grid.y}) ` +
+                    `without kind+power; generation must call placeTrap with ` +
+                    `trapKinds so pick_trap + power are spent in the gen stream ` +
+                    `(trap.c:356-394)`);
+            }
+        }
+        for (const t of descriptors) {
+            installTrap(state, t.grid, t.tidx, t.power, trapDeps);
+        }
+        for (const door of level.lockedDoors) {
+            squareSetDoorLock(state, door.grid, door.power, trapDeps);
+        }
+    }
+}
+/** square_isarrivable (cave-square.c L613) on the live cave: no occupant, no
+ * player trap / web, and a floor or stair (a legal player arrival square). */
+function squareIsArrivable(state, grid) {
+    const c = state.chunk;
+    if (c.mon(grid) !== 0)
+        return false;
+    if (squareIsPlayerTrap(state, grid))
+        return false;
+    if (squareIsWebbed(state, grid))
+        return false;
+    return c.isFloor(grid) || c.isStairs(grid);
+}
+/**
+ * sanitize_player_loc (generate.c L1265): keep the player's grid if it is a
+ * legal arrival square (in bounds, arrivable, not a vault); otherwise pick a
+ * random empty non-vault square, then fall back to a full linear scan (keeping
+ * a vault square only as a last resort). A faithful port including the RNG
+ * draws - reached only on the birth_levels_persist restore path. Mutates
+ * state.actor.grid in place, as upstream mutates p->grid.
+ */
+function sanitizePlayerLoc(state) {
+    const c = state.chunk;
+    const preds = {
+        isPlayerTrap: (g) => squareIsPlayerTrap(state, g),
+        isWebbed: (g) => squareIsWebbed(state, g),
+        isWarded: (g) => squareIsWarded(state, g),
+    };
+    const isVault = (g) => c.sqinfoHas(g, SQUARE.VAULT);
+    /* Allow direct transfer if the retained grid is teleportable. */
+    const grid = state.actor.grid;
+    if (c.inBoundsFully(grid) &&
+        squareIsArrivable(state, grid) &&
+        !isVault(grid)) {
+        return;
+    }
+    /* A bunch of random locations. */
+    for (let attempt = 1000; attempt > 0; attempt--) {
+        const tx = state.rng.randint0(c.width - 1) + 1;
+        const ty = state.rng.randint0(c.height - 1) + 1;
+        const g = loc(tx, ty);
+        if (squareIsEmptyLive(state, g, preds) && !isVault(g)) {
+            state.actor.grid = g;
+            return;
+        }
+    }
+    /* Whelp, that didn't work: scan the whole dungeon linearly from a random
+     * start, remembering the last empty vault square as a fallback. */
+    const ix = state.rng.randint0(c.width - 1) + 1;
+    const iy = state.rng.randint0(c.height - 1) + 1;
+    let tx = ix + 1;
+    let ty = iy;
+    if (tx >= c.width - 1) {
+        tx = 1;
+        ty = ty + 1;
+        if (ty >= c.height - 1)
+            ty = 1;
+    }
+    let vx = 1;
+    let vy = 1;
+    for (;;) {
+        const g = loc(tx, ty);
+        if (squareIsEmptyLive(state, g, preds)) {
+            if (!isVault(g)) {
+                state.actor.grid = g;
+                return;
+            }
+            /* A vault, but remember it just in case. */
+            vy = ty;
+            vx = tx;
+        }
+        /* Oops, tried every tile. */
+        if (tx === ix && ty === iy)
+            break;
+        tx = tx + 1;
+        if (tx >= c.width - 1) {
+            tx = 1;
+            ty = ty + 1;
+            if (ty >= c.height - 1)
+                ty = 1;
+        }
+    }
+    /* Fallback vault location (or at least a non-crashy square). */
+    state.actor.grid = loc(vx, vy);
+}
+/**
+ * dungeon_change_level + prepare_next_level: generate a fresh level at
+ * `depth` from the state's own RNG stream and swap it into the state in
+ * place. Installed commands keep working (they close over the state
+ * object, whose chunk and entity stores are replaced).
+ */
+function makeChangeLevel(state, reg, trapDeps, opts = {}) {
+    /* The level stashed when entering an arena: leaving a level FOR an
+     * arena persists it even without birth_levels_persist (generate.c
+     * L1349), and the arena exit restores it. */
+    let arenaStash = null;
+    let inArena = opts.inArena ?? false;
+    return (depth) => {
+        /* Consume the pending arrival-stair request (create_up_stair /
+         * create_down_stair) exactly once, on every path - the equivalent of
+         * player_place clearing the flags (player-util.c:1585-1586). Only a fresh
+         * generation below acts on it; arena/recall/persist-restore paths clear it
+         * without laying a stair, exactly as upstream leaves the flags unset. */
+        const pendingStair = state.arrivalStair ?? null;
+        delete state.arrivalStair;
+        /* --- Arena entry: EF_SINGLE_COMBAT fired the change. --- */
+        if (state.arenaLevel && !inArena) {
+            const mon = state.healthWho;
+            if (mon) {
+                arenaStash = {
+                    chunk: state.chunk,
+                    monsters: state.monsters,
+                    groups: state.groups,
+                    floor: state.floor,
+                    traps: state.traps,
+                    known: state.known,
+                    decoy: state.decoy ?? null,
+                    monMidx: mon.midx,
+                };
+                /* arena_gen (gen-cave.c L3984): 6x6 floor bounded by perm rock,
+                 * the player in one corner and the opponent in the other. */
+                const arena = new Chunk(reg.features, 6, 6);
+                arena.depth = state.chunk.depth;
+                for (let y = 0; y < 6; y++) {
+                    for (let x = 0; x < 6; x++) {
+                        const edge = y === 0 || x === 0 || y === 5 || x === 5;
+                        arena.setFeat(loc(x, y), edge ? FEAT.PERM : FEAT.FLOOR);
+                    }
+                }
+                state.chunk = arena;
+                installChunkFeatHook(state);
+                state.monsters = [null];
+                state.groups = [null];
+                state.floor = new Map();
+                state.traps = new Map();
+                state.known = newKnownMap(6, 6);
+                delete state.decoy;
+                /* wiz_light(chunk, p, false) (generate.c:1109): every arena level is
+                 * lit on generation. Upstream runs it while `chunk` is not yet `cave`,
+                 * so square_memorize / square_know_pile / square_forget all short-
+                 * circuit on their `c != cave` guard and the call is a pure
+                 * SQUARE_GLOW pass - hence isCurrentCave = false here. Without it the
+                 * arena is unlit and the opponent invisible without a light source. */
+                wizLightLevel(state, true, false, false);
+                /* The monster is COPIED in (upstream memcpy); the original stays
+                 * in the stashed level and is finished on the way out. Held
+                 * objects are ignored, and it gets a fresh group. */
+                const copy = blankMonster(mon.race);
+                copy.originalRace = mon.originalRace;
+                copy.hp = mon.hp;
+                copy.maxhp = mon.maxhp;
+                copy.mspeed = mon.mspeed;
+                copy.energy = mon.energy;
+                copy.mTimed.set(mon.mTimed);
+                copy.mflag = mon.mflag.clone();
+                copy.grid = loc(4, 1);
+                addMonster(state, copy);
+                state.groups[1] = { index: 1, leader: copy.midx, members: [copy.midx] };
+                copy.groupInfo[0] = { index: 1, role: MON_GROUP.LEADER };
+                state.healthWho = copy;
+                targetSetMonster(state, copy);
+                placePlayer(state, loc(1, 4));
+                inArena = true;
+                delete state.targetDepth;
+                state.updateBonuses?.(); /* on_new_level PU_BONUS -> calc_light */
+                state.updateFov?.(state);
+                return;
+            }
+            /* No tracked opponent: fall through to a normal change. */
+            state.arenaLevel = false;
+        }
+        /* --- Arena exit: the fight is over (or abandoned). --- */
+        if (inArena) {
+            inArena = false;
+            state.arenaLevel = false;
+            const stash = arenaStash;
+            arenaStash = null;
+            if (stash) {
+                /* Restore the level left behind (the player marker stayed). */
+                state.chunk = stash.chunk;
+                installChunkFeatHook(state);
+                state.monsters = stash.monsters;
+                state.groups = stash.groups;
+                state.floor = stash.floor;
+                state.traps = stash.traps;
+                state.known = stash.known;
+                if (stash.decoy)
+                    state.decoy = stash.decoy;
+                const back = state.oldGrid ?? state.actor.grid;
+                state.actor.grid = back;
+                state.chunk.setMon(back, -1);
+                delete state.oldGrid;
+                /* Kill the arena monster's original (kill_arena_monster). */
+                const orig = state.monsters[stash.monMidx];
+                if (orig) {
+                    orig.hp = -1;
+                    state.msg?.(`${orig.race.name} is defeated!`);
+                    state.onPlayerKill?.(orig);
+                    deleteMonster(state, orig.midx);
+                }
+                state.healthWho = null;
+                targetSetMonster(state, null);
+                delete state.targetDepth;
+                state.updateBonuses?.(); /* on_new_level PU_BONUS -> calc_light */
+                state.updateFov?.(state);
+                return;
+            }
+            /* The stash did not survive a save boundary: fall through to a
+             * fresh level of the same depth (ledgered). */
+            delete state.oldGrid;
+        }
+        /* dungeon_change_level: track the deepest level reached. */
+        if (depth > state.actor.player.maxDepth) {
+            state.actor.player.maxDepth = depth;
+        }
+        /* birth_levels_persist (#30, off by default): when on, the level being
+         * left is frozen into a depth-keyed cache and a previously-frozen target
+         * level is restored instead of regenerated (prepare_next_level's persist
+         * branch, generate.c L1347-1556). The whole branch is gated on the option,
+         * so default play runs the original fresh-level path below unchanged. The
+         * key is `depth` - the faithful identity for upstream's level NAME
+         * (chunk_find_name of level_by_depth(depth)->name); see StoredLevel. */
+        const persist = state.options?.get("birth_levels_persist") ?? false;
+        const currentDepth = state.chunk.depth;
+        /*
+         * Non-persist town store (generate.c:1371-1373): leaving depth 0 always
+         * keeps a terrain-only Town chunk so town_gen can reload the same layout
+         * (shops, stairs, ruins) without birth_levels_persist.
+         */
+        if (!persist && currentDepth === 0) {
+            state.townChunk = chunkWriteTerrain(state.chunk);
+        }
+        /* wipe_mon_list: the old level's monsters forget their racial counts
+         * before the new level allocates against them. Under persist the old level
+         * (and its monsters) survives in the cache with its counts intact, exactly
+         * as the persist branch skips cave_clear/wipe_mon_list. */
+        if (!persist) {
+            wipeMonsterCounts(state);
+        }
+        /* Forget the target and the tracked monster (game-world.c L1010),
+         * and release any commanded monster (L1065). */
+        targetSetMonster(state, null);
+        state.healthWho = null;
+        state.actor.player.timed[TMD.COMMAND] = 0;
+        if (persist) {
+            const cache = (state.levelCache ??= new Map());
+            /* Freeze the level being left (cave_store, generate.c L1366).
+             * compact_monsters(cave, 0) is the RNG-free "too many holes" pass; the
+             * player marker is cleared (L1362, non-arena - arena freezing keeps it
+             * and is handled by the arena stash above); the freeze turn is stamped on
+             * the chunk (cave_store L1032) for restore_monsters. Persistent levels
+             * keep their artifacts, so the non-persist artifact-loss loop below is
+             * skipped on this path. */
+            compactMonsters(state, 0);
+            state.chunk.setMon(state.actor.grid, 0);
+            state.chunk.turn = state.turn;
+            /* chunk_list_add (gen-chunk.c L69) is this Map insert: the C appends the
+             * stored chunk to a realloc'd chunk_list[] keyed by chunk->name (which is
+             * level_by_depth(depth)->name), so a depth-keyed Map is the same lookup
+             * without the name indirection or the manual growth. */
+            cache.set(currentDepth, {
+                chunk: state.chunk,
+                monsters: state.monsters,
+                groups: state.groups,
+                floor: state.floor,
+                traps: state.traps,
+                known: state.known,
+                decoy: state.decoy ?? null,
+                turn: state.turn,
+                /* chunk->join (generate.c L1203-1214): freeze the level's stair
+                 * connectors so a later first-visit neighbour can align its stairs. */
+                join: state.currentJoins ?? [],
+            });
+            /* Enter a previously-frozen target level: assign it back and let its
+             * monsters recover over the elapsed turns (prepare_next_level
+             * L1414-1506). chunk_find_name is the depth lookup here. */
+            const stored = cache.get(depth);
+            if (stored) {
+                cache.delete(depth); // chunk_list_remove (L1505)
+                state.chunk = stored.chunk;
+                installChunkFeatHook(state);
+                state.monsters = stored.monsters;
+                state.groups = stored.groups;
+                state.floor = stored.floor;
+                state.traps = stored.traps;
+                state.known = stored.known;
+                state.decoy = stored.decoy;
+                /* Restore the level's stair connectors so a subsequent departure
+                 * re-freezes them and adjacent first-visits keep aligning. */
+                state.currentJoins = stored.join;
+                /* restore_monsters (mon-move.c L2007): HP regen + timed reduction over
+                 * the turns the level was frozen (turn - chunk->freeze-turn). */
+                restoreMonsters(state, state.turn - stored.turn);
+                /* Place the player (prepare_next_level non-arena, L1497-1501): sanitize
+                 * the retained grid into a legal arrival square, then player_place.
+                 * DEFERRAL: exact stair-connector matching (dun->persist / one_off_*
+                 * join connectors, generate.c L1147-1152) is applied by upstream only
+                 * when GENERATING a persistent level, not when restoring one - a
+                 * restored level uses this same sanitize+place, so the round-trip is
+                 * faithful. The connector wiring for FIRST-visit generation stays
+                 * dormant (cave.ts): a first visit arrives at the fresh level's normal
+                 * playerSpot, which is a valid stair/empty grid. Level identity on
+                 * re-entry is exact; only the first-visit arrival stair is approximate. */
+                sanitizePlayerLoc(state);
+                placePlayer(state, state.actor.grid);
+                installChunkFeatHook(state);
+                refreshTownStores(state, reg);
+                delete state.targetDepth;
+                state.updateBonuses?.(); /* on_new_level PU_BONUS -> calc_light */
+                /* only_partial during level-entry FOV (ui-display.c:2522 / cave-view.c:851). */
+                state.chunk.onlyPartial = true;
+                state.updateFov?.(state);
+                announceFeeling(state, reg);
+                search(state); /* on_new_level (game-world.c:1052). */
+                state.chunk.onlyPartial = false;
+                return;
+            }
+            /* First visit to this depth: fall through to fresh generation. The old
+             * level is already frozen; counts were not wiped and artifacts are not
+             * lost (both skipped above / below under persist). */
+        }
+        /* Consume stored town layout for non-persist re-entry (town_gen L2682). */
+        const townLayout = !persist && depth === 0 && state.townChunk ? state.townChunk : null;
+        if (townLayout)
+            state.townChunk = null;
+        /* birth_levels_persist first-visit generation (generate.c L1147-1152): seed
+         * this fresh level's stair connectors from the frozen adjacent levels so
+         * up/down stairs line up, and mark the build persistent so dun.persist
+         * branches run. Off by default: persist is false, joinInfo stays undefined,
+         * and generateLevel builds exactly as before. */
+        const persistCache = state.levelCache;
+        let joinInfo;
+        if (persist && persistCache) {
+            const above = persistCache.get(depth - 1)?.join;
+            const twoAbove = persistCache.get(depth - 2)?.join;
+            const below = persistCache.get(depth + 1)?.join;
+            const twoBelow = persistCache.get(depth + 2)?.join;
+            joinInfo = getJoinInfo({
+                ...(above ? { above } : {}),
+                ...(twoAbove ? { twoAbove } : {}),
+                ...(below ? { below } : {}),
+                ...(twoBelow ? { twoBelow } : {}),
+            });
+        }
+        /* choose_profile's NOSCORE_JUMPING request (generate.c L824-836): consumed
+         * once, cleared as it is passed on, exactly as the C clears the bit. */
+        const jumpProfileName = state.jumpProfileName;
+        state.jumpProfileName = undefined;
+        const g = generateLevel(state.rng, depth, {
+            ...genDeps(reg, true, state.artifacts, state.options?.get("birth_no_artifacts") ?? false, 
+            /* mon_create_drop's unique theft reduction reads the live lore store. */
+            state.lore),
+            /* The mod behaviour seam, read at build time (this call is synchronous,
+             * so a Fixes & tweaks toggle applies from the next level onward).
+             * `levelGenerated` is the only hook cave_generate consults; absent =>
+             * faithful. */
+            ...(state.modHooks ? { hooks: state.modHooks } : {}),
+            /* new_player_spot's placement failure (gen-util.c:422): always audible. */
+            msg: (text) => state.msg?.(text),
+            /* cheat_room's restart narration (generate.c:1164, :1222): only when
+             * the cheat option is on, which is what gates it upstream. */
+            ...((state.options?.get("cheat_room") ?? false)
+                ? { cheatMsg: (text) => state.msg?.(text) }
+                : {}),
+        }, 
+        /* is_daytime() only affects the town (depth 0) build; passed always so a
+         * RECALL back to town honours the day/night clock. */
+        {
+            daytime: isDaytime(state.turn, state.z.dayLength),
+            birthLoseArts: state.options?.get("birth_lose_arts") ?? false,
+            questSpawns: questSpawnsForDepth(state, reg, depth),
+            persist,
+            ...(joinInfo ? { joinInfo } : {}),
+            /* chunk_find_adjacent (gen-chunk.c:147): whether the neighbour levels
+             * already exist in the frozen-level cache, so handle_level_stairs skips
+             * the alloc_stairs for a direction the neighbour already seeded. Passed
+             * unconditionally; only read under persist. */
+            hasAdjacentAbove: persistCache?.has(depth - 1) ?? false,
+            hasAdjacentBelow: persistCache?.has(depth + 1) ?? false,
+            /* birth_connect_stairs (gen-util.c:427-433): lay the arrival stair the
+             * stair command requested ("up" after a descent, "down" after an
+             * ascent), unless the option is off. Recall/first-spawn leave
+             * pendingStair null, so no arrival stair is laid. */
+            ...(pendingStair &&
+                (state.options?.get("birth_connect_stairs") ?? true)
+                ? { createStair: pendingStair }
+                : {}),
+            ...(townLayout ? { townLayout } : {}),
+            ...(jumpProfileName ? { profileName: jumpProfileName } : {}),
+        });
+        /* chunk->join (generate.c L1203-1214): remember this level's stair
+         * connectors for freezing and adjacent-level alignment. Gated on persist so
+         * that with birth_levels_persist off the field stays unset and the savefile
+         * is byte-identical to today (no currentJoins key emitted). */
+        if (persist)
+            state.currentJoins = g.joins;
+        state.chunk = g.c;
+        state.monsters = [null];
+        state.groups = [null];
+        /* Artifacts left on the abandoned level are lost (generate.c L1383-1394):
+         * a known one (or any, under birth_lose_arts) is logged as missed. The
+         * created-mark reset that lets an unknown one regenerate rides artifact
+         * upkeep (#24). Runs before the floor is cleared below. This is the
+         * NON-persist branch only: a frozen persistent level keeps its artifacts. */
+        if (!persist) {
+            const loseArts = state.options?.get("birth_lose_arts") ?? false;
+            for (const pile of state.floor.values()) {
+                for (const obj of pile) {
+                    if (obj.artifact &&
+                        (loseArts || (obj.notice & OBJ_NOTICE.ASSESSED) !== 0)) {
+                        state.onArtifactLost?.(obj.artifact);
+                    }
+                }
+            }
+        }
+        state.floor = new Map();
+        state.traps = new Map();
+        state.known = newKnownMap(g.c.width, g.c.height);
+        installChunkFeatHook(state);
+        populateFromLevel(state, {
+            playerSpot: g.playerSpot,
+            monsters: g.monsters,
+            objects: g.objects,
+            trapGrids: [...g.trapGrids].map((i) => iToGrid(i, g.c.width)),
+            traps: g.traps,
+            lockedDoors: g.lockedDoors,
+            depth,
+        }, trapDeps);
+        refreshTownStores(state, reg);
+        /* town_gen -> cave_illuminate (gen-cave.c / cave-map.c L555): the town is
+         * illuminated at generation. The chunk-flag half already ran in the town
+         * builder (gen/cave.ts caveIlluminate); this applies the player-KNOWLEDGE
+         * half against the freshly built known map so a daytime town is fully
+         * memorized (visible from anywhere on entry, exactly like the C town) and a
+         * night town forgets its boring floors. Town only (depth 0); dungeon levels
+         * start dark. Runs on both birth and recall-to-town. */
+        if (depth === 0) {
+            caveKnown(state);
+            caveIlluminateKnown(state, isDaytime(state.turn, state.z.dayLength));
+        }
+        /* cave_generate (generate.c:1255-1258): a builder that asked for the level
+         * to be revealed (labyrinth_gen's "known" maze, gen-cave.c:1594) gets
+         * `wiz_light(chunk, p, false)` and the flag is cleared. `chunk` is not yet
+         * `cave` there, so square_memorize / square_know_pile / square_forget all
+         * short-circuit on their `c != cave` guard and the call perma-LIGHTS the
+         * level without memorizing anything - hence isCurrentCave = false. */
+        if (g.lightLevel) {
+            wizLightLevel(state, true, false, false);
+            g.lightLevel = false;
+        }
+        delete state.targetDepth;
+        /* on_new_level (game-world.c:1034-1037): PU_BONUS -> update_bonuses ->
+         * calc_light recomputes cur_light for the NEW depth, then the view is
+         * flooded. Without this the daytime-town cur_light (0) leaks into the
+         * dungeon, so the torch radius is -1 and arrival renders dark until the
+         * next bonus recompute. Run the bonus pass before the first view build. */
+        state.updateBonuses?.();
+        /* only_partial during level-entry FOV (ui-display.c:2522 / cave-view.c:851). */
+        state.chunk.onlyPartial = true;
+        state.updateFov?.(state);
+        announceFeeling(state, reg);
+        search(state); /* on_new_level (game-world.c:1052). */
+        state.chunk.onlyPartial = false;
+    };
+}
+/**
+ * Resolve the quest guardians to place on a freshly generated level
+ * (generate.c L1170-1191). Returns one QuestSpawn per active quest whose
+ * level == depth, mapping the stored race index to its MonsterRace. A
+ * completed quest has level 0 (never a dungeon depth), so it is naturally
+ * excluded. The unique-already-alive (cur_num > 0) skip is applied inside
+ * generateLevel, matching upstream's placement-time check.
+ */
+function questSpawnsForDepth(state, reg, depth) {
+    if (depth <= 0)
+        return [];
+    const quests = state.actor.player.quests;
+    if (!quests || quests.length === 0)
+        return [];
+    const spawns = [];
+    for (const q of quests) {
+        if (q.level !== depth)
+            continue;
+        const race = reg.monsters.races[q.race];
+        if (!race)
+            continue;
+        spawns.push({ race, maxNum: q.maxNum });
+    }
+    return spawns;
+}
+/**
+ * on_new_level's level-feeling announcement (game-world.c:1047-1049):
+ *
+ *     if (player->depth)
+ *             display_feeling(false);
+ *
+ * The whole feeling system was ported - both message tables verbatim, the
+ * obj/mon rating arithmetic, place_feeling's scatter, feeling_squares, the
+ * birth_feelings gate, the LF: status row - and displayFeeling had exactly ONE
+ * caller in the repo: the ^F command. Nothing announced it on arrival, so a
+ * player who never pressed ^F never saw a feeling message in the whole game.
+ * That is the shape a call-site census is built to catch: the function exists and
+ * is correct, and no live path reaches it.
+ *
+ * The depth guard is the CALLER's upstream, not displayFeeling's own - the town
+ * line ("Looks like a typical town.") is reachable only through ^F, so guarding
+ * here rather than inside is what keeps the town silent on every arrival.
+ *
+ * Deliberately NOT called from the two arena paths, which mirror upstream's
+ * `arena_level` early return at game-world.c:1044-1046.
+ */
+function announceFeeling(state, reg) {
+    if (!state.chunk.depth)
+        return;
+    displayFeeling(state, { feelingNeed: reg.constants.feelingNeed });
+}
+/**
+ * store_init / store_reset / store_update lifecycle (store.c). The stores
+ * (including FEAT_HOME) are PERSISTENT global state, created once and kept alive
+ * for the whole game - they are NOT wiped on descent, so the home stash and
+ * shop stock survive across levels and save/load (gap 12.1). First creation
+ * (store_reset) fills every non-home shop; each subsequent return to town runs
+ * store_update, catching the shops up on the days that elapsed in the dungeon
+ * and occasionally shuffling a shopkeeper (gaps 12.2/12.3), consuming daycount.
+ * No-op when the pack ships no stores; a loaded save's restored stores skip the
+ * first-creation branch and (in town, daycount 0) leave the RNG stream untouched.
+ */
+function refreshTownStores(state, reg) {
+    if (!reg.stores)
+        return;
+    const storeDeps = {
+        reg: reg.objects,
+        alloc: new ObjAllocState(reg.objects, reg.constants),
+        constants: reg.constants,
+        /* Stores pass allowArtifacts=false, so these are inert here; shared
+         * for consistency with the rest of the game's MakeDeps. */
+        artifacts: state.artifacts ?? new ArtifactState(reg.objects.artifacts.length),
+        noArtifacts: state.options?.get("birth_no_artifacts") ?? false,
+        /* class book-rejection / curse-foil / no-selling generation foils. */
+        ...genFoilFields(state),
+    };
+    if (!state.stores) {
+        /* First time in town: store_init + store_reset. Build and stock every shop
+         * once. Gated on depth 0 so a game that begins in the dungeon (tests, or a
+         * future non-town start) draws no store RNG until town is actually reached -
+         * preserving the exact stream and the pre-fix behaviour. */
+        if (state.chunk.depth !== 0)
+            return;
+        state.stores = createTownStores(reg.stores.stores, storeDeps, state.rng, state.actor.player.maxDepth, 
+        /* parse_always book expansion (store.c:208-231): the bookseller's
+         * no-sval always lines need class-book metadata to resolve which town
+         * spellbooks to stock. Stashed on state by wireGame. */
+        state.classes);
+        return;
+    }
+    /* Stores already exist (persisted across levels). On the return to town run
+     * store_update over the accrued days, then zero daycount (store.c:1462). In
+     * the dungeon the stores are simply left as-is (home stash preserved). */
+    if (state.chunk.depth === 0) {
+        const ctx = {
+            rng: state.rng,
+            deps: storeDeps,
+            maxDepth: state.actor.player.maxDepth,
+            stores: state.stores,
+            /* OPT(cheat_xtra) (store.c:1424, :1444). */
+            ...(state.options?.get("cheat_xtra")
+                ? { cheatMsg: (text) => state.msg?.(text) }
+                : {}),
+        };
+        storeUpdate(ctx, state.daycount ?? 0);
+        state.daycount = 0;
+    }
+}
+/**
+ * Materialise upkeep->inven[] and upkeep->quiver[] for a game that has just
+ * come into existence, from birth (player_outfit -> inven_carry sets PU_INVEN,
+ * which the first update_stuff turns into calc_inventory) or from a savefile
+ * (rd_gear's explicit calc_inventory tail, load.c:1187).
+ *
+ * Both views are DERIVED and never persisted, and until this ran nothing built
+ * them: the port only recomputed them as a side effect of an object command or
+ * a game turn. Anything reading them before that - an inventory listing, an
+ * item picker, the quiver screen - saw an empty pack and an empty quiver.
+ *
+ * `characterDungeon` is false here: upstream's "You re-arrange your quiver."
+ * notice belongs to play, not to a character coming into being.
+ */
+function buildGearViews(state, reg, ammoTval) {
+    calcInventory(state.gear, reg.constants, {
+        store: false,
+        ammoTval,
+        objectValue: (obj) => computeObjectValue(reg.objects, obj, 1, true),
+        rogueLike: state.options?.get("rogue_like_commands") ?? false,
+        characterDungeon: false,
+    });
+}
+/**
+ * Assemble a runnable GameState from a pack: generate a level, birth a
+ * character, derive its bonuses, and register the placed monsters. The
+ * caller wires state.nextCommand (input) and state.updateFov (FOV) and then
+ * drives runGameLoop; on LOOP_STATUS.LEVEL_CHANGE it calls
+ * game.changeLevel(state.targetDepth) and clears state.generateLevel.
+ */
+export function startGame(pack, opts = {}) {
+    // Bind registries and the player domain first: spellbook object kinds
+    // are created FROM the class book definitions (init.c write_book_kind),
+    // and must exist before level generation builds the allocation tables
+    // (so books spawn) and before the starting kit resolves.
+    const reg = bindCore(pack);
+    const players = bindPlayer(pack.player);
+    registerBookKinds(reg.objects, players.classes);
+    // The player option store (option.c options_init_defaults): seeded from
+    // OPTION_ENTRIES defaults, with the birth/interface choices applied. Built
+    // before level generation so birth_randarts can swap the artifact set first.
+    // Every Angband option (show_damage, center_player, auto_more, ...) ships in
+    // core with its faithful upstream default (OPTION_ENTRIES.normal); the player
+    // changes them in the options menu exactly as upstream. Only explicit birth /
+    // interface CHOICES (birth screen, point-buy) are applied here as overrides,
+    // so with none supplied the store is byte-identical to the table.
+    const options = new OptionState({
+        ...(opts.optionOverrides ? { overrides: opts.optionOverrides } : {}),
+        ...(opts.hitpointWarn !== undefined ? { hitpointWarn: opts.hitpointWarn } : {}),
+    });
+    // options_init_cheat (player-birth.c:1234, gap 1.12): at character accept,
+    // clear every cheat option and its score twin, THEN re-apply the port-only
+    // birth optionOverrides seam AFTER the clear. Maintainer-decided faithful
+    // ordering: a NORMAL birth matches upstream exactly (cheat options default
+    // off, so this clear is a no-op), while an EXPLICIT birth-time cheat override
+    // (the port-only seam with no upstream equivalent) still survives because it
+    // is re-applied last. Birth options were already frozen into the snapshot at
+    // construction, so re-applying them here is a harmless no-op (set() is locked
+    // for birth options); only the interface/cheat/score overrides take effect.
+    optionsInitCheat(options);
+    if (opts.optionOverrides) {
+        for (const [name, value] of Object.entries(opts.optionOverrides)) {
+            if (value !== undefined)
+                options.set(name, value);
+        }
+    }
+    // Main game RNG (Decision 6.2): one continuous stream for birth UI
+    // continuation (opts.rng / opts.rngState), store_reset, seed_randart,
+    // seed_flavor, player outfit, and level gen. C player-birth.c:1269-1292
+    // order is store_reset, then seed_randart immediately followed by
+    // seed_flavor; prepare_next_level (ui-game.c:757-760) runs only later.
+    const mainRng = opts.rng ?? new Rng(opts.seed ?? 1);
+    if (!opts.rng && opts.rngState)
+        mainRng.setState(opts.rngState);
+    const race = (opts.raceName ? players.raceByName(opts.raceName) : null) ??
+        players.raceByName("Human") ??
+        players.races[0];
+    const cls = (opts.className ? players.classByName(opts.className) : null) ??
+        players.classByName("Warrior") ??
+        players.classes[0];
+    const body = players.bodies[race.body] ?? players.bodies[0];
+    // Point-based birth: apply the chosen allocation (drawing no stat RNG) only
+    // when the roller method is "point" AND a full stat array was supplied;
+    // otherwise fall through to the classic roller (the unchanged default).
+    const usePointBuy = opts.roller === "point" &&
+        opts.birthStats !== undefined &&
+        opts.birthStats.length === STAT_MAX;
+    // The accepted standard-roller stats ride opts.rolledStats (gap, birth
+    // thread-through): applied verbatim, they draw no stat RNG, so the character
+    // is born with exactly the set the roller UI showed.
+    const useRolledStats = opts.rolledStats !== undefined && opts.rolledStats.length === STAT_MAX;
+    // Character birth draws (roll_hp / ahw / history / stats) run before
+    // store_reset, matching C accept order where player_generate / roll_hp
+    // precede store_reset (player-birth.c:1236-1270). When the shell already
+    // advanced the stream for birth UI and supplies rolledStats/history, only
+    // roll_hp / ahw / the history walk remain here.
+    const birth = generatePlayer(race, cls, {
+        body,
+        historyChart: players.historyChart(race),
+        ...(useRolledStats ? { rolledStats: opts.rolledStats } : {}),
+        ...(usePointBuy ? { stats: opts.birthStats } : {}),
+        ...(opts.history !== undefined ? { historyOverride: opts.history } : {}),
+    }, mainRng);
+    // player_quests_reset (player-quest.c L157, called from player_birth): copy
+    // the standard quest table into the fresh character's quest history so
+    // is_quest and quest_check see the Sauron/Morgoth guardians from turn one.
+    playerQuestsReset(birth.player, reg.quests);
+    // C player-birth.c:1269-1292 then ui-game.c:757-760:
+    //   store_reset -> seed_randart -> seed_flavor -> (later) prepare_next_level
+    // Town store_reset draws on the main stream BEFORE both seeds; level gen
+    // draws come AFTER both seeds. Gated on starting depth 0 so a game that
+    // begins in the dungeon (tests) still draws no store RNG until town.
+    const startDepth = opts.depth ?? 1;
+    let earlyStores;
+    if (reg.stores && startDepth === 0) {
+        const bookKeys = new Set(birth.player.cls.magic.books.map((b) => `${b.tvalIdx},${b.sval}`));
+        const storeDeps = {
+            reg: reg.objects,
+            alloc: new ObjAllocState(reg.objects, reg.constants),
+            constants: reg.constants,
+            artifacts: new ArtifactState(reg.objects.artifacts.length),
+            noArtifacts: options.get("birth_no_artifacts") ?? false,
+            timedFoil: buildCurseTimedFoil(players.timed),
+            canBrowseBook: (kind) => bookKeys.has(`${kind.tval},${kind.sval}`),
+            noSelling: options.get("birth_no_selling") ?? false,
+        };
+        earlyStores = createTownStores(reg.stores.stores, storeDeps, mainRng, birth.player.maxDepth, players.classes);
+    }
+    // OPT(player, birth_randarts) (obj-randart.c do_randart): seed_randart =
+    // randint0(0x10000000) on the main stream (player-birth.c:1285), then
+    // seed_flavor immediately after (player-birth.c:1291).
+    let randartSeed = 0;
+    if (options.get("birth_randarts")) {
+        randartSeed = mainRng.randint0(0x10000000);
+        swapRandartSet(reg, randartSeed, buildCurseTimedFoil(players.timed), buildActivationSummarizer(pack, reg));
+    }
+    const seedFlavor = mainRng.randint0(0x10000000);
+    // aup_info[] (obj-make.c): the game's shared artifact-created registry.
+    // Built AFTER swapRandartSet so its length matches the (index-preserving)
+    // final artifact set, and BEFORE bootLevel so the starting level shares it.
+    const artifacts = new ArtifactState(reg.objects.artifacts.length);
+    const noArtifacts = options.get("birth_no_artifacts") ?? false;
+    // player_outfit (player-birth.c L1299): after seed_flavor, before level gen.
+    const gear = newGear();
+    /* object_flavor_aware(p, obj) on each start item (player-birth.c:650) has to
+     * wait for wireGame to build the awareness store, so collect the kinds here
+     * and apply them below. Without this a Warrior's own starting Flask of Oil
+     * read as "a Clear Flask" - named by flavour, as though they had found it on
+     * the floor. */
+    const startKinds = [];
+    outfitPlayer(gear, birth.player, reg.objects, mainRng, reg.constants, {
+        opt: (name) => options.get(name) ?? false,
+        onStartKind: (kind) => void startKinds.push(kind),
+    });
+    // prepare_next_level (ui-game.c:757-760): level generation AFTER both seeds.
+    const booted = bootLevel(pack, {
+        ...opts,
+        rng: mainRng,
+        registries: reg,
+        artifacts,
+        noArtifacts,
+    });
+    // Resolve the worn objects by body slot; calc_bonuses reads them for the
+    // equipment analysis, and the wielded weapon drives melee (py_attack).
+    const equipment = birth.player.equipment.map((h) => h ? gearGet(gear, h) : null);
+    const weaponSlot = birth.player.body.slots.findIndex((s) => s.type === "WEAPON");
+    const weapon = weaponSlot >= 0 ? (equipment[weaponSlot] ?? null) : null;
+    const pstate = calcBonuses(birth.player, {
+        equipment,
+        timedEffects: players.timed,
+        curses: reg.objects.curses,
+        update: true,
+    });
+    const combat = toCombatState(pstate);
+    // Spell bookkeeping for casting classes: size the spell arrays, compute
+    // the learnable-spell allowance (calc_spells) and mana (calc_mana, with
+    // the worn-armor weight over the class allowance as the penalty).
+    playerSpellsInit(birth.player);
+    calcSpells(birth.player, pstate.statInd);
+    /* Record cumber_armor on the birth state too, so the first refreshDerived of
+     * the game diffs against the true starting value and cannot announce an
+     * armour change that never happened. */
+    pstate.cumberArmor = calcMana(birth.player, pstate.statInd, wornArmorWeight(birth.player, equipment));
+    birth.player.csp = birth.player.msp; // born rested, full mana
+    const spot = booted.playerSpot ?? loc(1, 1);
+    const actor = {
+        player: birth.player,
+        grid: spot,
+        energy: 0,
+        speed: pstate.speed,
+        totalEnergy: 0,
+        combat,
+        defense: toDefenderState(pstate),
+        weapon,
+        stealth: combat.skills[SKILL.STEALTH] ?? 0,
+        light: pstate.curLight,
+        unlight: pstate.pflags.has(PF.UNLIGHT),
+    };
+    const state = {
+        rng: booted.rng,
+        chunk: booted.chunk,
+        actor,
+        gear,
+        monsters: [null],
+        groups: [null],
+        floor: new Map(),
+        traps: new Map(),
+        known: newKnownMap(booted.chunk.width, booted.chunk.height),
+        target: newTargetState(),
+        ignore: new IgnoreSettings(),
+        autoinscribe: new AutoinscriptionRegistry(),
+        runeNotes: new RuneNoteRegistry(),
+        options,
+        artifacts,
+        /* Effective mod-rule flags (declarative bundled-mod seam): absent/empty =
+         * faithful 4.2.6. Seeded a copy so later menu toggles mutate this map, not
+         * the caller's. */
+        ...(opts.modRules ? { modRules: { ...opts.modRules } } : {}),
+        /* The behaviour seam itself, already composed by the host. Not copied: it is
+         * a fold of functions, not mutable player state, and the menu re-composes it
+         * rather than editing it in place. */
+        ...(opts.modHooks ? { modHooks: opts.modHooks } : {}),
+        lore: new Map(),
+        /* birth_levels_persist (#30) frozen-level cache; empty until a level is
+         * left with the option on (the whole persist path is option-gated). */
+        levelCache: new Map(),
+        turn: 0,
+        z: {
+            ...DEFAULT_GAME_CONSTANTS,
+            maxSight: reg.constants.maxSight,
+            maxRange: reg.constants.maxRange,
+            floorSize: reg.constants.floorSize,
+            maxDepth: reg.constants.maxDepth,
+            stairSkip: reg.constants.stairSkip,
+            dayLength: reg.constants.dayLength,
+            foodValue: reg.constants.foodValue,
+            allocMonsterChance: reg.constants.allocMonsterChance,
+            storeTurns: reg.constants.storeTurns,
+            lifeDrainPercent: reg.constants.lifeDrainPercent,
+            levelMonsterMax: reg.constants.levelMonsterMax,
+        },
+        brands: reg.objects.brands,
+        slays: reg.objects.slays,
+        /* Placeholder; wireGame installs the full registry-backed env. */
+        runeEnv: makeRuneEnv(() => null, () => false),
+        playing: true,
+        isDead: false,
+        generateLevel: false,
+        nextCommand: () => null,
+        // store_reset already ran on the main stream before seed_randart/flavor.
+        ...(earlyStores ? { stores: earlyStores } : {}),
+    };
+    // seed_flavor already drawn above; flavor_init runs inside wireGame.
+    if (opts.updateFov)
+        state.updateFov = opts.updateFov;
+    const wired = wireGame(state, reg, players, pstate, seedFlavor, pack);
+    /* PU_INVEN from the starting kit's inven_carry (player-birth.c). */
+    buildGearViews(state, reg, pstate.ammoTval);
+    // kind->everseen = true for each bought start item (player-birth.c L658). At
+    // birth the gear holds only the starting kit, so marking every carried kind
+    // is exactly the start-item set. Pure Set insert, no RNG.
+    for (const obj of state.gear.store.values()) {
+        wired.everseen.markKind(obj.kind);
+    }
+    // object_flavor_aware(p, obj) per start item (player-birth.c:650), applied now
+    // that flavor_init has run and the awareness store exists. NOOP deps, not the
+    // live ones: upstream's L2276-79 ignore side effects re-check a pack that does
+    // not exist yet at this point in birth, and the first real notice_stuff pass
+    // covers it. No RNG.
+    for (const kind of startKinds) {
+        wired.flavor.objectFlavorAware(kind, NOOP_FLAVOR_AWARE_DEPS);
+    }
+    // birth_know_runes (player-birth.c L1261-1262): a birth_know_runes character
+    // knows every rune for ID-on-walkover (gap 1.5). No RNG. Before
+    // player_learn_innate, matching the C acceptance order.
+    if (options.get("birth_know_runes")) {
+        playerLearnAllRunes(birth.player, state.runeEnv);
+    }
+    // birth_know_flavors (player-birth.c L1295-1296): a birth_know_flavors
+    // character is aware of every flavoured kind for auto-ID of consumables (gap
+    // 1.5). flavor_init already ran inside wireGame. No RNG.
+    if (options.get("birth_know_flavors")) {
+        flavorSetAllAware(wired.flavor, reg.objects.kinds, (k) => state.hasFlavor ? state.hasFlavor(k) : false);
+    }
+    // Racial rune knowledge (player-birth.c L1274 player_learn_innate) and the
+    // starting kit's obvious runes (L495 object_learn_on_wield): the outfit
+    // wield ran before the rune env existed and learned only the modifier
+    // runes, so run the full wield learning over the worn items now (their
+    // WORN notice bit is still clear).
+    playerLearnInnate(birth.player, state.runeEnv);
+    for (let i = 0; i < birth.player.body.count; i++) {
+        const worn = state.runeEnv.slotObject(i);
+        if (worn)
+            objectLearnOnWield(birth.player, worn, state.runeEnv);
+    }
+    populateFromLevel(state, {
+        playerSpot: booted.playerSpot,
+        monsters: booted.monsters,
+        objects: booted.objects,
+        trapGrids: booted.trapGrids,
+        traps: booted.traps,
+        lockedDoors: booted.lockedDoors,
+        depth: booted.depth,
+    }, wired.trapDeps);
+    // Stores already created pre-seed when startDepth === 0; refresh is then a
+    // daycount-0 no-op. Depth > 0 still no-ops until the first town entry.
+    refreshTownStores(state, reg);
+    /* town_gen -> cave_illuminate (gen-cave.c / cave-map.c L555): the birth town
+     * is illuminated at generation. The chunk-flag half ran in the town builder;
+     * this applies the player-KNOWLEDGE half so a daytime town is fully memorized
+     * (visible from the spawn corner on entry, exactly like the C town) and a
+     * night town forgets its boring floors. Town only (booted depth 0); the level
+     * changer (changeLevel) does the same for recall-to-town. */
+    if (booted.depth === 0) {
+        caveKnown(state);
+        caveIlluminateKnown(state, isDaytime(state.turn, state.z.dayLength));
+    }
+    /*
+     * only_partial during the initial level-entry FOV (ui-display.c:2522 /
+     * cave-view.c:851): C sets this for the first new-level display too, not
+     * only for later change_level transitions.
+     *
+     * The guard used to be load-bearing: with no default updateFov, a host that had
+     * not wired one yet got NO initial flood, and onlyPartial was left set for it to
+     * run later. That is what left an agent with a blank map - it never wired one, so
+     * the else branch was the whole story rather than a fallback. wireGame now
+     * installs a default, so the branch is always taken. The `if` stays because a
+     * host may still replace the seam with its own, and one that deleted it outright
+     * should get silence rather than a crash.
+     */
+    state.chunk.onlyPartial = true;
+    if (state.updateFov) {
+        state.updateFov(state);
+        announceFeeling(state, reg);
+        search(state); /* on_new_level (game-world.c:1052). */
+        state.chunk.onlyPartial = false;
+    }
+    return {
+        state,
+        registry: wired.registry,
+        effects: wired.effects,
+        booted,
+        players,
+        flavor: wired.flavor,
+        everseen: wired.everseen,
+        seedFlavor,
+        /* A freshly-birthed game is core-only, deterministic, with no mod bags or
+         * quarantined content (P7.2). A future mod loader seeds a richer manifest. */
+        manifest: coreOnlyManifest(),
+        mods: {},
+        orphans: {},
+        orphansAcknowledged: false,
+        options,
+        randartSeed,
+        changeLevel: makeChangeLevel(state, reg, wired.trapDeps),
+        wizardBundles: wired.wizardBundles,
+        ...makeStoreApi(state, reg, wired.flavor, options),
+    };
+}
+/**
+ * The store buy/sell/price closures a shell uses: they build the maintenance
+ * context (for restock after a purchase empties a shop), read the live flavour
+ * knowledge and no-selling option, and route through the ported store runtime.
+ * Shared by startGame and loadGame so both StartedGame results expose them.
+ */
+function makeStoreApi(state, reg, flavor, options) {
+    const storeCtx = () => ({
+        rng: state.rng,
+        deps: {
+            reg: reg.objects,
+            alloc: new ObjAllocState(reg.objects, reg.constants),
+            constants: reg.constants,
+            /* allowArtifacts=false in store generation; inert but shared. */
+            artifacts: state.artifacts ?? new ArtifactState(reg.objects.artifacts.length),
+            noArtifacts: state.options?.get("birth_no_artifacts") ?? false,
+            /* class book-rejection / curse-foil / no-selling generation foils. */
+            ...genFoilFields(state),
+        },
+        maxDepth: state.actor.player.maxDepth,
+        stores: state.stores ?? [],
+    });
+    const noSelling = () => options.get("birth_no_selling") ?? false;
+    /* update_stuff's PU_INVEN after a gear change (obj-gear.c: inven_carry /
+     * gear_object_for_use both set PU_INVEN): rebuild the computed quiver so
+     * bought/sold ammo is routed into (or out of) the quiver, exactly as the
+     * wield/takeoff/use paths already do (obj-cmd.ts). Without this a purchased
+     * bolt stays displayed in the pack instead of the quiver. Mirrors the
+     * calc_inventory opts assembled for the object commands above. */
+    const refreshQuiver = () => {
+        calcInventory(state.gear, reg.constants, {
+            store: false,
+            /* Live ammo_tval, as refreshInventory above and calcInvOpts do; without
+             * it a store purchase re-sorted the quiver ignoring the wielded
+             * launcher. */
+            ammoTval: state.playerState?.ammoTval ?? 0,
+            objectValue: (obj) => computeObjectValue(reg.objects, obj, 1, true),
+            rogueLike: state.options?.get("rogue_like_commands") ?? false,
+            characterDungeon: true,
+            msg: (text) => state.msg?.(text),
+        });
+    };
+    const txnKnow = (obj) => ({
+        flavor,
+        flavorDeps: flavorAwareDeps(state),
+        aware: flavor.isAware(obj.kind),
+        noSelling: noSelling(),
+        /* do_cmd_sell L1946-1951: selling teaches the runes as well as the flavour.
+         * buildRuneList is rebuilt per call for the same reason effect-item.ts does
+         * it (L930): a mod can add runes mid-session, so a cached list would go
+         * stale. Unused by storeBuy, which learns flavour only. */
+        learnRunes: { env: state.runeEnv, runes: buildRuneList(state.runeEnv) },
+    });
+    return {
+        buy: (store, obj, amt) => {
+            /* do_cmd_retrieve (store.c:1783): Home Take is free - no price, no
+             * ORIGIN_STORE, no shuffle/maint RNG. Reuse the existing homeRetrieve. */
+            if (store.feat === FEAT.HOME) {
+                const r = homeRetrieve(store, obj, amt, state.gear, reg.constants);
+                if (!r.ok) {
+                    return {
+                        ok: false,
+                        failure: r.failure === "no-room" ? "no-room" : "not-in-stock",
+                    };
+                }
+                refreshQuiver();
+                return r.obj
+                    ? { ok: true, price: 0, bought: r.obj }
+                    : { ok: true, price: 0 };
+            }
+            const result = storeBuy(storeCtx(), store, obj, amt, state.actor.player, state.gear, txnKnow(obj));
+            if (result.ok)
+                refreshQuiver();
+            return result;
+        },
+        sell: (store, handle, amt) => {
+            /* do_cmd_stash (store.c:2009): Home Drop is free, pack-style stacking,
+             * no value gate / note-fuel-timeout rewrite. Reuse homeStash/homeCarry. */
+            if (store.feat === FEAT.HOME) {
+                const r = homeStash(store, handle, amt, state.actor.player, state.gear, reg.constants);
+                if (!r.ok) {
+                    return {
+                        ok: false,
+                        failure: r.failure ?? "no-item",
+                    };
+                }
+                refreshQuiver();
+                return {
+                    ok: true,
+                    price: 0,
+                    ...(r.obj ? { sold: r.obj } : {}),
+                    ...(r.noneLeft !== undefined ? { noneLeft: r.noneLeft } : {}),
+                    carried: true,
+                };
+            }
+            const obj = state.gear.store.get(handle);
+            const know = obj
+                ? txnKnow(obj)
+                : { flavor, flavorDeps: flavorAwareDeps(state), aware: false, noSelling: noSelling() };
+            const result = storeSell(storeCtx(), store, handle, amt, state.actor.player, state.gear, know);
+            /* do_cmd_sell: selling an artifact reveals it (history_find_artifact,
+             * store.c L1928); if the store then discards it, it is lost (L1992). */
+            if (result.ok && result.sold?.artifact) {
+                state.onArtifactFound?.(result.sold.artifact);
+                if (result.carried === false)
+                    state.onArtifactLost?.(result.sold.artifact);
+            }
+            /* apply_autoinscription (store.c:1976-1977): "Autoinscribe if we still
+             * have any" - the remaining stack, not the sold copy. */
+            if (result.ok && result.noneLeft === false) {
+                const left = state.gear.store.get(handle);
+                if (left)
+                    state.autoinscribeObject?.(left);
+            }
+            if (result.ok)
+                refreshQuiver();
+            return result;
+        },
+        sellFloor: (store, obj, amt) => {
+            /* Home Drop from the floor pile: room check, detach, home_carry. */
+            if (store.feat === FEAT.HOME) {
+                const n = Math.min(amt, obj.number);
+                const dummy = objectCopyAmt(obj, n);
+                if (!storeCheckNum(store, dummy)) {
+                    return { ok: false, failure: "no-room" };
+                }
+                const { usable, noneLeft } = floorObjectForUse(state, obj, n);
+                homeCarry(store, usable, reg.constants);
+                refreshQuiver();
+                return {
+                    ok: true,
+                    price: 0,
+                    sold: usable,
+                    noneLeft,
+                    carried: true,
+                };
+            }
+            const result = storeSellFloor(storeCtx(), store, obj, amt, state.actor.player, txnKnow(obj), (n) => {
+                const { usable, noneLeft } = floorObjectForUse(state, obj, n);
+                return { obj: usable, noneLeft };
+            });
+            /* do_cmd_sell artifact reveal / loss, exactly as the gear-handle path. */
+            if (result.ok && result.sold?.artifact) {
+                state.onArtifactFound?.(result.sold.artifact);
+                if (result.carried === false)
+                    state.onArtifactLost?.(result.sold.artifact);
+            }
+            if (result.ok)
+                refreshQuiver();
+            return result;
+        },
+        price: (store, obj, storeBuying, qty) => priceItem(reg.objects, store, store.owner, obj, storeBuying, qty, flavor.isAware(obj.kind), noSelling()),
+        /* runesKnown matches storeSell's know (txnKnow never sets it, so the
+         * transaction treats it as false); keep the filter aligned with the sale. */
+        willBuy: (store, obj) => storeWillBuy(reg.objects, store, obj, flavor.isAware(obj.kind), noSelling(), false),
+    };
+}
+/**
+ * do_randart (obj-randart.c): generate a random artifact set from `seed` and
+ * install it in place of the registry's standard set. do_randart preserves the
+ * artifact indices (aidx), so live references and saved-object aidx lookups
+ * keep resolving; only the artifact properties change. Mutates the per-game
+ * ObjRegistry (built fresh by bindCore), never a shared global.
+ */
+/**
+ * The player-class-and-timed dependent object-generation foils shared by every
+ * live MakeDeps built after wireGame (store stock): append_object_curse's
+ * TIMED_INC foil (gap 3.2), obj_kind_can_browse book rejection (gap 3.5) and
+ * make_gold's birth_no_selling inflation (gap 3.7). The dungeon/loot makeDeps
+ * in wireGame builds these inline from players.timed (state.world is not set
+ * yet at that point). Reads the LIVE timed table so it stays correct.
+ */
+function genFoilFields(state) {
+    const keys = new Set(state.actor.player.cls.magic.books.map((b) => `${b.tvalIdx},${b.sval}`));
+    return {
+        timedFoil: buildCurseTimedFoil(state.world?.timedTable ?? []),
+        canBrowseBook: (kind) => keys.has(`${kind.tval},${kind.sval}`),
+        noSelling: state.options?.get("birth_no_selling") ?? false,
+    };
+}
+/**
+ * Build the effect_summarize_properties summarizer (effects-info.c L898)
+ * injected into remove_contradictory_activation (obj-randart.c L2420, gap 3.8).
+ * Draws no RNG; only ever nulls a redundant activation.
+ */
+function buildActivationSummarizer(pack, reg) {
+    return makeActivationSummarizer({
+        timedRecords: pack.player.timed,
+        brands: reg.objects.brands,
+        slays: reg.objects.slays,
+        ofIndex: (n) => OF[n] ?? 0,
+        elemIndex: (n) => ELEM[n] ?? -1,
+    });
+}
+function swapRandartSet(reg, seed, timedFoil, activationSummarize) {
+    /* Thread the RANDNAME_TOLKIEN corpus (names.json section 1, loaded into
+     * CoreRegistries.nameSections at boot) so artifact_gen_name draws faithful
+     * Markov names via randnameMake instead of the local syllable fallback -
+     * this also keeps the RNG draw count identical to upstream for the whole set
+     * (obj-randart.c L2713-L2724). */
+    /* artifact_curse_conflicts TIMED_INC foil (obj-randart.c L2530, gap 3.3):
+     * thread the player-timed fail tables so a randart curse an item property
+     * would foil is rejected / removable. The activation-redundancy summarizer
+     * (gap 3.8, effect_summarize_properties) is threaded via activationSummarize
+     * so remove_contradictory_activation can drop a redundant activation
+     * (obj-randart.c L2420); absent, it stays a conservative no-op. */
+    const randarts = doRandart(reg.objects, seed, reg.nameSections.get(RANDNAME_TOLKIEN), timedFoil || activationSummarize
+        ? { timedFoil, activationSummarize }
+        : undefined);
+    reg.objects.artifacts.length = 0;
+    reg.objects.artifacts.push(...randarts);
+}
+/** The worn-armor weight calc_mana penalizes (non-weapon/bow/jewelry slots). */
+function wornArmorWeight(player, equipment) {
+    let weight = 0;
+    for (let i = 0; i < player.body.count; i++) {
+        const slotType = player.body.slots[i]?.type ?? "";
+        if (slotType === "WEAPON" ||
+            slotType === "BOW" ||
+            slotType === "RING" ||
+            slotType === "AMULET" ||
+            slotType === "LIGHT") {
+            continue;
+        }
+        const worn = equipment[i];
+        if (worn)
+            weight += worn.weight;
+    }
+    return weight;
+}
+/** Serialize a started game into the JSON save format (decision 9). */
+export function saveGame(game) {
+    const ids = new ContentIdResolver(game.booted.registries);
+    const save = serializeGame(game.state, game.flavor, game.seedFlavor, ids, game.randartSeed, game.everseen);
+    /* The mod-lifecycle blocks (P7.2): the manifest fingerprint always travels
+     * with the save; the per-mod bags and any quarantined orphans ride along only
+     * when non-empty, so a core-only save stays clean. */
+    save.manifest = game.manifest;
+    if (Object.keys(game.mods).length > 0)
+        save.mods = game.mods;
+    if (Object.keys(game.orphans).length > 0)
+        save.orphans = game.orphans;
+    if (game.orphansAcknowledged)
+        save.orphansAcknowledged = true;
+    return save;
+}
+export function loadGame(pack, saveIn, present = new Set(["core"]), opts = {}) {
+    if (saveIn.version !== SAVE_VERSION) {
+        throw new Error(`save: unsupported version ${saveIn.version}`);
+    }
+    const reg = bindCore(pack);
+    const players = bindPlayer(pack.player);
+    registerBookKinds(reg.objects, players.classes);
+    // The mod-lifecycle blocks (P7.2). The manifest fingerprint is core-only for
+    // saves written before the mod substrate. Reconcile the mod set against the
+    // packs present now: first rehydrate any orphans whose pack has returned, then
+    // quarantine live entities whose defining pack is missing or shadowed - so the
+    // deserializers below only ever see ids the present packs can resolve, instead
+    // of throwing on a removed mod. `present` defaults to core-only; a future mod
+    // loader passes the actually-loaded namespace set.
+    const manifest = {
+        ...(saveIn.manifest ?? coreOnlyManifest()),
+        /* Saves written before the gameplay-mod ratchet remain scoreable until a
+         * gameplay-affecting mod is actually enabled. */
+        modNoscore: saveIn.manifest?.modNoscore ?? false,
+    };
+    const isPresent = (ns) => present.has(ns);
+    const quarantine = quarantineSave(rehydrateSave(saveIn, isPresent), manifest, isPresent);
+    const save = quarantine.save;
+    // The content-id resolver: every namespaced string id in the save resolves
+    // back to a runtime index against this bound pack (mod/ids.ts). The feature
+    // remap turns the save's terrain-legend indices into this pack's indices.
+    const ids = new ContentIdResolver(reg);
+    const featRemap = buildFeatRemap(save.featLegend, ids);
+    // Restore the option store (older saves lack it: table defaults). Do this
+    // before the artifact-set swap so birth_randarts is known.
+    const options = save.options
+        ? OptionState.restore(save.options)
+        : new OptionState();
+    // OPT(player, birth_randarts): rebuild the same random artifact set from the
+    // persisted seed, so saved-object aidx references resolve to the identical
+    // randarts (do_randart preserves indices). Off / seed 0: the standard set.
+    const randartSeed = save.randartSeed ?? 0;
+    if (options.get("birth_randarts") && randartSeed) {
+        swapRandartSet(reg, randartSeed, buildCurseTimedFoil(players.timed), buildActivationSummarizer(pack, reg));
+    }
+    // aup_info[] (load.c): the artifact-created registry. Restore the saved
+    // flags (built after swapRandartSet so aidx references align); older saves
+    // predate the field and load with an all-false set (a fresh game's state).
+    const artifacts = save.artifactsCreated || save.artifactsSeen || save.artifactsEverseen
+        ? ArtifactState.restore({
+            created: deserializeArtifactsCreated(save.artifactsCreated, reg.objects.artifacts.length, ids),
+            seen: deserializeArtifactFlags(save.artifactsSeen, reg.objects.artifacts.length, ids),
+            everseen: deserializeArtifactFlags(save.artifactsEverseen, reg.objects.artifacts.length, ids),
+        })
+        : new ArtifactState(reg.objects.artifacts.length);
+    const chunk = save.chunk
+        ? deserializeChunk(save.chunk, reg.features, featRemap)
+        : new Chunk(reg.features, 1, 1);
+    if (!save.chunk && save.dungeonDepth !== undefined) {
+        chunk.depth = save.dungeonDepth;
+    }
+    const player = deserializePlayer(save.player, players, reg.objects, ids);
+    const gear = deserializeGear(save.gear, reg.objects, ids);
+    const equipment = player.equipment.map((h) => (h ? gearGet(gear, h) : null));
+    const weaponSlot = player.body.slots.findIndex((s) => s.type === "WEAPON");
+    const weapon = weaponSlot >= 0 ? (equipment[weaponSlot] ?? null) : null;
+    const pstate = calcBonuses(player, {
+        equipment,
+        timedEffects: players.timed,
+        curses: reg.objects.curses,
+        update: true,
+    });
+    /* cumber_armor is calc_mana's to set, and a resumed character's msp is
+     * restored from the save rather than recomputed - so derive the flag alone,
+     * without touching msp/csp. Skipping it would make the first refreshDerived
+     * of the session diff false -> true and announce that a mage's armour had
+     * just become too heavy, on a character who simply loaded their save. */
+    pstate.cumberArmor = cumberArmorFrom(player, wornArmorWeight(player, equipment));
+    const combat = toCombatState(pstate);
+    const rng = new Rng(1);
+    rng.setState(save.rng);
+    const actor = {
+        player,
+        grid: loc(save.actor.grid.x, save.actor.grid.y),
+        energy: save.actor.energy,
+        speed: pstate.speed,
+        totalEnergy: save.actor.totalEnergy,
+        combat,
+        defense: toDefenderState(pstate),
+        weapon,
+        stealth: combat.skills[SKILL.STEALTH] ?? 0,
+        light: pstate.curLight,
+        unlight: pstate.pflags.has(PF.UNLIGHT),
+    };
+    /* load.c:1473-1505 marks cave->decoy while rd_traps reads the active cave. */
+    let decoy = null;
+    const loadedTraps = !save.isDead && reg.traps
+        ? deserializeTraps(save.traps, reg.traps, chunk.width, ids, (grid) => {
+            decoy = grid;
+        })
+        : new Map();
+    const state = {
+        rng,
+        chunk,
+        actor,
+        gear,
+        decoy,
+        monsters: (save.isDead ? [null] : (save.monsters ?? [null])).map((m) => m ? deserializeMonster(m, reg.monsters, reg.objects, ids) : null),
+        groups: (save.isDead ? [null] : (save.groups ?? [null])).map((g) => g ? { index: g.index, leader: g.leader, members: [...g.members] } : null),
+        floor: !save.isDead && save.floor
+            ? deserializeFloor(save.floor, reg.objects, chunk.width, ids)
+            : new Map(),
+        traps: loadedTraps,
+        known: save.isDead
+            ? newKnownMap(chunk.width, chunk.height)
+            : deserializeKnown(save.known, chunk.width, chunk.height, featRemap),
+        /* birth_levels_persist (#30) frozen-level cache; empty in saves written
+         * before the field or with the option off (back-compat). */
+        levelCache: deserializeLevelCache(save.isDead ? undefined : save.levelCache, reg.features, reg.monsters, reg.objects, reg.traps, ids),
+        /*
+         * Terrain-only Town cache (wr_chunks / load.c:1701-1704): restore even when
+         * birth_levels_persist is off so town re-entry keeps seed parity.
+         */
+        ...(() => {
+            if (save.isDead || !save.townChunk)
+                return {};
+            const townRemap = buildFeatRemap(save.townFeatLegend, ids);
+            return {
+                townChunk: deserializeChunk(save.townChunk, reg.features, townRemap),
+            };
+        })(),
+        /* The target is not persisted (as upstream: the savefile carries no
+         * target and loading starts unset). */
+        target: newTargetState(),
+        ignore: new IgnoreSettings(),
+        autoinscribe: new AutoinscriptionRegistry(),
+        runeNotes: new RuneNoteRegistry(),
+        options,
+        artifacts,
+        /* Effective mod-rule flags (declarative bundled-mod seam): the host
+         * recomputes these from the enabled mods + saved choices and passes them on
+         * load, so they are a client setting (like the enabled-mod set), not part of
+         * the savefile. Absent/empty = faithful 4.2.6. */
+        ...(opts.modRules ? { modRules: { ...opts.modRules } } : {}),
+        /* And the composed behaviour, recomputed by the host on load for the same
+         * reason the flags are: which mods are enabled is a client setting. */
+        ...(opts.modHooks ? { modHooks: opts.modHooks } : {}),
+        lore: deserializeLore(save.lore, ids),
+        /* Town stores + accrued daycount (rd_stores, gaps 12.1/12.2/12.3). Restored
+         * from the save (never re-rolled) so the home stash and shop stock survive;
+         * deserializeStores draws no RNG, so the resumed stream stays exact. Absent
+         * in older saves / saves taken before reaching town: left undefined here and
+         * lazily created by refreshTownStores on the next town entry (back-compat). */
+        ...(save.stores && reg.stores
+            ? {
+                stores: deserializeStores(reg.stores.stores, save.stores, reg.objects, ids, reg.constants.storeInvenMax),
+            }
+            : {}),
+        ...(save.daycount ? { daycount: save.daycount } : {}),
+        /* Player-side transient scalars (save.c: wr_player). Absent in older saves
+         * / falsy defaults load as unset, matching a fresh character. */
+        ...(save.restingTurn ? { restingTurn: save.restingTurn } : {}),
+        ...(save.skipCmdCoercion ? { skipCmdCoercion: save.skipCmdCoercion } : {}),
+        ...(save.unignoring ? { unignoring: save.unignoring } : {}),
+        ...(save.nameSuffix ? { nameSuffix: save.nameSuffix } : {}),
+        /* Running message log (rd_messages, load.c:471-495, gap 12.8): re-add each
+         * saved entry oldest-first; older saves without the field load empty. */
+        messages: deserializeMessages(save.messages),
+        /* chunk->join of the level in play (gap 9.4/9.6): restore the stair
+         * connectors so a first-visit persistent level still aligns after reload. */
+        ...(!save.isDead && save.currentJoins
+            ? {
+                currentJoins: save.currentJoins.map((j) => ({
+                    grid: loc(j.x, j.y),
+                    feat: featRemap.get(j.feat) ?? j.feat,
+                    ...(j.info ? { info: [...j.info] } : {}),
+                })),
+            }
+            : {}),
+        turn: save.turn,
+        z: {
+            ...DEFAULT_GAME_CONSTANTS,
+            maxSight: reg.constants.maxSight,
+            maxRange: reg.constants.maxRange,
+            floorSize: reg.constants.floorSize,
+            maxDepth: reg.constants.maxDepth,
+            stairSkip: reg.constants.stairSkip,
+            dayLength: reg.constants.dayLength,
+            foodValue: reg.constants.foodValue,
+            allocMonsterChance: reg.constants.allocMonsterChance,
+            storeTurns: reg.constants.storeTurns,
+            lifeDrainPercent: reg.constants.lifeDrainPercent,
+            levelMonsterMax: reg.constants.levelMonsterMax,
+        },
+        brands: reg.objects.brands,
+        slays: reg.objects.slays,
+        /* Placeholder; wireGame installs the full registry-backed env. */
+        runeEnv: makeRuneEnv(() => null, () => false),
+        playing: save.playing,
+        isDead: save.isDead,
+        generateLevel: false,
+        nextCommand: () => null,
+    };
+    /* Rebuild the racial counts from the restored monster list (the save
+     * carries the monsters, not the registry-side counters). */
+    countMonsterRaces(state);
+    /* SV-01 (load.c:532-535 rd_monster_memory, "ensure dead uniques stay dead";
+     * mon-make.c:257 refuses a unique whose max_num is exhausted):
+     * a fresh registry starts every UNIQUE at maxNum=1, and countMonsterRaces
+     * above only rebuilds curNum from the live monster list - so a unique the
+     * player already killed (restored lore pkills>0, but no live copy) would bind
+     * back at maxNum=1 and could respawn / be re-killed after a reload. Re-derive
+     * maxNum=0 for those uniques, exactly as upstream does on load. */
+    for (const race of reg.monsters.races) {
+        if (!race)
+            continue;
+        if (race.flags.has(RF.UNIQUE) &&
+            (state.lore.get(race.ridx)?.pkills ?? 0) > 0) {
+            race.maxNum = 0;
+        }
+    }
+    /* savefile.c:647-651: loading a DEAD character with the wizard/cheat-death
+     * launch flag set resurrects it (is_dead cleared, HP refilled) and flags it
+     * NOSCORE_WIZARD, keeping it off the high-score table (gap 15.3). A normal
+     * load (wizard off) leaves a dead character dead. */
+    if (save.isDead && opts.wizard) {
+        player.chp = player.mhp;
+        player.chpFrac = 0;
+        player.noscore = markNoscore(player.noscore, NOSCORE.WIZARD);
+        state.isDead = false;
+    }
+    /* A save taken in single combat resumes it (the stashed pre-arena
+     * level is gone: winning exits to a fresh level of the same depth). */
+    if (save.arena) {
+        state.arenaLevel = true;
+        state.oldGrid = loc(save.arena.oldGrid.x, save.arena.oldGrid.y);
+    }
+    /* seed_flavor from the save (load.c L960). Older saves predate it; fall
+     * back to 0 so flavor_init still produces a stable per-load assignment. */
+    const seedFlavor = save.seedFlavor ?? 0;
+    const wired = wireGame(state, reg, players, pstate, seedFlavor, pack);
+    /* rd_gear's tail (load.c:1187). */
+    buildGearViews(state, reg, pstate.ammoTval);
+    /* restore() replaces the aware/tried sets, so it must run AFTER flavor_init's
+     * aware-marking of non-flavoured kinds - the save is the source of truth for
+     * what the player has actually identified. */
+    wired.flavor.restore(deserializeFlavor(save.flavor, ids));
+    /* kind/ego everseen (save.c L397/L533): absent in saves written before
+     * everseen tracking, which load with an empty set. */
+    if (save.everseen)
+        wired.everseen.restore(deserializeEverseen(save.everseen, ids));
+    if (save.ignore)
+        state.ignore.restore(deserializeIgnore(save.ignore, ids));
+    /* Per-kind autoinscriptions (obj-ignore.c note_aware/note_unaware): absent in
+     * saves written before this block, which load with an empty registry. */
+    if (save.autoinscriptions && state.autoinscribe) {
+        deserializeAutoinscriptions(save.autoinscriptions, state.autoinscribe, ids);
+    }
+    /* Per-RUNE autoinscriptions (rd_ignore's rune block, load.c:934-945):
+     * rd_s16b(runeid) + rd_string, straight into rune_set_note. The savefile keys
+     * by runeKey, so resolve each back to its live buildRuneList index; a key the
+     * running pack no longer builds is dropped. Absent in saves written before
+     * this block, which load with no rune notes. */
+    if (save.runeNotes && state.runeNotes) {
+        const runes = buildRuneList(state.runeEnv);
+        const byKey = new Map();
+        runes.forEach((rune, i) => byKey.set(runeKey(rune), i));
+        for (const [key, note] of save.runeNotes) {
+            const i = byKey.get(key);
+            if (i !== undefined)
+                state.runeNotes.set(i, note);
+        }
+    }
+    // A renderer-facing view of the restored level (no generation ran).
+    const booted = {
+        chunk,
+        depth: chunk.depth,
+        playerSpot: actor.grid,
+        monsters: [],
+        objects: [],
+        trapGrids: [],
+        traps: [],
+        lockedDoors: [],
+        rng,
+        registries: reg,
+    };
+    /* Resuming in town: re-stock the shops (store stock is not persisted). */
+    refreshTownStores(state, reg);
+    return {
+        state,
+        registry: wired.registry,
+        effects: wired.effects,
+        booted,
+        players,
+        flavor: wired.flavor,
+        everseen: wired.everseen,
+        seedFlavor,
+        manifest,
+        mods: save.mods ?? {},
+        orphans: quarantine.orphans,
+        orphansAcknowledged: save.orphansAcknowledged ?? false,
+        options,
+        randartSeed,
+        changeLevel: makeChangeLevel(state, reg, wired.trapDeps, {
+            inArena: !!save.arena,
+        }),
+        wizardBundles: wired.wizardBundles,
+        ...makeStoreApi(state, reg, wired.flavor, options),
+    };
+}
+//# sourceMappingURL=game.js.map