@jgengine/core 0.19.0 → 0.22.0

package/dist/game/quest.js

@@ -7,6 +7,104 @@ import { clamp } from "../math/scalar.js";
 export function createQuestJournal(deps) {
     const catalog = new Map();
     const users = new Map();
+    const turningIn = new Set();
+    const credits = new Map();
+    const activeUsers = new Map();
+    const userKills = new Map();
+    const userCollects = new Map();
+    const sharedKills = new Map();
+    const catalogOrder = new Map();
+    function compareCredit(a, b) {
+        return a.order - b.order || a.index - b.index;
+    }
+    function updateIndex(index, key, credit, add) {
+        const bucket = index.get(key);
+        if (!add) {
+            if (!bucket)
+                return;
+            const position = bucket.indexOf(credit);
+            if (position !== -1)
+                bucket.splice(position, 1);
+            if (bucket.length === 0)
+                index.delete(key);
+            return;
+        }
+        if (!bucket) {
+            index.set(key, [credit]);
+            return;
+        }
+        let low = 0;
+        let high = bucket.length;
+        while (low < high) {
+            const middle = (low + high) >>> 1;
+            if (compareCredit(bucket[middle], credit) < 0)
+                low = middle + 1;
+            else
+                high = middle;
+        }
+        bucket.splice(low, 0, credit);
+    }
+    function updateUserIndex(userId, questId, add) {
+        for (const credit of credits.get(questId) ?? []) {
+            const indexes = credit.kind === "kill" ? userKills : userCollects;
+            let index = indexes.get(userId);
+            if (!index) {
+                if (!add)
+                    continue;
+                index = new Map();
+                indexes.set(userId, index);
+            }
+            updateIndex(index, credit.key, credit, add);
+            if (index.size === 0)
+                indexes.delete(userId);
+        }
+    }
+    function updateSharedIndex(questId, add) {
+        for (const credit of credits.get(questId) ?? []) {
+            if (credit.kind === "kill" && credit.shared) {
+                updateIndex(sharedKills, credit.key, credit, add);
+            }
+        }
+    }
+    function setActive(userId, questId, active) {
+        const members = activeUsers.get(questId);
+        if (active) {
+            if (members?.has(userId))
+                return;
+            if (members)
+                members.add(userId);
+            else {
+                activeUsers.set(questId, new Set([userId]));
+                updateSharedIndex(questId, true);
+            }
+            updateUserIndex(userId, questId, true);
+        }
+        else if (members?.delete(userId)) {
+            updateUserIndex(userId, questId, false);
+            if (members.size === 0) {
+                activeUsers.delete(questId);
+                updateSharedIndex(questId, false);
+            }
+        }
+    }
+    function hydrate(userId, data) {
+        for (const [questId, state] of users.get(userId) ?? []) {
+            if (state.status === "active")
+                setActive(userId, questId, false);
+        }
+        const quests = new Map();
+        for (const entry of data) {
+            quests.set(entry.questId, {
+                status: entry.status,
+                progress: new Map(Object.entries(entry.progress)),
+            });
+        }
+        users.set(userId, quests);
+        for (const [questId, state] of quests) {
+            if (state.status === "active")
+                setActive(userId, questId, true);
+        }
+    }
     function requireUserQuests(userId) {
         let quests = users.get(userId);
         if (!quests) {
@@ -41,6 +139,7 @@ export function createQuestJournal(deps) {
         if (denied !== null)
             return denied;
         requireUserQuests(userId).set(questId, { status: "active", progress: new Map() });
+        setActive(userId, questId, true);
         deps.events.emit("quest.accepted", { userId, questId });
         return null;
     }
@@ -67,6 +166,8 @@ export function createQuestJournal(deps) {
         if (state === undefined || state.status !== "active") {
             return { reason: `quest "${questId}" is not active` };
         }
+        if (turningIn.has(state))
+            return { reason: `quest "${questId}" is already turning in` };
         for (const objective of def.objectives) {
             if ((state.progress.get(objective.id) ?? 0) < objective.count) {
                 return { reason: `objective "${objective.id}" incomplete` };
@@ -75,20 +176,15 @@ export function createQuestJournal(deps) {
         return null;
     }
     function applyRewards(userId, rewards) {
-        for (const entry of rewards.items ?? []) {
-            const fail = deps.rewards.grantItem(userId, entry.inventory, entry.item, entry.count);
-            if (fail !== null)
-                return fail;
-        }
-        if (rewards.xp)
-            deps.rewards.grantXp(userId, rewards.xp.amount);
-        for (const [currencyId, amount] of Object.entries(rewards.economy ?? {})) {
-            deps.rewards.grantEconomy(userId, currencyId, amount);
-        }
-        for (const unlockId of rewards.unlocks ?? []) {
-            deps.rewards.grantUnlock(userId, unlockId);
-        }
-        return null;
+        return applyQuestRewards(rewards, {
+            grantItem: (inventoryId, itemId, count) => deps.rewards.grantItem(userId, inventoryId, itemId, count),
+            grantItems: deps.rewards.grantItems === undefined
+                ? undefined
+                : (items) => deps.rewards.grantItems(userId, items),
+            grantXp: (amount) => deps.rewards.grantXp(userId, amount),
+            grantEconomy: (currencyId, amount) => deps.rewards.grantEconomy(userId, currencyId, amount),
+            grantUnlock: (unlockId) => deps.rewards.grantUnlock(userId, unlockId),
+        });
     }
     function turnIn(userId, questId) {
         const denied = canTurnIn(userId, questId);
@@ -96,49 +192,95 @@ export function createQuestJournal(deps) {
             return denied;
         const def = catalog.get(questId);
         const state = users.get(userId).get(questId);
-        if (def.rewards) {
-            const fail = applyRewards(userId, def.rewards);
-            if (fail !== null)
-                return fail;
+        turningIn.add(state);
+        try {
+            if (def.rewards) {
+                const fail = applyRewards(userId, def.rewards);
+                if (fail !== null)
+                    return fail;
+            }
+            state.status = "completed";
+            setActive(userId, questId, false);
+            deps.events.emit("quest.completed", { userId, questId });
+            for (const nextQuestId of def.rewards?.quests ?? []) {
+                if (canAccept(userId, nextQuestId) === null)
+                    accept(userId, nextQuestId);
+            }
+            return null;
         }
-        state.status = "completed";
-        deps.events.emit("quest.completed", { userId, questId });
-        for (const nextQuestId of def.rewards?.quests ?? []) {
-            if (canAccept(userId, nextQuestId) === null)
-                accept(userId, nextQuestId);
+        finally {
+            turningIn.delete(state);
         }
-        return null;
     }
     function creditKill(killerUserId, catalogId) {
-        for (const def of catalog.values()) {
-            for (const objective of def.objectives) {
-                if (objective.kind !== "kill" || objective.target !== catalogId)
-                    continue;
-                const recipients = new Set([killerUserId]);
-                if (objective.partyShare?.credit === "all" && deps.partyMembersNear) {
-                    for (const member of deps.partyMembersNear(killerUserId, objective.partyShare.radius)) {
-                        recipients.add(member);
-                    }
+        const direct = userKills.get(killerUserId)?.get(catalogId) ?? [];
+        const shared = deps.partyMembersNear ? sharedKills.get(catalogId) ?? [] : [];
+        const candidates = [];
+        let a = 0;
+        let b = 0;
+        while (a < direct.length || b < shared.length) {
+            const left = direct[a];
+            const right = shared[b];
+            if (left && right && left === right) {
+                candidates.push(left);
+                a++;
+                b++;
+            }
+            else if (left && (!right || compareCredit(left, right) < 0)) {
+                candidates.push(left);
+                a++;
+            }
+            else {
+                candidates.push(right);
+                b++;
+            }
+        }
+        for (const { questId, objective } of candidates) {
+            const recipients = new Set([killerUserId]);
+            if (objective.partyShare?.credit === "all" && deps.partyMembersNear) {
+                for (const member of deps.partyMembersNear(killerUserId, objective.partyShare.radius)) {
+                    recipients.add(member);
                 }
-                for (const userId of recipients)
-                    progress(userId, def.id, objective.id, 1);
             }
+            for (const userId of recipients)
+                progress(userId, questId, objective.id, 1);
         }
     }
     function creditCollect(userId, itemId, count) {
-        for (const def of catalog.values()) {
-            for (const objective of def.objectives) {
-                if (objective.kind !== "collect" || objective.item !== itemId)
-                    continue;
-                progress(userId, def.id, objective.id, count);
-            }
+        const candidates = userCollects.get(userId)?.get(itemId)?.slice() ?? [];
+        for (const { questId, objective } of candidates) {
+            progress(userId, questId, objective.id, count);
         }
     }
     return {
         register(defs) {
             const entries = Array.isArray(defs) ? defs : Object.values(defs);
-            for (const def of entries)
+            for (const def of entries) {
+                const members = activeUsers.get(def.id);
+                if (members) {
+                    for (const userId of members)
+                        updateUserIndex(userId, def.id, false);
+                    updateSharedIndex(def.id, false);
+                }
+                if (!catalogOrder.has(def.id))
+                    catalogOrder.set(def.id, catalogOrder.size);
                 catalog.set(def.id, def);
+                credits.set(def.id, def.objectives.flatMap((objective, index) => {
+                    const kind = objective.kind;
+                    if (kind !== "kill" && kind !== "collect")
+                        return [];
+                    const key = kind === "kill" ? objective.target : objective.item;
+                    if (key === undefined)
+                        return [];
+                    return [{ questId: def.id, objective, order: catalogOrder.get(def.id), index,
+                            kind, key, shared: objective.partyShare?.credit === "all" }];
+                }));
+                if (members) {
+                    for (const userId of members)
+                        updateUserIndex(userId, def.id, true);
+                    updateSharedIndex(def.id, true);
+                }
+            }
         },
         has(questId) {
             return catalog.has(questId);
@@ -147,8 +289,10 @@ export function createQuestJournal(deps) {
         accept,
         abandon(userId, questId) {
             const quests = users.get(userId);
-            if (quests?.get(questId)?.status === "active")
+            if (quests?.get(questId)?.status === "active") {
                 quests.delete(questId);
+                setActive(userId, questId, false);
+            }
         },
         progress,
         canTurnIn,
@@ -167,6 +311,7 @@ export function createQuestJournal(deps) {
                 status: completed ? "completed" : "active",
                 progress: progressMap,
             });
+            setActive(userId, questId, !completed);
             if (completed)
                 deps.events.emit("quest.completed", { userId, questId });
             else
@@ -174,6 +319,7 @@ export function createQuestJournal(deps) {
         },
         revoke(userId, questId) {
             users.get(userId)?.delete(questId);
+            setActive(userId, questId, false);
         },
         list(userId) {
             const quests = users.get(userId);
@@ -223,16 +369,7 @@ export function createQuestJournal(deps) {
                 progress: Object.fromEntries(state.progress),
             }));
         },
-        hydrate(userId, data) {
-            const quests = new Map();
-            for (const entry of data) {
-                quests.set(entry.questId, {
-                    status: entry.status,
-                    progress: new Map(Object.entries(entry.progress)),
-                });
-            }
-            users.set(userId, quests);
-        },
+        hydrate,
         snapshotAll() {
             const out = {};
             for (const [userId, quests] of users) {
@@ -246,15 +383,12 @@ export function createQuestJournal(deps) {
         },
         hydrateAll(data) {
             users.clear();
+            activeUsers.clear();
+            userKills.clear();
+            userCollects.clear();
+            sharedKills.clear();
             for (const [userId, entries] of Object.entries(data)) {
-                const quests = new Map();
-                for (const entry of entries) {
-                    quests.set(entry.questId, {
-                        status: entry.status,
-                        progress: new Map(Object.entries(entry.progress)),
-                    });
-                }
-                users.set(userId, quests);
+                hydrate(userId, entries);
             }
         },
     };
@@ -290,9 +424,21 @@ export function describeTrackedQuest(def, instance, label = defaultObjectiveLabe
         }),
     };
 }
+/**
+ * Apply items before XP, currency, and unlocks. Multiple items require an all-or-reject `grantItems`
+ * callback; legacy single-item appliers remain supported. Rejected callbacks must make no writes.
+ * Arbitrary callback side effects or thrown exceptions cannot be rolled back by this helper.
+ */
 export function applyQuestRewards(rewards, appliers) {
-    for (const entry of rewards.items ?? []) {
-        const fail = appliers.grantItem?.(entry.inventory, entry.item, entry.count);
+    const items = rewards.items ?? [];
+    if (items.length > 1 && appliers.grantItems === undefined) {
+        return { reason: "multiple quest item rewards require grantItems" };
+    }
+    if (items.length > 0) {
+        const entry = items[0];
+        const fail = appliers.grantItems !== undefined
+            ? appliers.grantItems(items)
+            : appliers.grantItem?.(entry.inventory, entry.item, entry.count);
         if (fail != null && typeof fail === "object" && "reason" in fail)
             return fail;
     }

package/dist/game/questCatalog.d.ts

@@ -0,0 +1,50 @@
+import type { QuestDef, QuestObjective, QuestRewards } from "./quest.js";
+/** Readonly authoring input; mutable QuestDef catalogs also satisfy this shape. */
+export type QuestCatalogDefinition = Omit<Readonly<QuestDef>, "requires" | "objectives" | "rewards"> & {
+    requires?: readonly string[];
+    objectives: readonly Readonly<QuestObjective>[];
+    rewards?: Omit<Readonly<QuestRewards>, "items" | "unlocks" | "quests"> & {
+        items?: readonly Readonly<NonNullable<QuestRewards["items"]>[number]>[];
+        unlocks?: readonly string[];
+        quests?: readonly string[];
+    };
+};
+/** Caller-owned reference namespaces; objective kinds remain unconstrained. */
+export type QuestCatalogReferenceKind = "item" | "target" | "inventory" | "currency";
+/** A located structural issue; path is a JSON Pointer into the supplied catalog. */
+export interface QuestCatalogIssue {
+    code: "duplicate-quest" | "duplicate-objective" | "missing-requirement" | "missing-follow-up" | "missing-external-start" | "unknown-reference" | "invalid-count" | "invalid-amount" | "invalid-radius" | "blocked-prerequisites" | "dependency-cycle";
+    severity: "error" | "warning";
+    message: string;
+    path: string;
+    questId?: string;
+    objectiveId?: string;
+    referenceId?: string;
+    relatedQuestIds?: string[];
+    requirementIds?: string[];
+}
+/** Declarations and optional lookups for a game's own authoring rules. */
+export interface QuestCatalogValidationOptions {
+    /** Unlock ids that non-quest systems may grant, including ids shared with quests. */
+    externalUnlocks?: Iterable<string>;
+    /** Quests game systems may grant active, bypassing their acceptance prerequisites. */
+    externallyStartedQuests?: Iterable<string>;
+    /** Check present references against caller catalogs; omitted means unchecked. */
+    hasReference?(kind: QuestCatalogReferenceKind, id: string, context: {
+        quest: QuestCatalogDefinition;
+        objective?: Readonly<QuestObjective>;
+    }): boolean;
+}
+/**
+ * Validate catalog ids, references, quantities, and potential prerequisite progression without mutation.
+ * Requirements are completed quest ids OR unlock ids; all requirements of a quest must be met.
+ * Any eligible quest may be accepted directly. External unlocks and granted quest starts are possible
+ * entry points, not claims about their timing. Blocked progression/cycles are warnings: game systems
+ * can bypass prerequisites. Topology uses the last duplicate, matching journal registration.
+ * Traversal is iterative and linear in definitions, requirements, and their producer edges.
+ * Objective and item counts may be fractional or zero; negative/nonfinite counts are invalid.
+ * This assumes objectives can be completed and does not evaluate narrative, chronology, or balance.
+ *
+ * @capability quest-catalog-validation diagnose authored quest ids, prerequisite and reward references, quantities, and blocked dependencies with caller-declared external unlocks
+ */
+export declare function validateQuestCatalog(catalog: readonly QuestCatalogDefinition[] | Readonly<Record<string, QuestCatalogDefinition>>, options?: QuestCatalogValidationOptions): QuestCatalogIssue[];

package/dist/game/questCatalog.js

@@ -0,0 +1,205 @@
+function pointerKey(key) {
+    return key.replaceAll("~", "~0").replaceAll("/", "~1");
+}
+/**
+ * Validate catalog ids, references, quantities, and potential prerequisite progression without mutation.
+ * Requirements are completed quest ids OR unlock ids; all requirements of a quest must be met.
+ * Any eligible quest may be accepted directly. External unlocks and granted quest starts are possible
+ * entry points, not claims about their timing. Blocked progression/cycles are warnings: game systems
+ * can bypass prerequisites. Topology uses the last duplicate, matching journal registration.
+ * Traversal is iterative and linear in definitions, requirements, and their producer edges.
+ * Objective and item counts may be fractional or zero; negative/nonfinite counts are invalid.
+ * This assumes objectives can be completed and does not evaluate narrative, chronology, or balance.
+ *
+ * @capability quest-catalog-validation diagnose authored quest ids, prerequisite and reward references, quantities, and blocked dependencies with caller-declared external unlocks
+ */
+export function validateQuestCatalog(catalog, options = {}) {
+    const entries = Array.isArray(catalog)
+        ? catalog.map((quest, index) => ({ quest, path: `/${index}` }))
+        : Object.entries(catalog).map(([key, quest]) => ({ quest, path: `/${pointerKey(key)}` }));
+    const issues = [];
+    const quests = new Map();
+    const producers = new Map();
+    const externalUnlocks = new Set(options.externalUnlocks);
+    const externalStarts = new Set(options.externallyStartedQuests);
+    for (const entry of entries) {
+        const { quest, path } = entry;
+        if (quests.has(quest.id)) {
+            issues.push({ code: "duplicate-quest", severity: "error", questId: quest.id, path: `${path}/id`,
+                message: `Duplicate quest "${quest.id}"; journal registration replaces the earlier definition.` });
+        }
+        quests.set(quest.id, entry);
+    }
+    for (const { quest } of quests.values()) {
+        for (const token of new Set([quest.id, ...(quest.rewards?.unlocks ?? [])])) {
+            let sources = producers.get(token);
+            if (sources === undefined)
+                producers.set(token, sources = new Set());
+            sources.add(quest.id);
+        }
+    }
+    for (const { quest, path } of entries) {
+        function issue(code, field, message, detail = {}) {
+            issues.push({ code, severity: "error", path: `${path}/${field}`, questId: quest.id, message, ...detail });
+        }
+        function reference(kind, id, field, objective) {
+            if (id !== undefined && options.hasReference?.(kind, id, { quest, objective }) === false) {
+                issue("unknown-reference", field, `Unknown ${kind} reference "${id}".`, { referenceId: id, objectiveId: objective?.id });
+            }
+        }
+        for (const [index, id] of (quest.requires ?? []).entries()) {
+            if (!producers.has(id) && !externalUnlocks.has(id)) {
+                issue("missing-requirement", `requires/${index}`, `Requirement "${id}" is neither a catalog quest nor a declared unlock.`, { referenceId: id });
+            }
+        }
+        const objectiveIds = new Set();
+        for (const [index, objective] of quest.objectives.entries()) {
+            const field = `objectives/${index}`;
+            if (objectiveIds.has(objective.id)) {
+                issue("duplicate-objective", `${field}/id`, `Duplicate objective "${objective.id}" in quest "${quest.id}".`, { objectiveId: objective.id });
+            }
+            objectiveIds.add(objective.id);
+            if (!Number.isFinite(objective.count) || objective.count < 0) {
+                issue("invalid-count", `${field}/count`, "Objective count must be finite and nonnegative.", { objectiveId: objective.id });
+            }
+            if (objective.partyShare && (!Number.isFinite(objective.partyShare.radius) || objective.partyShare.radius < 0)) {
+                issue("invalid-radius", `${field}/partyShare/radius`, "Party share radius must be finite and nonnegative.", { objectiveId: objective.id });
+            }
+            reference("item", objective.item, `${field}/item`, objective);
+            reference("target", objective.target, `${field}/target`, objective);
+        }
+        for (const [index, id] of (quest.rewards?.quests ?? []).entries()) {
+            if (!quests.has(id)) {
+                issue("missing-follow-up", `rewards/quests/${index}`, `Reward starts unknown quest "${id}".`, { referenceId: id });
+            }
+        }
+        for (const [index, reward] of (quest.rewards?.items ?? []).entries()) {
+            const field = `rewards/items/${index}`;
+            if (!Number.isFinite(reward.count) || reward.count < 0) {
+                issue("invalid-count", `${field}/count`, "Item reward count must be finite and nonnegative.");
+            }
+            reference("item", reward.item, `${field}/item`);
+            reference("inventory", reward.inventory, `${field}/inventory`);
+        }
+        if (quest.rewards?.xp && !Number.isFinite(quest.rewards.xp.amount)) {
+            issue("invalid-amount", "rewards/xp/amount", "XP reward amount must be finite.");
+        }
+        for (const [id, amount] of Object.entries(quest.rewards?.economy ?? {})) {
+            const field = `rewards/economy/${pointerKey(id)}`;
+            if (!Number.isFinite(amount))
+                issue("invalid-amount", field, "Currency reward amount must be finite.");
+            reference("currency", id, field);
+        }
+    }
+    for (const id of externalStarts) {
+        if (!quests.has(id))
+            issues.push({ code: "missing-external-start", severity: "error", path: "",
+                referenceId: id, message: `Externally started quest "${id}" does not exist in the catalog.` });
+    }
+    const available = new Set(externalUnlocks);
+    const pending = new Map();
+    const dependents = new Map();
+    const ready = [];
+    for (const { quest } of quests.values()) {
+        let count = 0;
+        for (const token of new Set(quest.requires ?? [])) {
+            if (available.has(token))
+                continue;
+            count++;
+            let waiting = dependents.get(token);
+            if (waiting === undefined)
+                dependents.set(token, waiting = []);
+            waiting.push(quest.id);
+        }
+        pending.set(quest.id, count);
+        if (count === 0 || externalStarts.has(quest.id))
+            ready.push(quest.id);
+    }
+    const completed = new Set();
+    for (let head = 0; head < ready.length; head++) {
+        const id = ready[head];
+        if (completed.has(id))
+            continue;
+        completed.add(id);
+        const quest = quests.get(id).quest;
+        for (const token of [id, ...(quest.rewards?.unlocks ?? [])]) {
+            if (available.has(token))
+                continue;
+            available.add(token);
+            for (const next of dependents.get(token) ?? []) {
+                const remaining = pending.get(next) - 1;
+                pending.set(next, remaining);
+                if (remaining === 0)
+                    ready.push(next);
+            }
+        }
+    }
+    const graph = new Map();
+    const reverse = new Map();
+    for (const { quest, path } of quests.values()) {
+        if (completed.has(quest.id))
+            continue;
+        const unmet = [...new Set(quest.requires ?? [])].filter((id) => !available.has(id));
+        issues.push({ code: "blocked-prerequisites", severity: "warning", questId: quest.id,
+            path: `${path}/requires`, requirementIds: unmet,
+            message: `Quest "${quest.id}" has no prerequisite route from declared entry points; external grants may bypass it.` });
+        const dependencies = new Set();
+        for (const token of unmet) {
+            for (const producer of producers.get(token) ?? []) {
+                if (!completed.has(producer))
+                    dependencies.add(producer);
+            }
+        }
+        graph.set(quest.id, [...dependencies]);
+        for (const id of dependencies) {
+            let incoming = reverse.get(id);
+            if (incoming === undefined)
+                reverse.set(id, incoming = []);
+            incoming.push(quest.id);
+        }
+    }
+    const visited = new Set();
+    const order = [];
+    for (const root of graph.keys()) {
+        if (visited.has(root))
+            continue;
+        visited.add(root);
+        const stack = [{ id: root, index: 0 }];
+        while (stack.length > 0) {
+            const frame = stack[stack.length - 1];
+            const neighbors = graph.get(frame.id);
+            if (frame.index === neighbors.length) {
+                order.push(frame.id);
+                stack.pop();
+                continue;
+            }
+            const next = neighbors[frame.index++];
+            if (visited.has(next))
+                continue;
+            visited.add(next);
+            stack.push({ id: next, index: 0 });
+        }
+    }
+    visited.clear();
+    for (let index = order.length - 1; index >= 0; index--) {
+        const root = order[index];
+        if (visited.has(root))
+            continue;
+        const component = [root];
+        visited.add(root);
+        for (let head = 0; head < component.length; head++) {
+            for (const next of reverse.get(component[head]) ?? []) {
+                if (visited.has(next))
+                    continue;
+                visited.add(next);
+                component.push(next);
+            }
+        }
+        if (component.length > 1 || graph.get(root).includes(root)) {
+            issues.push({ code: "dependency-cycle", severity: "warning", questId: root,
+                path: `${quests.get(root).path}/requires`, relatedQuestIds: component,
+                message: "Blocked prerequisite producers form a cycle; review external grants or dependency references." });
+        }
+    }
+    return issues;
+}

package/dist/game/saveStore.d.ts

@@ -1,4 +1,4 @@
-import { type KeyValueStorage } from "./keyValueStore.js";
+import { type KeyValueStorage, type KeyValueStorageErrorPolicy } from "./keyValueStore.js";
 /**
  * The one async storage seam a save store persists through. Every backend
  * satisfies this same three-method shape — the browser's `localStorage`
@@ -16,17 +16,18 @@ export interface SaveBackend {
 /**
  * A {@link SaveBackend} over a synchronous {@link KeyValueStorage} — the
  * browser's `localStorage` by default (offline, on-device saves), a test stub,
- * or `null` for memory-only. Storage errors (quota exceeded, private mode, no
- * DOM) degrade to no-ops, so a save never throws into a game tick.
+ * or `null` for a no-op backend. Default fallback ignores failures; `errorMode: "throw"`
+ * rejects failed operations and unavailable storage, so SaveStore status/onError can report them.
+ * Use {@link memorySaveBackend} for deliberate ephemeral persistence.
  *
  * @capability local-save persist a game to on-device localStorage (offline)
  */
-export declare function localSaveBackend(storage?: KeyValueStorage | null): SaveBackend;
+export declare function localSaveBackend(storage?: KeyValueStorage | null, policy?: KeyValueStorageErrorPolicy): SaveBackend;
 /** A memory-only {@link SaveBackend} — saves survive a reload only within the same session. For tests, SSR, or a "no persistence" mode that still exercises the same save code path. */
 export declare function memorySaveBackend(): SaveBackend;
 /** Adopt any async `read`/`write`/`remove` trio as a {@link SaveBackend} — the seam for cloud saves backed by a database, an HTTP endpoint, or Convex (see `@jgengine/convex/convexSaveBackend`). Reads/writes may reject; the save store surfaces the failure as `"error"` status instead of throwing. */
 export declare function remoteSaveBackend(backend: SaveBackend): SaveBackend;
-/** Lifecycle of the last save/load — drive a "Saving…"/"Saved" indicator or a loading gate off it. `"error"` means the backend rejected a read or write. */
+/** Lifecycle of the last save/load — drive a "Saving…"/"Saved" indicator or a loading gate off it. `"error"` includes rejected reads, writes, removals and slot metadata updates; metadata failure can follow a successful payload write. */
 export type SaveStatus = "idle" | "loading" | "saving" | "saved" | "error";
 /** Autosave cadence: debounce writes `debounceMs` after the last edit, but never wait longer than `maxWaitMs` while edits keep coming (`0` removes the ceiling). `autosave: true` uses `{ debounceMs: 1000, maxWaitMs: 15000 }`. */
 export interface SaveAutoConfig {