@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/src/verify/formal/solver.ts

@@ -0,0 +1,235 @@
+/**
+ * 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";
+
+/**
+ * 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;
+}
+
+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: string,
+  options: SolverOptions = {}
+): Promise<SmtCheckResult> {
+  const timeoutMs = options.timeout_ms ?? DEFAULT_TIMEOUT_MS;
+  const z3Path = options.z3_path ?? "z3";
+
+  const start = performance.now();
+
+  return new Promise<SmtCheckResult>((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: SmtCheckResult): void => {
+      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: Buffer) => {
+      stdout += chunk.toString();
+    });
+    child.stderr.on("data", (chunk: Buffer) => {
+      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: boolean | undefined;
+
+export async function isZ3Available(z3Path = "z3"): Promise<boolean> {
+  if (z3Available !== undefined) return z3Available;
+  z3Available = await new Promise<boolean>((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(): void {
+  z3Available = undefined;
+}

package/src/verify/formal/spec-language.ts

@@ -0,0 +1,274 @@
+/**
+ * src/verify/formal/spec-language.ts
+ *
+ * Sprint-587 — DSL for axiom specifications, compiled to SMT-LIB v2.
+ *
+ * Design philosophy (inspired by FormalJudge, arXiv:2602.11136) : agent-cycle
+ * properties are expressed as small, typed pre/post-condition tuples. Each
+ * condition is mapped to an SMT-LIB fragment by {@link compileToSmt}, which
+ * frames the property as a NEGATION of the post-conditions under the
+ * pre-conditions. This way, Z3 returning `sat` means a counterexample exists
+ * (= UNSAFE) and `unsat` means the post-conditions hold (= SAFE).
+ *
+ * Bound types : Reals for budgets and ratios, Bools for binary properties,
+ * Sets-as-symbols for scope subset checks.
+ *
+ * @module verify/formal/spec-language
+ */
+
+/**
+ * One verifiable axiom-level property.
+ */
+export interface AxiomSpec {
+  /** Human-readable axiom label (e.g. "Robuste", "Profitable"). */
+  axiom: string;
+  /** Conditions that must hold for the spec to be meaningful. */
+  preconditions: Condition[];
+  /** Conditions whose conjunction defines the post-state to verify. */
+  postconditions: Condition[];
+  /** Solver timeout in ms — see {@link DEFAULT_POLICIES}. */
+  timeout_ms?: number;
+}
+
+/**
+ * Tagged union of all supported condition kinds.
+ *
+ * `custom_smt` is the escape hatch : the consumer supplies a raw SMT-LIB
+ * fragment that will be inlined under an `(assert ...)`. Use sparingly —
+ * mistakes here are silent semantic bugs.
+ */
+export type Condition =
+  | { type: "budget_constraint"; child_max_fraction: number }
+  | { type: "scope_subset"; parent_scope: string[]; child_scope: string[] }
+  | { type: "no_pii_in_output"; pii_count_var?: string }
+  | { type: "cost_positive_roi"; min_roi_ratio: number }
+  | { type: "response_time"; max_ms: number }
+  | { type: "custom_smt"; smt_fragment: string };
+
+// ---------------------------------------------------------------------------
+// Compilation : condition → SMT-LIB fragment
+// ---------------------------------------------------------------------------
+
+interface CompileContext {
+  /** Declared symbols (so we don't double-declare). */
+  declared: Set<string>;
+  /** Accumulated declarations. */
+  declarations: string[];
+  /** Accumulated assertions (precondition + negated postcondition). */
+  assertions: string[];
+}
+
+function ensureDecl(ctx: CompileContext, decl: string, name: string): void {
+  if (ctx.declared.has(name)) return;
+  ctx.declared.add(name);
+  ctx.declarations.push(decl);
+}
+
+/**
+ * Lower a single Condition into SMT-LIB assertions appended to `ctx`.
+ * `negated` flag : when true, the condition is being added as a negated
+ * post-condition (i.e. we want to find a counterexample).
+ */
+function lowerCondition(
+  c: Condition,
+  ctx: CompileContext,
+  negated: boolean
+): void {
+  switch (c.type) {
+    case "budget_constraint": {
+      // parent_budget >= 0, child_budget >= 0, child_budget <= parent_budget * fraction
+      ensureDecl(ctx, "(declare-const parent_budget Real)", "parent_budget");
+      ensureDecl(ctx, "(declare-const child_budget Real)", "child_budget");
+      // Positivity is part of the pre-state, always assert.
+      ctx.assertions.push("(assert (>= parent_budget 0))");
+      ctx.assertions.push("(assert (>= child_budget 0))");
+      const expr = `(<= child_budget (* parent_budget ${c.child_max_fraction}))`;
+      ctx.assertions.push(`(assert ${negated ? `(not ${expr})` : expr})`);
+      return;
+    }
+
+    case "scope_subset": {
+      // Encode each child element as a Bool : it must be present in parent.
+      // We do this by reducing to a boolean conjunction over the listed
+      // child elements. Mismatches surface as a counterexample.
+      const parentSet = new Set(c.parent_scope);
+      const childOk = c.child_scope.every((s) => parentSet.has(s));
+      // No declarations needed — fold the result statically into a bool.
+      const expr = childOk ? "true" : "false";
+      ctx.assertions.push(`(assert ${negated ? `(not ${expr})` : expr})`);
+      return;
+    }
+
+    case "no_pii_in_output": {
+      const name = c.pii_count_var ?? "pii_count";
+      ensureDecl(ctx, `(declare-const ${name} Int)`, name);
+      // pii_count >= 0 (always)
+      ctx.assertions.push(`(assert (>= ${name} 0))`);
+      const expr = `(= ${name} 0)`;
+      ctx.assertions.push(`(assert ${negated ? `(not ${expr})` : expr})`);
+      return;
+    }
+
+    case "cost_positive_roi": {
+      ensureDecl(ctx, "(declare-const cost Real)", "cost");
+      ensureDecl(ctx, "(declare-const value Real)", "value");
+      ctx.assertions.push("(assert (> cost 0))");
+      ctx.assertions.push("(assert (>= value 0))");
+      const expr = `(>= (/ value cost) ${c.min_roi_ratio})`;
+      ctx.assertions.push(`(assert ${negated ? `(not ${expr})` : expr})`);
+      return;
+    }
+
+    case "response_time": {
+      ensureDecl(ctx, "(declare-const response_ms Real)", "response_ms");
+      ctx.assertions.push("(assert (>= response_ms 0))");
+      const expr = `(<= response_ms ${c.max_ms})`;
+      ctx.assertions.push(`(assert ${negated ? `(not ${expr})` : expr})`);
+      return;
+    }
+
+    case "custom_smt": {
+      const frag = c.smt_fragment.trim();
+      // The custom fragment is expected to be a parenthesised assertion body.
+      if (negated) {
+        ctx.assertions.push(`(assert (not ${frag}))`);
+      } else {
+        ctx.assertions.push(`(assert ${frag})`);
+      }
+      return;
+    }
+  }
+}
+
+/**
+ * Compile an {@link AxiomSpec} into an SMT-LIB v2 program string.
+ *
+ * Pattern : preconditions are asserted as-is ; postconditions are joined by
+ * conjunction and asserted NEGATED. A counterexample (z3 returns `sat`)
+ * therefore means : "pre-conditions hold AND at least one post-condition
+ * fails" — i.e. an UNSAFE outcome.
+ *
+ * Includes `(check-sat)` and `(get-model)` as terminating commands.
+ */
+export function compileToSmt(spec: AxiomSpec): string {
+  const ctx: CompileContext = {
+    declared: new Set(),
+    declarations: [],
+    assertions: [],
+  };
+
+  // Header — set logic to QF_LRA (quantifier-free linear real arithmetic
+  // plus integers) which covers all our supported condition kinds.
+  const header = ["(set-logic ALL)", `; AxiomSpec : ${spec.axiom}`];
+
+  // Preconditions : assert as-is (positive form).
+  for (const pre of spec.preconditions) {
+    lowerCondition(pre, ctx, false);
+  }
+
+  // Postconditions : conjoin and negate.
+  // Strategy : assert each one negated separately using De Morgan. We want
+  //   NOT (post1 AND post2 AND …) ≡ (NOT post1) OR (NOT post2) OR …
+  // For check-sat-as-counterexample, we want the solver to find *any*
+  // violation, so we encode the disjunction with an auxiliary Bool flag
+  // per postcondition. Simpler equivalent : assert (or (not post1) (not post2) …).
+  if (spec.postconditions.length === 0) {
+    // Empty postcondition set : trivially SAFE (no obligation to verify).
+    ctx.assertions.push("(assert false)");
+  } else if (spec.postconditions.length === 1) {
+    lowerCondition(spec.postconditions[0]!, ctx, true);
+  } else {
+    // Build per-postcondition expression strings via a side-context, then
+    // emit a single `(assert (or ...))`.
+    const subCtx: CompileContext = {
+      declared: ctx.declared,
+      declarations: ctx.declarations,
+      assertions: [],
+    };
+    const negatedExprs: string[] = [];
+    for (const post of spec.postconditions) {
+      const before = subCtx.assertions.length;
+      lowerCondition(post, subCtx, true);
+      // The last appended assertion is "(assert <neg expr>)" or pre-assertions.
+      // To recover only the negated post-condition body, we accept that some
+      // conditions append additional non-negotiable preconditions (positivity).
+      // Those are valid in any case and stay in the main assertion list.
+      for (let i = before; i < subCtx.assertions.length; i++) {
+        const a = subCtx.assertions[i]!;
+        // Heuristic : split positivity asserts (>= x 0) and the negated body.
+        // The negated body always contains "(not ".
+        if (a.includes("(not ")) {
+          // Extract the inner expr "(not …)" inside the outer assert.
+          const inner = a.slice("(assert ".length, -1);
+          negatedExprs.push(inner);
+        }
+      }
+      // Drop the negated body assertions from subCtx so we only keep
+      // the positivity ones in the main assertion list.
+      subCtx.assertions = subCtx.assertions.filter((a) => !a.includes("(not "));
+    }
+    ctx.assertions = subCtx.assertions;
+    ctx.assertions.push(`(assert (or ${negatedExprs.join(" ")}))`);
+  }
+
+  return [
+    ...header,
+    ...ctx.declarations,
+    ...ctx.assertions,
+    "(check-sat)",
+    "(get-model)",
+  ].join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// Pre-built specs for the 5 Vauban axioms
+// ---------------------------------------------------------------------------
+
+/**
+ * Default per-axiom AxiomSpec presets. Consumers can override the timeout
+ * or augment with additional conditions before passing to `formalVerify`.
+ *
+ * Robuste        : 5s — engineering robustness, may need richer checks
+ * Institutionnel : 10s — strongest spec, PII + scope-subset + budget
+ * SOTA           : 2s  — lightweight (single ROI check on cost)
+ * AntiFragile    : 1s  — response-time bound only
+ * Profitable     : 1s  — cost-vs-value ROI check
+ */
+export const AXIOM_SPECS: Record<string, AxiomSpec> = {
+  Robuste: {
+    axiom: "Robuste",
+    preconditions: [],
+    postconditions: [
+      { type: "budget_constraint", child_max_fraction: 1.0 },
+      { type: "response_time", max_ms: 30_000 },
+    ],
+    timeout_ms: 5000,
+  },
+  Institutionnel: {
+    axiom: "Institutionnel",
+    preconditions: [],
+    postconditions: [
+      { type: "no_pii_in_output" },
+      { type: "budget_constraint", child_max_fraction: 1.0 },
+    ],
+    timeout_ms: 10_000,
+  },
+  SOTA: {
+    axiom: "SOTA",
+    preconditions: [],
+    postconditions: [{ type: "cost_positive_roi", min_roi_ratio: 1.0 }],
+    timeout_ms: 2000,
+  },
+  AntiFragile: {
+    axiom: "AntiFragile",
+    preconditions: [],
+    postconditions: [{ type: "response_time", max_ms: 60_000 }],
+    timeout_ms: 1000,
+  },
+  Profitable: {
+    axiom: "Profitable",
+    preconditions: [],
+    postconditions: [{ type: "cost_positive_roi", min_roi_ratio: 1.5 }],
+    timeout_ms: 1000,
+  },
+};