@vauban-org/agent-sdk 1.0.0 → 1.3.0

package/src/testing/test-event-bus.ts

@@ -13,6 +13,8 @@
  * @public
  */
 
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
 import type {
   CloudEvent,
   DomainEvent,
@@ -23,6 +25,8 @@ import { signEvent } from "../auth/sign-event.js";
 import { verifyEvent } from "../auth/verify-event.js";
 import { InMemoryNonceStore } from "../auth/nonce-store.js";
 
+const TEST_TRACER = trace.getTracer("vauban-agent-sdk.ports.test", "0.1.0");
+
 type CloudHandler = (event: CloudEvent) => Promise<void>;
 type DomainHandler<T = unknown> = (event: DomainEvent<T>) => Promise<void>;
 
@@ -59,57 +63,114 @@ export class TestEventBus implements EventBusPort {
   // ─── EventBusPort ──────────────────────────────────────────────────────────
 
   async publish(event: CloudEvent, stream: string): Promise<void> {
-    if (!event.id) throw new Error("CloudEvent.id is required");
-    if (event.specversion !== "1.0")
-      throw new Error("CloudEvent.specversion must be 1.0");
-
-    const events = this.streams.get(stream) ?? [];
-    events.push(event);
-    this.streams.set(stream, events);
-
-    // Track consumed events per stream
-    const consumed = this._consumed.get(stream) ?? [];
-    consumed.push(event);
-    this._consumed.set(stream, consumed);
-
-    // Dispatch to subscribers
-    const streamSubs = this.subscribers.get(stream);
-    if (streamSubs) {
-      for (const handler of streamSubs.values()) {
-        await handler(event);
+    return TEST_TRACER.startActiveSpan(
+      "event-bus.publish",
+      {
+        attributes: {
+          "event.type": event.type,
+          "event.stream": stream,
+          "event.id": event.id,
+          "vauban.port.name": "event-bus",
+          "vauban.port.impl": "TestEventBus",
+        },
+      },
+      async (span: Span) => {
+        try {
+          if (!event.id) throw new Error("CloudEvent.id is required");
+          if (event.specversion !== "1.0")
+            throw new Error("CloudEvent.specversion must be 1.0");
+
+          const events = this.streams.get(stream) ?? [];
+          events.push(event);
+          this.streams.set(stream, events);
+
+          // Track consumed events per stream
+          const consumed = this._consumed.get(stream) ?? [];
+          consumed.push(event);
+          this._consumed.set(stream, consumed);
+
+          // Dispatch to subscribers
+          const streamSubs = this.subscribers.get(stream);
+          if (streamSubs) {
+            for (const handler of streamSubs.values()) {
+              await handler(event);
+            }
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          span.setStatus({ code: SpanStatusCode.ERROR, message });
+          if (err instanceof Error) span.recordException(err);
+          throw err;
+        } finally {
+          span.end();
+        }
       }
-    }
+    );
   }
 
   async publishWithIdempotency<T>(
     event: Omit<DomainEvent<T>, "signature">,
     key: string
   ): Promise<void> {
-    // Dedup: silently skip if key already processed (producer-side)
-    const isNew = await this.publishIdempotencyStore.setNX(key, 10 * 60 * 1000);
-    if (!isNew) return;
-
-    // Auto-sign the event
-    const signature = signEvent(
-      event as Omit<DomainEvent, "signature">,
-      this.signingSecret
-    );
-    const signed: DomainEvent<T> = { ...(event as DomainEvent<T>), signature };
-
-    // Store in domain stream
-    const streamKey = `domain:${event.type}`;
-    const stored = this.domainStreams.get(streamKey) ?? [];
-    const streamId = `${Date.now()}-${stored.length}`;
-    stored.push({ streamId, event: signed as DomainEvent });
-    this.domainStreams.set(streamKey, stored);
-
-    // Dispatch to domain subscribers
-    const typeSubs = this.domainSubscribers.get(event.type);
-    if (typeSubs) {
-      for (const handler of typeSubs.values()) {
-        await (handler as DomainHandler<T>)(signed);
+    return TEST_TRACER.startActiveSpan(
+      "event-bus.publishWithIdempotency",
+      {
+        attributes: {
+          "event.type": event.type,
+          "event.idempotency_key": key,
+          "vauban.port.name": "event-bus",
+          "vauban.port.impl": "TestEventBus",
+        },
+      },
+      async (span: Span) => {
+        try {
+          // Dedup: silently skip if key already processed (producer-side)
+          const isNew = await this.publishIdempotencyStore.setNX(
+            key,
+            10 * 60 * 1000
+          );
+          if (!isNew) {
+            span.setAttribute("event.dedup.skipped", true);
+            span.setStatus({ code: SpanStatusCode.OK });
+            return;
+          }
+
+          // Auto-sign the event
+          const signature = signEvent(
+            event as Omit<DomainEvent, "signature">,
+            this.signingSecret
+          );
+          const signed: DomainEvent<T> = {
+            ...(event as DomainEvent<T>),
+            signature,
+          };
+
+          // Store in domain stream
+          const streamKey = `domain:${event.type}`;
+          const stored = this.domainStreams.get(streamKey) ?? [];
+          const streamId = `${Date.now()}-${stored.length}`;
+          stored.push({ streamId, event: signed as DomainEvent });
+          this.domainStreams.set(streamKey, stored);
+
+          // Dispatch to domain subscribers
+          const typeSubs = this.domainSubscribers.get(event.type);
+          if (typeSubs) {
+            for (const handler of typeSubs.values()) {
+              await (handler as DomainHandler<T>)(signed);
+            }
+          }
+          span.setStatus({ code: SpanStatusCode.OK });
+        } catch (err) {
+          const message = err instanceof Error ? err.message : String(err);
+          span.setStatus({ code: SpanStatusCode.ERROR, message });
+          if (err instanceof Error) span.recordException(err);
+          throw err;
+        } finally {
+          span.end();
+        }
       }
-    }
+    );
   }
 
   subscribe(

package/src/trace/schema.ts

@@ -15,7 +15,7 @@
 
 /** Semver version of this trace schema. Increment MINOR on additive changes,
  *  MAJOR on breaking changes (new required fields or removed fields). */
-export const TRACE_SCHEMA_VERSION = "0.1.0-draft" as const;
+export const TRACE_SCHEMA_VERSION = "1.0.0" as const;
 
 /** Status of an optional TSA receipt for a Trace. */
 export type ReceiptStatus = "present" | "pending" | "failed";

package/src/verify/formal/index.ts

@@ -0,0 +1,154 @@
+/**
+ * src/verify/formal/index.ts
+ *
+ * Sprint-587 — Formal verification entry point.
+ *
+ * Orchestrates : AxiomSpec → SMT-LIB → Z3 subprocess → 4-state result →
+ * (optionally) per-axiom policy decision.
+ *
+ * When `z3` is not in PATH, every spec resolves to UNKNOWN with a uniform
+ * rationale. Callers can then apply their policies — typically resulting in
+ * escalation or log (depending on the axiom and consumer mode).
+ *
+ * @module verify/formal
+ */
+
+import type { FormalVerifyResult } from "./result.js";
+import {
+  type AxiomPolicy,
+  type ConsumerMode,
+  type PolicyDecision,
+  type VerifyContext,
+  DEFAULT_POLICIES,
+  applyPolicy,
+} from "./policy.js";
+import { type AxiomSpec, compileToSmt } from "./spec-language.js";
+import { checkSmt, isZ3Available } from "./solver.js";
+
+export {
+  type FormalVerifyResult,
+  type FormalVerifyState,
+  type FormalSolver,
+} from "./result.js";
+export {
+  type AxiomPolicy,
+  type ConsumerMode,
+  type VerifyContext,
+  type PolicyAction,
+  type PolicyDecision,
+  type OnUnknown,
+  type OnUnsafe,
+  DEFAULT_POLICIES,
+  applyPolicy,
+} from "./policy.js";
+export {
+  type AxiomSpec,
+  type Condition,
+  AXIOM_SPECS,
+  compileToSmt,
+} from "./spec-language.js";
+export {
+  type SmtCheckResult,
+  type SolverOptions,
+  checkSmt,
+  isZ3Available,
+} from "./solver.js";
+
+/**
+ * Bundle returned by {@link formalVerify} : the raw verification result plus
+ * the policy-resolved decision.
+ */
+export interface FormalVerifyDecision {
+  result: FormalVerifyResult;
+  decision: PolicyDecision;
+}
+
+/**
+ * Verify every supplied AxiomSpec, apply the per-axiom policy, and return
+ * one {@link FormalVerifyDecision} per spec.
+ *
+ * If `z3` is not available on PATH, every result is UNKNOWN with
+ * `solver: "none"`, and the policy layer handles routing.
+ *
+ * @param axiomSpecs       List of specs to verify (typically derived from
+ *                         {@link AXIOM_SPECS}, possibly customised).
+ * @param mode             Consumer mode (strict / permissive / audit_only).
+ * @param context          Calling context (runtime / skill_ingestion).
+ * @param customPolicies   Optional override map keyed by axiom label.
+ */
+export async function formalVerify(
+  axiomSpecs: AxiomSpec[],
+  mode: ConsumerMode,
+  context: VerifyContext,
+  customPolicies?: Partial<Record<string, AxiomPolicy>>
+): Promise<FormalVerifyDecision[]> {
+  const z3Available = await isZ3Available();
+
+  const out: FormalVerifyDecision[] = [];
+
+  for (const spec of axiomSpecs) {
+    const policy = customPolicies?.[spec.axiom] ??
+      DEFAULT_POLICIES[
+        spec.axiom
+      ] ?? // Fallback policy for unknown axioms : permissive defaults.
+      {
+        onSafe: "proceed" as const,
+        onUnsafe: "escalate_human" as const,
+        onUnknown: "proceed_with_log" as const,
+        timeout_ms: spec.timeout_ms ?? 5000,
+        skillLoopStrict: true,
+      };
+
+    const timeout_ms = spec.timeout_ms ?? policy.timeout_ms ?? 5000;
+
+    let result: FormalVerifyResult;
+
+    if (!z3Available) {
+      result = {
+        state: "UNKNOWN",
+        axiom: spec.axiom,
+        rationale: "z3 binary not available on PATH",
+        time_ms: 0,
+        solver: "none",
+      };
+    } else {
+      const smt = compileToSmt(spec);
+      const smtRes = await checkSmt(smt, { timeout_ms });
+
+      if (smtRes.sat === false) {
+        // unsat → no counterexample → property holds → SAFE
+        result = {
+          state: "SAFE",
+          axiom: spec.axiom,
+          rationale: `Z3 proved post-conditions hold for axiom ${spec.axiom}`,
+          time_ms: smtRes.time_ms,
+          solver: "z3",
+        };
+      } else if (smtRes.sat === true) {
+        // sat → counterexample → property violated → UNSAFE
+        result = {
+          state: "UNSAFE",
+          axiom: spec.axiom,
+          rationale: `Z3 found a counterexample for axiom ${spec.axiom}`,
+          counterexample: smtRes.model,
+          time_ms: smtRes.time_ms,
+          solver: "z3",
+        };
+      } else {
+        // null → unknown / timeout / error → UNKNOWN
+        result = {
+          state: "UNKNOWN",
+          axiom: spec.axiom,
+          rationale: smtRes.reason ?? "z3 returned unknown",
+          time_ms: smtRes.time_ms,
+          solver: "z3",
+        };
+      }
+    }
+
+    const decision = applyPolicy(result, policy as AxiomPolicy, mode, context);
+    out.push({ result, decision });
+  }
+
+  return out;
+}

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