@woosh/meep-engine 2.168.1 → 2.169.1

package/src/REVIEW_2026_08_06/core-process.md

@@ -0,0 +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).

package/src/REVIEW_2026_08_06/core-science.md

@@ -0,0 +1,223 @@
+# Correctness review — `core/science` + `core/color`
+
+Scope: every non-spec source file under
+`meep/src/core/science/` (40 files) and `meep/src/core/color/` (47 files).
+`editor/`, `prototype*.js`, `*.spec.js` (evidence only) and `.d.ts` excluded.
+
+All findings below were reproduced by executing the actual modules under node
+(`type: module`, direct file-URL imports). Numbers quoted are measured, not derived.
+
+---
+
+## Verified-correct (no findings)
+
+Checked against the cited standard/reference and found exact:
+
+* **`science/units`** — all 7 base + 19 derived SI exponent vectors match the SI Brochure
+  (F, H, Ω, S, Wb, T, V, W, Pa, J, N, C, Hz, Bq, Gy, Sv, lm, lx, kat all correct).
+  `UnitMatrix` composition/inverse/power algebra correct and alias-safe.
+  `magnitude_prefix_index` verified exact at every one of the 21 decade boundaries
+  (`Math.log10` returns exact integers for all of 1e-30…1e30, so no off-by-one).
+  `unit_matrix_to_string` decomposition terminates and produces the documented strings;
+  `compute_scalar_power` correctly rejects fractional powers (`m/s` does not render as `Gy^0.5`).
+* **`sRGB_to_linear` / `linear_to_sRGB`** — threshold 0.04045 / 0.0031308, `1/12.92 = 0.0773993808`,
+  `1/1.055 = 0.9478672986`, `0.055/1.055 = 0.0521327014`, exponent `1/2.4 = 0.4166666666666667`.
+  All correct to ≥1e-10 relative.
+* **`rgb_to_xyz` / `xyz_to_rgb`** — exact sRGB↔XYZ D65 matrices; measured `rgb(1,1,1) → XYZ
+  (0.950456, 1.000000, 1.089058)` and an exact round trip.
+* **`xyz_cmf_tabulated` × `D65_spd_tabulated`** integrated over 360–830 nm gives
+  chromaticity **xy = (0.31273, 0.32902)** vs the standard D65 (0.31272, 0.32903) — both tables
+  are correct and correctly indexed/interpolated. `D65_spd_tabulated(560) === 100` exactly.
+* **`xyz_cmf_wyman`** — all 7 lobe amplitudes/centres/σL/σR match Wyman–Sloan–Shirley 2013 exactly;
+  integrated white point xy = (0.31264, 0.32923).
+* **`planckian_radiance`** — `c2 = 1.438776877e-2 m·K` matches CODATA; the `exponent > 80`
+  early-out discards at most ~1e-26 of the peak, so it is numerically free.
+* **`xyz_to_hpe`** — exact Hunt-Pointer-Estévez (D65-normalised) matrix.
+* **`tonemap_aces`** — input/output matrices and the RRT+ODT rational fit match Stephen Hill's
+  `ACES.hlsl` exactly; the fit denominator has negative discriminant so there is no pole.
+* **`oklab/*`** — `linear_srgb_to_oklab`, `oklab_to_linear_srgb`, `toe`/`toe_inv`,
+  `compute_max_saturation` (all three coefficient sets + Halley step), `find_cusp`,
+  `find_gamut_intersection`, `linear_srgb_to_okhsv`, `okhsv_to_linear_srgb`,
+  `xyz_to_oklab`, `oklab_to_xyz` — all match Björn Ottosson's reference term for term.
+* **`YCbCr`** — Rec.709 full-range coefficients verified algebraically
+  (0.5/(1−Kb) = 0.53891, 0.5/(1−Kr) = 0.635 and their inverses 1.5748 / 1.8556 / 0.1873 / 0.4681).
+* **`Color.setHSL`** — matches the Wikipedia `f(n)` formulation bit-for-bit on 6 test hues.
+* **`Color.setHCL` / `setHSI`** — match the Wikipedia luma-chroma-hue and HSI formulations
+  (aside from SCI-6 below).
+* **`color_lerp`** — shortest-arc hue wrap `((h1-h0)%1 + 1.5)%1 - 0.5` is correct in both
+  directions; alpha is interpolated.
+* `rgb_to_luminance` (Rec.709), `YCoCg`, `rgb2uint24`, `int2rgb`, `hex/*`, `rgb_to_rgbe9995`,
+  `rgbe9995_to_rgb`, `sRGB_cmf`, `D65_spd_analytical` — no defects found.
+
+---
+
+## Findings
+
+### SCI-1 `color_darken` / `color_lighten` / `color_saturate` / `color_desaturate` silently drop the alpha channel
+- **Severity**: MAJOR
+- **File**:
+  `H:/git/moh/app/src/mir-engine/meep/src/core/color/operations/color_darken.js:24-32`,
+  `.../color_lighten.js:24-32`,
+  `.../color_saturate.js:24-32`,
+  `.../color_desaturate.js:24-32`
+- **Defect**: each function builds `const r = new Color();` (whose constructor default is `a = 1`)
+  and then writes only R, G, B into it via `okhsv_to_linear_srgb(r, ...hsv)`. The input's alpha is
+  never copied, so every returned colour is fully opaque.
+- **Failure scenario**:
+  `color_darken(new Color(1, 0, 0, 0.25), 0.5).a` → **produced `1`**, expected `0.25`.
+  Measured identically for `color_lighten`, `color_saturate`, `color_desaturate`.
+  The reference for "expected" is this module family's own convention: the sibling
+  `color_lerp.js:44` does `r.a = lerp(color_0.a, color_1.a, _t)` and `color_lerp.spec.js:86`
+  asserts it ("alpha is interpolated linearly"). It is also self-inconsistent: the
+  `amount === 0` fast path (`color_darken.js:19-22`) returns `input` itself, so
+  `color_darken(c, 0).a === 0.25` while `color_darken(c, 1e-9).a === 1` — a discontinuity in
+  alpha at `amount → 0` that cannot be intentional.
+- **Fix**: add `r.a = input.a;` before the `return r;` in all four functions.
+- **Confidence**: Confirmed
+
+---
+
+### SCI-2 `Color.prototype.parse` writes alpha outside `set()`, suppressing / corrupting the `onChanged` signal
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/Color.js:666-676`
+- **Defect**: `parse()` assigns `this.a = c[3]` directly and only afterwards calls
+  `setRGB(...)`, which forwards `this.a` (already the *new* value) into `set()`. `set()`
+  therefore (a) sees `_a === a` and can take the "no change" early-out, and (b) when it does
+  fire, reports the new alpha as the old alpha in the `send8(r,g,b,a,_r,_g,_b,_a)` payload.
+- **Failure scenario**: with a live listener attached (this is not hypothetical —
+  `engine/graphics/ecs/light/binding/LightBinding.js:56` and
+  `engine/graphics/ecs/decal/v2/FPDecalSystem.js:180` both subscribe to `color.onChanged`,
+  and `Light.js:105`, `Decal.js:74`, `TubePathStyle.js:180` all call `color.parse(...)`):
+
+  1. Alpha-only change is lost entirely.
+     ```js
+     const c = Color.parse('rgba(0,0,0,1)');
+     c.onChanged.add(() => fired++);
+     c.parse('rgba(0,0,0,0.5)');
+     ```
+     → `c.a === 0.5` (state did change) but **`fired === 0`**; expected `fired === 1`.
+     The bound decal/light is never rebuilt and keeps rendering at the old opacity.
+  2. Old-value payload is wrong even when RGB does change.
+     `new Color(0,0,0,1).parse('#FF000080')` fires
+     `onChanged(1, 0, 0, 0.50196, 0, 0, 0, **0.50196**)`; the 8th argument (previous alpha)
+     should be `1`, not `0.50196`.
+- **Fix**: don't touch `this.a` directly; compute the alpha locally and issue one call —
+  `const a = typeof c[3] === 'number' ? c[3] : 1; this.set(c[0]/255, c[1]/255, c[2]/255, a);`
+- **Confidence**: Confirmed
+
+---
+
+### SCI-3 `rgb_to_kelvin` collapses the whole 1000–2000 K range to 1000 K
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/kelvin/rgb_to_kelvin.js:43-71`
+- **Defect**: the bisection solves only on the blue/red ratio `b / r`. In the forward model
+  (`kelvin_to_rgb`) blue is identically `0` for every `t <= 20` (i.e. T ≤ 2000 K) and red is
+  pinned to `1` below 6500 K, so `b/r === 0` over the entire lower fifth of the supported range.
+  The objective is flat, the bisection always takes the `br >= expected` branch, and the search
+  walks the upper bound all the way down to `minTemperature`. The green channel, which *does*
+  vary monotonically there (0.2293 at 1000 K → 0.4195 at 1500 K → 0.5441 at 2000 K), is never read.
+- **Failure scenario** (round-tripping this module's own forward function, the only defensible
+  reference for an inverse):
+  | input T | `kelvin_to_rgb` output | `rgb_to_kelvin` result | expected |
+  |---|---|---|---|
+  | 1500 K | `[1, 0.419469, 0]` | **1000** | ≈1500 (−33.3 %) |
+  | 1900 K | `[1, 0.522401, 0]` | **1000** | ≈1900 (−47.4 %) |
+  | 2000 K | `[1, 0.544074, 0]` | **1000** | ≈2000 (−50.0 %) |
+
+  Also against the vendian.org black-body table the file's sibling spec cites:
+  `rgb_to_kelvin(Color.parse('#ff4500'))` (the table's 1100 K entry) → **1000**, expected 1100.
+  Everything at 3000 K and above round-trips exactly, so this is specifically the b === 0 band.
+  `rgb_to_kelvin.spec.js` does not catch it: its only low-temperature case is the 1000 K entry.
+- **Fix**: when the target `b` is 0 (or, more uniformly, always) bisect on a residual that
+  includes green — e.g. minimise `(r_t − r)² + (g_t − g)² + (b_t − b)²` over the same bracket, or
+  bisect on `g / r` whenever `b === 0`. `g/r` is strictly monotonic over 1000–6500 K, so the
+  existing bisection structure works unchanged.
+- **Confidence**: Confirmed
+
+---
+
+### SCI-4 `kelvin_to_rgb` blue cut-off is at t ≤ 20 instead of the cited fit's t ≤ 19, zeroing blue over 1900–2000 K
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/kelvin/kelvin_to_rgb.js:23`
+- **Defect**: `const b = t <= 20 ? 0 : clamp01(...)`. Every other constant in this file is an
+  exact /255 transcription of the Bartlett fit at the cited
+  `https://www.zombieprototypes.com/?p=210` (verified: `-254.76935184120902/255 = -0.9990954974165059`,
+  `0.8274096064007395/255 = 0.0032447435545127036`, `115.67994401066147/255 = 0.453646839257496`),
+  but that source gates the blue lobe at `t <= 19`, not `t <= 20`. The extra decade of clamping
+  both suppresses real signal and enlarges the step where the lobe switches on.
+- **Failure scenario**: `kelvin_to_rgb(out, 0, 2000)` → `out[2] = 0.000000`; the cited fit gives
+  `(-254.76935 + 0.82741·10 + 115.67994·ln 10)/255 = 0.077912` (19.9/255). The vendian.org
+  black-body table that `kelvin_to_rgb.spec.js:20` cites as the fit's source data lists 2000 K as
+  `#ff8d0b`, i.e. blue = 11/255 = 0.0431 — also non-zero.
+  The visible consequence is a hard step from a 1 K input change:
+  `T = 2000 → b = 0.000000`, `T = 2001 → b = 0.078398`, a 20/255 discontinuity in the middle of any
+  colour-temperature ramp. (The file already blends the 6500/6700 K regime boundary specifically
+  "to avoid discontinuity", so continuity is an intended property here.)
+- **Fix**: change the guard to `t <= 19` to match the cited fit; or, for full continuity, clamp at
+  the fit's own zero crossing (`t ≈ 18.51`, i.e. `T ≈ 1851 K`) so the lobe starts from 0.
+- **Confidence**: Confirmed
+
+---
+
+### SCI-5 `rgb2uint32` returns a *signed* int32 — negative for every colour with red ≥ 128
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/rgb2uint32.js:17`
+  (surfaced via `Color.toUint32()`, `Color.js:489-491`)
+- **Defect**: `return (partial << 8) | (_a & 0xFF);` — `<<` coerces to int32, so as soon as the red
+  byte reaches 0x80 the shifted value sets the sign bit and the expression evaluates negative.
+  The JSDoc and the function name both promise a uint32, and the two sibling packers in the same
+  package do force unsignedness (`YCbCr_to_rgb_uint24.js:24` and `rgb_to_rgbe9995.js:57` both end
+  in `>>> 0`).
+- **Failure scenario**:
+  `new Color(1, 0, 0, 1).toUint32()` → **`-16776961`**, expected `4278190335` (`0xFF0000FF`).
+  `new Color(1, 1, 1, 1).toUint32()` → **`-1`**, expected `4294967295`.
+  Bit pattern is right, the numeric value is not: `color.toUint32() === 0xFF0000FF` is `false`,
+  and the value serialises to JSON / compares / hashes as a negative number.
+- **Fix**: `return ((partial << 8) | (_a & 0xFF)) >>> 0;`
+- **Note**: `Color.spec.js:47-66` currently encodes the present behaviour (it normalises with
+  `>>> 0` at every assertion and comments on it), so this is a deliberate-looking wart rather
+  than an unnoticed one — but it still contradicts the published contract, and the fix would let
+  those `>>> 0`s be dropped from the spec.
+- **Confidence**: Confirmed
+
+---
+
+### SCI-6 `Color.setHCL` / `Color.setHSI` produce NaN for infinitesimally negative hues
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/Color.js:332-383` (`setHCL`)
+  and `Color.js:393-447` (`setHSI`)
+- **Defect**: both normalise hue as `_h = h % 1; if (_h < 0) _h += Math.ceil(Math.abs(_h));`
+  — the modulo happens *before* the shift. For `-1.1e-16 < h < 0` the addition rounds to exactly
+  `1.0`, so `h_face = 6`, `Math.floor(h_face) === 6`, and the `switch` (cases 0–5, no `default`)
+  leaves `r`, `g`, `b` as `undefined`. `undefined + m` is `NaN`.
+  `hsv/hsv2rgb_float.js:11-17` does the same normalisation in the opposite order (shift, then
+  `% 1`) and is immune, which shows the correct ordering is already known in this package.
+- **Failure scenario**: `new Color().setHCL(-1e-17, 1, 0.5)` →
+  in a production build (asserts stripped) sets `r = g = b = NaN`; expected `(1.2, 0.2, 0.2)`,
+  the value produced for `h = 0`. Identical for `setHSI(-1e-17, 1, 0.5)`
+  (expected `(1.5, 0, 0)`). Confirmed at `h ∈ {-1e-17, -1e-18, -5e-17}`; `h = -1e-16` and larger
+  magnitudes are unaffected.
+- **Fix**: apply the modulo last, exactly as `hsv2rgb_float` does:
+  `let _h = h; if (_h < 0) { _h += Math.ceil(Math.abs(_h)); } _h = _h % 1;`
+- **Confidence**: Confirmed
+
+---
+
+### SCI-7 3-digit / 4-digit CSS hex shorthand silently yields a NaN channel
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/color/hex/hex2rgb.js:12-14`
+  (reached via `parse_color.js:53-61` and `Color.parse`, `Color.js:774-780`)
+- **Defect**: `hex2rgb` slices fixed byte pairs at offsets 1/3/5 and never checks the string
+  length, so for a 4-character input the blue slice is `""` and `parseInt("", 16)` is `NaN`.
+  `parse_color`'s `#`-branch has no length validation either, so it neither expands the
+  shorthand nor falls through to its `throw new Error('Failed to decode color string ...')`.
+- **Failure scenario**: `parse_color('#fff')` → **`[255, 15, NaN, 1]`**, expected `[255, 255, 255, 1]`.
+  `Color.parse('#fff')` therefore yields `r = 1, g = 0.0588, b = NaN` in a production build
+  (in a dev build `Color.set`'s `assert.notNaN` throws instead, which is why this has gone
+  unnoticed). `hex2rgb('#fff8')` → `{r: 255, g: 248, b: NaN, a: 255}`.
+  `Color.parse` documents `@throws Error if format could not be parsed` and advertises "most CSS
+  color representations", so both silent-NaN and no-throw violate the stated contract.
+- **Fix**: in `hex2rgb`, branch on `hex.length`: for 4/5-character input expand each nibble
+  (`c → cc`) before `hex2dec`; otherwise keep the current 7/9-character path. Anything else should
+  reach `parse_color`'s existing `throw`.
+- **Confidence**: Confirmed