libpetri 4.1.0 → 5.1.0

package/dist/{petri-net-p0ONpSAO.d.ts → petri-net-6G5r1Wwb.d.ts}

@@ -239,6 +239,16 @@ declare function matchCorrelates(spec: MatchSpec, placeName: string): boolean;
  * - Place: Leaf node representing a single output place
  * - Timeout: Timeout branch that activates if action exceeds duration
  * - ForwardInput: Forward consumed input to output on timeout
+ *
+ * A spec names **places, not counts**. Validation ([IO-015]) compares the SET of
+ * places an action wrote against the branches' claims, so an action that deposits
+ * several tokens into one named place is accepted — and every analysis that
+ * enumerates branches ({@link enumerateBranches}: the state-class graph, the SMT
+ * encoding, the ν fragment check) models exactly one token per named place. Such a
+ * firing therefore does more than the analyses explore, in the direction that can
+ * make a `proven` false. The executors report it once per transition as a `WARN`
+ * log-message ([IO-016]); a net meant to be verified should produce one token per
+ * named place and express multiplicity in its topology.
  */
 type Out = OutAnd | OutXor | OutPlace | OutTimeout | OutForwardInput;
 interface OutAnd {
@@ -294,11 +304,19 @@ declare function forwardInput(from: Place<any>, to: Place<any>): OutForwardInput
 /** Collects all leaf places from this output spec (flattened). */
 declare function allPlaces(out: Out): Set<Place<any>>;
 /**
- * Enumerates all possible output branches for structural analysis.
+ * Enumerates all possible output branches for structural analysis ([IO-016]).
  *
  * - AND = single branch containing all child places (Cartesian product)
  * - XOR = one branch per alternative child
  * - Nested = Cartesian product for AND, union for XOR
+ *
+ * A branch is a **set** of places: it says which places receive a token, not how
+ * many tokens each receives. Analyses built on it (the state-class graph's virtual
+ * transitions, the flattener's post vectors, the ν fragment check) deposit one token
+ * per place of the chosen branch. An action that writes `n > 1` tokens to a place
+ * its branch names once is accepted by [IO-015] but is outside what those analyses
+ * explore — a sound under-approximation for safety only when it never happens, which
+ * is why the executors warn about it ([IO-016] AC4).
  */
 declare function enumerateBranches(out: Out): ReadonlyArray<ReadonlySet<Place<any>>>;
 
@@ -842,11 +860,30 @@ declare function ignore(): EnvironmentAnalysisMode;
  * violates the property, Spacer finds a counterexample. If no violation
  * is reachable, the property is proven.
  */
-type SmtProperty = DeadlockFree | MutualExclusion | PlaceBound | Unreachable | BranchPlaceBound | JoinedOrDeadLettered;
-/** Deadlock-freedom: no reachable marking has all transitions disabled. */
+type SmtProperty = DeadlockFree | TerminatesAtSink | MutualExclusion | PlaceBound | Unreachable | BranchPlaceBound | JoinedOrDeadLettered;
+/**
+ * Deadlock-freedom: no reachable quiescent marking strands a token (VER-002).
+ *
+ * Violated when a reachable marking is quiescent (every transition disabled) and
+ * holds a token in a place that is not a declared sink. The empty marking strands
+ * nothing and never violates. This is workflow-net proper completion; for the
+ * weaker "did the net reach a terminal at all", see {@link TerminatesAtSink},
+ * which inverts on the empty marking.
+ */
 interface DeadlockFree {
     readonly type: 'deadlock-free';
 }
+/**
+ * Termination at a declared sink: every reachable quiescent marking has at least
+ * one declared sink marked (VER-002).
+ *
+ * Violated when a reachable marking is quiescent and no declared sink holds a
+ * token. Says nothing about tokens left elsewhere. Meaningful only with at least
+ * one sink declared; with none, every quiescent marking violates vacuously.
+ */
+interface TerminatesAtSink {
+    readonly type: 'terminates-at-sink';
+}
 /** Mutual exclusion: two places never have tokens simultaneously. */
 interface MutualExclusion {
     readonly type: 'mutual-exclusion';
@@ -890,6 +927,8 @@ interface JoinedOrDeadLettered {
     readonly pending: Place<any>;
 }
 declare function deadlockFree(): DeadlockFree;
+/** Quiescence reaches a declared sink (VER-002). See {@link TerminatesAtSink}. */
+declare function terminatesAtSink(): TerminatesAtSink;
 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;
@@ -981,6 +1020,31 @@ interface Unknown {
     readonly type: 'unknown';
     readonly reason: string;
 }
+/**
+ * Which route decided a verdict ([VER-003]).
+ *
+ * The routes do equivalent work by different means, and a consumer reading the
+ * result's fields rather than its report needs to know which one answered:
+ * `enumeration` and `nu-scg` decide by exploring a finite graph and compute no
+ * P-invariants at all.
+ *
+ * The rule for {@link SmtVerificationResult.invariants} is about the *empty* case
+ * only: an empty list from a route other than `smt` means "not computed", not
+ * "the net has none". A non-empty list is always real — `unavailable` in
+ * particular still carries the invariants the pipeline computed before it found
+ * no usable solver, and `structural` carries whatever the proof rested on.
+ */
+type VerificationRoute = 
+/** The IC3/PDR pipeline: flatten, invariants, encode, solve ([VER-001]). */
+'smt'
+/** Bounded state-space enumeration ([VER-017]). */
+ | 'enumeration'
+/** The ν name-partition state-class graph ([VER-012], Route B). */
+ | 'nu-scg'
+/** A structural proof — Commoner's theorem, or the linear bound of [VER-015]. */
+ | 'structural'
+/** No route could run (no solver, an unresolved property place). */
+ | 'unavailable';
 /**
  * Solver statistics.
  */
@@ -995,6 +1059,13 @@ interface SmtStatistics {
  */
 interface SmtVerificationResult {
     readonly verdict: Verdict;
+    /**
+     * Which route decided this verdict ([VER-003]). Read it before concluding
+     * anything from an **empty** {@link invariants}: off the `'smt'` route that
+     * means "not computed", never "none exist". A non-empty list is real whatever
+     * the route says.
+     */
+    readonly route: VerificationRoute;
     readonly report: string;
     readonly invariants: readonly PInvariant[];
     readonly discoveredInvariants: readonly string[];
@@ -1017,6 +1088,13 @@ interface SmtVerificationResult {
      *   `counterexampleReplay(false)`, the coloured ν-encoding / Route B (whose
      *   state shapes are outside the flat replayer's scope), or a structural
      *   proof.
+     *
+     * A `true` from the enumeration route ([VER-017]) means the same thing it means
+     * everywhere else — the trace is an ordered firing sequence that reaches the
+     * violation — even though it was read off the state-class graph rather than
+     * re-executed: the graph path *is* a firing sequence, so there is nothing to
+     * re-confirm. Consumers keying "are these steps ordered" off this field get the
+     * right answer without special-casing the route.
      */
     readonly counterexampleConfirmed: boolean | null;
     readonly elapsedMs: number;
@@ -1826,4 +1904,4 @@ declare class PetriNetBuilder {
     private buildWithFusion;
 }
 
-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, requiredCount as aA, resetArc as aB, timeout as aC, timeoutPlace as aD, tokenAt as aE, tokenOf as aF, transform as aG, transformAsync as aH, transformFrom as aI, unitToken as aJ, window as aK, withTimeout as aL, xor as aM, xorPlaces as aN, type EnvironmentAnalysisMode as aO, type PInvariant as aP, MarkingState as aQ, type SmtProperty as aR, MarkingStateBuilder 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, immediate as ai, inhibitorArc as aj, inputArc as ak, isPassthrough as al, isUnit as am, keyForPlace as an, latest as ao, matchCorrelates as ap, matchKey as aq, matchSpec as ar, nameId as as, one as at, outPlace as au, outputArc as av, passthrough as aw, place as ax, produce as ay, readArc as az, Transition as b, type Unknown as b0, type Unreachable as b1, type Verdict as b2, type Violated as b3, alwaysAvailable as b4, bounded as b5, ignore as b6, branchPlaceBound as b7, deadlockFree as b8, isProven as b9, isViolated as ba, joinedOrDeadLettered as bb, mutualExclusion as bc, pInvariant as bd, pInvariantToString as be, placeBound as bf, propertyDescription as bg, unreachable as bh, 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 };
+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 SmtStatistics 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, requiredCount as aA, resetArc as aB, timeout as aC, timeoutPlace as aD, tokenAt as aE, tokenOf as aF, transform as aG, transformAsync as aH, transformFrom as aI, unitToken as aJ, window as aK, withTimeout as aL, xor as aM, xorPlaces as aN, type EnvironmentAnalysisMode as aO, type PInvariant as aP, MarkingState as aQ, type SmtProperty as aR, type Verdict as aS, MarkingStateBuilder as aT, type SmtVerificationResult as aU, type BranchPlaceBound as aV, type DeadlockFree as aW, type JoinedOrDeadLettered as aX, type MutualExclusion as aY, type PlaceBound as aZ, type Proven 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, immediate as ai, inhibitorArc as aj, inputArc as ak, isPassthrough as al, isUnit as am, keyForPlace as an, latest as ao, matchCorrelates as ap, matchKey as aq, matchSpec as ar, nameId as as, one as at, outPlace as au, outputArc as av, passthrough as aw, place as ax, produce as ay, readArc as az, Transition as b, type TerminatesAtSink as b0, type TokenSupplier as b1, type Unknown as b2, type Unreachable as b3, type VerificationRoute as b4, type Violated as b5, alwaysAvailable as b6, bounded as b7, ignore as b8, branchPlaceBound as b9, deadlockFree as ba, isProven as bb, isViolated as bc, joinedOrDeadLettered as bd, mutualExclusion as be, pInvariant as bf, pInvariantToString as bg, placeBound as bh, propertyDescription as bi, terminatesAtSink as bj, unreachable as bk, 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/render-dom/index.js

@@ -1,7 +1,7 @@
 import {
   DEFAULT_PANZOOM_OPTS,
   mount
-} from "../chunk-GJAHGHGT.js";
+} from "../chunk-BPGE7GZR.js";
 
 // src/render-dom/index.ts
 async function renderDotToContainer(dotSource, container, opts = {}) {