@vauban-org/agent-sdk 0.17.4 → 1.2.0

package/src/verify/formal/policy.ts

@@ -0,0 +1,253 @@
+/**
+ * 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 const DEFAULT_POLICIES: Record<string, AxiomPolicy> = {
+  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,
+  },
+};
+
+/**
+ * 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;
+}
+
+/**
+ * Whether an axiom is in the "hard" set (Robuste, Institutionnel) whose
+ * UNSAFE outcomes are non-negotiable.
+ */
+function isHardAxiom(axiom: string): boolean {
+  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: FormalVerifyResult,
+  policy: AxiomPolicy,
+  mode: ConsumerMode,
+  context: VerifyContext
+): PolicyDecision {
+  // 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})`,
+      };
+  }
+}

package/src/verify/formal/result.ts

@@ -0,0 +1,52 @@
+/**
+ * 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;
+}

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;
+}