@futdevpro/fsm-dynamo 1.20.95 → 1.20.99

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

@@ -10,6 +10,14 @@ export * from './_models/seeded-random-registry.interface';
 export * from './_models/seeded-random-registry.control-model';
 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;AAGtD,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

@@ -15,7 +15,15 @@ tslib_1.__exportStar(require("./_models/seeded-random-registry.interface"), expo
 tslib_1.__exportStar(require("./_models/seeded-random-registry.control-model"), exports);
 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;AAEtD,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/flying-effect.control-model.js

@@ -5,6 +5,7 @@ export class DyFM_FlyingEffect_ControlModel {
     defaultDurationMs;
     defaultRisePx;
     defaultStackGapPx;
+    reducedMotion;
     items = [];
     sequence = 0;
     paused = false;
@@ -20,6 +21,15 @@ export class DyFM_FlyingEffect_ControlModel {
         this.defaultDurationMs = this.positive(config.defaultDurationMs ?? 1_400, 'defaultDurationMs');
         this.defaultRisePx = this.nonNegative(config.defaultRisePx ?? 52, 'defaultRisePx');
         this.defaultStackGapPx = this.nonNegative(config.defaultStackGapPx ?? 18, 'defaultStackGapPx');
+        this.reducedMotion = config.reducedMotion === true;
+    }
+    /**
+     * BFR-WARFACTORY-006 — reduced motion (e.g. the player setting or `prefers-reduced-motion`): the text no longer RISES,
+     * it stays at its anchor + stack offset and only fades (a fade is not motion). Takes effect from the next snapshot —
+     * lifetimes, stacking and expiry are unchanged, so switching it mid-game is safe.
+     */
+    setReducedMotion(reducedMotion) {
+        this.reducedMotion = reducedMotion === true;
     }
     spawn(command, nowMs) {
         this.validateCommand(command);
@@ -129,7 +139,7 @@ export class DyFM_FlyingEffect_ControlModel {
                 mergeKey: item.mergeKey,
                 progress,
                 opacity: 1 - progress,
-                offsetY: -(item.risePx * progress + item.stackGapPx * stackIndex),
+                offsetY: -((this.reducedMotion ? 0 : item.risePx * progress) + item.stackGapPx * stackIndex),
                 stackIndex,
             };
         });
@@ -143,6 +153,7 @@ export class DyFM_FlyingEffect_ControlModel {
             expiredCount: this.expiredCount,
             evictedCount: this.evictedCount,
             paused: this.paused,
+            reducedMotion: this.reducedMotion,
             lastTimeMs: this.lastTimeMs,
         };
     }

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 {};

package/build-esm/_modules/game/_models/simulation-clock.control-model.js

@@ -0,0 +1,117 @@
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+/**
+ * BFR-WARFACTORY-010 — framework-independent, monotonic simulation clock.
+ *
+ * - The CALLER supplies real delta, speed and pause; the clock never reads wall time (deterministic, replayable).
+ * - Fixed-step mode (`fixedStepSeconds`): scaled time goes into an accumulator, whole steps are committed and the
+ *   remainder carries over — at speed 10 the loop runs ten times as many steps of the same size, so fast-forward is
+ *   behaviour-neutral. Variable mode (no `fixedStepSeconds`): one step of `realDelta * speed` (not neutral).
+ * - Real deltas are clamped (`maxRealDeltaSeconds`) and fixed steps capped (`maxStepsPerAdvance`); what is cut or
+ *   dropped is reported, never silently lost.
+ * - `exportState` / `importState` (versioned; the legacy `{ elapsedSimulationSeconds }` shape is accepted) / `reset`.
+ *   An invalid snapshot is rejected WITHOUT touching the running clock.
+ */
+export class DyFM_SimulationClock_ControlModel {
+    fixedStepSeconds;
+    maxRealDeltaSeconds;
+    maxStepsPerAdvance;
+    elapsedSeconds = 0;
+    accumulatorSeconds = 0;
+    /** Creates the clock; an invalid configuration throws (`DYFM-SIM-CLOCK-CONFIG`). */
+    constructor(config = {}) {
+        this.fixedStepSeconds = config.fixedStepSeconds === undefined
+            ? undefined
+            : DyFM_SimulationClock_ControlModel.positive(config.fixedStepSeconds, 'fixedStepSeconds');
+        this.maxRealDeltaSeconds =
+            DyFM_SimulationClock_ControlModel.positive(config.maxRealDeltaSeconds ?? 0.25, 'maxRealDeltaSeconds');
+        this.maxStepsPerAdvance = DyFM_SimulationClock_ControlModel.positive(config.maxStepsPerAdvance ?? 240, 'maxStepsPerAdvance');
+        if (!Number.isInteger(this.maxStepsPerAdvance)) {
+            throw DyFM_SimulationClock_ControlModel.configError('maxStepsPerAdvance must be an integer');
+        }
+    }
+    /** Total committed simulation seconds. */
+    now() {
+        return this.elapsedSeconds;
+    }
+    /** Advances by one real frame. Paused, speed ≤ 0 or a non-finite input ⇒ nothing passes (a zero result). */
+    advance(input) {
+        const idle = {
+            simulationDeltaSeconds: 0, steps: 0, stepSeconds: this.fixedStepSeconds ?? 0,
+            clampedRealSeconds: 0, droppedSimulationSeconds: 0,
+        };
+        if (input.paused || !Number.isFinite(input.realDeltaSeconds) || !Number.isFinite(input.speed)
+            || input.speed <= 0 || input.realDeltaSeconds <= 0) {
+            return idle;
+        }
+        const realSeconds = Math.min(input.realDeltaSeconds, this.maxRealDeltaSeconds);
+        const clampedRealSeconds = input.realDeltaSeconds - realSeconds;
+        const scaledSeconds = realSeconds * input.speed;
+        if (this.fixedStepSeconds === undefined) {
+            // Variable step: one update of the scaled delta (documented as NOT behaviour-neutral across speeds)
+            this.elapsedSeconds += scaledSeconds;
+            return {
+                simulationDeltaSeconds: scaledSeconds, steps: 1, stepSeconds: scaledSeconds,
+                clampedRealSeconds: clampedRealSeconds, droppedSimulationSeconds: 0,
+            };
+        }
+        // Fixed step: commit whole steps, carry the remainder, cap the burst (spiral-of-death guard)
+        this.accumulatorSeconds += scaledSeconds;
+        // the epsilon keeps 3 × (1/60) from rounding down to 2 steps
+        const available = Math.floor(this.accumulatorSeconds / this.fixedStepSeconds + 1e-9);
+        const steps = Math.min(available, this.maxStepsPerAdvance);
+        let droppedSimulationSeconds = 0;
+        this.accumulatorSeconds = Math.max(0, this.accumulatorSeconds - available * this.fixedStepSeconds);
+        if (available > steps) {
+            droppedSimulationSeconds = (available - steps) * this.fixedStepSeconds;
+        }
+        this.elapsedSeconds += steps * this.fixedStepSeconds;
+        return {
+            simulationDeltaSeconds: steps * this.fixedStepSeconds, steps: steps, stepSeconds: this.fixedStepSeconds,
+            clampedRealSeconds: clampedRealSeconds, droppedSimulationSeconds: droppedSimulationSeconds,
+        };
+    }
+    /** The save/load snapshot. */
+    exportState() {
+        return { schemaVersion: 1, elapsedSimulationSeconds: this.elapsedSeconds, accumulatorSeconds: this.accumulatorSeconds };
+    }
+    /**
+     * Restores a snapshot; returns `false` (and changes NOTHING) when it is invalid. Accepts the legacy
+     * `{ elapsedSimulationSeconds }` shape (no `schemaVersion`) as an empty accumulator.
+     */
+    importState(snapshot) {
+        if (!snapshot || typeof snapshot !== 'object') {
+            return false;
+        }
+        const state = snapshot;
+        const accumulator = state.schemaVersion === undefined ? 0 : state.accumulatorSeconds;
+        if ((state.schemaVersion !== undefined && state.schemaVersion !== 1)
+            || !DyFM_SimulationClock_ControlModel.isNonNegative(state.elapsedSimulationSeconds)
+            || !DyFM_SimulationClock_ControlModel.isNonNegative(accumulator)) {
+            return false;
+        }
+        this.elapsedSeconds = state.elapsedSimulationSeconds;
+        this.accumulatorSeconds = accumulator;
+        return true;
+    }
+    /** A new run: zero elapsed time and accumulator. */
+    reset() {
+        this.elapsedSeconds = 0;
+        this.accumulatorSeconds = 0;
+    }
+    static isNonNegative(value) {
+        return typeof value === 'number' && Number.isFinite(value) && value >= 0;
+    }
+    static positive(value, field) {
+        if (typeof value !== 'number' || !Number.isFinite(value) || value <= 0) {
+            throw DyFM_SimulationClock_ControlModel.configError(`${field} must be a finite number > 0 (got ${value})`);
+        }
+        return value;
+    }
+    static configError(message) {
+        return new DyFM_Error({
+            message: `DyFM_SimulationClock: ${message}`,
+            errorCode: 'DYFM-SIM-CLOCK-CONFIG',
+            issuerService: 'DyFM_SimulationClock_ControlModel',
+        });
+    }
+}

package/build-esm/_modules/game/_models/simulation-clock.interface.js

@@ -0,0 +1 @@
+export {};