@woosh/meep-engine 3.60.4 → 3.60.6

package/src/core/model/reactive/evaluation/PREDICATE_APPLICABILITY_PROPOSAL.md

@@ -1,446 +0,0 @@
-# Predicate applicability in `MultiPredicateEvaluator`
-
-**Status:** implemented — revised after adversarial review (§9) and after implementation (§10)
-**Date:** 2026-08-22
-**Area:** `core/model/reactive/evaluation`, `engine/ecs/dynamic_actions`
-
----
-
-## 1. Symptom
-
-Entering combat produces a cascade of four errors:
-
-```
-CombatScene.js:886  Failed to build unit entity
-                    Error: value 'scope.request' is not found is undefined
-                        at ReactiveReference.evaluate (ReactiveReference.js:136)
-                        at MultiPredicateEvaluator.__resolve_node
-                        at MultiPredicateEvaluator.next
-                        at DynamicActorSystem.matchRule
-                        at DynamicActorSystem.match
-
-CombatScene.js:906  Failed to initialize state management
-                    Error: expected entity_id to be a number, instead was 'undefined'
-                        at EntityComponentDataset.getComponent
-                        at manageCombatState (UnitStateManager.js:410)
-
-dispatchViaProxy.js:24  Failed to dispatch handler __handleUnitStateEntered
-                    Error: expected entity_id to be a number, instead was 'undefined'
-                        at HighlightCurrentTurnCellCombatProcess.processStateEntry
-
-EntityManager.js:576  Failed during update of system 'DynamicActorSystem'
-                    Error: value 'scope.Team.value' is not found is undefined
-```
-
-Only the first is a cause. The rest are consequences.
-
-## 2. Minimal repro
-
-No combat, no ECS, no game code — four lines against the evaluator:
-
-```js
-const ev = new MultiPredicateEvaluator(e => e.computeTreeSize());
-ev.build([compileReactiveExpression('a > 5'), compileReactiveExpression('b < 3')]);
-ev.initialize({ b: 1 });     // 'a' deliberately unbound
-ev.next();
-```
-
-Measured:
-
-| build | result for `{ b: 1 }` |
-|---|---|
-| dev (asserts live) | **throws** `value 'scope.a' is not found`, zero matches |
-| prod (`unassert` strips `assert.defined`) | `[ "( b < 3 )" ]` |
-
-Two things follow. First, dev and prod compute **different rule sets** from the same database and
-the same context. Second, one unbound name anywhere in the database destroys the *entire* match in
-dev: `b < 3` is satisfiable and is never reached.
-
-Production is behaving as intended here. Development is not.
-
-## 3. Causal chain in combat
-
-1. `Entity.build(ecd)` adds components one at a time. `addComponentToEntityByIndex` synchronously
-   runs observers and dispatches `ComponentAdded` per component
-   (`EntityComponentDataset.js:1196`).
-2. `DynamicActor` is added at `UnitMaker.js:204`; `Team` is appended last at `CombatScene.js:878`.
-   The moment `DynamicActor` lands, `AbstractContextSystem` links a `Context` whose `link()`
-   registers an **any-event** listener.
-3. Every subsequent `ComponentAdded` therefore runs a full rule match against an entity that does
-   not yet have `Team`.
-4. `DynamicActorSystem.matchRule` walks the shared predicate database. Predicates referencing
-   `request` (never bound outside a `SendRequest` context) and `Team.value` (not bound on this
-   entity yet) reach `ReactiveReference.evaluate`, which **asserts**.
-5. The throw escapes `Entity.build` mid-loop. The entity is left in the dataset with a **partial
-   component set**, permanently missing `Team` and everything after it — which is why error #4
-   keeps firing on that entity forever.
-6. `CombatScene.handleUnitAdded` catches and continues with `entity === undefined`, then writes
-   that `undefined` into `cell.entity` for every occupied cell.
-
-Step 6 is the open REVIEW_03 item *"`CombatCell.entity` is `undefined` for occupied cells"*. This
-is its repro.
-
-Note what is **not** wrong here. Incremental component addition is `EntityComponentDataset`'s
-contract and `Entity` is syntactic sugar over it. A listener that expects a particular component
-tuple to be present when some *other* component is added is the thing in error, and that
-expectation belongs to the listener.
-
-## 4. Root cause
-
-Two callers disagree about what "this name is not bound in this scope" means.
-
-`ReactiveReference.evaluate` (`ReactiveReference.js:136`) treats it as a programmer error:
-
-```js
-evaluate(scope) {
-    const v = scope[this.name];
-    assert.defined(v, `value 'scope.${this.name}' is not found`);
-    return v;
-}
-```
-
-Its only production caller, `MultiPredicateEvaluator.__resolve_node` (line 358), treats it as
-routine:
-
-```js
-value = expression.evaluate(this.__context);
-
-if (value === undefined) {
-    // value not found
-    this.__invalidate_node(node);
-    return false;
-}
-```
-
-The evaluator's own field documentation agrees with the evaluator (line 126): *"Marks nodes that
-have failed to be evaluated, typically due to unresolved references."*
-
-The assert throws before the caller can ever observe the `undefined` it explicitly checks for.
-**The `if (value === undefined)` branch is dead code in development.** It executes only in
-production, where `rollup-plugin-unassert` (`rollup.config.js:41`) strips the assert.
-
-That dev/prod divergence is why this defect resisted four instrumented runs: instrumentation runs
-unstripped, so the assert masks the very path being observed.
-
-### The contradiction was already noticed once
-
-`MultiPredicateEvaluator.spec.js` carries this helper:
-
-```js
-/**
- * Build a reference that, when evaluated against the test context, yields a defined value whose
- * runtime type does NOT match the reference's declared dataType. Such a reference cannot be
- * resolved by the evaluator (type mismatch -> invalidated) and therefore stands in for an
- * "unresolvable operand" without relying on a missing scope value (which would trip an assert).
- */
-function unresolvableNumberRef(name) { ... }
-```
-
-A previous author needed an unresolvable operand, found that the natural way to express one trips
-the assert, and invented a type-mismatch stand-in rather than resolve the contradiction. The
-conflict is documented in the test suite; it just was never fixed.
-
-### Both failing names are legitimately unbound
-
-- **`request`** — `data.json:83` and friends are *response* rules
-  (`"request == 'combat-turn-start.archetype.Fighter' && ..."`). `request` enters scope only via
-  `SendRequestActionDescription.execute` → `requestBestActors`. For a `ComponentAdded` event it is
-  correctly absent.
-- **`Team.value`** — `EntityProxyScope.resolvePath` yields nothing when the entity has no `Team`.
-  True for context/non-unit `DynamicActor` entities, and for the unit itself mid-build.
-
-### Evidence of intended semantics
-
-`DynamicRuleDescriptionTable` gates on binding before evaluating, at `matchBest` (line 100) and
-`match` (line 137):
-
-```js
-const references = rule.references;
-
-for (let i = 0; i < n; i++) {
-    if (context[references[i].name] === undefined) {
-        continue main;              // rule does not apply to this scope
-    }
-}
-
-const isMatch = rule.condition.evaluate(context);   // only now
-```
-
-and its spec pins it: `test("match skips rules when context is missing needed property for
-evaluation", ...)`, `expect(table.matchBest({})).toBeUndefined()`.
-
-This is evidence of *intent*, not settled precedent — neither `match` nor `matchBest` has a
-production caller (see §9, F1). The load-bearing conclusion is narrower and does not depend on
-them: **an expression must not be evaluated against a scope that does not bind its references**,
-and the check belongs before `evaluate`, not inside it.
-
-## 5. Proposal
-
-### R1 — Gate on binding inside `__resolve_node`, before `evaluate`
-
-Add a binding query to `ReactiveReference` and consult it first:
-
-```js
-// ReactiveReference
-/**
- * Whether this reference resolves to a value in the given scope. Asking is how a caller avoids
- * evaluating an expression that does not apply to the scope it is being matched against;
- * `evaluate` remains strict and treats an unbound name as a broken precondition.
- * @param {Object} scope
- * @returns {boolean}
- */
-isBound(scope) {
-    return scope[this.name] !== undefined;
-}
-```
-
-```js
-// MultiPredicateEvaluator.__resolve_node
-if (expression.isReference) {
-
-    if (!expression.isBound(this.__context)) {
-        // reference is not bound in this scope - the node cannot apply here
-        this.__invalidate_node(node);
-
-        return false;
-    }
-
-    value = expression.evaluate(this.__context);
-    // ... type check unchanged
-}
-```
-
-`undefined` never enters the expression algebra, `ReactiveReference.evaluate` keeps its assert
-verbatim, and the assert becomes meaningful: it now fires only when a caller evaluated without
-gating, which is a real bug.
-
-This is **exactly behaviour-preserving against production**. Production reaches
-`__invalidate_node` precisely when `scope[name]` is `undefined`; so does R1, by construction — the
-two read the same scope through the same accessor.
-
-### R2 — *(withdrawn during implementation — see §10)*
-
-An earlier revision routed the binding query through `name in scope` and therefore required `has`
-traps on `DataScope`, `EntityProxyScope` and `make_blackboard_proxy`, none of which answer `in`
-correctly today. Implementing R1 showed the traps are not merely extra work but actively wrong for
-this purpose: `in` and `!== undefined` disagree on a frame that binds a name *to* `undefined`, and
-on that input an `in`-based gate would let `evaluate` be called on an unbound name — reintroducing
-the crash it exists to prevent. The value probe above has no such gap and needs no new protocol.
-
-### R3 — Make the evaluator self-correcting across matches
-
-`initialize()` resets `evaluated` and the cursor; only `finalize()` resets `invalidated`
-(line 484), and `matchRule` calls it unguarded:
-
-```js
-evaluator.initialize(context);
-for (;;) { const predicate = evaluator.next(); ... }
-evaluator.finalize();   // skipped when next() throws
-```
-
-A throw escaping `next()` leaves stale invalidations that silently suppress later matches.
-**Demonstrated**, not theorised:
-
-```
-run 1: type-mismatched 'bad' invalidates p1; a throwing scope getter aborts the loop
-run 2: clean context { bad: 50, boom: 5 } - both predicates are TRUE
-       matches: ["( boom > 0 )"]                      <-- p1 silently dropped
-control (after finalize() ran):
-       matches: ["( ( bad > 1 ) && ( bad < 100 ) )", "( boom > 0 )"]
-```
-
-Wrong answers, no error, persisting for the life of the evaluator. Fix: `initialize()` establishes
-the complete starting state, resetting `invalidated` there rather than depending on `finalize()`
-having run. `finalize()` keeps a real job — releasing the scope, which is commonly a proxy over a
-live frame that a finished evaluator must not keep reachable.
-
-No `try/finally` in `matchRule`. Once `initialize()` owns the reset there is nothing left for it to
-protect: a skipped `finalize()` retains one scope reference until the next match and cannot corrupt
-a result. Guarding that would be guarding a condition that can no longer happen.
-
-This is independent of R1 and stands on its own — it is a silent-wrong-answer bug and a one-line
-fix. R1 removes the throw that triggers it today; R3 removes the class.
-
-### R4 — Stop `CombatScene.handleUnitAdded` laundering failures into a corrupt board
-
-Three `try`/`catch` blocks each swallow and continue with the state the failure produced:
-
-- around `makeUnit` — leaves `entityBuilder` `undefined`, so the next line throws anyway, with a
-  worse message than the error that was caught;
-- around `entityBuilder.build(ecd)` — leaves `entity` `undefined`, which then reaches
-  `manageCombatState` **and** `cell.entity`;
-- around `manageCombatState` — hides a genuine wiring failure.
-
-All three go. `Signal.send4` already isolates a throwing handler (`Signal.js:615`), so the failure
-is reported there and the rest of the dispatch survives; what changes is that `handleUnitAdded`
-stops running on past the failure and writing a non-entity into the board. `cells.forEach` also
-moves ahead of `manageCombatState`, so the cells are populated as soon as there is a real entity to
-put in them.
-
-This does not make a failed unit fail the *scene* — `Signal` catches by design and that design is
-not this change's business. It makes a failed unit stop corrupting the board.
-
-## 6. Tests
-
-- `MultiPredicateEvaluator.spec.js` — the §2 repro as a test: a predicate over an unbound name does
-  not match and does not throw, while a co-resident satisfiable predicate still matches; the same
-  name matches in scopes that do bind it. Plus the R3 leak repro: an exception escaping `next()`
-  must not change the result of the following match.
-- `ReactiveReference.spec.js` — `isBound` reports absence, treats `0`/`false`/`''` as bound, and
-  reads through a scope that resolves names dynamically rather than as own properties.
-- `EntityProxyScope.spec.js` — a component path is unbound until the entity has the component, and
-  resolves through the component's getter once it does.
-- `DataScope.spec.js` — the combat failure end to end: a rule database matched against a real
-  entity scope skips the rules the scope cannot supply, and picks up the `Team` rule the moment the
-  component lands.
-
-No `evaluate`-throws-on-unbound test: `assert` is stripped from production builds, so a rejection
-test would pin behaviour that does not exist in the shipped artifact.
-
-The existing short-circuit suite in `MultiPredicateEvaluator.spec.js` must pass unchanged. It pins
-node-level resolvability semantics, which R1 deliberately does not touch.
-
-## 7. Deferred
-
-- **Unifying `match` / `matchBest` with the evaluator.** They duplicate gate-then-evaluate and can
-  drift from it, but neither has a production caller and meep is a library, so they are public
-  surface to keep rather than churn. Worth doing as its own change with its own justification; it
-  is not part of fixing this crash.
-- **Predicate-level applicability gating** (skip a whole predicate when any of its references is
-  unbound, per `rule.references`). See §9, F3: it changes matching semantics, is not needed for the
-  crash, and is behaviourally inert on the current rule data.
-
-## 8. Explicitly rejected
-
-- **Making `ReactiveReference.evaluate` return `undefined`.** This turns `undefined` into a value in
-  the expression algebra: every operator must learn to propagate it, every consumer must handle it,
-  and the assert dies. It opens the floodgate instead of containing the problem. R1 achieves the
-  same outcome with the containment intact — the question "is this bound?" is asked and answered
-  before evaluation, and never becomes a value.
-- **Making `Entity.build` atomic w.r.t. observers.** `Entity` is syntactic sugar over
-  `EntityComponentDataset`; the incremental add flow is correct. Expecting a given component tuple
-  to be present when some other component is added is the error, and it belongs to the consumer that
-  expects it — not to `Entity`.
-
----
-
-## 9. Adversarial review
-
-Reviewed against three questions: is it principled, does it damage the engine, is it the simplest
-thing that works. The proposal that entered review is preserved here as **P1–P4**; §5 is the
-revised outcome.
-
-> **P1** intern reference names, give each predicate a `BitSet` of required names, gate whole
-> predicates in `next()` with a per-match probe cache.
-> **P2** delete the `value === undefined` branch as unreachable.
-> **P3** adopt `match`/`matchBest`'s all-references-must-be-bound semantics across the evaluator.
-> **P4** collapse the three matching paths onto one.
-
-### Is it a principled fix?
-
-**F1 — "the contract already exists, twice" was an appeal to incumbency.** *Confirmed.* `match` and
-`matchBest` have no production callers; grep finds only `DynamicRuleDescriptionTable.spec.js`. The
-original draft leaned on them as settled precedent. They are evidence of *intent* — reinforced by
-their specs — but they are not a shipped contract, and "be consistent with two unused functions"
-cannot by itself justify changing a hot path. §4 now states this explicitly and rests the argument
-on the narrower claim instead.
-
-**F2 — stronger evidence existed and was missed.** The `unresolvableNumberRef` helper in
-`MultiPredicateEvaluator.spec.js` documents a previous author hitting this exact contradiction and
-routing around it. That is far better evidence than the incumbency argument. Added to §4.
-
-**F3 — P3 was a semantics change dressed as a fix.** *Upheld; P3 dropped.* It is not required to
-fix the crash. On the actual data it buys nothing: of 89 rule conditions only 5 contain `||`, all
-of the shape `(count == 1 && Team.value == 0) || (count == 1 && Team.value == 1)`, where both
-branches reference `Team.value` — so predicate-level gating and short-circuiting agree on every one
-of them. It would have been a hard-to-reason-about behaviour change with no demonstrated benefit.
-
-**Diagnosis survived.** The dev/prod divergence is now measured (§2) rather than argued, and the
-repro is four lines with no game code in it.
-
-### Does it damage the engine?
-
-**F4 — P1 pushed consumer policy into a core class.** *Partly upheld.* Reference-set interning and
-per-predicate requirement bitsets are `dynamic_actions` shaped, added permanently to
-`core/model/reactive` for one consumer. R1's binding query is the general form of the same idea
-("do not evaluate an expression against a scope that does not bind its references") and adds one
-predicate-free method to `ReactiveReference`.
-
-**F5 — P2 was the most damaging item in the document.** *Upheld; P2 dropped.* The
-`value === undefined` branch is only unreachable if *every* caller gates. `MultiPredicateEvaluator`
-is public library surface and its own spec calls `initialize()` with plain objects; deleting the
-branch converts a handled condition into a crash for any ungated caller. R1 does not delete it — it
-**re-roots** it, reaching the same `__invalidate_node` via a binding query instead of by inspecting
-`evaluate`'s return value. Same handling, sound trigger.
-
-**F6 — the proposal was not implementable as written.** *Upheld.* Every variant needs to ask a scope
-whether a name is bound, and no scope can answer today. Measured: `'a' in dataScope.proxy` is
-`false` for a bound name, `'stack' in dataScope.proxy` is `true`, `'contains' in blackboardProxy` is
-`true`. P1 would have silently gated on the host object's shape. The review's conclusion — add the
-missing `has` traps — was itself superseded during implementation: the right answer is not to use
-`in` at all. See §10.
-
-**F7 — P4 churned public API for no defect.** *Upheld; moved to §7 Deferred.*
-
-### KISS
-
-**F8 — a materially smaller fix does the same job.** *Upheld; this is now R1.* Gating at the node
-level inside `__resolve_node` is roughly four lines and subsumes P1, P2 and P3:
-
-| | P1–P4 | R1 |
-|---|---|---|
-| name interning + per-predicate bitsets | yes | no |
-| per-match probe cache | yes | no |
-| semantics decision required (F3) | yes | no |
-| existing short-circuit tests | need re-reasoning | pass unchanged |
-| `match` / `matchBest` touched | yes | no |
-| behaviour vs production | changes it | provably identical |
-
-The one thing P1 had that R1 does not is skipping a predicate's DAG walk wholesale. That is a
-performance argument, and see F9.
-
-**F9 — the probe cache was premature optimisation.** *Upheld; dropped.* 89 rules, 84 distinct
-conditions, and the evaluator already memoises per node through `evaluated`/`invalidated`. No
-measurement was offered for the claim that gating is "cheaper than today". Work, right, fast — in
-that order.
-
-### Net effect of the review
-
-Four of the five original items were dropped or deferred. What survives is: gate before evaluating
-(R1), make the scopes answerable (R2), stop the evaluator carrying state across matches (R3), stop
-the combat scene laundering failures (R4). R3 gained a working repro during review and is
-independent of the rest.
-
----
-
-## 10. Implementation record
-
-Landed as R1, R3 and R4. R2 was withdrawn.
-
-**R2 did not survive contact with the code.** The review concluded that a binding query needs `has`
-traps because `in` is broken on all three scope proxies. Writing R1 showed the premise was wrong:
-`in` is the incorrect operator here regardless of whether the traps exist. `in` and `!== undefined`
-diverge on a frame that binds a name *to* `undefined`, and on that input an `in`-based gate reports
-"bound" and hands `evaluate` an unbound name — the exact crash the gate exists to prevent. The value
-probe has no such gap, needs no new protocol, and matches what `DynamicRuleDescriptionTable`'s gate
-has always done. Three files of new trap code went away and the fix got smaller.
-
-The broken `in` behaviour on `DataScope`, `EntityProxyScope` and `make_blackboard_proxy` is real and
-was measured, but nothing uses `in` on those proxies. Fixing it is speculative work on an unused
-path and is deliberately not part of this change.
-
-**No `try`/`finally` in `matchRule`.** Once `initialize()` establishes complete state, a skipped
-`finalize()` cannot affect a result — see R3.
-
-**Verified.** The two gate tests were written first and failed with the reported production error
-(`value 'scope.a' is not found`) before R1 existed. The `DataScope` end-to-end test was confirmed
-non-vacuous by neutralising `isBound` and observing the original failure return verbatim:
-`value 'scope.request' is not found`. Full regression over `engine/ecs`, `core/model` and
-`core/lang`: 130 files, 884 tests, green — including the pre-existing short-circuit suite, which R1
-does not touch.
-
-**Not done, still open:** the deferred items in §7, and the residual noted in §3 — rule matching
-still runs on every `ComponentAdded` during `Entity.build`, several times per unit. That is wasted
-work and it lets a rule fire against a partially-populated entity. R1 makes it harmless rather than
-fatal; whether actors should be matching at all mid-build is a separate design question about
-`DynamicActorSystem`, not about `Entity`.