libpetri 0.5.4 → 1.0.0

package/dist/verification/index.d.ts

@@ -35,6 +35,10 @@ declare class MarkingStateBuilder {
     tokens(place: Place<any>, count: number): this;
     /** Adds tokens to a place. */
     addTokens(place: Place<any>, count: number): this;
+    /** Removes tokens from a place. Throws if insufficient. */
+    removeTokens(place: Place<any>, count: number): this;
+    /** Copies all token counts from another marking state. */
+    copyFrom(other: MarkingState): this;
     build(): MarkingState;
 }
 
@@ -142,14 +146,14 @@ declare class IncidenceMatrix {
 /**
  * How to treat environment places during analysis.
  */
-type EnvironmentAnalysisMode = {
+type EnvironmentAnalysisMode$1 = {
     readonly type: 'unbounded';
 } | {
     readonly type: 'bounded';
     readonly maxTokens: number;
 };
-declare function unbounded(): EnvironmentAnalysisMode;
-declare function bounded(maxTokens: number): EnvironmentAnalysisMode;
+declare function unbounded(): EnvironmentAnalysisMode$1;
+declare function bounded$1(maxTokens: number): EnvironmentAnalysisMode$1;
 /**
  * Flattens a PetriNet into a FlatNet suitable for SMT encoding.
  *
@@ -160,7 +164,7 @@ declare function bounded(maxTokens: number): EnvironmentAnalysisMode;
  * 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;
+declare function flatten(net: PetriNet, environmentPlaces?: Set<EnvironmentPlace<any>>, environmentMode?: EnvironmentAnalysisMode$1): FlatNet;
 
 /**
  * A P-invariant (place invariant) of a Petri net.
@@ -397,7 +401,7 @@ declare class SmtVerifier {
     initialMarking(configurator: (builder: MarkingStateBuilder) => void): this;
     property(property: SmtProperty): this;
     environmentPlaces(...places: EnvironmentPlace<any>[]): this;
-    environmentMode(mode: EnvironmentAnalysisMode): this;
+    environmentMode(mode: EnvironmentAnalysisMode$1): this;
     /**
      * Declares expected sink (terminal) places for deadlock-freedom analysis.
      * Markings where any sink place has a token are not considered deadlocks.
@@ -508,4 +512,194 @@ interface DecodedTrace {
  */
 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 };
+/**
+ * Difference Bound Matrix (DBM) for Time Petri Net state class analysis.
+ *
+ * Implements the Berthomieu-Diaz (1991) algorithm for computing firing domains
+ * and their successors. Matrix bounds[i][j] = upper bound on (xi - xj).
+ * Index 0 is the reference clock; index i+1 is the clock for transition i.
+ */
+declare class DBM {
+    private readonly bounds;
+    private readonly dim;
+    readonly clockNames: readonly string[];
+    private readonly _empty;
+    private constructor();
+    /** Creates an initial firing domain for enabled transitions. */
+    static create(clockNames: readonly string[], lowerBounds: number[], upperBounds: number[]): DBM;
+    /** Creates an empty (unsatisfiable) zone. */
+    static empty(clockNames: readonly string[]): DBM;
+    isEmpty(): boolean;
+    clockCount(): number;
+    private get;
+    /** Gets the lower bound (earliest firing time) for clock i. */
+    getLowerBound(clockIndex: number): number;
+    /** Gets the upper bound (latest firing time / deadline) for clock i. */
+    getUpperBound(clockIndex: number): number;
+    /** Checks if transition can fire (lower bound <= 0 after time passage). */
+    canFire(clockIndex: number): boolean;
+    /**
+     * Computes the successor firing domain after firing transition t_f.
+     * Implements the 5-step Berthomieu-Diaz successor formula.
+     */
+    fireTransition(firedClock: number, newClockNames: readonly string[], newLowerBounds: number[], newUpperBounds: number[], persistentClocks: number[]): DBM;
+    /** Lets time pass: set all lower bounds to 0. */
+    letTimePass(): DBM;
+    private canonicalize;
+    equals(other: DBM): boolean;
+    toString(): string;
+}
+
+/**
+ * A State Class in Time Petri Net analysis.
+ *
+ * A state class is a pair (M, D) where M is a marking and D is a firing domain (DBM).
+ * State classes provide a finite abstraction of the infinite state space of Time Petri Nets.
+ */
+declare class StateClass {
+    readonly marking: MarkingState;
+    readonly firingDomain: DBM;
+    readonly enabledTransitions: readonly Transition[];
+    constructor(marking: MarkingState, firingDomain: DBM, enabledTransitions: readonly Transition[]);
+    isEmpty(): boolean;
+    canFire(transition: Transition): boolean;
+    transitionIndex(transition: Transition): number;
+    equals(other: StateClass): boolean;
+    toString(): string;
+}
+
+/**
+ * Strongly Connected Component analysis using Tarjan's algorithm.
+ * Generic over node type T. Uses a key function for Map-based lookups.
+ */
+/** Computes all SCCs in a graph. O(V + E) via Tarjan's algorithm. */
+declare function computeSCCs<T>(nodes: Iterable<T>, successors: (node: T) => Iterable<T>): Set<T>[];
+/** Finds terminal (bottom) SCCs — SCCs with no outgoing edges to other SCCs. */
+declare function findTerminalSCCs<T>(nodes: Iterable<T>, successors: (node: T) => Iterable<T>): Set<T>[];
+
+/**
+ * Analysis mode for environment places in state class graph construction.
+ */
+type EnvironmentAnalysisMode = {
+    readonly type: 'always-available';
+} | {
+    readonly type: 'bounded';
+    readonly maxTokens: number;
+} | {
+    readonly type: 'ignore';
+};
+/** Assumes environment places always have sufficient tokens. */
+declare function alwaysAvailable(): EnvironmentAnalysisMode;
+/** Analyzes with a bounded number of tokens in environment places. */
+declare function bounded(maxTokens: number): EnvironmentAnalysisMode;
+/** Treats environment places as regular places (default). */
+declare function ignore(): EnvironmentAnalysisMode;
+
+/** Edge that tracks which XOR branch was taken. */
+interface BranchEdge {
+    readonly branchIndex: number;
+    readonly target: StateClass;
+}
+/**
+ * State Class Graph for Time Petri Net analysis.
+ *
+ * Implements the Berthomieu-Diaz (1991) algorithm for computing the state class
+ * graph of a bounded Time Petri Net.
+ */
+declare class StateClassGraph {
+    readonly net: PetriNet;
+    readonly initialClass: StateClass;
+    private readonly _stateClasses;
+    private readonly _transitions;
+    private readonly _successors;
+    private readonly _predecessors;
+    private readonly _complete;
+    private constructor();
+    /** Builds the state class graph for a Time Petri Net. */
+    static build(net: PetriNet, initialMarking: MarkingState, maxClasses: number, environmentPlaces?: Set<EnvironmentPlace<any>>, environmentMode?: EnvironmentAnalysisMode): StateClassGraph;
+    stateClasses(): readonly StateClass[];
+    size(): number;
+    isComplete(): boolean;
+    successors(sc: StateClass): Set<StateClass>;
+    predecessors(sc: StateClass): Set<StateClass>;
+    /** Returns all outgoing transitions with their branch edges. */
+    outgoingBranchEdges(sc: StateClass): Map<Transition, BranchEdge[]>;
+    /** Returns the branch edges for a specific transition from a state class. */
+    branchEdges(sc: StateClass, transition: Transition): BranchEdge[];
+    /** Returns all transitions that are enabled from a state class. */
+    enabledTransitions(sc: StateClass): Set<Transition>;
+    /** Finds all state classes with a given marking. */
+    classesWithMarking(marking: MarkingState): StateClass[];
+    /** Checks if a marking is reachable. */
+    isReachable(marking: MarkingState): boolean;
+    /** Gets all reachable markings. */
+    reachableMarkings(): Set<string>;
+    /** Counts edges in the graph (each branch edge counts separately). */
+    edgeCount(): number;
+    toString(): string;
+}
+
+/** Result of liveness analysis. */
+interface LivenessResult {
+    readonly stateClassGraph: StateClassGraph;
+    readonly allSCCs: Set<StateClass>[];
+    readonly terminalSCCs: Set<StateClass>[];
+    readonly goalClasses: Set<StateClass>;
+    readonly canReachGoal: Set<StateClass>;
+    readonly isGoalLive: boolean;
+    readonly isL4Live: boolean;
+    readonly isComplete: boolean;
+    readonly report: string;
+}
+/** Information about XOR branch coverage for a single transition. */
+interface XorBranchInfo {
+    readonly totalBranches: number;
+    readonly takenBranches: Set<number>;
+    readonly untakenBranches: Set<number>;
+    readonly branchOutputs: ReadonlyArray<ReadonlySet<Place<any>>>;
+}
+/** Result of XOR branch analysis. */
+interface XorBranchAnalysis {
+    readonly transitionBranches: Map<Transition, XorBranchInfo>;
+    unreachableBranches(): Map<Transition, Set<number>>;
+    isXorComplete(): boolean;
+    report(): string;
+}
+/**
+ * Formal analyzer for Time Petri Nets using the State Class Graph method.
+ * Implements Berthomieu-Diaz (1991) analysis.
+ */
+declare class TimePetriNetAnalyzer {
+    private readonly net;
+    private readonly initialMarking;
+    private readonly goalPlaces;
+    private readonly maxClasses;
+    private readonly environmentPlaces;
+    private readonly environmentMode;
+    /** @internal Called by builder — use `TimePetriNetAnalyzer.forNet()` instead. */
+    static create(net: PetriNet, initialMarking: MarkingState, goalPlaces: Set<Place<any>>, maxClasses: number, environmentPlaces: Set<EnvironmentPlace<any>>, environmentMode: EnvironmentAnalysisMode): TimePetriNetAnalyzer;
+    private constructor();
+    static forNet(net: PetriNet): TimePetriNetAnalyzerBuilder;
+    /** Performs formal liveness analysis. */
+    analyze(): LivenessResult;
+    /** Analyzes XOR branch coverage for a built state class graph. */
+    static analyzeXorBranches(scg: StateClassGraph): XorBranchAnalysis;
+}
+/** Builder for TimePetriNetAnalyzer. */
+declare class TimePetriNetAnalyzerBuilder {
+    private readonly net;
+    private _initialMarking;
+    private readonly _goalPlaces;
+    private _maxClasses;
+    private readonly _environmentPlaces;
+    private _environmentMode;
+    constructor(net: PetriNet);
+    initialMarking(marking: MarkingState): this;
+    goalPlaces(...places: Place<any>[]): this;
+    maxClasses(max: number): this;
+    environmentPlaces(...places: EnvironmentPlace<any>[]): this;
+    environmentMode(mode: EnvironmentAnalysisMode): this;
+    build(): TimePetriNetAnalyzer;
+}
+
+export { type EnvironmentAnalysisMode as AnalysisEnvironmentMode, type BranchEdge, DBM, type DeadlockFree, type DecodedTrace, type EncodingResult, type EnvironmentAnalysisMode$1 as EnvironmentAnalysisMode, type FlatNet, type FlatTransition, IncidenceMatrix, type LivenessResult, 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, StateClass, StateClassGraph, type StructuralCheckResult, TimePetriNetAnalyzer, TimePetriNetAnalyzerBuilder, type Unknown, type Unreachable, type Verdict, type Violated, type XorBranchAnalysis, type XorBranchInfo, alwaysAvailable as analysisAlwaysAvailable, bounded as analysisBounded, ignore as analysisIgnore, bounded$1 as bounded, computePInvariants, computeSCCs, createSpacerRunner, deadlockFree, decode, encode, findMaximalTrapIn, findMinimalSiphons, findTerminalSCCs, flatNetIndexOf, flatNetPlaceCount, flatNetTransitionCount, flatTransition, flatten, isCoveredByInvariants, isProven, isViolated, mutualExclusion, pInvariant, pInvariantToString, placeBound, propertyDescription, structuralCheck, unbounded, unreachable };