@jgengine/core 0.19.0 → 0.21.0

package/dist/visibility/assetStreaming.js

@@ -1,14 +1,31 @@
 import { DEFAULT_STREAMING_SETTINGS, mergeStreamingSettings } from "./settings.js";
 import { nowMs } from "./diagnostics.js";
+/** Stream shared resources with bounded load concurrency, per-tick resident-byte eviction, and explicit inactive-history cleanup. */
 export function createAssetStreamingSystem(options) {
-    const settings = mergeStreamingSettings(DEFAULT_STREAMING_SETTINGS, options.settings ?? {});
+    function mergeSettings(base, patch) {
+        const next = mergeStreamingSettings(base, patch);
+        if (!Number.isSafeInteger(next.maxConcurrentLoads) || next.maxConcurrentLoads < 0) {
+            throw new RangeError("AssetStreamingSystem: maxConcurrentLoads must be a nonnegative safe integer");
+        }
+        if (next.maxResidentBytes !== Infinity && (!Number.isFinite(next.maxResidentBytes) || next.maxResidentBytes < 0)) {
+            throw new RangeError("AssetStreamingSystem: maxResidentBytes must be nonnegative and finite, or Infinity");
+        }
+        if (next.residentEvictionOrder !== "oldest" && next.residentEvictionOrder !== "largest") {
+            throw new RangeError("AssetStreamingSystem: residentEvictionOrder must be oldest or largest");
+        }
+        return next;
+    }
+    let settings = mergeSettings(DEFAULT_STREAMING_SETTINGS, options.settings ?? {});
     const clock = options.now ?? nowMs;
     const records = new Map();
     const queued = new Set();
+    const residents = new Set();
+    const unknownSizes = new Set();
     const signals = new Map();
     const inFlight = new Set();
     let unloadedTotal = 0;
     let cancelledTotal = 0;
+    let budgetEvictedTotal = 0;
     function ensure(id) {
         let record = records.get(id);
         if (record === undefined) {
@@ -31,29 +48,56 @@ export function createAssetStreamingSystem(options) {
         record.state = "loading";
         const signal = { cancelled: false };
         signals.set(record.id, signal);
-        const promise = options
-            .load(record.id, signal)
+        let loading;
+        try {
+            loading = options.load(record.id, signal);
+        }
+        catch (error) {
+            loading = Promise.reject(error);
+        }
+        const promise = loading
             .then((result) => {
-            signals.delete(record.id);
-            if (signal.cancelled || !records.has(record.id)) {
-                record.state = "unloaded";
+            if (signal.cancelled || records.get(record.id) !== record) {
+                options.unload?.(record.id);
                 return;
             }
             record.state = "loaded";
-            record.bytes = result.bytes ?? 0;
+            const knownSize = typeof result.bytes === "number" && Number.isFinite(result.bytes) && result.bytes >= 0;
+            record.bytes = knownSize ? result.bytes : 0;
+            if (!knownSize)
+                unknownSizes.add(record);
             record.value = result.value;
             record.lastActiveMs = clock();
+            residents.add(record);
         })
             .catch(() => {
-            signals.delete(record.id);
-            if (!signal.cancelled)
+            if (!signal.cancelled && records.get(record.id) === record)
                 record.state = "error";
         })
             .finally(() => {
+            if (signals.get(record.id) === signal)
+                signals.delete(record.id);
             inFlight.delete(promise);
         });
         inFlight.add(promise);
     }
+    function unprotected(record) {
+        return record.state === "loaded" && !record.pinned && record.refCount === 0;
+    }
+    function compareEviction(a, b) {
+        if (settings.residentEvictionOrder === "largest" && a.bytes !== b.bytes)
+            return b.bytes - a.bytes;
+        return a.lastActiveMs - b.lastActiveMs || (a.id < b.id ? -1 : a.id > b.id ? 1 : 0);
+    }
+    function unload(record) {
+        options.unload?.(record.id);
+        residents.delete(record);
+        unknownSizes.delete(record);
+        record.state = "unloaded";
+        record.bytes = 0;
+        record.value = undefined;
+        unloadedTotal += 1;
+    }
     function evictable(record, now) {
         if (record.state !== "loaded")
             return false;
@@ -92,29 +136,45 @@ export function createAssetStreamingSystem(options) {
         },
         tick() {
             const now = clock();
-            if (queued.size > 0) {
+            if (queued.size > 0 && signals.size < settings.maxConcurrentLoads) {
                 const pending = [];
                 for (const id of queued) {
                     const record = records.get(id);
-                    if (record !== undefined)
+                    if (record !== undefined && !signals.has(id))
                         pending.push(record);
                 }
                 pending.sort((a, b) => b.priority - a.priority);
-                const budget = Math.min(settings.maxLoadsPerFrame, pending.length);
-                for (let i = 0; i < budget; i += 1)
-                    startLoad(pending[i]);
+                const budget = Math.min(settings.maxLoadsPerFrame, settings.maxConcurrentLoads - signals.size, pending.length);
+                for (let i = 0; i < budget && signals.size < settings.maxConcurrentLoads; i += 1) {
+                    const record = pending[i];
+                    if (queued.has(record.id) && records.get(record.id) === record && !signals.has(record.id))
+                        startLoad(record);
+                }
             }
+            let bytes = 0;
+            for (const record of residents)
+                bytes += record.bytes;
             let unloads = 0;
-            for (const record of records.values()) {
+            while (bytes > settings.maxResidentBytes && unloads < settings.maxUnloadsPerFrame) {
+                let candidate;
+                for (const record of residents) {
+                    if (record.bytes > 0 && unprotected(record) && (candidate === undefined || compareEviction(record, candidate) < 0))
+                        candidate = record;
+                }
+                if (candidate === undefined)
+                    break;
+                const releasedBytes = candidate.bytes;
+                unload(candidate);
+                bytes -= releasedBytes;
+                budgetEvictedTotal += 1;
+                unloads += 1;
+            }
+            for (const record of residents) {
                 if (unloads >= settings.maxUnloadsPerFrame)
                     break;
                 if (!evictable(record, now))
                     continue;
-                options.unload?.(record.id);
-                record.state = "unloaded";
-                record.bytes = 0;
-                record.value = undefined;
-                unloadedTotal += 1;
+                unload(record);
                 unloads += 1;
             }
         },
@@ -127,7 +187,7 @@ export function createAssetStreamingSystem(options) {
                 return;
             }
             const signal = signals.get(assetId);
-            if (signal !== undefined) {
+            if (signal !== undefined && !signal.cancelled) {
                 signal.cancelled = true;
                 const record = records.get(assetId);
                 if (record !== undefined)
@@ -135,6 +195,9 @@ export function createAssetStreamingSystem(options) {
                 cancelledTotal += 1;
             }
         },
+        retune(patch) {
+            settings = mergeSettings(settings, patch);
+        },
         stateOf(assetId) {
             return records.get(assetId)?.state;
         },
@@ -144,8 +207,16 @@ export function createAssetStreamingSystem(options) {
         record(assetId) {
             return records.get(assetId);
         },
+        forget(assetId) {
+            const record = records.get(assetId);
+            if (record === undefined || record.pinned || record.refCount > 0 || signals.has(assetId) || queued.has(assetId))
+                return false;
+            if (record.state !== "unloaded" && record.state !== "error")
+                return false;
+            return records.delete(assetId);
+        },
         stats() {
-            let queuedCount = 0, loading = 0, loaded = 0, errored = 0, bytes = 0;
+            let queuedCount = 0, loading = 0, loaded = 0, errored = 0, bytes = 0, protectedBytes = 0, unknownSizeLoaded = 0;
             for (const record of records.values()) {
                 switch (record.state) {
                     case "queued":
@@ -157,6 +228,10 @@ export function createAssetStreamingSystem(options) {
                     case "loaded":
                         loaded += 1;
                         bytes += record.bytes;
+                        if (record.pinned || record.refCount > 0)
+                            protectedBytes += record.bytes;
+                        if (unknownSizes.has(record))
+                            unknownSizeLoaded += 1;
                         break;
                     case "error":
                         errored += 1;
@@ -172,6 +247,11 @@ export function createAssetStreamingSystem(options) {
                 inFlight: inFlight.size,
                 cancelled: cancelledTotal,
                 bytes,
+                records: records.size,
+                protectedBytes,
+                unknownSizeLoaded,
+                overBudgetBytes: Math.max(0, bytes - settings.maxResidentBytes),
+                budgetEvicted: budgetEvictedTotal,
             };
         },
         applyTo(stats) {
@@ -190,12 +270,16 @@ export function createAssetStreamingSystem(options) {
         clear() {
             for (const signal of signals.values())
                 signal.cancelled = true;
+            const loaded = [...records.values()].filter((record) => record.state === "loaded").map((record) => record.id);
             records.clear();
             queued.clear();
-            signals.clear();
-            inFlight.clear();
+            residents.clear();
+            unknownSizes.clear();
+            budgetEvictedTotal = 0;
             unloadedTotal = 0;
             cancelledTotal = 0;
+            for (const id of loaded)
+                options.unload?.(id);
         },
     };
 }

package/dist/visibility/settings.d.ts

@@ -23,11 +23,17 @@ export interface StreamingSettings {
     readonly enabled: boolean;
     /** Extra world units around the camera whose assets are preloaded ahead of visibility. */
     readonly preloadMargin: number;
-    /** Seconds an asset must stay outside the active area before it is eligible for unload. */
+    /** Idle unload delay; resident-byte pressure can evict unprotected assets sooner. */
     readonly unloadGraceSeconds: number;
     readonly maxLoadsPerFrame: number;
+    /** Maximum unresolved loads, including cancelled work until its loader settles. Zero pauses new loads. */
+    readonly maxConcurrentLoads: number;
     readonly maxUnloadsPerFrame: number;
-    /** Assets at or below this byte size are kept resident once loaded (small shared assets). */
+    /** Resident-byte target, enforced on ticks within maxUnloadsPerFrame; protected assets may exceed it. */
+    readonly maxResidentBytes: number;
+    /** Budget eviction order. Ties use oldest activity then asset id for deterministic selection. */
+    readonly residentEvictionOrder: "oldest" | "largest";
+    /** Small shared assets survive idle unloading, but remain eligible under resident-byte pressure. */
     readonly keepResidentBytes: number;
 }
 export declare const DEFAULT_STREAMING_SETTINGS: StreamingSettings;

package/dist/visibility/settings.js

@@ -13,8 +13,11 @@ export const DEFAULT_STREAMING_SETTINGS = {
     preloadMargin: 32,
     unloadGraceSeconds: 10,
     maxLoadsPerFrame: 4,
+    maxConcurrentLoads: 4,
     maxUnloadsPerFrame: 2,
     keepResidentBytes: 64 * 1024,
+    maxResidentBytes: Infinity,
+    residentEvictionOrder: "oldest",
 };
 const EMPTY = {};
 /** Merge override layers by precedence: earlier arguments win. Pass object, then layer, then scene, then global. */

package/dist/visibility/visibilitySystem.js

@@ -68,6 +68,7 @@ export function createVisibilitySystem(options) {
             index.remove(id);
             bounds.delete(id);
             records.delete(id);
+            consideredStamp.delete(id);
         }
         return alwaysVisibleList;
     }

package/dist/work/expedition.d.ts

@@ -0,0 +1,110 @@
+import type { LootPipeline, LootResolution } from "../game/lootPipeline.js";
+import type { Drop } from "../game/lootTable.js";
+import { type RandomSeed } from "../random/rng.js";
+/** Timestamped serializable event. `at` is epoch milliseconds, compatible with `appendFeed`. */
+export interface ExpeditionEvent {
+    at: number;
+    /** Lifecycle kinds are loot/hazard/supply/death/recall/return; encounter notices may use caller kinds. */
+    kind: string;
+    text: string;
+    /** Accepted drops; `loot.drops` records the full roll before the item-unit capacity bound. */
+    drops?: readonly Drop[];
+    loot?: LootResolution;
+    hpDelta?: number;
+    exposureDelta?: number;
+    supply?: string;
+}
+/** Plain saveable expedition data. Persist this whole value, including the RNG cursor and tick frontier. */
+export interface ExpeditionState {
+    readonly id: string;
+    readonly status: "exploring" | "returning" | "home" | "dead";
+    readonly startedAtMs: number;
+    /** Last completed event tick (arrival time after return), never an unprocessed catch-up target. */
+    readonly lastSettledMs: number;
+    readonly elapsedMs: number;
+    readonly returnUntilMs: number | null;
+    readonly hp: number;
+    /** Caller-interpreted hazard meter; its meaning and effective max-HP policy are injected. */
+    readonly exposure: number;
+    readonly supplies: Readonly<Record<string, number>>;
+    /** Counts are merged by item/currency id; currency does not consume item capacity. */
+    readonly carried: readonly Drop[];
+    readonly log: readonly ExpeditionEvent[];
+    readonly seed: string;
+    readonly cursor: RandomSeed;
+}
+/** Dispatch data, detached from the caller's supply record. All timestamps are epoch milliseconds. */
+export interface ExpeditionDispatch {
+    id: string;
+    startAtMs: number;
+    hp: number;
+    exposure?: number;
+    supplies?: Readonly<Record<string, number>>;
+    seed: string;
+}
+/** One encounter's mechanical effects and optional caller-authored notices. */
+export interface ExpeditionHazard {
+    damage?: number;
+    exposure?: number;
+    notices?: readonly {
+        kind: string;
+        text: string;
+    }[];
+}
+/** Ordered auto-consumption rule: spends one finite supply only when its declared effect changes a vital. */
+export interface ExpeditionSupplyRule {
+    key: string;
+    when: (state: ExpeditionState) => boolean;
+    restoreHp?: number;
+    clearExposure?: number;
+}
+/** Runtime policy, supplied on each transition and never saved. Callbacks must be pure. */
+export interface ExpeditionConfig<TCtx> {
+    /** Positive whole milliseconds between events; cadence retuning anchors at the last completed tick. */
+    tickMs: number;
+    loot: LootPipeline<TCtx>;
+    lootCtx: (state: ExpeditionState) => TCtx;
+    maxHp: (state: ExpeditionState) => number;
+    hazard?: (state: ExpeditionState, rng: () => number) => ExpeditionHazard;
+    supplies?: readonly ExpeditionSupplyRule[];
+    /** Nonnegative fraction of exploring elapsed time spent returning. */
+    returnFraction: number;
+    /** Positive whole item units; currency is carried without consuming item slots. */
+    carryCap: number;
+    /** Bounded work per call, default 10,000; excess ticks remain unsettled for the next call. */
+    maxTicksPerSettle?: number;
+    /** Newest event count retained by appendFeed, default 200; rewards and RNG are retained separately. */
+    logLimit?: number;
+    /** Optional alternative persisted RNG recurrence; returns a [0,1) value and its next cursor. */
+    randomStep?: (cursor: RandomSeed) => readonly [number, RandomSeed];
+    /** All lifecycle prose is caller-authored; omit for headless logs with empty text. */
+    describe?: (event: Omit<ExpeditionEvent, "text">, state: ExpeditionState) => string;
+}
+/**
+ * Dispatch plain expedition state with a persisted seeded cursor; no clock, scheduler or storage is owned.
+ *
+ * @capability expedition-dispatch dispatch a saveable timed away mission with finite supplies and a seeded RNG cursor
+ */
+export declare function dispatchExpedition(input: ExpeditionDispatch): ExpeditionState;
+/**
+ * Replay due event ticks using the existing stepped catch-up primitive. Order is loot → hazard → ordered
+ * supplies → death → capacity recall. Unprocessed ticks retain their frontier; returning never rolls or
+ * takes damage. Auto-recall uses the triggering tick's time, including offline arrival in the same call.
+ *
+ * @capability expedition-settle settle bounded offline expedition ticks without losing supplies rewards or RNG continuity
+ */
+export declare function settleExpedition<TCtx>(config: ExpeditionConfig<TCtx>, state: ExpeditionState, nowMs: number): ExpeditionState;
+/**
+ * Settle first, then recall safely. If the catch-up budget leaves due exploring ticks, return that state
+ * without recalling; repeat at the same target until the frontier catches up. Dead state never revives.
+ *
+ * @capability expedition-recall begin a safe fractional-time return after settling the pending expedition frontier
+ */
+export declare function recallExpedition<TCtx>(config: ExpeditionConfig<TCtx>, state: ExpeditionState, nowMs: number): ExpeditionState;
+/**
+ * Settle first, then complete a live return instantly. Caller owns payment/authorization; pending ticks
+ * remain unsettled when the budget is exhausted, and dead/home state is never changed.
+ *
+ * @capability expedition-return complete an authorized instant return without skipping unsettled ticks or reviving death
+ */
+export declare function returnExpeditionNow<TCtx>(config: ExpeditionConfig<TCtx>, state: ExpeditionState, nowMs: number): ExpeditionState;

package/dist/work/expedition.js

@@ -0,0 +1,195 @@
+import { appendFeed } from "../game/feed.js";
+import { hashString, randomSeedFrom, stepRandomSeed } from "../random/rng.js";
+import { accrueSince } from "../time/accrueSince.js";
+import { steppedCatchUp } from "../time/idleProgress.js";
+function nonnegative(value, name) {
+    if (!Number.isFinite(value) || value < 0)
+        throw new RangeError(`${name} must be finite and nonnegative`);
+    return value;
+}
+function positiveInteger(value, name) {
+    if (!Number.isSafeInteger(value) || value <= 0)
+        throw new RangeError(`${name} must be a positive safe integer`);
+    return value;
+}
+function validate(config, state, nowMs) {
+    if (!Number.isFinite(nowMs) || !Number.isFinite(state.startedAtMs) || !Number.isFinite(state.lastSettledMs))
+        throw new RangeError("Expedition timestamps must be finite");
+    if (state.lastSettledMs < state.startedAtMs || (state.returnUntilMs !== null && !Number.isFinite(state.returnUntilMs)))
+        throw new RangeError("Invalid expedition time frontier");
+    if (!Number.isSafeInteger(state.cursor))
+        throw new RangeError("Expedition RNG cursor must be a safe integer");
+    positiveInteger(config.tickMs, "tickMs");
+    positiveInteger(config.carryCap, "carryCap");
+    positiveInteger(config.maxTicksPerSettle ?? 10_000, "maxTicksPerSettle");
+    positiveInteger(config.logLimit ?? 200, "logLimit");
+    nonnegative(config.returnFraction, "returnFraction");
+    nonnegative(state.hp, "hp");
+    nonnegative(state.exposure, "exposure");
+    nonnegative(state.elapsedMs, "elapsedMs");
+    for (const count of Object.values(state.supplies))
+        if (!Number.isSafeInteger(count) || count < 0)
+            throw new RangeError("Supply counts must be nonnegative safe integers");
+}
+function record(config, state, event, text) {
+    return { ...state, log: appendFeed(state.log, { ...event, text: text ?? config.describe?.(event, state) ?? "" }, { limit: config.logLimit ?? 200 }) };
+}
+function itemUnits(drops) {
+    let units = 0;
+    for (const drop of drops)
+        if (drop.item !== undefined)
+            units += nonnegative(drop.count, "Item count");
+    return nonnegative(units, "Carried item units");
+}
+function acceptLoot(cap, carried, drops) {
+    let remaining = Math.max(0, cap - itemUnits(carried));
+    const next = carried.map(drop => ({ ...drop }));
+    const accepted = [];
+    for (const drop of drops) {
+        const count = nonnegative(drop.count, "Drop count");
+        if ((drop.item === undefined) === (drop.currency === undefined))
+            throw new RangeError("Expedition drops need exactly one item or currency id");
+        if (drop.item !== undefined && !Number.isSafeInteger(count))
+            throw new RangeError("Item counts must be nonnegative safe integers");
+        const admitted = drop.item === undefined ? count : Math.min(count, remaining);
+        if (drop.item !== undefined)
+            remaining -= admitted;
+        if (admitted === 0)
+            continue;
+        const incoming = { ...drop, count: admitted };
+        accepted.push(incoming);
+        const existing = next.find(entry => drop.item !== undefined ? entry.item === drop.item : entry.currency === drop.currency && entry.item === undefined);
+        if (existing === undefined)
+            next.push({ ...incoming });
+        else
+            existing.count = nonnegative(existing.count + admitted, "Carried count");
+    }
+    return { carried: next, accepted };
+}
+function arrive(config, state, nowMs) {
+    if (state.status !== "returning" || state.returnUntilMs === null || nowMs < state.returnUntilMs)
+        return state;
+    const at = state.returnUntilMs;
+    return record(config, { ...state, status: "home", lastSettledMs: at }, { at, kind: "return" });
+}
+function beginReturn(config, state, at) {
+    const elapsedMs = Math.max(state.elapsedMs, at - state.startedAtMs);
+    const returnUntilMs = at + elapsedMs * config.returnFraction;
+    if (!Number.isFinite(returnUntilMs))
+        throw new RangeError("Expedition return deadline overflowed");
+    return arrive(config, record(config, { ...state, status: "returning", elapsedMs, returnUntilMs, lastSettledMs: at }, { at, kind: "recall" }), at);
+}
+/**
+ * Dispatch plain expedition state with a persisted seeded cursor; no clock, scheduler or storage is owned.
+ *
+ * @capability expedition-dispatch dispatch a saveable timed away mission with finite supplies and a seeded RNG cursor
+ */
+export function dispatchExpedition(input) {
+    if (!Number.isFinite(input.startAtMs))
+        throw new RangeError("startAtMs must be finite");
+    nonnegative(input.hp, "hp");
+    nonnegative(input.exposure ?? 0, "exposure");
+    const supplies = { ...input.supplies };
+    for (const count of Object.values(supplies))
+        if (!Number.isSafeInteger(count) || count < 0)
+            throw new RangeError("Supply counts must be nonnegative safe integers");
+    return { id: input.id, status: input.hp === 0 ? "dead" : "exploring", startedAtMs: input.startAtMs, lastSettledMs: input.startAtMs,
+        elapsedMs: 0, returnUntilMs: null, hp: input.hp, exposure: input.exposure ?? 0, supplies, carried: [], log: [], seed: input.seed, cursor: randomSeedFrom(hashString(input.seed)) };
+}
+/**
+ * Replay due event ticks using the existing stepped catch-up primitive. Order is loot → hazard → ordered
+ * supplies → death → capacity recall. Unprocessed ticks retain their frontier; returning never rolls or
+ * takes damage. Auto-recall uses the triggering tick's time, including offline arrival in the same call.
+ *
+ * @capability expedition-settle settle bounded offline expedition ticks without losing supplies rewards or RNG continuity
+ */
+export function settleExpedition(config, state, nowMs) {
+    validate(config, state, nowMs);
+    if (nowMs < state.lastSettledMs || (state.status === "exploring" && nowMs < state.startedAtMs + state.elapsedMs) || state.status === "dead" || state.status === "home")
+        return state;
+    if (state.status === "returning")
+        return arrive(config, state, nowMs);
+    let next = state;
+    const step = config.randomStep ?? stepRandomSeed;
+    const window = accrueSince(state.lastSettledMs, nowMs);
+    nonnegative(window.elapsedMs, "Catch-up duration");
+    // Normalize to whole one-unit ticks so fractional-second division cannot lose a due millisecond.
+    const ticks = Math.floor(window.elapsedMs / config.tickMs);
+    steppedCatchUp(ticks, 1, () => {
+        if (next.status !== "exploring")
+            return;
+        const at = next.lastSettledMs + config.tickMs;
+        next = { ...next, lastSettledMs: at, elapsedMs: at - next.startedAtMs };
+        let cursor = next.cursor;
+        const rng = () => {
+            const [value, following] = step(cursor);
+            if (!Number.isFinite(value) || value < 0 || value >= 1 || !Number.isSafeInteger(following))
+                throw new RangeError("Expedition RNG must return a [0,1) value and safe integer cursor");
+            cursor = following;
+            return value;
+        };
+        const resolution = config.loot.resolve({ ctx: config.lootCtx(next), rng, seed: next.seed });
+        const accepted = acceptLoot(config.carryCap, next.carried, resolution.drops);
+        next = { ...next, carried: accepted.carried };
+        if (resolution.drops.length > 0)
+            next = record(config, next, { at, kind: "loot", drops: accepted.accepted, loot: resolution });
+        const hazard = config.hazard?.(next, rng) ?? {};
+        const exposure = nonnegative(next.exposure + nonnegative(hazard.exposure ?? 0, "Hazard exposure"), "Exposure");
+        const hp = Math.min(nonnegative(config.maxHp({ ...next, exposure }), "maxHp"), Math.max(0, next.hp - nonnegative(hazard.damage ?? 0, "Hazard damage")));
+        const hpDelta = hp - next.hp, exposureDelta = exposure - next.exposure;
+        next = { ...next, hp, exposure };
+        if (hpDelta !== 0 || exposureDelta !== 0)
+            next = record(config, next, { at, kind: "hazard", hpDelta, exposureDelta });
+        for (const notice of hazard.notices ?? [])
+            next = record(config, next, { at, kind: notice.kind }, notice.text);
+        for (const rule of config.supplies ?? []) {
+            const count = Object.hasOwn(next.supplies, rule.key) ? next.supplies[rule.key] : 0;
+            const restoreHp = nonnegative(rule.restoreHp ?? 0, "Supply restoration"), clearExposure = nonnegative(rule.clearExposure ?? 0, "Supply cleansing");
+            if (count <= 0 || !rule.when(next))
+                continue;
+            const exposure = Math.max(0, next.exposure - clearExposure);
+            const hp = Math.min(nonnegative(config.maxHp({ ...next, exposure }), "maxHp"), nonnegative(next.hp + restoreHp, "Restored hp"));
+            if (hp === next.hp && exposure === next.exposure)
+                continue;
+            const hpDelta = hp - next.hp, exposureDelta = exposure - next.exposure;
+            next = { ...next, hp, exposure, supplies: { ...next.supplies, [rule.key]: count - 1 } };
+            next = record(config, next, { at, kind: "supply", supply: rule.key, hpDelta, exposureDelta });
+        }
+        next = { ...next, cursor };
+        if (next.hp <= 0)
+            next = record(config, { ...next, status: "dead" }, { at, kind: "death" });
+        else if (itemUnits(next.carried) >= config.carryCap)
+            next = beginReturn(config, next, at);
+    }, config.maxTicksPerSettle ?? 10_000);
+    if (next.status === "exploring" && nowMs - next.lastSettledMs < config.tickMs) {
+        const elapsedMs = Math.max(next.elapsedMs, nowMs - next.startedAtMs);
+        nonnegative(elapsedMs, "Exploring duration");
+        if (elapsedMs !== next.elapsedMs)
+            next = { ...next, elapsedMs };
+        if (itemUnits(next.carried) >= config.carryCap)
+            next = beginReturn(config, next, nowMs);
+    }
+    return arrive(config, next, nowMs);
+}
+/**
+ * Settle first, then recall safely. If the catch-up budget leaves due exploring ticks, return that state
+ * without recalling; repeat at the same target until the frontier catches up. Dead state never revives.
+ *
+ * @capability expedition-recall begin a safe fractional-time return after settling the pending expedition frontier
+ */
+export function recallExpedition(config, state, nowMs) {
+    const next = settleExpedition(config, state, nowMs);
+    return next.status === "exploring" && nowMs >= next.startedAtMs + next.elapsedMs && nowMs >= next.lastSettledMs && nowMs - next.lastSettledMs < config.tickMs ? beginReturn(config, next, nowMs) : next;
+}
+/**
+ * Settle first, then complete a live return instantly. Caller owns payment/authorization; pending ticks
+ * remain unsettled when the budget is exhausted, and dead/home state is never changed.
+ *
+ * @capability expedition-return complete an authorized instant return without skipping unsettled ticks or reviving death
+ */
+export function returnExpeditionNow(config, state, nowMs) {
+    const next = settleExpedition(config, state, nowMs);
+    if (next.status === "dead" || next.status === "home" || nowMs < next.lastSettledMs || (next.status === "exploring" && nowMs < next.startedAtMs + next.elapsedMs) || (next.status === "exploring" && nowMs - next.lastSettledMs >= config.tickMs))
+        return next;
+    return record(config, { ...next, status: "home", returnUntilMs: nowMs, lastSettledMs: nowMs }, { at: nowMs, kind: "return" });
+}

package/dist/work/staffedStation.d.ts

@@ -0,0 +1,29 @@
+/** One assigned worker's caller-resolved contribution; stat names and modifiers stay caller-owned. */
+export interface StationWorker {
+    readonly id: string;
+    readonly stat: number;
+}
+/** Serializable staffing snapshot. The caller owns assignment, unique worker ids, and stable order. */
+export interface StaffedStation {
+    readonly stationId: string;
+    /** Nonnegative whole slot count; fractional values round down and nonfinite values admit no workers. */
+    readonly slots: number;
+    /** Only the first `slots` entries contribute; overflow assignments are not reordered or mutated. */
+    readonly workers: readonly StationWorker[];
+}
+/** Caller-owned output tuning in production cycles per game-second. */
+export interface StationRateTuning {
+    readonly base: number;
+    readonly perStat: number;
+    /** Applied to the whole rate, including base; defaults to 1 and clamps to 0…1. */
+    readonly efficiency?: number;
+}
+/**
+ * Resolve `(base + perStat * sum(admitted worker stats)) * efficiency` without allocation.
+ * Empty staffing retains base production. Negative/nonfinite contributions are zero; a nonfinite
+ * efficiency or overflowing result stops production with rate zero. Invalid workers still occupy
+ * their ordered slots. Assign the result to a `ProductionBuildingDef.rate` for `tickProduction`.
+ *
+ * @capability staffed-station-rate turn bounded caller-owned worker stats and efficiency into a production rate
+ */
+export declare function stationOutputRate(station: StaffedStation, tuning: StationRateTuning): number;

package/dist/work/staffedStation.js

@@ -0,0 +1,27 @@
+function contribution(value) {
+    return Number.isFinite(value) && value > 0 ? value : 0;
+}
+/**
+ * Resolve `(base + perStat * sum(admitted worker stats)) * efficiency` without allocation.
+ * Empty staffing retains base production. Negative/nonfinite contributions are zero; a nonfinite
+ * efficiency or overflowing result stops production with rate zero. Invalid workers still occupy
+ * their ordered slots. Assign the result to a `ProductionBuildingDef.rate` for `tickProduction`.
+ *
+ * @capability staffed-station-rate turn bounded caller-owned worker stats and efficiency into a production rate
+ */
+export function stationOutputRate(station, tuning) {
+    const efficiency = Math.min(1, contribution(tuning.efficiency ?? 1));
+    if (efficiency === 0)
+        return 0;
+    const base = contribution(tuning.base);
+    const perStat = contribution(tuning.perStat);
+    if (perStat === 0)
+        return base * efficiency;
+    const slots = Number.isFinite(station.slots) ? Math.max(0, Math.floor(station.slots)) : 0;
+    const count = Math.min(slots, station.workers.length);
+    let total = 0;
+    for (let index = 0; index < count; index += 1)
+        total += contribution(station.workers[index].stat);
+    const rate = (base + perStat * total) * efficiency;
+    return Number.isFinite(rate) ? rate : 0;
+}