libpetri 5.0.0 → 6.0.0

package/dist/{petri-net-CH7UvjOW.d.ts → petri-net-34SkD5RT.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,7 +860,7 @@ declare function ignore(): EnvironmentAnalysisMode;
  * violates the property, Spacer finds a counterexample. If no violation
  * is reachable, the property is proven.
  */
-type SmtProperty = DeadlockFree | TerminatesAtSink | MutualExclusion | PlaceBound | Unreachable | BranchPlaceBound | JoinedOrDeadLettered;
+type SmtProperty = DeadlockFree | TerminatesAtSink | MutualExclusion | PlaceBound | Unreachable | BranchPlaceBound | JoinedOrDeadLettered | QuiescentCount;
 /**
  * Deadlock-freedom: no reachable quiescent marking strands a token (VER-002).
  *
@@ -908,6 +926,19 @@ interface JoinedOrDeadLettered {
     readonly type: 'joined-or-dead-lettered';
     readonly pending: Place<any>;
 }
+/**
+ * A token count at quiescence (VER-002): every reachable quiescent marking holds between
+ * `min` and `max` tokens across `places` (`max` may be `Infinity`). The lower bound is
+ * waived while any `waivedBy` place is marked, the upper never: a halted run ([VER-014])
+ * need not refund its budget, but never holds more than there is.
+ */
+interface QuiescentCount {
+    readonly type: 'quiescent-count';
+    readonly places: readonly Place<any>[];
+    readonly min: number;
+    readonly max: number;
+    readonly waivedBy: readonly Place<any>[];
+}
 declare function deadlockFree(): DeadlockFree;
 /** Quiescence reaches a declared sink (VER-002). See {@link TerminatesAtSink}. */
 declare function terminatesAtSink(): TerminatesAtSink;
@@ -918,6 +949,14 @@ declare function unreachable(places: ReadonlySet<Place<any>>): Unreachable;
 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;
+/**
+ * A token count at quiescence (VER-002). See {@link QuiescentCount}.
+ *
+ * ```ts
+ * quiescentCount([budget], k, k, [halt])   // the budget is back at k whenever the net comes to rest, unless it halted
+ * ```
+ */
+declare function quiescentCount(places: Iterable<Place<any>>, min: number, max: number, waivedBy?: Iterable<Place<any>>): QuiescentCount;
 /** Human-readable description of a property. */
 declare function propertyDescription(prop: SmtProperty): string;
 
@@ -944,6 +983,10 @@ declare class MarkingState {
     totalTokens(): number;
     /** Checks if no tokens exist anywhere. */
     isEmpty(): boolean;
+    /**
+     * The marking as `{name:count, ...}`, places in code-point order of their names, so reports
+     * and witness traces print the same on every host ([VER-013], [VER-022]).
+     */
     toString(): string;
     static empty(): MarkingState;
     static builder(): MarkingStateBuilder;
@@ -1002,6 +1045,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.
  */
@@ -1016,6 +1084,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[];
@@ -1038,6 +1113,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;
@@ -1847,4 +1929,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 TerminatesAtSink 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 TokenSupplier as b0, type Unknown as b1, type Unreachable as b2, type Verdict as b3, type Violated as b4, alwaysAvailable as b5, bounded as b6, ignore as b7, branchPlaceBound as b8, deadlockFree as b9, isProven as ba, isViolated as bb, joinedOrDeadLettered as bc, mutualExclusion as bd, pInvariant as be, pInvariantToString as bf, placeBound as bg, propertyDescription as bh, terminatesAtSink as bi, unreachable as bj, 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 QuiescentCount 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 SmtStatistics as b0, type TerminatesAtSink as b1, type TokenSupplier as b2, type Unknown as b3, type Unreachable as b4, type VerificationRoute as b5, type Violated as b6, alwaysAvailable as b7, bounded as b8, ignore as b9, branchPlaceBound as ba, deadlockFree as bb, isProven as bc, isViolated as bd, joinedOrDeadLettered as be, mutualExclusion as bf, pInvariant as bg, pInvariantToString as bh, placeBound as bi, propertyDescription as bj, quiescentCount as bk, terminatesAtSink as bl, unreachable as bm, 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-4HMFNYTH.js";
+} from "../chunk-5LE2M5PW.js";
 
 // src/render-dom/index.ts
 async function renderDotToContainer(dotSource, container, opts = {}) {