@vauban-org/agent-sdk 1.0.0 → 1.2.0

package/dist/ports/event-bus.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/ports/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG;AAIH,MAAM,WAAW,UAAU;IACzB,8DAA8D;IAC9D,EAAE,EAAE,MAAM,CAAC;IACX,qBAAqB;IACrB,WAAW,EAAE,KAAK,CAAC;IACnB,+DAA+D;IAC/D,MAAM,EAAE,MAAM,CAAC;IACf,gEAAgE;IAChE,IAAI,EAAE,MAAM,CAAC;IACb,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,oCAAoC;IACpC,eAAe,CAAC,EAAE,MAAM,CAAC;IACzB,yDAAyD;IACzD,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,8CAA8C;IAC9C,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,4CAA4C;IAC5C,aAAa,CAAC,EAAE,MAAM,CAAC;IACvB,0DAA0D;IAC1D,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,wEAAwE;IACxE,iBAAiB,CAAC,EAAE,MAAM,CAAC;CAC5B;AAID;;;GAGG;AACH,MAAM,MAAM,WAAW,GACnB,OAAO,GACP,QAAQ,GACR,gBAAgB,GAChB,OAAO,GACP,SAAS,GACT,QAAQ,GACR,IAAI,GACJ,QAAQ,CAAC;AAEb;;;;;;;GAOG;AACH,MAAM,WAAW,WAAW,CAAC,CAAC,GAAG,OAAO;IACtC,2DAA2D;IAC3D,IAAI,EAAE,MAAM,CAAC;IACb,wDAAwD;IACxD,MAAM,EAAE,WAAW,CAAC;IACpB,mEAAmE;IACnE,aAAa,EAAE,MAAM,CAAC;IACtB,sEAAsE;IACtE,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB;;;OAGG;IACH,cAAc,EAAE,MAAM,CAAC;IACvB,4CAA4C;IAC5C,SAAS,EAAE,MAAM,CAAC;IAClB,2EAA2E;IAC3E,aAAa,EAAE,MAAM,CAAC;IACtB,yDAAyD;IACzD,OAAO,EAAE,CAAC,CAAC;IACX;;;OAGG;IACH,SAAS,EAAE,MAAM,CAAC;CACnB;AAED,yFAAyF;AACzF,MAAM,WAAW,YAAY;IAC3B,WAAW,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC9B;AAID,MAAM,WAAW,YAAY;IAC3B;;;;;;;;OAQG;IACH,OAAO,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;IAE1D;;;;;;;;;;;OAWG;IACH,sBAAsB,CAAC,CAAC,EACtB,KAAK,EAAE,IAAI,CAAC,WAAW,CAAC,CAAC,CAAC,EAAE,WAAW,CAAC,EACxC,GAAG,EAAE,MAAM,GACV,OAAO,CAAC,IAAI,CAAC,CAAC;IAEjB;;;;;;;;;;;OAWG;IACH,eAAe,CAAC,CAAC,EACf,SAAS,EAAE,MAAM,EACjB,OAAO,EAAE,CAAC,KAAK,EAAE,WAAW,CAAC,CAAC,CAAC,KAAK,OAAO,CAAC,IAAI,CAAC,EACjD,IAAI,CAAC,EAAE;QAAE,OAAO,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GACxC,YAAY,CAAC;IAEhB;;;;;;OAMG;IACH,UAAU,CAAC,SAAS,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,aAAa,CAAC,WAAW,CAAC,CAAC;IAE1E;;OAEG;IACH,GAAG,IAAI;QACL,qCAAqC;QACrC,KAAK,IAAI,OAAO,CAAC,MAAM,CAAC,CAAC;QACzB,6DAA6D;QAC7D,MAAM,CAAC,OAAO,EAAE,MAAM,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;KACxC,CAAC;IAEF;;;OAGG;IACH,YAAY,CAAC,MAAM,EAAE,MAAM,EAAE,aAAa,EAAE,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACtE"}
+{"version":3,"file":"event-bus.d.ts","sourceRoot":"","sources":["../../src/ports/event-bus.ts"],"names":[],"mappings":"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"}

package/dist/ports/event-bus.js

@@ -19,7 +19,112 @@
  * ADR-ECO-017: Cross-product events MUST carry a DomainEvent signature.
  * Use DomainEvent for inter-product events and CloudEvent for intra-product.
  *
+ * OTel instrumentation: import { createTracedEventBusPort } to wrap any
+ * EventBusPort implementation with OpenTelemetry spans per publish/subscribe call.
+ * Gracefully degrades to noop spans when no OTel SDK is installed.
+ *
  * @public
  */
-export {};
+// ─── Typed errors ─────────────────────────────────────────────────────────────
+/**
+ * Thrown when an event could not be published to Redis (connection lost,
+ * stream key conflict, or OOM on XADD). The original event is available
+ * for retry or DLQ routing.
+ */
+export class EventPublishError extends Error {
+    cause;
+    /** The stream key the event was targeting. */
+    stream;
+    /** The event id (UUIDv7) that failed to publish. */
+    eventId;
+    constructor(message, stream, eventId, cause) {
+        super(message);
+        this.cause = cause;
+        this.name = "EventPublishError";
+        this.stream = stream;
+        this.eventId = eventId;
+        Object.setPrototypeOf(this, new.target.prototype);
+    }
+}
+import { SpanStatusCode, trace } from "@opentelemetry/api";
+const PORT_TRACER = trace.getTracer("vauban-agent-sdk.ports", "0.1.0");
+/**
+ * Wrap any EventBusPort implementation with OTel spans.
+ * Publishes and subscribeDomain calls each get a span with the event type
+ * and stream as attributes. Gracefully degrades to noop spans when no OTel
+ * SDK is installed.
+ *
+ * Usage:
+ *   const raw: EventBusPort = buildRedisEventBus(...);
+ *   const traced = createTracedEventBusPort(raw);
+ *   await traced.publish(event, "vault.events") // emits "event-bus.publish" span
+ */
+export function createTracedEventBusPort(impl) {
+    function spanName(op) {
+        return `event-bus.${op}`;
+    }
+    return {
+        async publish(event, stream) {
+            return PORT_TRACER.startActiveSpan(spanName("publish"), {
+                attributes: {
+                    "event.type": event.type,
+                    "event.stream": stream,
+                    "event.id": event.id,
+                    "vauban.port.name": "event-bus",
+                },
+            }, async (span) => {
+                try {
+                    await impl.publish(event, stream);
+                    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(event, key) {
+            return PORT_TRACER.startActiveSpan(spanName("publishWithIdempotency"), {
+                attributes: {
+                    "event.type": event.type,
+                    "event.idempotency_key": key,
+                    "vauban.port.name": "event-bus",
+                },
+            }, async (span) => {
+                try {
+                    await impl.publishWithIdempotency(event, key);
+                    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();
+                }
+            });
+        },
+        subscribeDomain(eventType, handler, opts) {
+            return impl.subscribeDomain(eventType, handler, opts);
+        },
+        replayFrom(streamKey, fromId) {
+            return impl.replayFrom(streamKey, fromId);
+        },
+        dlq() {
+            return impl.dlq();
+        },
+        pendingCount(stream, consumerGroup) {
+            return impl.pendingCount(stream, consumerGroup);
+        },
+    };
+}
 //# sourceMappingURL=event-bus.js.map

package/dist/ports/event-bus.js.map

@@ -1 +1 @@
-{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../src/ports/event-bus.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;GAsBG"}
+{"version":3,"file":"event-bus.js","sourceRoot":"","sources":["../../src/ports/event-bus.ts"],"names":[],"mappings":"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"}

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

@@ -0,0 +1,9 @@
+/**
+ * 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.
+ */
+export declare const federationPortContract: (factory: () => any) => void;
+//# sourceMappingURL=federation.contract.test.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"federation.contract.test.d.ts","sourceRoot":"","sources":["../../src/ports/federation.contract.test.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AA2FH,eAAO,MAAM,sBAAsB,GAAI,SAAS,MAAM,GAAG,SA0NxD,CAAC"}

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"}