libpetri 3.0.0 → 4.0.0

package/dist/verification/index.d.ts

@@ -1,6 +1,5 @@
-import { b as Transition, a as Place, P as PetriNet, E as EnvironmentPlace, aO as MarkingState, aP as PInvariant, aQ as MarkingStateBuilder, aR as SmtProperty, aS as SmtVerificationResult } from '../petri-net-UQBBkvLl.js';
-export { aT as BranchPlaceBound, aU as DeadlockFree, aV as JoinedOrDeadLettered, aW as MutualExclusion, aX as PlaceBound, aY as Proven, aZ as SmtStatistics, a_ as TokenSupplier, a$ as Unknown, b0 as Unreachable, b1 as Verdict, $ as VerificationHarness, a0 as VerificationResult, b2 as Violated, b3 as branchPlaceBound, b4 as deadlockFree, b5 as isProven, b6 as isViolated, b7 as joinedOrDeadLettered, b8 as mutualExclusion, b9 as pInvariant, ba as pInvariantToString, bb as placeBound, bc as propertyDescription, bd as unreachable } from '../petri-net-UQBBkvLl.js';
-import { Expr, init, Bool, FuncDecl } from 'z3-solver';
+import { b as Transition, a as Place, P as PetriNet, E as EnvironmentPlace, aO as PInvariant, aP as MarkingState, aQ as SmtProperty, aR as MarkingStateBuilder, aS as SmtVerificationResult } from '../petri-net-hduM6tJf.js';
+export { aT as BranchPlaceBound, aU as DeadlockFree, aV as JoinedOrDeadLettered, aW as MutualExclusion, aX as PlaceBound, aY as Proven, aZ as SmtStatistics, a_ as TokenSupplier, a$ as Unknown, b0 as Unreachable, b1 as Verdict, $ as VerificationHarness, a0 as VerificationResult, b2 as Violated, b3 as branchPlaceBound, b4 as deadlockFree, b5 as isProven, b6 as isViolated, b7 as joinedOrDeadLettered, b8 as mutualExclusion, b9 as pInvariant, ba as pInvariantToString, bb as placeBound, bc as propertyDescription, bd as unreachable } from '../petri-net-hduM6tJf.js';
 
 /**
  * A flattened transition with pre/post vectors for SMT encoding.
@@ -182,22 +181,35 @@ declare function flatten(net: PetriNet, environmentPlaces?: Set<EnvironmentPlace
  */
 declare function computePInvariants(matrix: IncidenceMatrix, flatNet: FlatNet, initialMarking: MarkingState): PInvariant[];
 /**
- * Computes minimal **P-semiflows** — non-negative place weightings `y` with
- * `y·C = 0` — via the Colom–Silva / Farkas method. Unlike {@link computePInvariants}
- * (a signed null-space basis), every returned `PInvariant.weights` is non-negative:
- * a genuine P-semiflow, with `constant = y·M0`. A non-negative conservation law
- * soundly **bounds** the token sum over its support: `Σ_{support} M(p) ≤ y·M0`. Used
- * to bound the number of simultaneously-live colours in the name-coloured encoder
- * (see `colourSlotBound`).
+ * VER-007 — the semiflow union. Appends every gate-validated P-semiflow that is not
+ * already a basis row (same weights, same constant) to `invariants`, returning the
+ * strengthened list and how many rows were added.
  *
- * Mirrors the Rust reference `compute_p_semiflows`.
+ * The null-space basis is one basis of many: elimination hands back mixed-sign rows
+ * and rows that fold a reset place into a chain whose other combinations avoid it,
+ * both lost to the exact gate — on a reset-heavy net every law of the chains those
+ * arcs touch, leaving IC3 to rediscover conservation it cannot within any practical
+ * budget. The Farkas rows ({@link computePSemiflows}) are the minimal laws of the
+ * net. Conjoining them alongside the basis is pure strengthening (`Semiflow.lean`,
+ * `semiflow_union_sound`) **provided both lists passed the same exact gate**
+ * (`semiflow_gate_is_necessary`) — the caller's obligation; this only merges.
  */
+declare function strengthenWithSemiflows(invariants: readonly PInvariant[], semiflows: readonly PInvariant[]): {
+    readonly invariants: readonly PInvariant[];
+    readonly added: number;
+};
 declare function computePSemiflows(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;
+/**
+ * The invariants in canonical order (VER-013): by ascending support, then weights,
+ * then constant, each compared lexicographically. The same order the Rust and Java
+ * verifiers apply, so the strengthened scripts are byte-identical.
+ */
+declare function canonicalInvariantOrder(invariants: readonly PInvariant[]): PInvariant[];
 
 /**
  * @module structural-check
@@ -259,6 +271,168 @@ declare function findMinimalSiphons(flatNet: FlatNet): ReadonlySet<number>[];
  */
 declare function findMaximalTrapIn(flatNet: FlatNet, places: ReadonlySet<number>): ReadonlySet<number>;
 
+/** 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. */
+declare const DUMP_ENV = "LIBPETRI_SMT_DUMP";
+/** A z3 release version, ordered numerically. */
+interface Z3Version {
+    readonly major: number;
+    readonly minor: number;
+    readonly patch: number;
+}
+/**
+ * Oldest z3 the transport accepts: `-t`/`-T`, Spacer as `fp.engine`, and the
+ * `(get-model)` / `(get-proof)` printers the decoders read are stable from here.
+ */
+declare const MIN_Z3_VERSION: Z3Version;
+/** Parses the version out of a `z3 --version` reply (`Z3 version 4.16.0 - 64 bit`). */
+declare function parseZ3Version(text: string): Z3Version | null;
+declare function formatZ3Version(v: Z3Version): string;
+/** A resolved z3 executable: where it is and which version answered the probe. */
+interface Z3Solver {
+    /** The executable as resolved (a path, or a bare name on `PATH`). */
+    readonly program: string;
+    /** The version the probe reported. */
+    readonly version: Z3Version;
+    /** Where scripts and replies are written, or `null` for no dump. */
+    readonly dumpDir: string | null;
+}
+/** No usable z3 resolved; the message is the `unknown` reason the verifier reports. */
+declare class Z3Unavailable extends Error {
+    constructor(message: string);
+}
+/** The process could not be started; the message is the `unknown` reason. */
+declare class Z3ProcessError extends Error {
+    constructor(message: string);
+}
+/** How a z3 process ended. */
+type Z3Exit = {
+    readonly kind: 'exited';
+    readonly code: number | null;
+} | {
+    readonly kind: 'killed';
+};
+/** The raw reply of one z3 run. */
+interface Z3Reply {
+    readonly stdout: string;
+    readonly stderr: string;
+    readonly exit: Z3Exit;
+}
+/** Resolves a specific executable (tests point this at a stub). No dump directory. */
+declare function z3SolverAt(program: string, env?: NodeJS.ProcessEnv): Z3Solver;
+/**
+ * Resolves the executable named by {@link Z3_ENV}, or `z3` on `PATH`, probes its
+ * version, and reads {@link DUMP_ENV}. Throws {@link Z3Unavailable}.
+ */
+declare function resolveZ3(env?: NodeJS.ProcessEnv): Z3Solver;
+/**
+ * True if a usable `z3` executable resolves: `LIBPETRI_Z3` if set, else `z3` on
+ * `PATH`, at or above {@link MIN_Z3_VERSION}. Without one every SMT path returns
+ * `unknown`; the test suites use this to skip loudly rather than fail.
+ */
+declare function z3Available(env?: NodeJS.ProcessEnv): boolean;
+/**
+ * Runs one script through one z3 process and resolves with the raw reply. `phase`
+ * names the dump files; `extraArgs` follow the standard argument list. The only
+ * rejection is a failed spawn: a solver that printed nothing, errored, timed out or
+ * was killed still comes back as a reply for the caller to classify
+ * ({@link failureReason}).
+ */
+declare function runZ3Text(solver: Z3Solver, script: string, phase: string, timeoutMs: number, extraArgs?: readonly string[]): Promise<Z3Reply>;
+
+/**
+ * @module certificate-checker
+ *
+ * Independent certificate check for IC3/PDR proofs.
+ *
+ * When Z3 Spacer answers `sat` on the CHC encoding ({@link module:smt-encoder}), the
+ * model it prints interprets `Reachable` as an inductive invariant, the proof
+ * certificate. This module re-verifies that certificate with plain (non-HORN) SMT
+ * queries in a SECOND z3 run, so a `proven` verdict no longer rests on the empirical
+ * HORN sat ⇒ proven mapping alone, nor on the correctness of the P-invariant
+ * strengthening: the three verification conditions below are discharged against the
+ * UNSTRENGTHENED step relation ({@link encodeStepRelationSmt2}).
+ *
+ * The candidate invariant is `R' := R ∧ Inv`, where `R` is the pasted `Reachable`
+ * interpretation and `Inv` the validated P-invariant equalities the CHC encoding
+ * strengthened its rule bodies with: a Spacer model is only guaranteed inductive
+ * *relative to* that strengthening, so the conjuncts ride along in the candidate, but
+ * the RELATION stays unstrengthened, which means VC1/VC2 re-prove each conjunct's
+ * initiation and inductiveness from scratch. A wrong P-invariant cannot weaken this
+ * check: it fails init or consecution instead.
+ *
+ * 1. **VC1 (init)**: `¬R'(M₀)` is UNSAT.
+ * 2. **VC2 (consecution)**: `M ≥ 0 ∧ R'(M) ∧ T(M,M') ∧ ¬R'(M')` is UNSAT.
+ * 3. **VC3 (safety)**: `M ≥ 0 ∧ R'(M) ∧ Bad(M)` is UNSAT.
+ *
+ * The `M ≥ 0` conjunct is the state domain: markings are token counts, so the VCs
+ * range over ℕ^P; without it a certificate inductive over ℕ^P is refuted by a negative
+ * predecessor in ℤ^P.
+ *
+ * The certificate is the `(define-fun …)` block of the `(get-model)` reply, pasted
+ * verbatim: auxiliary definitions stay alongside `Reachable`, so every name resolves
+ * in the fresh script. The three VCs run under `(push)`/`(pop)` in ONE script; the
+ * emitted text is byte-identical to the Rust reference (`certificate_check.rs`) and
+ * the Java port.
+ *
+ * Outcomes are split the way the caller must treat them: `failed` names the first VC
+ * that was not UNSAT (with the solver status and, for SAT, a witness marking),
+ * `unavailable` means the check could not run at all (missing or malformed
+ * certificate, solver spawn failure, errored assert). Both withhold PROVEN; neither
+ * throws.
+ */
+
+/** Label of a validity condition, as it appears in the downgrade reason. */
+type CertificateVc = 'initiation (VC1)' | 'consecution (VC2)' | 'safety (VC3)';
+/**
+ * Outcome of the certificate check.
+ *
+ * `passed` — all three validity conditions are UNSAT; the proven verdict is certified
+ * independently of the Fixedpoint engine.
+ * `failed` — a validity condition was not UNSAT; `detail` carries the solver status
+ * and, when the solver produced a model, a witness marking.
+ * `unavailable` — the check could not run (missing/malformed certificate, solver
+ * failure), so no VC is implicated.
+ *
+ * The caller must withhold PROVEN on `failed` and `unavailable` alike.
+ */
+type CertificateCheckOutcome = {
+    readonly type: 'passed';
+    readonly invariant: string;
+} | {
+    readonly type: 'failed';
+    readonly vc: CertificateVc;
+    readonly detail: string;
+    readonly invariant: string;
+} | {
+    readonly type: 'unavailable';
+    readonly reason: string;
+    readonly invariant: string | null;
+};
+/**
+ * Re-verifies an extracted proof certificate against the unstrengthened step relation.
+ *
+ * @param certificate the `(define-fun …)` block extracted verbatim from the Spacer
+ *   model (`null` when the solver printed none)
+ * @param flatNet the flat net the CHC query was encoded from
+ * @param initialMarking the verified initial marking (VC1)
+ * @param property the verified property (VC3)
+ * @param invariants the exactly-validated P-invariants the CHC bodies were
+ *   strengthened with; conjoined into the CANDIDATE certificate and re-proven by the
+ *   three VCs (never conjoined into the step relation)
+ * @param sinkPlaces declared sink places (deadlock-freedom VC3)
+ * @param solver the resolved z3 executable
+ * @param timeoutMs per-invocation solver budget in milliseconds
+ */
+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>;
+/**
+ * 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;
+
 /**
  * Name-correlation fragment classifier for the ν-aware state class graph
  * (NU-050, Route B). See the Rust/Java equivalents for the full contract.
@@ -362,6 +536,9 @@ declare class SmtVerifier {
     private readonly _budgetPlaces;
     private _environmentMode;
     private _timeoutMs;
+    private _certificateCheck;
+    private _counterexampleReplay;
+    private _semiflowInvariants;
     private _nuMaxClasses;
     private _fragmentMode;
     private readonly _carrierPlaces;
@@ -388,6 +565,49 @@ declare class SmtVerifier {
      */
     budgetPlaces(...places: Place<any>[]): this;
     timeout(ms: number): this;
+    /**
+     * Enables/disables the independent IC3 certificate check (default: enabled).
+     *
+     * When a proven verdict comes from the IC3/Spacer path on the flat count
+     * encoding, the synthesized inductive invariant is re-validated with a plain
+     * solver against the UNSTRENGTHENED step relation — VC1 (init), VC2
+     * (consecution), VC3 (safety) — so a Spacer or encoder defect cannot certify
+     * a false PROVEN. A certificate that fails validation downgrades the verdict
+     * to unknown. Structural proofs and the coloured ν-encoding are unaffected.
+     */
+    certificateCheck(enabled: boolean): this;
+    /**
+     * Enables/disables abstract counterexample replay (default: enabled).
+     *
+     * When a violated verdict comes from the flat count encoding, the decoded
+     * counterexample states (an order-free set — the derivation tree is walked in
+     * traversal order, not firing order) are re-executed TS-side against the
+     * abstract semantics the encoder emits (Lean's `fireA`, Basic.lean), searching
+     * for a firing order from M₀ to a property-violating marking. See
+     * `SmtVerificationResult.counterexampleConfirmed` for how each outcome lands.
+     */
+    counterexampleReplay(enabled: boolean): this;
+    /**
+     * Also hands the validated **P-semiflows** to the encoders as invariants
+     * (VER-007; default: disabled — the encoders then see only the null-space basis).
+     *
+     * Every validated semiflow is a conservation law in its own right (`y >= 0`,
+     * `y·C = 0`, `y·M0` exact, zero weight on every reset / consume-all place), and
+     * the Farkas enumeration returns the *minimal* laws of the net. The null-space
+     * basis the encoders get by default is one basis of many: elimination hands back
+     * mixed-sign rows (discarded as not semi-positive) or rows that fold a reset place
+     * into a chain whose other combinations avoid it (dropped by the H1 guard). On a
+     * net with a few reset arcs that can lose every law of the chains those arcs
+     * touch, and without them IC3 has to rediscover the conservation of each chain —
+     * on a ~100-place net it does not within any practical budget. With the semiflows
+     * in, the same reachability-safety queries close in about a second.
+     *
+     * Soundness is unchanged: the semiflows pass the same exact re-validation as the
+     * basis rows, the union is pure strengthening (`Semiflow.lean`,
+     * `semiflow_union_sound`), and the certificate check re-proves the strengthened
+     * invariant. Off by default so reports stay byte-equal.
+     */
+    semiflowInvariants(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
@@ -425,6 +645,16 @@ declare class SmtVerifier {
      * dead-letter-drain stalls the eager, priority-ordered executor never produces.
      */
     prioritySemantics(semantics: PrioritySemantics): this;
+    /**
+     * The SMT-LIB2 scripts {@link verify} would send to z3 for this configuration,
+     * without running a solver (VER-013 AC1): the HORN query (flat, or name-coloured
+     * when a declared budget puts the net on Route A's exact encoding) and, for the
+     * flat encoding, the certificate-check script built around
+     * {@link placeholderCertificate}. This is what the cross-language golden tests diff
+     * byte for byte. Route B, the structural pre-check and the unresolved-place
+     * refusal are bypassed: it is what Route A encodes.
+     */
+    encodeScripts(): EncodedScripts;
     /**
      * Runs the verification pipeline.
      *
@@ -452,104 +682,243 @@ declare class SmtVerifier {
      */
     private applyNuGuard;
 }
+/** The scripts {@link SmtVerifier.encodeScripts} reports. */
+interface EncodedScripts {
+    /** The HORN query, flat or name-coloured. */
+    readonly horn: string;
+    /** The certificate-check script around {@link placeholderCertificate}; `null` for the name-coloured encoding. */
+    readonly certificate: string | null;
+    /** Whether `horn` is the name-coloured encoding. */
+    readonly coloured: boolean;
+}
+/**
+ * `(define-fun Reachable ((x!0 Int) …) Bool true)`: the certificate stand-in the
+ * golden certificate scripts are built around (a real certificate is solver output
+ * and never part of a golden).
+ */
+declare function placeholderCertificate(placeCount: number): string;
 
 /**
- * Result of a Spacer query.
+ * @module spacer-runner
+ *
+ * Runs Z3 Spacer on a HORN script through one `z3` process (VER-013) and
+ * classifies the reply in verdict terms.
+ *
+ * HORN/Spacer convention (shared with the Rust and Java verifiers and corroborated
+ * by the certificate check): with the query `(assert (not Error))`, z3 prints `sat`
+ * when the property is PROVEN (an inductive invariant excluding every violating
+ * state exists) and `unsat` when it is VIOLATED (no such invariant; the refutation
+ * proof carries the counterexample states).
  */
+
+/** Result of a Spacer query. */
 type QueryResult = QueryProven | QueryViolated | QueryUnknown;
-/** Property proven: no reachable error state (UNSAT). */
+/** Property proven (z3 `sat`). */
 interface QueryProven {
     readonly type: 'proven';
+    /**
+     * The `(define-fun …)` block of the model, verbatim (the certificate the
+     * certificate checker re-validates), or `null` when no model printed.
+     */
     readonly invariantFormula: string | null;
-    readonly levelInvariants: readonly string[];
 }
-/** Counterexample found (SAT). The answer is the derivation tree. */
+/** Property violated (z3 `unsat`). */
 interface QueryViolated {
     readonly type: 'violated';
-    readonly answer: Expr | null;
+    /** The raw solver reply; the refutation proof in it is decoded by the counterexample decoder. */
+    readonly answer: string;
 }
-/** Solver could not determine (timeout, resource limit). */
+/** Solver could not determine (timeout, resource limit, transport failure). */
 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.
+ * Runs `smt2` with `fp.engine=spacer`. `phase` names the dump files (`horn` or
+ * `horn-coloured`).
  */
-declare function createSpacerRunner(timeoutMs: number): Promise<SpacerContext>;
+declare function runZ3Spacer(solver: Z3Solver, timeoutMs: number, smt2: string, phase: string): Promise<QueryResult>;
 
 /**
  * @module smt-encoder
  *
- * Encodes a flattened Petri net as Constrained Horn Clauses (CHC) for Z3's Spacer engine.
+ * Encodes a flattened Petri net as Constrained Horn Clauses (CHC) in SMT-LIB2 text
+ * for Z3's Spacer engine (VER-013).
  *
- * **CHC encoding strategy**: The net's state space is modeled as integer vectors
- * (one variable per place = token count). Three rule types:
+ * 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
+ * 1. **Init**: `(assert (Reachable M0))` — the initial marking is reachable
+ * 2. **Transition**: `Reachable(M') :- Reachable(M) ∧ enabled(M,t) ∧ fire(M,M',t) ∧
+ *    M' ≥ 0 ∧ invariants(M') ∧ env-bounds(M')` — one rule per flat transition, plus
+ *    one env-injection rule per injected environment place (VER-006)
+ * 3. **Error**: `Error :- Reachable(M) ∧ violation(M)`; `(assert (not Error))`, so
+ *    `sat` is PROVEN and `unsat` is VIOLATED
  *
- * Transition rules include: non-negativity constraints on M', P-invariant strengthening
- * clauses, and environment bounds for bounded analysis.
+ * 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,
+ * invariants in the order the verifier canonicalised.
+ */
+
+/** An encoded SMT-LIB2 script. */
+interface SmtEncoding {
+    /** The script text. */
+    readonly smt2: string;
+    /** The number of flat places (the arity of `Reachable` in the flat encoding). */
+    readonly placeCount: number;
+}
+/**
+ * Encodes the net and property as a HORN script.
  *
- * Z3 types are complex and partially untyped; the ctx/fp parameters use `any`.
+ * @param produceProofs emit `:produce-proofs` and `(get-proof)` so an `unsat` reply
+ *   carries the refutation the replay decodes
  */
+declare function encode(flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[], sinkPlaces?: ReadonlySet<Place<any>>, produceProofs?: boolean): 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
+ * every env-injection step (VER-006). This is the UNSTRENGTHENED relation the
+ * certificate check validates against: it shares the condition emitters with the CHC
+ * 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;
 
-/** 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.
+ * @module counterexample-decoder
+ *
+ * Decodes z3's refutation output into replayable counterexample material.
+ *
+ * There is exactly one decoder: {@link decodeStateSet}, which collects the ground
+ * `Reachable` facts of a `:produce-proofs` refutation into a SET. The ordered trace
+ * a caller sees is reconstructed from that set by the abstract replayer; the proof
+ * printer's traversal order is not a firing order and was never safe to read as one.
+ *
+ * Applications with non-ground arguments (rule bodies quantify `Reachable` over
+ * variables) or the wrong arity are skipped; a malformed proof simply yields a
+ * smaller (possibly empty) set, never a throw. Byte-for-byte mirror of the Rust
+ * `counterexample::decode_state_set`.
  */
-interface EncodingResult {
-    readonly errorExpr: Bool;
-    readonly reachableDecl: FuncDecl;
+
+/** Result of counterexample decoding. */
+interface DecodedTrace {
+    /**
+     * The ground `Reachable` markings of the proof as an order-free set (text order
+     * preserved for display), what the abstract replayer chains into a firing order.
+     */
+    readonly states: ReadonlySet<MarkingState>;
+    /** Why nothing was decoded; `null` when `states` is non-empty. */
+    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;
 /**
- * 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
+ * Collects the ground `Reachable(...)` applications from a z3 refutation proof into
+ * a state set, in text order.
  */
-declare function encode(ctx: Z3Context, fp: Z3Fixedpoint, flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[], sinkPlaces?: ReadonlySet<Place<any>>): EncodingResult;
+declare function decodeStateSet(answer: string, flatNet: FlatNet): ReadonlySet<MarkingState>;
 
 /**
- * Result of counterexample decoding.
+ * @module abstract-replayer
+ *
+ * Pure TS-side replayer for Spacer counterexamples over the ABSTRACT
+ * (untimed, value-blind) count-vector semantics — the exact semantics the CHC
+ * encoder emits and the Lean development verifies:
+ *
+ * - {@link enabledA} mirrors `lean/Libpetri/Basic.lean` `enabledA` and the
+ *   encoder's `encodeEnabled` arm (smt-encoder.ts): every input place holds at
+ *   least `pre[p]` tokens, every inhibited place is empty, every read place is
+ *   non-empty.
+ * - {@link fireA} mirrors `Basic.lean` `fireA` and the encoder's `encodeFire`
+ *   arm: a reset or consume-all (`All`/`AtLeast`) place jumps to `post[p]`;
+ *   every other place moves by `M[p] - pre[p] + post[p]`.
+ * - {@link successors} mirrors one disjunct of `encodeStepRelation`: a firing
+ *   is a successor only when its `M'` also respects `environmentBounds` (the
+ *   `envBounds(M')` conjunct every transition disjunct carries), and one
+ *   injection per modeled environment place whose guard admits it.
+ * - {@link injectA} mirrors `encodeInjectionFire`/`encodeInjectionGuard`
+ *   (VER-006): one environment injection adds one token to the env place,
+ *   gated by `M[p] < k` for `Bounded(k)` and unguarded for `AlwaysAvailable`.
+ * - {@link satisfiesBad} mirrors `encodePropertyViolation` — including the
+ *   relax-env deadlock enablement and the declared-sink exemption — as a
+ *   direct TS evaluator, so confirming a counterexample never needs a Z3 call.
+ *
+ * Because the abstraction over-approximates the concrete timed/valued net
+ * (VER-004), a decoded counterexample can be spurious. This module therefore
+ * only ever REPORTS an outcome ({@link ReplayOutcome}) — nothing here is
+ * allowed to certify by crashing, and only the `no-chain` outcome (a fully
+ * explored search that found no chain) is strong enough to withdraw a verdict.
  */
-interface DecodedTrace {
-    readonly trace: readonly MarkingState[];
-    readonly transitions: readonly string[];
+
+/** An abstract marking: token count per flat place index. */
+type AbstractState = readonly number[];
+/** One abstract step in a replayed chain. */
+type ReplayStep = {
+    readonly kind: 'fire';
+    readonly transition: string;
+} | {
+    readonly kind: 'inject';
+    readonly place: string;
+};
+/** Options for {@link replayCounterexample}. */
+interface ReplayOptions {
+    /** Max abstract steps searched between decoded anchors (default 3). */
+    readonly segmentBudget?: number;
+    /**
+     * Max search nodes ADMITTED to the whole search (default 10_000).
+     *
+     * A node is admitted when it survives the segment budget and the domination
+     * check; dominated successors are never admitted and never counted. The root
+     * (`M₀`) counts as the first admitted node, and the search stops as soon as
+     * `nodeBudget` nodes have been admitted and another one is due — the same
+     * `>=`-before-admission rule the Rust and Java replayers apply, so the same
+     * nominal budget means the same effective search depth in all of them.
+     */
+    readonly nodeBudget?: number;
 }
 /**
- * Decodes Z3 Spacer counterexample answers into Petri net marking traces.
+ * Outcome of an abstract replay attempt.
+ *
+ * `confirmed` — a genuine abstract chain `M₀ → … → Bad` was found.
+ * `no-chain` — the search ran to completion without truncation and no chain
+ * exists: the counterexample is spurious or the decoder mis-read the
+ * derivation, and ONLY this outcome may withdraw a `violated` verdict.
+ * `exhausted` — the search was cut short (node or segment budget, or `M₀` was
+ * not among the decoded states), so nothing was proved either way.
+ */
+type ReplayOutcome = {
+    readonly kind: 'confirmed';
+    /** The replayed chain in FIRING order, `M₀ … M_bad` inclusive. */
+    readonly states: readonly AbstractState[];
+    /** One step per consecutive pair of {@link states}. */
+    readonly steps: readonly ReplayStep[];
+    readonly nodesExplored: number;
+} | {
+    readonly kind: 'no-chain';
+    readonly nodesExplored: number;
+} | {
+    readonly kind: 'exhausted';
+    readonly reason: string;
+    readonly nodesExplored: number;
+};
+/**
+ * Attempts to re-execute a decoded (order-free) counterexample state set in
+ * the abstract semantics.
  *
- * 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.
+ * The decoder collects Spacer's `Reachable` applications in derivation
+ * TRAVERSAL order, which is not firing order; this search recovers a firing
+ * order or reports that none exists. It is a single global breadth-first
+ * search from `initial` over {@link successors}, where each node carries the
+ * number of steps taken since the last decoded state (`segment`, reset to 0
+ * whenever a decoded state is reached) and a node is expanded only while that
+ * counter is below `segmentBudget`. A state is re-entered only when reached
+ * with a strictly smaller segment counter (domination by `(state, segment)`),
+ * and the whole search shares one `nodeBudget` counting nodes ADMITTED to the
+ * search — non-dominated states only, the root included (see
+ * {@link ReplayOptions.nodeBudget}).
  */
-declare function decode(ctx: any, answer: Expr | null, flatNet: FlatNet): DecodedTrace;
+declare function replayCounterexample(flatNet: FlatNet, initial: AbstractState, decodedStates: readonly AbstractState[], property: SmtProperty, sinkPlaces: ReadonlySet<Place<any>>, options?: ReplayOptions): ReplayOutcome;
 
 /**
  * Difference Bound Matrix (DBM) for Time Petri Net state class analysis.
@@ -740,4 +1109,4 @@ declare class TimePetriNetAnalyzerBuilder {
     build(): TimePetriNetAnalyzer;
 }
 
-export { type EnvironmentAnalysisMode as AnalysisEnvironmentMode, type BranchEdge, DBM, type DecodedTrace, type EncodingResult, type EnvironmentAnalysisMode, type FlatNet, type FlatTransition, IncidenceMatrix, type LivenessResult, MarkingState, MarkingStateBuilder, PInvariant, type PrioritySemantics, type QueryProven, type QueryResult, type QueryUnknown, type QueryViolated, SmtProperty, SmtVerificationResult, SmtVerifier, type SpacerContext, StateClass, StateClassGraph, type StructuralCheckResult, TimePetriNetAnalyzer, TimePetriNetAnalyzerBuilder, type XorBranchAnalysis, type XorBranchInfo, alwaysAvailable, alwaysAvailable as analysisAlwaysAvailable, bounded as analysisBounded, ignore as analysisIgnore, bounded, computePInvariants, computePSemiflows, computeSCCs, createSpacerRunner, decode, encode, findMaximalTrapIn, findMinimalSiphons, findTerminalSCCs, flatNetIndexOf, flatNetPlaceCount, flatNetTransitionCount, flatTransition, flatten, ignore, isCoveredByInvariants, structuralCheck };
+export { type AbstractState, type EnvironmentAnalysisMode as AnalysisEnvironmentMode, type BranchEdge, type CertificateCheckOutcome, type CertificateVc, DBM, DUMP_ENV, type DecodedTrace, type EncodedScripts, type 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, alwaysAvailable, alwaysAvailable as analysisAlwaysAvailable, bounded as analysisBounded, ignore as analysisIgnore, bounded, canonicalInvariantOrder, checkCertificate, computePInvariants, computePSemiflows, computeSCCs, decode, decodeStateSet, encode, encodeStepRelationSmt2, findMaximalTrapIn, findMinimalSiphons, findTerminalSCCs, flatNetIndexOf, flatNetPlaceCount, flatNetTransitionCount, flatTransition, flatten, formatZ3Version, ignore, isCoveredByInvariants, parseZ3Version, placeholderCertificate, replayCounterexample, resolveZ3, runZ3Spacer, runZ3Text, strengthenWithSemiflows, structuralCheck, vcScript, z3Available, z3SolverAt };