@vauban-org/agent-sdk 0.17.4 → 1.2.0

package/dist/ports/manifest-registry.d.ts

@@ -0,0 +1,116 @@
+/**
+ * ManifestRegistryPort — agent manifest registration and lifecycle management (S1 spec).
+ *
+ * Implements: manifest registration with Ed25519 signatures, lifecycle states
+ * (active/deprecated/revoked), version monotonicity, and tier-based compliance gating.
+ *
+ * Invariants enforced: I-S1-1..12 (capabilities, tier constraints, versioning).
+ * Errors: ManifestNotFoundError, ManifestSignatureInvalidError, ManifestVersionConflictError,
+ * ManifestComplianceConflictError (from S5 Cedar G-3).
+ */
+export type Tier = "dev" | "test" | "pilot" | "production" | "internal" | "legacy";
+export declare const SUPPORTED_TIERS: Tier[];
+export type ComplianceMode = "strict" | "audit_only";
+export interface Manifest {
+    readonly name: string;
+    readonly version: string;
+    readonly tier: Tier;
+    readonly compliance_mode: ComplianceMode;
+    readonly capabilities: readonly string[];
+    readonly compliance: {
+        readonly jurisdictions: readonly string[];
+        readonly legal_bases: readonly string[];
+        readonly data_classification: string;
+    };
+    readonly runtime: {
+        readonly max_compute_seconds: number;
+        readonly max_llm_tokens: number;
+    };
+    readonly ed25519_pubkey: string;
+    readonly signature: string;
+    readonly manifestHash: string;
+}
+export type RegistrationStatus = "registered" | "partial" | "failed";
+export interface ComplianceError {
+    readonly code: string;
+    readonly description: string;
+}
+export interface RegistrationResult {
+    readonly claim_id: string;
+    readonly status: RegistrationStatus;
+    readonly manifest_id?: string;
+    readonly errors?: readonly ComplianceError[];
+}
+export interface RegisterOptions {
+    readonly operatorId?: string;
+    readonly timestamp?: Date;
+}
+export interface LookupResult {
+    readonly manifest: Manifest | null;
+    readonly status?: "active" | "deprecated" | "revoked";
+    readonly deprecated_at?: Date;
+    readonly revoked_at?: Date;
+    readonly revocation_reason?: string;
+}
+export interface ManifestRegistryPort {
+    /**
+     * Register a manifest with Ed25519 signature validation.
+     * Validates I-S1-1..12 invariants before persisting.
+     * Rejects I-S1-2 violation: tier='production' + mode='audit_only'.
+     * Returns claim_id (signed Claim artifact) or ComplianceErrors.
+     */
+    register(manifest: Manifest, options?: RegisterOptions): Promise<RegistrationResult>;
+    /**
+     * Look up a manifest by name + version.
+     * Returns null if not found or revoked.
+     * Does not include errors list (use getValidationErrors for detailed checks).
+     */
+    lookup(name: string, version: string): Promise<Manifest | null>;
+    /**
+     * Revoke a manifest by claim_id.
+     * After revocation, lookup() returns null.
+     * Emits revocation event (audit trail).
+     * Returns void on success; throws ManifestNotFoundError if claim_id invalid.
+     */
+    revoke(claim_id: string, reason: string): Promise<void>;
+    /**
+     * List all versions of a manifest by name, sorted by semver.
+     * Returns versions in ascending order (0.1.0 < 1.0.0).
+     * Returns empty array if name not found.
+     */
+    listVersions(name: string): Promise<readonly string[]>;
+    /**
+     * Validate a manifest signature against its ed25519_pubkey.
+     * Recomputes manifestHash and checks signature.
+     * Returns true if valid; throws ManifestSignatureInvalidError if invalid.
+     */
+    verifySignature(manifest: Manifest): Promise<boolean>;
+}
+export declare class ManifestNotFoundError extends Error {
+    readonly name: string;
+    readonly version: string;
+    constructor(name: string, version: string);
+}
+export declare class ManifestSignatureInvalidError extends Error {
+    readonly name: string;
+    readonly version: string;
+    readonly cause?: unknown | undefined;
+    constructor(name: string, version: string, cause?: unknown | undefined);
+}
+export declare class ManifestVersionConflictError extends Error {
+    readonly name: string;
+    readonly version: string;
+    readonly existingStatus: string;
+    constructor(name: string, version: string, existingStatus: string);
+}
+export declare class ManifestComplianceConflictError extends Error {
+    readonly name: string;
+    readonly version: string;
+    readonly violation: string;
+    constructor(name: string, version: string, violation: string);
+}
+export declare class ManifestValidationError extends Error {
+    readonly violations: readonly ComplianceError[];
+    constructor(violations: readonly ComplianceError[]);
+}
+//# sourceMappingURL=manifest-registry.d.ts.map

package/dist/ports/manifest-registry.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-registry.d.ts","sourceRoot":"","sources":["../../src/ports/manifest-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAIH,MAAM,MAAM,IAAI,GACZ,KAAK,GACL,MAAM,GACN,OAAO,GACP,YAAY,GACZ,UAAU,GACV,QAAQ,CAAC;AAEb,eAAO,MAAM,eAAe,EAAE,IAAI,EAOjC,CAAC;AAIF,MAAM,MAAM,cAAc,GAAG,QAAQ,GAAG,YAAY,CAAC;AAIrD,MAAM,WAAW,QAAQ;IACvB,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,EAAE,IAAI,CAAC;IACpB,QAAQ,CAAC,eAAe,EAAE,cAAc,CAAC;IACzC,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,UAAU,EAAE;QACnB,QAAQ,CAAC,aAAa,EAAE,SAAS,MAAM,EAAE,CAAC;QAC1C,QAAQ,CAAC,WAAW,EAAE,SAAS,MAAM,EAAE,CAAC;QACxC,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;KACtC,CAAC;IACF,QAAQ,CAAC,OAAO,EAAE;QAChB,QAAQ,CAAC,mBAAmB,EAAE,MAAM,CAAC;QACrC,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;KACjC,CAAC;IACF,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAID,MAAM,MAAM,kBAAkB,GAAG,YAAY,GAAG,SAAS,GAAG,QAAQ,CAAC;AAErE,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;CAC9B;AAED,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,EAAE,kBAAkB,CAAC;IACpC,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,eAAe,EAAE,CAAC;CAC9C;AAID,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;IAC7B,QAAQ,CAAC,SAAS,CAAC,EAAE,IAAI,CAAC;CAC3B;AAID,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,QAAQ,EAAE,QAAQ,GAAG,IAAI,CAAC;IACnC,QAAQ,CAAC,MAAM,CAAC,EAAE,QAAQ,GAAG,YAAY,GAAG,SAAS,CAAC;IACtD,QAAQ,CAAC,aAAa,CAAC,EAAE,IAAI,CAAC;IAC9B,QAAQ,CAAC,UAAU,CAAC,EAAE,IAAI,CAAC;IAC3B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;CACrC;AAID,MAAM,WAAW,oBAAoB;IACnC;;;;;OAKG;IACH,QAAQ,CACN,QAAQ,EAAE,QAAQ,EAClB,OAAO,CAAC,EAAE,eAAe,GACxB,OAAO,CAAC,kBAAkB,CAAC,CAAC;IAE/B;;;;OAIG;IACH,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,QAAQ,GAAG,IAAI,CAAC,CAAC;IAEhE;;;;;OAKG;IACH,MAAM,CAAC,QAAQ,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAExD;;;;OAIG;IACH,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAC,SAAS,MAAM,EAAE,CAAC,CAAC;IAEvD;;;;OAIG;IACH,eAAe,CAAC,QAAQ,EAAE,QAAQ,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CACvD;AAID,qBAAa,qBAAsB,SAAQ,KAAK;aAClB,IAAI,EAAE,MAAM;aAAkB,OAAO,EAAE,MAAM;gBAA7C,IAAI,EAAE,MAAM,EAAkB,OAAO,EAAE,MAAM;CAK1E;AAED,qBAAa,6BAA8B,SAAQ,KAAK;aAEpC,IAAI,EAAE,MAAM;aACZ,OAAO,EAAE,MAAM;aACf,KAAK,CAAC,EAAE,OAAO;gBAFf,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,KAAK,CAAC,EAAE,OAAO,YAAA;CAMlC;AAED,qBAAa,4BAA6B,SAAQ,KAAK;aAEnC,IAAI,EAAE,MAAM;aACZ,OAAO,EAAE,MAAM;aACf,cAAc,EAAE,MAAM;gBAFtB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,cAAc,EAAE,MAAM;CAQzC;AAED,qBAAa,+BAAgC,SAAQ,KAAK;aAEtC,IAAI,EAAE,MAAM;aACZ,OAAO,EAAE,MAAM;aACf,SAAS,EAAE,MAAM;gBAFjB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EACf,SAAS,EAAE,MAAM;CAMpC;AAED,qBAAa,uBAAwB,SAAQ,KAAK;aACpB,UAAU,EAAE,SAAS,eAAe,EAAE;gBAAtC,UAAU,EAAE,SAAS,eAAe,EAAE;CAKnE"}

package/dist/ports/manifest-registry.js

@@ -0,0 +1,79 @@
+/**
+ * ManifestRegistryPort — agent manifest registration and lifecycle management (S1 spec).
+ *
+ * Implements: manifest registration with Ed25519 signatures, lifecycle states
+ * (active/deprecated/revoked), version monotonicity, and tier-based compliance gating.
+ *
+ * Invariants enforced: I-S1-1..12 (capabilities, tier constraints, versioning).
+ * Errors: ManifestNotFoundError, ManifestSignatureInvalidError, ManifestVersionConflictError,
+ * ManifestComplianceConflictError (from S5 Cedar G-3).
+ */
+export const SUPPORTED_TIERS = [
+    "dev",
+    "test",
+    "pilot",
+    "production",
+    "internal",
+    "legacy",
+];
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+export class ManifestNotFoundError extends Error {
+    name;
+    version;
+    constructor(name, version) {
+        super(`Manifest not found: ${name}@${version}`);
+        this.name = name;
+        this.version = version;
+        this.name = "ManifestNotFoundError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class ManifestSignatureInvalidError extends Error {
+    name;
+    version;
+    cause;
+    constructor(name, version, cause) {
+        super(`Manifest signature invalid for ${name}@${version}`);
+        this.name = name;
+        this.version = version;
+        this.cause = cause;
+        this.name = "ManifestSignatureInvalidError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class ManifestVersionConflictError extends Error {
+    name;
+    version;
+    existingStatus;
+    constructor(name, version, existingStatus) {
+        super(`Manifest version conflict: ${name}@${version} already registered as ${existingStatus}`);
+        this.name = name;
+        this.version = version;
+        this.existingStatus = existingStatus;
+        this.name = "ManifestVersionConflictError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class ManifestComplianceConflictError extends Error {
+    name;
+    version;
+    violation;
+    constructor(name, version, violation) {
+        super(`Compliance violation for ${name}@${version}: ${violation}`);
+        this.name = name;
+        this.version = version;
+        this.violation = violation;
+        this.name = "ManifestComplianceConflictError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class ManifestValidationError extends Error {
+    violations;
+    constructor(violations) {
+        super(`Manifest validation failed with ${violations.length} violation(s)`);
+        this.violations = violations;
+        this.name = "ManifestValidationError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=manifest-registry.js.map

package/dist/ports/manifest-registry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"manifest-registry.js","sourceRoot":"","sources":["../../src/ports/manifest-registry.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG;AAYH,MAAM,CAAC,MAAM,eAAe,GAAW;IACrC,KAAK;IACL,MAAM;IACN,OAAO;IACP,YAAY;IACZ,UAAU;IACV,QAAQ;CACT,CAAC;AAyGF,iFAAiF;AAEjF,MAAM,OAAO,qBAAsB,SAAQ,KAAK;IAClB;IAA8B;IAA1D,YAA4B,IAAY,EAAkB,OAAe;QACvE,KAAK,CAAC,uBAAuB,IAAI,IAAI,OAAO,EAAE,CAAC,CAAC;QADtB,SAAI,GAAJ,IAAI,CAAQ;QAAkB,YAAO,GAAP,OAAO,CAAQ;QAEvE,IAAI,CAAC,IAAI,GAAG,uBAAuB,CAAC;QACpC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IAEpC;IACA;IACA;IAHlB,YACkB,IAAY,EACZ,OAAe,EACf,KAAe;QAE/B,KAAK,CAAC,kCAAkC,IAAI,IAAI,OAAO,EAAE,CAAC,CAAC;QAJ3C,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAAQ;QACf,UAAK,GAAL,KAAK,CAAU;QAG/B,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;QAC5C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,OAAO,4BAA6B,SAAQ,KAAK;IAEnC;IACA;IACA;IAHlB,YACkB,IAAY,EACZ,OAAe,EACf,cAAsB;QAEtC,KAAK,CACH,8BAA8B,IAAI,IAAI,OAAO,0BAA0B,cAAc,EAAE,CACxF,CAAC;QANc,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAAQ;QACf,mBAAc,GAAd,cAAc,CAAQ;QAKtC,IAAI,CAAC,IAAI,GAAG,8BAA8B,CAAC;QAC3C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IAEtC;IACA;IACA;IAHlB,YACkB,IAAY,EACZ,OAAe,EACf,SAAiB;QAEjC,KAAK,CAAC,4BAA4B,IAAI,IAAI,OAAO,KAAK,SAAS,EAAE,CAAC,CAAC;QAJnD,SAAI,GAAJ,IAAI,CAAQ;QACZ,YAAO,GAAP,OAAO,CAAQ;QACf,cAAS,GAAT,SAAS,CAAQ;QAGjC,IAAI,CAAC,IAAI,GAAG,iCAAiC,CAAC;QAC9C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,OAAO,uBAAwB,SAAQ,KAAK;IACpB;IAA5B,YAA4B,UAAsC;QAChE,KAAK,CAAC,mCAAmC,UAAU,CAAC,MAAM,eAAe,CAAC,CAAC;QADjD,eAAU,GAAV,UAAU,CAA4B;QAEhE,IAAI,CAAC,IAAI,GAAG,yBAAyB,CAAC;QACtC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/ports/observability.contract.test.d.ts

@@ -0,0 +1,12 @@
+/**
+ * ObservabilityPort contract tests — validate port interface compliance.
+ *
+ * Tests verify:
+ * - startSpan returns a valid Span with all methods
+ * - recordEvent accepts all 5 severity levels
+ * - recordMetric accepts gauge, counter, histogram types
+ * - flush() resolves successfully
+ * - NoopObservabilityPort satisfies the interface
+ */
+export {};
+//# sourceMappingURL=observability.contract.test.d.ts.map

package/dist/ports/observability.contract.test.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.contract.test.d.ts","sourceRoot":"","sources":["../../src/ports/observability.contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;;;;GASG"}

package/dist/ports/observability.contract.test.js

@@ -0,0 +1,260 @@
+/**
+ * ObservabilityPort contract tests — validate port interface compliance.
+ *
+ * Tests verify:
+ * - startSpan returns a valid Span with all methods
+ * - recordEvent accepts all 5 severity levels
+ * - recordMetric accepts gauge, counter, histogram types
+ * - flush() resolves successfully
+ * - NoopObservabilityPort satisfies the interface
+ */
+import { describe, it, expect } from "vitest";
+import { NoopObservabilityPort, } from "./observability";
+describe("ObservabilityPort contract", () => {
+    describe("startSpan", () => {
+        it("returns a Span with all required methods", () => {
+            const port = new NoopObservabilityPort();
+            const span = port.startSpan("test.span", {
+                service: "test",
+                version: 1,
+            });
+            expect(span).toBeDefined();
+            expect(typeof span.setAttribute).toBe("function");
+            expect(typeof span.recordException).toBe("function");
+            expect(typeof span.setStatus).toBe("function");
+            expect(typeof span.end).toBe("function");
+        });
+        it("accepts span name and optional attributes", () => {
+            const port = new NoopObservabilityPort();
+            const span1 = port.startSpan("workflow.execute");
+            const span2 = port.startSpan("brain.query", {
+                query: "test",
+                category: "semantic",
+                limit: 10,
+            });
+            expect(span1).toBeDefined();
+            expect(span2).toBeDefined();
+            span1.end();
+            span2.end();
+        });
+        it("span.setAttribute accepts string, number, boolean, and arrays", () => {
+            const port = new NoopObservabilityPort();
+            const span = port.startSpan("test");
+            span.setAttribute("string_attr", "hello");
+            span.setAttribute("number_attr", 42);
+            span.setAttribute("bool_attr", true);
+            span.setAttribute("string_array_attr", ["a", "b", "c"]);
+            span.setAttribute("number_array_attr", [1, 2, 3]);
+            expect(true).toBe(true); // noop implementation succeeds silently
+            span.end();
+        });
+        it("span.recordException accepts Error or unknown", () => {
+            const port = new NoopObservabilityPort();
+            const span = port.startSpan("test");
+            span.recordException(new Error("test error"));
+            span.recordException({ message: "unknown error" });
+            span.recordException("string error");
+            expect(true).toBe(true);
+            span.end();
+        });
+        it("span.setStatus accepts code and optional message", () => {
+            const port = new NoopObservabilityPort();
+            const span = port.startSpan("test");
+            span.setStatus({ code: "OK" });
+            span.setStatus({ code: "ERROR", message: "something went wrong" });
+            expect(true).toBe(true);
+            span.end();
+        });
+        it("span.end completes the span", () => {
+            const port = new NoopObservabilityPort();
+            const span = port.startSpan("test");
+            expect(() => span.end()).not.toThrow();
+        });
+    });
+    describe("recordEvent", () => {
+        it("accepts events with all 5 severity levels", () => {
+            const port = new NoopObservabilityPort();
+            const severities = ["debug", "info", "warn", "error", "fatal"];
+            for (const severity of severities) {
+                const event = {
+                    name: `event.${severity}`,
+                    severity,
+                };
+                expect(() => port.recordEvent(event)).not.toThrow();
+            }
+        });
+        it("accepts optional attributes, timestamp, traceId, spanId", () => {
+            const port = new NoopObservabilityPort();
+            const event = {
+                name: "test.event",
+                severity: "info",
+                attributes: {
+                    user_id: "user-123",
+                    action: "created",
+                    resource_count: 5,
+                },
+                timestamp: Date.now(),
+                traceId: "4bf92f3577b34da6a3ce929d0e0e4736",
+                spanId: "00f067aa0ba902b7",
+            };
+            expect(() => port.recordEvent(event)).not.toThrow();
+        });
+        it("attributes can contain strings, numbers, booleans, and arrays", () => {
+            const port = new NoopObservabilityPort();
+            const event = {
+                name: "complex.event",
+                severity: "warn",
+                attributes: {
+                    message: "test warning",
+                    count: 42,
+                    enabled: true,
+                    tags: ["tag1", "tag2"],
+                    scores: [9.5, 8.7, 9.2],
+                },
+            };
+            expect(() => port.recordEvent(event)).not.toThrow();
+        });
+    });
+    describe("recordMetric", () => {
+        it("accepts gauge type metrics", () => {
+            const port = new NoopObservabilityPort();
+            port.recordMetric({
+                name: "memory.usage",
+                type: "gauge",
+                value: 512,
+                labels: { instance: "worker-1" },
+            });
+            expect(true).toBe(true);
+        });
+        it("accepts counter type metrics", () => {
+            const port = new NoopObservabilityPort();
+            port.recordMetric({
+                name: "requests.total",
+                type: "counter",
+                value: 1,
+                labels: { endpoint: "/api/query" },
+            });
+            expect(true).toBe(true);
+        });
+        it("accepts histogram type metrics", () => {
+            const port = new NoopObservabilityPort();
+            port.recordMetric({
+                name: "request.duration",
+                type: "histogram",
+                value: 125,
+                labels: { method: "POST" },
+            });
+            expect(true).toBe(true);
+        });
+        it("optional timestamp defaults to Date.now()", () => {
+            const port = new NoopObservabilityPort();
+            const before = Date.now();
+            port.recordMetric({
+                name: "test.metric",
+                type: "gauge",
+                value: 100,
+            });
+            const after = Date.now();
+            expect(after).toBeGreaterThanOrEqual(before);
+        });
+        it("accepts metrics without labels", () => {
+            const port = new NoopObservabilityPort();
+            port.recordMetric({
+                name: "simple.metric",
+                type: "gauge",
+                value: 42,
+            });
+            expect(true).toBe(true);
+        });
+    });
+    describe("flush", () => {
+        it("resolves successfully", async () => {
+            const port = new NoopObservabilityPort();
+            const result = port.flush();
+            expect(result).toBeInstanceOf(Promise);
+            await expect(result).resolves.toBeUndefined();
+        });
+        it("can be called multiple times", async () => {
+            const port = new NoopObservabilityPort();
+            await expect(port.flush()).resolves.toBeUndefined();
+            await expect(port.flush()).resolves.toBeUndefined();
+            await expect(port.flush()).resolves.toBeUndefined();
+        });
+    });
+    describe("NoopObservabilityPort interface compliance", () => {
+        it("satisfies ObservabilityPort contract", () => {
+            const port = new NoopObservabilityPort();
+            // All methods required by ObservabilityPort are present
+            expect(typeof port.startSpan).toBe("function");
+            expect(typeof port.recordEvent).toBe("function");
+            expect(typeof port.recordMetric).toBe("function");
+            expect(typeof port.flush).toBe("function");
+        });
+        it("startSpan, recordEvent, recordMetric work together", () => {
+            const port = new NoopObservabilityPort();
+            const span = port.startSpan("integration.test", { phase: "setup" });
+            port.recordEvent({
+                name: "span.created",
+                severity: "info",
+            });
+            port.recordMetric({
+                name: "span.count",
+                type: "counter",
+                value: 1,
+            });
+            span.setAttribute("status", "active");
+            port.recordEvent({
+                name: "span.attribute.set",
+                severity: "debug",
+            });
+            span.setStatus({ code: "OK" });
+            span.end();
+            expect(true).toBe(true); // all calls succeed
+        });
+    });
+    describe("error paths", () => {
+        it("recordException handles various error types gracefully", () => {
+            const port = new NoopObservabilityPort();
+            const span = port.startSpan("error.test");
+            const testCases = [
+                new Error("standard error"),
+                new TypeError("type error"),
+                new RangeError("range error"),
+                { code: "CUSTOM_ERROR", message: "custom error object" },
+                "string error",
+                null,
+                undefined,
+            ];
+            for (const testCase of testCases) {
+                expect(() => span.recordException(testCase)).not.toThrow();
+            }
+            span.end();
+        });
+        it("setStatus accepts various code strings", () => {
+            const port = new NoopObservabilityPort();
+            const span = port.startSpan("status.test");
+            const codes = ["OK", "ERROR", "UNSET", "PENDING"];
+            for (const code of codes) {
+                expect(() => span.setStatus({ code })).not.toThrow();
+                expect(() => span.setStatus({ code, message: "optional message" })).not.toThrow();
+            }
+            span.end();
+        });
+    });
+    describe("attribute value types", () => {
+        it("setAttribute validates AttrValue union", () => {
+            const port = new NoopObservabilityPort();
+            const span = port.startSpan("types.test");
+            // All valid AttrValue types
+            span.setAttribute("string", "value");
+            span.setAttribute("number", 123);
+            span.setAttribute("float", 3.14);
+            span.setAttribute("bool", false);
+            span.setAttribute("array_strings", ["a", "b"]);
+            span.setAttribute("array_numbers", [1, 2, 3]);
+            expect(true).toBe(true);
+            span.end();
+        });
+    });
+});
+//# sourceMappingURL=observability.contract.test.js.map

package/dist/ports/observability.contract.test.js.map

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

package/dist/ports/observability.d.ts

@@ -0,0 +1,98 @@
+/**
+ * ObservabilityPort — cross-cutting telemetry for Vauban Integration Spine.
+ *
+ * Implements S0 §6 (ObservabilityPort, port #14): OpenTelemetry-compatible spans,
+ * structured event logging, metrics, and graceful shutdown. Adapters emit to
+ * Prometheus, Sentry, audit logs, or custom backends.
+ *
+ * Design: structured types only — no hard dependency on @opentelemetry/api.
+ * Real OTel Spans satisfy the structural Span interface.
+ *
+ * Reference: S0 §6 type definition + createTracedBrainPort pattern in brain.ts
+ */
+export type AttrValue = string | number | boolean | (string | number)[];
+export interface SpanAttributes {
+    readonly [key: string]: AttrValue;
+}
+export interface Span {
+    /** Record a key-value attribute on this span. */
+    setAttribute(key: string, value: AttrValue): void;
+    /** Record an exception / error on this span. */
+    recordException(error: Error | unknown): void;
+    /**
+     * Set the final status of this span.
+     * @param code 'OK', 'ERROR', or other OTel SpanStatusCode equivalent
+     * @param message optional message (used when code is 'ERROR')
+     */
+    setStatus(opts: {
+        code: string;
+        message?: string;
+    }): void;
+    /** Mark the span as complete. */
+    end(): void;
+}
+export type EventSeverity = "debug" | "info" | "warn" | "error" | "fatal";
+export interface ObservabilityEvent {
+    readonly name: string;
+    readonly severity: EventSeverity;
+    readonly attributes?: Record<string, AttrValue>;
+    readonly timestamp?: number;
+    readonly traceId?: string;
+    readonly spanId?: string;
+}
+export type MetricType = "gauge" | "counter" | "histogram";
+export interface MetricInput {
+    readonly name: string;
+    readonly type: MetricType;
+    readonly value: number;
+    readonly labels?: Record<string, string>;
+    readonly timestamp?: number;
+}
+export interface ObservabilityPort {
+    /**
+     * Start a new OTel-compatible span.
+     *
+     * @param name span name (e.g., "workflow.execute", "brain.query")
+     * @param attrs optional span attributes
+     * @returns Span handle for setAttribute, recordException, setStatus, end calls
+     */
+    startSpan(name: string, attrs?: SpanAttributes): Span;
+    /**
+     * Record a structured observability event (log, audit, compliance event).
+     *
+     * @param event event with name, severity, attributes, optional trace/span IDs
+     */
+    recordEvent(event: ObservabilityEvent): void;
+    /**
+     * Record a metric (gauge, counter, histogram).
+     *
+     * @param metric metric name, type, value, optional labels and timestamp
+     */
+    recordMetric(metric: MetricInput): void;
+    /**
+     * Graceful shutdown — flush all pending telemetry.
+     * Called at process exit or service shutdown.
+     */
+    flush(): Promise<void>;
+}
+/**
+ * NoopObservabilityPort — no-op implementation for tests or offline mode.
+ * All calls are discarded; span operations succeed silently.
+ */
+export declare class NoopObservabilityPort implements ObservabilityPort {
+    private readonly noopSpan;
+    startSpan(_name: string, _attrs?: SpanAttributes): Span;
+    recordEvent(_event: ObservabilityEvent): void;
+    recordMetric(_metric: MetricInput): void;
+    flush(): Promise<void>;
+}
+export declare class ObservabilityError extends Error {
+    readonly cause?: unknown | undefined;
+    constructor(message: string, cause?: unknown | undefined);
+}
+export declare class ObservabilityFlushTimeoutError extends Error {
+    readonly timeoutMs: number;
+    readonly cause?: unknown | undefined;
+    constructor(timeoutMs: number, cause?: unknown | undefined);
+}
+//# sourceMappingURL=observability.d.ts.map

package/dist/ports/observability.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"observability.d.ts","sourceRoot":"","sources":["../../src/ports/observability.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;GAWG;AAIH,MAAM,MAAM,SAAS,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,CAAC,MAAM,GAAG,MAAM,CAAC,EAAE,CAAC;AAExE,MAAM,WAAW,cAAc;IAC7B,QAAQ,EAAE,GAAG,EAAE,MAAM,GAAG,SAAS,CAAC;CACnC;AAID,MAAM,WAAW,IAAI;IACnB,iDAAiD;IACjD,YAAY,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAAC;IAElD,gDAAgD;IAChD,eAAe,CAAC,KAAK,EAAE,KAAK,GAAG,OAAO,GAAG,IAAI,CAAC;IAE9C;;;;OAIG;IACH,SAAS,CAAC,IAAI,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,OAAO,CAAC,EAAE,MAAM,CAAA;KAAE,GAAG,IAAI,CAAC;IAE1D,iCAAiC;IACjC,GAAG,IAAI,IAAI,CAAC;CACb;AAID,MAAM,MAAM,aAAa,GAAG,OAAO,GAAG,MAAM,GAAG,MAAM,GAAG,OAAO,GAAG,OAAO,CAAC;AAE1E,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,QAAQ,EAAE,aAAa,CAAC;IACjC,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAAC;IAChD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,QAAQ,CAAC,OAAO,CAAC,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;CAC1B;AAID,MAAM,MAAM,UAAU,GAAG,OAAO,GAAG,SAAS,GAAG,WAAW,CAAC;AAE3D,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB,QAAQ,CAAC,IAAI,EAAE,UAAU,CAAC;IAC1B,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;CAC7B;AAID,MAAM,WAAW,iBAAiB;IAChC;;;;;;OAMG;IACH,SAAS,CAAC,IAAI,EAAE,MAAM,EAAE,KAAK,CAAC,EAAE,cAAc,GAAG,IAAI,CAAC;IAEtD;;;;OAIG;IACH,WAAW,CAAC,KAAK,EAAE,kBAAkB,GAAG,IAAI,CAAC;IAE7C;;;;OAIG;IACH,YAAY,CAAC,MAAM,EAAE,WAAW,GAAG,IAAI,CAAC;IAExC;;;OAGG;IACH,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAID;;;GAGG;AACH,qBAAa,qBAAsB,YAAW,iBAAiB;IAC7D,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAKvB;IAEF,SAAS,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,CAAC,EAAE,cAAc,GAAG,IAAI;IAIvD,WAAW,CAAC,MAAM,EAAE,kBAAkB,GAAG,IAAI;IAI7C,YAAY,CAAC,OAAO,EAAE,WAAW,GAAG,IAAI;IAIlC,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;CAG7B;AAID,qBAAa,kBAAmB,SAAQ,KAAK;aACE,KAAK,CAAC,EAAE,OAAO;gBAAhD,OAAO,EAAE,MAAM,EAAkB,KAAK,CAAC,EAAE,OAAO,YAAA;CAK7D;AAED,qBAAa,8BAA+B,SAAQ,KAAK;aAErC,SAAS,EAAE,MAAM;aACjB,KAAK,CAAC,EAAE,OAAO;gBADf,SAAS,EAAE,MAAM,EACjB,KAAK,CAAC,EAAE,OAAO,YAAA;CAMlC"}

package/dist/ports/observability.js

@@ -0,0 +1,59 @@
+/**
+ * ObservabilityPort — cross-cutting telemetry for Vauban Integration Spine.
+ *
+ * Implements S0 §6 (ObservabilityPort, port #14): OpenTelemetry-compatible spans,
+ * structured event logging, metrics, and graceful shutdown. Adapters emit to
+ * Prometheus, Sentry, audit logs, or custom backends.
+ *
+ * Design: structured types only — no hard dependency on @opentelemetry/api.
+ * Real OTel Spans satisfy the structural Span interface.
+ *
+ * Reference: S0 §6 type definition + createTracedBrainPort pattern in brain.ts
+ */
+// ─── Noop implementation (for tests, fallback, or offline mode) ──────────────
+/**
+ * NoopObservabilityPort — no-op implementation for tests or offline mode.
+ * All calls are discarded; span operations succeed silently.
+ */
+export class NoopObservabilityPort {
+    noopSpan = {
+        setAttribute: () => { },
+        recordException: () => { },
+        setStatus: () => { },
+        end: () => { },
+    };
+    startSpan(_name, _attrs) {
+        return this.noopSpan;
+    }
+    recordEvent(_event) {
+        // no-op
+    }
+    recordMetric(_metric) {
+        // no-op
+    }
+    async flush() {
+        // no-op
+    }
+}
+// ─── Typed errors ────────────────────────────────────────────────────────────
+export class ObservabilityError extends Error {
+    cause;
+    constructor(message, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "ObservabilityError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class ObservabilityFlushTimeoutError extends Error {
+    timeoutMs;
+    cause;
+    constructor(timeoutMs, cause) {
+        super(`Observability flush timed out after ${timeoutMs}ms`);
+        this.timeoutMs = timeoutMs;
+        this.cause = cause;
+        this.name = "ObservabilityFlushTimeoutError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=observability.js.map