@vauban-org/agent-sdk 0.17.4 → 1.2.0

package/dist/verify/formal/policy.d.ts

@@ -0,0 +1,105 @@
+/**
+ * src/verify/formal/policy.ts
+ *
+ * Sprint-587 — Per-axiom policy + consumer mode resolution.
+ *
+ * The policy layer maps a 4-state {@link FormalVerifyResult} to an action
+ * (proceed / block / escalate / log), parameterised by :
+ *   - the axiom (Robuste, Institutionnel, … — each has different sensitivity)
+ *   - the consumer mode (strict / permissive / audit_only)
+ *   - the calling context (runtime vs skill_ingestion — see Tension Sprint C)
+ *
+ * Tension Sprint C : skill-loop ingestion is ALWAYS strict on UNKNOWN.
+ * Even if the runtime policy says "proceed_with_log" on UNKNOWN for the
+ * Profitable axiom, the skill-ingestion path must refuse to ingest the
+ * skill until UNKNOWN becomes SAFE. This prevents UNKNOWN-tainted skills
+ * from accumulating in the skill library.
+ *
+ * @module verify/formal/policy
+ */
+import type { FormalVerifyResult } from "./result.js";
+/**
+ * Action chosen by the policy resolver.
+ *
+ *   `proceed`        : continue without intervention
+ *   `block`          : refuse the operation outright
+ *   `escalate_human` : pause and request human approval (HITL)
+ *   `log`            : continue but emit an audit-grade log entry
+ */
+export type PolicyAction = "proceed" | "block" | "escalate_human" | "log";
+/**
+ * Strategy for handling UNKNOWN outcomes.
+ *
+ *   `escalate_human`        : refuse to make a unilateral decision
+ *   `proceed_with_log`      : continue and emit a regular log entry
+ *   `proceed_with_audit_log`: continue and emit an audit-grade log entry
+ */
+export type OnUnknown = "escalate_human" | "proceed_with_log" | "proceed_with_audit_log";
+/**
+ * Strategy for handling UNSAFE outcomes — either hard-block or escalate.
+ */
+export type OnUnsafe = "block" | "escalate_human";
+/**
+ * Policy bundle for one axiom.
+ *
+ * `skillLoopStrict` is ALWAYS true by design : it is exposed as a field so
+ * downstream code can read it but is not configurable (see Tension Sprint C).
+ */
+export interface AxiomPolicy {
+    /** Action on SAFE. Fixed at `"proceed"` — kept explicit for symmetry. */
+    onSafe: "proceed";
+    /** Action on UNSAFE. */
+    onUnsafe: OnUnsafe;
+    /** Action on UNKNOWN. */
+    onUnknown: OnUnknown;
+    /** Solver timeout for this axiom, in milliseconds. */
+    timeout_ms: number;
+    /**
+     * Skill-loop ingestion strict mode — always true. Exposed so callers can
+     * assert the invariant. Do not set to false ; Tension Sprint C invariant.
+     */
+    skillLoopStrict: boolean;
+}
+/**
+ * Default per-axiom policies.
+ *
+ * Rationale :
+ *   Robuste / Institutionnel : hard axioms — UNSAFE blocks, UNKNOWN escalates
+ *   SOTA                     : UNKNOWN allowed with audit log (SOTA evolves)
+ *   AntiFragile / Profitable : softer — UNSAFE escalates, UNKNOWN logs
+ */
+export declare const DEFAULT_POLICIES: Record<string, AxiomPolicy>;
+/**
+ * Consumer-level mode for the formal verifier.
+ *
+ *   `strict`     : enforce all policies as declared
+ *   `permissive` : downgrade non-critical UNSAFE to log (Robuste/Institutionnel
+ *                  remain enforced), and treat UNKNOWN as SKIPPED
+ *   `audit_only` : never block ; map every actionable outcome to `log`
+ */
+export type ConsumerMode = "strict" | "permissive" | "audit_only";
+/**
+ * Calling context — distinguishes between live runtime verification and
+ * skill-loop ingestion. The latter has stricter rules on UNKNOWN.
+ */
+export type VerifyContext = "runtime" | "skill_ingestion";
+/**
+ * Resolution outcome of {@link applyPolicy}.
+ */
+export interface PolicyDecision {
+    action: PolicyAction;
+    rationale: string;
+}
+/**
+ * Apply the policy + mode + context to a single verification result.
+ *
+ * Decision order :
+ *   1. SKIPPED                                        → log
+ *   2. skill_ingestion + UNKNOWN                      → block  (Tension Sprint C)
+ *   3. mode = audit_only                              → log
+ *   4. mode = permissive + UNKNOWN                    → log    (treated as SKIPPED)
+ *   5. mode = permissive + UNSAFE + non-hard axiom    → log
+ *   6. otherwise                                      → policy.on{Safe,Unsafe,Unknown}
+ */
+export declare function applyPolicy(result: FormalVerifyResult, policy: AxiomPolicy, mode: ConsumerMode, context: VerifyContext): PolicyDecision;
+//# sourceMappingURL=policy.d.ts.map

package/dist/verify/formal/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../../src/verify/formal/policy.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,aAAa,CAAC;AAEtD;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,SAAS,GAAG,OAAO,GAAG,gBAAgB,GAAG,KAAK,CAAC;AAE1E;;;;;;GAMG;AACH,MAAM,MAAM,SAAS,GACjB,gBAAgB,GAChB,kBAAkB,GAClB,wBAAwB,CAAC;AAE7B;;GAEG;AACH,MAAM,MAAM,QAAQ,GAAG,OAAO,GAAG,gBAAgB,CAAC;AAElD;;;;;GAKG;AACH,MAAM,WAAW,WAAW;IAC1B,yEAAyE;IACzE,MAAM,EAAE,SAAS,CAAC;IAClB,wBAAwB;IACxB,QAAQ,EAAE,QAAQ,CAAC;IACnB,yBAAyB;IACzB,SAAS,EAAE,SAAS,CAAC;IACrB,sDAAsD;IACtD,UAAU,EAAE,MAAM,CAAC;IACnB;;;OAGG;IACH,eAAe,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;GAOG;AACH,eAAO,MAAM,gBAAgB,EAAE,MAAM,CAAC,MAAM,EAAE,WAAW,CAoCxD,CAAC;AAEF;;;;;;;GAOG;AACH,MAAM,MAAM,YAAY,GAAG,QAAQ,GAAG,YAAY,GAAG,YAAY,CAAC;AAElE;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG,SAAS,GAAG,iBAAiB,CAAC;AAE1D;;GAEG;AACH,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,YAAY,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CACnB;AAUD;;;;;;;;;;GAUG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,kBAAkB,EAC1B,MAAM,EAAE,WAAW,EACnB,IAAI,EAAE,YAAY,EAClB,OAAO,EAAE,aAAa,GACrB,cAAc,CAuFhB"}

package/dist/verify/formal/policy.js

@@ -0,0 +1,159 @@
+/**
+ * src/verify/formal/policy.ts
+ *
+ * Sprint-587 — Per-axiom policy + consumer mode resolution.
+ *
+ * The policy layer maps a 4-state {@link FormalVerifyResult} to an action
+ * (proceed / block / escalate / log), parameterised by :
+ *   - the axiom (Robuste, Institutionnel, … — each has different sensitivity)
+ *   - the consumer mode (strict / permissive / audit_only)
+ *   - the calling context (runtime vs skill_ingestion — see Tension Sprint C)
+ *
+ * Tension Sprint C : skill-loop ingestion is ALWAYS strict on UNKNOWN.
+ * Even if the runtime policy says "proceed_with_log" on UNKNOWN for the
+ * Profitable axiom, the skill-ingestion path must refuse to ingest the
+ * skill until UNKNOWN becomes SAFE. This prevents UNKNOWN-tainted skills
+ * from accumulating in the skill library.
+ *
+ * @module verify/formal/policy
+ */
+/**
+ * Default per-axiom policies.
+ *
+ * Rationale :
+ *   Robuste / Institutionnel : hard axioms — UNSAFE blocks, UNKNOWN escalates
+ *   SOTA                     : UNKNOWN allowed with audit log (SOTA evolves)
+ *   AntiFragile / Profitable : softer — UNSAFE escalates, UNKNOWN logs
+ */
+export const DEFAULT_POLICIES = {
+    Robuste: {
+        onSafe: "proceed",
+        onUnsafe: "block",
+        onUnknown: "escalate_human",
+        timeout_ms: 5000,
+        skillLoopStrict: true,
+    },
+    Institutionnel: {
+        onSafe: "proceed",
+        onUnsafe: "block",
+        onUnknown: "escalate_human",
+        timeout_ms: 10_000,
+        skillLoopStrict: true,
+    },
+    SOTA: {
+        onSafe: "proceed",
+        onUnsafe: "escalate_human",
+        onUnknown: "proceed_with_audit_log",
+        timeout_ms: 2000,
+        skillLoopStrict: true,
+    },
+    AntiFragile: {
+        onSafe: "proceed",
+        onUnsafe: "escalate_human",
+        onUnknown: "proceed_with_log",
+        timeout_ms: 1000,
+        skillLoopStrict: true,
+    },
+    Profitable: {
+        onSafe: "proceed",
+        onUnsafe: "escalate_human",
+        onUnknown: "proceed_with_log",
+        timeout_ms: 1000,
+        skillLoopStrict: true,
+    },
+};
+/**
+ * Whether an axiom is in the "hard" set (Robuste, Institutionnel) whose
+ * UNSAFE outcomes are non-negotiable.
+ */
+function isHardAxiom(axiom) {
+    return axiom === "Robuste" || axiom === "Institutionnel";
+}
+/**
+ * Apply the policy + mode + context to a single verification result.
+ *
+ * Decision order :
+ *   1. SKIPPED                                        → log
+ *   2. skill_ingestion + UNKNOWN                      → block  (Tension Sprint C)
+ *   3. mode = audit_only                              → log
+ *   4. mode = permissive + UNKNOWN                    → log    (treated as SKIPPED)
+ *   5. mode = permissive + UNSAFE + non-hard axiom    → log
+ *   6. otherwise                                      → policy.on{Safe,Unsafe,Unknown}
+ */
+export function applyPolicy(result, policy, mode, context) {
+    // 1. SKIPPED → log
+    if (result.state === "SKIPPED") {
+        return {
+            action: "log",
+            rationale: `Axiom ${result.axiom} verification was skipped (${result.rationale})`,
+        };
+    }
+    // 2. Tension Sprint C : skill_ingestion + UNKNOWN → block, always.
+    if (context === "skill_ingestion" && result.state === "UNKNOWN") {
+        return {
+            action: "block",
+            rationale: `Skill ingestion refuses UNKNOWN on axiom ${result.axiom} ` +
+                `(Tension Sprint C : skill-loop is always strict on UNKNOWN)`,
+        };
+    }
+    // 3. audit_only never blocks.
+    if (mode === "audit_only") {
+        return {
+            action: "log",
+            rationale: `audit_only mode : axiom ${result.axiom} = ${result.state}`,
+        };
+    }
+    // SAFE is always proceed.
+    if (result.state === "SAFE") {
+        return {
+            action: "proceed",
+            rationale: `Axiom ${result.axiom} proved SAFE in ${result.time_ms.toFixed(0)}ms`,
+        };
+    }
+    // 4 + 5. Permissive softening.
+    if (mode === "permissive") {
+        if (result.state === "UNKNOWN") {
+            return {
+                action: "log",
+                rationale: `permissive mode : UNKNOWN on axiom ${result.axiom} treated as ` +
+                    `non-blocking (${result.rationale})`,
+            };
+        }
+        if (result.state === "UNSAFE" && !isHardAxiom(result.axiom)) {
+            return {
+                action: "log",
+                rationale: `permissive mode : UNSAFE on soft axiom ${result.axiom} downgraded ` +
+                    `to log (${result.rationale})`,
+            };
+        }
+        // UNSAFE on hard axiom : fall through to strict policy.
+    }
+    // 6. Strict policy resolution.
+    if (result.state === "UNSAFE") {
+        return {
+            action: policy.onUnsafe,
+            rationale: `UNSAFE on axiom ${result.axiom} : ${policy.onUnsafe} ` +
+                `(counterexample : ${result.counterexample ?? "n/a"})`,
+        };
+    }
+    // result.state === "UNKNOWN" (runtime context only)
+    switch (policy.onUnknown) {
+        case "escalate_human":
+            return {
+                action: "escalate_human",
+                rationale: `UNKNOWN on axiom ${result.axiom} : escalating (${result.rationale})`,
+            };
+        case "proceed_with_audit_log":
+            return {
+                action: "log",
+                rationale: `UNKNOWN on axiom ${result.axiom} : audit-log proceed (${result.rationale})`,
+            };
+        case "proceed_with_log":
+        default:
+            return {
+                action: "log",
+                rationale: `UNKNOWN on axiom ${result.axiom} : log-proceed (${result.rationale})`,
+            };
+    }
+}
+//# sourceMappingURL=policy.js.map

package/dist/verify/formal/policy.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.js","sourceRoot":"","sources":["../../../src/verify/formal/policy.ts"],"names":[],"mappings":"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"}

package/dist/verify/formal/result.d.ts

@@ -0,0 +1,50 @@
+/**
+ * src/verify/formal/result.ts
+ *
+ * Sprint-587 — Z3 formal verification result type.
+ *
+ * 4-state result discipline:
+ *   - SAFE     : Z3 proved the post-conditions hold under pre-conditions
+ *   - UNSAFE   : Z3 found a counterexample (state where pre-conditions hold
+ *                but post-conditions are violated)
+ *   - UNKNOWN  : Z3 returned `unknown` (timeout, undecidable, or solver
+ *                limitation). EXPLICIT — never silently treated as SAFE.
+ *   - SKIPPED  : Verification not run (consumer mode = permissive opt-out,
+ *                or solver binary unavailable when caller chooses to skip)
+ *
+ * The distinction between UNKNOWN and SAFE is the core epistemic discipline
+ * of this module : we never assert proof when none was produced.
+ *
+ * @module verify/formal/result
+ */
+/**
+ * Discriminated state of a formal verification attempt.
+ */
+export type FormalVerifyState = "SAFE" | "UNSAFE" | "UNKNOWN" | "SKIPPED";
+/**
+ * Solver backend identifier — currently only Z3 or `none` (no solver).
+ */
+export type FormalSolver = "z3" | "none";
+/**
+ * Result of running a single axiom spec through the formal verifier.
+ *
+ * `state`           : 4-state outcome (see {@link FormalVerifyState})
+ * `axiom`           : human-readable axiom label (e.g. "Robuste")
+ * `rationale`       : human-readable explanation of the outcome
+ * `witness`         : when SAFE, optional UNSAT-core or proof witness string
+ *                     emitted by the solver (informational only)
+ * `counterexample`  : when UNSAFE, SMT model (variable assignment) that
+ *                     violates the post-conditions
+ * `time_ms`         : wall-clock time spent in the solver, in milliseconds
+ * `solver`          : which backend produced the result
+ */
+export interface FormalVerifyResult {
+    state: FormalVerifyState;
+    axiom: string;
+    rationale: string;
+    witness?: string;
+    counterexample?: string;
+    time_ms: number;
+    solver: FormalSolver;
+}
+//# sourceMappingURL=result.d.ts.map

package/dist/verify/formal/result.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.d.ts","sourceRoot":"","sources":["../../../src/verify/formal/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG;AAEH;;GAEG;AACH,MAAM,MAAM,iBAAiB,GAAG,MAAM,GAAG,QAAQ,GAAG,SAAS,GAAG,SAAS,CAAC;AAE1E;;GAEG;AACH,MAAM,MAAM,YAAY,GAAG,IAAI,GAAG,MAAM,CAAC;AAEzC;;;;;;;;;;;;GAYG;AACH,MAAM,WAAW,kBAAkB;IACjC,KAAK,EAAE,iBAAiB,CAAC;IACzB,KAAK,EAAE,MAAM,CAAC;IACd,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,YAAY,CAAC;CACtB"}

package/dist/verify/formal/result.js

@@ -0,0 +1,21 @@
+/**
+ * src/verify/formal/result.ts
+ *
+ * Sprint-587 — Z3 formal verification result type.
+ *
+ * 4-state result discipline:
+ *   - SAFE     : Z3 proved the post-conditions hold under pre-conditions
+ *   - UNSAFE   : Z3 found a counterexample (state where pre-conditions hold
+ *                but post-conditions are violated)
+ *   - UNKNOWN  : Z3 returned `unknown` (timeout, undecidable, or solver
+ *                limitation). EXPLICIT — never silently treated as SAFE.
+ *   - SKIPPED  : Verification not run (consumer mode = permissive opt-out,
+ *                or solver binary unavailable when caller chooses to skip)
+ *
+ * The distinction between UNKNOWN and SAFE is the core epistemic discipline
+ * of this module : we never assert proof when none was produced.
+ *
+ * @module verify/formal/result
+ */
+export {};
+//# sourceMappingURL=result.js.map

package/dist/verify/formal/result.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"result.js","sourceRoot":"","sources":["../../../src/verify/formal/result.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;GAkBG"}

package/dist/verify/formal/solver.d.ts

@@ -0,0 +1,67 @@
+/**
+ * src/verify/formal/solver.ts
+ *
+ * Sprint-587 — Z3 SMT solver wrapper.
+ *
+ * Strategy : avoid adding `z3-solver` as a hard npm dependency (heavy WASM
+ * package, ~5MB) by spawning the `z3` binary as a subprocess and piping
+ * SMT-LIB v2 source on stdin. If `z3` is not in PATH, the wrapper degrades
+ * gracefully by returning `{ sat: null }` so callers can map that to the
+ * UNKNOWN state.
+ *
+ * This keeps the SDK lean : consumers that want formal verification install
+ * `z3` system-wide (apt / brew / scoop). Consumers that do not, get UNKNOWN
+ * results and can route them according to their policy.
+ *
+ * @module verify/formal/solver
+ */
+/**
+ * Options accepted by {@link checkSmt}.
+ */
+export interface SolverOptions {
+    /** Wall-clock timeout in milliseconds. Defaults to 5000ms. */
+    timeout_ms?: number;
+    /** Optional path to the z3 binary (defaults to `z3` resolved via PATH). */
+    z3_path?: string;
+}
+/**
+ * Outcome of a single SMT-LIB check-sat invocation.
+ *
+ * `sat`     : `true`  → solver returned `sat` (formula is satisfiable, i.e.
+ *                       a counterexample exists for a violation query)
+ *             `false` → solver returned `unsat` (no counterexample, the
+ *                       property holds)
+ *             `null`  → solver returned `unknown`, timed out, was not
+ *                       installed, or failed to run
+ * `model`   : when `sat === true`, the textual SMT-LIB model string emitted
+ *             by `(get-model)` — useful as a counterexample witness
+ * `time_ms` : wall-clock time spent waiting on the solver subprocess
+ * `reason`  : optional human-readable diagnostic for UNKNOWN / null outcomes
+ */
+export interface SmtCheckResult {
+    sat: boolean | null;
+    model?: string;
+    time_ms: number;
+    reason?: string;
+}
+/**
+ * Run a single SMT-LIB v2 formula through Z3 and return the satisfiability
+ * outcome.
+ *
+ * Convention : the caller frames the property as a NEGATION (i.e. asserts the
+ * conjunction of preconditions AND the negation of the postcondition). Then :
+ *   - `sat`   → counterexample found → property VIOLATED → UNSAFE
+ *   - `unsat` → no counterexample exists → property HOLDS → SAFE
+ *   - `unknown` / timeout / missing binary → UNKNOWN
+ *
+ * The function never throws : transport errors and missing binaries are
+ * surfaced via `sat: null` with a `reason` string.
+ */
+export declare function checkSmt(smtFormula: string, options?: SolverOptions): Promise<SmtCheckResult>;
+export declare function isZ3Available(z3Path?: string): Promise<boolean>;
+/**
+ * Test-only helper to reset the cached availability probe.
+ * @internal
+ */
+export declare function __resetZ3AvailabilityCache(): void;
+//# sourceMappingURL=solver.d.ts.map

package/dist/verify/formal/solver.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"solver.d.ts","sourceRoot":"","sources":["../../../src/verify/formal/solver.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;GAgBG;AAKH;;GAEG;AACH,MAAM,WAAW,aAAa;IAC5B,8DAA8D;IAC9D,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;;GAaG;AACH,MAAM,WAAW,cAAc;IAC7B,GAAG,EAAE,OAAO,GAAG,IAAI,CAAC;IACpB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;CACjB;AAID;;;;;;;;;;;;GAYG;AACH,wBAAsB,QAAQ,CAC5B,UAAU,EAAE,MAAM,EAClB,OAAO,GAAE,aAAkB,GAC1B,OAAO,CAAC,cAAc,CAAC,CAmHzB;AAWD,wBAAsB,aAAa,CAAC,MAAM,SAAO,GAAG,OAAO,CAAC,OAAO,CAAC,CA8BnE;AAED;;;GAGG;AACH,wBAAgB,0BAA0B,IAAI,IAAI,CAEjD"}

package/dist/verify/formal/solver.js

@@ -0,0 +1,184 @@
+/**
+ * src/verify/formal/solver.ts
+ *
+ * Sprint-587 — Z3 SMT solver wrapper.
+ *
+ * Strategy : avoid adding `z3-solver` as a hard npm dependency (heavy WASM
+ * package, ~5MB) by spawning the `z3` binary as a subprocess and piping
+ * SMT-LIB v2 source on stdin. If `z3` is not in PATH, the wrapper degrades
+ * gracefully by returning `{ sat: null }` so callers can map that to the
+ * UNKNOWN state.
+ *
+ * This keeps the SDK lean : consumers that want formal verification install
+ * `z3` system-wide (apt / brew / scoop). Consumers that do not, get UNKNOWN
+ * results and can route them according to their policy.
+ *
+ * @module verify/formal/solver
+ */
+import { spawn } from "node:child_process";
+import { performance } from "node:perf_hooks";
+const DEFAULT_TIMEOUT_MS = 5000;
+/**
+ * Run a single SMT-LIB v2 formula through Z3 and return the satisfiability
+ * outcome.
+ *
+ * Convention : the caller frames the property as a NEGATION (i.e. asserts the
+ * conjunction of preconditions AND the negation of the postcondition). Then :
+ *   - `sat`   → counterexample found → property VIOLATED → UNSAFE
+ *   - `unsat` → no counterexample exists → property HOLDS → SAFE
+ *   - `unknown` / timeout / missing binary → UNKNOWN
+ *
+ * The function never throws : transport errors and missing binaries are
+ * surfaced via `sat: null` with a `reason` string.
+ */
+export async function checkSmt(smtFormula, options = {}) {
+    const timeoutMs = options.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+    const z3Path = options.z3_path ?? "z3";
+    const start = performance.now();
+    return new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(z3Path, ["-in", `-T:${Math.ceil(timeoutMs / 1000)}`], {
+                stdio: ["pipe", "pipe", "pipe"],
+            });
+        }
+        catch (err) {
+            resolve({
+                sat: null,
+                time_ms: performance.now() - start,
+                reason: `z3 spawn failed : ${err instanceof Error ? err.message : String(err)}`,
+            });
+            return;
+        }
+        let stdout = "";
+        let stderr = "";
+        let settled = false;
+        const settle = (r) => {
+            if (settled)
+                return;
+            settled = true;
+            resolve(r);
+        };
+        const timer = setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* ignored */
+            }
+            settle({
+                sat: null,
+                time_ms: performance.now() - start,
+                reason: `z3 timeout after ${timeoutMs}ms`,
+            });
+        }, timeoutMs);
+        child.stdout.on("data", (chunk) => {
+            stdout += chunk.toString();
+        });
+        child.stderr.on("data", (chunk) => {
+            stderr += chunk.toString();
+        });
+        child.on("error", (err) => {
+            clearTimeout(timer);
+            settle({
+                sat: null,
+                time_ms: performance.now() - start,
+                reason: `z3 not available : ${err.message}`,
+            });
+        });
+        child.on("close", (code) => {
+            clearTimeout(timer);
+            const time_ms = performance.now() - start;
+            // z3 exits 0 even on `unsat`; non-zero usually means parse error.
+            const out = stdout.trim();
+            const firstLine = out.split(/\r?\n/)[0]?.trim() ?? "";
+            if (firstLine === "sat") {
+                // Extract model block if present (everything after the first line).
+                const modelStart = out.indexOf("\n");
+                const model = modelStart >= 0 ? out.slice(modelStart + 1).trim() : undefined;
+                settle({ sat: true, model: model || undefined, time_ms });
+                return;
+            }
+            if (firstLine === "unsat") {
+                settle({ sat: false, time_ms });
+                return;
+            }
+            if (firstLine === "unknown") {
+                settle({
+                    sat: null,
+                    time_ms,
+                    reason: "z3 returned unknown (likely timeout or undecidable fragment)",
+                });
+                return;
+            }
+            // Parse error or other failure : surface stderr.
+            settle({
+                sat: null,
+                time_ms,
+                reason: `z3 unexpected output (exit ${code}) : ${(stderr || out).slice(0, 200)}`,
+            });
+        });
+        try {
+            child.stdin.write(smtFormula);
+            child.stdin.end();
+        }
+        catch (err) {
+            clearTimeout(timer);
+            settle({
+                sat: null,
+                time_ms: performance.now() - start,
+                reason: `z3 stdin write failed : ${err instanceof Error ? err.message : String(err)}`,
+            });
+        }
+    });
+}
+/**
+ * Probe : check whether a usable `z3` binary is reachable.
+ * Returns `true` if `z3 --version` exits 0 within 1s.
+ *
+ * Cached for the lifetime of the process — the binary's presence does not
+ * change at runtime.
+ */
+let z3Available;
+export async function isZ3Available(z3Path = "z3") {
+    if (z3Available !== undefined)
+        return z3Available;
+    z3Available = await new Promise((resolve) => {
+        let child;
+        try {
+            child = spawn(z3Path, ["--version"], {
+                stdio: ["ignore", "pipe", "pipe"],
+            });
+        }
+        catch {
+            resolve(false);
+            return;
+        }
+        const t = setTimeout(() => {
+            try {
+                child.kill("SIGKILL");
+            }
+            catch {
+                /* ignored */
+            }
+            resolve(false);
+        }, 1000);
+        child.on("error", () => {
+            clearTimeout(t);
+            resolve(false);
+        });
+        child.on("close", (code) => {
+            clearTimeout(t);
+            resolve(code === 0);
+        });
+    });
+    return z3Available;
+}
+/**
+ * Test-only helper to reset the cached availability probe.
+ * @internal
+ */
+export function __resetZ3AvailabilityCache() {
+    z3Available = undefined;
+}
+//# sourceMappingURL=solver.js.map

package/dist/verify/formal/solver.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"solver.js","sourceRoot":"","sources":["../../../src/verify/formal/solver.ts"],"names":[],"mappings":"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"}