@woosh/meep-engine 3.1.0 → 3.3.0

package/src/REVIEW_2026_08_06/core-binary.md

@@ -1,348 +1,348 @@
-# Correctness review — meep `core/` (binary, json, parser, codegen, lang, localization, path, primitives, model)
-
-Scope reviewed: every non-spec source file under the nine listed directories.
-Findings marked **Confirmed** were reproduced by executing the real code (node, ESM, asserts active); the reproductions are noted inline.
-
----
-
-### BIN-1 `writeUTF8String` destroys the string body when the buffer grows mid-write
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/BinaryBuffer.js:1086-1141` (interacting with `setCapacity` at `:192-203`)
-- **Defect**: `writeUTF8String` writes UTF-8 bytes into a local `cursor` and only assigns `this.position = cursor` at the very end (line 1141). When the loop hits `ensureCapacity(cursor + 4)` at line 1114, `setCapacity` copies only `Math.min(oldLen, newLen, this.position)` bytes — and `this.position` is still pointing at the *start* of the string body. Every byte written between the start of the body and `cursor` is silently replaced with zeroes.
-- **Failure scenario**: `const b = new BinaryBuffer(); b.writeUTF8String("\u0416".repeat(3000)); b.position = 0; b.readUTF8String()` returns `""` instead of the 3000-character string. Same for `"\u65E5".repeat(3000)` (CJK) and `"\u{1F600}".repeat(3000)` (emoji). The initial reserve is only `1.5 * string.length + 7` bytes, so any string whose UTF-8 size exceeds that by more than one growth step (≥1024 bytes) corrupts — i.e. roughly any Cyrillic/Greek/Hebrew/CJK/emoji string longer than ~2000 code units. ASCII of the same length round-trips fine, which is why this has gone unnoticed.
-- **Fix**: assign `this.position = cursor;` immediately before the in-loop `ensureCapacity(cursor + 4)` call (and re-read `this.__data_uint8`/`this.capacity` after, as it already does). Alternatively size the reserve exactly up front (4 bytes per code unit) so no in-loop growth can occur.
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-2 `Localization.loadLocale` hangs forever when `path` ends with a separator
-- **Severity**: CRITICAL
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/localization/Localization.js:140-143`
-- **Defect**: the trailing-separator trim loop calls `_path.slice(0, _path.length - 1)` and discards the result. `String.slice` does not mutate, so `_path` never changes and the `while` condition never becomes false.
-- **Failure scenario**: `localization.loadLocale('en-gb', 'data/database/text/')` — the loop spins forever, freezing the tab/worker. Any caller passing a path with a trailing `/` or `\` hangs the application. (The default argument has no trailing slash, which is why the shipped path works.)
-- **Fix**: `_path = _path.slice(0, _path.length - 1);`
-- **Confidence**: Confirmed (static; not executed because it hangs)
-
----
-
-### BIN-3 Lone high surrogates desynchronise the UTF-8 stream
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/BinaryBuffer.js:1084` (length header) and `:1106-1108` (drop), read side `:1172`
-- **Defect**: the length header written is `string.length` in UTF-16 code units, but a lone high surrogate is skipped (`continue`) and contributes zero bytes. The reader loops `while (i < capacity && charCount < stringLength)`, so it keeps consuming bytes *past the end of the string* to make up the missing count.
-- **Failure scenario**:
-  ```js
-  const b = new BinaryBuffer();
-  b.writeUTF8String("\uD800abc");   // length header = 4, only 3 bytes written
-  b.writeUint32(0x41414141);
-  b.position = 0;
-  b.readUTF8String();               // "abcA"  <-- ate a byte of the next field
-  b.readUint32();                   // 0x00414141 instead of 0x41414141
-  ```
-  Every field after the string is shifted by one byte. Lone high surrogates arise routinely from slicing a string that ends mid-emoji (e.g. truncating a player name).
-- **Fix**: count what is actually emitted. Either pre-scan and write the number of code units the writer will really encode, or write a byte-length prefix instead of a code-unit count, or encode the lone surrogate (CESU-8) instead of dropping it — the reader already round-trips lone *low* surrogates that way.
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-4 `StructureBuilder.build()` always throws `ReferenceError`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/type/TypeBuilder.js:76`
-- **Defect**: `buildConstructorFunction(structure)` calls `buildTypePrototype(type, lines)`, but the parameter is named `structure` — `type` is not defined in any enclosing scope.
-- **Failure scenario**: `new StructureBuilder("Foo").build()` throws `ReferenceError: type is not defined`. The class has no working code path at all.
-- **Fix**: `buildTypePrototype(structure, lines);`
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-5 `Type.clone()` loses the type name and flags
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/type/Type.js:74-78`
-- **Defect**: `clone()` does `new Type()` with no arguments and then copies only `fields`. `name`, `isPrimitive` and `isFixedLength` are dropped.
-- **Failure scenario**: `new Type("Foo").clone()` throws `Error: Name must be of type "string", instead was "undefined"` when asserts are live. With asserts compiled out (production) it silently returns a `Type` whose `name` is `undefined`, which then poisons `StructureRegistry.__add` (it keys `this.types[undefined]`) and every `getFieldByName`/error message.
-- **Fix**: `const result = new Type(this.name); result.isPrimitive = this.isPrimitive; result.isFixedLength = this.isFixedLength; result.fields = this.fields.slice();`
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-6 `DataViewStructAccessor` generates broken accessors for `Uint64`/`Int64`/`Float16`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/data_view/DataType2DataViewReaders.js:12,17` and `DataType2DataViewWriters.js:12,17`; codegen at `buildAccessor.js:49-53`
-- **Defect**: `DataView` exposes `getBigUint64`/`getBigInt64`, not `getUint64`/`getInt64`. `BinaryDataType.Float16` has no entry in either map at all, yet `assert.enum(type, BinaryDataType)` accepts it and `DataTypeByteSizes` gives it a size, so the schema is considered valid and the generated getter body becomes `return this.$data.undefined(...)`.
-- **Failure scenario**:
-  - `new DataViewStructAccessor({ v: BinaryDataType.Uint64 }).v` → `TypeError: this.$data.getUint64 is not a function`
-  - `new DataViewStructAccessor({ v: BinaryDataType.Float16 }).v` → `TypeError: this.$data.undefined is not a function`
-  Both fail at first *access*, not at construction, so the schema looks accepted.
-- **Fix**: map `Uint64`→`getBigUint64`/`setBigUint64` and `Int64`→`getBigInt64`/`setBigInt64`; either add a Float16 path (`getUint16` + `half_to_float_uint16`) or make `buildAccessor` throw for types with no reader/writer mapping instead of emitting `undefined`.
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-7 `BitSet.shift()` shifts right for negative distances
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/BitSet.js:547-553`
-- **Defect**: the negative branch calls `this.shift_right(-distance, ...)` instead of `this.shift_left(-distance, ...)`.
-- **Failure scenario**: `const s = new BitSet(); s.set(5, true); s.shift(-1, 0, 10);` → bit 6 is set, bits 4 and 5 are clear. Expected bit 4 set. The sign of the argument is inverted in effect: a "shift left by 1" moves everything one place right.
-- **Fix**: `this.shift_left(-distance, start_index, end_index);`
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-8 `ImmutableObjectPool.add` can delete the bucket it is about to write into
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/object/ImmutableObjectPool.js:133-176` (eviction at `:150`, push at `:171`, crash site `:120`)
-- **Defect**: `add` first resolves/creates the per-key bucket array, *then* evicts the LRU head at line 150. If the evicted element has the same key and was the last one in that bucket, `__removeElement` calls `this.data.delete(key)` — removing the very array the local `elements` variable still points at. The new element is then pushed into a detached array and `size++` still runs.
-- **Failure scenario**:
-  ```js
-  const p = new ImmutableObjectPool({ capacity: 1, perKeyCapacity: 10 });
-  p.add(k, "v1");
-  p.add(k, "v2");        // evicts v1, deletes bucket k, pushes v2 into the detached array
-  p.get(k);              // undefined  (value is unreachable but size === 1)
-  p.clear();             // TypeError: Cannot read properties of undefined (reading 'indexOf')
-  ```
-  With the default `capacity: 100` this triggers whenever the pool is full and the oldest element happens to be the sole entry for the key being added — after which that key is permanently unusable and `clear()` throws.
-- **Fix**: perform the eviction *before* resolving/creating the bucket, and re-resolve `elements` afterwards (or have `__removeElement` skip the `data.delete` when the bucket is the one currently being populated).
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-9 `ObservedEnum.hash()` iterates a plain object with `for...of`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/ObservedEnum.js:94`
-- **Defect**: `for (const n of this.__validSet)` — `__validSet` is a plain object (`Object.<string,T>` per the constructor contract), which is not iterable.
-- **Failure scenario**: `new ObservedEnum(7, { ONE: 1, SEVEN: 7 }).hash()` throws `TypeError: this.__validSet is not iterable`. Any `HashMap`/`HashSet`/`Cache` keyed by an `ObservedEnum` crashes on insert.
-- **Fix**: `for (const n in this.__validSet)`.
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-10 `JsonUtils.stringify` writes `undefined` as the *string* `"null"`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/json/JsonUtils.js:62-63`
-- **Defect**: the `"undefined"` case calls `processValue("null")`, which re-enters the `"string"` branch and emits `JSON.stringify("null")` — i.e. `"null"` with quotes — instead of the bare literal `null`.
-- **Failure scenario**: `stringify({ a: undefined })` → `{"a":"null"}`. Round-tripping through `JSON.parse` yields the string `"null"` where `null` was expected; any downstream `=== null` / `typeof` check now sees a string.
-- **Fix**: `addToOutput("null");` directly, without recursing.
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-11 `JsonUtils.stringify` does not escape property names, producing invalid JSON
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/json/JsonUtils.js:16`
-- **Defect**: `addToOutput('"' + name + '":')` concatenates the raw key. Values go through `JSON.stringify`, keys do not.
-- **Failure scenario**:
-  - `stringify({ 'a"b': 1 })` → `{"a"b":1}` → `JSON.parse` throws `Expected ':' after property name in JSON at position 4`.
-  - `stringify({ 'a\nb': 1 })` → contains a literal newline inside the key → `JSON.parse` throws `Bad control character in string literal`.
-  Keys containing `"`, `\` or control characters (Windows paths, user-authored ids) produce output that cannot be parsed back.
-- **Fix**: `addToOutput(JSON.stringify(name) + ':');`
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-12 `write_property` ignores `part_offset`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/object/write_property.js:17`
-- **Defect**: it calls `read_property(root, parts, 0, last_index, true)` — hard-coding offset `0` and passing `last_index` (= `part_offset + part_count - 1`) as the *count*. The correct arguments are offset `part_offset` and count `part_count - 1`. The two coincide only when `part_offset === 0`, which is the only case the spec covers.
-- **Failure scenario**: `write_property({ a: { b: 0 } }, ['x','a','b'], 1, 2, 31)` should set `root.a.b = 31`; instead it starts at `parts[0] === 'x'` and throws `Error: No no property or getter found for 'x' on [0]'x/a'`. With a root that happens to have the extraneous key, it writes to the wrong location instead of throwing.
-- **Fix**: `const thing = read_property(root, parts, part_offset, part_count - 1, true);`
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-13 `BoundedValue` drops the lower limit in `copy`, JSON and binary serialisation
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/BoundedValue.js:156-160` (`copy`), `:185-190` (`toJSON`/`fromJSON`), `:201-215` (binary)
-- **Defect**: `__limitLower` participates in `equals()`, `hash()` and `getFraction()`, but `copy`, `toJSON`/`fromJSON` and `toBinaryBuffer`/`fromBinaryBuffer` all transfer only `__value` and `__limitUpper`.
-- **Failure scenario**:
-  ```js
-  const a = new BoundedValue(0, 10, 0);
-  const b = new BoundedValue(5, 10, 2);
-  a.copy(b);
-  a.equals(b);        // false   (a.__limitLower === 0, b's === 2)
-  a.getFraction();    // 0.5 instead of 0.375
-  ```
-  The same loss occurs across a save/load cycle: a bar with a non-zero floor reloads with floor 0 and renders at the wrong fill fraction.
-- **Fix**: include `__limitLower` in `copy`, in the JSON payload (with a default for old saves) and in the binary form (versioned, since it changes the wire size).
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-14 `ConnectedBoxLayouter.__execute_swaps` scores the same box twice
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/node-graph/visual/layout/ConnectedBoxLayouter.js:132`
-- **Defect**: `const b1_cost_after = this.__compute_box_cost(b0);` — copy-paste of the line above; it should score `b1`.
-- **Failure scenario**: for any pair `(b0, b1)`, the accept/reject test at line 134 compares `b0_cost + b1_cost` against `2 * cost_after(b0)` instead of `cost_after(b0) + cost_after(b1)`. Swapping two boxes where b0's cost drops slightly but b1's cost rises sharply is accepted, so `layout()` converges to a worse (and, because `b1_cost` still feeds the left side, non-monotonic) arrangement. Every call to `layout()` / `step()` is affected.
-- **Fix**: `const b1_cost_after = this.__compute_box_cost(b1);`
-- **Confidence**: Confirmed
-
----
-
-### BIN-15 `string_format_kebab_to_underscore` converts only the first separator
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/primitives/strings/string_format_kebab_to_underscore.js:7`
-- **Defect**: `string.replace('-', '_')` with a string pattern replaces the first occurrence only.
-- **Failure scenario**: `string_format_kebab_to_underscore("a-b-c")` returns `"a_b-c"`; the documented result is `"a_b_c"`. Any multi-segment kebab identifier (`"top-left-corner"`, `"en-gb-fallback"`) comes out half-converted.
-- **Fix**: `string.replace(/-/g, '_')` (or `replaceAll`).
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-16 `LocalizationEngine.resolve` cannot read a `LocaleDataset`
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/localization/LocalizationEngine.js:61-64`
-- **Defect**: `setLocaleDataset` is documented `@param {LocaleDataset} dataset` and `#locales` is `Object<LocaleDataset>`, but `resolve` indexes the stored object directly (`locale[fragment_key]`). `LocaleDataset` keeps its entries in a `#map` private field and exposes them only through `get(key)` / `hasKey(key)`, so direct indexing is always `undefined`.
-- **Failure scenario**: `engine.setLocaleDataset("en", someLocaleDataset); engine.resolve("en", "greeting")` returns `undefined` even when `someLocaleDataset.get("greeting") === "Hello"`, and the engine then walks the whole fallback chain for nothing. (It only works today because the spec passes plain objects instead of the documented type.)
-- **Fix**: call `locale.get(fragment_key)` / `locale.hasKey(fragment_key)` — and give `LocaleDataset` a way to populate `#map`, which it currently lacks.
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-17 `compileReactiveToJS` emits `--x` for nested negation
-- **Severity**: MAJOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/reactive/js/compileReactiveToJS.js:98-101`
-- **Defect**: `compileNegate` concatenates `-` directly onto the operand with no parentheses or separating space.
-- **Failure scenario**:
-  - `ReactiveNegate.from(ReactiveNegate.from(ReactiveReference.from(v,'a')))` compiles to `--this.a`, which is a *decrement* — it mutates `this.a` and yields the decremented value, instead of evaluating to `a`.
-  - `ReactiveNegate.from(ReactiveLiteralNumber.from(-5))` compiles to `--5`, a `SyntaxError` when the string is handed to `new Function`.
-- **Fix**: `return \`-( ${compileExpression(exp.source)} )\`;` (matching how the binary compilers already parenthesise). `compileNot` has the same shape but `!!` is harmless.
-- **Confidence**: Confirmed
-
----
-
-### BIN-18 `readArrayLiteral` accepts unterminated arrays
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/parser/simple/readArrayLiteral.js:39`
-- **Defect**: the parse loop is `while (i < limit)`. When the input ends immediately after a separator (or after the opening bracket), the loop condition simply goes false and the function *returns a token* instead of reaching either the `]` branch or the `Unterminated array literal` throw.
-- **Failure scenario**: `readArrayLiteral("[1,", 0, 3)` returns a valid array token with `value.length === 1`, `end === 3` — no error. `readArrayLiteral("[", 0, 1)` returns an empty array token. Truncated data is accepted as well-formed.
-- **Fix**: track whether the terminator was consumed and throw `Unterminated array literal` when the loop exits without it.
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-19 `string_compute_byte_size` under-counts UTF-8 bytes
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/primitives/strings/string_compute_byte_size.js:9-18`
-- **Defect**: the function counts bytes needed to store the *code unit* (`while (c > 0xff) { p++; c >>= 8; }`), not the UTF-8 encoding length. Code points U+0080–U+00FF need 2 UTF-8 bytes but are counted as 1; U+0800–U+FFFF need 3 but are counted as 2.
-- **Failure scenario**: `string_compute_byte_size("\u65E5\u672C")` returns 4, the real UTF-8 size is 6. `string_compute_byte_size("\u00E9")` returns 1, the real size is 2. In-repo it is used as a `Cache` `keyWeigher` (`FunctionCompiler`, `TerrainLayer`, `TooltipParser`), so those caches systematically exceed their configured `maxWeight` for non-ASCII keys.
-- **Fix**: branch on the code point: `<0x80 → 1`, `<0x800 → 2`, surrogate pair → 4 (consume both units), else 3.
-- **Confidence**: Confirmed (reproduced)
-
----
-
-### BIN-20 `readUnsignedIntegerToken` returns 0 instead of erroring at end-of-input
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/parser/simple/readUnsignedIntegerToken.js:22-63`
-- **Defect**: the "no digits" error is raised inside the loop (`if (i === cursor)`), so when `cursor === length` the loop body never runs and the function returns `Token(0, cursor, cursor)` with no error.
-- **Failure scenario**: `readNumberToken("-", 0, 1)` returns a number token with value `-0` and `end === 1`; `readNumberToken("", 0, 0)` returns `0`. Truncated numeric input parses as zero rather than raising a `ParserError`.
-- **Fix**: after the loop, `if (i === cursor) throw new ParserError(i, 'Expected at least one digit', text);` — mirroring the fix already applied in `readHexToken.js:113`.
-- **Confidence**: Confirmed
-
----
-
-### BIN-21 `skipWhitespace` does not treat `\r` as whitespace
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/parser/simple/skipWhitespace.js:21`
-- **Defect**: only `' '`, `'\n'` and `'\t'` are skipped; `'\r'` is not.
-- **Failure scenario**: parsing an array literal written with CRLF line endings — `readArrayLiteral("[1,\r\n2]", 0, 7)` — stops at the `\r`, calls `readLiteralToken` on it and throws `ParserError: Expected literal start, but found ''`. Any CRLF-formatted data file fails to parse on Windows.
-- **Fix**: add `|| char === '\r'` (and consider `'\f'`/`'\v'`).
-- **Confidence**: Confirmed
-
----
-
-### BIN-22 `resolvePathByArray` mutates the caller's array and mis-truncates the error hint
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/json/resolvePathByArray.js:35` and `:15`
-- **Defect**: (a) `parts.shift()` destructively removes the leading empty segment from the caller-owned array; (b) `buildErrorSuggestions` does `options.splice(0, limit)`, which deletes the **first** 10 keys and keeps the rest, then appends `[... N-10 more options]`. The intent was to keep the first 10.
-- **Failure scenario**: for an object with 15 keys the thrown message lists keys 11–15 and claims "5 more options", while actually hiding 10 — a diagnostic that points at the wrong candidates. Separately, `const p = ["", "a", "b"]; resolvePathByArray(o, p);` leaves the caller holding `["a","b"]`.
-- **Fix**: `options.length = limit;` before the push; and skip the leading empty segment with a local start index instead of `shift()`.
-- **Confidence**: Confirmed
-
----
-
-### BIN-23 `ObservedInteger` binary round-trip turns ±(2^31−1 / −2^31) into ±Infinity
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/ObservedInteger.js:173-199`
-- **Defect**: `2147483647` and `-2147483648` are used as in-band sentinels for `±Infinity`, and `toBinaryBuffer` writes finite values of exactly those magnitudes unchanged (the source even carries a `//TODO` acknowledging it).
-- **Failure scenario**: `v.set(2147483647); v.toBinaryBuffer(b); b.position = 0; v2.fromBinaryBuffer(b);` → `v2.getValue() === Infinity`. Any stat/counter that legitimately reaches `2^31-1` becomes infinite after a save/load cycle.
-- **Fix**: write a one-byte tag (finite / +inf / -inf) before the int32, or clamp finite writes to `±2147483646`.
-- **Confidence**: Confirmed
-
----
-
-### BIN-24 `LanguageMetadata.fromJSON` throws on an unknown locale and never sets `locale`
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/localization/LanguageMetadata.js:28-39`; caller `Localization.js:165`
-- **Defect**: (a) the instance `fromJSON` destructures its argument, so `undefined` throws; the caller does `LanguageMetadata.fromJSON(languages_metadata[locale])` from inside a `.then` success handler, where the sibling rejection handler cannot catch it. (b) `fromJSON` never assigns `this.locale`, even though `LocalizationEngine.addLanguageMetadata` keys the registry by `metadata.locale`.
-- **Failure scenario**: `loadLocale('zh-cn')` against the shipped `app/data/database/text/languages.json` (which contains only `en-gb` and `ru`) rejects with `TypeError: Cannot destructure property 'reading_speed' of 'undefined'` instead of falling back to `DEFAULT_LANGUAGE_METADATA`. Separately, every metadata object produced by `fromJSON` registers under the empty-string key, so `LocalizationEngine`'s fallback chain never finds it.
-- **Fix**: default the parameter (`fromJSON(j = {})`) or check for `undefined` at the call site; and pass/assign the locale key.
-- **Confidence**: Confirmed
-
----
-
-### BIN-25 Reactive literals share a module-level `dummySignal`, leaking every expression that connects to one
-- **Severity**: MINOR
-- **File**: `ReactiveLiteralNumber.js:7,20`, `ReactiveLiteralBoolean.js:6,19`, `ReactiveLiteralString.js:7,16` (all under `core/model/reactive/model/terminal/`)
-- **Defect**: each literal instance assigns the same module-scoped `Signal` to `this.onChanged`. `ReactiveBinaryExpression.connect` / `ReactiveUnaryExpression.connect` then register `(this.update, this)` on that shared signal. The handler entry holds a strong reference to the parent expression, and the signal lives for the lifetime of the module.
-- **Failure scenario**: build and drop expressions containing literals without calling `disconnect()` — e.g. `for (let i = 0; i < 100000; i++) ReactiveAdd.from(ReactiveLiteralNumber.from(1), ReactiveLiteralNumber.from(2));` — all 100 000 `ReactiveAdd` instances remain reachable from the global `dummySignal` and are never collected. `compileReactiveExpression` produces literal-bearing trees on the common path.
-- **Fix**: skip registration when the source signal is the shared dummy (e.g. expose `isConstant` on terminals and have `connect` not subscribe), or give each literal its own lazily-created signal.
-- **Confidence**: Confirmed
-
----
-
-### BIN-26 `BoundedValue.setLowerLimit` dispatches `onChanged` with no arguments
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/BoundedValue.js:86`
-- **Defect**: every other mutator sends `send4(value, upperLimit, oldValue, oldUpperLimit)`; `setLowerLimit` calls `this.onChanged.dispatch()` with zero arguments.
-- **Failure scenario**: `bv.onChanged.add((value, limit) => bar.width = value / limit); bv.setLowerLimit(5);` → the handler receives `(undefined, undefined)` and sets `bar.width = NaN`, whereas the same handler works for `setValue`/`setUpperLimit`.
-- **Fix**: `this.onChanged.send4(this.__value, this.__limitUpper, this.__value, this.__limitUpper);` (and, per the existing TODO, widen the signature to carry the lower limit).
-- **Confidence**: Confirmed
-
----
-
-### BIN-27 `number_format_by_thousands` inserts separators inside the fractional part
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/primitives/numbers/number_format_by_thousands.js:13`
-- **Defect**: the regex `\B(?=(\d{3})+(?!\d))` is applied to the whole `toString()` output, including digits after the decimal point.
-- **Failure scenario**: `number_format_by_thousands(1234.5678)` returns `"1,234.5,678"` instead of `"1,234.5678"`. (The in-repo caller `number_pretty_print` always passes an integer, so this only bites external/direct callers of this public util.)
-- **Fix**: split on `.` and apply the grouping regex only to the integer part.
-- **Confidence**: Confirmed
-
----
-
-### BIN-28 `ExpressionNode.computeMaxParentScore` never computes a max
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/reactive/evaluation/MultiPredicateEvaluator.js:65-85` (bad call at `:77`)
-- **Defect**: two errors in one function. (a) `result = max2(parent.computeMaxParentScore(scoringFunction))` calls the 2-argument `max2` with one argument — `max2(a, undefined)` evaluates `a < undefined` (false) and returns `a`, so the loop just overwrites `result` with the *last* parent's score rather than the maximum. (b) the `n === 0` branch `return`s before `this.__max_parent_score = result`, so root nodes always report a score of 0 from `getScore()`.
-- **Failure scenario**: `evaluator.build([exprA, exprB])` where `exprA`/`exprB` share sub-expressions: every node's `getScore()` returns `0` (roots never assign; children are never visited because `build` only invokes the method on parentless roots). Any future ordering that reads `getScore()` gets a constant.
-- **Fix**: `result = max2(result, parent.computeMaxParentScore(scoringFunction));` and assign `__max_parent_score` on the `n === 0` path before returning.
-- **Confidence**: Confirmed
-
----
-
-### BIN-29 `Stat.Process.ROUND_DOWN` truncates toward zero and wraps at 2^31
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/stat/Stat.js:302-304`
-- **Defect**: `v | 0` is an int32 truncation, not a floor.
-- **Failure scenario**: a stat driven negative by a debuff — `postprocess = Stat.Process.ROUND_DOWN`, computed value `-2.5` → `-2`, whereas "round down" is `-3`; the stat reads one point *higher* than intended. And a value above 2^31 (e.g. a score of 3 000 000 000) becomes `-1294967296`.
-- **Fix**: `Math.floor(v)`.
-- **Confidence**: Confirmed
-
----
-
-### BIN-30 `ObservedValue.equals(null)` throws
-- **Severity**: MINOR
-- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/ObservedValue.js:63`
-- **Defect**: the guard `typeof other === 'object'` is clearly meant to reject non-objects, but `typeof null === 'object'`, so `null` passes and `other.__value` dereferences it.
-- **Failure scenario**: `new ObservedValue(1).equals(null)` throws `TypeError: Cannot read properties of null (reading '__value')` instead of returning `false` — which the guard's own existence shows was the intent. Every sibling class (`ObservedBoolean`, `ObservedString`, `ObservedInteger`) has no guard at all and is documented to take an instance, so this one is specifically claiming to handle the case.
-- **Fix**: `return other !== null && typeof other === 'object' && this.__value === other.__value;`
-- **Confidence**: Confirmed
-
----
-
-## Areas reviewed and found sound (no findings)
-
-- `BinaryBuffer` integer/float read/write pairs, `readUint24`/`writeUint24` (LE and BE), varint encode/decode across 0…2^31−1, `writeBytes`/`readBytes`, `writeASCIIString`.
-- `EncodingBinaryBuffer` string-interning: the `>>> 1` unsigned shift and the odd low-byte discriminator are correct, and the `BiMap` key/value orientation is self-consistent in both directions.
-- `to_half_float_uint16` / `half_to_float_uint16` (including NaN/±Inf/denormal/max-normal paths), `lsb_32` (the de Bruijn multiply is exact because the operand is always a power of two), `msb_32`, `ctz32`, `bitCount`, `reverse_bits_uint32`, `split_by_2`/`split_by_3`, `Base64` (matches upstream base64-js), `base58_encode`, `SmallFloat`, `OffsetAllocator` (faithful port of sebbbi/OffsetAllocator, including the freelist stack discipline).
-- `BitImage2`: `canBlit`'s cross-word guard is provably in-bounds; `or_blit`, `dilate`, `grow_preserving`, `copy_transposed` are correct.
-- `BitSet` core (`nextSetBit`, `nextClearBit`, `previousSetBit`, `cardinality`, `copy`, `reset`, resize/shrink) — the `setRange` inclusive / `clearRange` exclusive asymmetry is real but every in-repo caller compensates for it, and only the JSDoc is contradictory.
-- `path/*` (behaviour is pinned by specs), `codegen/*`, `objectDeepEquals`, `object_deep_clone`, `compareValues`, `ObjectPoolFactory`, `ModuleRegistry`, `Connection`/`Port`/`NodeInstancePortReference`, `serializeNodeGraphToJSON` / `deserializeNodeGraphFromJSON`, `MultiPredicateEvaluator.__resolve_node` short-circuit logic, `inferReactiveExpressionTypes`, `ReactivePegCompiler`, `AbstractCachingParser`, `readStringToken` (the `length - 1` loop bound is correct for every terminator position), `readHexToken`, `readIdentifierToken`, `readReferenceToken`, `string_jaro_distance`/`string_jaro_winkler`, `computeStringHash`, `number_pretty_print`.
+# Correctness review — meep `core/` (binary, json, parser, codegen, lang, localization, path, primitives, model)
+
+Scope reviewed: every non-spec source file under the nine listed directories.
+Findings marked **Confirmed** were reproduced by executing the real code (node, ESM, asserts active); the reproductions are noted inline.
+
+---
+
+### BIN-1 `writeUTF8String` destroys the string body when the buffer grows mid-write
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/BinaryBuffer.js:1086-1141` (interacting with `setCapacity` at `:192-203`)
+- **Defect**: `writeUTF8String` writes UTF-8 bytes into a local `cursor` and only assigns `this.position = cursor` at the very end (line 1141). When the loop hits `ensureCapacity(cursor + 4)` at line 1114, `setCapacity` copies only `Math.min(oldLen, newLen, this.position)` bytes — and `this.position` is still pointing at the *start* of the string body. Every byte written between the start of the body and `cursor` is silently replaced with zeroes.
+- **Failure scenario**: `const b = new BinaryBuffer(); b.writeUTF8String("\u0416".repeat(3000)); b.position = 0; b.readUTF8String()` returns `""` instead of the 3000-character string. Same for `"\u65E5".repeat(3000)` (CJK) and `"\u{1F600}".repeat(3000)` (emoji). The initial reserve is only `1.5 * string.length + 7` bytes, so any string whose UTF-8 size exceeds that by more than one growth step (≥1024 bytes) corrupts — i.e. roughly any Cyrillic/Greek/Hebrew/CJK/emoji string longer than ~2000 code units. ASCII of the same length round-trips fine, which is why this has gone unnoticed.
+- **Fix**: assign `this.position = cursor;` immediately before the in-loop `ensureCapacity(cursor + 4)` call (and re-read `this.__data_uint8`/`this.capacity` after, as it already does). Alternatively size the reserve exactly up front (4 bytes per code unit) so no in-loop growth can occur.
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-2 `Localization.loadLocale` hangs forever when `path` ends with a separator
+- **Severity**: CRITICAL
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/localization/Localization.js:140-143`
+- **Defect**: the trailing-separator trim loop calls `_path.slice(0, _path.length - 1)` and discards the result. `String.slice` does not mutate, so `_path` never changes and the `while` condition never becomes false.
+- **Failure scenario**: `localization.loadLocale('en-gb', 'data/database/text/')` — the loop spins forever, freezing the tab/worker. Any caller passing a path with a trailing `/` or `\` hangs the application. (The default argument has no trailing slash, which is why the shipped path works.)
+- **Fix**: `_path = _path.slice(0, _path.length - 1);`
+- **Confidence**: Confirmed (static; not executed because it hangs)
+
+---
+
+### BIN-3 Lone high surrogates desynchronise the UTF-8 stream
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/BinaryBuffer.js:1084` (length header) and `:1106-1108` (drop), read side `:1172`
+- **Defect**: the length header written is `string.length` in UTF-16 code units, but a lone high surrogate is skipped (`continue`) and contributes zero bytes. The reader loops `while (i < capacity && charCount < stringLength)`, so it keeps consuming bytes *past the end of the string* to make up the missing count.
+- **Failure scenario**:
+  ```js
+  const b = new BinaryBuffer();
+  b.writeUTF8String("\uD800abc");   // length header = 4, only 3 bytes written
+  b.writeUint32(0x41414141);
+  b.position = 0;
+  b.readUTF8String();               // "abcA"  <-- ate a byte of the next field
+  b.readUint32();                   // 0x00414141 instead of 0x41414141
+  ```
+  Every field after the string is shifted by one byte. Lone high surrogates arise routinely from slicing a string that ends mid-emoji (e.g. truncating a player name).
+- **Fix**: count what is actually emitted. Either pre-scan and write the number of code units the writer will really encode, or write a byte-length prefix instead of a code-unit count, or encode the lone surrogate (CESU-8) instead of dropping it — the reader already round-trips lone *low* surrogates that way.
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-4 `StructureBuilder.build()` always throws `ReferenceError`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/type/TypeBuilder.js:76`
+- **Defect**: `buildConstructorFunction(structure)` calls `buildTypePrototype(type, lines)`, but the parameter is named `structure` — `type` is not defined in any enclosing scope.
+- **Failure scenario**: `new StructureBuilder("Foo").build()` throws `ReferenceError: type is not defined`. The class has no working code path at all.
+- **Fix**: `buildTypePrototype(structure, lines);`
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-5 `Type.clone()` loses the type name and flags
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/type/Type.js:74-78`
+- **Defect**: `clone()` does `new Type()` with no arguments and then copies only `fields`. `name`, `isPrimitive` and `isFixedLength` are dropped.
+- **Failure scenario**: `new Type("Foo").clone()` throws `Error: Name must be of type "string", instead was "undefined"` when asserts are live. With asserts compiled out (production) it silently returns a `Type` whose `name` is `undefined`, which then poisons `StructureRegistry.__add` (it keys `this.types[undefined]`) and every `getFieldByName`/error message.
+- **Fix**: `const result = new Type(this.name); result.isPrimitive = this.isPrimitive; result.isFixedLength = this.isFixedLength; result.fields = this.fields.slice();`
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-6 `DataViewStructAccessor` generates broken accessors for `Uint64`/`Int64`/`Float16`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/data_view/DataType2DataViewReaders.js:12,17` and `DataType2DataViewWriters.js:12,17`; codegen at `buildAccessor.js:49-53`
+- **Defect**: `DataView` exposes `getBigUint64`/`getBigInt64`, not `getUint64`/`getInt64`. `BinaryDataType.Float16` has no entry in either map at all, yet `assert.enum(type, BinaryDataType)` accepts it and `DataTypeByteSizes` gives it a size, so the schema is considered valid and the generated getter body becomes `return this.$data.undefined(...)`.
+- **Failure scenario**:
+  - `new DataViewStructAccessor({ v: BinaryDataType.Uint64 }).v` → `TypeError: this.$data.getUint64 is not a function`
+  - `new DataViewStructAccessor({ v: BinaryDataType.Float16 }).v` → `TypeError: this.$data.undefined is not a function`
+  Both fail at first *access*, not at construction, so the schema looks accepted.
+- **Fix**: map `Uint64`→`getBigUint64`/`setBigUint64` and `Int64`→`getBigInt64`/`setBigInt64`; either add a Float16 path (`getUint16` + `half_to_float_uint16`) or make `buildAccessor` throw for types with no reader/writer mapping instead of emitting `undefined`.
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-7 `BitSet.shift()` shifts right for negative distances
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/binary/BitSet.js:547-553`
+- **Defect**: the negative branch calls `this.shift_right(-distance, ...)` instead of `this.shift_left(-distance, ...)`.
+- **Failure scenario**: `const s = new BitSet(); s.set(5, true); s.shift(-1, 0, 10);` → bit 6 is set, bits 4 and 5 are clear. Expected bit 4 set. The sign of the argument is inverted in effect: a "shift left by 1" moves everything one place right.
+- **Fix**: `this.shift_left(-distance, start_index, end_index);`
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-8 `ImmutableObjectPool.add` can delete the bucket it is about to write into
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/object/ImmutableObjectPool.js:133-176` (eviction at `:150`, push at `:171`, crash site `:120`)
+- **Defect**: `add` first resolves/creates the per-key bucket array, *then* evicts the LRU head at line 150. If the evicted element has the same key and was the last one in that bucket, `__removeElement` calls `this.data.delete(key)` — removing the very array the local `elements` variable still points at. The new element is then pushed into a detached array and `size++` still runs.
+- **Failure scenario**:
+  ```js
+  const p = new ImmutableObjectPool({ capacity: 1, perKeyCapacity: 10 });
+  p.add(k, "v1");
+  p.add(k, "v2");        // evicts v1, deletes bucket k, pushes v2 into the detached array
+  p.get(k);              // undefined  (value is unreachable but size === 1)
+  p.clear();             // TypeError: Cannot read properties of undefined (reading 'indexOf')
+  ```
+  With the default `capacity: 100` this triggers whenever the pool is full and the oldest element happens to be the sole entry for the key being added — after which that key is permanently unusable and `clear()` throws.
+- **Fix**: perform the eviction *before* resolving/creating the bucket, and re-resolve `elements` afterwards (or have `__removeElement` skip the `data.delete` when the bucket is the one currently being populated).
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-9 `ObservedEnum.hash()` iterates a plain object with `for...of`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/ObservedEnum.js:94`
+- **Defect**: `for (const n of this.__validSet)` — `__validSet` is a plain object (`Object.<string,T>` per the constructor contract), which is not iterable.
+- **Failure scenario**: `new ObservedEnum(7, { ONE: 1, SEVEN: 7 }).hash()` throws `TypeError: this.__validSet is not iterable`. Any `HashMap`/`HashSet`/`Cache` keyed by an `ObservedEnum` crashes on insert.
+- **Fix**: `for (const n in this.__validSet)`.
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-10 `JsonUtils.stringify` writes `undefined` as the *string* `"null"`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/json/JsonUtils.js:62-63`
+- **Defect**: the `"undefined"` case calls `processValue("null")`, which re-enters the `"string"` branch and emits `JSON.stringify("null")` — i.e. `"null"` with quotes — instead of the bare literal `null`.
+- **Failure scenario**: `stringify({ a: undefined })` → `{"a":"null"}`. Round-tripping through `JSON.parse` yields the string `"null"` where `null` was expected; any downstream `=== null` / `typeof` check now sees a string.
+- **Fix**: `addToOutput("null");` directly, without recursing.
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-11 `JsonUtils.stringify` does not escape property names, producing invalid JSON
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/json/JsonUtils.js:16`
+- **Defect**: `addToOutput('"' + name + '":')` concatenates the raw key. Values go through `JSON.stringify`, keys do not.
+- **Failure scenario**:
+  - `stringify({ 'a"b': 1 })` → `{"a"b":1}` → `JSON.parse` throws `Expected ':' after property name in JSON at position 4`.
+  - `stringify({ 'a\nb': 1 })` → contains a literal newline inside the key → `JSON.parse` throws `Bad control character in string literal`.
+  Keys containing `"`, `\` or control characters (Windows paths, user-authored ids) produce output that cannot be parsed back.
+- **Fix**: `addToOutput(JSON.stringify(name) + ':');`
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-12 `write_property` ignores `part_offset`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/object/write_property.js:17`
+- **Defect**: it calls `read_property(root, parts, 0, last_index, true)` — hard-coding offset `0` and passing `last_index` (= `part_offset + part_count - 1`) as the *count*. The correct arguments are offset `part_offset` and count `part_count - 1`. The two coincide only when `part_offset === 0`, which is the only case the spec covers.
+- **Failure scenario**: `write_property({ a: { b: 0 } }, ['x','a','b'], 1, 2, 31)` should set `root.a.b = 31`; instead it starts at `parts[0] === 'x'` and throws `Error: No no property or getter found for 'x' on [0]'x/a'`. With a root that happens to have the extraneous key, it writes to the wrong location instead of throwing.
+- **Fix**: `const thing = read_property(root, parts, part_offset, part_count - 1, true);`
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-13 `BoundedValue` drops the lower limit in `copy`, JSON and binary serialisation
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/BoundedValue.js:156-160` (`copy`), `:185-190` (`toJSON`/`fromJSON`), `:201-215` (binary)
+- **Defect**: `__limitLower` participates in `equals()`, `hash()` and `getFraction()`, but `copy`, `toJSON`/`fromJSON` and `toBinaryBuffer`/`fromBinaryBuffer` all transfer only `__value` and `__limitUpper`.
+- **Failure scenario**:
+  ```js
+  const a = new BoundedValue(0, 10, 0);
+  const b = new BoundedValue(5, 10, 2);
+  a.copy(b);
+  a.equals(b);        // false   (a.__limitLower === 0, b's === 2)
+  a.getFraction();    // 0.5 instead of 0.375
+  ```
+  The same loss occurs across a save/load cycle: a bar with a non-zero floor reloads with floor 0 and renders at the wrong fill fraction.
+- **Fix**: include `__limitLower` in `copy`, in the JSON payload (with a default for old saves) and in the binary form (versioned, since it changes the wire size).
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-14 `ConnectedBoxLayouter.__execute_swaps` scores the same box twice
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/node-graph/visual/layout/ConnectedBoxLayouter.js:132`
+- **Defect**: `const b1_cost_after = this.__compute_box_cost(b0);` — copy-paste of the line above; it should score `b1`.
+- **Failure scenario**: for any pair `(b0, b1)`, the accept/reject test at line 134 compares `b0_cost + b1_cost` against `2 * cost_after(b0)` instead of `cost_after(b0) + cost_after(b1)`. Swapping two boxes where b0's cost drops slightly but b1's cost rises sharply is accepted, so `layout()` converges to a worse (and, because `b1_cost` still feeds the left side, non-monotonic) arrangement. Every call to `layout()` / `step()` is affected.
+- **Fix**: `const b1_cost_after = this.__compute_box_cost(b1);`
+- **Confidence**: Confirmed
+
+---
+
+### BIN-15 `string_format_kebab_to_underscore` converts only the first separator
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/primitives/strings/string_format_kebab_to_underscore.js:7`
+- **Defect**: `string.replace('-', '_')` with a string pattern replaces the first occurrence only.
+- **Failure scenario**: `string_format_kebab_to_underscore("a-b-c")` returns `"a_b-c"`; the documented result is `"a_b_c"`. Any multi-segment kebab identifier (`"top-left-corner"`, `"en-gb-fallback"`) comes out half-converted.
+- **Fix**: `string.replace(/-/g, '_')` (or `replaceAll`).
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-16 `LocalizationEngine.resolve` cannot read a `LocaleDataset`
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/localization/LocalizationEngine.js:61-64`
+- **Defect**: `setLocaleDataset` is documented `@param {LocaleDataset} dataset` and `#locales` is `Object<LocaleDataset>`, but `resolve` indexes the stored object directly (`locale[fragment_key]`). `LocaleDataset` keeps its entries in a `#map` private field and exposes them only through `get(key)` / `hasKey(key)`, so direct indexing is always `undefined`.
+- **Failure scenario**: `engine.setLocaleDataset("en", someLocaleDataset); engine.resolve("en", "greeting")` returns `undefined` even when `someLocaleDataset.get("greeting") === "Hello"`, and the engine then walks the whole fallback chain for nothing. (It only works today because the spec passes plain objects instead of the documented type.)
+- **Fix**: call `locale.get(fragment_key)` / `locale.hasKey(fragment_key)` — and give `LocaleDataset` a way to populate `#map`, which it currently lacks.
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-17 `compileReactiveToJS` emits `--x` for nested negation
+- **Severity**: MAJOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/reactive/js/compileReactiveToJS.js:98-101`
+- **Defect**: `compileNegate` concatenates `-` directly onto the operand with no parentheses or separating space.
+- **Failure scenario**:
+  - `ReactiveNegate.from(ReactiveNegate.from(ReactiveReference.from(v,'a')))` compiles to `--this.a`, which is a *decrement* — it mutates `this.a` and yields the decremented value, instead of evaluating to `a`.
+  - `ReactiveNegate.from(ReactiveLiteralNumber.from(-5))` compiles to `--5`, a `SyntaxError` when the string is handed to `new Function`.
+- **Fix**: `return \`-( ${compileExpression(exp.source)} )\`;` (matching how the binary compilers already parenthesise). `compileNot` has the same shape but `!!` is harmless.
+- **Confidence**: Confirmed
+
+---
+
+### BIN-18 `readArrayLiteral` accepts unterminated arrays
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/parser/simple/readArrayLiteral.js:39`
+- **Defect**: the parse loop is `while (i < limit)`. When the input ends immediately after a separator (or after the opening bracket), the loop condition simply goes false and the function *returns a token* instead of reaching either the `]` branch or the `Unterminated array literal` throw.
+- **Failure scenario**: `readArrayLiteral("[1,", 0, 3)` returns a valid array token with `value.length === 1`, `end === 3` — no error. `readArrayLiteral("[", 0, 1)` returns an empty array token. Truncated data is accepted as well-formed.
+- **Fix**: track whether the terminator was consumed and throw `Unterminated array literal` when the loop exits without it.
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-19 `string_compute_byte_size` under-counts UTF-8 bytes
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/primitives/strings/string_compute_byte_size.js:9-18`
+- **Defect**: the function counts bytes needed to store the *code unit* (`while (c > 0xff) { p++; c >>= 8; }`), not the UTF-8 encoding length. Code points U+0080–U+00FF need 2 UTF-8 bytes but are counted as 1; U+0800–U+FFFF need 3 but are counted as 2.
+- **Failure scenario**: `string_compute_byte_size("\u65E5\u672C")` returns 4, the real UTF-8 size is 6. `string_compute_byte_size("\u00E9")` returns 1, the real size is 2. In-repo it is used as a `Cache` `keyWeigher` (`FunctionCompiler`, `TerrainLayer`, `TooltipParser`), so those caches systematically exceed their configured `maxWeight` for non-ASCII keys.
+- **Fix**: branch on the code point: `<0x80 → 1`, `<0x800 → 2`, surrogate pair → 4 (consume both units), else 3.
+- **Confidence**: Confirmed (reproduced)
+
+---
+
+### BIN-20 `readUnsignedIntegerToken` returns 0 instead of erroring at end-of-input
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/parser/simple/readUnsignedIntegerToken.js:22-63`
+- **Defect**: the "no digits" error is raised inside the loop (`if (i === cursor)`), so when `cursor === length` the loop body never runs and the function returns `Token(0, cursor, cursor)` with no error.
+- **Failure scenario**: `readNumberToken("-", 0, 1)` returns a number token with value `-0` and `end === 1`; `readNumberToken("", 0, 0)` returns `0`. Truncated numeric input parses as zero rather than raising a `ParserError`.
+- **Fix**: after the loop, `if (i === cursor) throw new ParserError(i, 'Expected at least one digit', text);` — mirroring the fix already applied in `readHexToken.js:113`.
+- **Confidence**: Confirmed
+
+---
+
+### BIN-21 `skipWhitespace` does not treat `\r` as whitespace
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/parser/simple/skipWhitespace.js:21`
+- **Defect**: only `' '`, `'\n'` and `'\t'` are skipped; `'\r'` is not.
+- **Failure scenario**: parsing an array literal written with CRLF line endings — `readArrayLiteral("[1,\r\n2]", 0, 7)` — stops at the `\r`, calls `readLiteralToken` on it and throws `ParserError: Expected literal start, but found ''`. Any CRLF-formatted data file fails to parse on Windows.
+- **Fix**: add `|| char === '\r'` (and consider `'\f'`/`'\v'`).
+- **Confidence**: Confirmed
+
+---
+
+### BIN-22 `resolvePathByArray` mutates the caller's array and mis-truncates the error hint
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/json/resolvePathByArray.js:35` and `:15`
+- **Defect**: (a) `parts.shift()` destructively removes the leading empty segment from the caller-owned array; (b) `buildErrorSuggestions` does `options.splice(0, limit)`, which deletes the **first** 10 keys and keeps the rest, then appends `[... N-10 more options]`. The intent was to keep the first 10.
+- **Failure scenario**: for an object with 15 keys the thrown message lists keys 11–15 and claims "5 more options", while actually hiding 10 — a diagnostic that points at the wrong candidates. Separately, `const p = ["", "a", "b"]; resolvePathByArray(o, p);` leaves the caller holding `["a","b"]`.
+- **Fix**: `options.length = limit;` before the push; and skip the leading empty segment with a local start index instead of `shift()`.
+- **Confidence**: Confirmed
+
+---
+
+### BIN-23 `ObservedInteger` binary round-trip turns ±(2^31−1 / −2^31) into ±Infinity
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/ObservedInteger.js:173-199`
+- **Defect**: `2147483647` and `-2147483648` are used as in-band sentinels for `±Infinity`, and `toBinaryBuffer` writes finite values of exactly those magnitudes unchanged (the source even carries a `//TODO` acknowledging it).
+- **Failure scenario**: `v.set(2147483647); v.toBinaryBuffer(b); b.position = 0; v2.fromBinaryBuffer(b);` → `v2.getValue() === Infinity`. Any stat/counter that legitimately reaches `2^31-1` becomes infinite after a save/load cycle.
+- **Fix**: write a one-byte tag (finite / +inf / -inf) before the int32, or clamp finite writes to `±2147483646`.
+- **Confidence**: Confirmed
+
+---
+
+### BIN-24 `LanguageMetadata.fromJSON` throws on an unknown locale and never sets `locale`
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/localization/LanguageMetadata.js:28-39`; caller `Localization.js:165`
+- **Defect**: (a) the instance `fromJSON` destructures its argument, so `undefined` throws; the caller does `LanguageMetadata.fromJSON(languages_metadata[locale])` from inside a `.then` success handler, where the sibling rejection handler cannot catch it. (b) `fromJSON` never assigns `this.locale`, even though `LocalizationEngine.addLanguageMetadata` keys the registry by `metadata.locale`.
+- **Failure scenario**: `loadLocale('zh-cn')` against the shipped `app/data/database/text/languages.json` (which contains only `en-gb` and `ru`) rejects with `TypeError: Cannot destructure property 'reading_speed' of 'undefined'` instead of falling back to `DEFAULT_LANGUAGE_METADATA`. Separately, every metadata object produced by `fromJSON` registers under the empty-string key, so `LocalizationEngine`'s fallback chain never finds it.
+- **Fix**: default the parameter (`fromJSON(j = {})`) or check for `undefined` at the call site; and pass/assign the locale key.
+- **Confidence**: Confirmed
+
+---
+
+### BIN-25 Reactive literals share a module-level `dummySignal`, leaking every expression that connects to one
+- **Severity**: MINOR
+- **File**: `ReactiveLiteralNumber.js:7,20`, `ReactiveLiteralBoolean.js:6,19`, `ReactiveLiteralString.js:7,16` (all under `core/model/reactive/model/terminal/`)
+- **Defect**: each literal instance assigns the same module-scoped `Signal` to `this.onChanged`. `ReactiveBinaryExpression.connect` / `ReactiveUnaryExpression.connect` then register `(this.update, this)` on that shared signal. The handler entry holds a strong reference to the parent expression, and the signal lives for the lifetime of the module.
+- **Failure scenario**: build and drop expressions containing literals without calling `disconnect()` — e.g. `for (let i = 0; i < 100000; i++) ReactiveAdd.from(ReactiveLiteralNumber.from(1), ReactiveLiteralNumber.from(2));` — all 100 000 `ReactiveAdd` instances remain reachable from the global `dummySignal` and are never collected. `compileReactiveExpression` produces literal-bearing trees on the common path.
+- **Fix**: skip registration when the source signal is the shared dummy (e.g. expose `isConstant` on terminals and have `connect` not subscribe), or give each literal its own lazily-created signal.
+- **Confidence**: Confirmed
+
+---
+
+### BIN-26 `BoundedValue.setLowerLimit` dispatches `onChanged` with no arguments
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/BoundedValue.js:86`
+- **Defect**: every other mutator sends `send4(value, upperLimit, oldValue, oldUpperLimit)`; `setLowerLimit` calls `this.onChanged.dispatch()` with zero arguments.
+- **Failure scenario**: `bv.onChanged.add((value, limit) => bar.width = value / limit); bv.setLowerLimit(5);` → the handler receives `(undefined, undefined)` and sets `bar.width = NaN`, whereas the same handler works for `setValue`/`setUpperLimit`.
+- **Fix**: `this.onChanged.send4(this.__value, this.__limitUpper, this.__value, this.__limitUpper);` (and, per the existing TODO, widen the signature to carry the lower limit).
+- **Confidence**: Confirmed
+
+---
+
+### BIN-27 `number_format_by_thousands` inserts separators inside the fractional part
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/primitives/numbers/number_format_by_thousands.js:13`
+- **Defect**: the regex `\B(?=(\d{3})+(?!\d))` is applied to the whole `toString()` output, including digits after the decimal point.
+- **Failure scenario**: `number_format_by_thousands(1234.5678)` returns `"1,234.5,678"` instead of `"1,234.5678"`. (The in-repo caller `number_pretty_print` always passes an integer, so this only bites external/direct callers of this public util.)
+- **Fix**: split on `.` and apply the grouping regex only to the integer part.
+- **Confidence**: Confirmed
+
+---
+
+### BIN-28 `ExpressionNode.computeMaxParentScore` never computes a max
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/reactive/evaluation/MultiPredicateEvaluator.js:65-85` (bad call at `:77`)
+- **Defect**: two errors in one function. (a) `result = max2(parent.computeMaxParentScore(scoringFunction))` calls the 2-argument `max2` with one argument — `max2(a, undefined)` evaluates `a < undefined` (false) and returns `a`, so the loop just overwrites `result` with the *last* parent's score rather than the maximum. (b) the `n === 0` branch `return`s before `this.__max_parent_score = result`, so root nodes always report a score of 0 from `getScore()`.
+- **Failure scenario**: `evaluator.build([exprA, exprB])` where `exprA`/`exprB` share sub-expressions: every node's `getScore()` returns `0` (roots never assign; children are never visited because `build` only invokes the method on parentless roots). Any future ordering that reads `getScore()` gets a constant.
+- **Fix**: `result = max2(result, parent.computeMaxParentScore(scoringFunction));` and assign `__max_parent_score` on the `n === 0` path before returning.
+- **Confidence**: Confirmed
+
+---
+
+### BIN-29 `Stat.Process.ROUND_DOWN` truncates toward zero and wraps at 2^31
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/stat/Stat.js:302-304`
+- **Defect**: `v | 0` is an int32 truncation, not a floor.
+- **Failure scenario**: a stat driven negative by a debuff — `postprocess = Stat.Process.ROUND_DOWN`, computed value `-2.5` → `-2`, whereas "round down" is `-3`; the stat reads one point *higher* than intended. And a value above 2^31 (e.g. a score of 3 000 000 000) becomes `-1294967296`.
+- **Fix**: `Math.floor(v)`.
+- **Confidence**: Confirmed
+
+---
+
+### BIN-30 `ObservedValue.equals(null)` throws
+- **Severity**: MINOR
+- **File**: `H:/git/moh/app/src/mir-engine/meep/src/core/model/ObservedValue.js:63`
+- **Defect**: the guard `typeof other === 'object'` is clearly meant to reject non-objects, but `typeof null === 'object'`, so `null` passes and `other.__value` dereferences it.
+- **Failure scenario**: `new ObservedValue(1).equals(null)` throws `TypeError: Cannot read properties of null (reading '__value')` instead of returning `false` — which the guard's own existence shows was the intent. Every sibling class (`ObservedBoolean`, `ObservedString`, `ObservedInteger`) has no guard at all and is documented to take an instance, so this one is specifically claiming to handle the case.
+- **Fix**: `return other !== null && typeof other === 'object' && this.__value === other.__value;`
+- **Confidence**: Confirmed
+
+---
+
+## Areas reviewed and found sound (no findings)
+
+- `BinaryBuffer` integer/float read/write pairs, `readUint24`/`writeUint24` (LE and BE), varint encode/decode across 0…2^31−1, `writeBytes`/`readBytes`, `writeASCIIString`.
+- `EncodingBinaryBuffer` string-interning: the `>>> 1` unsigned shift and the odd low-byte discriminator are correct, and the `BiMap` key/value orientation is self-consistent in both directions.
+- `to_half_float_uint16` / `half_to_float_uint16` (including NaN/±Inf/denormal/max-normal paths), `lsb_32` (the de Bruijn multiply is exact because the operand is always a power of two), `msb_32`, `ctz32`, `bitCount`, `reverse_bits_uint32`, `split_by_2`/`split_by_3`, `Base64` (matches upstream base64-js), `base58_encode`, `SmallFloat`, `OffsetAllocator` (faithful port of sebbbi/OffsetAllocator, including the freelist stack discipline).
+- `BitImage2`: `canBlit`'s cross-word guard is provably in-bounds; `or_blit`, `dilate`, `grow_preserving`, `copy_transposed` are correct.
+- `BitSet` core (`nextSetBit`, `nextClearBit`, `previousSetBit`, `cardinality`, `copy`, `reset`, resize/shrink) — the `setRange` inclusive / `clearRange` exclusive asymmetry is real but every in-repo caller compensates for it, and only the JSDoc is contradictory.
+- `path/*` (behaviour is pinned by specs), `codegen/*`, `objectDeepEquals`, `object_deep_clone`, `compareValues`, `ObjectPoolFactory`, `ModuleRegistry`, `Connection`/`Port`/`NodeInstancePortReference`, `serializeNodeGraphToJSON` / `deserializeNodeGraphFromJSON`, `MultiPredicateEvaluator.__resolve_node` short-circuit logic, `inferReactiveExpressionTypes`, `ReactivePegCompiler`, `AbstractCachingParser`, `readStringToken` (the `length - 1` loop bound is correct for every terminator position), `readHexToken`, `readIdentifierToken`, `readReferenceToken`, `string_jaro_distance`/`string_jaro_winkler`, `computeStringHash`, `number_pretty_print`.