@futdevpro/fsm-dynamo 1.20.95 → 1.20.99

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

@@ -12,6 +12,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';
 // 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.95",
+  "version": "1.20.99",
   "description": "Full Stack Model Collection for Dynamic (NodeJS-Typescript) Framework called Dynamo, by Future Development Ltd.",
   "DyBu_settings": {
     "packageType": "full-stack-package",