libpetri 2.7.0 → 2.8.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) {
@@ -2210,6 +2280,9 @@ var PetriNetBuilder = class _PetriNetBuilder {
 };
 function rebuildWithAction(t, action) {
   const builder = Transition.builder(t.name).timing(t.timing).priority(t.priority).action(action);
+  if (t.placeAlias.size > 0) {
+    builder.placeAlias(t.placeAlias);
+  }
   if (t.inputSpecs.length > 0) {
     builder.inputs(...t.inputSpecs);
   }
@@ -2384,6 +2457,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();
@@ -2415,12 +2492,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;
@@ -2502,6 +2581,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:
@@ -2606,6 +2688,81 @@ 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;
+}
+
 // src/runtime/out-violation-error.ts
 var OutViolationError = class extends Error {
   constructor(message) {
@@ -2679,6 +2836,8 @@ function produceTimeoutOutput(context, timeoutChild) {
 var BitmapNetExecutor = class {
   compiled;
   marking;
+  /** Monotonic source for ν-name minting (ctx.freshName(), NU-010). */
+  freshNameCounter = 0;
   eventStore;
   environmentPlaces;
   hasEnvironmentPlaces;
@@ -2977,6 +3136,12 @@ var BitmapNetExecutor = class {
         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) {
+        return false;
+      }
+    }
     return true;
   }
   hasInputFromResetPlace(t) {
@@ -3054,7 +3219,20 @@ var BitmapNetExecutor = class {
     const t = this.compiled.transition(tid);
     const inputs = new TokenInput();
     const consumed = [];
+    const ms = t.matchSpec;
+    const chosen = ms ? findBinding(t, (p) => this.marking.peekTokens(p)) : null;
     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":
@@ -3064,14 +3242,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);
@@ -3133,6 +3309,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;
@@ -3485,6 +3663,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;
@@ -3579,12 +3760,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);
@@ -3780,6 +3964,17 @@ 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 = [];
   // ==================== Marking Bitmap ====================
   markingBitmap;
   // ==================== Transition State ====================
@@ -4082,6 +4277,12 @@ var PrecompiledNetExecutor = class {
         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) {
+        return false;
+      }
+    }
     return true;
   }
   countMatching(pid, guard) {
@@ -4171,7 +4372,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];
@@ -4305,6 +4508,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;
@@ -4358,6 +4568,63 @@ 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 chosen = findBinding(t, (p) => this.tokenQueues[prog.compiled.placeId(p)]);
+    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) {
@@ -4716,8 +4983,13 @@ export {
   intersects,
   isFailureEvent,
   isUnit,
+  keyForPlace,
   latest,
+  matchCorrelates,
+  matchKey,
+  matchSpec,
   matchesGuard,
+  nameId,
   noopEventStore,
   one,
   openSubnet,