libpetri 2.7.1 → 2.9.0

package/dist/index.js

@@ -12,11 +12,17 @@ import {
   timeoutPlace,
   xor,
   xorPlaces
-} from "./chunk-ETNHEAS6.js";
+} from "./chunk-M3KT7BFO.js";
 import {
   eventTransitionName,
   isFailureEvent
 } from "./chunk-SXK2Z45Z.js";
+import {
+  keyForPlace,
+  matchCorrelates,
+  matchKey,
+  matchSpec
+} from "./chunk-E3ZWB645.js";
 import {
   MAX_DURATION_MS,
   deadline,
@@ -131,6 +137,11 @@ function consumptionCount(spec, available) {
   }
 }
 
+// src/core/name.ts
+function nameId(value) {
+  return value;
+}
+
 // src/core/transition-action.ts
 function passthrough() {
   return PASSTHROUGH;
@@ -204,6 +215,7 @@ function withTimeout(action, timeoutMs, timeoutPlace2, timeoutValue) {
 
 // src/core/transition-context.ts
 var EMPTY_ALIAS = /* @__PURE__ */ new Map();
+var GLOBAL_FRESH_NAME_COUNTER = 0;
 var TransitionContext = class {
   rawInput;
   _rawOutput;
@@ -217,6 +229,7 @@ var TransitionContext = class {
   executionCtx;
   _logFn;
   placeAlias;
+  _freshNameSupplier;
   constructor(transitionName, rawInput, rawOutput, inputPlaces, readPlaces, outputPlaces, executionContext, logFn, placeAlias) {
     this._transitionName = transitionName;
     this.rawInput = rawInput;
@@ -358,6 +371,28 @@ var TransitionContext = class {
       );
     }
   }
+  // ==================== ν-name minting (NU-010) ====================
+  /**
+   * @internal Installs the ν-name minter. Wired by the executor at firing time
+   * so names minted by {@link freshName} are monotonic across the run and
+   * instance-prefixed (spec NU-010, NU-030).
+   */
+  setFreshNameSupplier(supplier) {
+    this._freshNameSupplier = supplier;
+  }
+  /**
+   * Mints a fresh ν-name (the ν-binder primitive — spec NU-010).
+   *
+   * An action calls this on the fork side to create a correlation id, then
+   * writes it into the sibling output payloads; a later join correlates those
+   * siblings via a {@link import('./match-spec.js').MatchSpec}. Uses the
+   * executor-installed minter when present; otherwise falls back to a
+   * process-global counter prefixed by the transition name.
+   */
+  freshName() {
+    if (this._freshNameSupplier) return this._freshNameSupplier();
+    return nameId(`${this._transitionName}#${GLOBAL_FRESH_NAME_COUNTER++}`);
+  }
   // ==================== Structure Info ====================
   /** Returns the transition name. */
   transitionName() {
@@ -472,6 +507,11 @@ var Transition = class {
   actionTimeout;
   action;
   priority;
+  /**
+   * ν-net join correlation: a subset of `inputSpecs` that must be correlated by
+   * name equality on firing (spec NU-020). `null` for ordinary transitions.
+   */
+  matchSpec;
   /**
    * Per-transition **declared → actual** place correspondence (per
    * **MOD-031**), keyed by the author-original declared place **name** →
@@ -488,7 +528,7 @@ var Transition = class {
   _readPlaces;
   _outputPlaces;
   /** @internal Use {@link Transition.builder} to create instances. */
-  constructor(key, name, inputSpecs, outputSpec, inhibitors, reads, resets, timing, action, priority, placeAlias = EMPTY_PLACE_ALIAS) {
+  constructor(key, name, inputSpecs, outputSpec, inhibitors, reads, resets, timing, action, priority, placeAlias = EMPTY_PLACE_ALIAS, matchSpec2 = null) {
     if (key !== TRANSITION_KEY) throw new Error("Use Transition.builder() to create instances");
     this.name = name;
     this.inputSpecs = inputSpecs;
@@ -501,6 +541,7 @@ var Transition = class {
     this.action = action;
     this.priority = priority;
     this.placeAlias = placeAlias.size === 0 ? EMPTY_PLACE_ALIAS : placeAlias;
+    this.matchSpec = matchSpec2;
     const inputPlaces = /* @__PURE__ */ new Set();
     for (const spec of inputSpecs) {
       inputPlaces.add(spec.place);
@@ -553,6 +594,7 @@ var TransitionBuilder = class {
   _action = passthrough();
   _priority = 0;
   _placeAlias = EMPTY_PLACE_ALIAS;
+  _matchSpec = null;
   constructor(name) {
     this._name = name;
   }
@@ -617,6 +659,15 @@ var TransitionBuilder = class {
     this._priority = priority;
     return this;
   }
+  /**
+   * Sets the ν-net join correlation spec: the named input places must be
+   * correlated by name equality on firing (spec NU-020). Every place referenced
+   * by the spec must also be declared as an input.
+   */
+  match(spec) {
+    this._matchSpec = spec;
+    return this;
+  }
   /**
    * Sets the per-transition declared→actual place correspondence (per
    * **MOD-031**). Populated by the subnet rewriter during the compose-time
@@ -638,6 +689,16 @@ var TransitionBuilder = class {
         }
       }
     }
+    if (this._matchSpec !== null) {
+      const inputPlaceNames = new Set(this._inputSpecs.map((s) => s.place.name));
+      for (const k of this._matchSpec.keys) {
+        if (!inputPlaceNames.has(k.place.name)) {
+          throw new Error(
+            `Transition '${this._name}': MatchSpec correlates non-input place '${k.place.name}'`
+          );
+        }
+      }
+    }
     return new Transition(
       TRANSITION_KEY,
       this._name,
@@ -649,7 +710,8 @@ var TransitionBuilder = class {
       this._timing,
       this._action,
       this._priority,
-      this._placeAlias
+      this._placeAlias,
+      this._matchSpec
     );
   }
 };
@@ -967,6 +1029,14 @@ function rebuildWithName(t, name, remap) {
   for (let i = 0; i < t.resets.length; i++) {
     builder.reset(rewriteReset(t.resets[i], remap).place);
   }
+  if (t.matchSpec !== null) {
+    builder.match({
+      keys: t.matchSpec.keys.map((k) => ({
+        place: remap.get(k.place.name) ?? k.place,
+        key: k.key
+      }))
+    });
+  }
   return builder.build();
 }
 function buildPlaceAlias(t, remap) {
@@ -2298,7 +2368,8 @@ var Marking = class _Marking {
     for (let i = 0; i < queue.length; i++) {
       const token = queue[i];
       if (spec.guard(token.value)) {
-        queue.splice(i, 1);
+        if (i === 0) queue.shift();
+        else queue.splice(i, 1);
         return token;
       }
     }
@@ -2387,6 +2458,10 @@ var CompiledNet = class _CompiledNet {
   // Cardinality and guard flags
   _cardinalityChecks;
   _hasGuards;
+  // ν-net join flag: the transition carries a MatchSpec (NU-020). Precomputed
+  // so the hot enablement loop can skip the match check on non-ν transitions
+  // (zero-cost gating), mirroring `_hasGuards`.
+  _hasMatch;
   constructor(net) {
     this.net = net;
     const allPlacesSet = /* @__PURE__ */ new Map();
@@ -2418,12 +2493,14 @@ var CompiledNet = class _CompiledNet {
     this._consumptionPlaceIds = new Array(this.transitionCount);
     this._cardinalityChecks = new Array(this.transitionCount).fill(null);
     this._hasGuards = new Array(this.transitionCount).fill(false);
+    this._hasMatch = new Array(this.transitionCount).fill(false);
     const placeToTransitionsList = new Array(this.placeCount);
     for (let i = 0; i < this.placeCount; i++) {
       placeToTransitionsList[i] = [];
     }
     for (let tid = 0; tid < this.transitionCount; tid++) {
       const t = this._transitionsById[tid];
+      this._hasMatch[tid] = t.matchSpec !== null;
       const needs = new Uint32Array(this.wordCount);
       const inhibitors = new Uint32Array(this.wordCount);
       let needsCardinality = false;
@@ -2505,6 +2582,9 @@ var CompiledNet = class _CompiledNet {
   hasGuards(tid) {
     return this._hasGuards[tid];
   }
+  hasMatch(tid) {
+    return this._hasMatch[tid];
+  }
   // ==================== Enablement Check ====================
   /**
    * Two-phase bitmap enablement check for a transition:
@@ -2609,6 +2689,224 @@ function inMemoryEventStore() {
   return new InMemoryEventStore();
 }
 
+// src/runtime/match-engine.ts
+function selectMatchName(perPlace, requireds) {
+  if (perPlace.length === 0) return null;
+  let seed = 0;
+  for (let i = 1; i < perPlace.length; i++) {
+    if (perPlace[i].size < perPlace[seed].size) seed = i;
+  }
+  let bestName = null;
+  let bestTs = 0;
+  for (const [name, stat] of perPlace[seed]) {
+    if (stat.count < requireds[seed]) continue;
+    let repTs = Number.MAX_SAFE_INTEGER;
+    let satisfied = true;
+    for (let j = 0; j < perPlace.length; j++) {
+      const s = perPlace[j].get(name);
+      if (s === void 0 || s.count < requireds[j]) {
+        satisfied = false;
+        break;
+      }
+      repTs = Math.min(repTs, s.minCreatedAt);
+    }
+    if (!satisfied) continue;
+    const take = bestName === null || repTs < bestTs || repTs === bestTs && name < bestName;
+    if (take) {
+      bestName = name;
+      bestTs = repTs;
+    }
+  }
+  return bestName;
+}
+function buildNameIndex(tokens, key, guard) {
+  const index = /* @__PURE__ */ new Map();
+  for (const token of tokens) {
+    if (guard && !guard(token.value)) continue;
+    const name = key(token.value);
+    if (name === void 0 || name === null) continue;
+    const ts = token.createdAt;
+    const prev = index.get(name);
+    if (prev) {
+      prev.count++;
+      if (ts < prev.minCreatedAt) prev.minCreatedAt = ts;
+    } else {
+      index.set(name, { count: 1, minCreatedAt: ts });
+    }
+  }
+  return index;
+}
+function requiredFor(t, placeName) {
+  for (const inSpec of t.inputSpecs) {
+    if (inSpec.place.name === placeName) {
+      if (inSpec.type === "exactly") return inSpec.count;
+      if (inSpec.type === "at-least") return inSpec.minimum;
+      return 1;
+    }
+  }
+  return 1;
+}
+function findBinding(t, getTokens) {
+  const ms = t.matchSpec;
+  if (!ms) return null;
+  const perPlace = [];
+  const requireds = [];
+  for (const k of ms.keys) {
+    perPlace.push(buildNameIndex(getTokens(k.place), k.key, guardFor(t, k.place.name)));
+    requireds.push(requiredFor(t, k.place.name));
+  }
+  return selectMatchName(perPlace, requireds);
+}
+function guardFor(t, placeName) {
+  for (const inSpec of t.inputSpecs) {
+    if (inSpec.place.name === placeName) return inSpec.guard;
+  }
+  return void 0;
+}
+var MinQueue = class {
+  inStack = [];
+  inMin = [];
+  outStack = [];
+  outMin = [];
+  get size() {
+    return this.inStack.length + this.outStack.length;
+  }
+  pushBack(v) {
+    this.inStack.push(v);
+    const top = this.inMin.length;
+    this.inMin.push(top ? Math.min(this.inMin[top - 1], v) : v);
+  }
+  popFront() {
+    if (this.outStack.length === 0) {
+      while (this.inStack.length) {
+        const v = this.inStack.pop();
+        this.inMin.pop();
+        this.outStack.push(v);
+        const top = this.outMin.length;
+        this.outMin.push(top ? Math.min(this.outMin[top - 1], v) : v);
+      }
+    }
+    this.outStack.pop();
+    this.outMin.pop();
+  }
+  min() {
+    const a = this.inMin.length ? this.inMin[this.inMin.length - 1] : Infinity;
+    const b = this.outMin.length ? this.outMin[this.outMin.length - 1] : Infinity;
+    return a < b ? a : b;
+  }
+};
+var ReadyHeap = class {
+  a = [];
+  get size() {
+    return this.a.length;
+  }
+  peek() {
+    return this.a[0];
+  }
+  less(x, y) {
+    return x.ts < y.ts || x.ts === y.ts && x.name < y.name;
+  }
+  push(e) {
+    const a = this.a;
+    a.push(e);
+    let i = a.length - 1;
+    while (i > 0) {
+      const p = i - 1 >> 1;
+      if (this.less(a[i], a[p])) {
+        const tmp = a[i];
+        a[i] = a[p];
+        a[p] = tmp;
+        i = p;
+      } else break;
+    }
+  }
+  pop() {
+    const a = this.a;
+    const last = a.pop();
+    if (a.length === 0) return;
+    a[0] = last;
+    let i = 0;
+    const n = a.length;
+    for (; ; ) {
+      const l = 2 * i + 1;
+      const r = 2 * i + 2;
+      let m = i;
+      if (l < n && this.less(a[l], a[m])) m = l;
+      if (r < n && this.less(a[r], a[m])) m = r;
+      if (m === i) break;
+      const tmp = a[i];
+      a[i] = a[m];
+      a[m] = tmp;
+      i = m;
+    }
+  }
+};
+var IncrementalMatcher = class {
+  constructor(requireds) {
+    this.requireds = requireds;
+    this.ts = requireds.map(() => /* @__PURE__ */ new Map());
+  }
+  ts;
+  heap = new ReadyHeap();
+  ready = /* @__PURE__ */ new Map();
+  /** Add one (already guard-passing) token carrying `name` at `createdAt` to input `i`. */
+  add(i, name, createdAt) {
+    let q = this.ts[i].get(name);
+    if (!q) {
+      q = new MinQueue();
+      this.ts[i].set(name, q);
+    }
+    q.pushBack(createdAt);
+    this.refresh(name);
+    this.cleanTop();
+  }
+  /** Remove the `required` earliest-inserted tokens of `name` from every input (NU-020). */
+  consume(name) {
+    for (let i = 0; i < this.requireds.length; i++) {
+      const q = this.ts[i].get(name);
+      if (q) {
+        for (let r = 0; r < this.requireds[i]; r++) q.popFront();
+        if (q.size === 0) this.ts[i].delete(name);
+      }
+    }
+    this.refresh(name);
+    this.cleanTop();
+  }
+  /** The name `selectMatchName` would pick, or `null`. O(1) read. */
+  best() {
+    const top = this.heap.peek();
+    return top ? top.name : null;
+  }
+  repTs(name) {
+    let rep = Infinity;
+    for (let i = 0; i < this.requireds.length; i++) {
+      const q = this.ts[i].get(name);
+      if (!q || q.size < this.requireds[i]) return null;
+      const m = q.min();
+      if (m < rep) rep = m;
+    }
+    return rep;
+  }
+  refresh(name) {
+    const rep = this.repTs(name);
+    if (rep !== null) {
+      if (this.ready.get(name) !== rep) {
+        this.ready.set(name, rep);
+        this.heap.push({ ts: rep, name });
+      }
+    } else {
+      this.ready.delete(name);
+    }
+  }
+  cleanTop() {
+    for (; ; ) {
+      const top = this.heap.peek();
+      if (top && this.ready.get(top.name) !== top.ts) this.heap.pop();
+      else break;
+    }
+  }
+};
+
 // src/runtime/out-violation-error.ts
 var OutViolationError = class extends Error {
   constructor(message) {
@@ -2682,6 +2980,18 @@ function produceTimeoutOutput(context, timeoutChild) {
 var BitmapNetExecutor = class {
   compiled;
   marking;
+  /** Monotonic source for ν-name minting (ctx.freshName(), NU-010). */
+  freshNameCounter = 0;
+  /**
+   * ν-net incremental match caches (NU-020): per matched transition, an
+   * {@link IncrementalMatcher} kept in lockstep with the marking when the
+   * transition is fast-path eligible (every correlated input is `one`/`exactly`,
+   * consumed by no other transition, never reset), else `null` → fall back to
+   * the O(n) rebuild {@link findBinding}. Turns a draining matched join from
+   * O(n²) into O(n log n). Mirrors the precompiled executor and the Rust backends.
+   */
+  matchCaches = [];
+  placeMatchTargets = [];
   eventStore;
   environmentPlaces;
   hasEnvironmentPlaces;
@@ -2776,6 +3086,90 @@ var BitmapNetExecutor = class {
       for (const spec of t.inputSpecs) names.add(spec.place.name);
       this.transitionInputPlaceNames.set(t, names);
     }
+    this.initMatchCaches();
+  }
+  /**
+   * Builds the ν-net incremental match caches (NU-020). A matched join is
+   * fast-path eligible only when every correlated input is `one`/`exactly`, is
+   * consumed by no other transition, and is never reset — so the cache can never
+   * desync from the marking. Mirrors the precompiled executor.
+   */
+  initMatchCaches() {
+    const compiled = this.compiled;
+    const tc = compiled.transitionCount;
+    const pc = compiled.placeCount;
+    this.matchCaches = new Array(tc).fill(null);
+    this.placeMatchTargets = Array.from({ length: pc }, () => []);
+    let anyMatch = false;
+    for (let tid = 0; tid < tc; tid++) {
+      if (compiled.hasMatch(tid)) {
+        anyMatch = true;
+        break;
+      }
+    }
+    if (!anyMatch) return;
+    const inputConsumers = Array.from({ length: pc }, () => []);
+    const resetTarget = new Array(pc).fill(false);
+    for (let tid = 0; tid < tc; tid++) {
+      const t = compiled.transition(tid);
+      for (const spec of t.inputSpecs) inputConsumers[compiled.placeId(spec.place)].push(tid);
+      for (const arc of t.resets) resetTarget[compiled.placeId(arc.place)] = true;
+    }
+    for (let tid = 0; tid < tc; tid++) {
+      if (!compiled.hasMatch(tid)) continue;
+      const t = compiled.transition(tid);
+      const ms = t.matchSpec;
+      if (!ms) continue;
+      const requireds = [];
+      let eligible = true;
+      for (const mk of ms.keys) {
+        const pid = compiled.placeId(mk.place);
+        const spec = t.inputSpecs.find((s) => s.place.name === mk.place.name);
+        let required;
+        if (spec?.type === "one") required = 1;
+        else if (spec?.type === "exactly") required = spec.count;
+        else {
+          eligible = false;
+          break;
+        }
+        const cons = inputConsumers[pid];
+        if (resetTarget[pid] || cons.length !== 1 || cons[0] !== tid) {
+          eligible = false;
+          break;
+        }
+        requireds.push(required);
+      }
+      if (!eligible) continue;
+      const matcher = new IncrementalMatcher(requireds);
+      for (let keyIdx = 0; keyIdx < ms.keys.length; keyIdx++) {
+        const mk = ms.keys[keyIdx];
+        const pid = compiled.placeId(mk.place);
+        const guard = t.inputSpecs.find((s) => s.place.name === mk.place.name)?.guard;
+        for (const token of this.marking.peekTokens(mk.place)) {
+          if (guard && !guard(token.value)) continue;
+          const name = mk.key(token.value);
+          if (name !== void 0 && name !== null) matcher.add(keyIdx, name, token.createdAt);
+        }
+        this.placeMatchTargets[pid].push([tid, keyIdx]);
+      }
+      this.matchCaches[tid] = matcher;
+    }
+  }
+  /** Mirror a token added to correlated input `pid` into every fast-path matcher. */
+  cacheAddToken(pid, token) {
+    const targets = this.placeMatchTargets[pid];
+    if (targets === void 0 || targets.length === 0) return;
+    const compiled = this.compiled;
+    for (const [tid, keyIdx] of targets) {
+      const cache = this.matchCaches[tid];
+      if (cache == null) continue;
+      const t = compiled.transition(tid);
+      const mk = t.matchSpec.keys[keyIdx];
+      const guard = t.inputSpecs.find((s) => s.place.name === mk.place.name)?.guard;
+      if (guard && !guard(token.value)) continue;
+      const name = mk.key(token.value);
+      if (name !== void 0 && name !== null) cache.add(keyIdx, name, token.createdAt);
+    }
   }
   // ======================== Execution ========================
   async run(timeoutMs) {
@@ -2974,12 +3368,22 @@ var BitmapNetExecutor = class {
     }
     if (this.compiled.hasGuards(tid)) {
       const t = this.compiled.transition(tid);
+      const cache = this.matchCaches[tid];
+      const ms = t.matchSpec;
       for (const spec of t.inputSpecs) {
         if (!spec.guard) continue;
+        if (cache != null && ms && keyForPlace(ms, spec.place.name) !== void 0) continue;
         const requiredCount2 = spec.type === "one" ? 1 : spec.type === "exactly" ? spec.count : spec.type === "at-least" ? spec.minimum : 1;
         if (this.marking.countMatching(spec) < requiredCount2) return false;
       }
     }
+    if (this.compiled.hasMatch(tid)) {
+      const cache = this.matchCaches[tid];
+      const noBinding = cache != null ? cache.best() === null : findBinding(this.compiled.transition(tid), (p) => this.marking.peekTokens(p)) === null;
+      if (noBinding) {
+        return false;
+      }
+    }
     return true;
   }
   hasInputFromResetPlace(t) {
@@ -3057,7 +3461,22 @@ var BitmapNetExecutor = class {
     const t = this.compiled.transition(tid);
     const inputs = new TokenInput();
     const consumed = [];
+    const ms = t.matchSpec;
+    const cache = ms ? this.matchCaches[tid] : null;
+    const chosen = ms ? cache != null ? cache.best() : findBinding(t, (p) => this.marking.peekTokens(p)) : null;
+    if (cache != null && chosen !== null) cache.consume(chosen);
     for (const inSpec of t.inputSpecs) {
+      const keyFn = ms ? keyForPlace(ms, inSpec.place.name) : void 0;
+      let spec;
+      if (keyFn && chosen !== null) {
+        const baseGuard = inSpec.guard;
+        spec = {
+          place: inSpec.place,
+          guard: (v) => (baseGuard ? baseGuard(v) : true) && keyFn(v) === chosen
+        };
+      } else {
+        spec = inSpec;
+      }
       let toConsume;
       switch (inSpec.type) {
         case "one":
@@ -3067,14 +3486,12 @@ var BitmapNetExecutor = class {
           toConsume = inSpec.count;
           break;
         case "all":
-          toConsume = inSpec.guard ? this.marking.countMatching(inSpec) : this.marking.tokenCount(inSpec.place);
-          break;
         case "at-least":
-          toConsume = inSpec.guard ? this.marking.countMatching(inSpec) : this.marking.tokenCount(inSpec.place);
+          toConsume = spec.guard ? this.marking.countMatching(spec) : this.marking.tokenCount(inSpec.place);
           break;
       }
       for (let i = 0; i < toConsume; i++) {
-        const token = inSpec.guard ? this.marking.removeFirstMatching(inSpec) : this.marking.removeFirst(inSpec.place);
+        const token = spec.guard ? this.marking.removeFirstMatching(spec) : this.marking.removeFirst(inSpec.place);
         if (token === null) break;
         consumed.push(token);
         inputs.add(inSpec.place, token);
@@ -3136,6 +3553,8 @@ var BitmapNetExecutor = class {
       logFn,
       t.placeAlias
     );
+    const freshNameBase = t.name;
+    context.setFreshNameSupplier(() => nameId(`${freshNameBase}#${this.freshNameCounter++}`));
     let actionPromise = t.action(context);
     if (t.hasActionTimeout()) {
       const timeoutSpec = t.actionTimeout;
@@ -3237,9 +3656,10 @@ var BitmapNetExecutor = class {
         }
         const produced = [];
         for (const entry of outputs.entries()) {
+          const pid = this.compiled.placeId(entry.place);
+          this.cacheAddToken(pid, entry.token);
           this.marking.addToken(entry.place, entry.token);
           produced.push(entry.token);
-          const pid = this.compiled.placeId(entry.place);
           setBit(this.markedPlaces, pid);
           this.markDirty(pid);
           this.emitEvent({
@@ -3280,8 +3700,9 @@ var BitmapNetExecutor = class {
     for (let i = 0; i < len; i++) {
       const event = this.externalQueue[i];
       try {
-        this.marking.addToken(event.place, event.token);
         const pid = this.compiled.placeId(event.place);
+        this.cacheAddToken(pid, event.token);
+        this.marking.addToken(event.place, event.token);
         setBit(this.markedPlaces, pid);
         this.markDirty(pid);
         this.emitEvent({
@@ -3488,6 +3909,9 @@ var PrecompiledNet = class _PrecompiledNet {
   // ==================== Cardinality & Guards ====================
   cardinalityChecks;
   hasGuards;
+  // ν-net join flag (NU-020): gates the match-binding check off the hot
+  // enablement path for non-ν transitions, mirroring `hasGuards`.
+  hasMatch;
   // ==================== Global Flags ====================
   allImmediate;
   allSamePriority;
@@ -3582,12 +4006,15 @@ var PrecompiledNet = class _PrecompiledNet {
     this.consumptionPlaceIds = consumptionPlaceIds;
     const cardinalityChecks = new Array(tc);
     const hasGuards = new Array(tc);
+    const hasMatch = new Array(tc);
     for (let tid = 0; tid < tc; tid++) {
       cardinalityChecks[tid] = compiled.cardinalityCheck(tid);
       hasGuards[tid] = compiled.hasGuards(tid);
+      hasMatch[tid] = compiled.hasMatch(tid);
     }
     this.cardinalityChecks = cardinalityChecks;
     this.hasGuards = hasGuards;
+    this.hasMatch = hasMatch;
     this.earliestMs = new Float64Array(tc);
     this.latestMs = new Float64Array(tc);
     this.hasDeadline = new Uint8Array(tc);
@@ -3783,6 +4210,28 @@ var PrecompiledNetExecutor = class {
   // ==================== Token Storage ====================
   /** Per-place token arrays, indexed by pid. */
   tokenQueues;
+  /** Monotonic source for ν-name minting (ctx.freshName(), NU-010). */
+  freshNameCounter = 0;
+  /**
+   * Per-transition ν-name minter cache, indexed by tid (built lazily). Each
+   * supplier is created once and reused across firings, so installing it on a
+   * per-fire context is a field assignment rather than a per-fire closure
+   * allocation — keeping the fire path lean for non-ν transitions. Every
+   * transition gets one (forks mint but carry no MatchSpec, so gating on
+   * `hasMatch` would wrongly starve them).
+   */
+  freshNameSuppliers = [];
+  // ==================== ν-net incremental match caches (NU-020) ====================
+  /**
+   * Per matched transition: an {@link IncrementalMatcher} kept in lockstep with
+   * the token queues when the transition is fast-path eligible (every correlated
+   * input is `one`/`exactly`, consumed by no other transition, and never reset),
+   * else `null` → fall back to the O(n) rebuild {@link findBinding}. This turns a
+   * draining matched join from O(n²) into O(n log n).
+   */
+  matchCaches = [];
+  /** Per place (by pid): the `[tid, keyIndex]` of every fast-path correlated input it feeds. */
+  placeMatchTargets = [];
   // ==================== Marking Bitmap ====================
   markingBitmap;
   // ==================== Transition State ====================
@@ -3869,6 +4318,92 @@ var PrecompiledNetExecutor = class {
     this.pendingResetWords = new Uint32Array(wc);
     this.markingSnapBuffer = new Uint32Array(wc);
     this.firingSnapBuffer = new Uint32Array(wc);
+    this.initMatchCaches();
+  }
+  /**
+   * Builds the ν-net incremental match caches (NU-020). A matched join is
+   * fast-path eligible only when every correlated input is `one`/`exactly`, is
+   * consumed by no other transition, and is never reset — so tokens enter a
+   * correlated input only via produce/inject (mirrored by `add`) and leave only
+   * via this join's matched consume (mirrored by `consume`), and the cache can
+   * never desync. Mirrors the Rust backends.
+   */
+  initMatchCaches() {
+    const prog = this.program;
+    const tc = prog.transitionCount;
+    const pc = prog.placeCount;
+    this.matchCaches = new Array(tc).fill(null);
+    this.placeMatchTargets = Array.from({ length: pc }, () => []);
+    let anyMatch = false;
+    for (let tid = 0; tid < tc; tid++) {
+      if (prog.hasMatch[tid]) {
+        anyMatch = true;
+        break;
+      }
+    }
+    if (!anyMatch) return;
+    const inputConsumers = Array.from({ length: pc }, () => []);
+    const resetTarget = new Array(pc).fill(false);
+    for (let tid = 0; tid < tc; tid++) {
+      const t = prog.compiled.transition(tid);
+      for (const spec of t.inputSpecs) inputConsumers[prog.compiled.placeId(spec.place)].push(tid);
+      for (const arc of t.resets) resetTarget[prog.compiled.placeId(arc.place)] = true;
+    }
+    for (let tid = 0; tid < tc; tid++) {
+      if (!prog.hasMatch[tid]) continue;
+      const t = prog.compiled.transition(tid);
+      const ms = t.matchSpec;
+      if (!ms) continue;
+      const requireds = [];
+      let eligible = true;
+      for (const mk of ms.keys) {
+        const pid = prog.compiled.placeId(mk.place);
+        const spec = t.inputSpecs.find((s) => s.place.name === mk.place.name);
+        let required;
+        if (spec?.type === "one") required = 1;
+        else if (spec?.type === "exactly") required = spec.count;
+        else {
+          eligible = false;
+          break;
+        }
+        const cons = inputConsumers[pid];
+        if (resetTarget[pid] || cons.length !== 1 || cons[0] !== tid) {
+          eligible = false;
+          break;
+        }
+        requireds.push(required);
+      }
+      if (!eligible) continue;
+      const matcher = new IncrementalMatcher(requireds);
+      for (let keyIdx = 0; keyIdx < ms.keys.length; keyIdx++) {
+        const mk = ms.keys[keyIdx];
+        const pid = prog.compiled.placeId(mk.place);
+        const guard = t.inputSpecs.find((s) => s.place.name === mk.place.name)?.guard;
+        for (const token of this.tokenQueues[pid]) {
+          if (guard && !guard(token.value)) continue;
+          const name = mk.key(token.value);
+          if (name !== void 0 && name !== null) matcher.add(keyIdx, name, token.createdAt);
+        }
+        this.placeMatchTargets[pid].push([tid, keyIdx]);
+      }
+      this.matchCaches[tid] = matcher;
+    }
+  }
+  /** Mirror a token added to correlated input `pid` into every fast-path matcher. */
+  cacheAddToken(pid, token) {
+    const targets = this.placeMatchTargets[pid];
+    if (targets === void 0 || targets.length === 0) return;
+    const prog = this.program;
+    for (const [tid, keyIdx] of targets) {
+      const cache = this.matchCaches[tid];
+      if (cache == null) continue;
+      const t = prog.compiled.transition(tid);
+      const mk = t.matchSpec.keys[keyIdx];
+      const guard = t.inputSpecs.find((s) => s.place.name === mk.place.name)?.guard;
+      if (guard && !guard(token.value)) continue;
+      const name = mk.key(token.value);
+      if (name !== void 0 && name !== null) cache.add(keyIdx, name, token.createdAt);
+    }
   }
   // ======================== Bitmap Helpers ========================
   markTransitionDirty(tid) {
@@ -4079,12 +4614,22 @@ var PrecompiledNetExecutor = class {
     }
     if (prog.hasGuards[tid]) {
       const t = prog.compiled.transition(tid);
+      const cache = this.matchCaches[tid];
+      const ms = t.matchSpec;
       for (const spec of t.inputSpecs) {
         if (!spec.guard) continue;
+        if (cache != null && ms && keyForPlace(ms, spec.place.name) !== void 0) continue;
         const required = spec.type === "one" ? 1 : spec.type === "exactly" ? spec.count : spec.type === "at-least" ? spec.minimum : 1;
         if (this.countMatching(prog.compiled.placeId(spec.place), spec.guard) < required) return false;
       }
     }
+    if (prog.hasMatch[tid]) {
+      const cache = this.matchCaches[tid];
+      const noBinding = cache != null ? cache.best() === null : findBinding(prog.compiled.transition(tid), (p) => this.tokenQueues[prog.compiled.placeId(p)]) === null;
+      if (noBinding) {
+        return false;
+      }
+    }
     return true;
   }
   countMatching(pid, guard) {
@@ -4099,7 +4644,7 @@ var PrecompiledNetExecutor = class {
     const q = this.tokenQueues[pid];
     for (let i = 0; i < q.length; i++) {
       if (guard(q[i].value)) {
-        return q.splice(i, 1)[0];
+        return i === 0 ? q.shift() : q.splice(i, 1)[0];
       }
     }
     return null;
@@ -4174,7 +4719,9 @@ var PrecompiledNetExecutor = class {
     const t = prog.compiled.transition(tid);
     const consumed = [];
     const inputs = new TokenInput();
-    if (prog.hasGuards[tid]) {
+    if (t.matchSpec) {
+      this.fireTransitionMatched(tid, t, inputs, consumed);
+    } else if (prog.hasGuards[tid]) {
       this.fireTransitionGuarded(tid, t, inputs, consumed);
     } else {
       const ops = prog.consumeOps[tid];
@@ -4308,6 +4855,13 @@ var PrecompiledNetExecutor = class {
       logFn,
       t.placeAlias
     );
+    let freshNameSupplier = this.freshNameSuppliers[tid];
+    if (freshNameSupplier === void 0) {
+      const base = t.name;
+      freshNameSupplier = () => nameId(`${base}#${this.freshNameCounter++}`);
+      this.freshNameSuppliers[tid] = freshNameSupplier;
+    }
+    context.setFreshNameSupplier(freshNameSupplier);
     let actionPromise = t.action(context);
     if (t.hasActionTimeout()) {
       const timeoutSpec = t.actionTimeout;
@@ -4361,6 +4915,65 @@ var PrecompiledNetExecutor = class {
     this.enabledTransitionCount--;
     this.enabledAtMs[tid] = -Infinity;
   }
+  /**
+   * Consumes the name-matched tokens for a ν-net join (NU-020): correlated
+   * inputs take tokens whose projected name equals the chosen binding (guard
+   * first, then name equality — NU-021); other inputs consume FIFO. Reset arcs
+   * are honoured as on the opcode path. Mirrors {@link fireTransitionGuarded}.
+   */
+  fireTransitionMatched(tid, t, inputs, consumed) {
+    const prog = this.program;
+    const ms = t.matchSpec;
+    const cache = this.matchCaches[tid];
+    const chosen = cache != null ? cache.best() : findBinding(t, (p) => this.tokenQueues[prog.compiled.placeId(p)]);
+    if (cache != null && chosen !== null) cache.consume(chosen);
+    for (const inSpec of t.inputSpecs) {
+      const pid = prog.compiled.placeId(inSpec.place);
+      const keyFn = keyForPlace(ms, inSpec.place.name);
+      const baseGuard = inSpec.guard;
+      const pred = keyFn && chosen !== null ? (v) => (baseGuard ? baseGuard(v) : true) && keyFn(v) === chosen : baseGuard;
+      let toConsume;
+      switch (inSpec.type) {
+        case "one":
+          toConsume = 1;
+          break;
+        case "exactly":
+          toConsume = inSpec.count;
+          break;
+        case "all":
+        case "at-least":
+          toConsume = pred ? this.countMatching(pid, pred) : this.tokenQueues[pid].length;
+          break;
+      }
+      for (let i = 0; i < toConsume; i++) {
+        const token = pred ? this.removeFirstMatching(pid, pred) : this.tokenQueues[pid].shift() ?? null;
+        if (token === null) break;
+        consumed.push(token);
+        inputs.add(inSpec.place, token);
+        this.emitEvent({
+          type: "token-removed",
+          timestamp: Date.now(),
+          placeName: inSpec.place.name,
+          token
+        });
+      }
+    }
+    for (const arc of t.resets) {
+      const pid = prog.compiled.placeId(arc.place);
+      const tokens = this.tokenQueues[pid].splice(0);
+      this.pendingResetWords[pid >>> WORD_SHIFT] |= 1 << (pid & BIT_MASK);
+      this.hasPendingResets = true;
+      for (const token of tokens) {
+        consumed.push(token);
+        this.emitEvent({
+          type: "token-removed",
+          timestamp: Date.now(),
+          placeName: arc.place.name,
+          token
+        });
+      }
+    }
+  }
   fireTransitionGuarded(_tid, t, inputs, consumed) {
     const prog = this.program;
     for (const inSpec of t.inputSpecs) {
@@ -4475,6 +5088,7 @@ var PrecompiledNetExecutor = class {
         const produced = [];
         for (const entry of outputs.entries()) {
           const pid = prog.compiled.placeId(entry.place);
+          this.cacheAddToken(pid, entry.token);
           this.tokenQueues[pid].push(entry.token);
           produced.push(entry.token);
           this.setMarkingBit(pid);
@@ -4519,6 +5133,7 @@ var PrecompiledNetExecutor = class {
       const event = this.externalQueue[i];
       try {
         const pid = prog.compiled.placeId(event.place);
+        this.cacheAddToken(pid, event.token);
         this.tokenQueues[pid].push(event.token);
         this.setMarkingBit(pid);
         this.markDirty(pid);
@@ -4719,8 +5334,13 @@ export {
   intersects,
   isFailureEvent,
   isUnit,
+  keyForPlace,
   latest,
+  matchCorrelates,
+  matchKey,
+  matchSpec,
   matchesGuard,
+  nameId,
   noopEventStore,
   one,
   openSubnet,