@vauban-org/agent-sdk 1.0.0 → 1.2.0

package/src/testing/test-brain-port.ts

@@ -5,17 +5,35 @@
  * Maps. Use for agent unit tests that need to archive/query without
  * external infrastructure.
  *
+ * OTel spans are emitted on archiveKnowledge and queryKnowledge via
+ * @opentelemetry/api. Gracefully degrades to noop spans when no OTel SDK
+ * is installed.
+ *
  * @public
  */
 
-import type { BrainPort, BrainEntry, BrainEntryInput, BrainQueryFilters } from "../ports/brain.js";
+import type { Span } from "@opentelemetry/api";
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+import type {
+  BrainPort,
+  BrainEntry,
+  BrainEntryInput,
+  BrainQueryFilters,
+} from "../ports/brain.js";
 import {
   InMemoryWorkingMemory,
   InMemoryEpisodicMemory,
   InMemorySemanticMemory,
   InMemoryProceduralMemory,
 } from "../ports/brain.js";
-import type { WorkingMemoryPort, EpisodicMemoryPort, SemanticMemoryPort, ProceduralMemoryPort } from "../ports/brain.js";
+import type {
+  WorkingMemoryPort,
+  EpisodicMemoryPort,
+  SemanticMemoryPort,
+  ProceduralMemoryPort,
+} from "../ports/brain.js";
+
+const TEST_TRACER = trace.getTracer("vauban-agent-sdk.ports.test", "0.1.0");
 
 export class TestBrainPort implements BrainPort {
   readonly working: WorkingMemoryPort;
@@ -34,31 +52,87 @@ export class TestBrainPort implements BrainPort {
   }
 
   async archiveKnowledge(entry: BrainEntryInput): Promise<BrainEntry | null> {
-    const id = `test-${this.nextId++}`;
-    const created: BrainEntry = {
-      id,
-      content: entry.content,
-      category: entry.category,
-      tags: entry.tags,
-      metadata: entry.metadata as Record<string, unknown> | undefined,
-      created_at: new Date().toISOString(),
-    };
-    this.entries.set(id, created);
-    return created;
+    return TEST_TRACER.startActiveSpan(
+      "brain.archiveKnowledge",
+      {
+        attributes: {
+          "brain.entry.category": entry.category ?? "unknown",
+          "brain.entry.content_preview": entry.content.slice(0, 200),
+          "brain.entry.tags": entry.tags?.join(",") ?? "",
+          "vauban.port.name": "brain",
+          "vauban.port.impl": "TestBrainPort",
+        },
+      },
+      async (span: Span) => {
+        try {
+          const id = `test-${this.nextId++}`;
+          const created: BrainEntry = {
+            id,
+            content: entry.content,
+            category: entry.category,
+            tags: entry.tags,
+            metadata: entry.metadata as Record<string, unknown> | undefined,
+            created_at: new Date().toISOString(),
+          };
+          this.entries.set(id, created);
+          span.setAttribute("brain.entry.id", id);
+          span.setStatus({ code: SpanStatusCode.OK });
+          return created;
+        } 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 queryKnowledge(query: string, filters?: BrainQueryFilters): Promise<BrainEntry[]> {
-    let results = Array.from(this.entries.values()).filter(
-      (e) => e.content.toLowerCase().includes(query.toLowerCase())
+  async queryKnowledge(
+    query: string,
+    filters?: BrainQueryFilters
+  ): Promise<BrainEntry[]> {
+    return TEST_TRACER.startActiveSpan(
+      "brain.queryKnowledge",
+      {
+        attributes: {
+          "brain.query.preview": query.slice(0, 200),
+          "brain.query.category": filters?.category ?? "none",
+          "brain.query.limit": filters?.limit ?? -1,
+          "vauban.port.name": "brain",
+          "vauban.port.impl": "TestBrainPort",
+        },
+      },
+      async (span: Span) => {
+        try {
+          let results = Array.from(this.entries.values()).filter((e) =>
+            e.content.toLowerCase().includes(query.toLowerCase())
+          );
+          if (filters?.category) {
+            results = results.filter((e) => e.category === filters.category);
+          }
+          if (filters?.tags && filters.tags.length > 0) {
+            results = results.filter((e) =>
+              e.tags?.some((t) => (filters.tags as string[]).includes(t))
+            );
+          }
+          const limit = (filters?.limit as number) ?? 10;
+          const sliced = results.slice(0, limit);
+          span.setAttribute("brain.query.result_count", sliced.length);
+          span.setStatus({ code: SpanStatusCode.OK });
+          return sliced;
+        } 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();
+        }
+      }
     );
-    if (filters?.category) {
-      results = results.filter((e) => e.category === filters.category);
-    }
-    if (filters?.tags && filters.tags.length > 0) {
-      results = results.filter((e) => e.tags?.some((t) => (filters.tags as string[]).includes(t)));
-    }
-    const limit = (filters?.limit as number) ?? 10;
-    return results.slice(0, limit);
   }
 
   /** Clear all entries. */

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