libpetri 4.1.0 → 5.1.0

package/dist/verification/index.d.ts

@@ -1,5 +1,5 @@
-import { b as Transition, a as Place, P as PetriNet, E as EnvironmentPlace, aO as EnvironmentAnalysisMode, aP as PInvariant, aQ as MarkingState, aR as SmtProperty, aS as MarkingStateBuilder, aT as SmtVerificationResult } from '../petri-net-p0ONpSAO.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 alwaysAvailable, b4 as analysisAlwaysAvailable, b5 as analysisBounded, b6 as analysisIgnore, b5 as bounded, b7 as branchPlaceBound, b8 as deadlockFree, b6 as ignore, b9 as isProven, ba as isViolated, bb as joinedOrDeadLettered, bc as mutualExclusion, bd as pInvariant, be as pInvariantToString, bf as placeBound, bg as propertyDescription, bh as unreachable } from '../petri-net-p0ONpSAO.js';
+import { b as Transition, a as Place, P as PetriNet, E as EnvironmentPlace, aO as EnvironmentAnalysisMode, aP as PInvariant, aQ as MarkingState, aR as SmtProperty, aS as Verdict, aT as MarkingStateBuilder, aU as SmtVerificationResult } from '../petri-net-6G5r1Wwb.js';
+export { aV as BranchPlaceBound, aW as DeadlockFree, aX as JoinedOrDeadLettered, aY as MutualExclusion, aZ as PlaceBound, a_ as Proven, a$ as SmtStatistics, b0 as TerminatesAtSink, b1 as TokenSupplier, b2 as Unknown, b3 as Unreachable, $ as VerificationHarness, a0 as VerificationResult, b4 as VerificationRoute, b5 as Violated, b6 as alwaysAvailable, b6 as analysisAlwaysAvailable, b7 as analysisBounded, b8 as analysisIgnore, b7 as bounded, b9 as branchPlaceBound, ba as deadlockFree, b8 as ignore, bb as isProven, bc as isViolated, bd as joinedOrDeadLettered, be as mutualExclusion, bf as pInvariant, bg as pInvariantToString, bh as placeBound, bi as propertyDescription, bj as terminatesAtSink, bk as unreachable } from '../petri-net-6G5r1Wwb.js';
 
 /**
  * A flattened transition with pre/post vectors for SMT encoding.
@@ -253,6 +253,182 @@ declare function findMinimalSiphons(flatNet: FlatNet): ReadonlySet<number>[];
  */
 declare function findMaximalTrapIn(flatNet: FlatNet, places: ReadonlySet<number>): ReadonlySet<number>;
 
+/**
+ * @module rest-set
+ *
+ * Where a token may come to rest without being stranded (VER-002, VER-014).
+ *
+ * `DeadlockFree` is violated by a quiescent marking that holds a token outside the
+ * places where resting is permitted. The permitted set has two layers:
+ *
+ * - the **declared sinks** (`SmtVerifier.sinkPlaces`), where a token may always rest;
+ * - the **conditional sinks** (`SmtVerifier.sinkPlacesWhen(marker, …)`), where a
+ *   token may rest only while `marker` holds a token. A marked marker is a
+ *   *designed terminal* — a halted or paused run — and the marker itself is at rest
+ *   whenever it is marked.
+ *
+ * Declarations union: a token in `p` is excused when `p` is a declared sink, when
+ * `p` is a marker, or when some conditional set naming `p` has its marker marked.
+ * Every route that decides `DeadlockFree` — the flat and name-coloured CHC encoders,
+ * the abstract counterexample replay and the Route B name-partition graph — reads
+ * this one module, so the predicate cannot drift between them (VER-002 AC7).
+ *
+ * `TerminatesAtSink` is untouched by conditional declarations: it asks whether a
+ * declared sink was reached and reads only the unconditional set.
+ */
+
+/** Places where a token may rest while `marker` holds a token. */
+interface ConditionalSinks {
+    readonly marker: Place<any>;
+    readonly places: ReadonlySet<Place<any>>;
+}
+/**
+ * Per flat place, how a token resting there is excused: `null` when it never counts
+ * as stranded (a declared sink, or a marker), otherwise the ascending flat indices of
+ * the markers whose presence excuses it — empty when nothing does, so a token there
+ * is stranded whenever the marking is quiescent.
+ *
+ * Places and markers that do not resolve in the flat net contribute nothing, as an
+ * unresolved sink does: a mistyped marker makes the property stricter, never laxer.
+ */
+declare function strandingExcuses(flatNet: FlatNet, sinkPlaces: ReadonlySet<Place<any>>, conditional: readonly ConditionalSinks[]): (readonly number[] | null)[];
+/**
+ * Whether `m` holds a token that is stranded — outside every place where resting is
+ * permitted in `m`. The graph-route form of {@link strandingExcuses}.
+ */
+declare function strandsToken(m: MarkingState, sinkPlaces: ReadonlySet<Place<any>>, conditional: readonly ConditionalSinks[]): boolean;
+/**
+ * The declarations as the report prints them after the property description:
+ * `sinks: a, b; when h: c, d; when p`, or `null` when nothing is declared.
+ * Declaration order throughout, so the four implementations render the same text.
+ */
+declare function describeSinks(sinkPlaces: ReadonlySet<Place<any>>, conditional: readonly ConditionalSinks[]): string | null;
+
+/**
+ * @module programming-error
+ *
+ * Telling a verification failure apart from a bug.
+ *
+ * The pipeline is full of `catch` blocks that turn a failure into `Unknown`, or
+ * into a weaker but still well-formed result. Every one of them was written for a
+ * real condition — the solver died, the transport timed out, the replay search ran
+ * out of budget — and every one of them quietly acquires a second meaning: *any*
+ * defect in the code it guards. Once both arrive as the same verdict they cannot
+ * be told apart, and a bug becomes a permanently plausible weaker answer instead
+ * of a loud failure. That is the most expensive failure shape this verifier has:
+ * a report that looks right and proves less.
+ *
+ * So the taxonomy is explicit. A `TypeError` or `ReferenceError` is never a
+ * verdict — it is a defect in libpetri or in a caller's net, and it propagates. A
+ * `RangeError` *is* a verdict: a stack overflow on a deep net is the capacity
+ * limit `Unknown` exists to report. Everything else — a dead solver, a bad reply,
+ * an exhausted budget — is the condition the catch was written for and passes
+ * through untouched.
+ */
+/**
+ * Re-throws `e` when it is a programming defect rather than a verification
+ * outcome. Call it first in any `catch` that degrades a result.
+ */
+declare function rethrowIfProgrammingError(e: unknown): void;
+
+/**
+ * @module graph-decision
+ *
+ * The property predicate both state-class-graph routes decide, in one place.
+ *
+ * Two routes enumerate a finite graph of classes and read a verdict off it: the
+ * ν name-partition quotient of [VER-012] (`nu-scg-verifier`) and the plain
+ * bounded enumeration of [VER-017] (`scg-verifier`). They explore different
+ * graphs, but the question they ask of a class is identical, and [VER-002] AC7
+ * requires every route to decide the *same* predicate. Stating it once is what
+ * keeps that true: when the sink clause last lived in two copies, one of them
+ * drifted (NU-040 AC4).
+ */
+
+/** A finite graph of classes, indexed `0 .. count - 1`, class 0 the initial one. */
+interface ClassView {
+    readonly count: number;
+    /** The marking of class `i`. */
+    markingOf(i: number): MarkingState;
+    /** Whether class `i` has no successor — the graph's quiescence. */
+    isQuiescent(i: number): boolean;
+}
+/**
+ * The index of the first class witnessing a violation, or `-1` when the property
+ * holds across the whole graph.
+ *
+ * Quiescence-based properties read `isQuiescent`; reachability-safety properties
+ * read the marking alone. `DeadlockFree` uses the shared rest set of [VER-014],
+ * so a conditional sink excuses a token exactly as it does in the encoders.
+ */
+declare function decideOverClasses(view: ClassView, property: SmtProperty, sinkPlaces: ReadonlySet<Place<any>>, conditionalSinks?: readonly ConditionalSinks[]): number;
+
+/**
+ * @module scg-verifier
+ *
+ * Bounded state-space enumeration ([VER-017]): decide a property by building the
+ * state-class graph and reading the verdict off it, when the graph closes within
+ * a class budget.
+ *
+ * IC3/PDR is built for state spaces that are wide and shallow. A workflow net is
+ * the opposite — narrow and deep: a forty-node pipeline has under two thousand
+ * reachable classes, but its diameter is the length of the pipeline, so the
+ * fixpoint engine needs a frame per stage and its cost climbs with the cube of
+ * the length. Enumerating the same net is linear in the state space and finishes
+ * in milliseconds. Measured on a forty-node chain (370 places): 410 s on the
+ * fixpoint path, 0.11 s here.
+ *
+ * The route is exact when the graph closes — sound *and* complete, so a
+ * `violated` is a real firing sequence rather than a possibly-spurious
+ * over-approximation, and a `proven` is never the `unknown` a fixpoint search
+ * runs out of time for.
+ *
+ * It applies only to an **untimed** net — every transition `immediate` — and that
+ * restriction is what makes the verdict interchangeable with the encoders'. The
+ * state-class graph carries firing domains, so on a timed net it would explore
+ * only the runs the timing admits and its `proven` would be the weaker timed
+ * claim; [VER-004] is explicit that the untimed proof is the stronger one, and a
+ * route must not quietly hand back a weaker claim than the one it replaced. On an
+ * untimed net no domain excludes anything, the graph explores exactly the untimed
+ * reachable set, and the two routes decide the same predicate over the same
+ * abstraction — enumeration simply decides it where the search may not.
+ *
+ * When the graph does not close within the budget the route declines and the
+ * caller runs the SMT pipeline unchanged: enumeration never turns a verdict into
+ * `unknown` that the solver could have decided.
+ */
+
+/**
+ * Whether every transition is `immediate`, so the state-class graph explores the
+ * untimed reachable set exactly and its verdict is the encoders' claim rather
+ * than the weaker timed one. See this module's header.
+ */
+declare function isUntimed(net: PetriNet): boolean;
+/** The note a decided verdict carries into the report. */
+declare const NOTE_ENUMERATED: string;
+/** Outcome of the enumeration route. */
+type ScgOutcome = 
+/** The graph closed and decided the property. */
+{
+    readonly kind: 'decided';
+    readonly verdict: Verdict;
+    readonly trace: MarkingState[];
+    readonly transitions: string[];
+    readonly classCount: number;
+}
+/** The graph hit the class budget; the caller falls through to the SMT pipeline. */
+ | {
+    readonly kind: 'truncated';
+    readonly classCount: number;
+};
+/**
+ * Decides `property` by enumeration, or reports truncation.
+ *
+ * @param maxClasses the class budget; `<= 0` disables the route (the caller then
+ *   never calls this).
+ */
+declare function verifyViaStateClassGraph(net: PetriNet, initial: MarkingState, property: SmtProperty, sinkPlaces: ReadonlySet<Place<any>>, maxClasses: number, conditionalSinks?: readonly ConditionalSinks[]): ScgOutcome;
+
 /** Environment variable naming the z3 executable (default: `z3` on `PATH`). */
 declare const Z3_ENV = "LIBPETRI_Z3";
 /** Environment variable naming a directory that receives every script and reply. */
@@ -406,14 +582,15 @@ type CertificateCheckOutcome = {
  * @param sinkPlaces declared sink places (deadlock-freedom VC3)
  * @param solver the resolved z3 executable
  * @param timeoutMs per-invocation solver budget in milliseconds
+ * @param conditionalSinks conditional sink declarations (VER-014, deadlock-freedom VC3)
  */
-declare function checkCertificate(certificate: string | null, flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[], sinkPlaces: ReadonlySet<Place<any>>, solver: Z3Solver, timeoutMs: number): Promise<CertificateCheckOutcome>;
+declare function checkCertificate(certificate: string | null, flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[], sinkPlaces: ReadonlySet<Place<any>>, solver: Z3Solver, timeoutMs: number, conditionalSinks?: readonly ConditionalSinks[], stateEquation?: boolean): Promise<CertificateCheckOutcome>;
 /**
  * The certificate-check script for the given inputs, exactly as
  * {@link checkCertificate} would send it (VER-013 script parity): what the
  * cross-language golden tests diff.
  */
-declare function vcScript(certificate: string, flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, sinkPlaces: ReadonlySet<Place<any>>, invariants: readonly PInvariant[]): string;
+declare function vcScript(certificate: string, flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, sinkPlaces: ReadonlySet<Place<any>>, invariants: readonly PInvariant[], conditionalSinks?: readonly ConditionalSinks[], stateEquation?: boolean): string;
 
 /**
  * Name-correlation fragment classifier for the ν-aware state class graph
@@ -492,13 +669,17 @@ declare class SmtVerifier {
     private _property;
     private readonly _environmentPlaces;
     private readonly _sinkPlaces;
+    private readonly _conditionalSinks;
     private readonly _budgetPlaces;
     private _environmentMode;
     private _timeoutMs;
     private _certificateCheck;
     private _counterexampleReplay;
     private _semiflowInvariants;
+    private _stateEquation;
+    private _linearBound;
     private _nuMaxClasses;
+    private _enumerationMaxClasses;
     private _fragmentMode;
     private readonly _carrierPlaces;
     private _prioritySemantics;
@@ -510,10 +691,36 @@ declare class SmtVerifier {
     environmentPlaces(...places: EnvironmentPlace<any>[]): this;
     environmentMode(mode: EnvironmentAnalysisMode): this;
     /**
-     * Declares expected sink (terminal) places for deadlock-freedom analysis.
-     * Markings where any sink place has a token are not considered deadlocks.
+     * Declares expected sink (terminal) places for deadlock-freedom analysis
+     * (VER-002): a token resting in one is never stranded, and `TerminatesAtSink`
+     * asks whether one of them was reached.
      */
     sinkPlaces(...places: Place<any>[]): this;
+    /**
+     * Declares places where a token may rest **while `marker` holds a token**
+     * (VER-014) — a designed terminal such as a halt or pause marker, under which
+     * the work it interrupted legitimately stays where it was delivered.
+     *
+     * `DeadlockFree` then reads a quiescent marking against the union of the
+     * declared sinks, the markers, and every conditional set whose marker is marked:
+     * a token in `p` is stranded only when none of those excuse it. The marker
+     * itself is at rest whenever it is marked, so `sinkPlacesWhen(halt)` with no
+     * further places excuses exactly the halt token. Repeated calls for one marker
+     * accumulate; declarations for several markers union. `TerminatesAtSink` is
+     * unaffected and reads only {@link sinkPlaces}.
+     *
+     * ```ts
+     * SmtVerifier.forNet(net)
+     *   .property(deadlockFree())
+     *   .sinkPlaces(done)                       // may always rest
+     *   .sinkPlacesWhen(halt, inbox, pending)   // may rest once the run halted
+     *   .sinkPlacesWhen(pause, inbox)           // may rest while paused
+     * ```
+     *
+     * An unresolved marker or place contributes nothing, as an unresolved sink
+     * does: a mistyped marker makes the property stricter, never laxer.
+     */
+    sinkPlacesWhen(marker: Place<any>, ...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
@@ -579,7 +786,58 @@ declare class SmtVerifier {
      * `Certificate check: not applicable (name-coloured encoding)`. Off by default so
      * reports stay byte-equal.
      */
-    semiflowInvariants(enabled: boolean): this;
+    /**
+     * `'auto'` decides whether the semiflows would add **information to the
+     * encoding**, which is not the same question as whether they would appear in
+     * {@link SmtVerificationResult.invariants} for a caller who reads them.
+     *
+     * A complete basis spans every conservation law of the net, so a semiflow it
+     * spans constrains nothing further and IC3 gains nothing from it — that is why
+     * `'auto'` skips the enumeration there. But the basis is the *signed*
+     * null-space, and a law it spans need not appear in it in **non-negative**
+     * form; only the Farkas enumeration produces that. A caller inspecting the
+     * invariant list for a law of a given shape — "a non-negative law weighting the
+     * budget place and every running place positively" — can therefore find nothing
+     * on a net that plainly has one. Such a caller should ask for the union
+     * explicitly: `'auto'` is the setting to prefer for verification, not for
+     * harvesting.
+     */
+    semiflowInvariants(enabled: boolean | 'auto'): this;
+    /**
+     * Enables/disables the linear state-equation bound phase (VER-015; default:
+     * enabled). A reachability-safety property whose violating markings exceed some
+     * `y·M <= y·M0` with `y >= 0`, `y·C <= 0` is then proven structurally, from one
+     * linear query re-checked in exact integer arithmetic, before any fixpoint search.
+     * Disable it to force the IC3/PDR path — for its certificate, or to exercise the
+     * fixpoint engine itself.
+     */
+    linearBound(enabled: boolean): this;
+    /**
+     * Encodes the **state equation** with firing counters (VER-016; default:
+     * disabled — the encoding then carries places only).
+     *
+     * The flat encoding gains one counter `n_t` per flat transition and every
+     * transition rule conjoins the marking equation `M' = M0 + C·n'` for each place
+     * whose column is exact (no consume-all / reset arc, not injected). Every linear
+     * consequence of the marking equation — the equality laws of VER-005/VER-007
+     * **and** the inequality laws `y·M ≤ y·M0` (`y ≥ 0, y·C ≤ 0`) and their mixed-sign
+     * kin, which are what an *ordering* argument ("both join slots armed means every
+     * upstream stage has run, so nothing can still halt") looks like in linear
+     * arithmetic — is then available to Spacer as a fact rather than a lemma it has to
+     * invent. On a 50-place agent-dispatch workflow, proper completion under conditional
+     * sinks went from `unknown` after 120 s to `proven` in 1.5 s with this as the only
+     * change; a 53-place pipeline stage before a join, `unknown` at 300 s, proves in
+     * under a second.
+     *
+     * The cost is a larger state (places + transitions) and a slower witness search
+     * on genuinely violated properties (about 1.5× on the nets above), so it is opt-in.
+     * Soundness is unchanged: the counters are exact bookkeeping, the equation holds
+     * on every reachable state by construction (`Strengthening.lean`, the same shape
+     * as the equality laws), and the certificate check re-proves it against the raw
+     * step relation, whose only counter knowledge is the increment. Not applied to the
+     * name-coloured encoding or Route B, which the report says when it applies.
+     */
+    stateEquation(enabled: boolean): 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
@@ -587,6 +845,26 @@ declare class SmtVerifier {
      * structurally bounded). Default 100_000.
      */
     nuMaxClasses(max: number): this;
+    /**
+     * Sets the class budget for the bounded state-space enumeration route
+     * (VER-017; default 50 000). `0` disables the route, so every query goes to
+     * the SMT pipeline.
+     *
+     * When the state-class graph closes within the budget the property is decided
+     * exactly — sound and complete over the timed semantics — and no solver runs.
+     * This is what makes a long pipeline tractable: IC3 needs a frame per stage and
+     * its cost climbs with the cube of the length, while enumeration is linear in
+     * the reachable state space. A forty-node chain (370 places, 1 967 classes)
+     * takes 410 s on the fixpoint path and 0.11 s here.
+     *
+     * The route declines when the graph exceeds the budget, and the SMT pipeline
+     * then runs unchanged — it can only add verdicts, never remove them. It is
+     * skipped for ν-nets, which have their own exact route (NU-050, Route B), for
+     * nets with environment places, whose injection the graph does not model, and
+     * for **timed** nets, where its verdict would be the weaker timed claim rather
+     * than the untimed one the encoders make (VER-004).
+     */
+    enumerationMaxClasses(max: number): this;
     /**
      * Selects the ν-net coloured-place fragment for Route B (NU-051). `base`
      * (default) admits the shipped mint → matched-join fragment only; `extended`
@@ -650,6 +928,14 @@ declare class SmtVerifier {
      * @throws Error if the net violates CORE-043 — verification rejects the same nets execution rejects.
      */
     verify(): Promise<SmtVerificationResult>;
+    /**
+     * Runs the linear state-equation bound query (VER-015) and re-checks its answer in
+     * exact integer arithmetic. Returns the bound as the report prints it when one
+     * separates the violation, `null` otherwise (no bound, solver inconclusive, or a
+     * model that failed the re-check — each named in the report). Never the last word:
+     * `null` hands over to the fixpoint query.
+     */
+    private linearBoundProof;
     /**
      * ν-net soundness guard (NU-040, NU-050). Applied only when the net contains
      * match (ν-join) transitions, and only to a proven/violated verdict (an
@@ -679,6 +965,11 @@ interface EncodedScripts {
     readonly certificate: string | null;
     /** Whether `horn` is the name-coloured encoding. */
     readonly coloured: boolean;
+    /**
+     * The linear state-equation bound query (VER-015), or `null` for a property with
+     * no linear demand (the quiescence properties).
+     */
+    readonly bound: string | null;
 }
 /**
  * `(define-fun Reachable ((x!0 Int) …) Bool true)`: the certificate stand-in the
@@ -744,6 +1035,11 @@ declare function runZ3Spacer(solver: Z3Solver, timeoutMs: number, smt2: string,
  * 3. **Error**: `Error :- Reachable(M) ∧ violation(M)`; `(assert (not Error))`, so
  *    `sat` is PROVEN and `unsat` is VIOLATED
  *
+ * With the state equation (VER-016, {@link encodeNet}) the state is `(M, n)` — one
+ * firing counter per flat transition — and every transition rule also conjoins
+ * `M' = M0 + C·n'`, which hands Spacer every linear consequence of the marking
+ * equation (the inequality conservation laws it cannot invent) at no enumeration cost.
+ *
  * The emitted script is byte-identical to the Rust reference (`smt_encoder.rs`) and
  * the Java port for the same input: places in code-point order of their names, the
  * property's places, sinks, env bounds and injections in place-index order,
@@ -754,16 +1050,48 @@ declare function runZ3Spacer(solver: Z3Solver, timeoutMs: number, smt2: string,
 interface SmtEncoding {
     /** The script text. */
     readonly smt2: string;
-    /** The number of flat places (the arity of `Reachable` in the flat encoding). */
+    /** The number of flat places (the leading arguments of `Reachable` in the flat encoding). */
     readonly placeCount: number;
+    /**
+     * The number of firing counters that follow the places in `Reachable` (VER-016):
+     * one per flat transition when the state equation is encoded, else 0.
+     */
+    readonly counterCount: number;
+}
+/** Options of {@link encodeNet}. */
+interface EncodeOptions {
+    /** Declared sink places (VER-002). */
+    readonly sinkPlaces?: ReadonlySet<Place<any>>;
+    /** Emit `:produce-proofs` and `(get-proof)` so an `unsat` reply carries the refutation the replay decodes. */
+    readonly produceProofs?: boolean;
+    /** Conditional sinks (VER-014); read by `deadlock-free` only. */
+    readonly conditionalSinks?: readonly ConditionalSinks[];
+    /**
+     * Carry one firing counter per flat transition and conjoin the marking equation
+     * `M' = M0 + C·n'` (VER-016) into every rule body. Off by default (scripts stay
+     * byte-identical).
+     */
+    readonly stateEquation?: boolean;
 }
 /**
  * Encodes the net and property as a HORN script.
  *
  * @param produceProofs emit `:produce-proofs` and `(get-proof)` so an `unsat` reply
  *   carries the refutation the replay decodes
+ * @param conditionalSinks places where a token may rest while a marker is marked
+ *   (VER-014); read by `deadlock-free` only
+ */
+declare function encode(flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[], sinkPlaces?: ReadonlySet<Place<any>>, produceProofs?: boolean, conditionalSinks?: readonly ConditionalSinks[]): SmtEncoding;
+/**
+ * {@link encode} with named options. With `stateEquation` (VER-016) the state carries
+ * one firing counter per flat transition after the places: `Reachable(M, n)`, the
+ * initial fact has `n = 0`, transition `k`'s rule increments `n_k` and copies the
+ * others, an injection rule copies them all, and every transition rule's body
+ * conjoins `m'_p = M0_p + Σ_t C[p][t]·n'_t` for each place whose column is exact
+ * (no consume-all / reset arc, not injected) together with `n' ≥ 0`. The error rule
+ * quantifies the counters and constrains only the marking.
  */
-declare function encode(flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[], sinkPlaces?: ReadonlySet<Place<any>>, produceProofs?: boolean): SmtEncoding;
+declare function encodeNet(flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[], options?: EncodeOptions): SmtEncoding;
 /**
  * The net's one-step relation `T(M, M')` as one plain SMT-LIB2 formula over the free
  * variables `m0..` / `m0p..`: the disjunction of every flat transition firing and
@@ -772,7 +1100,75 @@ declare function encode(flatNet: FlatNet, initialMarking: MarkingState, property
  * path but omits the P-invariant conjuncts, so a certificate poisoned by a wrong
  * invariant cannot re-certify itself.
  */
-declare function encodeStepRelationSmt2(flatNet: FlatNet): string;
+declare function encodeStepRelationSmt2(flatNet: FlatNet, stateEquation?: boolean): string;
+
+/**
+ * @module linear-bound
+ *
+ * The linear state-equation bound (VER-015): a structural proof of a
+ * reachability-safety property that needs no fixpoint search.
+ *
+ * Every reachable marking of the abstract net satisfies `M = M0 + C·σ` for some
+ * firing count vector `σ ≥ 0`, so for any weighting `y ≥ 0` with `y·C ≤ 0` on every
+ * transition, `y·M ≤ y·M0` holds along every run — a **decreasing** conservation
+ * law, where the P-invariants of [VER-005] are the *equalities* `y·C = 0`. The
+ * violation of a reachability-safety property is a lower demand on some places
+ * (`m_p ≥ 1` for each place of an `unreachable`, `m_p ≥ k+1` for a `placeBound`);
+ * if some `y` makes that demand exceed `y·M0`, no reachable marking meets it and the
+ * property is proven.
+ *
+ * Finding `y` is one linear query in `QF_LIA`, answered by the same `z3` transport
+ * as everything else ([VER-013]); the answer is then re-checked in exact integer
+ * arithmetic (`y ≥ 0`, `y·C ≤ 0` per transition, `y·d ≥ y·M0 + 1`), so the proof
+ * rests on the check, not on the solver. It closes exactly the class of proofs IC3
+ * misses on pipeline-shaped nets: an ordering argument ("both join slots armed means
+ * every upstream stage has run, so no halt is still possible") is a weighted count
+ * bound, which Spacer's lemma generalisation does not invent over fifty variables
+ * but a linear solver finds in milliseconds.
+ *
+ * Soundness needs the same guards as the equality laws: zero weight on every
+ * consume-all / reset place (H1 — the fire relation is not linear there) and on
+ * every injected environment place (H3' — injection breaks conservation).
+ */
+
+/** One linear bound `Σ weights[p]·m_p ≤ constant`, with the demand it separates. */
+interface LinearBound {
+    /** `y`, one entry per flat place, all non-negative. */
+    readonly weights: readonly bigint[];
+    /** `y·M0`. */
+    readonly constant: bigint;
+    /** `y·d`, what the violating markings need at least; strictly above `constant`. */
+    readonly demandValue: bigint;
+}
+/**
+ * The violation's demand: flat place index → the least count a violating marking
+ * holds there. `null` when the property is not a reachability-safety property, or
+ * names no place the net resolves (the verifier refuses those before this runs).
+ */
+declare function violationDemand(flatNet: FlatNet, property: SmtProperty): Map<number, number> | null;
+/**
+ * The `QF_LIA` script asking for a separating `y`, or `null` when the property has
+ * no linear demand. Byte-identical across the four implementations: places in flat
+ * index order, one row per flat transition in net order, `(- k)` for a negative
+ * literal, a lone term unwrapped.
+ */
+declare function encodeLinearBound(flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty): string | null;
+/**
+ * The weighting in a `sat` reply's model: `y_p` per flat place, zero where the model
+ * is silent. `null` when the reply defines no `y`.
+ */
+declare function decodeLinearBound(stdout: string, placeCount: number): bigint[] | null;
+/**
+ * Re-proves the bound in exact integer arithmetic: `y ≥ 0`, zero on every H1/H3'
+ * place, `y·C ≤ 0` on every flat transition, and `y·d ≥ y·M0 + 1`. Returns the bound
+ * when every check passes and `null` otherwise — the verifier then continues to the
+ * fixpoint query rather than trust the solver's model.
+ */
+declare function checkLinearBoundExact(flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, y: readonly bigint[]): LinearBound | null;
+/** `2*a + b <= 2` — the bound as the report prints it. */
+declare function formatLinearBound(flatNet: FlatNet, bound: LinearBound): string;
+/** `ready_0 + ready_1 + _halt >= 3` — the violation's weighted demand as the report prints it. */
+declare function formatLinearDemand(flatNet: FlatNet, property: SmtProperty, bound: LinearBound): string;
 
 /**
  * @module counterexample-decoder
@@ -801,12 +1197,12 @@ interface DecodedTrace {
     readonly note: string | null;
 }
 /** Decodes the states of a z3 reply; a note says so when none were found. */
-declare function decode(answer: string, flatNet: FlatNet): DecodedTrace;
+declare function decode(answer: string, flatNet: FlatNet, counterCount?: number): DecodedTrace;
 /**
  * Collects the ground `Reachable(...)` applications from a z3 refutation proof into
  * a state set, in text order.
  */
-declare function decodeStateSet(answer: string, flatNet: FlatNet): ReadonlySet<MarkingState>;
+declare function decodeStateSet(answer: string, flatNet: FlatNet, counterCount?: number): ReadonlySet<MarkingState>;
 
 /**
  * @module abstract-replayer
@@ -907,7 +1303,7 @@ type ReplayOutcome = {
  * search — non-dominated states only, the root included (see
  * {@link ReplayOptions.nodeBudget}).
  */
-declare function replayCounterexample(flatNet: FlatNet, initial: AbstractState, decodedStates: readonly AbstractState[], property: SmtProperty, sinkPlaces: ReadonlySet<Place<any>>, options?: ReplayOptions): ReplayOutcome;
+declare function replayCounterexample(flatNet: FlatNet, initial: AbstractState, decodedStates: readonly AbstractState[], property: SmtProperty, sinkPlaces: ReadonlySet<Place<any>>, options?: ReplayOptions, conditionalSinks?: readonly ConditionalSinks[]): ReplayOutcome;
 
 /**
  * Difference Bound Matrix (DBM) for Time Petri Net state class analysis.
@@ -940,10 +1336,35 @@ declare class DBM {
      * Implements the 5-step Berthomieu-Diaz successor formula.
      */
     fireTransition(firedClock: number, newClockNames: readonly string[], newLowerBounds: number[], newUpperBounds: number[], persistentClocks: number[]): DBM;
+    /**
+     * The same zone with its clocks reordered: clock `k` of the result is clock
+     * `order[k]` of this DBM. `order` must be a permutation of `0..clockCount()-1`.
+     *
+     * The state-class graph applies this to put every class's clocks in the one
+     * canonical order (VER-010), so two arrivals at the same marking and zone whose
+     * transitions became enabled in a different sequence share a key instead of
+     * being counted as two classes. The reference row and column stay put; the
+     * matrix is copied once, O(dim²) against the O(dim³) canonicalisation every
+     * successor already pays.
+     */
+    permuted(order: readonly number[]): DBM;
     /** Lets time pass: set all lower bounds to 0. */
     letTimePass(): DBM;
     private canonicalize;
     equals(other: DBM): boolean;
+    /**
+     * The zone's identity for state-class dedup: the clock names and the FULL
+     * canonical matrix, every difference bound included.
+     *
+     * {@link toString} prints only the per-clock projections `[lo, hi]`, and two
+     * zones can agree on every projection while disagreeing on a difference
+     * constraint `θi - θj <= c` — the class where one transition must fire no later
+     * than another versus the class where either may go first. Keying on the
+     * projections merges those, and since the graph explores only the first
+     * arrival's successors, a marking reachable only from the second is lost: a
+     * false `proven`. This key is what {@link equals} compares, rendered.
+     */
+    zoneKey(): string;
     toString(): string;
 }
 
@@ -1098,4 +1519,4 @@ declare class TimePetriNetAnalyzerBuilder {
     build(): TimePetriNetAnalyzer;
 }
 
-export { type AbstractState, EnvironmentAnalysisMode as AnalysisEnvironmentMode, type BranchEdge, type CertificateCheckOutcome, type CertificateVc, DBM, DUMP_ENV, type DecodedTrace, type EncodedScripts, EnvironmentAnalysisMode, type FlatNet, type FlatTransition, IncidenceMatrix, type LivenessResult, MIN_Z3_VERSION, MarkingState, MarkingStateBuilder, PInvariant, type PrioritySemantics, type QueryProven, type QueryResult, type QueryUnknown, type QueryViolated, type ReplayOptions, type ReplayOutcome, type ReplayStep, type SmtEncoding, SmtProperty, SmtVerificationResult, SmtVerifier, StateClass, StateClassGraph, type StructuralCheckResult, TimePetriNetAnalyzer, TimePetriNetAnalyzerBuilder, type XorBranchAnalysis, type XorBranchInfo, type Z3Exit, Z3ProcessError, type Z3Reply, type Z3Solver, Z3Unavailable, type Z3Version, Z3_ENV, canonicalInvariantOrder, checkCertificate, computePInvariants, computePSemiflows, computeSCCs, decode, decodeStateSet, encode, encodeStepRelationSmt2, findMaximalTrapIn, findMinimalSiphons, findTerminalSCCs, flatNetIndexOf, flatNetPlaceCount, flatNetTransitionCount, flatTransition, flatten, formatZ3Version, isCoveredByInvariants, parseZ3Version, placeholderCertificate, replayCounterexample, resolveZ3, runZ3Spacer, runZ3Text, strengthenWithSemiflows, structuralCheck, vcScript, z3Available, z3SolverAt };
+export { type AbstractState, EnvironmentAnalysisMode as AnalysisEnvironmentMode, type BranchEdge, type CertificateCheckOutcome, type CertificateVc, type ClassView, type ConditionalSinks, DBM, DUMP_ENV, type DecodedTrace, type EncodeOptions, type EncodedScripts, EnvironmentAnalysisMode, type FlatNet, type FlatTransition, IncidenceMatrix, type LinearBound, type LivenessResult, MIN_Z3_VERSION, MarkingState, MarkingStateBuilder, NOTE_ENUMERATED, PInvariant, type PrioritySemantics, type QueryProven, type QueryResult, type QueryUnknown, type QueryViolated, type ReplayOptions, type ReplayOutcome, type ReplayStep, type ScgOutcome, type SmtEncoding, SmtProperty, SmtVerificationResult, SmtVerifier, StateClass, StateClassGraph, type StructuralCheckResult, TimePetriNetAnalyzer, TimePetriNetAnalyzerBuilder, Verdict, type XorBranchAnalysis, type XorBranchInfo, type Z3Exit, Z3ProcessError, type Z3Reply, type Z3Solver, Z3Unavailable, type Z3Version, Z3_ENV, canonicalInvariantOrder, checkCertificate, checkLinearBoundExact, computePInvariants, computePSemiflows, computeSCCs, decideOverClasses, decode, decodeLinearBound, decodeStateSet, describeSinks, encode, encodeLinearBound, encodeNet, encodeStepRelationSmt2, findMaximalTrapIn, findMinimalSiphons, findTerminalSCCs, flatNetIndexOf, flatNetPlaceCount, flatNetTransitionCount, flatTransition, flatten, formatLinearBound, formatLinearDemand, formatZ3Version, isCoveredByInvariants, isUntimed, parseZ3Version, placeholderCertificate, replayCounterexample, resolveZ3, rethrowIfProgrammingError, runZ3Spacer, runZ3Text, strandingExcuses, strandsToken, strengthenWithSemiflows, structuralCheck, vcScript, verifyViaStateClassGraph, violationDemand, z3Available, z3SolverAt };