libpetri 2.8.0 → 2.10.0

package/README.md

@@ -68,6 +68,10 @@ Supported properties:
 
 Also computes **P-invariants** (Farkas variant) and supports IC3/PDR-style incremental verification.
 
+### ν-nets (`src/runtime/`)
+
+Correlated fork/join by identity. A `MatchSpec` declares a `value → NameId` key projection over a transition's input places; a fork mints a fresh opaque name via `ctx.freshName()` into the token payload, and a join consumes only the sibling tokens that project to the same name. The deterministic `(oldest-timestamp, then name)` tie-break is byte-identical across implementations (NU-022), and an incremental matcher keeps correlated-join drain at O(N log N). A bounded `Budget` place is the decidability lever for verification.
+
 ## Quick Start
 
 ```typescript

package/dist/index.d.ts

@@ -254,6 +254,16 @@ declare class BitmapNetExecutor implements PetriNetExecutor {
     private readonly marking;
     /** Monotonic source for ν-name minting (ctx.freshName(), NU-010). */
     private freshNameCounter;
+    /**
+     * ν-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.
+     */
+    private matchCaches;
+    private placeMatchTargets;
     private readonly eventStore;
     private readonly environmentPlaces;
     private readonly hasEnvironmentPlaces;
@@ -291,6 +301,15 @@ declare class BitmapNetExecutor implements PetriNetExecutor {
     private draining;
     private closed;
     constructor(net: PetriNet, initialTokens: Map<Place<any>, Token<any>[]>, options?: BitmapNetExecutorOptions);
+    /**
+     * 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.
+     */
+    private initMatchCaches;
+    /** Mirror a token added to correlated input `pid` into every fast-path matcher. */
+    private cacheAddToken;
     run(timeoutMs?: number): Promise<Marking>;
     private executeLoop;
     inject<T>(envPlace: EnvironmentPlace<T>, token: Token<T>): Promise<boolean>;
@@ -515,6 +534,16 @@ declare class PrecompiledNetExecutor implements PetriNetExecutor {
      * `hasMatch` would wrongly starve them).
      */
     private readonly freshNameSuppliers;
+    /**
+     * 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).
+     */
+    private matchCaches;
+    /** Per place (by pid): the `[tid, keyIndex]` of every fast-path correlated input it feeds. */
+    private placeMatchTargets;
     private readonly markingBitmap;
     private readonly dirtyBitmap;
     private readonly dirtyScanBuffer;
@@ -545,6 +574,17 @@ declare class PrecompiledNetExecutor implements PetriNetExecutor {
     private closed;
     private marking;
     constructor(net: PetriNet, initialTokens: Map<Place<any>, Token<any>[]>, options?: PrecompiledNetExecutorOptions);
+    /**
+     * 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.
+     */
+    private initMatchCaches;
+    /** Mirror a token added to correlated input `pid` into every fast-path matcher. */
+    private cacheAddToken;
     private markTransitionDirty;
     private markDirty;
     private setMarkingBit;

package/dist/index.js

@@ -2368,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;
       }
     }
@@ -2762,6 +2763,206 @@ function guardFor(t, placeName) {
   }
   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;
+  /** Monotonic fast path: ascending `(rep_ts, name)`; `fifo[fifoHead]` (after
+   * `cleanTop`) is the min. Active while `!heaped`. Advance `fifoHead` instead of
+   * `shift()` (O(1)); reset when the head catches the length. */
+  fifo = [];
+  fifoHead = 0;
+  /** Largest entry appended to `fifo` in the current monotonic run. */
+  maxPushed = null;
+  /** Once an out-of-order push migrates `fifo` into `heap`. */
+  heaped = false;
+  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() {
+    if (this.heaped) {
+      const top = this.heap.peek();
+      return top ? top.name : null;
+    }
+    return this.fifoHead < this.fifo.length ? this.fifo[this.fifoHead].name : null;
+  }
+  /**
+   * Route a ready name's `(rep, name)` to the active structure: append to the
+   * FIFO in O(1) while pushes stay non-decreasing; on the first inversion,
+   * migrate the FIFO into the heap and stay heap-backed.
+   */
+  pushReady(rep, name) {
+    const entry = { ts: rep, name };
+    if (this.heaped) {
+      this.heap.push(entry);
+      return;
+    }
+    const max = this.maxPushed;
+    const monotonic = max === null || rep > max.ts || rep === max.ts && name >= max.name;
+    if (monotonic) {
+      this.maxPushed = entry;
+      this.fifo.push(entry);
+    } else {
+      this.heaped = true;
+      for (let i = this.fifoHead; i < this.fifo.length; i++) this.heap.push(this.fifo[i]);
+      this.fifo.length = 0;
+      this.fifoHead = 0;
+      this.heap.push(entry);
+    }
+  }
+  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.pushReady(rep, name);
+      }
+    } else {
+      this.ready.delete(name);
+    }
+  }
+  cleanTop() {
+    if (this.heaped) {
+      for (; ; ) {
+        const top = this.heap.peek();
+        if (top && this.ready.get(top.name) !== top.ts) this.heap.pop();
+        else break;
+      }
+      if (this.heap.size === 0) {
+        this.heaped = false;
+        this.maxPushed = null;
+      }
+    } else {
+      while (this.fifoHead < this.fifo.length) {
+        const top = this.fifo[this.fifoHead];
+        if (this.ready.get(top.name) !== top.ts) this.fifoHead++;
+        else break;
+      }
+      if (this.fifoHead >= this.fifo.length) {
+        this.fifo.length = 0;
+        this.fifoHead = 0;
+        this.maxPushed = null;
+      }
+    }
+  }
+  /** Test-only: has the matcher fallen back from the FIFO fast path to the heap? */
+  isHeaped() {
+    return this.heaped;
+  }
+};
 
 // src/runtime/out-violation-error.ts
 var OutViolationError = class extends Error {
@@ -2838,6 +3039,16 @@ var BitmapNetExecutor = class {
   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;
@@ -2932,6 +3143,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) {
@@ -3130,15 +3425,19 @@ 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 tMatch = this.compiled.transition(tid);
-      if (findBinding(tMatch, (p) => this.marking.peekTokens(p)) === null) {
+      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;
       }
     }
@@ -3220,7 +3519,9 @@ var BitmapNetExecutor = class {
     const inputs = new TokenInput();
     const consumed = [];
     const ms = t.matchSpec;
-    const chosen = ms ? findBinding(t, (p) => this.marking.peekTokens(p)) : null;
+    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;
@@ -3412,9 +3713,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({
@@ -3455,8 +3757,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({
@@ -3975,6 +4278,17 @@ var PrecompiledNetExecutor = class {
    * `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 ====================
@@ -4061,6 +4375,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) {
@@ -4271,15 +4671,19 @@ 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 tMatch = prog.compiled.transition(tid);
-      if (findBinding(tMatch, (p) => this.tokenQueues[prog.compiled.placeId(p)]) === null) {
+      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;
       }
     }
@@ -4297,7 +4701,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;
@@ -4574,10 +4978,12 @@ var PrecompiledNetExecutor = class {
    * 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) {
+  fireTransitionMatched(tid, t, inputs, consumed) {
     const prog = this.program;
     const ms = t.matchSpec;
-    const chosen = findBinding(t, (p) => this.tokenQueues[prog.compiled.placeId(p)]);
+    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);
@@ -4739,6 +5145,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);
@@ -4783,6 +5190,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);