@futdevpro/fsm-dynamo 1.20.97 → 1.20.100

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

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

@@ -0,0 +1,162 @@
+import { DyFM_Error } from '../../../_models/control-models/error.control-model';
+/**
+ * BFR-WARFACTORY-013 — framework-independent zoom / pan viewport. It is deliberately NOT "the camera": the same model
+ * drives a world canvas and a DOM panel (e.g. a zoomable tech tree). Input handling (pointer, wheel, keys) belongs to
+ * a UI adapter that calls these methods.
+ *
+ * - `worldToScreen` / `screenToWorld` — the only transform; the screen centre shows `center`.
+ * - `zoomAt(screenPoint, factor)` — the world point UNDER the pointer stays under the pointer (wheel / pinch feel).
+ * - `panByScreen(dx, dy)` — drag: the content follows the pointer at any zoom.
+ * - `move(direction, speed, elapsedSeconds)` — elapsed-time keyboard panning; each step is capped
+ *   (`maxMoveStepSeconds`), so a hitch never makes the camera jump; speed is in SCREEN px/s (same feel at any zoom).
+ * - Zoom is clamped to [minZoom, maxZoom], the centre to `worldBounds`; non-finite input is ignored, never stored.
+ */
+export class DyFM_Viewport_ControlModel {
+    screenWidth;
+    screenHeight;
+    minZoom;
+    maxZoom;
+    bounds;
+    stepFactor;
+    maxMoveStep;
+    centerPoint = { x: 0, y: 0 };
+    zoomValue = 1;
+    /** Creates the viewport; an invalid configuration throws `DYFM-VIEWPORT-CONFIG`. */
+    constructor(config) {
+        this.minZoom = config.minZoom ?? 0.25;
+        this.maxZoom = config.maxZoom ?? 4;
+        this.stepFactor = config.zoomStepFactor ?? 1.1;
+        this.maxMoveStep = config.maxMoveStepSeconds ?? 0.1;
+        this.bounds = config.worldBounds;
+        const positive = (value) => Number.isFinite(value) && value > 0;
+        if (!positive(config.screenWidth) || !positive(config.screenHeight) || !positive(this.minZoom)
+            || !(this.maxZoom >= this.minZoom) || !(this.stepFactor > 1) || !positive(this.maxMoveStep)
+            || (this.bounds && !(this.bounds.maxX >= this.bounds.minX && this.bounds.maxY >= this.bounds.minY))) {
+            throw new DyFM_Error({
+                message: 'DyFM_Viewport: needs a positive screen size, 0 < minZoom ≤ maxZoom, zoomStepFactor > 1, '
+                    + 'maxMoveStepSeconds > 0 and ordered worldBounds',
+                errorCode: 'DYFM-VIEWPORT-CONFIG',
+                issuerService: 'DyFM_Viewport_ControlModel',
+            });
+        }
+        this.screenWidth = config.screenWidth;
+        this.screenHeight = config.screenHeight;
+        this.zoomValue = this.clampZoom(1);
+        this.centerPoint = this.clampCenter({ x: 0, y: 0 });
+    }
+    /** The world point shown at the screen centre. */
+    get center() {
+        return { ...this.centerPoint };
+    }
+    /** Screen pixels per world unit. */
+    get zoom() {
+        return this.zoomValue;
+    }
+    /** World → screen pixels. */
+    worldToScreen(world) {
+        return {
+            x: (world.x - this.centerPoint.x) * this.zoomValue + this.screenWidth / 2,
+            y: (world.y - this.centerPoint.y) * this.zoomValue + this.screenHeight / 2,
+        };
+    }
+    /** Screen pixels → world. */
+    screenToWorld(screen) {
+        return {
+            x: (screen.x - this.screenWidth / 2) / this.zoomValue + this.centerPoint.x,
+            y: (screen.y - this.screenHeight / 2) / this.zoomValue + this.centerPoint.y,
+        };
+    }
+    /** Sets the zoom (clamped), keeping the centre. */
+    setZoom(zoom) {
+        if (Number.isFinite(zoom)) {
+            this.zoomValue = this.clampZoom(zoom);
+        }
+    }
+    /** Zooms by `factor` keeping the world point under `screenPoint` fixed on screen (then clamps). */
+    zoomAt(screenPoint, factor) {
+        if (!Number.isFinite(factor) || factor <= 0 || !Number.isFinite(screenPoint?.x) || !Number.isFinite(screenPoint?.y)) {
+            return;
+        }
+        const anchor = this.screenToWorld(screenPoint);
+        this.zoomValue = this.clampZoom(this.zoomValue * factor);
+        // re-centre so that `anchor` maps back to `screenPoint`
+        this.centerPoint = this.clampCenter({
+            x: anchor.x - (screenPoint.x - this.screenWidth / 2) / this.zoomValue,
+            y: anchor.y - (screenPoint.y - this.screenHeight / 2) / this.zoomValue,
+        });
+    }
+    /** `steps` notches (+ in, − out) at `screenPoint` (default: the screen centre). */
+    zoomStep(steps, screenPoint) {
+        if (Number.isFinite(steps) && steps !== 0) {
+            this.zoomAt(screenPoint ?? { x: this.screenWidth / 2, y: this.screenHeight / 2 }, this.stepFactor ** steps);
+        }
+    }
+    /** Drag by a screen delta: the content moves WITH the pointer. */
+    panByScreen(dx, dy) {
+        if (Number.isFinite(dx) && Number.isFinite(dy)) {
+            this.centerPoint = this.clampCenter({
+                x: this.centerPoint.x - dx / this.zoomValue,
+                y: this.centerPoint.y - dy / this.zoomValue,
+            });
+        }
+    }
+    /**
+     * Elapsed-time panning (keyboard): `direction` is normalised, `speedScreenPxPerSecond` is screen speed, the elapsed
+     * time is capped at `maxMoveStepSeconds` per call. Returns the world distance actually moved.
+     */
+    move(direction, speedScreenPxPerSecond, elapsedSeconds) {
+        const length = Math.hypot(direction?.x ?? NaN, direction?.y ?? NaN);
+        if (!Number.isFinite(length) || length === 0 || !Number.isFinite(speedScreenPxPerSecond)
+            || speedScreenPxPerSecond <= 0 || !Number.isFinite(elapsedSeconds) || elapsedSeconds <= 0) {
+            return 0;
+        }
+        const seconds = Math.min(elapsedSeconds, this.maxMoveStep);
+        const worldDistance = speedScreenPxPerSecond * seconds / this.zoomValue;
+        const before = this.centerPoint;
+        this.centerPoint = this.clampCenter({
+            x: before.x + direction.x / length * worldDistance,
+            y: before.y + direction.y / length * worldDistance,
+        });
+        return Math.hypot(this.centerPoint.x - before.x, this.centerPoint.y - before.y);
+    }
+    /** Centres on a world point (clamped). */
+    centerOn(world) {
+        if (Number.isFinite(world?.x) && Number.isFinite(world?.y)) {
+            this.centerPoint = this.clampCenter(world);
+        }
+    }
+    /** The screen changed size (e.g. a window resize); the centre stays. */
+    resize(screenWidth, screenHeight) {
+        if (Number.isFinite(screenWidth) && screenWidth > 0 && Number.isFinite(screenHeight) && screenHeight > 0) {
+            this.screenWidth = screenWidth;
+            this.screenHeight = screenHeight;
+        }
+    }
+    /** Save state. */
+    exportState() {
+        return { schemaVersion: 1, center: this.center, zoom: this.zoomValue };
+    }
+    /** Restore state (clamped to THIS viewport's limits); `false` and no change when unreadable. */
+    importState(state) {
+        const candidate = state && typeof state === 'object' ? state : null;
+        if (!candidate || candidate.schemaVersion !== 1 || !Number.isFinite(candidate.zoom)
+            || !Number.isFinite(candidate.center?.x) || !Number.isFinite(candidate.center?.y)) {
+            return false;
+        }
+        this.zoomValue = this.clampZoom(candidate.zoom);
+        this.centerPoint = this.clampCenter(candidate.center);
+        return true;
+    }
+    clampZoom(zoom) {
+        return Math.min(this.maxZoom, Math.max(this.minZoom, zoom));
+    }
+    clampCenter(point) {
+        if (!this.bounds) {
+            return { x: point.x, y: point.y };
+        }
+        return {
+            x: Math.min(this.bounds.maxX, Math.max(this.bounds.minX, point.x)),
+            y: Math.min(this.bounds.maxY, Math.max(this.bounds.minY, point.y)),
+        };
+    }
+}

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

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

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

@@ -0,0 +1,196 @@
+import { DyFM_Error } from '../../../_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`).
+ */
+export 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 DyFM_Error({
+            message: `DyFM_WorkOrderScheduler: ${message}`,
+            errorCode: code,
+            issuerService: 'DyFM_WorkOrderScheduler_ControlModel',
+        });
+    }
+}

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

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

package/build-esm/_modules/game/index.js

@@ -14,6 +14,14 @@ 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 './_models/viewport.interface';
+export * from './_models/viewport.control-model';
 // COLLECTIONS
 export * from './_collections/audio-mixer.util';
 export * from './_collections/audio-scale.util';
+export * from './_collections/game-save.util';
+export * from './_collections/build-reservation.util';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@futdevpro/fsm-dynamo",
-  "version": "1.20.97",
+  "version": "1.20.100",
   "description": "Full Stack Model Collection for Dynamic (NodeJS-Typescript) Framework called Dynamo, by Future Development Ltd.",
   "DyBu_settings": {
     "packageType": "full-stack-package",