@woosh/meep-engine 3.29.0 → 3.31.0

package/src/core/process/executor/ConcurrentExecutor.js

@@ -4,6 +4,7 @@ import { IllegalStateException } from "../../fsm/exceptions/IllegalStateExceptio
 import { objectKeyByValue } from "../../model/object/objectKeyByValue.js";
 import { TaskSignal } from "../task/TaskSignal.js";
 import TaskState from "../task/TaskState.js";
+import { task_find_dependency_cycle } from "../task/task_find_dependency_cycle.js";
 
 /**
  * @typedef {import("../task/Task.js").Task} Task
@@ -170,6 +171,10 @@ class ConcurrentExecutor {
                 this.removeTask(child);
             }
         }
+
+        // the group itself is not queued - its children are - so it needs its own terminal
+        // transition, or anything awaiting the group stays pending after every child is cancelled
+        this.#cancel(group);
     }
 
     /**
@@ -185,6 +190,9 @@ class ConcurrentExecutor {
         if (readyIndex !== -1) {
             //is in ready queue, remove
             this.queueReady.splice(readyIndex, 1);
+
+            this.#cancel(task);
+
             return true;
         }
 
@@ -194,6 +202,8 @@ class ConcurrentExecutor {
             //found in unresolved queue, remove
             this.queueUnresolved.splice(unresolvedIndex, 1);
 
+            this.#cancel(task);
+
             return true;
         }
 
@@ -201,6 +211,33 @@ class ConcurrentExecutor {
         return false;
     }
 
+    /**
+     * Give a removed task a terminal outcome.
+     *
+     * Removal used to only splice the task out of its queue: the task stayed RUNNING for ever, its
+     * promise never settled, and anything awaiting it - including the enclosing group, which counts
+     * it as still pending - hung. `TaskState.CANCELLED` exists for exactly this and was written
+     * nowhere in the scheduler.
+     *
+     * @param {Task|TaskGroup} task
+     */
+    #cancel(task) {
+        const state = task.state.getValue();
+
+        if (
+            state === TaskState.SUCCEEDED
+            || state === TaskState.FAILED
+            || state === TaskState.CANCELLED
+        ) {
+            // already terminal, nothing to announce
+            return;
+        }
+
+        task.state.set(TaskState.CANCELLED);
+
+        task.on.cancelled.send0();
+    }
+
     /**
      *
      * @param {Task} task
@@ -294,7 +331,14 @@ class ConcurrentExecutor {
                     // Dropping it from the queue is not enough: the task still
                     // has to reach a terminal state, or its promise never
                     // settles and everything awaiting it waits forever.
-                    unresolvedTask.state.set(TaskState.FAILED);
+                    //
+                    // Nor is the state enough on its own. `Task.join` reads the
+                    // state only at the moment it is called and otherwise
+                    // subscribes to `on.failed`, so a caller that takes the
+                    // promise before submitting the task was left waiting on a
+                    // signal nothing sent. The executor's other two terminal
+                    // transitions both dispatch; this one used not to.
+                    this.#fail_unresolved_task(unresolvedTask);
 
                     // its own dependants are now resolvable too, and they may
                     // sit earlier in the queue, so rescan from the start the
@@ -368,6 +412,38 @@ class ConcurrentExecutor {
 
     }
 
+    /**
+     * Fail a task that never got as far as the ready queue, because one of its dependencies failed.
+     * @param {Task} task
+     * @private
+     */
+    #fail_unresolved_task(task) {
+        const dependencies = task.dependencies;
+
+        let culprit = undefined;
+
+        for (let i = 0; i < dependencies.length; i++) {
+            if (dependencies[i].state.getValue() === TaskState.FAILED) {
+                culprit = dependencies[i];
+                break;
+            }
+        }
+
+        const reason = new Error(
+            `Task '${task.name}' failed because its dependency '${culprit === undefined ? '?' : culprit.name}' failed`
+        );
+
+        task.state.set(TaskState.FAILED);
+        task.on.failed.send1(reason);
+
+        if (!task.on.failed.hasHandlers()) {
+            // no one is watching for task failure
+            console.warn(`Task '${task.name}' failed.`, reason);
+        }
+
+        this.on.task_completed.send1(task);
+    }
+
     /**
      *
      * @param {Task} task
@@ -510,9 +586,63 @@ class ConcurrentExecutor {
      * kicks the scheduler into action, this is an internal method and should not be called from outside
      * @private
      */
+    /**
+     * Fail every task sitting on a dependency cycle, and then everything that depended on one.
+     *
+     * A cycle is the one form of "nothing can run" that no later `run` can rescue — an unsubmitted
+     * dependency is the other, and that one is a legal pattern here, so idleness alone is not the
+     * test. Left alone a cycle stopped the executor with no signal at all: `queueReady` never grows,
+     * `#executeTimeSlice` is the only place `on.completed` is sent and is never entered, so `join`
+     * subscribes to a signal that cannot fire and the task promises never settle.
+     * @private
+     */
+    #fail_dependency_cycles() {
+        for (
+            let cycle = task_find_dependency_cycle(this.queueUnresolved);
+            cycle !== null;
+            cycle = task_find_dependency_cycle(this.queueUnresolved)
+        ) {
+            const description = cycle.map(t => t.name).join(' -> ');
+
+            const reason = new Error(`Task dependency cycle: ${description} -> ${cycle[0].name}`);
+
+            console.error(reason.message, cycle.slice());
+
+            for (let i = 0; i < cycle.length; i++) {
+                const task = cycle[i];
+
+                const index = this.queueUnresolved.indexOf(task);
+
+                if (index !== -1) {
+                    this.queueUnresolved.splice(index, 1);
+                }
+
+                // as with any other failure, the task still has to reach a terminal state or its
+                // promise never settles and everything awaiting it waits forever
+                task.state.set(TaskState.FAILED);
+                task.on.failed.send1(reason);
+
+                this.on.task_completed.send1(task);
+            }
+
+            // the dependants of what just failed are resolvable now, as failures
+            this.resolveTasks();
+        }
+
+        if (this.queueReady.length === 0 && this.queueUnresolved.length === 0) {
+            // nothing is left to run, and `#executeTimeSlice` — which is what normally announces
+            // that — was never entered, so anything waiting on `join` would wait forever
+            this.on.completed.send0();
+        }
+    }
+
     prod() {
         this.resolveTasks();
 
+        if (!this.busy && this.queueReady.length === 0 && this.queueUnresolved.length > 0) {
+            this.#fail_dependency_cycles();
+        }
+
         if (!this.busy && this.queueReady.length > 0) {
             this.busy = true;
             this.#executeTimeSlice();

package/src/core/process/task/Task.d.ts

@@ -71,6 +71,14 @@ export class Task {
          * @type {Signal}
          */
         readonly failed: Signal;
+        /**
+         * Removed from its executor before reaching a terminal state. This is a terminal outcome
+         * like {@link failed}: without it, a removed task sat in RUNNING forever and every promise
+         * joined to it stayed pending.
+         * @readonly
+         * @type {Signal}
+         */
+        readonly cancelled: Signal;
     };
     /**
      *

package/src/core/process/task/Task.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"Task.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/task/Task.js"],"names":[],"mappings":"AAoBA;;;GAGG;AACH;IA+NI;;;;OAIG;IACH,yBAHW,MAAM,CAAC,IAAI,GAAC,SAAS,CAAC,CAAC,gBAOjC;IAED;;;OAGG;IACH,qBAFW,IAAI,GAAC,SAAS,gBAIxB;IAED;;;;;OAKG;IACH,kBAJW,IAAI,6CAqBd;IAED;;;;;OAKG;IACH,sBAJW,IAAI,EAAE,6CAgChB;IA9PD;;;;;;;;;;OAUG;IACH;QAR4B,IAAI,GAArB,MAAM;QACuD,WAAW,GAAxE,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,kBAAkB,KAAK,IAAI;QACnB,aAAa,QAAjC,UAAU;QACO,eAAe,SAAhC,MAAM;QACA,YAAY,GAA7B,IAAI,EAAE;QACW,iBAAiB,GAAlC,MAAM;OAwDhB;IA9GD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH;QACI;;;WAGG;0BADO,MAAM;QAGhB;;;WAGG;4BADO,MAAM;QAGhB;;;WAGG;yBADO,MAAM;MAGlB;IAEF;;;OAGG;IACH,OAFU,eAAe,CAEsB;IAE/C;;;;OAIG;IACH,0BAHU,MAAM,CAGM;IACtB;;;;OAIG;IACH,6BAHU,MAAM,CAGS;IA6BrB;;;OAGG;IACH,cAFU,IAAI,EAAE,CAEgB;IAEhC;;;OAGG;IACH,mBAFU,MAAM,CAE0B;IAE1C;;;OAGG;IACH,MAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFsB,UAAU,CAEN;IAE1B;;;OAGG;IACH,YAFU,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,kBAAkB,KAAK,IAAI,CAE/B;IAWjC,0BAUC;IAED;;;OAGG;IACH,sBAFa,MAAM,CAIlB;IAED,+BAEC;IAED;;;;OAIG;IACH,oBAHW,IAAI,GAAC,SAAS,QAuBxB;IAED;;;OAGG;IACH,uBAFW,MAAM,CAAC,IAAI,GAAC,SAAS,CAAC,CAAC,QAWjC;IAED,mBAEC;IAED;;;;OAIG;IACH,gDAEC;IAED;;OAEG;IACH,sBAkBC;IAED;;;OAGG;IACH,wBAEC;IAmFL;;;OAGG;IACH,iBAFU,OAAO,CAEI;CANpB;;iCA5TY,OAAO,mCAAmC,EAAE,OAAO;wBACnD,OAAO,gBAAgB,EAAE,OAAO;mBAT1B,+BAA+B;4BAGtB,gCAAgC;2BACjC,iBAAiB"}
+{"version":3,"file":"Task.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/task/Task.js"],"names":[],"mappings":"AAoBA;;;GAGG;AACH;IAuOI;;;;OAIG;IACH,yBAHW,MAAM,CAAC,IAAI,GAAC,SAAS,CAAC,CAAC,gBAOjC;IAED;;;OAGG;IACH,qBAFW,IAAI,GAAC,SAAS,gBAIxB;IAED;;;;;OAKG;IACH,kBAJW,IAAI,6CAwBd;IAED;;;;;OAKG;IACH,sBAJW,IAAI,EAAE,6CAgChB;IAjQD;;;;;;;;;;OAUG;IACH;QAR4B,IAAI,GAArB,MAAM;QACuD,WAAW,GAAxE,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,kBAAkB,KAAK,IAAI;QACnB,aAAa,QAAjC,UAAU;QACO,eAAe,SAAhC,MAAM;QACA,YAAY,GAA7B,IAAI,EAAE;QACW,iBAAiB,GAAlC,MAAM;OAwDhB;IAtHD;;;OAGG;IACH,aAFU,MAAM,CAEE;IAElB;;OAEG;IACH;QACI;;;WAGG;0BADO,MAAM;QAGhB;;;WAGG;4BADO,MAAM;QAGhB;;;WAGG;yBADO,MAAM;QAGhB;;;;;;WAMG;4BADO,MAAM;MAGlB;IAEF;;;OAGG;IACH,OAFU,eAAe,CAEsB;IAE/C;;;;OAIG;IACH,0BAHU,MAAM,CAGM;IACtB;;;;OAIG;IACH,6BAHU,MAAM,CAGS;IA6BrB;;;OAGG;IACH,cAFU,IAAI,EAAE,CAEgB;IAEhC;;;OAGG;IACH,mBAFU,MAAM,CAE0B;IAE1C;;;OAGG;IACH,MAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,aAFsB,UAAU,CAEN;IAE1B;;;OAGG;IACH,YAFU,CAAC,IAAI,EAAE,IAAI,EAAE,QAAQ,EAAE,kBAAkB,KAAK,IAAI,CAE/B;IAWjC,0BAUC;IAED;;;OAGG;IACH,sBAFa,MAAM,CAIlB;IAED,+BAEC;IAED;;;;OAIG;IACH,oBAHW,IAAI,GAAC,SAAS,QAuBxB;IAED;;;OAGG;IACH,uBAFW,MAAM,CAAC,IAAI,GAAC,SAAS,CAAC,CAAC,QAWjC;IAED,mBAEC;IAED;;;;OAIG;IACH,gDAEC;IAED;;OAEG;IACH,sBAkBC;IAED;;;OAGG;IACH,wBAEC;IAsFL;;;OAGG;IACH,iBAFU,OAAO,CAEI;CANpB;;iCAvUY,OAAO,mCAAmC,EAAE,OAAO;wBACnD,OAAO,gBAAgB,EAAE,OAAO;mBAT1B,+BAA+B;4BAGtB,gCAAgC;2BACjC,iBAAiB"}

package/src/core/process/task/Task.js

@@ -48,6 +48,14 @@ export class Task {
          * @type {Signal}
          */
         failed: new Signal(),
+        /**
+         * Removed from its executor before reaching a terminal state. This is a terminal outcome
+         * like {@link failed}: without it, a removed task sat in RUNNING forever and every promise
+         * joined to it stayed pending.
+         * @readonly
+         * @type {Signal}
+         */
+        cancelled: new Signal(),
     };
 
     /**
@@ -277,7 +285,9 @@ export class Task {
         const state = task.state.getValue();
         if (state === TaskState.SUCCEEDED) {
             resolve();
-        } else if (state === TaskState.FAILED) {
+        } else if (state === TaskState.FAILED || state === TaskState.CANCELLED) {
+            // CANCELLED is terminal like FAILED: a caller waiting on a task that was removed from
+            // its executor has to be told, or it waits for ever
             if (reject !== undefined) {
                 reject();
             }
@@ -285,6 +295,7 @@ export class Task {
             task.on.completed.addOne(resolve);
             if (reject !== undefined) {
                 task.on.failed.addOne(reject);
+                task.on.cancelled.addOne(reject);
             }
         }
     }

package/src/core/process/task/TaskGroup.d.ts

@@ -21,6 +21,12 @@ declare class TaskGroup {
         started: Signal;
         completed: Signal;
         failed: Signal;
+        /**
+         * Removed from its executor before reaching a terminal state. See the note on
+         * {@link Task}'s signal of the same name; `Task.join` treats it as a rejection, and
+         * `join` is what a group is awaited through.
+         */
+        cancelled: Signal;
     };
     /**
      *

package/src/core/process/task/TaskGroup.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"TaskGroup.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/task/TaskGroup.js"],"names":[],"mappings":";AASA;IACI;;;;;OAKG;IACH,sBAJW,CAAC,IAAI,GAAC,SAAS,CAAC,EAAE,SAClB,MAAM,EA8BhB;IAvBG;;;OAGG;IACH,MAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,UAFU,CAAC,IAAI,GAAC,SAAS,CAAC,EAAE,CAEJ;IAExB;;;;MAIC;IAED;;;OAGG;IACH,OAFU,eAAe,CAE0B;IAGvD;;;OAGG;IACH,sBAFa,MAAM,CAiBlB;IAED;;;;OAIG;IACH,gBAHW,IAAI,GAAC,SAAS,GACZ,OAAO,CAInB;IAED;;;OAGG;IACH,sBAFW,CAAC,IAAI,GAAC,SAAS,CAAC,EAAE,QAQ5B;IAED;;;OAGG;IACH,0BAFW,IAAI,GAAC,SAAS,QAkBxB;IAED,yCAUC;IAED;;;OAGG;IACH,wBAFa,MAAM,CAmBlB;IAED;;;OAGG;IACH,2BAFa,MAAM,CAyBlB;IAED,0BAmCC;IAED;;;;OAIG;IACH,sCAEC;IAED;;;OAGG;IACH,WAFa,QAAQ,OAAO,CAAC,CAI5B;IAGL;;;OAGG;IACH,sBAFU,OAAO,CAEc;CAN9B;iBA5NgB,WAAW;mBAHT,+BAA+B;4BAEtB,gCAAgC"}
+{"version":3,"file":"TaskGroup.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/task/TaskGroup.js"],"names":[],"mappings":";AASA;IACI;;;;;OAKG;IACH,sBAJW,CAAC,IAAI,GAAC,SAAS,CAAC,EAAE,SAClB,MAAM,EAoChB;IA7BG;;;OAGG;IACH,MAFU,MAAM,CAEA;IAEhB;;;OAGG;IACH,UAFU,CAAC,IAAI,GAAC,SAAS,CAAC,EAAE,CAEJ;IAExB;;;;QAII;;;;WAIG;;MAEN;IAED;;;OAGG;IACH,OAFU,eAAe,CAE0B;IAGvD;;;OAGG;IACH,sBAFa,MAAM,CAiBlB;IAED;;;;OAIG;IACH,gBAHW,IAAI,GAAC,SAAS,GACZ,OAAO,CAInB;IAED;;;OAGG;IACH,sBAFW,CAAC,IAAI,GAAC,SAAS,CAAC,EAAE,QAQ5B;IAED;;;OAGG;IACH,0BAFW,IAAI,GAAC,SAAS,QAkBxB;IAED,yCAUC;IAED;;;OAGG;IACH,wBAFa,MAAM,CAmBlB;IAED;;;OAGG;IACH,2BAFa,MAAM,CAyBlB;IAED,0BAmCC;IAED;;;;OAIG;IACH,sCAEC;IAED;;;OAGG;IACH,WAFa,QAAQ,OAAO,CAAC,CAI5B;IAGL;;;OAGG;IACH,sBAFU,OAAO,CAEc;CAN9B;iBAlOgB,WAAW;mBAHT,+BAA+B;4BAEtB,gCAAgC"}

package/src/core/process/task/TaskGroup.js

@@ -33,7 +33,13 @@ class TaskGroup {
         this.on = {
             started: new Signal(),
             completed: new Signal(),
-            failed: new Signal()
+            failed: new Signal(),
+            /**
+             * Removed from its executor before reaching a terminal state. See the note on
+             * {@link Task}'s signal of the same name; `Task.join` treats it as a rejection, and
+             * `join` is what a group is awaited through.
+             */
+            cancelled: new Signal()
         };
 
         /**

package/src/core/process/task/task_find_dependency_cycle.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Find one dependency cycle reachable from `roots`, following {@link Task#dependencies}.
+ *
+ * A cycle can never resolve: every task on it waits for a task that is waiting for it, so all of them
+ * stay INITIAL forever. Unlike a dependency that simply has not been submitted yet, no later `run`
+ * can rescue it — which is what makes this, and not "the executor is idle with work outstanding", the
+ * safe test for a deadlock.
+ *
+ * Iterative rather than recursive: task graphs are authored by hand but are not bounded in depth, and
+ * a stack overflow while diagnosing a hang is not an improvement on the hang.
+ *
+ * @param {Task[]} roots
+ * @returns {Task[]|null} the tasks on a cycle, in dependency order, or null if there is none. The
+ *  first element depends on the last.
+ */
+export function task_find_dependency_cycle(roots: Task[]): Task[] | null;
+//# sourceMappingURL=task_find_dependency_cycle.d.ts.map

package/src/core/process/task/task_find_dependency_cycle.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"task_find_dependency_cycle.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/task/task_find_dependency_cycle.js"],"names":[],"mappings":"AAkBA;;;;;;;;;;;;;;GAcG;AACH,kDAJW,MAAM,GACJ,MAAM,GAAC,IAAI,CAkDvB"}

package/src/core/process/task/task_find_dependency_cycle.js

@@ -0,0 +1,81 @@
+/**
+ * Not yet visited. Absent from the map, in practice — named for the comparison below.
+ * @type {number}
+ */
+const UNVISITED = 0;
+
+/**
+ * On the current DFS path. An edge back to one of these is a cycle.
+ * @type {number}
+ */
+const ON_PATH = 1;
+
+/**
+ * Fully explored, and no cycle was found through it.
+ * @type {number}
+ */
+const EXPLORED = 2;
+
+/**
+ * Find one dependency cycle reachable from `roots`, following {@link Task#dependencies}.
+ *
+ * A cycle can never resolve: every task on it waits for a task that is waiting for it, so all of them
+ * stay INITIAL forever. Unlike a dependency that simply has not been submitted yet, no later `run`
+ * can rescue it — which is what makes this, and not "the executor is idle with work outstanding", the
+ * safe test for a deadlock.
+ *
+ * Iterative rather than recursive: task graphs are authored by hand but are not bounded in depth, and
+ * a stack overflow while diagnosing a hang is not an improvement on the hang.
+ *
+ * @param {Task[]} roots
+ * @returns {Task[]|null} the tasks on a cycle, in dependency order, or null if there is none. The
+ *  first element depends on the last.
+ */
+export function task_find_dependency_cycle(roots) {
+    const states = new Map();
+
+    const root_count = roots.length;
+
+    for (let r = 0; r < root_count; r++) {
+        const root = roots[r];
+
+        if (states.get(root) === EXPLORED) {
+            continue;
+        }
+
+        const path = [root];
+
+        //frame `i` holds how many of `path[i]`'s dependencies have been taken
+        const cursors = [0];
+
+        states.set(root, ON_PATH);
+
+        while (path.length > 0) {
+            const depth = path.length - 1;
+            const task = path[depth];
+            const dependencies = task.dependencies;
+
+            if (cursors[depth] < dependencies.length) {
+                const dependency = dependencies[cursors[depth]];
+
+                cursors[depth]++;
+
+                const state = states.get(dependency) ?? UNVISITED;
+
+                if (state === ON_PATH) {
+                    return path.slice(path.indexOf(dependency));
+                } else if (state === UNVISITED) {
+                    states.set(dependency, ON_PATH);
+                    path.push(dependency);
+                    cursors.push(0);
+                }
+            } else {
+                states.set(task, EXPLORED);
+                path.pop();
+                cursors.pop();
+            }
+        }
+    }
+
+    return null;
+}

package/src/core/process/undo/ActionProcessor.d.ts

@@ -115,6 +115,18 @@ export class ActionProcessor<C, M> {
      * @private
      */
     private __unsafe_mark;
+    /**
+     * Trim the history down to whichever of the two budgets binds first.
+     *
+     * NOTE: they are budgets in different units, and the previous version mixed them -
+     * `min2(marks.length, this.historyMemoryLimit)`, a count against a byte count. With the default
+     * 268435456-byte limit that was always `marks.length`, so the trimming block never ran at all
+     * and `historyMarkLimit` was a no-op; lower the memory limit to make the cap real and the block
+     * finally ran, computing `lastMark - this.historyMarkLimit`, a negative index into `marks`,
+     * and dereferenced `undefined`.
+     *
+     * Each policy names a first-mark-to-keep of its own here, and the stricter one wins.
+     */
     cleanupHistory(): void;
     /**
      *

package/src/core/process/undo/ActionProcessor.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"ActionProcessor.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/undo/ActionProcessor.js"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH;IA4DI;;;;OAIG;IACH,0BAMC;IAtED;;;OAGG;IACH,SAFU,YAAY,CAED;IAErB;;;OAGG;IACH,OAFU,MAAM,KAAK,CAAC,CAAC,CAAC,CAEb;IAEX;;OAEG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,kBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,oBAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,aAFU,OAAO,CAAC,CAAC,GAAG,MAAM,CAED;IAE3B;;;OAGG;IACH,eAFU,OAAO,CAAC,CAAC,GAAG,MAAM,CAEC;IAE7B;;;;;;;;;OASG;IACH,uBAAmC;IAQ/B;;;OAGG;IACH,aAAsB;IAG1B;;;;;;;;;;OAUG;IACH,kBAMC;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,0BAJW,MAAM,GACJ,CAAC,CAWb;IAED;;OAEG;IACH,cAGC;IAED;;;;;;;;OAQG;IACH,wBAFW,MAAM,QAyChB;IAED;;;OAGG;IACH,kBAFW,CAAC,iBAIX;IAED;;;OAGG;IACH,sBAyBC;IAED,uBA2BC;IAED;;;;;OAKG;IACH,2CAcC;IAED;;;;;OAKG;IACH,4BAJW,CAAC,GACC,OAAO,CAKnB;IAED;;;;;;OAMG;IACH,4BAyDC;IAED,sBAEC;IAED;;;;OAIG;IACH,sBAmCC;IAED;;OAEG;IACH,sBAEC;IAED;;;;OAIG;IACH,sBA0BC;IAED;;;;;;OAMG;IACH,gBAFW,QAAQ,iBAUlB;IAED;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,oBAgCC;CACJ;iBAtfgB,+BAA+B;qBAG3B,WAAW;mBAFb,+BAA+B"}
+{"version":3,"file":"ActionProcessor.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/undo/ActionProcessor.js"],"names":[],"mappings":"AAMA;;;;;;GAMG;AACH;IA4DI;;;;OAIG;IACH,0BAMC;IAtED;;;OAGG;IACH,SAFU,YAAY,CAED;IAErB;;;OAGG;IACH,OAFU,MAAM,KAAK,CAAC,CAAC,CAAC,CAEb;IAEX;;OAEG;IACH,QAFU,MAAM,CAEL;IAEX;;;OAGG;IACH,oBAFU,MAAM,CAEO;IAEvB;;;OAGG;IACH,kBAFU,MAAM,CAES;IAEzB;;;OAGG;IACH,oBAFU,MAAM,CAEe;IAE/B;;;OAGG;IACH,aAFU,OAAO,CAAC,CAAC,GAAG,MAAM,CAED;IAE3B;;;OAGG;IACH,eAFU,OAAO,CAAC,CAAC,GAAG,MAAM,CAEC;IAE7B;;;;;;;;;OASG;IACH,uBAAmC;IAQ/B;;;OAGG;IACH,aAAsB;IAG1B;;;;;;;;;;OAUG;IACH,kBAMC;IAED;;;OAGG;IACH,gBAFa,MAAM,CAIlB;IAED;;;;;OAKG;IACH,0BAJW,MAAM,GACJ,CAAC,CAWb;IAED;;OAEG;IACH,cAGC;IAED;;;;;;;;OAQG;IACH,wBAFW,MAAM,QAyChB;IAED;;;OAGG;IACH,kBAFW,CAAC,iBAIX;IAED;;;OAGG;IACH,sBAyBC;IAED;;;;;;;;;;;OAWG;IACH,uBAyCC;IAED;;;;;OAKG;IACH,2CAcC;IAED;;;;;OAKG;IACH,4BAJW,CAAC,GACC,OAAO,CAKnB;IAED;;;;;;OAMG;IACH,4BAyDC;IAED,sBAEC;IAED;;;;OAIG;IACH,sBAmCC;IAED;;OAEG;IACH,sBAEC;IAED;;;;OAIG;IACH,sBA0BC;IAED;;;;;;OAMG;IACH,gBAFW,QAAQ,iBAUlB;IAED;;;OAGG;IACH,kCAEC;IAED;;;;;OAKG;IACH,oBAgCC;CACJ;iBAhhBgB,+BAA+B;qBAG3B,WAAW;mBAFb,+BAA+B"}

package/src/core/process/undo/ActionProcessor.js

@@ -224,33 +224,59 @@ export class ActionProcessor {
         this.cleanupHistory();
     }
 
+    /**
+     * Trim the history down to whichever of the two budgets binds first.
+     *
+     * NOTE: they are budgets in different units, and the previous version mixed them -
+     * `min2(marks.length, this.historyMemoryLimit)`, a count against a byte count. With the default
+     * 268435456-byte limit that was always `marks.length`, so the trimming block never ran at all
+     * and `historyMarkLimit` was a no-op; lower the memory limit to make the cap real and the block
+     * finally ran, computing `lastMark - this.historyMarkLimit`, a negative index into `marks`,
+     * and dereferenced `undefined`.
+     *
+     * Each policy names a first-mark-to-keep of its own here, and the stricter one wins.
+     */
     cleanupHistory() {
         const marks = this.marks;
 
-        let lastMark = min2(marks.length, this.historyMemoryLimit) - 1;
-
-        if (this.historyMemoryUsage >= this.historyMemoryLimit) {
-
-
-            for (; lastMark > 0 && marks[lastMark].memoryUsage > this.historyMemoryUsage; lastMark--) {
-            }
-
+        const mark_count = marks.length;
 
+        if (mark_count === 0) {
+            return;
         }
 
-        if (lastMark + 1 < marks.length) {
-            const marksToDrop = lastMark - this.historyMarkLimit;
+        // count policy: at most `historyMarkLimit` marks are kept
+        let first_keep = 0;
 
-            //get first mark to keep
-            const newFirstMark = marks[marksToDrop];
+        if (mark_count > this.historyMarkLimit) {
+            first_keep = mark_count - this.historyMarkLimit;
+        }
 
-            //drop history before first mark's index
-            this.dropHistory(newFirstMark.index);
+        // Memory policy. `mark.memoryUsage` is the cumulative usage as of that mark, so the bytes
+        // still held once everything before mark `i` is dropped is the difference from the current
+        // total. The last mark is never dropped: it is the one just added, and a single action
+        // larger than the whole budget must not take itself out with the rest.
+        const memory_usage = this.historyMemoryUsage;
+
+        while (
+            first_keep < mark_count - 1
+            && memory_usage - marks[first_keep].memoryUsage > this.historyMemoryLimit
+            ) {
+            first_keep++;
+        }
 
-            assert.equal(newFirstMark.index, 0, "New First Mark's index must be 0");
+        if (first_keep <= 0) {
+            return;
         }
 
+        // `dropHistory` drops every mark whose index is at or before the cut, so it is handed the
+        // index of the LAST mark being dropped - everything after that survives. Doing it the other
+        // way round, by the first mark to keep, would take that mark with it.
+        const last_dropped = marks[first_keep - 1];
+
+        this.dropHistory(last_dropped.index);
 
+        assert.equal(marks.length, mark_count - first_keep, 'cleanup must keep exactly the marks from first_keep onward');
     }
 
     /**

package/src/core/process/worker/OnDemandWorkerManager.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"OnDemandWorkerManager.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/worker/OnDemandWorkerManager.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH;IAwBI;;;OAGG;IACH,iCAOC;IAjCD;;;;OAIG;IACH,wBAAoB;IAEpB;;;;;OAKG;IACH,qBAAoB;IAEpB;;;;OAIG;IACH,8BAA2B;IASvB;;OAEG;IACH,oBAAoB;IAGxB;;;;;OAKG;IACH,qBAFW,MAAM,QAMhB;IAED;;OAEG;IACH,kBAKC;IAED;;OAEG;IACH,mCASC;IAED;;;OAGG;IACH,6BAFW,MAAM,QAMhB;IAED;;OAEG;IACH,kBAMC;IAED;;OAEG;IACH,kBAeC;IAGD;;;;;;OAMG;IACH,iBAJW,MAAM,kCAahB;CACJ"}
+{"version":3,"file":"OnDemandWorkerManager.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/worker/OnDemandWorkerManager.js"],"names":[],"mappings":"AAEA;;;GAGG;AACH;IAwBI;;;OAGG;IACH,iCAOC;IAjCD;;;;OAIG;IACH,wBAAoB;IAEpB;;;;;OAKG;IACH,qBAAoB;IAEpB;;;;OAIG;IACH,8BAA2B;IASvB;;OAEG;IACH,oBAAoB;IAGxB;;;;;OAKG;IACH,qBAFW,MAAM,QAMhB;IAED;;OAEG;IACH,kBAKC;IAED;;OAEG;IACH,mCASC;IAED;;;OAGG;IACH,6BAFW,MAAM,QAMhB;IAED;;OAEG;IACH,kBAMC;IAED;;OAEG;IACH,kBAeC;IAGD;;;;;;OAMG;IACH,iBAJW,MAAM,kCAkBhB;CACJ"}

package/src/core/process/worker/OnDemandWorkerManager.js

@@ -132,7 +132,12 @@ export class OnDemandWorkerManager {
 
         const promise = this.worker.$submitRequest(name, parameters);
 
-        promise.finally(this.decrement);
+        // `finally` returns a *new* promise that rejects with the same reason, and discarding it
+        // leaves that rejection unhandled - an `unhandledrejection` in the browser, a process exit
+        // under Node's default policy - even though the caller attached its own catch to `promise`.
+        // Handling both outcomes settles the derived promise instead of abandoning it, which is
+        // what `PromiseWatcher.add` and `ConcurrencyGate` both already do and say.
+        promise.then(this.decrement, this.decrement);
 
         return promise;
     }

package/src/core/process/worker/WorkerBuilder.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"WorkerBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/worker/WorkerBuilder.js"],"names":[],"mappings":";AAQA;IAEI;;;OAGG;IACH,SAFU,MAAM,EAAE,CAEL;IACb,YAAa;IACb;;;OAGG;IACH,WAFU;QAAC,CAAC,WAAU;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,EAAE,CAEtB;IACf,sBAA6B;IAE7B;;;OAGG;IACH,cAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,UACN,WAAS,MAAM,QAIzB;IAED;;;;;OAKG;IACH,6CAKC;IAED;;;OAGG;IACH,mBAFW,MAAM,QAMhB;IAED;;;OAGG;IACH,SAFa,WAAW,CA2HvB;CACJ;wBA3LuB,8BAA8B;wBAC9B,kBAAkB"}
+{"version":3,"file":"WorkerBuilder.d.ts","sourceRoot":"","sources":["../../../../../src/core/process/worker/WorkerBuilder.js"],"names":[],"mappings":";AAQA;IAEI;;;OAGG;IACH,SAFU,MAAM,EAAE,CAEL;IACb,YAAa;IACb;;;OAGG;IACH,WAFU;QAAC,CAAC,WAAU;QAAC,IAAI,EAAC,MAAM,CAAA;KAAC,EAAE,CAEtB;IACf,sBAA6B;IAE7B;;;OAGG;IACH,cAFW,MAAM,QAIhB;IAED;;;;OAIG;IACH,gBAHW,MAAM,UACN,WAAS,MAAM,QAIzB;IAED;;;;;OAKG;IACH,6CAKC;IAED;;;OAGG;IACH,mBAFW,MAAM,QAMhB;IAED;;;OAGG;IACH,SAFa,WAAW,CAiJvB;CACJ;wBAjNuB,8BAA8B;wBAC9B,kBAAkB"}

package/src/core/process/worker/WorkerBuilder.js

@@ -117,15 +117,26 @@ class WorkerBuilder {
         //api handler
         Array.prototype.push.apply(codeLines, [
             //language=js
-            `function extractTransferables(obj, result) {
+            `function pushTransferableIfUnique(result, value) {
+                // De-duplicated, matching the extractTransferables module this is a copy of.
+                // postMessage rejects a transfer list holding the same object twice with a
+                // DataCloneError, and a result carrying two views over one ArrayBuffer - a header
+                // plus a payload, an interleaved vertex buffer - is the natural shape for a worker
+                // that carves its return value out of one allocation.
+                if (result.indexOf(value) === -1) {
+                    result.push(value);
+                }
+            }
+
+            function extractTransferables(obj, result) {
                 if (obj === null || typeof obj !== "object") {
                     return; //not an object (or null, which typeof reports as "object"), skip
                 } else if (obj instanceof ArrayBuffer) {
-                    result.push(obj);
+                    pushTransferableIfUnique(result, obj);
                 } else if (obj.buffer instanceof ArrayBuffer) {
-                    result.push(obj.buffer);
+                    pushTransferableIfUnique(result, obj.buffer);
                 } else if (typeof ImageBitmap !== "undefined" && obj instanceof ImageBitmap) {
-                    result.push(obj);
+                    pushTransferableIfUnique(result, obj);
                 } else {
                     for (var i in obj) {
                         if (obj.hasOwnProperty(i)) {
@@ -169,7 +180,18 @@ class WorkerBuilder {
                         
                         if(method_result != null && typeof method_result.then === "function"){
                             // thenable
-                            method_result.then(sendResult, sendError);
+                            //
+                            // sendResult can throw - postMessage refuses a value it cannot
+                            // structured-clone - and on this path there is no enclosing try, so
+                            // the throw used to escape as an in-worker unhandled rejection and the
+                            // caller's request never settled. Report it instead.
+                            method_result.then(function (value) {
+                                try {
+                                    sendResult(value);
+                                } catch (e) {
+                                    sendError(e);
+                                }
+                            }, sendError);
                         }else{
                             // straight value
                             sendResult(method_result);

package/src/core/wfc/WFCCellChoice.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Which cell the solver collapses next.
+ *
+ * Affects how reliably a solve finishes and how the output looks. It never affects *which* tile a
+ * cell ends up with — that is always a weighted draw — only the order cells are decided in.
+ *
+ * {@link SCANLINE } is the default and solves rule sets the other two fail on. Reach for
+ * {@link ENTROPY } when the character of the output matters more than first-time success.
+ * `WFC_DESIGN.md` §4.4 carries the measurements behind that.
+ */
+export type WFCCellChoice = number;
+export namespace WFCCellChoice {
+    let ENTROPY: number;
+    let MINIMUM_REMAINING: number;
+    let SCANLINE: number;
+}
+//# sourceMappingURL=WFCCellChoice.d.ts.map

package/src/core/wfc/WFCCellChoice.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"WFCCellChoice.d.ts","sourceRoot":"","sources":["../../../../src/core/wfc/WFCCellChoice.js"],"names":[],"mappings":";;;;;;;;;;4BAWU,MAAM"}

package/src/core/wfc/WFCCellChoice.js

@@ -0,0 +1,36 @@
+/**
+ * Which cell the solver collapses next.
+ *
+ * Affects how reliably a solve finishes and how the output looks. It never affects *which* tile a
+ * cell ends up with — that is always a weighted draw — only the order cells are decided in.
+ *
+ * {@link SCANLINE} is the default and solves rule sets the other two fail on. Reach for
+ * {@link ENTROPY} when the character of the output matters more than first-time success.
+ * `WFC_DESIGN.md` §4.4 carries the measurements behind that.
+ *
+ * @readonly
+ * @enum {number}
+ */
+export const WFCCellChoice = {
+    /**
+     * Lowest Shannon entropy over the remaining weights. The only policy in which weights affect
+     * the order cells are decided in, which is what gives its output an organic look; it is what
+     * Gumin's original and DeBroglie both default to.
+     *
+     * Needs a priority queue, and fails on rule sets the other two solve.
+     */
+    ENTROPY: 0,
+    /**
+     * Fewest remaining possibilities. Identical to {@link ENTROPY} when every weight is equal, and
+     * an integer comparison rather than a logarithm. Needs the same priority queue.
+     */
+    MINIMUM_REMAINING: 1,
+    /**
+     * Ascending cell index, skipping cells already decided. The default: no priority structure,
+     * and the policy most likely to solve a given rule set.
+     *
+     * Its cost is a directional bias in the output. Solving in blocks
+     * (see {@link wfc_state_set_eligible}) confines that bias to a block.
+     */
+    SCANLINE: 2
+};