test(rete): port pararules golden tests; tag Phase 1 parity (P1.14)

10 integration tests in packages/rete/tests/golden/ manually wire
AlphaNode → BetaMemory → JoinNode → ProductionNode chains and drive
them via Session.insert/retract. Each test maps to a pararules Nim
reference test (documented in GOLDEN-MAP.md).

Coverage: packages/rete/src at 96.8% statements / 95.4% branch /
97.8% functions — all well above the 90% Phase 1 gate.

Tests: 227 total (166 pre-existing + 61 new golden), all green.

packages/rete/tests/golden/GOLDEN-MAP.md

@@ -0,0 +1,89 @@
+# Golden Test Map
+
+Maps each golden integration test to its pararules origin in the Nim reference implementation.
+Source: https://github.com/paranim/pararules
+
+## Overview
+
+These tests manually wire Rete II network components (AlphaNode → BetaMemory → JoinNode →
+ProductionNode) via the Session's internal accessors (`_getAlpha()`, `_getWM()`), then insert/
+retract facts via `Session.insert/retract` to drive the alpha dispatch pipeline. This proves
+component interoperability at the integration level while the full `Session.add()` auto-wiring
+is pending (Phase 2).
+
+---
+
+## Test Map
+
+| File | Test Suite | Core Assertion | Pararules Origin | Nim File / Line |
+|------|------------|---------------|-----------------|-----------------|
+| `g1-single-condition.test.ts` | G1 — single-condition match | Insert (id, Health, 42) → 1 match with hp=42 | `tests/test2.nim` "queries" `getPerson` rule (single what-condition) | test2.nim ~1-30 |
+| `g2-two-condition-join.test.ts` | G2 — two-condition join (same entity) | `(?id, X, ?x) ∧ (?id, Y, ?y)` → 1 match per complete entity | `tests/test2.nim` "joins and advanced queries" `getCharacter` rule | test2.nim ~60-90 |
+| `g3-derived-facts.test.ts` | G3 — derived facts (truth maintenance) | Insert X=5 → derived Double=10; Retract → Double disappears | `tests/test2.nim` "derived facts" `thenFinally` block | test2.nim ~95-130 |
+| `g4-multiple-entities.test.ts` | G4 — multiple entities wildcard | N entities with Health → N matches | `tests/test1.nim` "number of conditions != number of facts" (Xavier/Thomas/George Height entities) | test1.nim ~1-40 |
+| `g5-filter-predicate.test.ts` | G5 — filter predicate (cond) | Health=100 passes `hp > 50`; Health=10 filtered out | `tests/test2.nim` "complex types" `stopPlayer` with `cond: x >= windowWidth` | test2.nim ~10-50 |
+| `g6-conflict-resolution.test.ts` | G6 — conflict resolution ordering | `orderActivations` sorts by salience↓ → specificity↓ → addedAt↑ | `tests/test2.nim` "recursion limit" (rule cascade order) + SPEC §Conflict Resolution | test2.nim ~130-160 |
+| `g7-serialization.test.ts` | G7 — serialization round-trip | `defineRule → serialize → JSON → deserialize` → equivalent `RuleDefinition` | `tests/test3.nim` `staticRuleset` (compile-time rule serialization analogue) | test3.nim ~1-40 |
+| `g8-variable-binding-chain.test.ts` | G8 — variable binding 3-condition chain | `(?eid, Type, ?t) ∧ (?eid, Health, ?hp) ∧ (?eid, Position, ?pos)` → idEquality through chain | `tests/test1.nim` "adding facts out of order" (multi-condition, deep binding) | test1.nim ~42-80 |
+| `g9-retraction.test.ts` | G9 — retraction removes match | Insert → match; Retract → no match; Re-insert → match again | `tests/test1.nim` "removing facts" (retract clears queryAll) | test1.nim ~82-110 |
+| `g10-cycle-detection.test.ts` | G10 — cycle detection / recursion limit | `fireRules()` at depth ≥ limit throws `RecursionLimitExceededError` | `tests/test2.nim` "recursion limit" (rule1→rule2→rule3 cascade loop) | test2.nim ~130-160 |
+
+---
+
+## Pararules API → TypeScript Engine Mapping
+
+| Pararules construct | TypeScript equivalent |
+|---------------------|-----------------------|
+| `initSession(Fact)` | `new Session({ autoFire: false })` |
+| `session.add(rule)` | Manual network wiring via `_getAlpha().buildNode()` |
+| `session.insert(id, attr, val)` | `session.insert(id as EntityId, attr, val)` |
+| `session.retract(id, attr)` | `session.retract(id as EntityId, attr)` |
+| `session.queryAll(rule).len` | `prod.matches.length` |
+| `session.query(rule).field` | `query(prod)["field"]` |
+| `what: (id, Attr, var)` | `alphaNode.buildNode({id: null, attr: "Attr"})` + `JoinNode(…, "var", "id")` |
+| `cond: expr` | `FilterNode([{predicate: "name", args: [...]}], predicateRegistry)` |
+| `thenFinally: session.insert(…)` | `DerivedFactProduction(ruleName, wm, handler)` |
+| salience on rules | `defineRule({salience: N, …})` + `orderActivations([…])` |
+| recursion limit error | `RecursionLimitExceededError` from `session.fireRules()` |
+| JSON rule schema | `serialize(rule)` / `deserialize(json, registry)` |
+
+---
+
+## Network Wiring Pattern
+
+All golden tests follow this manual wiring pattern (since `Session.add()` auto-wiring is Phase 2):
+
+```typescript
+// 1. Create Session (WM↔AlphaNetwork already wired internally)
+const session = new Session({ autoFire: false });
+const alpha = session._getAlpha();
+
+// 2. Root BetaMemory with seed token (drives first join)
+const rootMem = new BetaMemory();
+rootMem.leftActivate(new Token(null, ROOT_FACT, {}));
+
+// 3. Alpha node for each condition
+const alphaNode = alpha.buildNode({ id: null, attr: "Health" });
+
+// 4. JoinNode connecting left memory and alpha memory
+const join = new JoinNode(rootMem, alphaNode.memory, [], "hp", "eid");
+
+// 5. Wire alpha → join right side
+alphaNode.onActivate((id, attr, value) => join.rightActivate(id, attr, value));
+alphaNode.onDeactivate((id, attr, value) => join.rightDeactivate(id, attr, value));
+
+// 6. Wire join → ProductionNode
+const prod = new ProductionNode("ruleName");
+join.addDownstreamActivate(prod.leftActivate.bind(prod));
+join.addDownstreamDeactivate(prod.leftDeactivate.bind(prod));
+
+// 7. Insert facts via Session — flows WM → Alpha → JoinNode → ProductionNode
+session.insert(e1, "Health", 100);
+
+// 8. Assert
+expect(prod.matches).toHaveLength(1);
+```
+
+For multi-condition rules, intermediate `BetaMemory` nodes connect joins in a chain,
+with each downstream `BetaMemory` forwarding new tokens to the next `JoinNode` via
+`addDownstreamActivate(nextJoin.leftActivate.bind(nextJoin))`.

packages/rete/tests/golden/g1-single-condition.test.ts

@@ -0,0 +1,121 @@
+/**
+ * G1 — Single-condition match
+ *
+ * Pararules origin: tests/test1.nim "removing facts" (single-condition pattern)
+ * and tests/test2.nim "queries" rule getPerson with one what-condition.
+ *
+ * Nim equivalent:
+ *   rule getHealth(Fact):
+ *     what:
+ *       (id, Health, hp)
+ *   session.insert(player1, Health, 42)
+ *   check session.query(rules.getHealth).hp == 42
+ *
+ * We manually wire:
+ *   root BetaMemory → JoinNode(alphaHealth) → ProductionNode
+ *
+ * The Session's WM→AlphaNetwork is already wired internally; we attach
+ * additional listeners to route alpha activations into our JoinNode.
+ */
+import { describe, it, expect } from "vitest";
+import { Session } from "../../src/session.js";
+import { BetaMemory } from "../../src/beta.js";
+import { Token } from "../../src/beta.js";
+import { JoinNode } from "../../src/join.js";
+import { ProductionNode, query, queryAll, NoMatchError } from "../../src/query.js";
+import type { EntityId } from "../../src/schema.js";
+import type { TokenFact } from "../../src/beta.js";
+
+const ROOT_FACT: TokenFact = { id: 0 as EntityId, attr: "__root", value: null };
+
+function buildSingleConditionNetwork(attrKey: string) {
+  const session = new Session({ autoFire: false });
+  const alpha = session._getAlpha();
+
+  // Root BetaMemory seeded with a dummy token (seeds the first join)
+  const rootMem = new BetaMemory();
+  const rootToken = new Token(null, ROOT_FACT, {});
+  rootMem.leftActivate(rootToken);
+
+  // Alpha node for our attribute (wildcard entity id)
+  const alphaNode = alpha.buildNode({ id: null, attr: attrKey });
+
+  // JoinNode: binds value → "val", entity id → "eid"
+  const join = new JoinNode(rootMem, alphaNode.memory, [], "val", "eid");
+
+  // Wire alpha → join (right side)
+  alphaNode.onActivate((id, attr, value) => join.rightActivate(id, attr, value));
+  alphaNode.onDeactivate((id, attr, value) => join.rightDeactivate(id, attr, value));
+
+  // ProductionNode collects full matches
+  const prod = new ProductionNode("singleCondRule");
+  join.addDownstreamActivate(prod.leftActivate.bind(prod));
+  join.addDownstreamDeactivate(prod.leftDeactivate.bind(prod));
+
+  return { session, prod };
+}
+
+describe("G1 — single-condition match", () => {
+  it("inserts one fact → production has exactly 1 match with correct binding", () => {
+    const { session, prod } = buildSingleConditionNetwork("Health");
+
+    const e1 = session.nextId();
+    session.insert(e1, "Health", 42);
+
+    expect(prod.matches).toHaveLength(1);
+    expect(prod.matches[0]?.bindings["val"]).toBe(42);
+    expect(prod.matches[0]?.bindings["eid"]).toBe(e1);
+  });
+
+  it("query() returns the single match bindings", () => {
+    const { session, prod } = buildSingleConditionNetwork("Health");
+
+    const e1 = session.nextId();
+    session.insert(e1, "Health", 100);
+
+    const bindings = query(prod);
+    expect(bindings["val"]).toBe(100);
+  });
+
+  it("queryAll() returns all matches", () => {
+    const { session, prod } = buildSingleConditionNetwork("Health");
+
+    const e1 = session.nextId();
+    const e2 = session.nextId();
+    session.insert(e1, "Health", 10);
+    session.insert(e2, "Health", 20);
+
+    const all = queryAll(prod);
+    expect(all).toHaveLength(2);
+  });
+
+  it("query() throws NoMatchError when no facts present", () => {
+    const { prod } = buildSingleConditionNetwork("Health");
+    expect(() => query(prod)).toThrow(NoMatchError);
+  });
+
+  it("two attributes produce independent matches (no cross-join)", () => {
+    const { session, prod: prodHealth } = buildSingleConditionNetwork("Health");
+    const { prod: prodPos } = (() => {
+      const alpha = session._getAlpha();
+      const rootMem = new BetaMemory();
+      const rootToken = new Token(null, ROOT_FACT, {});
+      rootMem.leftActivate(rootToken);
+      const alphaNode = alpha.buildNode({ id: null, attr: "Position" });
+      const join = new JoinNode(rootMem, alphaNode.memory, [], "val", "eid");
+      alphaNode.onActivate((id, attr, value) => join.rightActivate(id, attr, value));
+      alphaNode.onDeactivate((id, attr, value) => join.rightDeactivate(id, attr, value));
+      const prod = new ProductionNode("posRule");
+      join.addDownstreamActivate(prod.leftActivate.bind(prod));
+      join.addDownstreamDeactivate(prod.leftDeactivate.bind(prod));
+      return { prod };
+    })();
+
+    const e1 = session.nextId();
+    session.insert(e1, "Health", 50);
+    session.insert(e1, "Position", "e4");
+
+    expect(prodHealth.matches).toHaveLength(1);
+    expect(prodPos.matches).toHaveLength(1);
+  });
+});

packages/rete/tests/golden/g10-cycle-detection.test.ts

@@ -0,0 +1,101 @@
+/**
+ * G10 — Cycle detection (recursion limit)
+ *
+ * Pararules origin: tests/test2.nim "recursion limit":
+ *   test "recursion limit":
+ *     let rules =
+ *       ruleset:
+ *         rule rule1(Fact): what: (Alice, Color, color) then: insert(Alice, Height, 15)
+ *         rule rule2(Fact): what: (Alice, Height, h)   then: insert(Alice, Age, 10)
+ *         rule rule3(Fact): what: (Alice, Age, age)    then: insert(Alice, Color, "blue")
+ *         rule rule4(Fact): ...
+ *   # This creates an infinite cascade — pararules detects and throws
+ *
+ * Our engine detects infinite recursion via a depth counter in Session.fireRules().
+ * When fireRules() is re-entered while already executing (depth ≥ limit),
+ * it throws RecursionLimitExceededError.
+ *
+ * Since fireRules() is currently a stub (returns 0), we test the guard
+ * directly by manipulating the internal depth counter, which is intentionally
+ * exposed via the underscore-prefixed `_fireDepth` field.
+ */
+import { describe, it, expect } from "vitest";
+import { Session } from "../../src/session.js";
+import { RecursionLimitExceededError } from "../../src/cycle.js";
+
+describe("G10 — cycle detection (recursion limit)", () => {
+  it("fireRules() at depth ≥ limit throws RecursionLimitExceededError", () => {
+    const session = new Session({ recursionLimit: 3, autoFire: false });
+
+    // Simulate being already at the recursion limit
+    session._fireDepth = 3;
+
+    expect(() => session.fireRules()).toThrow(RecursionLimitExceededError);
+  });
+
+  it("RecursionLimitExceededError carries the depth at which it fired", () => {
+    const session = new Session({ recursionLimit: 5, autoFire: false });
+    session._fireDepth = 5;
+
+    let caught: RecursionLimitExceededError | undefined;
+    try {
+      session.fireRules();
+    } catch (e) {
+      if (e instanceof RecursionLimitExceededError) caught = e;
+    }
+    expect(caught).toBeDefined();
+    expect(caught?.depth).toBe(5);
+  });
+
+  it("error message includes depth information", () => {
+    const session = new Session({ recursionLimit: 2, autoFire: false });
+    session._fireDepth = 2;
+
+    expect(() => session.fireRules()).toThrow(/2/);
+  });
+
+  it("fireRules() succeeds when depth is below the limit", () => {
+    const session = new Session({ recursionLimit: 10, autoFire: false });
+    session._fireDepth = 9;
+
+    // Should NOT throw — 9 < 10
+    expect(() => session.fireRules()).not.toThrow();
+  });
+
+  it("recursionLimit: 0 disables the guard (unlimited depth)", () => {
+    const session = new Session({ recursionLimit: 0, autoFire: false });
+    session._fireDepth = 9999;
+
+    // limit=0 means "disabled" — never throws regardless of depth
+    expect(() => session.fireRules()).not.toThrow();
+  });
+
+  it("fireRules() increments depth and decrements on exit (balanced)", () => {
+    const session = new Session({ recursionLimit: 64, autoFire: false });
+    expect(session._fireDepth).toBe(0);
+
+    session.fireRules();
+    // After normal return, depth should be back to 0
+    expect(session._fireDepth).toBe(0);
+  });
+
+  it("depth is decremented even when RecursionLimitExceededError is thrown", () => {
+    const session = new Session({ recursionLimit: 1, autoFire: false });
+    session._fireDepth = 1;
+
+    expect(() => session.fireRules()).toThrow(RecursionLimitExceededError);
+    // Throws before incrementing, so _fireDepth stays at 1 (set by us)
+    // and is not cleaned up (guard fires before the try block)
+    expect(session._fireDepth).toBe(1);
+  });
+
+  it("custom per-call recursionLimit overrides session default", () => {
+    const session = new Session({ recursionLimit: 100, autoFire: false });
+    session._fireDepth = 3;
+
+    // Override with a tighter limit in this specific call
+    expect(() => session.fireRules({ recursionLimit: 2 })).toThrow(
+      RecursionLimitExceededError,
+    );
+  });
+});

packages/rete/tests/golden/g2-two-condition-join.test.ts

@@ -0,0 +1,139 @@
+/**
+ * G2 — Two-condition join (same entity)
+ *
+ * Pararules origin: tests/test1.nim "duplicate facts" / "removing facts",
+ * tests/test2.nim "queries" rule getCharacter:
+ *   rule getCharacter(Fact):
+ *     what:
+ *       (id, X, x)
+ *       (id, Y, y)
+ *
+ * Demonstrates idEquality join: a variable bound as the entity id in
+ * condition 1 constrains which facts match in condition 2 (same entity).
+ *
+ * Network wired manually:
+ *   root → join1(alphaX) → betaMem1 → join2(alphaY, idEquality:"eid") → prod
+ */
+import { describe, it, expect } from "vitest";
+import { Session } from "../../src/session.js";
+import { BetaMemory } from "../../src/beta.js";
+import { Token } from "../../src/beta.js";
+import { JoinNode } from "../../src/join.js";
+import { ProductionNode } from "../../src/query.js";
+import type { EntityId } from "../../src/schema.js";
+import type { JoinTest } from "../../src/join.js";
+import type { TokenFact } from "../../src/beta.js";
+
+const ROOT_FACT: TokenFact = { id: 0 as EntityId, attr: "__root", value: null };
+
+function buildTwoConditionNetwork() {
+  const session = new Session({ autoFire: false });
+  const alpha = session._getAlpha();
+
+  // Root memory with dummy token
+  const rootMem = new BetaMemory();
+  rootMem.leftActivate(new Token(null, ROOT_FACT, {}));
+
+  // Alpha nodes for X and Y
+  const alphaX = alpha.buildNode({ id: null, attr: "X" });
+  const alphaY = alpha.buildNode({ id: null, attr: "Y" });
+
+  // Intermediate beta memory between join1 and join2
+  const betaMem1 = new BetaMemory();
+
+  // join1: root × alphaX — binds x and eid
+  const join1 = new JoinNode(rootMem, alphaX.memory, [], "x", "eid");
+
+  // join2: betaMem1 × alphaY — idEquality on "eid", binds y
+  const idEqTest: JoinTest = { type: "idEquality", leftVar: "eid" };
+  const join2 = new JoinNode(betaMem1, alphaY.memory, [idEqTest], "y", null);
+
+  // Wire join1 → betaMem1
+  join1.addDownstreamActivate(betaMem1.leftActivate.bind(betaMem1));
+  join1.addDownstreamDeactivate(betaMem1.leftDeactivate.bind(betaMem1));
+
+  // Wire betaMem1 → join2 (propagate new partial matches)
+  betaMem1.addDownstreamActivate(join2.leftActivate.bind(join2));
+  betaMem1.addDownstreamDeactivate(join2.leftDeactivate.bind(join2));
+
+  // Wire alpha events → join right sides
+  alphaX.onActivate((id, attr, value) => join1.rightActivate(id, attr, value));
+  alphaX.onDeactivate((id, attr, value) => join1.rightDeactivate(id, attr, value));
+  alphaY.onActivate((id, attr, value) => join2.rightActivate(id, attr, value));
+  alphaY.onDeactivate((id, attr, value) => join2.rightDeactivate(id, attr, value));
+
+  // ProductionNode
+  const prod = new ProductionNode("xyRule");
+  join2.addDownstreamActivate(prod.leftActivate.bind(prod));
+  join2.addDownstreamDeactivate(prod.leftDeactivate.bind(prod));
+
+  return { session, prod };
+}
+
+describe("G2 — two-condition join (same entity)", () => {
+  it("entity with both X and Y produces exactly 1 match", () => {
+    const { session, prod } = buildTwoConditionNetwork();
+
+    const e1 = session.nextId();
+    session.insert(e1, "X", 3);
+    session.insert(e1, "Y", 4);
+
+    expect(prod.matches).toHaveLength(1);
+    expect(prod.matches[0]?.bindings["x"]).toBe(3);
+    expect(prod.matches[0]?.bindings["y"]).toBe(4);
+    expect(prod.matches[0]?.bindings["eid"]).toBe(e1);
+  });
+
+  it("entity with only X does not match (missing Y)", () => {
+    const { session, prod } = buildTwoConditionNetwork();
+
+    const e1 = session.nextId();
+    session.insert(e1, "X", 10);
+    // no Y fact for e1
+
+    expect(prod.matches).toHaveLength(0);
+  });
+
+  it("two entities: only the complete one matches", () => {
+    const { session, prod } = buildTwoConditionNetwork();
+
+    const e1 = session.nextId();
+    const e2 = session.nextId();
+
+    // e1 has both X and Y
+    session.insert(e1, "X", 1);
+    session.insert(e1, "Y", 2);
+
+    // e2 has only X
+    session.insert(e2, "X", 99);
+
+    expect(prod.matches).toHaveLength(1);
+    expect(prod.matches[0]?.bindings["eid"]).toBe(e1);
+  });
+
+  it("two complete entities produce 2 matches", () => {
+    const { session, prod } = buildTwoConditionNetwork();
+
+    const e1 = session.nextId();
+    const e2 = session.nextId();
+    session.insert(e1, "X", 1);
+    session.insert(e1, "Y", 2);
+    session.insert(e2, "X", 10);
+    session.insert(e2, "Y", 20);
+
+    expect(prod.matches).toHaveLength(2);
+  });
+
+  it("order of insert (X then Y, or Y then X) does not matter", () => {
+    const { session, prod } = buildTwoConditionNetwork();
+
+    const e1 = session.nextId();
+    // Insert Y before X
+    session.insert(e1, "Y", 99);
+    session.insert(e1, "X", 77);
+
+    expect(prod.matches).toHaveLength(1);
+    expect(prod.matches[0]?.bindings["x"]).toBe(77);
+    expect(prod.matches[0]?.bindings["y"]).toBe(99);
+  });
+});

packages/rete/tests/golden/g3-derived-facts.test.ts

@@ -0,0 +1,127 @@
+/**
+ * G3 — Derived facts (truth maintenance)
+ *
+ * Pararules origin: tests/test2.nim "derived facts" (thenFinally block):
+ *   rule getCharacter(Fact):
+ *     what:
+ *       (id, X, x)
+ *       (id, Y, y)
+ *     thenFinally:
+ *       let chars = session.queryAll(this)
+ *       session.insert(Derived, AllCharacters, chars)
+ *
+ * Our equivalent uses DerivedFactProduction, which inserts derived facts into
+ * working memory when a match activates and retracts them when it withdraws.
+ * Derived entity ids are negative (per SPEC §ID Authority).
+ *
+ * Network:
+ *   root → join(alphaX) → DerivedFactProduction (inserts "Double" = x*2 into WM)
+ */
+import { describe, it, expect } from "vitest";
+import { Session } from "../../src/session.js";
+import { BetaMemory } from "../../src/beta.js";
+import { Token } from "../../src/beta.js";
+import { JoinNode } from "../../src/join.js";
+import { DerivedFactProduction } from "../../src/derived.js";
+import type { EntityId } from "../../src/schema.js";
+import type { Bindings, TokenFact } from "../../src/beta.js";
+import type { DerivedFact } from "../../src/derived.js";
+
+const ROOT_FACT: TokenFact = { id: 0 as EntityId, attr: "__root", value: null };
+
+function buildDerivedNetwork(handler: (bindings: Bindings) => readonly DerivedFact[]) {
+  const session = new Session({ autoFire: false });
+  const alpha = session._getAlpha();
+  const wm = session._getWM();
+
+  const rootMem = new BetaMemory();
+  rootMem.leftActivate(new Token(null, ROOT_FACT, {}));
+
+  const alphaX = alpha.buildNode({ id: null, attr: "X" });
+  const join = new JoinNode(rootMem, alphaX.memory, [], "x", "eid");
+  alphaX.onActivate((id, attr, value) => join.rightActivate(id, attr, value));
+  alphaX.onDeactivate((id, attr, value) => join.rightDeactivate(id, attr, value));
+
+  const derivedProd = new DerivedFactProduction("deriveDouble", wm, handler);
+  join.addDownstreamActivate(derivedProd.leftActivate.bind(derivedProd));
+  join.addDownstreamDeactivate(derivedProd.leftDeactivate.bind(derivedProd));
+
+  return { session, wm };
+}
+
+describe("G3 — derived facts (truth maintenance)", () => {
+  it("inserting a fact activates derived production and asserts Double=x*2 in WM", () => {
+    const { session, wm } = buildDerivedNetwork((b) => [
+      { attr: "Double", value: (b["x"] as number) * 2 },
+    ]);
+
+    const e1 = session.nextId();
+    session.insert(e1, "X", 5);
+
+    const allFacts = wm.allFacts();
+    const doubleFact = allFacts.find((f) => f.attr === "Double");
+    expect(doubleFact).toBeDefined();
+    expect(doubleFact?.value).toBe(10);
+  });
+
+  it("derived entity id is negative (per SPEC §ID Authority)", () => {
+    const { session, wm } = buildDerivedNetwork((b) => [
+      { attr: "Score", value: b["x"] },
+    ]);
+
+    const e1 = session.nextId();
+    session.insert(e1, "X", 7);
+
+    const allFacts = wm.allFacts();
+    const scoreFact = allFacts.find((f) => f.attr === "Score");
+    expect(scoreFact).toBeDefined();
+    expect(scoreFact?.id as number).toBeLessThan(0);
+  });
+
+  it("retracting the source fact retracts the derived fact (truth maintenance)", () => {
+    const { session, wm } = buildDerivedNetwork((b) => [
+      { attr: "Double", value: (b["x"] as number) * 2 },
+    ]);
+
+    const e1 = session.nextId();
+    session.insert(e1, "X", 5);
+    expect(wm.allFacts().find((f) => f.attr === "Double")).toBeDefined();
+
+    session.retract(e1, "X");
+    expect(wm.allFacts().find((f) => f.attr === "Double")).toBeUndefined();
+  });
+
+  it("updating a fact retracts old derived and asserts new derived", () => {
+    const { session, wm } = buildDerivedNetwork((b) => [
+      { attr: "Double", value: (b["x"] as number) * 2 },
+    ]);
+
+    const e1 = session.nextId();
+    session.insert(e1, "X", 3); // Double = 6
+    expect(wm.allFacts().find((f) => f.attr === "Double")?.value).toBe(6);
+
+    session.insert(e1, "X", 10); // Update → Double = 20
+    const doubleFacts = wm.allFacts().filter((f) => f.attr === "Double");
+    expect(doubleFacts).toHaveLength(1);
+    expect(doubleFacts[0]?.value).toBe(20);
+  });
+
+  it("two entities produce two independent derived facts with distinct negative ids", () => {
+    const { session, wm } = buildDerivedNetwork((b) => [
+      { attr: "Double", value: (b["x"] as number) * 2 },
+    ]);
+
+    const e1 = session.nextId();
+    const e2 = session.nextId();
+    session.insert(e1, "X", 4);
+    session.insert(e2, "X", 8);
+
+    const doubles = wm.allFacts().filter((f) => f.attr === "Double");
+    expect(doubles).toHaveLength(2);
+    expect(doubles.map((f) => f.value).sort((a, b) => (a as number) - (b as number))).toEqual([8, 16]);
+    // All derived ids are negative and distinct
+    const ids = doubles.map((f) => f.id as number);
+    expect(ids.every((id) => id < 0)).toBe(true);
+    expect(ids[0]).not.toBe(ids[1]);
+  });
+});

packages/rete/tests/golden/g4-multiple-entities.test.ts

@@ -0,0 +1,108 @@
+/**
+ * G4 — Multiple entities matching a wildcard condition
+ *
+ * Pararules origin: tests/test1.nim "number of conditions != number of facts":
+ *   rule numCondsAndFacts(Fact):
+ *     what:
+ *       (b, Color, "blue")
+ *       (y, LeftOf, z)
+ *       (a, Color, "maize")
+ *       (y, RightOf, b)
+ *       (x, Height, h)        ← wildcard on x; George/Thomas/Xavier all match
+ *   check session.queryAll(rule1).len == 3
+ *
+ * Our equivalent: a single wildcard condition `(?id, Health, ?hp)` matches
+ * all entities that have a Health fact. Inserting N entities → N matches.
+ *
+ * Network:
+ *   root → join(alphaHealth, no tests) → prod
+ */
+import { describe, it, expect } from "vitest";
+import { Session } from "../../src/session.js";
+import { BetaMemory } from "../../src/beta.js";
+import { Token } from "../../src/beta.js";
+import { JoinNode } from "../../src/join.js";
+import { ProductionNode, queryAll } from "../../src/query.js";
+import type { EntityId } from "../../src/schema.js";
+import type { TokenFact } from "../../src/beta.js";
+
+const ROOT_FACT: TokenFact = { id: 0 as EntityId, attr: "__root", value: null };
+
+function buildHealthNetwork() {
+  const session = new Session({ autoFire: false });
+  const alpha = session._getAlpha();
+
+  const rootMem = new BetaMemory();
+  rootMem.leftActivate(new Token(null, ROOT_FACT, {}));
+
+  const alphaHealth = alpha.buildNode({ id: null, attr: "Health" });
+  const join = new JoinNode(rootMem, alphaHealth.memory, [], "hp", "eid");
+  alphaHealth.onActivate((id, attr, value) => join.rightActivate(id, attr, value));
+  alphaHealth.onDeactivate((id, attr, value) => join.rightDeactivate(id, attr, value));
+
+  const prod = new ProductionNode("healthRule");
+  join.addDownstreamActivate(prod.leftActivate.bind(prod));
+  join.addDownstreamDeactivate(prod.leftDeactivate.bind(prod));
+
+  return { session, prod };
+}
+
+describe("G4 — multiple entities matching wildcard condition", () => {
+  it("N entities each with Health fact → N matches", () => {
+    const { session, prod } = buildHealthNetwork();
+
+    const count = 3;
+    for (let i = 0; i < count; i++) {
+      const e = session.nextId();
+      session.insert(e, "Health", (i + 1) * 10);
+    }
+
+    expect(prod.matches).toHaveLength(count);
+  });
+
+  it("5 entities → 5 matches (pararules test1.nim '3 height entities' scaled)", () => {
+    const { session, prod } = buildHealthNetwork();
+
+    for (let i = 0; i < 5; i++) {
+      const e = session.nextId();
+      session.insert(e, "Health", 72);
+    }
+
+    expect(prod.matches).toHaveLength(5);
+  });
+
+  it("queryAll returns one bindings object per entity", () => {
+    const { session, prod } = buildHealthNetwork();
+
+    const ids: EntityId[] = [];
+    for (let i = 0; i < 4; i++) {
+      const e = session.nextId();
+      ids.push(e);
+      session.insert(e, "Health", i * 100);
+    }
+
+    const all = queryAll(prod);
+    expect(all).toHaveLength(4);
+    // Every matched entity id appears in the results
+    const matchedIds = all.map((b) => b["eid"]);
+    for (const id of ids) {
+      expect(matchedIds).toContain(id);
+    }
+  });
+
+  it("entity without Health fact is not counted", () => {
+    const { session, prod } = buildHealthNetwork();
+
+    const e1 = session.nextId();
+    const e2 = session.nextId();
+    session.insert(e1, "Health", 100);
+    session.insert(e2, "Position", "a1"); // no Health
+
+    expect(prod.matches).toHaveLength(1);
+  });
+
+  it("0 entities → 0 matches", () => {
+    const { prod } = buildHealthNetwork();
+    expect(prod.matches).toHaveLength(0);
+  });
+});

packages/rete/tests/golden/g5-filter-predicate.test.ts

@@ -0,0 +1,170 @@
+/**
+ * G5 — Filter predicate (cond equivalent)
+ *
+ * Pararules origin: tests/test2.nim "complex types" stopPlayer rule:
+ *   rule stopPlayer(Fact):
+ *     what:
+ *       (Global, WindowWidth, windowWidth)
+ *       (Player, X, x)
+ *     cond:
+ *       x >= float(windowWidth)
+ *       windowWidth > 0
+ *     then:
+ *       session.insert(Player, X, 0.0)
+ *
+ * Also: tests/test1.nim "complex conditions":
+ *   cond:
+ *     z != Zach
+ *
+ * Our equivalent: FilterNode with registered predicates filters tokens
+ * that don't satisfy the predicate. Only entities whose hp > 50 match.
+ *
+ * Network:
+ *   root → join(alphaHealth) → FilterNode("greaterThan", [50]) → prod
+ */
+import { describe, it, expect } from "vitest";
+import { Session } from "../../src/session.js";
+import { BetaMemory } from "../../src/beta.js";
+import { Token } from "../../src/beta.js";
+import { JoinNode } from "../../src/join.js";
+import { FilterNode } from "../../src/condition.js";
+import { ProductionNode } from "../../src/query.js";
+import { PredicateRegistry, UnknownPredicateError } from "../../src/registry.js";
+import type { EntityId } from "../../src/schema.js";
+import type { TokenFact } from "../../src/beta.js";
+
+const ROOT_FACT: TokenFact = { id: 0 as EntityId, attr: "__root", value: null };
+
+function buildFilteredHealthNetwork(threshold: number) {
+  const session = new Session({ autoFire: false });
+  const alpha = session._getAlpha();
+
+  const rootMem = new BetaMemory();
+  rootMem.leftActivate(new Token(null, ROOT_FACT, {}));
+
+  const alphaHealth = alpha.buildNode({ id: null, attr: "Health" });
+  const join = new JoinNode(rootMem, alphaHealth.memory, [], "hp", "eid");
+  alphaHealth.onActivate((id, attr, value) => join.rightActivate(id, attr, value));
+  alphaHealth.onDeactivate((id, attr, value) => join.rightDeactivate(id, attr, value));
+
+  // PredicateRegistry with a "greaterThan" predicate
+  const predReg = new PredicateRegistry();
+  predReg.register("greaterThan", (match, args) => {
+    const hp = match["hp"] as number;
+    const limit = args[0] as number;
+    return hp > limit;
+  });
+
+  // FilterNode sits between join and prod
+  const filter = new FilterNode(
+    [{ predicate: "greaterThan", args: [threshold] }],
+    predReg,
+  );
+
+  // Wire join → filter
+  join.addDownstreamActivate(filter.leftActivate.bind(filter));
+  join.addDownstreamDeactivate(filter.leftDeactivate.bind(filter));
+
+  const prod = new ProductionNode("filteredHealthRule");
+  filter.addDownstreamActivate(prod.leftActivate.bind(prod));
+  filter.addDownstreamDeactivate(prod.leftDeactivate.bind(prod));
+
+  return { session, prod, predReg };
+}
+
+describe("G5 — filter predicate (cond equivalent)", () => {
+  it("only the entity with hp > 50 appears in matches", () => {
+    const { session, prod } = buildFilteredHealthNetwork(50);
+
+    const strong = session.nextId();
+    const weak = session.nextId();
+    session.insert(strong, "Health", 100); // passes: 100 > 50
+    session.insert(weak, "Health", 10);   // fails:  10 > 50
+
+    expect(prod.matches).toHaveLength(1);
+    expect(prod.matches[0]?.bindings["hp"]).toBe(100);
+    expect(prod.matches[0]?.bindings["eid"]).toBe(strong);
+  });
+
+  it("threshold=0: all positive health values pass", () => {
+    const { session, prod } = buildFilteredHealthNetwork(0);
+
+    for (let i = 0; i < 3; i++) {
+      const e = session.nextId();
+      session.insert(e, "Health", i + 1);
+    }
+
+    expect(prod.matches).toHaveLength(3);
+  });
+
+  it("all below threshold → 0 matches", () => {
+    const { session, prod } = buildFilteredHealthNetwork(1000);
+
+    for (let i = 0; i < 3; i++) {
+      const e = session.nextId();
+      session.insert(e, "Health", i + 1);
+    }
+
+    expect(prod.matches).toHaveLength(0);
+  });
+
+  it("retracting a passing entity removes its match", () => {
+    const { session, prod } = buildFilteredHealthNetwork(50);
+
+    const e1 = session.nextId();
+    session.insert(e1, "Health", 100);
+    expect(prod.matches).toHaveLength(1);
+
+    session.retract(e1, "Health");
+    expect(prod.matches).toHaveLength(0);
+  });
+
+  it("FilterNode rejects unknown predicates at construction time", () => {
+    const emptyReg = new PredicateRegistry();
+    expect(
+      () => new FilterNode([{ predicate: "nonexistent", args: [] }], emptyReg),
+    ).toThrow(UnknownPredicateError);
+  });
+
+  it("conjunction: both predicates must pass", () => {
+    const session = new Session({ autoFire: false });
+    const alpha = session._getAlpha();
+
+    const rootMem = new BetaMemory();
+    rootMem.leftActivate(new Token(null, ROOT_FACT, {}));
+
+    const alphaHealth = alpha.buildNode({ id: null, attr: "Health" });
+    const join = new JoinNode(rootMem, alphaHealth.memory, [], "hp", "eid");
+    alphaHealth.onActivate((id, attr, value) => join.rightActivate(id, attr, value));
+    alphaHealth.onDeactivate((id, attr, value) => join.rightDeactivate(id, attr, value));
+
+    const predReg = new PredicateRegistry();
+    predReg.register("greaterThan", (match, args) => (match["hp"] as number) > (args[0] as number));
+    predReg.register("lessThan", (match, args) => (match["hp"] as number) < (args[0] as number));
+
+    // hp > 20 AND hp < 80
+    const filter = new FilterNode(
+      [
+        { predicate: "greaterThan", args: [20] },
+        { predicate: "lessThan", args: [80] },
+      ],
+      predReg,
+    );
+    join.addDownstreamActivate(filter.leftActivate.bind(filter));
+    join.addDownstreamDeactivate(filter.leftDeactivate.bind(filter));
+
+    const prod = new ProductionNode("rangeRule");
+    filter.addDownstreamActivate(prod.leftActivate.bind(prod));
+    filter.addDownstreamDeactivate(prod.leftDeactivate.bind(prod));
+
+    const inRange = session.nextId();
+    const tooLow = session.nextId();
+    const tooHigh = session.nextId();
+    session.insert(inRange, "Health", 50);  // passes both
+    session.insert(tooLow, "Health", 10);   // fails greaterThan(20)
+    session.insert(tooHigh, "Health", 90);  // fails lessThan(80)
+
+    expect(prod.matches).toHaveLength(1);
+    expect(prod.matches[0]?.bindings["hp"]).toBe(50);
+  });
+});

packages/rete/tests/golden/g6-conflict-resolution.test.ts

@@ -0,0 +1,154 @@
+/**
+ * G6 — Conflict resolution ordering
+ *
+ * Pararules origin: tests/test2.nim "recursion limit" (rule1/rule2/rule3 cascade)
+ * and SPEC.md §Conflict Resolution which defines salience → specificity → addedAt.
+ *
+ * Pararules uses salience in rule declarations to control firing order.
+ * Our engine implements the same three-key sort via orderActivations():
+ *   1. Salience descending
+ *   2. Specificity (# conditions) descending
+ *   3. Insertion order ascending
+ *
+ * This golden test verifies the pure ordering function, which is the
+ * conflict-resolution kernel that the future agenda will call.
+ */
+import { describe, it, expect } from "vitest";
+import { orderActivations } from "../../src/conflict.js";
+import { Token } from "../../src/beta.js";
+import { Session } from "../../src/session.js";
+import { HandlerRegistry } from "../../src/registry.js";
+import { defineRule, v } from "../../src/builder.js";
+import type { Activation, OrderableRule } from "../../src/conflict.js";
+import type { EntityId } from "../../src/schema.js";
+import type { TokenFact } from "../../src/beta.js";
+
+const ROOT_FACT: TokenFact = { id: 0 as EntityId, attr: "__root", value: null };
+const dummyToken = new Token(null, ROOT_FACT, {});
+
+function mkActivation(
+  name: string,
+  salience: number,
+  conditionCount: number,
+  addedAt: number,
+): Activation {
+  const rule: OrderableRule = {
+    name,
+    salience,
+    conditions: Array.from({ length: conditionCount }, () => ({})),
+    handler: "noop",
+    addedAt,
+  };
+  return { rule, token: dummyToken };
+}
+
+describe("G6 — conflict resolution ordering", () => {
+  it("higher salience fires first", () => {
+    const activations = [
+      mkActivation("low", 0, 1, 0),
+      mkActivation("high", 10, 1, 1),
+      mkActivation("mid", 5, 1, 2),
+    ];
+
+    const ordered = orderActivations(activations);
+    expect(ordered[0]?.rule.name).toBe("high");
+    expect(ordered[1]?.rule.name).toBe("mid");
+    expect(ordered[2]?.rule.name).toBe("low");
+  });
+
+  it("salience ties broken by specificity (more conditions wins)", () => {
+    const activations = [
+      mkActivation("oneCondition", 10, 1, 0),
+      mkActivation("twoConditions", 10, 2, 1),
+      mkActivation("threeConditions", 10, 3, 2),
+    ];
+
+    const ordered = orderActivations(activations);
+    expect(ordered[0]?.rule.name).toBe("threeConditions");
+    expect(ordered[1]?.rule.name).toBe("twoConditions");
+    expect(ordered[2]?.rule.name).toBe("oneCondition");
+  });
+
+  it("salience and specificity ties broken by insertion order ascending", () => {
+    const activations = [
+      mkActivation("added2", 5, 2, 2),
+      mkActivation("added0", 5, 2, 0),
+      mkActivation("added1", 5, 2, 1),
+    ];
+
+    const ordered = orderActivations(activations);
+    expect(ordered[0]?.rule.name).toBe("added0");
+    expect(ordered[1]?.rule.name).toBe("added1");
+    expect(ordered[2]?.rule.name).toBe("added2");
+  });
+
+  it("mixed case: salience, then specificity, then addedAt", () => {
+    const activations = [
+      mkActivation("ruleC", 5, 3, 2),   // low salience, many conditions
+      mkActivation("ruleA", 10, 1, 0),  // high salience, 1 condition
+      mkActivation("ruleB", 10, 2, 1),  // high salience, 2 conditions
+    ];
+
+    const ordered = orderActivations(activations);
+    // B > A (same salience, B has more conditions)
+    // A > C (higher salience)
+    expect(ordered[0]?.rule.name).toBe("ruleB");
+    expect(ordered[1]?.rule.name).toBe("ruleA");
+    expect(ordered[2]?.rule.name).toBe("ruleC");
+  });
+
+  it("empty activations list → empty result", () => {
+    expect(orderActivations([])).toHaveLength(0);
+  });
+
+  it("single activation → unchanged", () => {
+    const single = [mkActivation("only", 10, 2, 0)];
+    const ordered = orderActivations(single);
+    expect(ordered).toHaveLength(1);
+    expect(ordered[0]?.rule.name).toBe("only");
+  });
+
+  it("orderActivations does not mutate the input array", () => {
+    const activations = [
+      mkActivation("b", 5, 1, 0),
+      mkActivation("a", 10, 1, 1),
+    ];
+    const original = [...activations];
+    orderActivations(activations);
+    expect(activations[0]?.rule.name).toBe(original[0]?.rule.name);
+    expect(activations[1]?.rule.name).toBe(original[1]?.rule.name);
+  });
+
+  it("Session._getOrderableRules returns rules in addedAt order with correct salience", () => {
+    const registry = new HandlerRegistry();
+    registry.register("noop", () => {});
+
+    const session = new Session({ autoFire: false });
+
+    const r1 = defineRule({
+      name: "rule1",
+      salience: 0,
+      what: [{ id: null, attr: "X", binding: v("x") }],
+      handler: "noop",
+      registry,
+    });
+    const r2 = defineRule({
+      name: "rule2",
+      salience: 10,
+      what: [{ id: null, attr: "Y", binding: v("y") }],
+      handler: "noop",
+      registry,
+    });
+    session.add(r1);
+    session.add(r2);
+
+    const orderable = session._getOrderableRules();
+    expect(orderable).toHaveLength(2);
+    expect(orderable[0]?.name).toBe("rule1");
+    expect(orderable[0]?.salience).toBe(0);
+    expect(orderable[0]?.addedAt).toBe(0);
+    expect(orderable[1]?.name).toBe("rule2");
+    expect(orderable[1]?.salience).toBe(10);
+    expect(orderable[1]?.addedAt).toBe(1);
+  });
+});

packages/rete/tests/golden/g7-serialization.test.ts

@@ -0,0 +1,146 @@
+/**
+ * G7 — Serialization round-trip of a complete rule
+ *
+ * Pararules origin: pararules uses staticRuleset (tests/test3.nim) for
+ * compile-time rule serialization. Our engine equivalent is the
+ * serialize/deserialize JSON round-trip per SPEC §JSON Rule Schema:
+ *   - Rules are pure data (no closures, no eval)
+ *   - Handlers are referenced by name and resolved against a HandlerRegistry
+ *   - serialize() → JSON-safe object → JSON.stringify → JSON.parse → deserialize()
+ *     produces a structurally identical RuleDefinition
+ *
+ * This tests the full pipeline including Zod schema validation.
+ */
+import { describe, it, expect } from "vitest";
+import { serialize, deserialize, RULE_SCHEMA_V1 } from "../../src/serialize.js";
+import { defineRule, v } from "../../src/builder.js";
+import { HandlerRegistry, UnknownHandlerError } from "../../src/registry.js";
+import type { EntityId } from "../../src/schema.js";
+
+function makeRegistry(...names: string[]): HandlerRegistry {
+  const reg = new HandlerRegistry();
+  for (const name of names) {
+    reg.register(name, () => {});
+  }
+  return reg;
+}
+
+describe("G7 — serialization round-trip", () => {
+  it("serialize + JSON round-trip + deserialize produces equivalent RuleDefinition", () => {
+    const registry = makeRegistry("myHandler");
+
+    const rule = defineRule({
+      name: "myRule",
+      salience: 5,
+      what: [
+        { id: null, attr: "Health", binding: v("hp"), idBinding: v("eid") },
+        { id: null, attr: "Position", binding: v("pos") },
+      ],
+      handler: "myHandler",
+      registry,
+    });
+
+    // Serialize → JSON → deserialize
+    const serialized = serialize(rule);
+    const json = JSON.stringify(serialized);
+    const parsed = JSON.parse(json) as unknown;
+    const restored = deserialize(parsed, registry);
+
+    // Core identity preserved
+    expect(restored.name).toBe(rule.name);
+    expect(restored.salience).toBe(rule.salience);
+    expect(restored.handler).toBe(rule.handler);
+    expect(restored.conditions).toHaveLength(rule.conditions.length);
+
+    // Condition details preserved
+    const c0 = restored.conditions[0];
+    expect(c0?.id).toBe(null);
+    expect(c0?.attr).toBe("Health");
+    expect(c0?.binding?.name).toBe("hp");
+    expect(c0?.idBinding?.name).toBe("eid");
+
+    const c1 = restored.conditions[1];
+    expect(c1?.attr).toBe("Position");
+    expect(c1?.binding?.name).toBe("pos");
+    expect(c1?.idBinding).toBeUndefined();
+  });
+
+  it("rule with specific entity id survives round-trip", () => {
+    const registry = makeRegistry("handler");
+    const specificId = 42 as EntityId;
+
+    const rule = defineRule({
+      name: "specificRule",
+      salience: 0,
+      what: [{ id: specificId, attr: "Active", binding: v("active") }],
+      handler: "handler",
+      registry,
+    });
+
+    const serialized = serialize(rule);
+    const restored = deserialize(JSON.parse(JSON.stringify(serialized)), registry);
+
+    expect(restored.conditions[0]?.id).toBe(42);
+  });
+
+  it("rule with handlerArgs survives round-trip", () => {
+    const registry = makeRegistry("handler");
+
+    const rule = defineRule({
+      name: "argsRule",
+      salience: 0,
+      what: [{ id: null, attr: "X", binding: v("x") }],
+      handler: "handler",
+      handlerArgs: ["threshold", 50, true],
+      registry,
+    });
+
+    const serialized = serialize(rule);
+    const restored = deserialize(JSON.parse(JSON.stringify(serialized)), registry);
+
+    expect(restored.handlerArgs).toEqual(["threshold", 50, true]);
+  });
+
+  it("salience defaults to 0 when omitted in serialized form", () => {
+    const registry = makeRegistry("h");
+    const raw = { name: "noSalience", handler: "h", conditions: [] };
+    const restored = deserialize(raw, registry);
+    expect(restored.salience).toBe(0);
+  });
+
+  it("deserialize throws UnknownHandlerError for unregistered handler", () => {
+    const emptyRegistry = new HandlerRegistry();
+    const json = { name: "r", handler: "missing", conditions: [] };
+    expect(() => deserialize(json, emptyRegistry)).toThrow(UnknownHandlerError);
+  });
+
+  it("RULE_SCHEMA_V1 validates structure with Zod", () => {
+    const valid = { name: "r", handler: "h", conditions: [], salience: 0 };
+    const parsed = RULE_SCHEMA_V1.safeParse(valid);
+    expect(parsed.success).toBe(true);
+
+    const invalid = { name: "", handler: "h" }; // empty name fails min(1)
+    const badParsed = RULE_SCHEMA_V1.safeParse(invalid);
+    expect(badParsed.success).toBe(false);
+  });
+
+  it("serialize produces plain JSON-safe values (no functions, no undefined)", () => {
+    const registry = makeRegistry("h");
+    const rule = defineRule({
+      name: "plain",
+      salience: 1,
+      what: [{ id: null, attr: "X", binding: v("x") }],
+      handler: "h",
+      registry,
+    });
+
+    const serialized = serialize(rule);
+    // Must round-trip cleanly through JSON without loss
+    const jsonStr = JSON.stringify(serialized);
+    expect(typeof jsonStr).toBe("string");
+    const reparsed = JSON.parse(jsonStr) as Record<string, unknown>;
+    expect(reparsed["name"]).toBe("plain");
+    expect(reparsed["salience"]).toBe(1);
+    expect(Array.isArray(reparsed["conditions"])).toBe(true);
+  });
+});

packages/rete/tests/golden/g8-variable-binding-chain.test.ts

@@ -0,0 +1,174 @@
+/**
+ * G8 — Variable binding propagation across a 3-condition join chain
+ *
+ * Pararules origin: tests/test1.nim "number of conditions != number of facts"
+ * and tests/test2.nim "join value with id" / "multiple joins":
+ *   rule rule1(Fact):
+ *     what:
+ *       (Bob, LeftOf, id)      ← id bound from value
+ *       (id, Color, color)     ← id used in entity position (value join)
+ *       (id, Height, height)   ← id equality
+ *
+ * Our equivalent: 3-condition chain where eid is bound in condition 1,
+ * then used as idEquality in conditions 2 and 3.
+ *
+ *   (?eid, "Type", ?type) ∧ (?eid, "Health", ?hp) ∧ (?eid, "Position", ?pos)
+ *
+ * Network:
+ *   root → join1(alphaType) → mem1 → join2(alphaHealth, idEq:eid) →
+ *          mem2 → join3(alphaPos, idEq:eid) → prod
+ */
+import { describe, it, expect } from "vitest";
+import { Session } from "../../src/session.js";
+import { BetaMemory } from "../../src/beta.js";
+import { Token } from "../../src/beta.js";
+import { JoinNode } from "../../src/join.js";
+import { ProductionNode } from "../../src/query.js";
+import type { EntityId } from "../../src/schema.js";
+import type { JoinTest } from "../../src/join.js";
+import type { TokenFact } from "../../src/beta.js";
+
+const ROOT_FACT: TokenFact = { id: 0 as EntityId, attr: "__root", value: null };
+const idEq: JoinTest = { type: "idEquality", leftVar: "eid" };
+
+function buildThreeConditionNetwork() {
+  const session = new Session({ autoFire: false });
+  const alpha = session._getAlpha();
+
+  // Root
+  const rootMem = new BetaMemory();
+  rootMem.leftActivate(new Token(null, ROOT_FACT, {}));
+
+  // Alpha nodes for each condition
+  const alphaType = alpha.buildNode({ id: null, attr: "Type" });
+  const alphaHealth = alpha.buildNode({ id: null, attr: "Health" });
+  const alphaPos = alpha.buildNode({ id: null, attr: "Position" });
+
+  // Intermediate beta memories
+  const mem1 = new BetaMemory();
+  const mem2 = new BetaMemory();
+
+  // join1: root × Type → binds type and eid
+  const join1 = new JoinNode(rootMem, alphaType.memory, [], "type", "eid");
+
+  // join2: mem1 × Health with idEquality → binds hp
+  const join2 = new JoinNode(mem1, alphaHealth.memory, [idEq], "hp", null);
+
+  // join3: mem2 × Position with idEquality → binds pos
+  const join3 = new JoinNode(mem2, alphaPos.memory, [idEq], "pos", null);
+
+  // Wire: join1 → mem1 → join2 → mem2 → join3
+  join1.addDownstreamActivate(mem1.leftActivate.bind(mem1));
+  join1.addDownstreamDeactivate(mem1.leftDeactivate.bind(mem1));
+  mem1.addDownstreamActivate(join2.leftActivate.bind(join2));
+  mem1.addDownstreamDeactivate(join2.leftDeactivate.bind(join2));
+
+  join2.addDownstreamActivate(mem2.leftActivate.bind(mem2));
+  join2.addDownstreamDeactivate(mem2.leftDeactivate.bind(mem2));
+  mem2.addDownstreamActivate(join3.leftActivate.bind(join3));
+  mem2.addDownstreamDeactivate(join3.leftDeactivate.bind(join3));
+
+  // Wire alpha events → join right sides
+  alphaType.onActivate((id, attr, value) => join1.rightActivate(id, attr, value));
+  alphaType.onDeactivate((id, attr, value) => join1.rightDeactivate(id, attr, value));
+  alphaHealth.onActivate((id, attr, value) => join2.rightActivate(id, attr, value));
+  alphaHealth.onDeactivate((id, attr, value) => join2.rightDeactivate(id, attr, value));
+  alphaPos.onActivate((id, attr, value) => join3.rightActivate(id, attr, value));
+  alphaPos.onDeactivate((id, attr, value) => join3.rightDeactivate(id, attr, value));
+
+  // ProductionNode
+  const prod = new ProductionNode("threeCondRule");
+  join3.addDownstreamActivate(prod.leftActivate.bind(prod));
+  join3.addDownstreamDeactivate(prod.leftDeactivate.bind(prod));
+
+  return { session, prod };
+}
+
+describe("G8 — variable binding propagation across 3-condition chain", () => {
+  it("entity with all 3 facts produces 1 match with all bindings correct", () => {
+    const { session, prod } = buildThreeConditionNetwork();
+
+    const e1 = session.nextId();
+    session.insert(e1, "Type", "knight");
+    session.insert(e1, "Health", 100);
+    session.insert(e1, "Position", "e4");
+
+    expect(prod.matches).toHaveLength(1);
+    const b = prod.matches[0]?.bindings;
+    expect(b?.["type"]).toBe("knight");
+    expect(b?.["hp"]).toBe(100);
+    expect(b?.["pos"]).toBe("e4");
+    expect(b?.["eid"]).toBe(e1);
+  });
+
+  it("entity missing one fact (Position) does not produce a match", () => {
+    const { session, prod } = buildThreeConditionNetwork();
+
+    const e1 = session.nextId();
+    session.insert(e1, "Type", "pawn");
+    session.insert(e1, "Health", 50);
+    // no Position
+
+    expect(prod.matches).toHaveLength(0);
+  });
+
+  it("2 complete entities → 2 matches; 1 partial → still 2 matches", () => {
+    const { session, prod } = buildThreeConditionNetwork();
+
+    const e1 = session.nextId();
+    const e2 = session.nextId();
+    const e3 = session.nextId();
+
+    session.insert(e1, "Type", "knight");
+    session.insert(e1, "Health", 100);
+    session.insert(e1, "Position", "e4");
+
+    session.insert(e2, "Type", "rook");
+    session.insert(e2, "Health", 80);
+    session.insert(e2, "Position", "a1");
+
+    session.insert(e3, "Type", "pawn");
+    // e3 missing Health and Position
+
+    expect(prod.matches).toHaveLength(2);
+  });
+
+  it("idEquality prevents cross-entity joins (different entities cannot merge bindings)", () => {
+    const { session, prod } = buildThreeConditionNetwork();
+
+    const e1 = session.nextId();
+    const e2 = session.nextId();
+
+    session.insert(e1, "Type", "knight");
+    session.insert(e1, "Health", 100);
+    // e1 has no Position
+
+    session.insert(e2, "Type", "rook");
+    session.insert(e2, "Position", "a1");
+    // e2 has no Health
+
+    // Neither entity has all 3 facts, so no complete matches
+    expect(prod.matches).toHaveLength(0);
+  });
+
+  it("bindings from all 3 conditions available in the final token", () => {
+    const { session, prod } = buildThreeConditionNetwork();
+
+    const e1 = session.nextId();
+    session.insert(e1, "Type", "bishop");
+    session.insert(e1, "Health", 75);
+    session.insert(e1, "Position", "c3");
+
+    const token = prod.matches[0]?.token;
+    expect(token).toBeDefined();
+    // Walk the token chain: 3 facts deep
+    let depth = 0;
+    let curr = token ?? null;
+    while (curr !== null) {
+      depth++;
+      curr = curr.parent;
+    }
+    // Root token (depth=1) + 3 condition facts = depth 4
+    expect(depth).toBe(4);
+  });
+});

packages/rete/tests/golden/g9-retraction.test.ts

@@ -0,0 +1,180 @@
+/**
+ * G9 — Retraction removes a match (non-derived)
+ *
+ * Pararules origin: tests/test1.nim "removing facts":
+ *   session.insert(Bob, Color, "blue")
+ *   session.insert(Yair, LeftOf, Zach)
+ *   session.insert(Alice, Color, "maize")
+ *   session.insert(Yair, RightOf, Bob)
+ *   check session.queryAll(rule1).len == 1
+ *
+ *   session.retract(Yair, RightOf, Bob)
+ *   check session.queryAll(rule1).len == 0
+ *
+ *   session.retract(Bob, Color)   ← value parameter not required
+ *   check session.queryAll(rule1).len == 0
+ *
+ * We test:
+ *   1. Insert fact → match appears
+ *   2. Retract fact → match disappears
+ *   3. Re-insert → match reappears
+ *   4. Two-condition join: retracting one condition removes joint match
+ *   5. Session.retract only needs (id, attr) — value is not required
+ */
+import { describe, it, expect } from "vitest";
+import { Session } from "../../src/session.js";
+import { BetaMemory } from "../../src/beta.js";
+import { Token } from "../../src/beta.js";
+import { JoinNode } from "../../src/join.js";
+import { ProductionNode } from "../../src/query.js";
+import type { EntityId } from "../../src/schema.js";
+import type { JoinTest } from "../../src/join.js";
+import type { TokenFact } from "../../src/beta.js";
+
+const ROOT_FACT: TokenFact = { id: 0 as EntityId, attr: "__root", value: null };
+
+function buildSingleCondNet(attr: string) {
+  const session = new Session({ autoFire: false });
+  const alpha = session._getAlpha();
+
+  const rootMem = new BetaMemory();
+  rootMem.leftActivate(new Token(null, ROOT_FACT, {}));
+
+  const alphaNode = alpha.buildNode({ id: null, attr });
+  const join = new JoinNode(rootMem, alphaNode.memory, [], "val", "eid");
+  alphaNode.onActivate((id, a, value) => join.rightActivate(id, a, value));
+  alphaNode.onDeactivate((id, a, value) => join.rightDeactivate(id, a, value));
+
+  const prod = new ProductionNode("rule");
+  join.addDownstreamActivate(prod.leftActivate.bind(prod));
+  join.addDownstreamDeactivate(prod.leftDeactivate.bind(prod));
+
+  return { session, prod };
+}
+
+function buildTwoCondNet() {
+  const session = new Session({ autoFire: false });
+  const alpha = session._getAlpha();
+
+  const rootMem = new BetaMemory();
+  rootMem.leftActivate(new Token(null, ROOT_FACT, {}));
+
+  const alphaX = alpha.buildNode({ id: null, attr: "X" });
+  const alphaY = alpha.buildNode({ id: null, attr: "Y" });
+  const mem1 = new BetaMemory();
+  const idEq: JoinTest = { type: "idEquality", leftVar: "eid" };
+
+  const join1 = new JoinNode(rootMem, alphaX.memory, [], "x", "eid");
+  const join2 = new JoinNode(mem1, alphaY.memory, [idEq], "y", null);
+
+  join1.addDownstreamActivate(mem1.leftActivate.bind(mem1));
+  join1.addDownstreamDeactivate(mem1.leftDeactivate.bind(mem1));
+  mem1.addDownstreamActivate(join2.leftActivate.bind(join2));
+  mem1.addDownstreamDeactivate(join2.leftDeactivate.bind(join2));
+
+  alphaX.onActivate((id, attr, value) => join1.rightActivate(id, attr, value));
+  alphaX.onDeactivate((id, attr, value) => join1.rightDeactivate(id, attr, value));
+  alphaY.onActivate((id, attr, value) => join2.rightActivate(id, attr, value));
+  alphaY.onDeactivate((id, attr, value) => join2.rightDeactivate(id, attr, value));
+
+  const prod = new ProductionNode("xyRule");
+  join2.addDownstreamActivate(prod.leftActivate.bind(prod));
+  join2.addDownstreamDeactivate(prod.leftDeactivate.bind(prod));
+
+  return { session, prod };
+}
+
+describe("G9 — retraction removes match", () => {
+  it("insert → match appears, retract → match disappears", () => {
+    const { session, prod } = buildSingleCondNet("Health");
+
+    const e1 = session.nextId();
+    session.insert(e1, "Health", 100);
+    expect(prod.matches).toHaveLength(1);
+
+    session.retract(e1, "Health");
+    expect(prod.matches).toHaveLength(0);
+  });
+
+  it("retract then re-insert → match reappears", () => {
+    const { session, prod } = buildSingleCondNet("Health");
+
+    const e1 = session.nextId();
+    session.insert(e1, "Health", 100);
+    expect(prod.matches).toHaveLength(1);
+
+    session.retract(e1, "Health");
+    expect(prod.matches).toHaveLength(0);
+
+    session.insert(e1, "Health", 50);
+    expect(prod.matches).toHaveLength(1);
+    expect(prod.matches[0]?.bindings["val"]).toBe(50);
+  });
+
+  it("two-condition join: retracting first condition removes joint match", () => {
+    const { session, prod } = buildTwoCondNet();
+
+    const e1 = session.nextId();
+    session.insert(e1, "X", 3);
+    session.insert(e1, "Y", 4);
+    expect(prod.matches).toHaveLength(1);
+
+    session.retract(e1, "X");
+    expect(prod.matches).toHaveLength(0);
+  });
+
+  it("two-condition join: retracting second condition removes joint match", () => {
+    const { session, prod } = buildTwoCondNet();
+
+    const e1 = session.nextId();
+    session.insert(e1, "X", 1);
+    session.insert(e1, "Y", 2);
+    expect(prod.matches).toHaveLength(1);
+
+    session.retract(e1, "Y");
+    expect(prod.matches).toHaveLength(0);
+  });
+
+  it("retract one entity of many — only that entity's match disappears", () => {
+    const { session, prod } = buildSingleCondNet("Health");
+
+    const e1 = session.nextId();
+    const e2 = session.nextId();
+    const e3 = session.nextId();
+    session.insert(e1, "Health", 10);
+    session.insert(e2, "Health", 20);
+    session.insert(e3, "Health", 30);
+    expect(prod.matches).toHaveLength(3);
+
+    session.retract(e2, "Health");
+    expect(prod.matches).toHaveLength(2);
+    // e1 and e3 still present
+    const remainingEids = prod.matches.map((m) => m.bindings["eid"]);
+    expect(remainingEids).toContain(e1);
+    expect(remainingEids).toContain(e3);
+    expect(remainingEids).not.toContain(e2);
+  });
+
+  it("update (re-insert same attr) replaces old value in match", () => {
+    const { session, prod } = buildSingleCondNet("Health");
+
+    const e1 = session.nextId();
+    session.insert(e1, "Health", 100);
+    expect(prod.matches[0]?.bindings["val"]).toBe(100);
+
+    session.insert(e1, "Health", 50); // update
+    expect(prod.matches).toHaveLength(1);
+    expect(prod.matches[0]?.bindings["val"]).toBe(50);
+  });
+
+  it("WM.contains returns false after retraction", () => {
+    const { session } = buildSingleCondNet("Health");
+
+    const e1 = session.nextId();
+    session.insert(e1, "Health", 100);
+    expect(session.contains(e1, "Health")).toBe(true);
+
+    session.retract(e1, "Health");
+    expect(session.contains(e1, "Health")).toBe(false);
+  });
+});

packages/rete/tsconfig.json

@@ -2,8 +2,7 @@
   "extends": "../../tsconfig.base.json",
   "compilerOptions": {
     "outDir": "dist",
-    "rootDir": "src",
     "composite": true
   },
-  "include": ["src/**/*"]
+  "include": ["src/**/*", "tests/**/*"]
 }