libpetri 2.7.0 → 2.8.0

package/dist/{petri-net-D73-PO6d.d.ts → petri-net-B4wQwsUj.d.ts}

@@ -157,6 +157,85 @@ declare function requiredCount(spec: In): number;
  */
 declare function consumptionCount(spec: In, available: number): number;
 
+/**
+ * ν-net token identities ([[NameId]]).
+ *
+ * A {@link NameId} is an **opaque correlation identity** carried by a token so
+ * that a fork can mint a fresh name and a later join can re-merge exactly the
+ * siblings that share it (see {@link import('./match-spec.js').MatchSpec}). The
+ * only operation defined on names is **equality** (`===`); names also have a
+ * lexicographic order used purely for the deterministic match tie-break
+ * (NU-020).
+ *
+ * Identity is a *projection* of the token payload, not a field on
+ * {@link import('./token.js').Token}: a `MatchSpec` declares the
+ * `value → NameId` key, and the fork mints a fresh name into the payload via
+ * `ctx.freshName()`. This keeps `Token` (and the event/archive formats)
+ * unchanged while still giving the analyzer a name-symmetric uninterpreted sort
+ * to reason about (spec NU-001).
+ */
+/** An opaque correlation identity for ν-net fork/join (a branded string). */
+type NameId = string & {
+    readonly __nameIdBrand: unique symbol;
+};
+/** Creates a {@link NameId} from a string. */
+declare function nameId(value: string): NameId;
+
+/**
+ * ν-net join correlation ([[MatchSpec]]).
+ *
+ * A {@link MatchSpec} declares that a subset of a transition's **input** places
+ * must be correlated by **name equality**: the transition is enabled only when
+ * there exists a single {@link NameId} `n` such that every correlated input
+ * supplies (at least) its required token count whose projected name equals `n`.
+ * On firing, exactly those name-matched tokens are consumed (spec NU-020).
+ *
+ * This is the single *decidable* predicate — equality of opaque names — and is
+ * deliberately NOT a general guard: it correlates the name dimension *across*
+ * places (composition-structural, like cardinality) rather than evaluating an
+ * arbitrary boolean per token. When both a unary input `guard` and a match are
+ * present the guard filters first, then the name correlation runs over the
+ * survivors (NU-021).
+ */
+
+/**
+ * A name projection: maps a token's value to its {@link NameId}. A projection
+ * that yields no name (returns `null`/`undefined` at runtime) is treated as
+ * "no name" — that token never correlates — mirroring the Java/Rust `KeyFn`
+ * contract; the binding selector handles a nullish result defensively.
+ */
+type KeyFn<T = any> = (value: T) => NameId;
+/** One correlated input: the place plus its name projection. */
+interface MatchKey<T = any> {
+    readonly place: Place<T>;
+    readonly key: KeyFn<T>;
+}
+/** Correlated fork/join match specification (ν-net join side). */
+interface MatchSpec {
+    readonly keys: readonly MatchKey[];
+}
+/** Builds one correlated input for a {@link MatchSpec}. */
+declare function matchKey<T>(place: Place<T>, key: KeyFn<T>): MatchKey<T>;
+/**
+ * Builds a {@link MatchSpec} from two or more correlated inputs.
+ *
+ * @example
+ *   Transition.builder('join')
+ *     .inputs(one(branchA), one(branchB))
+ *     .match(matchSpec(
+ *       matchKey(branchA, (m: Msg) => nameId(m.correlationId)),
+ *       matchKey(branchB, (m: Msg) => nameId(m.correlationId)),
+ *     ))
+ *
+ * @throws if fewer than two inputs are correlated (a match over a single place
+ *   is just a guard).
+ */
+declare function matchSpec(...keys: MatchKey[]): MatchSpec;
+/** Returns the name projection for `placeName`, or `undefined` if not correlated. */
+declare function keyForPlace(spec: MatchSpec, placeName: string): KeyFn | undefined;
+/** True when `placeName` is one of the correlated inputs. */
+declare function matchCorrelates(spec: MatchSpec, placeName: string): boolean;
+
 /**
  * Output specification with explicit split semantics.
  * Supports composite structures (XOR of ANDs, AND of XORs, etc.)
@@ -364,6 +443,7 @@ declare class TransitionContext {
     private readonly executionCtx;
     private readonly _logFn?;
     private readonly placeAlias;
+    private _freshNameSupplier?;
     constructor(transitionName: string, rawInput: TokenInput, rawOutput: TokenOutput, inputPlaces: ReadonlySet<Place<any>>, readPlaces: ReadonlySet<Place<any>>, outputPlaces: ReadonlySet<Place<any>>, executionContext?: Map<string, unknown>, logFn?: LogFn, placeAlias?: ReadonlyMap<string, Place<any>>);
     /**
      * Resolves a place key through the transition's declared→actual place
@@ -416,6 +496,22 @@ declare class TransitionContext {
     /** Returns declared output places. */
     outputPlaces(): ReadonlySet<Place<any>>;
     private requireOutput;
+    /**
+     * @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: () => NameId): void;
+    /**
+     * 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(): NameId;
     /** Returns the transition name. */
     transitionName(): string;
     /** Retrieves an execution context object by key. */
@@ -503,6 +599,11 @@ declare class Transition {
     readonly actionTimeout: OutTimeout | null;
     readonly action: TransitionAction;
     readonly priority: number;
+    /**
+     * ν-net join correlation: a subset of `inputSpecs` that must be correlated by
+     * name equality on firing (spec NU-020). `null` for ordinary transitions.
+     */
+    readonly matchSpec: MatchSpec | null;
     /**
      * Per-transition **declared → actual** place correspondence (per
      * **MOD-031**), keyed by the author-original declared place **name** →
@@ -519,7 +620,7 @@ declare class Transition {
     private readonly _readPlaces;
     private readonly _outputPlaces;
     /** @internal Use {@link Transition.builder} to create instances. */
-    constructor(key: symbol, name: string, inputSpecs: readonly In[], outputSpec: Out | null, inhibitors: readonly ArcInhibitor[], reads: readonly ArcRead[], resets: readonly ArcReset[], timing: Timing, action: TransitionAction, priority: number, placeAlias?: ReadonlyMap<string, Place<any>>);
+    constructor(key: symbol, name: string, inputSpecs: readonly In[], outputSpec: Out | null, inhibitors: readonly ArcInhibitor[], reads: readonly ArcRead[], resets: readonly ArcReset[], timing: Timing, action: TransitionAction, priority: number, placeAlias?: ReadonlyMap<string, Place<any>>, matchSpec?: MatchSpec | null);
     /** Returns set of input places — consumed tokens. */
     inputPlaces(): ReadonlySet<Place<any>>;
     /** Returns set of read places — context tokens, not consumed. */
@@ -542,6 +643,7 @@ declare class TransitionBuilder {
     private _action;
     private _priority;
     private _placeAlias;
+    private _matchSpec;
     constructor(name: string);
     /** Add input specifications with cardinality. */
     inputs(...specs: In[]): this;
@@ -565,6 +667,12 @@ declare class TransitionBuilder {
     action(action: TransitionAction): this;
     /** Set the priority (higher fires first). */
     priority(priority: number): 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: MatchSpec): this;
     /**
      * Sets the per-transition declared→actual place correspondence (per
      * **MOD-031**). Populated by the subnet rewriter during the compose-time
@@ -672,7 +780,7 @@ declare class InterfaceBuilder {
  * violates the property, Spacer finds a counterexample. If no violation
  * is reachable, the property is proven.
  */
-type SmtProperty = DeadlockFree | MutualExclusion | PlaceBound | Unreachable;
+type SmtProperty = DeadlockFree | MutualExclusion | PlaceBound | Unreachable | BranchPlaceBound | JoinedOrDeadLettered;
 /** Deadlock-freedom: no reachable marking has all transitions disabled. */
 interface DeadlockFree {
     readonly type: 'deadlock-free';
@@ -694,10 +802,39 @@ interface Unreachable {
     readonly type: 'unreachable';
     readonly places: ReadonlySet<Place<any>>;
 }
+/**
+ * Branch / budget place bound: a ν-net budget or fork-branch place never
+ * exceeds `bound` tokens — the bounded-budget decidability lever (NU-040).
+ *
+ * Encodes identically to {@link PlaceBound} (a linear-integer count bound), but
+ * names the ν-net intent: the live correlation pool is bounded, keeping the
+ * well-structured transition system finite. The matched-transition
+ * over-approximation is sound for this safety bound — a `proven` verdict holds
+ * for the real net, which fires strictly fewer joins than the over-approximation.
+ */
+interface BranchPlaceBound {
+    readonly type: 'branch-place-bound';
+    readonly place: Place<any>;
+    readonly bound: number;
+}
+/**
+ * Joined-or-dead-lettered: every forked name is eventually joined or
+ * dead-lettered, so no reachable *quiescent* (deadlocked) marking still holds a
+ * token in `pending` (NU-040). Violated when a reachable marking is both
+ * quiescent and has `pending >= 1` — a stranded correlation group.
+ */
+interface JoinedOrDeadLettered {
+    readonly type: 'joined-or-dead-lettered';
+    readonly pending: Place<any>;
+}
 declare function deadlockFree(): DeadlockFree;
 declare function mutualExclusion(p1: Place<any>, p2: Place<any>): MutualExclusion;
 declare function placeBound(place: Place<any>, bound: number): PlaceBound;
 declare function unreachable(places: ReadonlySet<Place<any>>): Unreachable;
+/** Branch / budget place bound (NU-040). See {@link BranchPlaceBound}. */
+declare function branchPlaceBound(place: Place<any>, bound: number): BranchPlaceBound;
+/** Joined-or-dead-lettered at quiescence (NU-040). See {@link JoinedOrDeadLettered}. */
+declare function joinedOrDeadLettered(pending: Place<any>): JoinedOrDeadLettered;
 /** Human-readable description of a property. */
 declare function propertyDescription(prop: SmtProperty): string;
 
@@ -1591,4 +1728,4 @@ declare class PetriNetBuilder {
     private buildWithFusion;
 }
 
-export { and as $, type Arc as A, SubnetDefBuilder as B, type Channel as C, type SubnetInstance as D, type EnvironmentPlace as E, FusionSet as F, type Timing as G, type TimingDeadline as H, type In as I, type TimingDelayed as J, type TimingExact as K, type LogFn as L, MAX_DURATION_MS as M, type TimingImmediate as N, type Out as O, PetriNet as P, type TimingWindow as Q, TokenInput as R, SubnetDef as S, type Token as T, TokenOutput as U, type TransitionAction as V, TransitionBuilder as W, type VerificationHarness as X, type VerificationResult as Y, all as Z, allPlaces as _, type Place as a, placeBound as a$, andPlaces as a0, arcPlace as a1, atLeast as a2, consumptionCount as a3, deadline as a4, delayed as a5, earliest as a6, enumerateBranches as a7, environmentPlace as a8, exact as a9, transformFrom as aA, unitToken as aB, window as aC, withTimeout as aD, xor as aE, xorPlaces as aF, MarkingState as aG, type PInvariant as aH, MarkingStateBuilder as aI, type SmtProperty as aJ, type SmtVerificationResult as aK, type DeadlockFree as aL, type MutualExclusion as aM, type PlaceBound as aN, type Proven as aO, type SmtStatistics as aP, type TokenSupplier as aQ, type Unknown as aR, type Unreachable as aS, type Verdict as aT, type Violated as aU, deadlockFree as aV, isProven as aW, isViolated as aX, mutualExclusion as aY, pInvariant as aZ, pInvariantToString as a_, exactly as aa, fork as ab, forwardInput as ac, hasDeadline as ad, hasGuard as ae, immediate as af, inhibitorArc as ag, inputArc as ah, isUnit as ai, latest as aj, matchesGuard as ak, one as al, outPlace as am, outputArc as an, passthrough as ao, place as ap, produce as aq, readArc as ar, requiredCount as as, resetArc as at, timeout as au, timeoutPlace as av, tokenAt as aw, tokenOf as ax, transform as ay, transformAsync as az, Transition as b, propertyDescription as b0, unreachable as b1, TransitionContext as c, type ArcInhibitor as d, type ArcInput as e, type ArcOutput as f, type ArcRead as g, type ArcReset as h, ComposeBindings as i, FusionSetBuilder as j, type InAll as k, type InAtLeast as l, type InExactly as m, type InOne as n, Instance as o, Interface as p, InterfaceBuilder as q, type OutAnd as r, type OutForwardInput as s, type OutPlace as t, type OutTimeout as u, type OutXor as v, type OutputEntry as w, PetriNetBuilder as x, type Port as y, type PortDirection as z };
+export { type VerificationHarness as $, type Arc as A, type Port as B, type Channel as C, type PortDirection as D, type EnvironmentPlace as E, FusionSet as F, SubnetDefBuilder as G, type SubnetInstance as H, type In as I, type Timing as J, type KeyFn as K, type LogFn as L, MAX_DURATION_MS as M, type NameId as N, type Out as O, PetriNet as P, type TimingDeadline as Q, type TimingDelayed as R, SubnetDef as S, type Token as T, type TimingExact as U, type TimingImmediate as V, type TimingWindow as W, TokenInput as X, TokenOutput as Y, type TransitionAction as Z, TransitionBuilder as _, type Place as a, type TokenSupplier as a$, type VerificationResult as a0, all as a1, allPlaces as a2, and as a3, andPlaces as a4, arcPlace as a5, atLeast as a6, consumptionCount as a7, deadline as a8, delayed as a9, readArc as aA, requiredCount as aB, resetArc as aC, timeout as aD, timeoutPlace as aE, tokenAt as aF, tokenOf as aG, transform as aH, transformAsync as aI, transformFrom as aJ, unitToken as aK, window as aL, withTimeout as aM, xor as aN, xorPlaces as aO, MarkingState as aP, type PInvariant as aQ, MarkingStateBuilder as aR, type SmtProperty as aS, type SmtVerificationResult as aT, type BranchPlaceBound as aU, type DeadlockFree as aV, type JoinedOrDeadLettered as aW, type MutualExclusion as aX, type PlaceBound as aY, type Proven as aZ, type SmtStatistics as a_, earliest as aa, enumerateBranches as ab, environmentPlace as ac, exact as ad, exactly as ae, fork as af, forwardInput as ag, hasDeadline as ah, hasGuard as ai, immediate as aj, inhibitorArc as ak, inputArc as al, isUnit as am, keyForPlace as an, latest as ao, matchCorrelates as ap, matchKey as aq, matchSpec as ar, matchesGuard as as, nameId as at, one as au, outPlace as av, outputArc as aw, passthrough as ax, place as ay, produce as az, Transition as b, type Unknown as b0, type Unreachable as b1, type Verdict as b2, type Violated as b3, branchPlaceBound as b4, deadlockFree as b5, isProven as b6, isViolated as b7, joinedOrDeadLettered as b8, mutualExclusion as b9, pInvariant as ba, pInvariantToString as bb, placeBound as bc, propertyDescription as bd, unreachable as be, TransitionContext as c, type ArcInhibitor as d, type ArcInput as e, type ArcOutput as f, type ArcRead as g, type ArcReset as h, ComposeBindings as i, FusionSetBuilder as j, type InAll as k, type InAtLeast as l, type InExactly as m, type InOne as n, Instance as o, Interface as p, InterfaceBuilder as q, type MatchKey as r, type MatchSpec as s, type OutAnd as t, type OutForwardInput as u, type OutPlace as v, type OutTimeout as w, type OutXor as x, type OutputEntry as y, PetriNetBuilder as z };

package/dist/verification/index.d.ts

@@ -1,5 +1,5 @@
-import { b as Transition, a as Place, P as PetriNet, E as EnvironmentPlace, aG as MarkingState, aH as PInvariant, aI as MarkingStateBuilder, aJ as SmtProperty, aK as SmtVerificationResult } from '../petri-net-D73-PO6d.js';
-export { aL as DeadlockFree, aM as MutualExclusion, aN as PlaceBound, aO as Proven, aP as SmtStatistics, aQ as TokenSupplier, aR as Unknown, aS as Unreachable, aT as Verdict, X as VerificationHarness, Y as VerificationResult, aU as Violated, aV as deadlockFree, aW as isProven, aX as isViolated, aY as mutualExclusion, aZ as pInvariant, a_ as pInvariantToString, a$ as placeBound, b0 as propertyDescription, b1 as unreachable } from '../petri-net-D73-PO6d.js';
+import { b as Transition, a as Place, P as PetriNet, E as EnvironmentPlace, aP as MarkingState, aQ as PInvariant, aR as MarkingStateBuilder, aS as SmtProperty, aT as SmtVerificationResult } from '../petri-net-B4wQwsUj.js';
+export { aU as BranchPlaceBound, aV as DeadlockFree, aW as JoinedOrDeadLettered, aX as MutualExclusion, aY as PlaceBound, aZ as Proven, a_ as SmtStatistics, a$ as TokenSupplier, b0 as Unknown, b1 as Unreachable, b2 as Verdict, $ as VerificationHarness, a0 as VerificationResult, b3 as Violated, b4 as branchPlaceBound, b5 as deadlockFree, b6 as isProven, b7 as isViolated, b8 as joinedOrDeadLettered, b9 as mutualExclusion, ba as pInvariant, bb as pInvariantToString, bc as placeBound, bd as propertyDescription, be as unreachable } from '../petri-net-B4wQwsUj.js';
 import { Expr, init, Bool, FuncDecl } from 'z3-solver';
 
 /**
@@ -275,8 +275,10 @@ declare class SmtVerifier {
     private _property;
     private readonly _environmentPlaces;
     private readonly _sinkPlaces;
+    private readonly _budgetPlaces;
     private _environmentMode;
     private _timeoutMs;
+    private _nuMaxClasses;
     private constructor();
     static forNet(net: PetriNet): SmtVerifier;
     initialMarking(marking: MarkingState): this;
@@ -289,11 +291,47 @@ declare class SmtVerifier {
      * Markings where any sink place has a token are not considered deadlocks.
      */
     sinkPlaces(...places: Place<any>[]): this;
+    /**
+     * Declares ν-net budget places (NU-040): places whose token count bounds the
+     * live correlation pool (they gate fresh-name minting). Declaring at least one
+     * places the net in the decidable bounded fragment, so reachability-safety
+     * properties over its ν-joins are verified (the matched transitions are
+     * over-approximated). Without any budget place, a net that mints fresh names
+     * is treated as unbounded and the verifier returns `unknown` (NU-050).
+     */
+    budgetPlaces(...places: Place<any>[]): this;
     timeout(ms: number): this;
+    /**
+     * Sets the class-count cap for the ν-aware state-class-graph analysis (NU-050,
+     * Route B). When the symbolic name-aware graph would exceed this, the analysis
+     * truncates and the verdict is `unknown` (the live correlation pool is not
+     * structurally bounded). Default 100_000.
+     */
+    nuMaxClasses(max: number): this;
     /**
      * Runs the verification pipeline.
      */
     verify(): Promise<SmtVerificationResult>;
+    /**
+     * ν-net soundness guard (NU-040, NU-050). Applied only when the net contains
+     * match (ν-join) transitions, and only to a proven/violated verdict (an
+     * existing unknown is left as-is).
+     *
+     * - Quiescence-based properties (deadlock / joined-or-dead-lettered): the
+     *   name-blind over-approximation over-fires joins, so it sees fewer quiescent
+     *   states and may miss a real stranded marking — downgraded to unknown
+     *   (exact quiescence reasoning is deferred to the SCG name-partition quotient).
+     * - Reachability-safety with unbounded fresh names (no budget declared):
+     *   reachability over unbounded fresh names is undecidable — unknown.
+     * - Bounded reachability-safety in the name-coloured fragment (`exact`): name
+     *   equality is encoded exactly via bounded name-colouring, so the verdict is
+     *   sound *and* complete within the budget — no spurious different-name
+     *   counterexample. The verdict is kept and the exact-path note is appended.
+     * - Bounded reachability-safety outside that fragment: `proven` is sound; a
+     *   `violated` may be spurious — the verdict is kept and the over-approximation
+     *   caveat is appended to the report.
+     */
+    private applyNuGuard;
 }
 
 /**