libpetri 3.0.1 → 4.1.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 SmtProperty, aR as MarkingStateBuilder, aS as SmtVerificationResult } from '../petri-net-WSScMyDL.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-WSScMyDL.js';
-import { Expr, init, Bool, FuncDecl } from 'z3-solver';
+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';
 
 /**
  * A flattened transition with pre/post vectors for SMT encoding.
@@ -100,24 +99,6 @@ declare class IncidenceMatrix {
     numPlaces(): number;
 }
 
-/**
- * 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;
-
 /**
  * @module net-flattener
  *
@@ -182,22 +163,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,72 +253,129 @@ 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 re-validation of the inductive invariant Z3 Spacer synthesizes
- * for a `proven` verdict (the IC3 certificate).
- *
- * A "proven" answer from the Fixedpoint engine is only as trustworthy as Z3
- * plus the CHC encoder. This module re-checks the certificate with a plain
- * `ctx.Solver()` in the same Z3 WASM context, against the UNSTRENGTHENED step
- * relation ({@link encodeStepRelation} — no P-invariant conjuncts), so even a
- * wrong-but-validated-looking invariant strengthening can never smuggle a
- * false PROVEN through. Three validity conditions, each expected UNSAT:
- *
- * 1. **VC1 (init)**: `¬I(M₀)` — the initial marking satisfies the invariant
- * 2. **VC2 (consecution)**: `I(M) ∧ M ≥ 0 ∧ T(M,M') ∧ ¬I(M')` — the invariant
- *    is inductive under the unstrengthened step relation
- * 3. **VC3 (safety)**: `I(M) ∧ M ≥ 0 ∧ Bad(M)` — the invariant excludes every
- *    property-violating marking
- *
- * The `M ≥ 0` domain conjunct in VC2/VC3 is sound: the net's state space is
- * ℕ^P (the initial marking is non-negative, transition steps constrain
- * `M' ≥ 0`, and injection steps only increment), so restricting the check to
- * ℕ^P checks exactly the states the system can inhabit — while the invariant
- * itself is only required to over-approximate `Reachable`, which never leaves
- * ℕ^P either.
- *
- * **Answer AST shapes** (`fp.getAnswer()` after an UNSAT query): typically a
- * top-level `and` of one definition per relation, where the `Reachable`
- * definition is `forall vars. Reachable(vars) = φ` (equivalence; `iff` and the
- * over-approximating `Reachable(vars) => φ` are accepted too). A ground
- * (unquantified) `Reachable(args) = φ` definition is handled as well. Inside a
- * `forall` the arguments of the `Reachable` application are de Bruijn
- * variables; argument position `j` names place `j`, and `ctx.substituteVars`
- * maps de Bruijn index `i` to its `to[i]` — the mapping is built from
- * `getVarIndex` per argument, so any bound-variable order is handled.
- *
- * **Candidate certificate**: Spacer synthesizes its invariant against CHC
- * bodies that conjoin the exactly-validated P-invariants, so the plain answer
- * `I` is often inductive only RELATIVE to that strengthening (e.g. `¬(B ≥ 2)`
- * relying on `A + B = 1` — bare consecution fails). The checked candidate is
- * therefore `R' := I ∧ (y·M = y·M₀ for each validated P-invariant)`, with all
- * three VCs proven for `R'` from scratch against the same unstrengthened step
- * relation (the design shared with the Rust and Java checkers). The
- * strengthening is verified, never assumed: a poisoned P-invariant fails VC1
- * (wrong constant) or VC2 (wrong weights) of `R'` and the verdict downgrades,
- * while a genuine strengthening-dependent certificate passes.
- *
- * 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
- * unparseable answer, solver error). Both withhold PROVEN; neither throws.
+ * 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.
  */
 
-/** Z3 high-level context. Typed as `any` because z3-solver's TS types are incomplete. */
-type Z3Context$1 = any;
 /** 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/unparseable answer, solver
- * error), so no VC is implicated.
+ * `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.
  */
@@ -342,20 +393,27 @@ type CertificateCheckOutcome = {
     readonly invariant: string | null;
 };
 /**
- * Re-validates the IC3 certificate for a proven flat-encoding verdict.
+ * Re-verifies an extracted proof certificate against the unstrengthened step relation.
  *
- * @param ctx the Z3 high-level context the answer was produced in
- * @param answer the raw `fp.getAnswer()` AST (null when Z3 produced none)
+ * @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)
+ *   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 timeoutMs per-VC solver timeout in milliseconds
+ * @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 checkCertificate(ctx: Z3Context$1, answer: Expr | null, flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[], sinkPlaces: ReadonlySet<Place<any>>, timeoutMs: number): Promise<CertificateCheckOutcome>;
+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
@@ -428,29 +486,6 @@ type FragmentMode = 'base' | 'extended';
  */
 type PrioritySemantics = 'none' | 'conflict';
 
-/**
- * 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)
- * - Input specifications are purely structural (IO-006) — there is no per-arc
- *   predicate for the encoder to be blind to
- * - If a counterexample is found, it may be spurious in timed 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;
@@ -462,6 +497,7 @@ declare class SmtVerifier {
     private _timeoutMs;
     private _certificateCheck;
     private _counterexampleReplay;
+    private _semiflowInvariants;
     private _nuMaxClasses;
     private _fragmentMode;
     private readonly _carrierPlaces;
@@ -510,6 +546,40 @@ declare class SmtVerifier {
      * `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.
+     *
+     * **Turn this on if the net has any `all()` / `atLeast(n)` or reset arc on a busy
+     * place** — draining an input queue is the everyday case. Every basis row whose
+     * support touches such a place fails the H1 guard and is dropped, so the encoders
+     * run on a deficient invariant set and nothing in the report says a law is missing
+     * beyond the `Dropped` lines.
+     *
+     * This reaches the **name-coloured** encoder (NU-050) as well as the flat one, and
+     * it matters most there. On a 113-place ν-net, whole-net deadlock-freedom went from
+     * `unknown` after 50 minutes to `proven` in about 15 seconds with this option as the
+     * only change; on the flat path, reachability-safety queries that timed out at 120 s
+     * 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 — that check is flat-path only, so a coloured `proven` reports
+     * `Certificate check: not applicable (name-coloured encoding)`. 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
@@ -547,6 +617,33 @@ declare class SmtVerifier {
      * dead-letter-drain stalls the eager, priority-ordered executor never produces.
      */
     prioritySemantics(semantics: PrioritySemantics): this;
+    /**
+     * The name-coloured plan and its encoding, or a null plan when the net is outside
+     * the fragment (NU-050) and a null encoding when the property names a place the net
+     * does not resolve.
+     *
+     * {@link verify} and {@link encodeScripts} share this deliberately. They used to
+     * invoke `buildColouredPlan` and `encodeColoured` separately, so handing the encoder
+     * the wrong one of the two lists changed only one of them — and the script-parity
+     * goldens are generated from `encodeScripts`. Unifying the invocation closes that. It
+     * does not make the two paths identical: each still computes its own invariant and
+     * semiflow lists, so they can still drift through the arguments rather than the call.
+     *
+     * `invariants` is what the encoder conjoins into every rule body (the null-space
+     * basis, unioned with the semiflows when VER-007 is enabled); `semiflows` sets the
+     * colour-slot bound k (NU-053). They are not the same list.
+     */
+    private colouredAttempt;
+    /**
+     * 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.
      *
@@ -574,146 +671,142 @@ 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';
-    readonly invariantFormula: string | null;
-    readonly levelInvariants: readonly string[];
     /**
-     * The raw `fp.getAnswer()` AST backing {@link invariantFormula} — the
-     * IC3-synthesized inductive invariant as a Z3 expression in the runner's
-     * context. Consumed by the certificate checker; `null` when the solver
-     * configuration produced no answer.
+     * The `(define-fun …)` block of the model, verbatim (the certificate the
+     * certificate checker re-validates), or `null` when no model printed.
      */
-    readonly answer: Expr | null;
+    readonly invariantFormula: string | null;
 }
-/** 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.
- *
- * **CHC encoding strategy**: The net's state space is modeled as integer vectors
- * (one variable per place = token count). Three rule types:
+ * Encodes a flattened Petri net as Constrained Horn Clauses (CHC) in SMT-LIB2 text
+ * for Z3's Spacer engine (VER-013).
  *
- * 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
+ * The net's state space is modeled as integer vectors (one variable per place = token
+ * count). Three rule types:
  *
- * Transition rules include: non-negativity constraints on M', P-invariant strengthening
- * clauses, and environment bounds for bounded analysis.
+ * 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
  *
- * Z3 types are complex and partially untyped; the ctx/fp parameters use `any`.
+ * 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.
  */
 
-/** 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;
+/** 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 a flattened Petri net as Constrained Horn Clauses (CHC) for Z3's Spacer engine.
+ * Encodes the net and property as a HORN script.
  *
- * 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
+ * @param produceProofs emit `:produce-proofs` and `(get-proof)` so an `unsat` reply
+ *   carries the refutation the replay decodes
  */
-declare function encode(ctx: Z3Context, fp: Z3Fixedpoint, flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[], sinkPlaces?: ReadonlySet<Place<any>>): EncodingResult;
-
+declare function encode(flatNet: FlatNet, initialMarking: MarkingState, property: SmtProperty, invariants: readonly PInvariant[], sinkPlaces?: ReadonlySet<Place<any>>, produceProofs?: boolean): SmtEncoding;
 /**
- * Structured reason why decoding degraded (never thrown — decoding a
- * counterexample must not crash a violated verdict).
+ * 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.
  */
-type DecodeFailure = {
-    readonly kind: 'no-answer';
-} | {
-    readonly kind: 'traversal-error';
-    readonly message: string;
-} | {
-    readonly kind: 'non-concrete';
-    readonly skipped: number;
-};
-/** Human-readable form of a {@link DecodeFailure} (or of a clean-but-empty walk). */
-declare function describeDecodeFailure(failure: DecodeFailure | null): string;
+declare function encodeStepRelationSmt2(flatNet: FlatNet): string;
+
 /**
- * Result of counterexample decoding.
+ * @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`.
  */
+
+/** Result of counterexample decoding. */
 interface DecodedTrace {
     /**
-     * Reachable states in derivation-TRAVERSAL order — NOT firing order (the
-     * derivation tree is walked recursively, so display order is fragile).
-     * May contain duplicates. Kept for raw reporting; the replayer consumes
-     * {@link states} instead.
-     */
-    readonly trace: readonly MarkingState[];
-    /** Rule names encountered during the walk (same traversal-order caveat). */
-    readonly transitions: readonly string[];
-    /**
-     * The decoded Reachable states as an order-free SET, deduplicated by
-     * marking. This is the shape the abstract replayer chains into firing order.
+     * 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>;
-    /**
-     * Structured reason when decoding degraded (partial results are still
-     * returned); `null` when the walk completed cleanly.
-     */
-    readonly failure: DecodeFailure | null;
+    /** 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;
 /**
- * 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 `Reachable` application. The derivation is
- * walked in TRAVERSAL order, so `trace` is not a firing sequence; `states`
- * carries the same markings as an order-free set for the abstract replayer
- * to chain. Failures degrade gracefully and are surfaced via `failure`.
+ * Collects the ground `Reachable(...)` applications from a z3 refutation proof into
+ * a state set, in text order.
  */
-declare function decode(ctx: any, answer: Expr | null, flatNet: FlatNet): DecodedTrace;
+declare function decodeStateSet(answer: string, flatNet: FlatNet): ReadonlySet<MarkingState>;
 
 /**
  * @module abstract-replayer
@@ -1005,4 +1098,4 @@ declare class TimePetriNetAnalyzerBuilder {
     build(): TimePetriNetAnalyzer;
 }
 
-export { type AbstractState, type EnvironmentAnalysisMode as AnalysisEnvironmentMode, type BranchEdge, type CertificateCheckOutcome, type CertificateVc, DBM, type DecodeFailure, 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, type ReplayOptions, type ReplayOutcome, type ReplayStep, 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, checkCertificate, computePInvariants, computePSemiflows, computeSCCs, createSpacerRunner, decode, describeDecodeFailure, encode, findMaximalTrapIn, findMinimalSiphons, findTerminalSCCs, flatNetIndexOf, flatNetPlaceCount, flatNetTransitionCount, flatTransition, flatten, ignore, isCoveredByInvariants, replayCounterexample, structuralCheck };
+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 };