libpetri 0.3.2

package/dist/verification/index.d.ts

@@ -0,0 +1,505 @@
+import { P as Place, b as Transition, a as PetriNet, E as EnvironmentPlace } from '../petri-net-C3Jy5HCt.js';
+import { Expr, init, Bool, FuncDecl } from 'z3-solver';
+
+/**
+ * Immutable snapshot of a Petri net marking for state space analysis.
+ *
+ * Maps places (by name) to integer token counts. Only stores places with count > 0.
+ * Used for invariant computation and structural verification, not runtime execution.
+ */
+declare class MarkingState {
+    private readonly tokenCounts;
+    private readonly placesByName;
+    /** @internal Use {@link MarkingState.builder} or {@link MarkingState.empty} to create instances. */
+    constructor(key: symbol, tokenCounts: Map<string, number>, placesByName: Map<string, Place<any>>);
+    /** Returns the token count for a place (0 if absent). */
+    tokens(place: Place<any>): number;
+    /** Checks if a place has at least one token. */
+    hasTokens(place: Place<any>): boolean;
+    /** Checks if any of the given places has tokens. */
+    hasTokensInAny(places: Iterable<Place<any>>): boolean;
+    /** Returns all places with tokens > 0. */
+    placesWithTokens(): Place<any>[];
+    /** Returns the total number of tokens. */
+    totalTokens(): number;
+    /** Checks if no tokens exist anywhere. */
+    isEmpty(): boolean;
+    toString(): string;
+    static empty(): MarkingState;
+    static builder(): MarkingStateBuilder;
+}
+declare class MarkingStateBuilder {
+    private readonly tokenCounts;
+    private readonly placesByName;
+    /** Sets the token count for a place. */
+    tokens(place: Place<any>, count: number): this;
+    /** Adds tokens to a place. */
+    addTokens(place: Place<any>, count: number): this;
+    build(): MarkingState;
+}
+
+/**
+ * A flattened transition with pre/post vectors for SMT encoding.
+ *
+ * Each Transition with XOR outputs is expanded into multiple FlatTransitions
+ * (one per branch). Non-XOR transitions map 1:1.
+ */
+interface FlatTransition {
+    /** Display name (e.g. "Search_b0", "Search_b1"). */
+    readonly name: string;
+    /** The original transition. */
+    readonly source: Transition;
+    /** Which XOR branch (-1 if no XOR). */
+    readonly branchIndex: number;
+    /** Tokens consumed per place (indexed by place index). */
+    readonly preVector: readonly number[];
+    /** Tokens produced per place (indexed by place index). */
+    readonly postVector: readonly number[];
+    /** Place indices where inhibitor arcs block firing. */
+    readonly inhibitorPlaces: readonly number[];
+    /** Place indices requiring a token without consuming. */
+    readonly readPlaces: readonly number[];
+    /** Place indices set to 0 on firing. */
+    readonly resetPlaces: readonly number[];
+    /** True at index i means place i uses All/AtLeast semantics. */
+    readonly consumeAll: readonly boolean[];
+}
+declare function flatTransition(name: string, source: Transition, branchIndex: number, preVector: number[], postVector: number[], inhibitorPlaces: number[], readPlaces: number[], resetPlaces: number[], consumeAll: boolean[]): FlatTransition;
+
+/**
+ * A flattened Petri net with indexed places and XOR-expanded transitions.
+ *
+ * Intermediate representation between the high-level PetriNet and Z3 CHC encoding.
+ */
+interface FlatNet {
+    /** Ordered list of places (index = position). */
+    readonly places: readonly Place<any>[];
+    /** Reverse lookup: place name -> index. */
+    readonly placeIndex: ReadonlyMap<string, number>;
+    /** XOR-expanded flat transitions. */
+    readonly transitions: readonly FlatTransition[];
+    /** For bounded environment places: place name -> max tokens. */
+    readonly environmentBounds: ReadonlyMap<string, number>;
+}
+declare function flatNetPlaceCount(net: FlatNet): number;
+declare function flatNetTransitionCount(net: FlatNet): number;
+declare function flatNetIndexOf(net: FlatNet, place: Place<any>): number;
+
+/**
+ * Incidence matrix for a flattened Petri net.
+ *
+ * The incidence matrix C is defined as C[t][p] = post[t][p] - pre[t][p].
+ * It captures the net effect of each transition on each place.
+ *
+ * P-invariants are solutions to y^T * C = 0, found via null space
+ * computation on C^T.
+ */
+declare class IncidenceMatrix {
+    private readonly _pre;
+    private readonly _post;
+    private readonly _incidence;
+    private readonly _numTransitions;
+    private readonly _numPlaces;
+    private constructor();
+    /**
+     * Computes the incidence matrix from a FlatNet.
+     */
+    static from(flatNet: FlatNet): IncidenceMatrix;
+    /**
+     * Returns C^T (transpose of incidence matrix), dimensions [P][T].
+     * Used for P-invariant computation: null space of C^T gives P-invariants.
+     */
+    transposedIncidence(): number[][];
+    /** Returns the pre-matrix (tokens consumed). T×P. */
+    pre(): readonly (readonly number[])[];
+    /** Returns the post-matrix (tokens produced). T×P. */
+    post(): readonly (readonly number[])[];
+    /** Returns the incidence matrix C[t][p] = post - pre. T×P. */
+    incidence(): readonly (readonly number[])[];
+    numTransitions(): number;
+    numPlaces(): number;
+}
+
+/**
+ * @module net-flattener
+ *
+ * Flattens a PetriNet into integer-indexed pre/post vectors for SMT encoding.
+ *
+ * **XOR expansion**: Transitions with XOR output specs are expanded into multiple
+ * flat transitions — one per deterministic branch. Each branch produces tokens to
+ * exactly one XOR child's places. This converts non-deterministic output routing
+ * into separate transitions that the SMT solver can reason about independently.
+ *
+ * **Vector construction**: For each flat transition, builds:
+ * - `preVector[p]`: tokens consumed from place p (input cardinality)
+ * - `postVector[p]`: tokens produced to place p (from the selected branch)
+ * - `consumeAll[p]`: true for `all`/`at-least` inputs (consume everything)
+ * - Index arrays for inhibitor, read, and reset arcs
+ *
+ * Places are sorted by name for stable, deterministic indexing across runs.
+ */
+
+/**
+ * How to treat environment places during analysis.
+ */
+type EnvironmentAnalysisMode = {
+    readonly type: 'unbounded';
+} | {
+    readonly type: 'bounded';
+    readonly maxTokens: number;
+};
+declare function unbounded(): EnvironmentAnalysisMode;
+declare function bounded(maxTokens: number): EnvironmentAnalysisMode;
+/**
+ * Flattens a PetriNet into a FlatNet suitable for SMT encoding.
+ *
+ * Flattening involves:
+ * 1. Assigning each place a stable integer index (sorted by name)
+ * 2. Expanding XOR outputs into separate flat transitions (one per branch)
+ * 3. Building pre/post vectors from input/output specs
+ * 4. Recording inhibitor, read, and reset arcs
+ * 5. Setting environment bounds for bounded analysis mode
+ */
+declare function flatten(net: PetriNet, environmentPlaces?: Set<EnvironmentPlace<any>>, environmentMode?: EnvironmentAnalysisMode): FlatNet;
+
+/**
+ * A P-invariant (place invariant) of a Petri net.
+ *
+ * A P-invariant is a vector y such that y^T * C = 0, where C is the
+ * incidence matrix. This means that for any reachable marking M:
+ * sum(y_i * M_i) = constant, where constant = sum(y_i * M0_i).
+ *
+ * P-invariants provide structural bounds on places and are used as
+ * strengthening lemmas for the IC3/PDR engine.
+ */
+interface PInvariant {
+    /** Weight vector (one entry per place index). */
+    readonly weights: readonly number[];
+    /** The invariant value sum(y_i * M0_i). */
+    readonly constant: number;
+    /** Set of place indices where weight != 0. */
+    readonly support: ReadonlySet<number>;
+}
+declare function pInvariant(weights: number[], constant: number, support: Set<number>): PInvariant;
+declare function pInvariantToString(inv: PInvariant): string;
+
+/**
+ * @module p-invariant-computer
+ *
+ * Computes P-invariants of a Petri net via integer Gaussian elimination (Farkas' algorithm).
+ *
+ * **Algorithm**: A P-invariant is a non-negative integer vector y such that y^T · C = 0
+ * (where C is the incidence matrix). This expresses a conservation law: the weighted
+ * token sum Σ(y_i · M[i]) is constant across all reachable markings.
+ *
+ * **Farkas variant**: Constructs the augmented matrix [C^T | I_P] and row-reduces
+ * the C^T portion to zero using integer elimination (no floating point). Rows where
+ * the C^T part becomes all-zero yield invariant vectors from the identity part.
+ * Row normalization by GCD keeps values small during elimination.
+ *
+ * **Integer Gaussian elimination**: Each elimination step multiplies rows by pivot
+ * coefficients (a·row - b·pivotRow) to avoid fractions. This preserves integer
+ * arithmetic throughout, critical for exact invariant computation.
+ *
+ * Invariants are used to strengthen SMT queries (added as constraints on M').
+ */
+
+/**
+ * Computes P-invariants of a Petri net via integer Gaussian elimination.
+ *
+ * P-invariants are non-negative integer vectors y where y^T * C = 0.
+ * They express conservation laws: the weighted token sum is constant
+ * across all reachable markings.
+ *
+ * Algorithm: compute the null space of C^T using integer row reduction
+ * with an augmented identity matrix (Farkas' algorithm variant).
+ */
+declare function computePInvariants(matrix: IncidenceMatrix, flatNet: FlatNet, initialMarking: MarkingState): PInvariant[];
+/**
+ * Checks if every place is covered by at least one P-invariant.
+ * If true, the net is structurally bounded.
+ */
+declare function isCoveredByInvariants(invariants: readonly PInvariant[], numPlaces: number): boolean;
+
+/**
+ * @module structural-check
+ *
+ * Structural deadlock pre-check using siphon/trap analysis (Commoner's theorem).
+ *
+ * **Commoner's theorem**: A Petri net is deadlock-free if every siphon contains
+ * an initially marked trap.
+ *
+ * **Siphon**: A set of places S where every transition that outputs to S also
+ * inputs from S. Key property: once all places in a siphon become empty,
+ * they can never be re-marked. An empty siphon can cause deadlock.
+ *
+ * **Trap**: A set of places S where every transition that inputs from S also
+ * outputs to S. Key property: once any place in a trap is marked,
+ * the trap remains marked forever.
+ *
+ * **Algorithm**: For each place, compute the minimal siphon containing it via
+ * fixed-point expansion. For each siphon, find the maximal trap within it
+ * (fixed-point contraction). If every siphon contains an initially-marked
+ * trap, deadlock-freedom is proven structurally — no SMT query needed.
+ *
+ * Limited to nets with ≤50 places to bound enumeration cost.
+ */
+
+/**
+ * Result of structural deadlock check using siphon/trap analysis.
+ */
+type StructuralCheckResult = {
+    readonly type: 'no-potential-deadlock';
+} | {
+    readonly type: 'potential-deadlock';
+    readonly siphon: ReadonlySet<number>;
+} | {
+    readonly type: 'inconclusive';
+    readonly reason: string;
+};
+/**
+ * Structural deadlock pre-check using siphon/trap analysis.
+ *
+ * Commoner's theorem: a Petri net is deadlock-free if every siphon
+ * contains a marked trap.
+ *
+ * A siphon is a set of places S such that every transition with
+ * an output in S also has an input in S. Once empty, a siphon stays empty.
+ *
+ * A trap is a set of places S such that every transition with
+ * an input in S also has an output in S. Once marked, a trap stays marked.
+ */
+declare function structuralCheck(flatNet: FlatNet, initialMarking: MarkingState): StructuralCheckResult;
+/**
+ * Finds minimal siphons by checking all non-empty subsets of deadlock-enabling places.
+ * Uses a fixed-point approach: start from each place and grow the siphon.
+ */
+declare function findMinimalSiphons(flatNet: FlatNet): ReadonlySet<number>[];
+/**
+ * Finds the maximal trap within a given set of places.
+ * Uses fixed-point: start with the full set and remove places that violate the trap condition.
+ */
+declare function findMaximalTrapIn(flatNet: FlatNet, places: ReadonlySet<number>): ReadonlySet<number>;
+
+/**
+ * Safety properties that can be verified via IC3/PDR.
+ *
+ * Each property is encoded as an error condition: if a reachable state
+ * violates the property, Spacer finds a counterexample. If no violation
+ * is reachable, the property is proven.
+ */
+type SmtProperty = DeadlockFree | MutualExclusion | PlaceBound | Unreachable;
+/** Deadlock-freedom: no reachable marking has all transitions disabled. */
+interface DeadlockFree {
+    readonly type: 'deadlock-free';
+}
+/** Mutual exclusion: two places never have tokens simultaneously. */
+interface MutualExclusion {
+    readonly type: 'mutual-exclusion';
+    readonly p1: Place<any>;
+    readonly p2: Place<any>;
+}
+/** Place bound: a place never exceeds a given token count. */
+interface PlaceBound {
+    readonly type: 'place-bound';
+    readonly place: Place<any>;
+    readonly bound: number;
+}
+/** Unreachability: the given places never all have tokens simultaneously. */
+interface Unreachable {
+    readonly type: 'unreachable';
+    readonly places: ReadonlySet<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;
+/** Human-readable description of a property. */
+declare function propertyDescription(prop: SmtProperty): string;
+
+/**
+ * Verification verdict.
+ */
+type Verdict = Proven | Violated | Unknown;
+/** Property proven safe. No reachable state violates it. */
+interface Proven {
+    readonly type: 'proven';
+    readonly method: string;
+    readonly inductiveInvariant: string | null;
+}
+/** Property violated. A counterexample trace is available. */
+interface Violated {
+    readonly type: 'violated';
+}
+/** Could not determine. */
+interface Unknown {
+    readonly type: 'unknown';
+    readonly reason: string;
+}
+/**
+ * Solver statistics.
+ */
+interface SmtStatistics {
+    readonly places: number;
+    readonly transitions: number;
+    readonly invariantsFound: number;
+    readonly structuralResult: string;
+}
+/**
+ * Result of SMT-based verification.
+ */
+interface SmtVerificationResult {
+    readonly verdict: Verdict;
+    readonly report: string;
+    readonly invariants: readonly PInvariant[];
+    readonly discoveredInvariants: readonly string[];
+    readonly counterexampleTrace: readonly MarkingState[];
+    readonly counterexampleTransitions: readonly string[];
+    readonly elapsedMs: number;
+    readonly statistics: SmtStatistics;
+}
+declare function isProven(result: SmtVerificationResult): boolean;
+declare function isViolated(result: SmtVerificationResult): boolean;
+
+/**
+ * IC3/PDR-based safety verifier for Petri nets using Z3's Spacer engine.
+ *
+ * Proves safety properties (especially deadlock-freedom) without
+ * enumerating all reachable states. IC3 constructs inductive invariants
+ * incrementally, which works well for bounded nets.
+ *
+ * Key design decisions:
+ * - Operates on the marking projection (integer vectors) — no timing
+ * - An untimed deadlock-freedom proof is stronger than needed
+ *   (timing can only restrict behavior)
+ * - Guards are ignored — over-approximation is sound for safety properties
+ * - If a counterexample is found, it may be spurious in timed/guarded
+ *   semantics — the report notes this
+ *
+ * Verification Pipeline:
+ * 1. Flatten — expand XOR, index places, build pre/post vectors
+ * 2. Structural pre-check — siphon/trap analysis (may prove early)
+ * 3. P-invariants — compute conservation laws for strengthening
+ * 4. SMT encode + query — IC3/PDR via Z3 Spacer
+ * 5. Decode result — proof or counterexample trace
+ */
+declare class SmtVerifier {
+    private readonly net;
+    private _initialMarking;
+    private _property;
+    private readonly _environmentPlaces;
+    private _environmentMode;
+    private _timeoutMs;
+    private constructor();
+    static forNet(net: PetriNet): SmtVerifier;
+    initialMarking(marking: MarkingState): this;
+    initialMarking(configurator: (builder: MarkingStateBuilder) => void): this;
+    property(property: SmtProperty): this;
+    environmentPlaces(...places: EnvironmentPlace<any>[]): this;
+    environmentMode(mode: EnvironmentAnalysisMode): this;
+    timeout(ms: number): this;
+    /**
+     * Runs the verification pipeline.
+     */
+    verify(): Promise<SmtVerificationResult>;
+}
+
+/**
+ * Result of a Spacer query.
+ */
+type QueryResult = QueryProven | QueryViolated | QueryUnknown;
+/** Property proven: no reachable error state (UNSAT). */
+interface QueryProven {
+    readonly type: 'proven';
+    readonly invariantFormula: string | null;
+    readonly levelInvariants: readonly string[];
+}
+/** Counterexample found (SAT). The answer is the derivation tree. */
+interface QueryViolated {
+    readonly type: 'violated';
+    readonly answer: Expr | null;
+}
+/** Solver could not determine (timeout, resource limit). */
+interface QueryUnknown {
+    readonly type: 'unknown';
+    readonly reason: string;
+}
+/**
+ * The Z3 context and helpers returned by SpacerRunner.create().
+ * Exposes the context object for building expressions.
+ */
+interface SpacerContext {
+    /** The Z3 high-level context for building expressions. */
+    readonly ctx: ReturnType<Awaited<ReturnType<typeof init>>['Context']>;
+    /** The Z3 Fixedpoint solver instance (Spacer engine). Z3 types are complex; using any. */
+    readonly fp: any;
+    /** Queries whether the error state is reachable. */
+    query(errorExpr: Bool, reachableDecl?: FuncDecl): Promise<QueryResult>;
+    /** Releases Z3 resources. */
+    dispose(): void;
+}
+/**
+ * Creates a Spacer runner with the given timeout.
+ *
+ * Uses Z3's Spacer engine (CHC solver based on IC3/PDR) to prove or
+ * disprove safety properties.
+ */
+declare function createSpacerRunner(timeoutMs: number): Promise<SpacerContext>;
+
+/**
+ * @module smt-encoder
+ *
+ * Encodes a flattened Petri net as Constrained Horn Clauses (CHC) for Z3's Spacer engine.
+ *
+ * **CHC encoding strategy**: The net's state space is modeled as integer vectors
+ * (one variable per place = token count). Three rule types:
+ *
+ * 1. **Init**: `Reachable(M0)` — the initial marking is reachable
+ * 2. **Transition**: `Reachable(M') :- Reachable(M) ∧ enabled(M,t) ∧ fire(M,M',t)` —
+ *    one rule per flat transition (XOR branches are separate transitions)
+ * 3. **Error**: `Error() :- Reachable(M) ∧ violation(M)` — safety property violation
+ *
+ * Transition rules include: non-negativity constraints on M', P-invariant strengthening
+ * clauses, and environment bounds for bounded analysis.
+ *
+ * Z3 types are complex and partially untyped; the ctx/fp parameters use `any`.
+ */
+
+/** Z3 high-level context. Typed as `any` because z3-solver's TS types are incomplete. */
+type Z3Context = any;
+/** Z3 Fixedpoint solver instance. Typed as `any` because z3-solver's TS types are incomplete. */
+type Z3Fixedpoint = any;
+/**
+ * Result of CHC encoding.
+ */
+interface EncodingResult {
+    readonly errorExpr: Bool;
+    readonly reachableDecl: FuncDecl;
+}
+/**
+ * Encodes a flattened Petri net as Constrained Horn Clauses (CHC) for Z3's Spacer engine.
+ *
+ * CHC rules:
+ * - Reachable(M0) — initial state is reachable
+ * - Reachable(M') :- Reachable(M) AND enabled(M,t) AND fire(M,M',t) — transition rules
+ * - Error() :- Reachable(M) AND property_violation(M) — safety property
+ */
+declare function encode(ctx: Z3Context, fp: Z3Fixedpoint, flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[]): EncodingResult;
+
+/**
+ * Result of counterexample decoding.
+ */
+interface DecodedTrace {
+    readonly trace: readonly MarkingState[];
+    readonly transitions: readonly string[];
+}
+/**
+ * Decodes Z3 Spacer counterexample answers into Petri net marking traces.
+ *
+ * When Spacer finds a counterexample (property violation), it produces
+ * a derivation tree showing how the error state is reachable. This function
+ * extracts the marking at each step to produce a human-readable trace.
+ */
+declare function decode(ctx: any, answer: Expr | null, flatNet: FlatNet): DecodedTrace;
+
+export { type DeadlockFree, type DecodedTrace, type EncodingResult, type EnvironmentAnalysisMode, type FlatNet, type FlatTransition, IncidenceMatrix, MarkingState, MarkingStateBuilder, type MutualExclusion, type PInvariant, type PlaceBound, type Proven, type QueryProven, type QueryResult, type QueryUnknown, type QueryViolated, type SmtProperty, type SmtStatistics, type SmtVerificationResult, SmtVerifier, type SpacerContext, type StructuralCheckResult, type Unknown, type Unreachable, type Verdict, type Violated, bounded, computePInvariants, createSpacerRunner, deadlockFree, decode, encode, findMaximalTrapIn, findMinimalSiphons, flatNetIndexOf, flatNetPlaceCount, flatNetTransitionCount, flatTransition, flatten, isCoveredByInvariants, isProven, isViolated, mutualExclusion, pInvariant, pInvariantToString, placeBound, propertyDescription, structuralCheck, unbounded, unreachable };