@woosh/meep-engine 3.0.2 → 3.2.0

package/src/REVIEW_2026_08_06/core-process.md

@@ -1,266 +1,266 @@
-# Correctness review — `core/process`, `core/graph`, `core/debug`, `core/time`, `core/clipboard`, `core/dom`, `core/assert.js`
-
-Scope reviewed: every non-spec source file under the listed directories.
-Every finding below was reproduced by executing the real module in Node (no mocks) unless marked otherwise.
-
----
-
-## core/debug
-
-### PROC-1 `anything()` matches nothing and `nothing()` matches everything
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/debug/matchers/IsAnything.js:12`
-- **Defect**: `IsAnything.matches()` returns `false` unconditionally. The matcher whose entire purpose is "accept any value" rejects every value, and `nothing()` (built as `not(anything())`) therefore accepts every value. Both public factories in `matchers.js` are logically inverted.
-- **Failure scenario**: `anything().matches(42)` → `false` (verified). `assert.that(x, 'x', anything())` throws for *every* `x`. Conversely `nothing().matches(42)` → `true` (verified), so `assert.that(x, 'x', nothing())` never triggers — a guard that is supposed to be unreachable silently passes everything.
-- **Fix**: `matches(item, mismatch_description) { return true; }`.
-- **Confidence**: Confirmed
-
-### PROC-2 `Matcher.matches(item)` — the documented single-argument form — throws in AllOf / IsIterableContaining / CombinableMatcher
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/debug/matchers/AllOf.js:25` (also `IsIterableContaining.js:22`, `CombinableMatcher.js:25`)
-- **Defect**: The base class declares `matches(item, mismatch_description = NullDescription.INSTANCE)` and documents the second parameter as optional. Subclass overrides re-declare the parameter *without* the default (default parameter values are not inherited), then dereference it on the mismatch path. `assert.that` calls `matcher.matches(value)` with one argument, so this is the primary in-repo call site.
-- **Failure scenario**: `allOf(isIn([3,7]), not(equalTo(7))).matches(2)` → `TypeError: Cannot read properties of undefined (reading 'appendDescriptionOf')` instead of `false` (verified). `hasItem(1).matches([])` → `TypeError: ... (reading 'appendText')` (verified). Any `assert.that(v, 'v', allOf(...))` on a failing value surfaces a TypeError instead of the intended assertion message.
-- **Fix**: Give every override the same default: `matches(item, mismatch_description = NullDescription.INSTANCE)`.
-- **Confidence**: Confirmed
-
-### PROC-3 `DescribeAs` never performs template substitution
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/debug/matchers/DescribeAs.js:42`
-- **Defect**: Three independent errors in `describeTo`. (a) `String.prototype.matchAll` returns an *iterator*, not an array, so `matches.length` is `undefined` and `for (let i = 0; i < undefined; i++)` never executes. (b) `match.groups[1]` reads a named-group bag that is `undefined` for this un-named-group regex — it would throw if the loop ever ran; it should be `match[1]`. (c) `textStart = match[0].length` should be `match.index + match[0].length`, otherwise the tail slice restarts from the wrong offset.
-- **Failure scenario**: `new DescribeAs("value must be %0 or %1", equalTo(1), ["A","B"]).describeTo(d)` writes the literal `value must be %0 or %1` instead of `value must be "A" or "B"` (verified). Reached in production via `nothing(message)`, which routes through `describeAs`.
-- **Fix**: `const matches = Array.from(this.template.matchAll(RX));`, use `match[1]`, and set `textStart = match.index + match[0].length`.
-- **Confidence**: Confirmed
-
-### PROC-4 `appendValue(undefined)` renders as `"null"`
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/debug/BaseDescription.js:39`
-- **Defect**: `if (value == null)` (loose equality) is true for `undefined` as well as `null`, so the dedicated `else if (value === undefined)` branch on the next line is unreachable.
-- **Failure scenario**: `new InMemoryDescriptor().appendValue(undefined).value` → `"null"` (verified). An assertion failure on an `undefined` value reports it as `null`, which is a different bug class for the reader.
-- **Fix**: Use `value === null` on the first branch, or reorder so the `undefined` test comes first.
-- **Confidence**: Confirmed
-
-### PROC-5 `IsIterableContaining` mismatch text describes the collection, not its elements
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/debug/matchers/IsIterableContaining.js:41`
-- **Defect**: The mismatch loop iterates `itemElement` but passes the whole collection `item` to `describeMismatch`. The element variable is never used.
-- **Failure scenario**: `hasItem(9).matches([1,2,3], d)` produces `mismatches were: [was <1,2,3>, was <1,2,3>, was <1,2,3>]` instead of `was 1, was 2, was 3`.
-- **Fix**: `this.#element_matcher.describeMismatch(itemElement, mismatch_description);`
-- **Confidence**: Confirmed
-
----
-
-## core/process — task & executor
-
-### PROC-6 A task blocked on a FAILED dependency is silently dropped: never fails, never resolves
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/executor/ConcurrentExecutor.js:286`
-- **Defect**: `resolveTasks()`'s `ResolutionType.FAILED` branch splices the task out of `queueUnresolved` and does nothing else — it never sets `task.state` to `FAILED` and never dispatches `task.on.failed`. The task is left in `INITIAL` forever, invisible to the executor.
-- **Failure scenario**: `A = failingTask(...)`, `B.addDependency(A)`, `executor.run(A); executor.run(B)`. Verified result: `A.state === FAILED (3)`, `B.state === INITIAL (0)`, no `on.failed`/`on.completed` dispatch on B, `executor.contains(B) === false`, `queueUnresolved.length === 0`. `await B.promise()` hangs forever. Worse, any task `C` depending on `B` sees `B.state === INITIAL` in `tryResolve` and returns `UNRESOLVED` forever — the whole downstream subgraph is permanently stuck while `executor.on.completed` still fires.
-- **Fix**: In the FAILED branch, mirror `#fail_task`: set `unresolvedTask.state.set(TaskState.FAILED)` and `unresolvedTask.on.failed.send1(<dependency failure reason>)` before/after the splice, then restart the scan (`i = -1; l = queueUnresolved.length;`) because the dispatch can mutate the queue.
-- **Confidence**: Confirmed
-
-### PROC-7 `Task.executeSync()` never updates `Task.state`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/task/Task.js:214`
-- **Defect**: `executeSync` runs the initializer, cycles to completion and fires `on.started`/`on.completed`/`on.failed`, but never assigns `this.state`. The task remains in `TaskState.INITIAL` after a successful synchronous run.
-- **Failure scenario**: `const t = emptyTask(); t.executeSync();` → `t.state.getValue() === 0 (INITIAL)`, not `4 (SUCCEEDED)` (verified). Consequently `Task.join`/`t.promise()` takes the "not finished yet" branch and registers `on.completed.addOne(resolve)` on a signal that already fired — the promise never settles (verified: still `PENDING` after 20 ms). Feeding a sync-executed task as a dependency into a `ConcurrentExecutor` also blocks its dependents forever, because `tryResolve` reads `INITIAL` → `UNRESOLVED`.
-- **Fix**: Set `this.state.set(TaskState.RUNNING)` before the cycle loop and `TaskState.SUCCEEDED` / `TaskState.FAILED` alongside the corresponding signal dispatch.
-- **Confidence**: Confirmed
-
-### PROC-8 `ignoreFailureTask` does not ignore a *thrown* failure
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/task/util/ignoreFailureTask.js:38`
-- **Defect**: The wrapper only converts an explicit `TaskSignal.EndFailure` return into `EndSuccess`. An exception thrown out of `task.cycle()` propagates through the wrapper unchanged, and `ConcurrentExecutor.#executeTimeSlice` treats a thrown exception as task failure (`#fail_task`) — so the wrapper fails too. Throwing is a first-class failure mode in this codebase: `failingTask(e)` (the repo's own canonical failing task) fails exclusively by throwing, and both `promiseTask` and `futureTask` `throw error` on rejection.
-- **Failure scenario**: `ignoreFailureTask(failingTask(new Error("boom")))` — the wrapper propagates `Error: boom` (verified) instead of resolving in success as its JSDoc promises. Under `ConcurrentExecutor` the wrapper ends in `FAILED`.
-- **Fix**: Wrap the `task.cycle()` call in try/catch and return `TaskSignal.EndSuccess` on a caught exception (matching the existing treatment of an initializer throw).
-- **Confidence**: Confirmed
-
-### PROC-9 `RemainingTimeEstimator.estimate` averages over unfilled sample slots
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/task/RemainingTimeEstimator.js:39`
-- **Defect**: `rates` is a zero-filled `Float32Array(sampleCount)`; `estimate` always divides the sum by the full `sampleCount` rather than by the number of `update()` calls actually recorded. The unwritten zeros drag the average rate down by a factor of `sampleCount / filled`.
-- **Failure scenario**: `const e = new RemainingTimeEstimator(10); e.update(1000, 0.5); e.estimate(0.5)` → `10000` (verified) when the correct remaining time is `1000`. A 10× over-estimate persists until the ring buffer is fully populated — i.e. for the whole early phase of every task, which is exactly when an ETA is displayed.
-- **Fix**: Track a `filled` counter (`Math.min(filled + 1, sampleCount)`) in `update` and divide by it in `estimate`; return `Infinity` when `filled === 0`.
-- **Confidence**: Confirmed
-
----
-
-## core/process — undo (`ActionProcessor`)
-
-### PROC-10 undo → do → redo crashes: the future branch of history is truncated but its marks are not
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/undo/ActionProcessor.js:487`
-- **Defect**: `__unsafe_do` discards the redo branch with `history.crop(0, this.cursor)` but leaves `this.marks` untouched (there is a `// TODO clear future marks` on line 489). Marks whose `index` now exceeds `history.length` become dangling, and `__unsafe_redo` uses those indices as a loop bound.
-- **Failure scenario** (verified end-to-end): `await ap.do(A); await ap.do(B); await ap.mark("m1"); await ap.undo(); await ap.do(C);` leaves `history.length === 1`, `cursor === 1`, `marks === [index 2]`. The next `await ap.redo()` computes `mark = 2`, reads `history.get(1) === undefined` and throws `TypeError: Cannot read properties of undefined (reading 'apply')`. This is the ordinary editor sequence "undo, then do something else, then press redo".
-- **Fix**: In `__unsafe_do`, before/alongside the crop, splice off every mark with `index > this.cursor` and dispatch `onMarkRemoved` for each.
-- **Confidence**: Confirmed
-
-### PROC-11 `doMany` with a failing action never settles and permanently deadlocks the processor
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/undo/ActionProcessor.js:439`
-- **Defect**: `new Promise(async (resolve, reject) => { ... await this.__unsafe_do(action) ... resolve(); })` — the classic async-executor antipattern. When `__unsafe_do` rejects, the rejection escapes into the async executor function's own (discarded) promise; `reject` is never called, so the constructed promise `p` stays pending forever. `p` is then stored in `this.__last_promise`, and every subsequent `do`/`undo`/`redo`/`mark`/`navigateTo` starts with `await this.__barrier()` on that never-settling promise.
-- **Failure scenario** (verified): `ap.doMany([goodAction, throwingAction])` — the returned promise is still `PENDING` after 60 ms and an `unhandledRejection` is emitted (fatal in Node ≥ 15 / reported by Jest). A following `await ap.do(anotherAction)` is also still `PENDING` and `history.length` stays at 1: the ActionProcessor is bricked for the remainder of the session.
-- **Fix**: Drop the wrapper — make the body a plain `async` helper (`const p = (async () => { for (...) await this.__unsafe_do(actions[i]); })()`), matching how `do`/`undo`/`redo` already build `p`.
-- **Confidence**: Confirmed
-
-### PROC-12 `cleanupHistory` compares a mark *count* against a *byte* limit — neither history limit is ever enforced
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/undo/ActionProcessor.js:204`
-- **Defect**: `let lastMark = min2(marks.length, this.historyMemoryLimit) - 1;` mixes a mark count with a byte budget (default 268435456), so `lastMark` is always `marks.length - 1` and the subsequent `if (lastMark + 1 < marks.length)` is always false. `historyMarkLimit` is never consulted at all. The memory branch is equally dead: it decrements while `marks[lastMark].memoryUsage > this.historyMemoryUsage`, but a mark's recorded usage is a *past* snapshot and therefore never exceeds the current total. Separately, if the guard ever did fire, `const marksToDrop = lastMark - this.historyMarkLimit` is negative for any realistic history and `marks[marksToDrop]` would be `undefined` → `TypeError` on `.index`.
-- **Failure scenario** (verified): with `ap.historyMarkLimit = 2`, doing 6 actions each followed by a mark leaves `marks.length === 6` and `history.length === 6` — nothing dropped. With `ap.historyMemoryLimit = 3000` and 10 actions of 1000 bytes each, `historyMemoryUsage === 10000` and `history.length === 10`. Both documented caps are inert, so undo history grows without bound for the process lifetime.
-- **Fix**: Compute the mark cut-off from `historyMarkLimit` (`const marksToDrop = marks.length - this.historyMarkLimit`) and, separately, walk marks from the oldest while `historyMemoryUsage - marks[i].memoryUsage > historyMemoryLimit` for the byte cap. Guard `marksToDrop > 0` before indexing.
-- **Confidence**: Confirmed
-
-### PROC-13 `dropHistory` destroys the boundary mark that should survive at index 0
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/undo/ActionProcessor.js:134`
-- **Defect**: The cut-off scan uses `marks[i].index <= recordsToDrop`. Records `[0, recordsToDrop)` are removed, so a mark at exactly `index === recordsToDrop` still points at a surviving record (it becomes index 0) and must be kept. The condition should be `<`. `cleanupHistory`'s own `assert.equal(newFirstMark.index, 0, ...)` on line 224 documents that this mark is expected to survive — the two sites contradict each other.
-- **Failure scenario**: history `[A,B,C,D]`, one mark at `index 2`. `dropHistory(2)` leaves history `[C,D]` but removes the mark, so the caller loses the only navigable point in the surviving history.
-- **Fix**: `for (; i < markCount && marks[i].index < recordsToDrop; i++)`.
-- **Confidence**: Confirmed (by reading; the runtime check is blocked by PROC-14's arity issue in dev builds)
-
-### PROC-14 `onMarkAdded` and `onMarkRemoved` emit different payload types
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/undo/ActionProcessor.js:196` and `:154`
-- **Defect**: `mark()` dispatches `this.onMarkAdded.send1(description)` (the raw description, verified) while `dropHistory` dispatches `Mark` instances (`dropped_marks.forEach(this.onMarkRemoved.send1, ...)`) and `mark()`'s own eviction path does `this.onMarkRemoved.send1(mark)`. Both signals are typed `Signal<M>` (description) in the field JSDoc. Additionally, `Array.prototype.forEach` invokes the callback with `(element, index, array)`, so `send1` is called with three arguments.
-- **Failure scenario**: A UI keeping an undo-stack list keyed by description adds `"m1"` on `onMarkAdded` but receives `Mark { index: 0, description: "m1" }` on `onMarkRemoved`; the lookup misses and the entry is never removed from the list.
-- **Fix**: Dispatch `mark.description` from both removal sites, and replace the `forEach(send1, signal)` with an explicit loop so exactly one argument is passed.
-- **Confidence**: Confirmed
-
----
-
-## core/process — other
-
-### PROC-15 `Future` can reach a terminal state twice; a rejected future can flip to resolved
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/Future.js:80`
-- **Defect**: `__handleResolution` and `__handleRejection` set `state` unconditionally with no already-settled guard. The `resolve`/`reject` callbacks handed to the resolver can therefore both fire, and the last one wins — violating the settle-once contract that `Future` advertises by mirroring the Promise API (`then`/`catch`, `@extends Promise<T>`).
-- **Failure scenario** (verified): `const f = new Future((res, rej) => { rej(new Error("nope")); res(42); }); f.resolve();` → `f.state === RESOLVED (2)`, and `f.then(onOk, onErr)` invokes `onOk(42)`. A real Promise stays rejected and runs `onErr`. Downstream, `futureTask` polls `resolved`/`rejected` flags set by exactly this `then` registration, so a resolver that rejects-then-resolves turns a failed task into a successful one.
-- **Fix**: Early-return from both handlers unless `this.state === FutureStates.PENDING`.
-- **Confidence**: Confirmed
-
-### PROC-16 `WatchDog.bark` disarms a watchdog that its own action re-armed
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/WatchDog.js:52`
-- **Defect**: `bark()` runs `this.action.call(...)` *first* and only then sets `this.timeoutId = -1`. During the action `isActive()` still reports `true`, so a re-arm from inside the action is either ignored (`start()` no-ops) or scheduled and then orphaned (`kick()` installs a fresh timer whose id is immediately overwritten with `-1`).
-- **Failure scenario** (verified): a watchdog whose action calls `wd.start()` to re-arm itself — the canonical "handle the stall, then keep watching" pattern. After the first bark `isActive() === false` and no second bark ever occurs: the watchdog is silently dead. With `kick()` instead, a timer is left running that `stop()` can no longer cancel (`isActive()` is false), so the action fires again unexpectedly and the `kick()` inside it throws `WatchDog is not active`.
-- **Fix**: Set `this.timeoutId = -1` *before* invoking the action.
-- **Confidence**: Confirmed
-
-### PROC-17 `.finally()` chains create unhandled promise rejections
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/PromiseWatcher.js:45` and `H:/git/moh/app/src/mir-engine/meep/src/core/process/worker/OnDemandWorkerManager.js:135`
-- **Defect**: Both sites call `promise.finally(cb)` and discard the returned promise. `p.finally(cb)` produces a *new* promise that adopts `p`'s rejection; because nothing attaches a handler to it, a rejecting `p` always produces an unhandled rejection — even when the original caller handled `p` correctly.
-- **Failure scenario**: `watcher.add(somePromise)` where `somePromise` later rejects → `unhandledrejection` in the browser; in Node/Jest (Node ≥ 15 default) the process aborts. For `OnDemandWorkerManager.request`, `WorkerProxy.__failAllPending` rejects every in-flight request on worker error, so a single failing worker script turns each queued request into an unhandled rejection on top of the (correctly handled) rejection the caller sees.
-- **Fix**: Suppress the derived promise: `promise.then(cb, cb)`, or `promise.finally(cb).catch(() => {})`.
-- **Confidence**: Confirmed
-
-### PROC-18 `CompositeProcess.finalize()` on a running composite leaves children in `Stopped`, not `Finalized`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/CompositeProcess.js:27`
-- **Defect**: `finalize()` finalizes children first, then calls `super.finalize()`. `BaseProcess.finalize` sees the composite still in `Running` and calls `this.shutdown()`, which is the *overridden* `CompositeProcess.shutdown` — so every child is shut down a second time, and `BaseProcess.shutdown` unconditionally writes `ProcessState.Stopped` over the child's `Finalized` state.
-- **Failure scenario** (verified): a `CompositeProcess([a, b])` taken through `initialize(); startup(); finalize()` ends with composite = `finalized` but `a` and `b` = `stopped`. Any subsequent lifecycle check that requires children to be `Finalized`, or a second `finalize()`, sees corrupt state; children that release resources in `finalize` are also asked to shut down after they have already torn themselves down.
-- **Failure path**: `finalize()` → children `Finalized` → `super.finalize()` sees `Running` → `this.shutdown()` → `children.forEach(c => c.shutdown())` → children forced back to `Stopped`.
-- **Fix**: Have `CompositeProcess.finalize` shut itself down first (`if (this.__state.getValue() === ProcessState.Running) super.shutdown();`) before finalizing children, or make `BaseProcess.finalize` call `BaseProcess.prototype.shutdown` on itself only.
-- **Confidence**: Confirmed
-
----
-
-## core/process — worker
-
-### PROC-19 `extractTransferables(null)` throws
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/worker/extractTransferables.js:24`
-- **Defect**: `typeof null === "object"`, so a `null` value falls past the "not an object, skip" branch, fails `instanceof ArrayBuffer`, and reaches `value.buffer` → TypeError. The inline duplicate of this exact function generated inside `WorkerBuilder.build()` (line 121) *does* have the `obj === null` guard, which shows the omission is unintentional.
-- **Failure scenario** (verified): `extractTransferables({ a: null }, [])` → `TypeError: Cannot read properties of null (reading 'buffer')`. Any worker payload containing a null field — extremely common in serialized game objects — crashes before the message is ever posted. The spec file covers `{}`, buffers, typed arrays and nesting, but never a null.
-- **Fix**: Change the first branch to `if (value === null || typeof value !== "object")`.
-- **Confidence**: Confirmed
-
-### PROC-20 A failed `postMessage` drops the request without ever rejecting its promise
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/worker/WorkerProxy.js:154`
-- **Defect**: When `trySendMessage` returns `false` (it swallows the `postMessage` exception and logs it), the request is removed from the pending queue but neither `resolve` nor `reject` is invoked. The promise handed to the caller can never settle: it is no longer in the queue, so `__handleMessage` and `__failAllPending` will never find it either.
-- **Failure scenario**: `workerProxy.someMethod(objectContainingAFunctionOrDomNode)` — `postMessage` throws `DataCloneError`, the console shows `failed to send message:`, and `await` on the returned promise hangs for the lifetime of the page. PROC-21 makes this reachable in ordinary use, since the `toJSON` sanitisation that was meant to prevent non-cloneable payloads never runs.
-- **Fix**: Reject the promise on send failure: `reject(new Error(...))` in place of (or alongside) the `array_remove_first`.
-- **Confidence**: Confirmed
-
-### PROC-21 `needsSerialization` compares a function against the string `"function"` — `toJSON` is never applied
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/worker/WorkerProxy.js:40`
-- **Defect**: `value.toJSON === "function"` should be `typeof value.toJSON === "function"`. As written the branch is unreachable, so `$submitRequest` always posts the raw argument and the documented `toJSON` sanitisation path is dead. (`hasOwnProperty('toJSON')` additionally excludes the normal case where `toJSON` lives on the class prototype.)
-- **Failure scenario** (verified with the exact predicate): `needsSerialization({ toJSON() { return { plain: 1 }; } })` → `false`. Passing any engine object that relies on `toJSON` to strip non-cloneable members (signals, DOM handles, functions) to a worker method posts the raw object, which `postMessage` rejects with `DataCloneError` → the request silently disappears per PROC-20.
-- **Fix**: `if (typeof value.toJSON === "function") { return true; }` (drop the `hasOwnProperty` gate so prototype-defined `toJSON` is honoured).
-- **Confidence**: Confirmed
-
----
-
-## core/graph
-
-### PROC-22 `colorizeGraph` builds an asymmetric adjacency matrix from directed edges and returns invalid colourings
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/graph/coloring/colorizeGraph.js:38`
-- **Defect**: `graphToMatrix` writes `data[i][other] = 1` only when `edge.validateTransition(node, otherNode)` succeeds. For a `Forward` edge `P → Q` this sets `data[P][Q] = 1` but leaves `data[Q][P] = 0`. Graph colouring is an inherently undirected constraint, and the downstream `colorizing`/`updateNN` conflict elimination reads the matrix by row only, so a conflict recorded in just one direction is missed whenever the *other* endpoint is coloured first.
-- **Failure scenario** (verified): nodes `X, P, Q, R` with `Forward` edges `P→X`, `X→Q`, `X→R`. `colorizeGraph` returns `[1, 1, 2, 2]` — `X` and `P` are adjacent yet share colour 1. `validateGraphColoring(colors, graph)` (which uses undirected `getNeighbours`) returns `false` on the library's own output.
-- **Fix**: Make the matrix symmetric: set both `data[i * V + otherIdx]` and `data[otherIdx * V + i]` for every attached edge, and drop the `validateTransition` gate (or keep it only for genuinely directed colouring variants, which this algorithm is not).
-- **Confidence**: Confirmed
-
-### PROC-23 `convert_graph_to_dot_string` silently omits every `Backward` edge
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/graph/convert_graph_to_dot_string.js:59`
-- **Defect**: The emission guard is `(direction === Forward || direction === Undirected) && edge.first === node`. `EdgeDirectionType.Backward` satisfies neither disjunct, so a backward edge is skipped when visiting `first` and also skipped when visiting `second` (because `edge.first !== node` there). It is never written out.
-- **Failure scenario** (verified): a graph with nodes `A`, `B` and `graph.createEdge("A", "B", EdgeDirectionType.Backward)` produces DOT containing both node declarations and **zero** `->` lines. The rendered diagram shows two isolated nodes; the edge is invisible.
-- **Fix**: Add a `Backward` case that emits the reversed arrow `nodeId(secondIndex) -> nodeId(i)` once (guarded on `edge.first === node` so it is emitted exactly once).
-- **Confidence**: Confirmed
-
-### PROC-24 Laplacian is inconsistent on multigraphs: degree counts parallel edges, adjacency saturates at 1
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/graph/graph_compute_adjacency_matrix.js:23` (surfaces in `graph_compute_laplacian_matrix.js:22`)
-- **Defect**: `graph_compute_adjacency_matrix` writes a literal `1` per edge, so parallel edges collapse to a single 1. `graph_compute_degree_matrix` uses `graph.getNodeDegree`, which returns `NodeContainer.getEdgeCount()` and *does* count each parallel edge. `L = D - A` therefore has rows that don't sum to zero — the defining property of a graph Laplacian. Multi-edges are a first-class supported state of `Graph` (`NodeContainer.__neighbors` is explicitly documented as "number of edges to that node").
-- **Failure scenario** (verified): nodes `A`, `B` joined by two parallel edges. `graph_compute_laplacian_matrix` yields `[[2, -1], [-1, 2]]`; row sums are `1`, not `0`. The correct Laplacian is `[[2, -2], [-2, 2]]`. Any spectral use (Fiedler vector, spectral clustering, connectivity count via the zero-eigenvalue multiplicity) reads the wrong matrix.
-- **Fix**: Accumulate instead of assigning in `graph_compute_adjacency_matrix` — `result.setCellValue(a, b, result.getCellValue(a, b) + 1)` for both `(a,b)` and `(b,a)` — and document that the matrix must be zero-filled by the caller (the JSDoc already states it does not zero-fill).
-- **Confidence**: Confirmed
-
-### PROC-25 Heap invariant broken after merging edge weights: `bubbleDown` used where the element must bubble **up**
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/graph/mn_graph_collapse_weighted_edge.js:69`
-- **Defect**: `mn_graph_coarsen` builds `new BinaryHeap(WeightedEdge.extractNegativeWeight)`. `BinaryHeap` is a min-heap on the score function (`bubbleUp` swaps while `score < parentScore`, `pop` returns `data[0]`), so score `-weight` makes it a max-heap on weight. In the merge branch, `target_edge.weight += b_edge.weight` **increases** the weight, i.e. **decreases** the score, so the element must move toward the root. The code calls only `heap.bubbleDown(heap_index)`, which is a no-op for a decreased score, leaving the element parked below lighter edges.
-- **Failure scenario**: heap contains edges of weight 10 (root) and 3 (a leaf). Collapsing merges 8 into the weight-3 edge, making it weight 11 while it stays at a leaf position. `bubbleDown` finds no smaller child and returns. The next `open_set.pop()` returns the weight-10 edge instead of the weight-11 edge, so `mn_graph_coarsen` no longer collapses heaviest-edge-first — the coarsening order the algorithm is defined by is violated and the resulting partition differs from the specified one.
-- **Fix**: Call the purpose-built `heap.updateElementScore(target_edge)` (it does `bubbleUp` then `bubbleDown` and already handles the not-found case), replacing the manual `indexOf` + `bubbleDown` pair.
-- **Confidence**: Confirmed
-
----
-
-## core/clipboard
-
-### PROC-26 `obtainClipBoard` has an inverted guard and resolves with `undefined` when there is no clipboard
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/clipboard/obtainClipBoard.js:8`
-- **Defect**: The permission check runs only `if (navigator.clipboard === undefined)` — i.e. only when there is no clipboard to permit — and the function then returns `navigator.clipboard` regardless, which in that branch is `undefined`. The condition is backwards: permissions should be verified when a clipboard *is* present, and the absence of `navigator.clipboard` should reject so callers can fall back.
-- **Failure scenario**: a context where `navigator.clipboard` is undefined but `navigator.permissions.query({name:"clipboard-read"})` resolves `"granted"` (Chromium exposes the Permissions API independently of the Async Clipboard API). `obtainClipBoard()` **resolves** with `undefined`; `safeClipboardReadText` then takes its success branch and evaluates `navigator.clipboard.readText()` → `TypeError: Cannot read properties of undefined`. The file-picker fallback — the entire reason `safeClipboardReadText`/`safeClipboardWriteText` exist — is never reached, because it is wired to the rejection handler.
-- **Fix**: Invert to `if (navigator.clipboard === undefined) { throw new Error("Clipboard API unavailable"); }` and perform the permission queries afterwards on the clipboard-present path.
-- **Confidence**: Confirmed (by reading; requires a browser to execute)
-
-### PROC-27 `safeClipboardReadText` fallback never settles when the user cancels the file picker
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/clipboard/safeClipboardReadText.js:29`
-- **Defect**: The fallback returns `new Promise((resolve, reject) => openFile(resolve))`. `resolve` is only reachable from `reader.onload`. Cancelling the dialog fires no `change` event at all; a `change` with no file hits `if (!file) { return; }`; and `reader.onerror` is not wired. `reject` is never called on any path. The hidden `<input>` is also left attached to `document.body`.
-- **Failure scenario**: `await safeClipboardReadText()` in a browser without an Async Clipboard API; the user presses Cancel in the file dialog. The awaiting code hangs forever with no error surfaced.
-- **Fix**: Reject on `reader.onerror` and on the `!file` path, and listen for the `cancel` event on the file input (or a window `focus` fallback) to reject; remove the input element in a `finally`.
-- **Confidence**: Confirmed (by reading; requires a browser to execute)
-
----
-
-## Areas reviewed and found clean
-
-- `core/assert.js` — no correctness defects found.
-- `core/time/current_time_in_seconds.js` — correct ms→s scaling, correct monotonic-source selection.
-- `core/dom/isImageBitmap.js` — correct.
-- `core/process/matcher/*` (the function-style matchers) — all correct.
-- `core/graph/csr/*` — `csr_graph_find_shortest_path` and `csr_graph_build_distance_field` Dijkstra relaxation, lazy-deletion handling and the `out_exit` inheritance chain are correct (a predecessor is always finalised before the vertex that names it, including under zero-weight edges). `CSRGraph` buffer arithmetic, `truncate_adjacency`, `equals` and `hash` all check out.
-- `core/graph/v2/Graph.js` / `NodeContainer.js` — add/remove edge bookkeeping, neighbour reference counting, self-loop handling and the snapshot-based `traverseEdges` are all consistent; `removeNode` correctly avoids mutation-during-iteration.
-- `core/graph/graph_compute_disconnected_clusters.js`, `layout/computeDisconnectedSubGraphs.js` — no double-visits, no missed nodes, multi-edge safe.
-- `core/graph/coloring/colorizeGraphGreedy.js`, `colorizeGraphMCS.js`, `colorizeGraphGreedyWeight.js`, `validateGraphColoring.js` — correct (the greedy comparator is explicit, not a bare `.sort()`).
-- `core/graph/format/graphviz/graphviz_escape_string.js` — escape ordering is correct (backslashes before quotes).
-- `core/graph/metis/native/coarsen/*` — `match_shem` renumbering contract and `create_coarse_graph`'s merge / self-loop-drop / position-reset logic are consistent with each other and with the worst-case sizing.
-- `core/process/filter/*`, `core/process/executor/profile/*`, `core/process/buildPromiseChain.js`, `core/process/delay.js`, `core/process/SimpleLifecycle.js` — no correctness defects found.
-- `WorkerBuilder`'s function-rename regex was suspected of renaming nested `function` declarations; verified it does not (`[^\]]*` spans newlines, so the nested definition is captured verbatim in group 3).
+# Correctness review — `core/process`, `core/graph`, `core/debug`, `core/time`, `core/clipboard`, `core/dom`, `core/assert.js`
+
+Scope reviewed: every non-spec source file under the listed directories.
+Every finding below was reproduced by executing the real module in Node (no mocks) unless marked otherwise.
+
+---
+
+## core/debug
+
+### PROC-1 `anything()` matches nothing and `nothing()` matches everything
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/debug/matchers/IsAnything.js:12`
+- **Defect**: `IsAnything.matches()` returns `false` unconditionally. The matcher whose entire purpose is "accept any value" rejects every value, and `nothing()` (built as `not(anything())`) therefore accepts every value. Both public factories in `matchers.js` are logically inverted.
+- **Failure scenario**: `anything().matches(42)` → `false` (verified). `assert.that(x, 'x', anything())` throws for *every* `x`. Conversely `nothing().matches(42)` → `true` (verified), so `assert.that(x, 'x', nothing())` never triggers — a guard that is supposed to be unreachable silently passes everything.
+- **Fix**: `matches(item, mismatch_description) { return true; }`.
+- **Confidence**: Confirmed
+
+### PROC-2 `Matcher.matches(item)` — the documented single-argument form — throws in AllOf / IsIterableContaining / CombinableMatcher
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/debug/matchers/AllOf.js:25` (also `IsIterableContaining.js:22`, `CombinableMatcher.js:25`)
+- **Defect**: The base class declares `matches(item, mismatch_description = NullDescription.INSTANCE)` and documents the second parameter as optional. Subclass overrides re-declare the parameter *without* the default (default parameter values are not inherited), then dereference it on the mismatch path. `assert.that` calls `matcher.matches(value)` with one argument, so this is the primary in-repo call site.
+- **Failure scenario**: `allOf(isIn([3,7]), not(equalTo(7))).matches(2)` → `TypeError: Cannot read properties of undefined (reading 'appendDescriptionOf')` instead of `false` (verified). `hasItem(1).matches([])` → `TypeError: ... (reading 'appendText')` (verified). Any `assert.that(v, 'v', allOf(...))` on a failing value surfaces a TypeError instead of the intended assertion message.
+- **Fix**: Give every override the same default: `matches(item, mismatch_description = NullDescription.INSTANCE)`.
+- **Confidence**: Confirmed
+
+### PROC-3 `DescribeAs` never performs template substitution
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/debug/matchers/DescribeAs.js:42`
+- **Defect**: Three independent errors in `describeTo`. (a) `String.prototype.matchAll` returns an *iterator*, not an array, so `matches.length` is `undefined` and `for (let i = 0; i < undefined; i++)` never executes. (b) `match.groups[1]` reads a named-group bag that is `undefined` for this un-named-group regex — it would throw if the loop ever ran; it should be `match[1]`. (c) `textStart = match[0].length` should be `match.index + match[0].length`, otherwise the tail slice restarts from the wrong offset.
+- **Failure scenario**: `new DescribeAs("value must be %0 or %1", equalTo(1), ["A","B"]).describeTo(d)` writes the literal `value must be %0 or %1` instead of `value must be "A" or "B"` (verified). Reached in production via `nothing(message)`, which routes through `describeAs`.
+- **Fix**: `const matches = Array.from(this.template.matchAll(RX));`, use `match[1]`, and set `textStart = match.index + match[0].length`.
+- **Confidence**: Confirmed
+
+### PROC-4 `appendValue(undefined)` renders as `"null"`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/debug/BaseDescription.js:39`
+- **Defect**: `if (value == null)` (loose equality) is true for `undefined` as well as `null`, so the dedicated `else if (value === undefined)` branch on the next line is unreachable.
+- **Failure scenario**: `new InMemoryDescriptor().appendValue(undefined).value` → `"null"` (verified). An assertion failure on an `undefined` value reports it as `null`, which is a different bug class for the reader.
+- **Fix**: Use `value === null` on the first branch, or reorder so the `undefined` test comes first.
+- **Confidence**: Confirmed
+
+### PROC-5 `IsIterableContaining` mismatch text describes the collection, not its elements
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/debug/matchers/IsIterableContaining.js:41`
+- **Defect**: The mismatch loop iterates `itemElement` but passes the whole collection `item` to `describeMismatch`. The element variable is never used.
+- **Failure scenario**: `hasItem(9).matches([1,2,3], d)` produces `mismatches were: [was <1,2,3>, was <1,2,3>, was <1,2,3>]` instead of `was 1, was 2, was 3`.
+- **Fix**: `this.#element_matcher.describeMismatch(itemElement, mismatch_description);`
+- **Confidence**: Confirmed
+
+---
+
+## core/process — task & executor
+
+### PROC-6 A task blocked on a FAILED dependency is silently dropped: never fails, never resolves
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/executor/ConcurrentExecutor.js:286`
+- **Defect**: `resolveTasks()`'s `ResolutionType.FAILED` branch splices the task out of `queueUnresolved` and does nothing else — it never sets `task.state` to `FAILED` and never dispatches `task.on.failed`. The task is left in `INITIAL` forever, invisible to the executor.
+- **Failure scenario**: `A = failingTask(...)`, `B.addDependency(A)`, `executor.run(A); executor.run(B)`. Verified result: `A.state === FAILED (3)`, `B.state === INITIAL (0)`, no `on.failed`/`on.completed` dispatch on B, `executor.contains(B) === false`, `queueUnresolved.length === 0`. `await B.promise()` hangs forever. Worse, any task `C` depending on `B` sees `B.state === INITIAL` in `tryResolve` and returns `UNRESOLVED` forever — the whole downstream subgraph is permanently stuck while `executor.on.completed` still fires.
+- **Fix**: In the FAILED branch, mirror `#fail_task`: set `unresolvedTask.state.set(TaskState.FAILED)` and `unresolvedTask.on.failed.send1(<dependency failure reason>)` before/after the splice, then restart the scan (`i = -1; l = queueUnresolved.length;`) because the dispatch can mutate the queue.
+- **Confidence**: Confirmed
+
+### PROC-7 `Task.executeSync()` never updates `Task.state`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/task/Task.js:214`
+- **Defect**: `executeSync` runs the initializer, cycles to completion and fires `on.started`/`on.completed`/`on.failed`, but never assigns `this.state`. The task remains in `TaskState.INITIAL` after a successful synchronous run.
+- **Failure scenario**: `const t = emptyTask(); t.executeSync();` → `t.state.getValue() === 0 (INITIAL)`, not `4 (SUCCEEDED)` (verified). Consequently `Task.join`/`t.promise()` takes the "not finished yet" branch and registers `on.completed.addOne(resolve)` on a signal that already fired — the promise never settles (verified: still `PENDING` after 20 ms). Feeding a sync-executed task as a dependency into a `ConcurrentExecutor` also blocks its dependents forever, because `tryResolve` reads `INITIAL` → `UNRESOLVED`.
+- **Fix**: Set `this.state.set(TaskState.RUNNING)` before the cycle loop and `TaskState.SUCCEEDED` / `TaskState.FAILED` alongside the corresponding signal dispatch.
+- **Confidence**: Confirmed
+
+### PROC-8 `ignoreFailureTask` does not ignore a *thrown* failure
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/task/util/ignoreFailureTask.js:38`
+- **Defect**: The wrapper only converts an explicit `TaskSignal.EndFailure` return into `EndSuccess`. An exception thrown out of `task.cycle()` propagates through the wrapper unchanged, and `ConcurrentExecutor.#executeTimeSlice` treats a thrown exception as task failure (`#fail_task`) — so the wrapper fails too. Throwing is a first-class failure mode in this codebase: `failingTask(e)` (the repo's own canonical failing task) fails exclusively by throwing, and both `promiseTask` and `futureTask` `throw error` on rejection.
+- **Failure scenario**: `ignoreFailureTask(failingTask(new Error("boom")))` — the wrapper propagates `Error: boom` (verified) instead of resolving in success as its JSDoc promises. Under `ConcurrentExecutor` the wrapper ends in `FAILED`.
+- **Fix**: Wrap the `task.cycle()` call in try/catch and return `TaskSignal.EndSuccess` on a caught exception (matching the existing treatment of an initializer throw).
+- **Confidence**: Confirmed
+
+### PROC-9 `RemainingTimeEstimator.estimate` averages over unfilled sample slots
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/task/RemainingTimeEstimator.js:39`
+- **Defect**: `rates` is a zero-filled `Float32Array(sampleCount)`; `estimate` always divides the sum by the full `sampleCount` rather than by the number of `update()` calls actually recorded. The unwritten zeros drag the average rate down by a factor of `sampleCount / filled`.
+- **Failure scenario**: `const e = new RemainingTimeEstimator(10); e.update(1000, 0.5); e.estimate(0.5)` → `10000` (verified) when the correct remaining time is `1000`. A 10× over-estimate persists until the ring buffer is fully populated — i.e. for the whole early phase of every task, which is exactly when an ETA is displayed.
+- **Fix**: Track a `filled` counter (`Math.min(filled + 1, sampleCount)`) in `update` and divide by it in `estimate`; return `Infinity` when `filled === 0`.
+- **Confidence**: Confirmed
+
+---
+
+## core/process — undo (`ActionProcessor`)
+
+### PROC-10 undo → do → redo crashes: the future branch of history is truncated but its marks are not
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/undo/ActionProcessor.js:487`
+- **Defect**: `__unsafe_do` discards the redo branch with `history.crop(0, this.cursor)` but leaves `this.marks` untouched (there is a `// TODO clear future marks` on line 489). Marks whose `index` now exceeds `history.length` become dangling, and `__unsafe_redo` uses those indices as a loop bound.
+- **Failure scenario** (verified end-to-end): `await ap.do(A); await ap.do(B); await ap.mark("m1"); await ap.undo(); await ap.do(C);` leaves `history.length === 1`, `cursor === 1`, `marks === [index 2]`. The next `await ap.redo()` computes `mark = 2`, reads `history.get(1) === undefined` and throws `TypeError: Cannot read properties of undefined (reading 'apply')`. This is the ordinary editor sequence "undo, then do something else, then press redo".
+- **Fix**: In `__unsafe_do`, before/alongside the crop, splice off every mark with `index > this.cursor` and dispatch `onMarkRemoved` for each.
+- **Confidence**: Confirmed
+
+### PROC-11 `doMany` with a failing action never settles and permanently deadlocks the processor
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/undo/ActionProcessor.js:439`
+- **Defect**: `new Promise(async (resolve, reject) => { ... await this.__unsafe_do(action) ... resolve(); })` — the classic async-executor antipattern. When `__unsafe_do` rejects, the rejection escapes into the async executor function's own (discarded) promise; `reject` is never called, so the constructed promise `p` stays pending forever. `p` is then stored in `this.__last_promise`, and every subsequent `do`/`undo`/`redo`/`mark`/`navigateTo` starts with `await this.__barrier()` on that never-settling promise.
+- **Failure scenario** (verified): `ap.doMany([goodAction, throwingAction])` — the returned promise is still `PENDING` after 60 ms and an `unhandledRejection` is emitted (fatal in Node ≥ 15 / reported by Jest). A following `await ap.do(anotherAction)` is also still `PENDING` and `history.length` stays at 1: the ActionProcessor is bricked for the remainder of the session.
+- **Fix**: Drop the wrapper — make the body a plain `async` helper (`const p = (async () => { for (...) await this.__unsafe_do(actions[i]); })()`), matching how `do`/`undo`/`redo` already build `p`.
+- **Confidence**: Confirmed
+
+### PROC-12 `cleanupHistory` compares a mark *count* against a *byte* limit — neither history limit is ever enforced
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/undo/ActionProcessor.js:204`
+- **Defect**: `let lastMark = min2(marks.length, this.historyMemoryLimit) - 1;` mixes a mark count with a byte budget (default 268435456), so `lastMark` is always `marks.length - 1` and the subsequent `if (lastMark + 1 < marks.length)` is always false. `historyMarkLimit` is never consulted at all. The memory branch is equally dead: it decrements while `marks[lastMark].memoryUsage > this.historyMemoryUsage`, but a mark's recorded usage is a *past* snapshot and therefore never exceeds the current total. Separately, if the guard ever did fire, `const marksToDrop = lastMark - this.historyMarkLimit` is negative for any realistic history and `marks[marksToDrop]` would be `undefined` → `TypeError` on `.index`.
+- **Failure scenario** (verified): with `ap.historyMarkLimit = 2`, doing 6 actions each followed by a mark leaves `marks.length === 6` and `history.length === 6` — nothing dropped. With `ap.historyMemoryLimit = 3000` and 10 actions of 1000 bytes each, `historyMemoryUsage === 10000` and `history.length === 10`. Both documented caps are inert, so undo history grows without bound for the process lifetime.
+- **Fix**: Compute the mark cut-off from `historyMarkLimit` (`const marksToDrop = marks.length - this.historyMarkLimit`) and, separately, walk marks from the oldest while `historyMemoryUsage - marks[i].memoryUsage > historyMemoryLimit` for the byte cap. Guard `marksToDrop > 0` before indexing.
+- **Confidence**: Confirmed
+
+### PROC-13 `dropHistory` destroys the boundary mark that should survive at index 0
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/undo/ActionProcessor.js:134`
+- **Defect**: The cut-off scan uses `marks[i].index <= recordsToDrop`. Records `[0, recordsToDrop)` are removed, so a mark at exactly `index === recordsToDrop` still points at a surviving record (it becomes index 0) and must be kept. The condition should be `<`. `cleanupHistory`'s own `assert.equal(newFirstMark.index, 0, ...)` on line 224 documents that this mark is expected to survive — the two sites contradict each other.
+- **Failure scenario**: history `[A,B,C,D]`, one mark at `index 2`. `dropHistory(2)` leaves history `[C,D]` but removes the mark, so the caller loses the only navigable point in the surviving history.
+- **Fix**: `for (; i < markCount && marks[i].index < recordsToDrop; i++)`.
+- **Confidence**: Confirmed (by reading; the runtime check is blocked by PROC-14's arity issue in dev builds)
+
+### PROC-14 `onMarkAdded` and `onMarkRemoved` emit different payload types
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/undo/ActionProcessor.js:196` and `:154`
+- **Defect**: `mark()` dispatches `this.onMarkAdded.send1(description)` (the raw description, verified) while `dropHistory` dispatches `Mark` instances (`dropped_marks.forEach(this.onMarkRemoved.send1, ...)`) and `mark()`'s own eviction path does `this.onMarkRemoved.send1(mark)`. Both signals are typed `Signal<M>` (description) in the field JSDoc. Additionally, `Array.prototype.forEach` invokes the callback with `(element, index, array)`, so `send1` is called with three arguments.
+- **Failure scenario**: A UI keeping an undo-stack list keyed by description adds `"m1"` on `onMarkAdded` but receives `Mark { index: 0, description: "m1" }` on `onMarkRemoved`; the lookup misses and the entry is never removed from the list.
+- **Fix**: Dispatch `mark.description` from both removal sites, and replace the `forEach(send1, signal)` with an explicit loop so exactly one argument is passed.
+- **Confidence**: Confirmed
+
+---
+
+## core/process — other
+
+### PROC-15 `Future` can reach a terminal state twice; a rejected future can flip to resolved
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/Future.js:80`
+- **Defect**: `__handleResolution` and `__handleRejection` set `state` unconditionally with no already-settled guard. The `resolve`/`reject` callbacks handed to the resolver can therefore both fire, and the last one wins — violating the settle-once contract that `Future` advertises by mirroring the Promise API (`then`/`catch`, `@extends Promise<T>`).
+- **Failure scenario** (verified): `const f = new Future((res, rej) => { rej(new Error("nope")); res(42); }); f.resolve();` → `f.state === RESOLVED (2)`, and `f.then(onOk, onErr)` invokes `onOk(42)`. A real Promise stays rejected and runs `onErr`. Downstream, `futureTask` polls `resolved`/`rejected` flags set by exactly this `then` registration, so a resolver that rejects-then-resolves turns a failed task into a successful one.
+- **Fix**: Early-return from both handlers unless `this.state === FutureStates.PENDING`.
+- **Confidence**: Confirmed
+
+### PROC-16 `WatchDog.bark` disarms a watchdog that its own action re-armed
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/WatchDog.js:52`
+- **Defect**: `bark()` runs `this.action.call(...)` *first* and only then sets `this.timeoutId = -1`. During the action `isActive()` still reports `true`, so a re-arm from inside the action is either ignored (`start()` no-ops) or scheduled and then orphaned (`kick()` installs a fresh timer whose id is immediately overwritten with `-1`).
+- **Failure scenario** (verified): a watchdog whose action calls `wd.start()` to re-arm itself — the canonical "handle the stall, then keep watching" pattern. After the first bark `isActive() === false` and no second bark ever occurs: the watchdog is silently dead. With `kick()` instead, a timer is left running that `stop()` can no longer cancel (`isActive()` is false), so the action fires again unexpectedly and the `kick()` inside it throws `WatchDog is not active`.
+- **Fix**: Set `this.timeoutId = -1` *before* invoking the action.
+- **Confidence**: Confirmed
+
+### PROC-17 `.finally()` chains create unhandled promise rejections
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/PromiseWatcher.js:45` and `H:/git/moh/app/src/mir-engine/meep/src/core/process/worker/OnDemandWorkerManager.js:135`
+- **Defect**: Both sites call `promise.finally(cb)` and discard the returned promise. `p.finally(cb)` produces a *new* promise that adopts `p`'s rejection; because nothing attaches a handler to it, a rejecting `p` always produces an unhandled rejection — even when the original caller handled `p` correctly.
+- **Failure scenario**: `watcher.add(somePromise)` where `somePromise` later rejects → `unhandledrejection` in the browser; in Node/Jest (Node ≥ 15 default) the process aborts. For `OnDemandWorkerManager.request`, `WorkerProxy.__failAllPending` rejects every in-flight request on worker error, so a single failing worker script turns each queued request into an unhandled rejection on top of the (correctly handled) rejection the caller sees.
+- **Fix**: Suppress the derived promise: `promise.then(cb, cb)`, or `promise.finally(cb).catch(() => {})`.
+- **Confidence**: Confirmed
+
+### PROC-18 `CompositeProcess.finalize()` on a running composite leaves children in `Stopped`, not `Finalized`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/CompositeProcess.js:27`
+- **Defect**: `finalize()` finalizes children first, then calls `super.finalize()`. `BaseProcess.finalize` sees the composite still in `Running` and calls `this.shutdown()`, which is the *overridden* `CompositeProcess.shutdown` — so every child is shut down a second time, and `BaseProcess.shutdown` unconditionally writes `ProcessState.Stopped` over the child's `Finalized` state.
+- **Failure scenario** (verified): a `CompositeProcess([a, b])` taken through `initialize(); startup(); finalize()` ends with composite = `finalized` but `a` and `b` = `stopped`. Any subsequent lifecycle check that requires children to be `Finalized`, or a second `finalize()`, sees corrupt state; children that release resources in `finalize` are also asked to shut down after they have already torn themselves down.
+- **Failure path**: `finalize()` → children `Finalized` → `super.finalize()` sees `Running` → `this.shutdown()` → `children.forEach(c => c.shutdown())` → children forced back to `Stopped`.
+- **Fix**: Have `CompositeProcess.finalize` shut itself down first (`if (this.__state.getValue() === ProcessState.Running) super.shutdown();`) before finalizing children, or make `BaseProcess.finalize` call `BaseProcess.prototype.shutdown` on itself only.
+- **Confidence**: Confirmed
+
+---
+
+## core/process — worker
+
+### PROC-19 `extractTransferables(null)` throws
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/worker/extractTransferables.js:24`
+- **Defect**: `typeof null === "object"`, so a `null` value falls past the "not an object, skip" branch, fails `instanceof ArrayBuffer`, and reaches `value.buffer` → TypeError. The inline duplicate of this exact function generated inside `WorkerBuilder.build()` (line 121) *does* have the `obj === null` guard, which shows the omission is unintentional.
+- **Failure scenario** (verified): `extractTransferables({ a: null }, [])` → `TypeError: Cannot read properties of null (reading 'buffer')`. Any worker payload containing a null field — extremely common in serialized game objects — crashes before the message is ever posted. The spec file covers `{}`, buffers, typed arrays and nesting, but never a null.
+- **Fix**: Change the first branch to `if (value === null || typeof value !== "object")`.
+- **Confidence**: Confirmed
+
+### PROC-20 A failed `postMessage` drops the request without ever rejecting its promise
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/worker/WorkerProxy.js:154`
+- **Defect**: When `trySendMessage` returns `false` (it swallows the `postMessage` exception and logs it), the request is removed from the pending queue but neither `resolve` nor `reject` is invoked. The promise handed to the caller can never settle: it is no longer in the queue, so `__handleMessage` and `__failAllPending` will never find it either.
+- **Failure scenario**: `workerProxy.someMethod(objectContainingAFunctionOrDomNode)` — `postMessage` throws `DataCloneError`, the console shows `failed to send message:`, and `await` on the returned promise hangs for the lifetime of the page. PROC-21 makes this reachable in ordinary use, since the `toJSON` sanitisation that was meant to prevent non-cloneable payloads never runs.
+- **Fix**: Reject the promise on send failure: `reject(new Error(...))` in place of (or alongside) the `array_remove_first`.
+- **Confidence**: Confirmed
+
+### PROC-21 `needsSerialization` compares a function against the string `"function"` — `toJSON` is never applied
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/process/worker/WorkerProxy.js:40`
+- **Defect**: `value.toJSON === "function"` should be `typeof value.toJSON === "function"`. As written the branch is unreachable, so `$submitRequest` always posts the raw argument and the documented `toJSON` sanitisation path is dead. (`hasOwnProperty('toJSON')` additionally excludes the normal case where `toJSON` lives on the class prototype.)
+- **Failure scenario** (verified with the exact predicate): `needsSerialization({ toJSON() { return { plain: 1 }; } })` → `false`. Passing any engine object that relies on `toJSON` to strip non-cloneable members (signals, DOM handles, functions) to a worker method posts the raw object, which `postMessage` rejects with `DataCloneError` → the request silently disappears per PROC-20.
+- **Fix**: `if (typeof value.toJSON === "function") { return true; }` (drop the `hasOwnProperty` gate so prototype-defined `toJSON` is honoured).
+- **Confidence**: Confirmed
+
+---
+
+## core/graph
+
+### PROC-22 `colorizeGraph` builds an asymmetric adjacency matrix from directed edges and returns invalid colourings
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/graph/coloring/colorizeGraph.js:38`
+- **Defect**: `graphToMatrix` writes `data[i][other] = 1` only when `edge.validateTransition(node, otherNode)` succeeds. For a `Forward` edge `P → Q` this sets `data[P][Q] = 1` but leaves `data[Q][P] = 0`. Graph colouring is an inherently undirected constraint, and the downstream `colorizing`/`updateNN` conflict elimination reads the matrix by row only, so a conflict recorded in just one direction is missed whenever the *other* endpoint is coloured first.
+- **Failure scenario** (verified): nodes `X, P, Q, R` with `Forward` edges `P→X`, `X→Q`, `X→R`. `colorizeGraph` returns `[1, 1, 2, 2]` — `X` and `P` are adjacent yet share colour 1. `validateGraphColoring(colors, graph)` (which uses undirected `getNeighbours`) returns `false` on the library's own output.
+- **Fix**: Make the matrix symmetric: set both `data[i * V + otherIdx]` and `data[otherIdx * V + i]` for every attached edge, and drop the `validateTransition` gate (or keep it only for genuinely directed colouring variants, which this algorithm is not).
+- **Confidence**: Confirmed
+
+### PROC-23 `convert_graph_to_dot_string` silently omits every `Backward` edge
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/graph/convert_graph_to_dot_string.js:59`
+- **Defect**: The emission guard is `(direction === Forward || direction === Undirected) && edge.first === node`. `EdgeDirectionType.Backward` satisfies neither disjunct, so a backward edge is skipped when visiting `first` and also skipped when visiting `second` (because `edge.first !== node` there). It is never written out.
+- **Failure scenario** (verified): a graph with nodes `A`, `B` and `graph.createEdge("A", "B", EdgeDirectionType.Backward)` produces DOT containing both node declarations and **zero** `->` lines. The rendered diagram shows two isolated nodes; the edge is invisible.
+- **Fix**: Add a `Backward` case that emits the reversed arrow `nodeId(secondIndex) -> nodeId(i)` once (guarded on `edge.first === node` so it is emitted exactly once).
+- **Confidence**: Confirmed
+
+### PROC-24 Laplacian is inconsistent on multigraphs: degree counts parallel edges, adjacency saturates at 1
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/graph/graph_compute_adjacency_matrix.js:23` (surfaces in `graph_compute_laplacian_matrix.js:22`)
+- **Defect**: `graph_compute_adjacency_matrix` writes a literal `1` per edge, so parallel edges collapse to a single 1. `graph_compute_degree_matrix` uses `graph.getNodeDegree`, which returns `NodeContainer.getEdgeCount()` and *does* count each parallel edge. `L = D - A` therefore has rows that don't sum to zero — the defining property of a graph Laplacian. Multi-edges are a first-class supported state of `Graph` (`NodeContainer.__neighbors` is explicitly documented as "number of edges to that node").
+- **Failure scenario** (verified): nodes `A`, `B` joined by two parallel edges. `graph_compute_laplacian_matrix` yields `[[2, -1], [-1, 2]]`; row sums are `1`, not `0`. The correct Laplacian is `[[2, -2], [-2, 2]]`. Any spectral use (Fiedler vector, spectral clustering, connectivity count via the zero-eigenvalue multiplicity) reads the wrong matrix.
+- **Fix**: Accumulate instead of assigning in `graph_compute_adjacency_matrix` — `result.setCellValue(a, b, result.getCellValue(a, b) + 1)` for both `(a,b)` and `(b,a)` — and document that the matrix must be zero-filled by the caller (the JSDoc already states it does not zero-fill).
+- **Confidence**: Confirmed
+
+### PROC-25 Heap invariant broken after merging edge weights: `bubbleDown` used where the element must bubble **up**
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/graph/mn_graph_collapse_weighted_edge.js:69`
+- **Defect**: `mn_graph_coarsen` builds `new BinaryHeap(WeightedEdge.extractNegativeWeight)`. `BinaryHeap` is a min-heap on the score function (`bubbleUp` swaps while `score < parentScore`, `pop` returns `data[0]`), so score `-weight` makes it a max-heap on weight. In the merge branch, `target_edge.weight += b_edge.weight` **increases** the weight, i.e. **decreases** the score, so the element must move toward the root. The code calls only `heap.bubbleDown(heap_index)`, which is a no-op for a decreased score, leaving the element parked below lighter edges.
+- **Failure scenario**: heap contains edges of weight 10 (root) and 3 (a leaf). Collapsing merges 8 into the weight-3 edge, making it weight 11 while it stays at a leaf position. `bubbleDown` finds no smaller child and returns. The next `open_set.pop()` returns the weight-10 edge instead of the weight-11 edge, so `mn_graph_coarsen` no longer collapses heaviest-edge-first — the coarsening order the algorithm is defined by is violated and the resulting partition differs from the specified one.
+- **Fix**: Call the purpose-built `heap.updateElementScore(target_edge)` (it does `bubbleUp` then `bubbleDown` and already handles the not-found case), replacing the manual `indexOf` + `bubbleDown` pair.
+- **Confidence**: Confirmed
+
+---
+
+## core/clipboard
+
+### PROC-26 `obtainClipBoard` has an inverted guard and resolves with `undefined` when there is no clipboard
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/clipboard/obtainClipBoard.js:8`
+- **Defect**: The permission check runs only `if (navigator.clipboard === undefined)` — i.e. only when there is no clipboard to permit — and the function then returns `navigator.clipboard` regardless, which in that branch is `undefined`. The condition is backwards: permissions should be verified when a clipboard *is* present, and the absence of `navigator.clipboard` should reject so callers can fall back.
+- **Failure scenario**: a context where `navigator.clipboard` is undefined but `navigator.permissions.query({name:"clipboard-read"})` resolves `"granted"` (Chromium exposes the Permissions API independently of the Async Clipboard API). `obtainClipBoard()` **resolves** with `undefined`; `safeClipboardReadText` then takes its success branch and evaluates `navigator.clipboard.readText()` → `TypeError: Cannot read properties of undefined`. The file-picker fallback — the entire reason `safeClipboardReadText`/`safeClipboardWriteText` exist — is never reached, because it is wired to the rejection handler.
+- **Fix**: Invert to `if (navigator.clipboard === undefined) { throw new Error("Clipboard API unavailable"); }` and perform the permission queries afterwards on the clipboard-present path.
+- **Confidence**: Confirmed (by reading; requires a browser to execute)
+
+### PROC-27 `safeClipboardReadText` fallback never settles when the user cancels the file picker
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/clipboard/safeClipboardReadText.js:29`
+- **Defect**: The fallback returns `new Promise((resolve, reject) => openFile(resolve))`. `resolve` is only reachable from `reader.onload`. Cancelling the dialog fires no `change` event at all; a `change` with no file hits `if (!file) { return; }`; and `reader.onerror` is not wired. `reject` is never called on any path. The hidden `<input>` is also left attached to `document.body`.
+- **Failure scenario**: `await safeClipboardReadText()` in a browser without an Async Clipboard API; the user presses Cancel in the file dialog. The awaiting code hangs forever with no error surfaced.
+- **Fix**: Reject on `reader.onerror` and on the `!file` path, and listen for the `cancel` event on the file input (or a window `focus` fallback) to reject; remove the input element in a `finally`.
+- **Confidence**: Confirmed (by reading; requires a browser to execute)
+
+---
+
+## Areas reviewed and found clean
+
+- `core/assert.js` — no correctness defects found.
+- `core/time/current_time_in_seconds.js` — correct ms→s scaling, correct monotonic-source selection.
+- `core/dom/isImageBitmap.js` — correct.
+- `core/process/matcher/*` (the function-style matchers) — all correct.
+- `core/graph/csr/*` — `csr_graph_find_shortest_path` and `csr_graph_build_distance_field` Dijkstra relaxation, lazy-deletion handling and the `out_exit` inheritance chain are correct (a predecessor is always finalised before the vertex that names it, including under zero-weight edges). `CSRGraph` buffer arithmetic, `truncate_adjacency`, `equals` and `hash` all check out.
+- `core/graph/v2/Graph.js` / `NodeContainer.js` — add/remove edge bookkeeping, neighbour reference counting, self-loop handling and the snapshot-based `traverseEdges` are all consistent; `removeNode` correctly avoids mutation-during-iteration.
+- `core/graph/graph_compute_disconnected_clusters.js`, `layout/computeDisconnectedSubGraphs.js` — no double-visits, no missed nodes, multi-edge safe.
+- `core/graph/coloring/colorizeGraphGreedy.js`, `colorizeGraphMCS.js`, `colorizeGraphGreedyWeight.js`, `validateGraphColoring.js` — correct (the greedy comparator is explicit, not a bare `.sort()`).
+- `core/graph/format/graphviz/graphviz_escape_string.js` — escape ordering is correct (backslashes before quotes).
+- `core/graph/metis/native/coarsen/*` — `match_shem` renumbering contract and `create_coarse_graph`'s merge / self-loop-drop / position-reset logic are consistent with each other and with the worst-case sizing.
+- `core/process/filter/*`, `core/process/executor/profile/*`, `core/process/buildPromiseChain.js`, `core/process/delay.js`, `core/process/SimpleLifecycle.js` — no correctness defects found.
+- `WorkerBuilder`'s function-rename regex was suspected of renaming nested `function` declarations; verified it does not (`[^\]]*` spans newlines, so the nested definition is captured verbatim in group 3).