@futdevpro/fsm-dynamo 1.20.97 → 1.20.99

package/build/_modules/game/_models/work-order-scheduler.control-model.js

@@ -0,0 +1,201 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DyFM_WorkOrderScheduler_ControlModel = void 0;
+const error_control_model_1 = require("../../../_models/control-models/error.control-model");
+/**
+ * BFR-WARFACTORY-012 — headless, cancel-safe scheduler of interchangeable workers over parallel work orders.
+ *
+ * Guarantees (each pinned by a spec):
+ * - **Release is structural, not a happy-path step:** an assignment exists only as `worker → order`; cancelling an
+ *   order, completing it or removing (destroying) a worker deletes the entry in the same call ⇒ no stranded worker.
+ * - **Every pending order gets ≥ 1 worker when possible:** idle workers first; if none is idle, one is moved from the
+ *   order that has the most (only from an order with > 1) — so one plan cannot starve the others ("frozen" plans).
+ * - **Stable least-assigned distribution:** extra workers go to the order with the fewest (tie → the earliest order);
+ *   existing assignments are not reshuffled.
+ * - **Self-healing import:** stale ownership (unknown worker / order, duplicates) is dropped and REPORTED; importing
+ *   the same state twice gives the same result.
+ * No clock, no RNG: time comes in through `advance(simulationSeconds)` (e.g. from `DyFM_SimulationClock_ControlModel`).
+ */
+class DyFM_WorkOrderScheduler_ControlModel {
+    rate;
+    orders = [];
+    workerIds = [];
+    /** workerId → orderId (the ONLY ownership record). */
+    assignments = new Map();
+    /** Creates the scheduler; an invalid rate throws `DYFM-WORK-ORDER-CONFIG`. */
+    constructor(config = {}) {
+        const rate = config.workPerWorkerPerSecond ?? 1;
+        if (!Number.isFinite(rate) || rate <= 0) {
+            throw DyFM_WorkOrderScheduler_ControlModel.error('DYFM-WORK-ORDER-CONFIG', `workPerWorkerPerSecond must be > 0 (${rate})`);
+        }
+        this.rate = rate;
+    }
+    /** Adds a work order at the end of the FIFO; a duplicate id or non-positive work throws `DYFM-WORK-ORDER-INVALID`. */
+    addOrder(order) {
+        if (!order?.orderId || this.orders.some((o) => o.orderId === order.orderId)
+            || !Number.isFinite(order.work) || order.work <= 0) {
+            throw DyFM_WorkOrderScheduler_ControlModel.error('DYFM-WORK-ORDER-INVALID', `order needs a unique orderId and work > 0 (${order?.orderId})`);
+        }
+        this.orders.push({ orderId: order.orderId, work: order.work, progress: Math.max(0, order.progress ?? 0) });
+        this.rebalance();
+    }
+    /** Adds an (idle) worker; duplicates are ignored. */
+    addWorker(workerId) {
+        if (workerId && !this.workerIds.includes(workerId)) {
+            this.workerIds.push(workerId);
+            this.rebalance();
+        }
+    }
+    /** Removes (destroys) a worker; its assignment goes with it. Idempotent. */
+    removeWorker(workerId) {
+        this.workerIds = this.workerIds.filter((id) => id !== workerId);
+        this.assignments.delete(workerId);
+        this.rebalance();
+    }
+    /** Cancels an order: removes it and releases its workers in the same call. Idempotent (unknown → found: false). */
+    cancel(orderId) {
+        const order = this.orders.find((o) => o.orderId === orderId);
+        if (!order) {
+            return { found: false, releasedWorkerIds: [], progressRatio: 0 };
+        }
+        const released = this.workersOf(orderId);
+        this.orders = this.orders.filter((o) => o.orderId !== orderId);
+        released.forEach((workerId) => this.assignments.delete(workerId));
+        this.rebalance();
+        return { found: true, releasedWorkerIds: released, progressRatio: Math.min(1, order.progress / order.work) };
+    }
+    /** Advances every order by its workers × rate × seconds; completed orders leave and free their workers. */
+    advance(simulationSeconds) {
+        if (!Number.isFinite(simulationSeconds) || simulationSeconds <= 0) {
+            return { completedOrderIds: [] };
+        }
+        const completed = [];
+        for (const order of this.orders) {
+            order.progress += this.workersOf(order.orderId).length * this.rate * simulationSeconds;
+            if (order.progress >= order.work) {
+                completed.push(order.orderId);
+            }
+        }
+        if (completed.length) {
+            this.orders = this.orders.filter((o) => !completed.includes(o.orderId));
+            for (const [workerId, orderId] of [...this.assignments]) {
+                if (completed.includes(orderId)) {
+                    this.assignments.delete(workerId);
+                }
+            }
+            this.rebalance();
+        }
+        return { completedOrderIds: completed };
+    }
+    /** The workers of an order, in assignment order. */
+    workersOf(orderId) {
+        return [...this.assignments].filter(([, id]) => id === orderId)
+            .map(([workerId]) => workerId);
+    }
+    /** The order a worker is on (`undefined` = idle). */
+    orderOf(workerId) {
+        return this.assignments.get(workerId);
+    }
+    /** Current orders (copies, FIFO). */
+    getOrders() {
+        return this.orders.map((o) => ({ ...o }));
+    }
+    /** The save/load snapshot. */
+    exportState() {
+        return {
+            schemaVersion: 1,
+            orders: this.getOrders(),
+            workerIds: [...this.workerIds],
+            assignments: Object.fromEntries(this.assignments),
+        };
+    }
+    /**
+     * Restores a snapshot and HEALS stale ownership (assignments to unknown workers / orders, duplicates): dropped and
+     * reported, then the distribution rules re-apply. An unreadable snapshot throws `DYFM-WORK-ORDER-STATE`.
+     */
+    importState(state) {
+        if (!state || state.schemaVersion !== 1 || !Array.isArray(state.orders) || !Array.isArray(state.workerIds)
+            || !state.assignments || typeof state.assignments !== 'object') {
+            throw DyFM_WorkOrderScheduler_ControlModel.error('DYFM-WORK-ORDER-STATE', 'unreadable scheduler snapshot');
+        }
+        const report = { droppedUnknownWorkers: [], droppedUnknownOrders: [], skippedDuplicates: [] };
+        const orders = [];
+        for (const order of state.orders) {
+            if (!order?.orderId || orders.some((o) => o.orderId === order.orderId)
+                || !Number.isFinite(order.work) || order.work <= 0) {
+                report.skippedDuplicates.push(String(order?.orderId));
+                continue;
+            }
+            if (Number(order.progress) >= order.work) {
+                continue; // a completed order is not "active" — its assignments heal below
+            }
+            orders.push({ orderId: order.orderId, work: order.work, progress: Math.max(0, Number(order.progress) || 0) });
+        }
+        const workerIds = [];
+        for (const workerId of state.workerIds) {
+            if (!workerId || workerIds.includes(workerId)) {
+                report.skippedDuplicates.push(String(workerId));
+                continue;
+            }
+            workerIds.push(workerId);
+        }
+        const assignments = new Map();
+        for (const [workerId, orderId] of Object.entries(state.assignments)) {
+            if (!workerIds.includes(workerId)) {
+                report.droppedUnknownWorkers.push(workerId);
+            }
+            else if (!orders.some((o) => o.orderId === orderId)) {
+                report.droppedUnknownOrders.push(`${workerId}→${orderId}`);
+            }
+            else {
+                assignments.set(workerId, orderId);
+            }
+        }
+        this.orders = orders;
+        this.workerIds = workerIds;
+        this.assignments = assignments;
+        this.rebalance();
+        return report;
+    }
+    /** Applies the distribution rules (stable: existing valid assignments are kept). */
+    rebalance() {
+        const count = (orderId) => this.workersOf(orderId).length;
+        const idle = () => this.workerIds.filter((id) => !this.assignments.has(id));
+        // 1) every order without a worker gets one: an idle worker, else one moved from the richest order (> 1)
+        for (const order of this.orders) {
+            if (count(order.orderId) > 0) {
+                continue;
+            }
+            const free = idle()[0];
+            if (free) {
+                this.assignments.set(free, order.orderId);
+                continue;
+            }
+            const donor = [...this.orders]
+                .filter((o) => count(o.orderId) > 1)
+                .sort((a, b) => count(b.orderId) - count(a.orderId) || this.orders.indexOf(b) - this.orders.indexOf(a))[0];
+            if (donor) {
+                const moved = this.workersOf(donor.orderId).slice(-1)[0];
+                this.assignments.set(moved, order.orderId);
+            }
+        }
+        // 2) the remaining idle workers go to the least-assigned order (tie → the earliest)
+        for (const workerId of idle()) {
+            const target = [...this.orders]
+                .sort((a, b) => count(a.orderId) - count(b.orderId) || this.orders.indexOf(a) - this.orders.indexOf(b))[0];
+            if (!target) {
+                return;
+            }
+            this.assignments.set(workerId, target.orderId);
+        }
+    }
+    static error(code, message) {
+        return new error_control_model_1.DyFM_Error({
+            message: `DyFM_WorkOrderScheduler: ${message}`,
+            errorCode: code,
+            issuerService: 'DyFM_WorkOrderScheduler_ControlModel',
+        });
+    }
+}
+exports.DyFM_WorkOrderScheduler_ControlModel = DyFM_WorkOrderScheduler_ControlModel;
+//# sourceMappingURL=work-order-scheduler.control-model.js.map

package/build/_modules/game/_models/work-order-scheduler.control-model.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-order-scheduler.control-model.js","sourceRoot":"","sources":["../../../../src/_modules/game/_models/work-order-scheduler.control-model.ts"],"names":[],"mappings":"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"}

package/build/_modules/game/_models/work-order-scheduler.interface.d.ts

@@ -0,0 +1,43 @@
+/** BFR-WARFACTORY-012 — `DyFM_WorkOrderScheduler_ControlModel` configuration. */
+export interface DyFM_WorkOrderScheduler_Config {
+    /** Work units one worker does per simulation second. Default: `1`. */
+    workPerWorkerPerSecond?: number;
+}
+/** One work order (FIFO priority = insertion order). */
+export interface DyFM_WorkOrder_State {
+    orderId: string;
+    /** Total work units needed. */
+    work: number;
+    /** Work units done so far. */
+    progress: number;
+}
+/** The save/load snapshot (versioned). */
+export interface DyFM_WorkOrderScheduler_State {
+    schemaVersion: 1;
+    orders: DyFM_WorkOrder_State[];
+    workerIds: string[];
+    /** workerId → orderId. On import, stale entries are healed (dropped), never trusted. */
+    assignments: Record<string, string>;
+}
+/** What `importState` repaired — stale ownership is reported, not silently dropped. */
+export interface DyFM_WorkOrderScheduler_HealReport {
+    /** Assignments whose worker no longer exists. */
+    droppedUnknownWorkers: string[];
+    /** Assignments pointing at an order that no longer exists (or is complete). */
+    droppedUnknownOrders: string[];
+    /** Duplicate / invalid order or worker entries skipped. */
+    skippedDuplicates: string[];
+}
+/** What an `advance` completed. */
+export interface DyFM_WorkOrderScheduler_AdvanceResult {
+    /** Orders that reached their work this step (in FIFO order). Their workers were released. */
+    completedOrderIds: string[];
+}
+/** What a `cancel` released — atomically, with the progress so the game can refund proportionally. */
+export interface DyFM_WorkOrderScheduler_CancelResult {
+    found: boolean;
+    releasedWorkerIds: string[];
+    /** Progress ratio at cancel time (0..1) — e.g. the base of a refund percentage. */
+    progressRatio: number;
+}
+//# sourceMappingURL=work-order-scheduler.interface.d.ts.map

package/build/_modules/game/_models/work-order-scheduler.interface.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-order-scheduler.interface.d.ts","sourceRoot":"","sources":["../../../../src/_modules/game/_models/work-order-scheduler.interface.ts"],"names":[],"mappings":"AAAA,iFAAiF;AACjF,MAAM,WAAW,8BAA8B;IAC7C,sEAAsE;IACtE,sBAAsB,CAAC,EAAE,MAAM,CAAC;CACjC;AAED,wDAAwD;AACxD,MAAM,WAAW,oBAAoB;IACnC,OAAO,EAAE,MAAM,CAAC;IAChB,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,8BAA8B;IAC9B,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,0CAA0C;AAC1C,MAAM,WAAW,6BAA6B;IAC5C,aAAa,EAAE,CAAC,CAAC;IACjB,MAAM,EAAE,oBAAoB,EAAE,CAAC;IAC/B,SAAS,EAAE,MAAM,EAAE,CAAC;IACpB,wFAAwF;IACxF,WAAW,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CACrC;AAED,uFAAuF;AACvF,MAAM,WAAW,kCAAkC;IACjD,iDAAiD;IACjD,qBAAqB,EAAE,MAAM,EAAE,CAAC;IAChC,+EAA+E;IAC/E,oBAAoB,EAAE,MAAM,EAAE,CAAC;IAC/B,2DAA2D;IAC3D,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,mCAAmC;AACnC,MAAM,WAAW,qCAAqC;IACpD,6FAA6F;IAC7F,iBAAiB,EAAE,MAAM,EAAE,CAAC;CAC7B;AAED,sGAAsG;AACtG,MAAM,WAAW,oCAAoC;IACnD,KAAK,EAAE,OAAO,CAAC;IACf,iBAAiB,EAAE,MAAM,EAAE,CAAC;IAC5B,mFAAmF;IACnF,aAAa,EAAE,MAAM,CAAC;CACvB"}

package/build/_modules/game/_models/work-order-scheduler.interface.js

@@ -0,0 +1,3 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+//# sourceMappingURL=work-order-scheduler.interface.js.map

package/build/_modules/game/_models/work-order-scheduler.interface.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"work-order-scheduler.interface.js","sourceRoot":"","sources":["../../../../src/_modules/game/_models/work-order-scheduler.interface.ts"],"names":[],"mappings":""}

package/build/_modules/game/index.d.ts

@@ -12,6 +12,12 @@ export * from './_models/flying-effect.interface';
 export * from './_models/flying-effect.control-model';
 export * from './_models/simulation-clock.interface';
 export * from './_models/simulation-clock.control-model';
+export * from './_models/game-save.interface';
+export * from './_models/work-order-scheduler.interface';
+export * from './_models/work-order-scheduler.control-model';
+export * from './_models/build-reservation.interface';
 export * from './_collections/audio-mixer.util';
 export * from './_collections/audio-scale.util';
+export * from './_collections/game-save.util';
+export * from './_collections/build-reservation.util';
 //# sourceMappingURL=index.d.ts.map

package/build/_modules/game/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":"AACA,cAAc,6BAA6B,CAAC;AAG5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AAGzD,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":"AACA,cAAc,6BAA6B,CAAC;AAG5C,cAAc,wCAAwC,CAAC;AACvD,cAAc,0CAA0C,CAAC;AACzD,cAAc,uCAAuC,CAAC;AACtD,cAAc,qCAAqC,CAAC;AACpD,cAAc,iCAAiC,CAAC;AAChD,cAAc,yCAAyC,CAAC;AACxD,cAAc,uCAAuC,CAAC;AACtD,cAAc,4CAA4C,CAAC;AAC3D,cAAc,gDAAgD,CAAC;AAC/D,cAAc,mCAAmC,CAAC;AAClD,cAAc,uCAAuC,CAAC;AACtD,cAAc,sCAAsC,CAAC;AACrD,cAAc,0CAA0C,CAAC;AACzD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,0CAA0C,CAAC;AACzD,cAAc,8CAA8C,CAAC;AAC7D,cAAc,uCAAuC,CAAC;AAGtD,cAAc,iCAAiC,CAAC;AAChD,cAAc,iCAAiC,CAAC;AAChD,cAAc,+BAA+B,CAAC;AAC9C,cAAc,uCAAuC,CAAC"}

package/build/_modules/game/index.js

@@ -17,7 +17,13 @@ tslib_1.__exportStar(require("./_models/flying-effect.interface"), exports);
 tslib_1.__exportStar(require("./_models/flying-effect.control-model"), exports);
 tslib_1.__exportStar(require("./_models/simulation-clock.interface"), exports);
 tslib_1.__exportStar(require("./_models/simulation-clock.control-model"), exports);
+tslib_1.__exportStar(require("./_models/game-save.interface"), exports);
+tslib_1.__exportStar(require("./_models/work-order-scheduler.interface"), exports);
+tslib_1.__exportStar(require("./_models/work-order-scheduler.control-model"), exports);
+tslib_1.__exportStar(require("./_models/build-reservation.interface"), exports);
 // COLLECTIONS
 tslib_1.__exportStar(require("./_collections/audio-mixer.util"), exports);
 tslib_1.__exportStar(require("./_collections/audio-scale.util"), exports);
+tslib_1.__exportStar(require("./_collections/game-save.util"), exports);
+tslib_1.__exportStar(require("./_collections/build-reservation.util"), exports);
 //# sourceMappingURL=index.js.map

package/build/_modules/game/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":";;;AAAA,QAAQ;AACR,sEAA4C;AAE5C,SAAS;AACT,iFAAuD;AACvD,mFAAyD;AACzD,gFAAsD;AACtD,8EAAoD;AACpD,0EAAgD;AAChD,kFAAwD;AACxD,gFAAsD;AACtD,qFAA2D;AAC3D,yFAA+D;AAC/D,4EAAkD;AAClD,gFAAsD;AACtD,+EAAqD;AACrD,mFAAyD;AAEzD,cAAc;AACd,0EAAgD;AAChD,0EAAgD"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../../src/_modules/game/index.ts"],"names":[],"mappings":";;;AAAA,QAAQ;AACR,sEAA4C;AAE5C,SAAS;AACT,iFAAuD;AACvD,mFAAyD;AACzD,gFAAsD;AACtD,8EAAoD;AACpD,0EAAgD;AAChD,kFAAwD;AACxD,gFAAsD;AACtD,qFAA2D;AAC3D,yFAA+D;AAC/D,4EAAkD;AAClD,gFAAsD;AACtD,+EAAqD;AACrD,mFAAyD;AACzD,wEAA8C;AAC9C,mFAAyD;AACzD,uFAA6D;AAC7D,gFAAsD;AAEtD,cAAc;AACd,0EAAgD;AAChD,0EAAgD;AAChD,wEAA8C;AAC9C,gFAAsD"}

package/build-esm/_modules/game/_collections/build-reservation.util.js

@@ -0,0 +1,72 @@
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+/**
+ * BFR-WARFACTORY-012 (①–②) — placement preview and escrow reservation, headless and pure (the caller owns the world
+ * state and applies the returned refund lines).
+ */
+export class DyFM_BuildReservation_Util {
+    /** ① Evaluates EVERY rule and returns the preview with all failure reasons (not just the first). */
+    static preview(candidate, rules) {
+        const reasons = [];
+        if (!(candidate.footprint?.width > 0) || !(candidate.footprint?.height > 0)) {
+            reasons.push({ code: 'invalid-footprint', message: 'the footprint must be at least 1 × 1' });
+        }
+        for (const rule of rules) {
+            const reason = rule(candidate);
+            if (reason) {
+                reasons.push(reason);
+            }
+        }
+        return { position: candidate.position, footprint: { ...candidate.footprint }, valid: !reasons.length, reasons: reasons };
+    }
+    /**
+     * ② Holds the cost in escrow for a VALID preview. An invalid preview or a non-positive amount throws
+     * (`DYFM-RESERVATION-INVALID`) — reserving an invalid placement is how resources silently disappear.
+     */
+    static reserve(reservationId, preview, sources, policy = {}) {
+        const ratio = policy.cancelRefundRatio ?? 1;
+        if (!reservationId || !preview.valid
+            || sources.some((s) => !s.resource || !s.sourceId || !(s.amount > 0))
+            || !(ratio >= 0 && ratio <= 1)) {
+            throw new DyFM_Error({
+                message: 'DyFM_BuildReservation: reserve needs an id, a VALID preview, sources with resource + sourceId + '
+                    + `amount > 0 and a refund ratio in 0..1 (reasons: ${preview.reasons.map((r) => r.code).join(', ') || '-'})`,
+                errorCode: 'DYFM-RESERVATION-INVALID',
+                issuerService: 'DyFM_BuildReservation_Util',
+            });
+        }
+        return {
+            reservationId: reservationId,
+            position: preview.position,
+            footprint: { ...preview.footprint },
+            reservedCostSources: sources.map((s) => ({ ...s })),
+            refundPolicy: { cancelRefundRatio: ratio },
+            status: 'held',
+        };
+    }
+    /** ② The build started / finished: the escrow is consumed. Idempotent on `committed`; a released one cannot commit. */
+    static commit(reservation) {
+        if (reservation.status === 'released') {
+            throw new DyFM_Error({
+                message: `DyFM_BuildReservation: ${reservation.reservationId} was already released — it cannot be committed`,
+                errorCode: 'DYFM-RESERVATION-STATE',
+                issuerService: 'DyFM_BuildReservation_Util',
+            });
+        }
+        return { ...reservation, status: 'committed' };
+    }
+    /**
+     * ② Cancel: returns the refund lines BACK TO THEIR ORIGINAL SOURCES — `cancelRefundRatio × (1 − progressRatio)`
+     * of each line (floored to whole units). A second release returns nothing (no double refund).
+     */
+    static release(reservation, progressRatio = 0) {
+        if (reservation.status === 'released') {
+            return { reservation: reservation, refunds: [] };
+        }
+        const progress = Math.min(1, Math.max(0, Number.isFinite(progressRatio) ? progressRatio : 0));
+        const share = reservation.refundPolicy.cancelRefundRatio * (1 - progress);
+        const refunds = reservation.reservedCostSources
+            .map((s) => ({ resource: s.resource, sourceId: s.sourceId, amount: Math.floor(s.amount * share + 1e-9) }))
+            .filter((line) => line.amount > 0);
+        return { reservation: { ...reservation, status: 'released' }, refunds: refunds };
+    }
+}

package/build-esm/_modules/game/_collections/game-save.util.js

@@ -0,0 +1,184 @@
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+/** The only envelope format this version reads and writes. */
+export const DYFM_GAME_SAVE_FORMAT = 'dyfm-game-save/1';
+/**
+ * BFR-WARFACTORY-011 — deterministic, headless game-save operations: seal (checksum), parse (corruption + format
+ * check), migrate (ordered replay with a typed failure) and conflict resolution (lineage first, then a time window).
+ * Nothing here reads a clock, a platform or a credential.
+ */
+export class DyFM_GameSave_Util {
+    /**
+     * FNV-1a (32-bit, hex) over the CANONICAL JSON of the payload (object keys sorted) — the same payload always gives
+     * the same checksum, whatever the key order. A corruption / identity check, NOT a security signature.
+     */
+    static checksum(payload) {
+        const text = DyFM_GameSave_Util.canonicalJson(payload);
+        let hash = 0x811c9dc5;
+        for (let i = 0; i < text.length; i++) {
+            hash ^= text.charCodeAt(i);
+            hash = Math.imul(hash, 0x01000193) >>> 0;
+        }
+        return hash.toString(16).padStart(8, '0');
+    }
+    /** Builds an envelope with the format and the computed checksum. Invalid input throws (`DYFM-GAME-SAVE-SEAL`). */
+    static seal(input) {
+        if (!input?.gameId?.trim() || !input.slotId?.trim() || !DyFM_GameSave_Util.isVersion(input.schemaVersion)
+            || !Number.isFinite(input.savedAtMs) || input.payload === undefined) {
+            throw new DyFM_Error({
+                message: 'DyFM_GameSave: seal needs gameId, slotId, an integer schemaVersion ≥ 1, a finite savedAtMs and a payload',
+                errorCode: 'DYFM-GAME-SAVE-SEAL',
+                issuerService: 'DyFM_GameSave_Util',
+            });
+        }
+        const envelope = {
+            format: DYFM_GAME_SAVE_FORMAT,
+            gameId: input.gameId,
+            slotId: input.slotId,
+            schemaVersion: input.schemaVersion,
+            savedAtMs: input.savedAtMs,
+            checksum: DyFM_GameSave_Util.checksum(input.payload),
+            payload: input.payload,
+        };
+        if (input.parentChecksum) {
+            envelope.parentChecksum = input.parentChecksum;
+        }
+        if (input.label) {
+            envelope.label = input.label;
+        }
+        return envelope;
+    }
+    /** The metadata of an envelope (what `list` returns — no payload). */
+    static metadataOf(envelope) {
+        const { payload: _payload, ...metadata } = envelope;
+        return metadata;
+    }
+    /**
+     * Validates a RAW read (anything an adapter returned): shape, format, field types and the checksum. A corrupt or
+     * foreign save is a typed failure — never a half-loaded game.
+     */
+    static parse(raw) {
+        const fail = (code, message) => ({ ok: false, code: code, message: message, appliedSteps: [] });
+        if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+            return fail('not-an-object', 'the save is not an object');
+        }
+        const envelope = raw;
+        if (envelope.format !== DYFM_GAME_SAVE_FORMAT) {
+            return fail('unknown-format', `unknown save format: ${String(envelope.format)}`);
+        }
+        if (typeof envelope.gameId !== 'string' || typeof envelope.slotId !== 'string'
+            || !DyFM_GameSave_Util.isVersion(envelope.schemaVersion) || !Number.isFinite(envelope.savedAtMs)
+            || typeof envelope.checksum !== 'string' || !('payload' in envelope)) {
+            return fail('invalid-field', 'the save is missing or has an invalid gameId / slotId / schemaVersion / savedAtMs / '
+                + 'checksum / payload');
+        }
+        if (DyFM_GameSave_Util.checksum(envelope.payload) !== envelope.checksum) {
+            return fail('checksum-mismatch', `the payload does not match its checksum (${envelope.checksum}) — corrupt save`);
+        }
+        return { ok: true, envelope: envelope, appliedSteps: [] };
+    }
+    /**
+     * Replays the migration steps from the envelope's `schemaVersion` up to `targetVersion`, step by step, on a COPY of
+     * the payload; the result is re-sealed (same slot, time and lineage). A save NEWER than the target, a gap in the
+     * chain or a throwing step is a typed failure and the input is untouched.
+     */
+    static migrate(envelope, steps, targetVersion) {
+        const applied = [];
+        const fail = (code, message) => ({ ok: false, code: code, message: message, appliedSteps: [...applied] });
+        if (steps.some((step) => !(step.to > step.from))) {
+            return fail('invalid-step', 'every migration step must go forward (to > from)');
+        }
+        if (envelope.schemaVersion > targetVersion) {
+            return fail('future-version', `save schema ${envelope.schemaVersion} is newer than this game (${targetVersion}) — `
+                + 'an older build must not load it');
+        }
+        let version = envelope.schemaVersion;
+        let payload = DyFM_GameSave_Util.clone(envelope.payload);
+        while (version < targetVersion) {
+            const step = steps.find((candidate) => candidate.from === version);
+            if (!step || step.to > targetVersion) {
+                return fail('missing-step', `no migration step from schema ${version} toward ${targetVersion}`);
+            }
+            try {
+                payload = step.migrate(payload);
+            }
+            catch (err) {
+                return fail('step-failed', `migration ${step.from}→${step.to} failed: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            applied.push(`${step.from}→${step.to}`);
+            version = step.to;
+        }
+        const migrated = {
+            ...envelope,
+            schemaVersion: version,
+            payload: payload,
+            checksum: DyFM_GameSave_Util.checksum(payload),
+        };
+        return { ok: true, envelope: migrated, appliedSteps: applied };
+    }
+    /**
+     * Deterministic local ↔ remote decision for ONE slot:
+     * none / one side missing → the existing one · same checksum → `in-sync` · proven descent (one side's
+     * `parentChecksum` is the other's checksum) → the descendant · both carry lineage but neither descends from the
+     * other → `ask-user` (a true divergence: picking one silently LOSES progress) · no lineage (legacy saves) → within
+     * `ambiguityWindowMs` `ask-user`, otherwise the newer one.
+     */
+    static resolveConflict(local, remote, options = {}) {
+        if (!local && !remote) {
+            return { decision: 'none', reason: 'no save on either side' };
+        }
+        if (!remote) {
+            return { decision: 'use-local', reason: 'only the local save exists' };
+        }
+        if (!local) {
+            return { decision: 'use-remote', reason: 'only the remote save exists' };
+        }
+        if (local.gameId !== remote.gameId || local.slotId !== remote.slotId) {
+            throw new DyFM_Error({
+                message: `DyFM_GameSave: resolveConflict compares ONE slot — got ${local.gameId}/${local.slotId} vs `
+                    + `${remote.gameId}/${remote.slotId}`,
+                errorCode: 'DYFM-GAME-SAVE-SLOT-MISMATCH',
+                issuerService: 'DyFM_GameSave_Util',
+            });
+        }
+        if (local.checksum === remote.checksum) {
+            return { decision: 'in-sync', reason: 'identical payloads' };
+        }
+        if (local.parentChecksum === remote.checksum) {
+            return { decision: 'use-local', reason: 'the local save was made from the remote one' };
+        }
+        if (remote.parentChecksum === local.checksum) {
+            return { decision: 'use-remote', reason: 'the remote save was made from the local one' };
+        }
+        if (local.parentChecksum && remote.parentChecksum) {
+            return { decision: 'ask-user', reason: 'both sides progressed separately (diverged) — either choice loses progress' };
+        }
+        const windowMs = options.ambiguityWindowMs ?? 30_000;
+        const gap = local.savedAtMs - remote.savedAtMs;
+        if (Math.abs(gap) <= windowMs) {
+            return { decision: 'ask-user', reason: `no lineage and saved within ${windowMs} ms of each other` };
+        }
+        return gap > 0
+            ? { decision: 'use-local', reason: 'no lineage; the local save is newer' }
+            : { decision: 'use-remote', reason: 'no lineage; the remote save is newer' };
+    }
+    static isVersion(value) {
+        return typeof value === 'number' && Number.isInteger(value) && value >= 1;
+    }
+    /** JSON with sorted object keys (arrays keep their order) — the checksum input. */
+    static canonicalJson(value) {
+        return JSON.stringify(value, (_key, item) => {
+            if (item && typeof item === 'object' && !Array.isArray(item)) {
+                return Object.keys(item).sort()
+                    .reduce((sorted, key) => {
+                    sorted[key] = item[key];
+                    return sorted;
+                }, {});
+            }
+            return item;
+        }) ?? 'undefined';
+    }
+    /** A deep copy for the migration replay (a step must not be able to change the caller's envelope). */
+    static clone(value) {
+        return value === undefined ? undefined : JSON.parse(JSON.stringify(value));
+    }
+}

package/build-esm/_modules/game/_models/build-reservation.interface.js

@@ -0,0 +1,5 @@
+/**
+ * BFR-WARFACTORY-012 (scope extension ①–②) — placement preview + reservation with escrow. Game-specific resources
+ * (drones, a hammer, the player's position) stay OUT: they are the game's extension, not these models.
+ */
+export {};

package/build-esm/_modules/game/_models/game-save.interface.js

@@ -0,0 +1,5 @@
+/**
+ * BFR-WARFACTORY-011 — headless game-save contracts. No provider credential, platform binding or game payload shape
+ * lives here: the payload is opaque (`TPayload`, typically the serialized game state), adapters are the game's.
+ */
+export {};