@vauban-org/agent-sdk 0.17.4 → 1.2.0

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

@@ -0,0 +1,279 @@
+/**
+ * FederationPort contract tests (S4 spec).
+ *
+ * Applied to any FederationPort implementation.
+ * Verifies: send→receive roundtrip, signature verification, delegation chain preservation,
+ * consistent hash routing determinism, replay protection via nonce.
+ */
+import { describe, expect, test } from "vitest";
+import { FederationSignatureInvalidError, FederationDelegationChainError, FederationMessageExpiredError, } from "./federation.js";
+/**
+ * Factory function to create a minimal valid FederationMessage for testing.
+ */
+function makeFederationMessage(overrides = {}) {
+    const now = new Date().toISOString();
+    const expiresAt = new Date(Date.now() + 86400000).toISOString(); // +24h
+    const header = {
+        message_id: crypto.randomUUID(),
+        from_agent: {
+            agent_id: "vauban.cc.test@v1.0",
+            tenant_id: "test-tenant-1",
+            agent_card_url: "https://example.com/cards/test-agent",
+        },
+        to_agent: {
+            agent_id: "vauban.cc.receiver@v1.0",
+            tenant_id: "test-tenant-2",
+        },
+        correlation_id: crypto.randomUUID(),
+        timestamp: now,
+        nonce: crypto.getRandomValues(new Uint8Array(32)).toString(),
+    };
+    const contentClaim = {
+        subject: `digest:${header.message_id}`,
+        predicate: {
+            domain: "vauban.federation.message.v1",
+            body: {
+                action: "test_message",
+                payload: { test_data: "hello world" },
+            },
+        },
+        evidence: {
+            proof: "ed25519_" + crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+            public_inputs: {
+                from_agent: header.from_agent.agent_id,
+                to_agent: header.to_agent.agent_id,
+            },
+        },
+        temporal_frame: {
+            not_before: now,
+            not_after: expiresAt,
+            revoked_at: null,
+        },
+        revelation_mask: {
+            disclosed: ["/subject", "/predicate", "/temporal_frame"],
+            committed: [],
+        },
+        anchor: [
+            {
+                chain: "StarknetMainnet",
+                tx_hash: "0x" + crypto.randomUUID().replace(/-/g, "").slice(0, 32),
+            },
+        ],
+    };
+    const transport = {
+        protocol: "mcp",
+        version: "1.0.0",
+        jws_signature: "eyJ" +
+            crypto.randomUUID().replace(/-/g, "").slice(0, 48) +
+            ".payload.signature",
+    };
+    return {
+        id: header.message_id,
+        header,
+        content_claim: contentClaim,
+        transport,
+        ...overrides,
+    };
+}
+export const federationPortContract = (factory) => {
+    describe("FederationPort contract", () => {
+        test("send→receive roundtrip delivers message to destination tenant", async () => {
+            const port = factory();
+            const msg = makeFederationMessage();
+            // Send message
+            const msgId = await port.send(msg);
+            expect(msgId).toBe(msg.id);
+            // Receive should deliver it to the destination tenant
+            const received = await port.receive({
+                destinationTenantId: msg.header.to_agent.tenant_id,
+                timeout: 2000,
+            });
+            expect(received.length).toBeGreaterThan(0);
+            const deliveredMsg = received.find((m) => m.id === msg.id);
+            expect(deliveredMsg).toBeDefined();
+            expect(deliveredMsg?.header.to_agent.tenant_id).toBe(msg.header.to_agent.tenant_id);
+        });
+        test("verifyMessage rejects tampered signature", async () => {
+            const port = factory();
+            const msg = makeFederationMessage();
+            // Tamper with the signature
+            const tamperedMsg = {
+                ...msg,
+                transport: {
+                    ...msg.transport,
+                    jws_signature: "invalid_signature_header.payload.signature",
+                },
+            };
+            const result = await port.verifyMessage(tamperedMsg);
+            expect(result.valid).toBe(false);
+            expect(result.errors.length).toBeGreaterThan(0);
+        });
+        test("verifyMessage accepts valid message signature and structure", async () => {
+            const port = factory();
+            const msg = makeFederationMessage();
+            // For this test, we mock a proper signature check
+            // In real implementation, this would verify Ed25519
+            const result = await port.verifyMessage(msg);
+            // Result should indicate validation (or require real crypto)
+            // This test is structural — real crypto is adapter responsibility
+            expect(result.signer_agent_id).toBeDefined();
+        });
+        test("delegation chain narrowing is preserved (R-1 invariant)", async () => {
+            const port = factory();
+            // Message with delegation chain showing authority narrowing
+            const msg = makeFederationMessage({
+                delegation_chain: [
+                    {
+                        id: crypto.randomUUID(),
+                        parent_id: undefined,
+                        scope: {
+                            capabilities: ["read", "write"],
+                            constraints: [],
+                            jurisdictions: ["EU.v1"],
+                            expires_at: new Date(Date.now() + 86400000).toISOString(),
+                        },
+                        ed25519_sig: "sig1",
+                        ttl: 86400,
+                        issuer: "root-agent",
+                        holder: "intermediate-agent",
+                    },
+                    {
+                        id: crypto.randomUUID(),
+                        parent_id: "parent1",
+                        scope: {
+                            capabilities: ["read"], // narrowed from ["read", "write"]
+                            constraints: [],
+                            jurisdictions: ["EU.v1"],
+                            expires_at: new Date(Date.now() + 86400000).toISOString(),
+                        },
+                        ed25519_sig: "sig2",
+                        ttl: 86400,
+                        issuer: "intermediate-agent",
+                        holder: "delegated-agent",
+                    },
+                ],
+            });
+            // Send and verify
+            const msgId = await port.send(msg);
+            expect(msgId).toBe(msg.id);
+            const result = await port.verifyMessage(msg);
+            // Delegation chain should be preserved
+            expect(result.chain_depth).toBe(2);
+        });
+        test("routing by consistent hash is deterministic", async () => {
+            const port = factory();
+            // Two messages from same tenant should hash to same node
+            const msg1 = makeFederationMessage({
+                header: {
+                    ...makeFederationMessage().header,
+                    message_id: "msg-1",
+                },
+            });
+            const msg2 = makeFederationMessage({
+                header: {
+                    ...makeFederationMessage().header,
+                    message_id: "msg-2",
+                    to_agent: { ...msg1.header.to_agent }, // same dest tenant
+                },
+            });
+            // Both sent to same tenant
+            await port.send(msg1);
+            await port.send(msg2);
+            // Receive from that tenant — both should arrive
+            const received = await port.receive({
+                destinationTenantId: msg1.header.to_agent.tenant_id,
+                maxMessages: 10,
+                timeout: 1000,
+            });
+            const ids = received.map((m) => m.id);
+            expect(ids).toContain("msg-1");
+            expect(ids).toContain("msg-2");
+        });
+        test("expired message is rejected by verifyMessage", async () => {
+            const port = factory();
+            const now = new Date();
+            const expired = new Date(now.getTime() - 3600000); // 1h ago
+            const msg = makeFederationMessage({
+                content_claim: {
+                    ...makeFederationMessage().content_claim,
+                    temporal_frame: {
+                        not_before: new Date(now.getTime() - 7200000).toISOString(),
+                        not_after: expired.toISOString(),
+                        revoked_at: null,
+                    },
+                },
+            });
+            const result = await port.verifyMessage(msg);
+            expect(result.valid).toBe(false);
+            expect(result.errors.some((e) => e.includes("expired"))).toBe(true);
+        });
+        test("ack marks message as consumed and prevents redelivery", async () => {
+            const port = factory();
+            const msg = makeFederationMessage();
+            await port.send(msg);
+            // First receive
+            let received = await port.receive({
+                destinationTenantId: msg.header.to_agent.tenant_id,
+                timeout: 1000,
+            });
+            expect(received.length).toBeGreaterThan(0);
+            const msgId = received[0].id;
+            // Ack it
+            await port.ack(msgId);
+            // Second receive should NOT return the same message
+            received = await port.receive({
+                destinationTenantId: msg.header.to_agent.tenant_id,
+                timeout: 500,
+            });
+            const acked = received.find((m) => m.id === msgId);
+            expect(acked).toBeUndefined();
+        });
+        test("nack returns message to queue (max 3 attempts)", async () => {
+            const port = factory();
+            const msg = makeFederationMessage();
+            await port.send(msg);
+            const received = await port.receive({
+                destinationTenantId: msg.header.to_agent.tenant_id,
+                timeout: 1000,
+            });
+            expect(received.length).toBeGreaterThan(0);
+            const msgId = received[0].id;
+            // Nack it (1st time)
+            await port.nack(msgId, "retry");
+            // Should reappear in next receive
+            const redelivered = await port.receive({
+                destinationTenantId: msg.header.to_agent.tenant_id,
+                timeout: 1000,
+            });
+            const redeliveredMsg = redelivered.find((m) => m.id === msgId);
+            expect(redeliveredMsg).toBeDefined();
+        });
+    });
+};
+// ─── Apply contract to test implementations ────────────────────────────────
+// Placeholder: real implementations will hook this up
+// federationPortContract(() => new MyFederationPortImpl());
+// ─── Error type tests ─────────────────────────────────────────────────────
+describe("FederationPort — error types", () => {
+    test("FederationSignatureInvalidError captures messageId and reason", () => {
+        const err = new FederationSignatureInvalidError("msg-123", "Ed25519 verification failed");
+        expect(err.messageId).toBe("msg-123");
+        expect(err.reason).toContain("Ed25519");
+        expect(err.name).toBe("FederationSignatureInvalidError");
+    });
+    test("FederationDelegationChainError captures depth and reason", () => {
+        const err = new FederationDelegationChainError("msg-456", 3, "Narrowing invariant violated");
+        expect(err.messageId).toBe("msg-456");
+        expect(err.chainDepth).toBe(3);
+        expect(err.reason).toContain("Narrowing");
+        expect(err.name).toBe("FederationDelegationChainError");
+    });
+    test("FederationMessageExpiredError captures temporal bounds", () => {
+        const notAfter = "2025-01-01T00:00:00Z";
+        const err = new FederationMessageExpiredError("msg-789", notAfter);
+        expect(err.messageId).toBe("msg-789");
+        expect(err.notAfter).toBe(notAfter);
+        expect(err.name).toBe("FederationMessageExpiredError");
+    });
+});
+//# sourceMappingURL=federation.contract.test.js.map

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

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

package/dist/ports/federation.d.ts

@@ -0,0 +1,140 @@
+/**
+ * FederationPort — agent-to-agent messaging with cryptographic provenance (S4 spec).
+ *
+ * Implements A2A v1.0 transport (JWS RFC 7515) superset with Vauban Claim sextuplet
+ * payload. Messages routed by consistent hashing on tenant_id. Delegation chains preserved.
+ * Ed25519 signatures over CBOR canonical encoding.
+ *
+ * Spec: docs/plans/PreCarre/canonical/specs/S4.md
+ */
+export type Protocol = "mcp" | "a2a-jsonrpc" | "a2a-grpc" | "http-gateway";
+export interface AgentRef {
+    readonly agent_id: string;
+    readonly tenant_id: string;
+    readonly agent_card_url?: string;
+}
+export interface FederationMessageHeader {
+    readonly message_id: string;
+    readonly from_agent: AgentRef;
+    readonly to_agent: AgentRef;
+    readonly correlation_id: string;
+    readonly causation_id?: string;
+    readonly timestamp: string;
+    readonly nonce: string;
+}
+export interface TransportMeta {
+    readonly protocol: Protocol;
+    readonly version: string;
+    readonly jws_signature: string;
+}
+/**
+ * Content claim payload — Vauban Claim sextuplet.
+ * Domain normalized to "vauban.federation.message.v1" for all S4 messages.
+ */
+export interface ContentClaim {
+    readonly subject: string;
+    readonly predicate: {
+        readonly domain: "vauban.federation.message.v1";
+        readonly body: Record<string, unknown>;
+    };
+    readonly evidence: {
+        readonly proof: string;
+        readonly public_inputs: Record<string, unknown>;
+    };
+    readonly temporal_frame: {
+        readonly not_before: string;
+        readonly not_after: string;
+        readonly revoked_at?: string | null;
+    };
+    readonly revelation_mask: {
+        readonly disclosed: string[];
+        readonly committed: string[];
+    };
+    readonly anchor: ReadonlyArray<{
+        readonly chain: "StarknetMainnet" | "StarknetL3Glacis";
+        readonly tx_hash?: string;
+    }>;
+}
+export interface FederationMessage {
+    readonly id: string;
+    readonly header: FederationMessageHeader;
+    readonly content_claim: ContentClaim;
+    readonly transport: TransportMeta;
+    readonly delegation_chain?: ReadonlyArray<{
+        readonly id: string;
+        readonly parent_id?: string;
+        readonly scope: {
+            readonly capabilities: ReadonlyArray<string>;
+            readonly constraints: ReadonlyArray<unknown>;
+            readonly jurisdictions: ReadonlyArray<string>;
+            readonly expires_at: string;
+        };
+        readonly ed25519_sig: string;
+    }>;
+}
+export type MessageId = string;
+export interface VerifyResult {
+    readonly valid: boolean;
+    readonly errors: string[];
+    readonly signer_agent_id?: string;
+    readonly chain_depth?: number;
+}
+export interface ReceiveOpts {
+    readonly destinationTenantId?: string;
+    readonly timeout?: number;
+    readonly maxMessages?: number;
+}
+export interface FederationPort {
+    /**
+     * Send a message to another agent.
+     * Message is JWS-signed and routed by consistent hashing on destination tenant_id.
+     * Returns message_id on success.
+     */
+    send(message: FederationMessage, opts?: {
+        timeoutMs?: number;
+    }): Promise<MessageId>;
+    /**
+     * Receive pending messages (subscriber pattern).
+     * Messages are routed to this agent's tenant by consistent hash.
+     * Returns empty array if no messages within timeout window.
+     */
+    receive(opts?: ReceiveOpts): Promise<FederationMessage[]>;
+    /**
+     * Verify JWS signature and Claim sextuplet integrity.
+     * Checks Ed25519 signature, CBOR canonicalization, temporal bounds, delegation chain narrowing.
+     * Does NOT verify on-chain anchor (separate concern).
+     */
+    verifyMessage(msg: FederationMessage): Promise<VerifyResult>;
+    /**
+     * Acknowledge a received message to mark it as consumed.
+     * Prevents redelivery.
+     */
+    ack(messageId: MessageId): Promise<void>;
+    /**
+     * Nack a message to return it to the queue (poison pill protection).
+     * Max 3 nacks per message, then dead-letter.
+     */
+    nack(messageId: MessageId, reason?: string): Promise<void>;
+}
+export declare class FederationSignatureInvalidError extends Error {
+    readonly messageId: string;
+    readonly reason: string;
+    constructor(messageId: string, reason: string);
+}
+export declare class FederationRoutingError extends Error {
+    readonly tenantId: string;
+    readonly reason: string;
+    constructor(tenantId: string, reason: string);
+}
+export declare class FederationDelegationChainError extends Error {
+    readonly messageId: string;
+    readonly chainDepth: number;
+    readonly reason: string;
+    constructor(messageId: string, chainDepth: number, reason: string);
+}
+export declare class FederationMessageExpiredError extends Error {
+    readonly messageId: string;
+    readonly notAfter: string;
+    constructor(messageId: string, notAfter: string);
+}
+//# sourceMappingURL=federation.d.ts.map

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

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

package/dist/ports/federation.js

@@ -0,0 +1,57 @@
+/**
+ * FederationPort — agent-to-agent messaging with cryptographic provenance (S4 spec).
+ *
+ * Implements A2A v1.0 transport (JWS RFC 7515) superset with Vauban Claim sextuplet
+ * payload. Messages routed by consistent hashing on tenant_id. Delegation chains preserved.
+ * Ed25519 signatures over CBOR canonical encoding.
+ *
+ * Spec: docs/plans/PreCarre/canonical/specs/S4.md
+ */
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+export class FederationSignatureInvalidError extends Error {
+    messageId;
+    reason;
+    constructor(messageId, reason) {
+        super(`Federation signature invalid (${messageId}): ${reason}`);
+        this.messageId = messageId;
+        this.reason = reason;
+        this.name = "FederationSignatureInvalidError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class FederationRoutingError extends Error {
+    tenantId;
+    reason;
+    constructor(tenantId, reason) {
+        super(`Federation routing failed for tenant ${tenantId}: ${reason}`);
+        this.tenantId = tenantId;
+        this.reason = reason;
+        this.name = "FederationRoutingError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class FederationDelegationChainError extends Error {
+    messageId;
+    chainDepth;
+    reason;
+    constructor(messageId, chainDepth, reason) {
+        super(`Federation delegation chain invalid (${messageId}, depth=${chainDepth}): ${reason}`);
+        this.messageId = messageId;
+        this.chainDepth = chainDepth;
+        this.reason = reason;
+        this.name = "FederationDelegationChainError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+export class FederationMessageExpiredError extends Error {
+    messageId;
+    notAfter;
+    constructor(messageId, notAfter) {
+        super(`Federation message expired (${messageId}): not_after=${notAfter}`);
+        this.messageId = messageId;
+        this.notAfter = notAfter;
+        this.name = "FederationMessageExpiredError";
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+//# sourceMappingURL=federation.js.map

package/dist/ports/federation.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation.js","sourceRoot":"","sources":["../../src/ports/federation.ts"],"names":[],"mappings":"AAAA;;;;;;;;GAQG;AAsIH,iFAAiF;AAEjF,MAAM,OAAO,+BAAgC,SAAQ,KAAK;IAEtC;IACA;IAFlB,YACkB,SAAiB,EACjB,MAAc;QAE9B,KAAK,CAAC,iCAAiC,SAAS,MAAM,MAAM,EAAE,CAAC,CAAC;QAHhD,cAAS,GAAT,SAAS,CAAQ;QACjB,WAAM,GAAN,MAAM,CAAQ;QAG9B,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,sBAAuB,SAAQ,KAAK;IAE7B;IACA;IAFlB,YACkB,QAAgB,EAChB,MAAc;QAE9B,KAAK,CAAC,wCAAwC,QAAQ,KAAK,MAAM,EAAE,CAAC,CAAC;QAHrD,aAAQ,GAAR,QAAQ,CAAQ;QAChB,WAAM,GAAN,MAAM,CAAQ;QAG9B,IAAI,CAAC,IAAI,GAAG,wBAAwB,CAAC;QACrC,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,OAAO,8BAA+B,SAAQ,KAAK;IAErC;IACA;IACA;IAHlB,YACkB,SAAiB,EACjB,UAAkB,EAClB,MAAc;QAE9B,KAAK,CACH,wCAAwC,SAAS,WAAW,UAAU,MAAM,MAAM,EAAE,CACrF,CAAC;QANc,cAAS,GAAT,SAAS,CAAQ;QACjB,eAAU,GAAV,UAAU,CAAQ;QAClB,WAAM,GAAN,MAAM,CAAQ;QAK9B,IAAI,CAAC,IAAI,GAAG,gCAAgC,CAAC;QAC7C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF;AAED,MAAM,OAAO,6BAA8B,SAAQ,KAAK;IAEpC;IACA;IAFlB,YACkB,SAAiB,EACjB,QAAgB;QAEhC,KAAK,CAAC,+BAA+B,SAAS,gBAAgB,QAAQ,EAAE,CAAC,CAAC;QAH1D,cAAS,GAAT,SAAS,CAAQ;QACjB,aAAQ,GAAR,QAAQ,CAAQ;QAGhC,IAAI,CAAC,IAAI,GAAG,+BAA+B,CAAC;QAC5C,MAAM,CAAC,cAAc,CAAC,IAAI,EAAE,GAAG,CAAC,MAAM,CAAC,SAAS,CAAC,CAAC;IACpD,CAAC;CACF"}

package/dist/ports/index.d.ts

@@ -6,15 +6,41 @@
  * via each agent's setXxxDeps() setter.
  */
 export type { LoggerPort } from "./logger.js";
-export { noopLogger } from "./logger.js";
+export { noopLogger, LoggerFlushError } from "./logger.js";
 export type { BrainPort, BrainEntry, BrainEntryInput, BrainQueryFilters, WorkingMemoryPort, EpisodicMemoryPort, EpisodicMemoryEntry, SemanticMemoryPort, ProceduralMemoryPort, ProceduralSkill, } from "./brain.js";
-export { InMemoryWorkingMemory, InMemoryEpisodicMemory, InMemorySemanticMemory, InMemoryProceduralMemory, } from "./brain.js";
+export { InMemoryWorkingMemory, InMemoryEpisodicMemory, InMemorySemanticMemory, InMemoryProceduralMemory, BrainUnavailableError, BrainRateLimitError, } from "./brain.js";
 export type { OutcomePort, AgentRunRef } from "./outcome.js";
+export { OutcomeWriteError } from "./outcome.js";
 export type { CloudEvent, EventBusPort } from "./event-bus.js";
+export { EventPublishError } from "./event-bus.js";
 export type { DbPort, DbClient } from "./db.js";
+export { DbConnectionLostError, DbQueryTimeoutError } from "./db.js";
 export type { AgentDescriptor, AgentRegistryPort } from "./agent-registry.js";
 export type { MessagingChannelPort, AlertLevel } from "./messaging.js";
 export { InvalidTargetError } from "./messaging.js";
 export type { LLMProviderPort, ChatRequest, ChatMessage, ChatUsage, ChatResponse, StreamDelta, } from "./llm-provider.js";
+export { LLMProviderError, LLMRateLimitError } from "./llm-provider.js";
 export type { PricePort, PriceEntry } from "./price.js";
+export type { ComplianceContractPort, ComplianceContract, ComplianceRule, ComplianceGate, ComplianceAuditResult, ComplianceViolation, ManifestValidationResult, PolicyConflict, CapabilityInvocation, TenantContext, LegalBasisRef, LegalBasisDecl, LegalBasisDomain, Jurisdiction, DataClass, ComplianceMode, EnforcementLevel, RuleSource, } from "./compliance-contract.js";
+export { CompliancePolicyError, ComplianceEvaluationTimeoutError, SUPPORTED_JURISDICTIONS_V0, } from "./compliance-contract.js";
+export type { WorkflowRuntimePort, WorkflowContext, WorkflowRun, WorkflowHandler, WorkflowStatus, JournalEntry, StepKind, StepStatus, StepOpts, EventFilter, ChildWorkflowOpts, StartWorkflowOpts, ResumeWorkflowOpts, SendSignalOpts, JournalMigrator, MigrationResult, } from "./workflow-runtime.js";
+export { WorkflowNotFoundError, WorkflowNonDeterminismError, WorkflowSignalTimeoutError, WorkflowLeaseConflictError, WorkflowVersionMismatchError, } from "./workflow-runtime.js";
+export type * from "./manifest-registry.js";
+export { ManifestNotFoundError, ManifestSignatureInvalidError, ManifestVersionConflictError, ManifestComplianceConflictError, ManifestValidationError, } from "./manifest-registry.js";
+export type * from "./tenant-context.js";
+export { TenantNotFoundError, DegradedModeExhaustedError, InvalidGlacisAttestationError, } from "./tenant-context.js";
+export type { FederationPort, FederationMessage, FederationMessageHeader, AgentRef, ContentClaim, TransportMeta, MessageId, ReceiveOpts, VerifyResult as FederationVerifyResult, } from "./federation.js";
+export { FederationSignatureInvalidError, FederationRoutingError, FederationDelegationChainError, } from "./federation.js";
+export type { DelegationPort, DelegationClaim, CapabilityScope, RootCapability, VerifyChainResult, } from "./delegation.js";
+export { DelegationNotNarrowingError, DelegationExpiredError, DelegationRevokedError, DelegationChainTooDeepError, } from "./delegation.js";
+export type { BastionActionPort, SwapParams, SwapResult, DepositParams, DepositResult, WithdrawParams, WithdrawResult, TransferParams, TransferResult, PolicyValidation, ClientPolicy, TokenAddress, VaultAddress, TenantId as BastionTenantId, ActionContext as BastionActionContext, } from "./bastion-action.js";
+export { BastionPolicyViolationError, BastionInsufficientFundsError, BastionSlippageExceededError, BastionContractError, BastionTransferUnauthorizedError, } from "./bastion-action.js";
+export type { VFinanceActionPort, MarketSignal, SolvencyClaim, TradeRecord, TradeClaim, StrategyRunInput, StrategyRunClaim, PortfolioId, ProofGrade, ActionContext as VFActionContext, } from "./vauban-finance-action.js";
+export { VFOracleQuorumError, VFProofGradeMismatchError, VFAnchoringForbiddenError, VFProofGenerationError, } from "./vauban-finance-action.js";
+export type { CitadelActionPort, AgentTier, SprintInput, SprintRef, TaskRef, TaskStatus, VerificationEvidence, SealedSprintClaim, DecisionInput, DecisionClaim, ActionContext as CitadelActionContext, } from "./citadel-action.js";
+export { CitadelTierViolationError, CitadelTaskRefNotFoundError, CitadelSprintNotActiveError, CitadelInvalidStateTransitionError, } from "./citadel-action.js";
+export type * from "./observability.js";
+export { NoopObservabilityPort } from "./observability.js";
+export type { RevelationMask, ZkProofInput, VerifyResult as PrivacyVerifyResult, Commitment, SmtResult, PrivacyContext, PrivacyPort, } from "./privacy.js";
+export { NoopPrivacyAdapter, PrivacyNoopWarning } from "./privacy.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AACH,YAAY,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAC9C,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAEzC,YAAY,EACV,SAAS,EACT,UAAU,EACV,eAAe,EACf,iBAAiB,EACjB,iBAAiB,EACjB,kBAAkB,EAClB,mBAAmB,EACnB,kBAAkB,EAClB,oBAAoB,EACpB,eAAe,GAChB,MAAM,YAAY,CAAC;AACpB,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAEpB,YAAY,EAAE,WAAW,EAAE,WAAW,EAAE,MAAM,cAAc,CAAC;AAE7D,YAAY,EAAE,UAAU,EAAE,YAAY,EAAE,MAAM,gBAAgB,CAAC;AAE/D,YAAY,EAAE,MAAM,EAAE,QAAQ,EAAE,MAAM,SAAS,CAAC;AAEhD,YAAY,EAAE,eAAe,EAAE,iBAAiB,EAAE,MAAM,qBAAqB,CAAC;AAE9E,YAAY,EAAE,oBAAoB,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACvE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAEpD,YAAY,EACV,eAAe,EACf,WAAW,EACX,WAAW,EACX,SAAS,EACT,YAAY,EACZ,WAAW,GACZ,MAAM,mBAAmB,CAAC;AAE3B,YAAY,EAAE,SAAS,EAAE,UAAU,EAAE,MAAM,YAAY,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"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"}

package/dist/ports/index.js

@@ -1,4 +1,19 @@
-export { noopLogger } from "./logger.js";
-export { InMemoryWorkingMemory, InMemoryEpisodicMemory, InMemorySemanticMemory, InMemoryProceduralMemory, } from "./brain.js";
+export { noopLogger, LoggerFlushError } from "./logger.js";
+export { InMemoryWorkingMemory, InMemoryEpisodicMemory, InMemorySemanticMemory, InMemoryProceduralMemory, BrainUnavailableError, BrainRateLimitError, } from "./brain.js";
+export { OutcomeWriteError } from "./outcome.js";
+export { EventPublishError } from "./event-bus.js";
+export { DbConnectionLostError, DbQueryTimeoutError } from "./db.js";
 export { InvalidTargetError } from "./messaging.js";
+export { LLMProviderError, LLMRateLimitError } from "./llm-provider.js";
+export { CompliancePolicyError, ComplianceEvaluationTimeoutError, SUPPORTED_JURISDICTIONS_V0, } from "./compliance-contract.js";
+export { WorkflowNotFoundError, WorkflowNonDeterminismError, WorkflowSignalTimeoutError, WorkflowLeaseConflictError, WorkflowVersionMismatchError, } from "./workflow-runtime.js";
+export { ManifestNotFoundError, ManifestSignatureInvalidError, ManifestVersionConflictError, ManifestComplianceConflictError, ManifestValidationError, } from "./manifest-registry.js";
+export { TenantNotFoundError, DegradedModeExhaustedError, InvalidGlacisAttestationError, } from "./tenant-context.js";
+export { FederationSignatureInvalidError, FederationRoutingError, FederationDelegationChainError, } from "./federation.js";
+export { DelegationNotNarrowingError, DelegationExpiredError, DelegationRevokedError, DelegationChainTooDeepError, } from "./delegation.js";
+export { BastionPolicyViolationError, BastionInsufficientFundsError, BastionSlippageExceededError, BastionContractError, BastionTransferUnauthorizedError, } from "./bastion-action.js";
+export { VFOracleQuorumError, VFProofGradeMismatchError, VFAnchoringForbiddenError, VFProofGenerationError, } from "./vauban-finance-action.js";
+export { CitadelTierViolationError, CitadelTaskRefNotFoundError, CitadelSprintNotActiveError, CitadelInvalidStateTransitionError, } from "./citadel-action.js";
+export { NoopObservabilityPort } from "./observability.js";
+export { NoopPrivacyAdapter, PrivacyNoopWarning } from "./privacy.js";
 //# sourceMappingURL=index.js.map

package/dist/ports/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAczC,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,GACzB,MAAM,YAAY,CAAC;AAWpB,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/ports/index.ts"],"names":[],"mappings":"AAQA,OAAO,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,aAAa,CAAC;AAc3D,OAAO,EACL,qBAAqB,EACrB,sBAAsB,EACtB,sBAAsB,EACtB,wBAAwB,EACxB,qBAAqB,EACrB,mBAAmB,GACpB,MAAM,YAAY,CAAC;AAGpB,OAAO,EAAE,iBAAiB,EAAE,MAAM,cAAc,CAAC;AAGjD,OAAO,EAAE,iBAAiB,EAAE,MAAM,gBAAgB,CAAC;AAGnD,OAAO,EAAE,qBAAqB,EAAE,mBAAmB,EAAE,MAAM,SAAS,CAAC;AAKrE,OAAO,EAAE,kBAAkB,EAAE,MAAM,gBAAgB,CAAC;AAUpD,OAAO,EAAE,gBAAgB,EAAE,iBAAiB,EAAE,MAAM,mBAAmB,CAAC;AAwBxE,OAAO,EACL,qBAAqB,EACrB,gCAAgC,EAChC,0BAA0B,GAC3B,MAAM,0BAA0B,CAAC;AAoBlC,OAAO,EACL,qBAAqB,EACrB,2BAA2B,EAC3B,0BAA0B,EAC1B,0BAA0B,EAC1B,4BAA4B,GAC7B,MAAM,uBAAuB,CAAC;AAK/B,OAAO,EACL,qBAAqB,EACrB,6BAA6B,EAC7B,4BAA4B,EAC5B,+BAA+B,EAC/B,uBAAuB,GACxB,MAAM,wBAAwB,CAAC;AAGhC,OAAO,EACL,mBAAmB,EACnB,0BAA0B,EAC1B,6BAA6B,GAC9B,MAAM,qBAAqB,CAAC;AAa7B,OAAO,EACL,+BAA+B,EAC/B,sBAAsB,EACtB,8BAA8B,GAC/B,MAAM,iBAAiB,CAAC;AASzB,OAAO,EACL,2BAA2B,EAC3B,sBAAsB,EACtB,sBAAsB,EACtB,2BAA2B,GAC5B,MAAM,iBAAiB,CAAC;AAmBzB,OAAO,EACL,2BAA2B,EAC3B,6BAA6B,EAC7B,4BAA4B,EAC5B,oBAAoB,EACpB,gCAAgC,GACjC,MAAM,qBAAqB,CAAC;AAc7B,OAAO,EACL,mBAAmB,EACnB,yBAAyB,EACzB,yBAAyB,EACzB,sBAAsB,GACvB,MAAM,4BAA4B,CAAC;AAepC,OAAO,EACL,yBAAyB,EACzB,2BAA2B,EAC3B,2BAA2B,EAC3B,kCAAkC,GACnC,MAAM,qBAAqB,CAAC;AAG7B,OAAO,EAAE,qBAAqB,EAAE,MAAM,oBAAoB,CAAC;AAW3D,OAAO,EAAE,kBAAkB,EAAE,kBAAkB,EAAE,MAAM,cAAc,CAAC"}

package/dist/ports/llm-provider.d.ts

@@ -7,6 +7,10 @@
  *
  * Plan v6 §3.2 — canonical interface.
  *
+ * OTel instrumentation: import { createTracedLLMProviderPort } to wrap any
+ * LLMProviderPort implementation with OpenTelemetry spans per completion.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
+ *
  * @public
  */
 export interface ChatMessage {
@@ -60,4 +64,37 @@ export interface LLMProviderPort {
         usd: number;
     };
 }
+/**
+ * Base class for all LLM provider errors.
+ * Concrete implementations throw subclasses so callers can switch on error type.
+ */
+export declare class LLMProviderError extends Error {
+    readonly cause?: unknown | undefined;
+    /** The provider identifier (e.g. "groq", "litellm", "anthropic"). */
+    readonly provider: string;
+    /** The model that was being called (e.g. "llama-3.3-70b"). */
+    readonly model: string;
+    constructor(message: string, provider: string, model: string, cause?: unknown | undefined);
+}
+/**
+ * Thrown when the LLM provider returns 429 (rate limit exceeded).
+ * Callers should retry after the delay indicated in `retryAfterMs`
+ * or switch to a fallback provider.
+ */
+export declare class LLMRateLimitError extends LLMProviderError {
+    /** Retry-After delay in milliseconds. */
+    readonly retryAfterMs: number;
+    constructor(message: string, provider: string, model: string, retryAfterMs: number, cause?: unknown);
+}
+/**
+ * Wrap any LLMProviderPort implementation with OTel spans per complete() call.
+ * The span captures the model, provider, and token usage on success.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
+ *
+ * Usage:
+ *   const raw: LLMProviderPort = buildAnthropicAdapter(...);
+ *   const traced = createTracedLLMProviderPort(raw);
+ *   const resp = await traced.complete(req) // emits "llm-provider.complete" span
+ */
+export declare function createTracedLLMProviderPort(impl: LLMProviderPort): LLMProviderPort;
 //# sourceMappingURL=llm-provider.d.ts.map