agentic-qe 3.6.0 → 3.6.2

package/v3/dist/coordination/federation/federation-mailbox.d.ts

@@ -0,0 +1,215 @@
+/**
+ * Agentic QE v3 - Federation Mailbox
+ * ADR-064 Phase 4B: Routes messages between fleet instances
+ *
+ * The FederationMailbox manages cross-fleet communication for the AQE
+ * federation layer. It provides:
+ * - Service registration and discovery by domain
+ * - Heartbeat-based health monitoring with automatic degradation
+ * - Priority-based routing with fallback to domain-based discovery
+ * - Outbox/inbox queues for asynchronous transport integration
+ * - Subscription-based message delivery to local handlers
+ *
+ * Usage:
+ * ```typescript
+ * import { createFederationMailbox } from './federation-mailbox.js';
+ *
+ * const mailbox = createFederationMailbox({ localFleetId: 'fleet-a' });
+ *
+ * // Register a remote fleet
+ * mailbox.registerService('fleet-b', 'Coverage Fleet', ['coverage-analysis']);
+ *
+ * // Add a route
+ * mailbox.addRoute('test-generation', 'coverage-analysis', 'fleet-b', 10);
+ *
+ * // Send a message
+ * const msg = mailbox.send('fleet-b', 'test-generation', 'coverage-analysis',
+ *   'task-request', { spec: 'auth-module' });
+ *
+ * // Transport layer drains outbox and delivers
+ * const pending = mailbox.drainOutbox();
+ *
+ * // Subscribe to incoming messages
+ * const unsub = mailbox.onMessage((msg) => console.log(msg.type));
+ * mailbox.receive(incomingMessage);
+ * ```
+ */
+import type { FleetId, FederatedService, FederatedMessage, FederatedMessageType, FederationRoute, FederationHealth, FederationConfig } from './types.js';
+/** Handler for incoming federated messages */
+export type FederatedMessageHandler = (message: FederatedMessage) => void;
+/**
+ * Routes messages between fleet instances in a federated AQE deployment.
+ * Manages service registration, routing rules, and message queues.
+ *
+ * Messages flow through an outbox (for sending) and inbox (for receiving).
+ * A transport layer (not included) is responsible for physically moving
+ * messages between fleet instances by draining the outbox and calling
+ * `receive()` on the target mailbox.
+ */
+export declare class FederationMailbox {
+    private readonly config;
+    private readonly services;
+    private readonly routes;
+    private readonly outbox;
+    private readonly inbox;
+    private readonly handlers;
+    private messagesSent;
+    private messagesReceived;
+    constructor(config?: Partial<FederationConfig>);
+    /**
+     * Register a remote fleet service in the federation.
+     * The service is immediately marked as 'active' with a fresh heartbeat.
+     *
+     * @param fleetId - Unique fleet identifier
+     * @param name - Human-readable service name
+     * @param domains - QE domains this service handles
+     * @param metadata - Optional key-value metadata
+     * @returns Immutable snapshot of the registered service
+     * @throws Error if a service with the same fleetId is already registered
+     */
+    registerService(fleetId: FleetId, name: string, domains: string[], metadata?: Record<string, string>): FederatedService;
+    /**
+     * Deregister a service, removing it and all routes targeting it.
+     *
+     * @param fleetId - Fleet to deregister
+     * @returns True if the service existed and was removed
+     */
+    deregisterService(fleetId: FleetId): boolean;
+    /**
+     * Record a heartbeat from a remote service, updating its last-seen
+     * timestamp. If the service was degraded or unreachable, it is
+     * promoted back to 'active'.
+     *
+     * @param fleetId - Fleet sending the heartbeat
+     * @returns True if the service exists and the heartbeat was recorded
+     */
+    heartbeat(fleetId: FleetId): boolean;
+    /**
+     * Add a routing rule for cross-fleet message delivery.
+     * Routes are sorted by priority (descending) so highest-priority routes
+     * are evaluated first during resolution.
+     *
+     * @param sourceDomain - Source domain that sends messages
+     * @param targetDomain - Target domain that receives messages
+     * @param targetFleetId - Fleet this route delivers to
+     * @param priority - Route priority (higher = preferred, default 0)
+     * @returns Immutable snapshot of the created route
+     * @throws Error if the maximum number of routes has been reached
+     */
+    addRoute(sourceDomain: string, targetDomain: string, targetFleetId: FleetId, priority?: number): FederationRoute;
+    /**
+     * Remove a routing rule matching the source domain and target fleet.
+     *
+     * @param sourceDomain - Source domain of the route
+     * @param targetFleetId - Target fleet of the route
+     * @returns True if a matching route was found and removed
+     */
+    removeRoute(sourceDomain: string, targetFleetId: FleetId): boolean;
+    /**
+     * Send a message to a specific fleet or resolve the target via routing.
+     * When `targetFleetId` is `'any'`, the mailbox uses priority-based route
+     * resolution with fallback to domain-based service discovery.
+     *
+     * Messages are placed in the outbox for the transport layer to drain
+     * and deliver to the target fleet's mailbox.
+     *
+     * @param targetFleetId - Specific fleet ID or 'any' for route resolution
+     * @param sourceDomain - Domain context of the sender
+     * @param targetDomain - Domain the message is intended for
+     * @param type - Message type classification
+     * @param payload - Message payload
+     * @param options - Optional correlation ID and TTL
+     * @returns The created message
+     * @throws Error if no route can be resolved when targetFleetId is 'any'
+     */
+    send(targetFleetId: FleetId | 'any', sourceDomain: string, targetDomain: string, type: FederatedMessageType, payload: unknown, options?: {
+        correlationId?: string;
+        ttl?: number;
+    }): FederatedMessage;
+    /**
+     * Receive a message from a remote fleet. The message is placed in the
+     * inbox and all registered handlers are notified synchronously.
+     *
+     * @param message - The incoming federated message
+     */
+    receive(message: FederatedMessage): void;
+    /**
+     * Subscribe to incoming federated messages.
+     *
+     * @param handler - Callback invoked on each received message
+     * @returns Unsubscribe function
+     */
+    onMessage(handler: FederatedMessageHandler): () => void;
+    /**
+     * Drain the outbox, returning all pending outbound messages.
+     * The outbox is cleared after draining. The transport layer should
+     * call this periodically to deliver messages to remote fleets.
+     *
+     * @returns Array of messages that were in the outbox
+     */
+    drainOutbox(): FederatedMessage[];
+    /**
+     * Drain the inbox, returning all pending inbound messages.
+     * The inbox is cleared after draining.
+     *
+     * @returns Array of messages that were in the inbox
+     */
+    drainInbox(): FederatedMessage[];
+    /**
+     * Find active services that handle a specific domain.
+     *
+     * @param domain - QE domain to search for
+     * @returns Array of active services that list the domain
+     */
+    findServicesByDomain(domain: string): FederatedService[];
+    /**
+     * Get a service by its fleet ID.
+     *
+     * @param fleetId - Fleet identifier to look up
+     * @returns Service snapshot or undefined if not found
+     */
+    getService(fleetId: FleetId): FederatedService | undefined;
+    /**
+     * List all registered services (regardless of status).
+     *
+     * @returns Array of service snapshots
+     */
+    listServices(): FederatedService[];
+    /**
+     * List all routing rules.
+     *
+     * @returns Array of route snapshots
+     */
+    listRoutes(): FederationRoute[];
+    /**
+     * Check service health and update statuses based on heartbeat age.
+     * Services that have not sent a heartbeat within `serviceTimeoutMs`
+     * are marked 'unreachable'. Services past 60% of the timeout are
+     * marked 'degraded'.
+     */
+    checkHealth(): void;
+    /**
+     * Get a summary of the federation's current health.
+     *
+     * @returns Health snapshot with counts and counters
+     */
+    getHealth(): FederationHealth;
+    /**
+     * Dispose all state, clearing services, routes, queues, and handlers.
+     */
+    dispose(): void;
+    /**
+     * Resolve a route for the given source -> target domain pair.
+     * First checks explicit routes (sorted by priority), then falls back
+     * to domain-based service discovery.
+     */
+    private resolveRoute;
+}
+/**
+ * Create a new FederationMailbox instance.
+ *
+ * @param config - Optional partial configuration (merged with defaults)
+ * @returns A fresh FederationMailbox
+ */
+export declare function createFederationMailbox(config?: Partial<FederationConfig>): FederationMailbox;
+//# sourceMappingURL=federation-mailbox.d.ts.map

package/v3/dist/coordination/federation/federation-mailbox.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"federation-mailbox.d.ts","sourceRoot":"","sources":["../../../src/coordination/federation/federation-mailbox.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAmCG;AAGH,OAAO,KAAK,EACV,OAAO,EACP,gBAAgB,EAChB,gBAAgB,EAChB,oBAAoB,EACpB,eAAe,EACf,gBAAgB,EAChB,gBAAgB,EAEjB,MAAM,YAAY,CAAC;AAOpB,8CAA8C;AAC9C,MAAM,MAAM,uBAAuB,GAAG,CAAC,OAAO,EAAE,gBAAgB,KAAK,IAAI,CAAC;AAM1E;;;;;;;;GAQG;AACH,qBAAa,iBAAiB;IAC5B,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAmB;IAC1C,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAsC;IAC/D,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAsB;IAC7C,OAAO,CAAC,QAAQ,CAAC,MAAM,CAA0B;IACjD,OAAO,CAAC,QAAQ,CAAC,KAAK,CAA0B;IAChD,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAiC;IAC1D,OAAO,CAAC,YAAY,CAAK;IACzB,OAAO,CAAC,gBAAgB,CAAK;gBAEjB,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC;IAQ9C;;;;;;;;;;OAUG;IACH,eAAe,CACb,OAAO,EAAE,OAAO,EAChB,IAAI,EAAE,MAAM,EACZ,OAAO,EAAE,MAAM,EAAE,EACjB,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAChC,gBAAgB;IAkBnB;;;;;OAKG;IACH,iBAAiB,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAgB5C;;;;;;;OAOG;IACH,SAAS,CAAC,OAAO,EAAE,OAAO,GAAG,OAAO;IAcpC;;;;;;;;;;;OAWG;IACH,QAAQ,CACN,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,aAAa,EAAE,OAAO,EACtB,QAAQ,GAAE,MAAU,GACnB,eAAe;IAgBlB;;;;;;OAMG;IACH,WAAW,CAAC,YAAY,EAAE,MAAM,EAAE,aAAa,EAAE,OAAO,GAAG,OAAO;IAalE;;;;;;;;;;;;;;;;OAgBG;IACH,IAAI,CACF,aAAa,EAAE,OAAO,GAAG,KAAK,EAC9B,YAAY,EAAE,MAAM,EACpB,YAAY,EAAE,MAAM,EACpB,IAAI,EAAE,oBAAoB,EAC1B,OAAO,EAAE,OAAO,EAChB,OAAO,CAAC,EAAE;QAAE,aAAa,CAAC,EAAE,MAAM,CAAC;QAAC,GAAG,CAAC,EAAE,MAAM,CAAA;KAAE,GACjD,gBAAgB;IAkCnB;;;;;OAKG;IACH,OAAO,CAAC,OAAO,EAAE,gBAAgB,GAAG,IAAI;IAexC;;;;;OAKG;IACH,SAAS,CAAC,OAAO,EAAE,uBAAuB,GAAG,MAAM,IAAI;IAYvD;;;;;;OAMG;IACH,WAAW,IAAI,gBAAgB,EAAE;IAMjC;;;;;OAKG;IACH,UAAU,IAAI,gBAAgB,EAAE;IAUhC;;;;;OAKG;IACH,oBAAoB,CAAC,MAAM,EAAE,MAAM,GAAG,gBAAgB,EAAE;IAMxD;;;;;OAKG;IACH,UAAU,CAAC,OAAO,EAAE,OAAO,GAAG,gBAAgB,GAAG,SAAS;IAK1D;;;;OAIG;IACH,YAAY,IAAI,gBAAgB,EAAE;IAIlC;;;;OAIG;IACH,UAAU,IAAI,eAAe,EAAE;IAQ/B;;;;;OAKG;IACH,WAAW,IAAI,IAAI;IAanB;;;;OAIG;IACH,SAAS,IAAI,gBAAgB;IAgB7B;;OAEG;IACH,OAAO,IAAI,IAAI;IAYf;;;;OAIG;IACH,OAAO,CAAC,YAAY;CAsBrB;AAiED;;;;;GAKG;AACH,wBAAgB,uBAAuB,CACrC,MAAM,CAAC,EAAE,OAAO,CAAC,gBAAgB,CAAC,GACjC,iBAAiB,CAEnB"}

package/v3/dist/coordination/federation/federation-mailbox.js

@@ -0,0 +1,442 @@
+/**
+ * Agentic QE v3 - Federation Mailbox
+ * ADR-064 Phase 4B: Routes messages between fleet instances
+ *
+ * The FederationMailbox manages cross-fleet communication for the AQE
+ * federation layer. It provides:
+ * - Service registration and discovery by domain
+ * - Heartbeat-based health monitoring with automatic degradation
+ * - Priority-based routing with fallback to domain-based discovery
+ * - Outbox/inbox queues for asynchronous transport integration
+ * - Subscription-based message delivery to local handlers
+ *
+ * Usage:
+ * ```typescript
+ * import { createFederationMailbox } from './federation-mailbox.js';
+ *
+ * const mailbox = createFederationMailbox({ localFleetId: 'fleet-a' });
+ *
+ * // Register a remote fleet
+ * mailbox.registerService('fleet-b', 'Coverage Fleet', ['coverage-analysis']);
+ *
+ * // Add a route
+ * mailbox.addRoute('test-generation', 'coverage-analysis', 'fleet-b', 10);
+ *
+ * // Send a message
+ * const msg = mailbox.send('fleet-b', 'test-generation', 'coverage-analysis',
+ *   'task-request', { spec: 'auth-module' });
+ *
+ * // Transport layer drains outbox and delivers
+ * const pending = mailbox.drainOutbox();
+ *
+ * // Subscribe to incoming messages
+ * const unsub = mailbox.onMessage((msg) => console.log(msg.type));
+ * mailbox.receive(incomingMessage);
+ * ```
+ */
+import { randomUUID } from 'node:crypto';
+import { DEFAULT_FEDERATION_CONFIG } from './types.js';
+// ============================================================================
+// Federation Mailbox
+// ============================================================================
+/**
+ * Routes messages between fleet instances in a federated AQE deployment.
+ * Manages service registration, routing rules, and message queues.
+ *
+ * Messages flow through an outbox (for sending) and inbox (for receiving).
+ * A transport layer (not included) is responsible for physically moving
+ * messages between fleet instances by draining the outbox and calling
+ * `receive()` on the target mailbox.
+ */
+export class FederationMailbox {
+    config;
+    services = new Map();
+    routes = [];
+    outbox = [];
+    inbox = [];
+    handlers = [];
+    messagesSent = 0;
+    messagesReceived = 0;
+    constructor(config) {
+        this.config = { ...DEFAULT_FEDERATION_CONFIG, ...config };
+    }
+    // ============================================================================
+    // Service Registration
+    // ============================================================================
+    /**
+     * Register a remote fleet service in the federation.
+     * The service is immediately marked as 'active' with a fresh heartbeat.
+     *
+     * @param fleetId - Unique fleet identifier
+     * @param name - Human-readable service name
+     * @param domains - QE domains this service handles
+     * @param metadata - Optional key-value metadata
+     * @returns Immutable snapshot of the registered service
+     * @throws Error if a service with the same fleetId is already registered
+     */
+    registerService(fleetId, name, domains, metadata) {
+        if (this.services.has(fleetId)) {
+            throw new Error(`Service '${fleetId}' already registered`);
+        }
+        const now = Date.now();
+        const service = {
+            fleetId,
+            name,
+            domains: [...domains],
+            status: 'active',
+            registeredAt: now,
+            lastHeartbeat: now,
+            metadata,
+        };
+        this.services.set(fleetId, service);
+        return toServiceSnapshot(service);
+    }
+    /**
+     * Deregister a service, removing it and all routes targeting it.
+     *
+     * @param fleetId - Fleet to deregister
+     * @returns True if the service existed and was removed
+     */
+    deregisterService(fleetId) {
+        const service = this.services.get(fleetId);
+        if (!service)
+            return false;
+        service.status = 'deregistered';
+        // Remove routes pointing to this fleet
+        for (let i = this.routes.length - 1; i >= 0; i--) {
+            if (this.routes[i].targetFleetId === fleetId) {
+                this.routes.splice(i, 1);
+            }
+        }
+        this.services.delete(fleetId);
+        return true;
+    }
+    /**
+     * Record a heartbeat from a remote service, updating its last-seen
+     * timestamp. If the service was degraded or unreachable, it is
+     * promoted back to 'active'.
+     *
+     * @param fleetId - Fleet sending the heartbeat
+     * @returns True if the service exists and the heartbeat was recorded
+     */
+    heartbeat(fleetId) {
+        const service = this.services.get(fleetId);
+        if (!service)
+            return false;
+        service.lastHeartbeat = Date.now();
+        if (service.status === 'degraded' || service.status === 'unreachable') {
+            service.status = 'active';
+        }
+        return true;
+    }
+    // ============================================================================
+    // Routing
+    // ============================================================================
+    /**
+     * Add a routing rule for cross-fleet message delivery.
+     * Routes are sorted by priority (descending) so highest-priority routes
+     * are evaluated first during resolution.
+     *
+     * @param sourceDomain - Source domain that sends messages
+     * @param targetDomain - Target domain that receives messages
+     * @param targetFleetId - Fleet this route delivers to
+     * @param priority - Route priority (higher = preferred, default 0)
+     * @returns Immutable snapshot of the created route
+     * @throws Error if the maximum number of routes has been reached
+     */
+    addRoute(sourceDomain, targetDomain, targetFleetId, priority = 0) {
+        if (this.routes.length >= this.config.maxRoutes) {
+            throw new Error(`Maximum routes (${this.config.maxRoutes}) reached`);
+        }
+        const route = {
+            sourceDomain,
+            targetDomain,
+            targetFleetId,
+            priority,
+            active: true,
+        };
+        this.routes.push(route);
+        this.routes.sort((a, b) => b.priority - a.priority);
+        return toRouteSnapshot(route);
+    }
+    /**
+     * Remove a routing rule matching the source domain and target fleet.
+     *
+     * @param sourceDomain - Source domain of the route
+     * @param targetFleetId - Target fleet of the route
+     * @returns True if a matching route was found and removed
+     */
+    removeRoute(sourceDomain, targetFleetId) {
+        const idx = this.routes.findIndex(r => r.sourceDomain === sourceDomain && r.targetFleetId === targetFleetId);
+        if (idx < 0)
+            return false;
+        this.routes.splice(idx, 1);
+        return true;
+    }
+    // ============================================================================
+    // Message Sending
+    // ============================================================================
+    /**
+     * Send a message to a specific fleet or resolve the target via routing.
+     * When `targetFleetId` is `'any'`, the mailbox uses priority-based route
+     * resolution with fallback to domain-based service discovery.
+     *
+     * Messages are placed in the outbox for the transport layer to drain
+     * and deliver to the target fleet's mailbox.
+     *
+     * @param targetFleetId - Specific fleet ID or 'any' for route resolution
+     * @param sourceDomain - Domain context of the sender
+     * @param targetDomain - Domain the message is intended for
+     * @param type - Message type classification
+     * @param payload - Message payload
+     * @param options - Optional correlation ID and TTL
+     * @returns The created message
+     * @throws Error if no route can be resolved when targetFleetId is 'any'
+     */
+    send(targetFleetId, sourceDomain, targetDomain, type, payload, options) {
+        const resolvedTarget = targetFleetId === 'any'
+            ? this.resolveRoute(sourceDomain, targetDomain)
+            : targetFleetId;
+        if (!resolvedTarget) {
+            throw new Error(`No route found for ${sourceDomain} -> ${targetDomain}`);
+        }
+        const message = {
+            id: randomUUID(),
+            sourceFleetId: this.config.localFleetId,
+            targetFleetId: resolvedTarget,
+            sourceDomain,
+            targetDomain,
+            type,
+            payload,
+            timestamp: Date.now(),
+            ttl: options?.ttl,
+            correlationId: options?.correlationId,
+        };
+        if (this.outbox.length >= this.config.maxPendingMessages) {
+            this.outbox.shift(); // Drop oldest to stay within limit
+        }
+        this.outbox.push(message);
+        this.messagesSent++;
+        return message;
+    }
+    // ============================================================================
+    // Message Receiving
+    // ============================================================================
+    /**
+     * Receive a message from a remote fleet. The message is placed in the
+     * inbox and all registered handlers are notified synchronously.
+     *
+     * @param message - The incoming federated message
+     */
+    receive(message) {
+        if (this.inbox.length >= this.config.maxPendingMessages) {
+            this.inbox.shift(); // Drop oldest to stay within limit
+        }
+        this.inbox.push(message);
+        this.messagesReceived++;
+        for (const handler of this.handlers) {
+            try {
+                handler(message);
+            }
+            catch {
+                // Swallow handler errors to avoid breaking delivery
+            }
+        }
+    }
+    /**
+     * Subscribe to incoming federated messages.
+     *
+     * @param handler - Callback invoked on each received message
+     * @returns Unsubscribe function
+     */
+    onMessage(handler) {
+        this.handlers.push(handler);
+        return () => {
+            const idx = this.handlers.indexOf(handler);
+            if (idx >= 0)
+                this.handlers.splice(idx, 1);
+        };
+    }
+    // ============================================================================
+    // Queue Draining
+    // ============================================================================
+    /**
+     * Drain the outbox, returning all pending outbound messages.
+     * The outbox is cleared after draining. The transport layer should
+     * call this periodically to deliver messages to remote fleets.
+     *
+     * @returns Array of messages that were in the outbox
+     */
+    drainOutbox() {
+        const messages = [...this.outbox];
+        this.outbox.length = 0;
+        return messages;
+    }
+    /**
+     * Drain the inbox, returning all pending inbound messages.
+     * The inbox is cleared after draining.
+     *
+     * @returns Array of messages that were in the inbox
+     */
+    drainInbox() {
+        const messages = [...this.inbox];
+        this.inbox.length = 0;
+        return messages;
+    }
+    // ============================================================================
+    // Service Discovery
+    // ============================================================================
+    /**
+     * Find active services that handle a specific domain.
+     *
+     * @param domain - QE domain to search for
+     * @returns Array of active services that list the domain
+     */
+    findServicesByDomain(domain) {
+        return Array.from(this.services.values())
+            .filter(s => s.status === 'active' && s.domains.includes(domain))
+            .map(toServiceSnapshot);
+    }
+    /**
+     * Get a service by its fleet ID.
+     *
+     * @param fleetId - Fleet identifier to look up
+     * @returns Service snapshot or undefined if not found
+     */
+    getService(fleetId) {
+        const s = this.services.get(fleetId);
+        return s ? toServiceSnapshot(s) : undefined;
+    }
+    /**
+     * List all registered services (regardless of status).
+     *
+     * @returns Array of service snapshots
+     */
+    listServices() {
+        return Array.from(this.services.values()).map(toServiceSnapshot);
+    }
+    /**
+     * List all routing rules.
+     *
+     * @returns Array of route snapshots
+     */
+    listRoutes() {
+        return this.routes.map(toRouteSnapshot);
+    }
+    // ============================================================================
+    // Health Monitoring
+    // ============================================================================
+    /**
+     * Check service health and update statuses based on heartbeat age.
+     * Services that have not sent a heartbeat within `serviceTimeoutMs`
+     * are marked 'unreachable'. Services past 60% of the timeout are
+     * marked 'degraded'.
+     */
+    checkHealth() {
+        const now = Date.now();
+        for (const service of this.services.values()) {
+            if (service.status === 'deregistered')
+                continue;
+            const elapsed = now - service.lastHeartbeat;
+            if (elapsed > this.config.serviceTimeoutMs) {
+                service.status = 'unreachable';
+            }
+            else if (elapsed > this.config.serviceTimeoutMs * 0.6) {
+                service.status = 'degraded';
+            }
+        }
+    }
+    /**
+     * Get a summary of the federation's current health.
+     *
+     * @returns Health snapshot with counts and counters
+     */
+    getHealth() {
+        return {
+            localFleetId: this.config.localFleetId,
+            connectedServices: Array.from(this.services.values())
+                .filter(s => s.status === 'active').length,
+            activeRoutes: this.routes.filter(r => r.active).length,
+            pendingMessages: this.outbox.length + this.inbox.length,
+            messagesSent: this.messagesSent,
+            messagesReceived: this.messagesReceived,
+        };
+    }
+    // ============================================================================
+    // Lifecycle
+    // ============================================================================
+    /**
+     * Dispose all state, clearing services, routes, queues, and handlers.
+     */
+    dispose() {
+        this.services.clear();
+        this.routes.length = 0;
+        this.outbox.length = 0;
+        this.inbox.length = 0;
+        this.handlers.length = 0;
+    }
+    // ============================================================================
+    // Private Helpers
+    // ============================================================================
+    /**
+     * Resolve a route for the given source -> target domain pair.
+     * First checks explicit routes (sorted by priority), then falls back
+     * to domain-based service discovery.
+     */
+    resolveRoute(sourceDomain, targetDomain) {
+        // Check explicit routes in priority order
+        for (const route of this.routes) {
+            if (!route.active)
+                continue;
+            if (route.sourceDomain === sourceDomain &&
+                route.targetDomain === targetDomain) {
+                const service = this.services.get(route.targetFleetId);
+                if (service && service.status === 'active') {
+                    return route.targetFleetId;
+                }
+            }
+        }
+        // Fallback: find any active service that handles the target domain
+        const candidates = this.findServicesByDomain(targetDomain);
+        return candidates.length > 0 ? candidates[0].fleetId : undefined;
+    }
+}
+// ============================================================================
+// Snapshot Helpers
+// ============================================================================
+/** Create an immutable snapshot of a mutable service */
+function toServiceSnapshot(service) {
+    return {
+        fleetId: service.fleetId,
+        name: service.name,
+        domains: [...service.domains],
+        status: service.status,
+        registeredAt: service.registeredAt,
+        lastHeartbeat: service.lastHeartbeat,
+        metadata: service.metadata,
+        endpoint: undefined,
+    };
+}
+/** Create an immutable snapshot of a mutable route */
+function toRouteSnapshot(route) {
+    return {
+        sourceDomain: route.sourceDomain,
+        targetDomain: route.targetDomain,
+        targetFleetId: route.targetFleetId,
+        priority: route.priority,
+        active: route.active,
+    };
+}
+// ============================================================================
+// Factory Function
+// ============================================================================
+/**
+ * Create a new FederationMailbox instance.
+ *
+ * @param config - Optional partial configuration (merged with defaults)
+ * @returns A fresh FederationMailbox
+ */
+export function createFederationMailbox(config) {
+    return new FederationMailbox(config);
+}
+//# sourceMappingURL=federation-mailbox.js.map

package/v3/dist/coordination/federation/federation-mailbox.js.map

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