@claude-flow/cli 3.32.29 → 3.32.32

package/node_modules/@claude-flow/plugin-agent-federation/dist/application/federation-breaker-service.d.ts

@@ -0,0 +1,192 @@
+/**
+ * Federation circuit breaker service (ADR-097 Phase 2.b).
+ *
+ * Phase 2.a shipped the FederationNode state machine + canTransition table.
+ * This service is what drives transitions: it records per-peer send outcomes
+ * (success/failure + spend), evaluates thresholds against the configured
+ * policy, and calls suspend()/evict()/reactivate() on the entity.
+ *
+ * Architecture is two-layer to keep the policy testable in isolation:
+ *
+ *   1. **evaluatePolicy** (pure function) — given rolling samples for a peer
+ *      + the policy + now, returns a BreakerDecision describing what should
+ *      happen. No I/O, no clock, no entity mutation.
+ *   2. **FederationBreakerService** — owns the rolling-sample buffer,
+ *      wraps evaluatePolicy with the entity mutation step, and exposes
+ *      `recordOutcome` (called by the coordinator on each send completion)
+ *      + `tick` (called periodically to drive cooldown/auto-evict).
+ *
+ * The cost-tracker integration (Phase 3 upstream — emits federation_spend
+ * events when sends complete) is *not* wired here; this service holds its
+ * own in-memory rolling buffer. When Phase 3 upstream lands, the consumer
+ * can call `recordOutcome` from the bus subscriber and the buffer becomes
+ * a transparent cache. This keeps Phase 2 deliverable without a hard
+ * cost-tracker dependency.
+ *
+ * Security invariants:
+ *
+ *   1. Negative tokens/usd are clamped to 0 — a malicious receive-side
+ *      reporter cannot drive an "unsuspend" through credit inflation.
+ *   2. Sample buffer is bounded per-peer (DEFAULT_MAX_SAMPLES_PER_PEER) so
+ *      a high-throughput peer cannot exhaust memory.
+ *   3. Policy evaluation is order-independent for SUSPEND triggers —
+ *      cost OR failure-ratio fires the same SUSPEND. The reason field
+ *      records which one tripped.
+ *   4. evaluatePolicy is pure & deterministic given (samples, policy, now)
+ *      — no Date.now() calls inside, no random IDs, no hidden state.
+ *   5. Auto-eviction only runs from SUSPENDED state and only after the
+ *      grace age. Cannot skip SUSPENDED for an ACTIVE → EVICTED jump.
+ */
+import { FederationNode } from '../domain/entities/federation-node.js';
+import { SuspensionReason } from '../domain/value-objects/federation-node-state.js';
+/** A single send outcome recorded by the coordinator. */
+export interface SendOutcome {
+    readonly nodeId: string;
+    readonly success: boolean;
+    /** Tokens consumed by this leg. Negative values are treated as 0. */
+    readonly tokensUsed?: number;
+    /** USD spent on this leg. Negative values are treated as 0. */
+    readonly usdSpent?: number;
+    /** Caller-supplied timestamp (for testability). Defaults to recordOutcome's `now`. */
+    readonly at?: Date;
+}
+/** Configurable thresholds. All defaults come from ADR-097 Part 2. */
+export interface BreakerPolicy {
+    /** 24h spend cap per peer. Default $5.00. */
+    readonly costSuspensionUsd: number;
+    /** Window for the cost cap. Default 24h. */
+    readonly costWindowMs: number;
+    /** Failure ratio that trips the breaker. Default 0.5 (50%). */
+    readonly failureRatioThreshold: number;
+    /** Window for failure-ratio computation. Default 1h. */
+    readonly failureWindowMs: number;
+    /** Minimum samples in the failure window before evaluating (anti-noise). Default 10. */
+    readonly failureMinSamples: number;
+    /** Cooldown before SUSPENDED → reactivate-eligible. Default 30min. */
+    readonly cooldownMs: number;
+    /** Continuous suspension age before auto-evict. Default 24h. */
+    readonly autoEvictionAgeMs: number;
+}
+export declare const DEFAULT_BREAKER_POLICY: BreakerPolicy;
+/** Per-peer sample buffer cap. ~24h of 1-Hz traffic. */
+export declare const DEFAULT_MAX_SAMPLES_PER_PEER = 100000;
+/** A normalized, time-stamped outcome (negatives clamped, `at` resolved). */
+interface NormalizedSample {
+    readonly success: boolean;
+    readonly tokensUsed: number;
+    readonly usdSpent: number;
+    readonly at: Date;
+}
+/**
+ * What the breaker decided for a peer at evaluation time. The service then
+ * applies the action (calls node.suspend()/evict()/reactivate()) but the
+ * decision itself is a pure return so tests can assert it without checking
+ * mutated state.
+ */
+export type BreakerDecision = {
+    readonly action: 'NONE';
+    readonly nodeId: string;
+} | {
+    readonly action: 'SUSPEND';
+    readonly nodeId: string;
+    readonly reason: SuspensionReason;
+} | {
+    readonly action: 'EVICT';
+    readonly nodeId: string;
+    readonly reason: SuspensionReason;
+} | {
+    readonly action: 'REACTIVATE_ELIGIBLE';
+    readonly nodeId: string;
+};
+/**
+ * Pure policy evaluator. Returns the decision the breaker should apply.
+ * No I/O, no clock, no entity mutation — given the same inputs, returns the
+ * same output. The service layer is responsible for calling node.suspend()
+ * / evict() / reactivate() based on this.
+ *
+ * Decision rules:
+ *
+ *   For ACTIVE peers:
+ *     - 24h cost > policy.costSuspensionUsd → SUSPEND/COST_THRESHOLD_EXCEEDED
+ *     - 1h failure ratio > policy.failureRatioThreshold (≥ failureMinSamples
+ *       in window) → SUSPEND/FAILURE_RATIO_EXCEEDED
+ *     - else NONE
+ *
+ *   For SUSPENDED peers:
+ *     - suspended ≥ autoEvictionAgeMs → EVICT/GRACE_PERIOD_EXPIRED
+ *     - cooldown elapsed → REACTIVATE_ELIGIBLE (caller probes + reactivates)
+ *     - else NONE
+ *
+ *   For EVICTED peers: always NONE (terminal under breaker flow).
+ *
+ * Cost takes priority over failure-ratio when both trip, because cost is
+ * the more conservative signal (a malicious peer can manufacture failures
+ * by trickling errors but cannot manufacture spend without actually
+ * burning budget).
+ */
+export declare function evaluatePolicy(samples: readonly NormalizedSample[], node: FederationNode, policy: BreakerPolicy, now: Date): BreakerDecision;
+/**
+ * Stateful service: owns the per-peer sample buffer, applies decisions to
+ * entities, and exposes the breaker control surface to the coordinator.
+ *
+ * Construct once per federation coordinator. Inject the policy if you need
+ * non-default thresholds (Phase 4 doctor surface will let users tune them).
+ */
+/**
+ * ADR-111 Phase 3 — callback invoked after the breaker applies a successful
+ * state transition. Used by the coordinator to propagate suspends to the
+ * WG mesh layer (clearing AllowedIPs). Not invoked for `apply=false` dry runs
+ * or `NONE` / `REACTIVATE_ELIGIBLE` decisions. Errors thrown from the callback
+ * are swallowed at the breaker — the entity transition has already happened,
+ * and side-effect failures shouldn't unwind the breaker's internal state.
+ */
+export type BreakerTransitionListener = (node: FederationNode, decision: BreakerDecision) => void | Promise<void>;
+export declare class FederationBreakerService {
+    private readonly policy;
+    private readonly samples;
+    private readonly maxSamplesPerPeer;
+    private readonly onTransition?;
+    constructor(policy?: BreakerPolicy, maxSamplesPerPeer?: number, onTransition?: BreakerTransitionListener);
+    /** Read the active policy (handy for tests + doctor surface). */
+    getPolicy(): BreakerPolicy;
+    /**
+     * Record a send outcome for a peer. Called by the coordinator after each
+     * `routing.send` completion. Returns a BreakerDecision describing what,
+     * if anything, the breaker would do for this peer right now — but does
+     * NOT apply it (the caller asks `evaluate(node)` if they want the action
+     * to actually happen). This split lets the coordinator decide whether to
+     * apply on every outcome or batch via tick.
+     *
+     * Negative tokens/usd are clamped to 0. A peer cannot inflate its own
+     * remaining cost ceiling by reporting credits.
+     */
+    recordOutcome(outcome: SendOutcome, now?: Date): void;
+    /**
+     * Evaluate the breaker for one peer and apply the resulting transition
+     * to the entity. Returns the decision so callers can observe the outcome.
+     *
+     * `apply` defaults to true — set to false to get the dry-run decision
+     * without mutating the entity (useful for the doctor surface).
+     */
+    evaluate(node: FederationNode, now?: Date, apply?: boolean): BreakerDecision;
+    /**
+     * Periodic tick — evaluate all known peers. Intended to be called from a
+     * timer or after each batch of outcomes. Returns the decisions for
+     * observability.
+     */
+    tick(nodes: readonly FederationNode[], now?: Date): BreakerDecision[];
+    /** Drop a peer's sample buffer (e.g. after reactivate or evict). */
+    forget(nodeId: string): void;
+    /**
+     * Snapshot of per-peer aggregates for the doctor surface. Pure read —
+     * does not mutate the buffer.
+     */
+    snapshot(nodeId: string, now?: Date): {
+        readonly nodeId: string;
+        readonly sampleCount: number;
+        readonly cumUsdInWindow: number;
+        readonly failureRatioInWindow: number | null;
+    };
+}
+export {};
+//# sourceMappingURL=federation-breaker-service.d.ts.map

package/node_modules/@claude-flow/plugin-agent-federation/dist/application/federation-breaker-service.d.ts.map

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

package/node_modules/@claude-flow/plugin-agent-federation/dist/application/federation-breaker-service.js

@@ -0,0 +1,253 @@
+/**
+ * Federation circuit breaker service (ADR-097 Phase 2.b).
+ *
+ * Phase 2.a shipped the FederationNode state machine + canTransition table.
+ * This service is what drives transitions: it records per-peer send outcomes
+ * (success/failure + spend), evaluates thresholds against the configured
+ * policy, and calls suspend()/evict()/reactivate() on the entity.
+ *
+ * Architecture is two-layer to keep the policy testable in isolation:
+ *
+ *   1. **evaluatePolicy** (pure function) — given rolling samples for a peer
+ *      + the policy + now, returns a BreakerDecision describing what should
+ *      happen. No I/O, no clock, no entity mutation.
+ *   2. **FederationBreakerService** — owns the rolling-sample buffer,
+ *      wraps evaluatePolicy with the entity mutation step, and exposes
+ *      `recordOutcome` (called by the coordinator on each send completion)
+ *      + `tick` (called periodically to drive cooldown/auto-evict).
+ *
+ * The cost-tracker integration (Phase 3 upstream — emits federation_spend
+ * events when sends complete) is *not* wired here; this service holds its
+ * own in-memory rolling buffer. When Phase 3 upstream lands, the consumer
+ * can call `recordOutcome` from the bus subscriber and the buffer becomes
+ * a transparent cache. This keeps Phase 2 deliverable without a hard
+ * cost-tracker dependency.
+ *
+ * Security invariants:
+ *
+ *   1. Negative tokens/usd are clamped to 0 — a malicious receive-side
+ *      reporter cannot drive an "unsuspend" through credit inflation.
+ *   2. Sample buffer is bounded per-peer (DEFAULT_MAX_SAMPLES_PER_PEER) so
+ *      a high-throughput peer cannot exhaust memory.
+ *   3. Policy evaluation is order-independent for SUSPEND triggers —
+ *      cost OR failure-ratio fires the same SUSPEND. The reason field
+ *      records which one tripped.
+ *   4. evaluatePolicy is pure & deterministic given (samples, policy, now)
+ *      — no Date.now() calls inside, no random IDs, no hidden state.
+ *   5. Auto-eviction only runs from SUSPENDED state and only after the
+ *      grace age. Cannot skip SUSPENDED for an ACTIVE → EVICTED jump.
+ */
+import { FederationNodeState, isCooldownElapsed, shouldAutoEvict, DEFAULT_SUSPENSION_COOLDOWN_MS, DEFAULT_AUTO_EVICTION_AGE_MS, } from '../domain/value-objects/federation-node-state.js';
+export const DEFAULT_BREAKER_POLICY = Object.freeze({
+    costSuspensionUsd: 5.0,
+    costWindowMs: 24 * 60 * 60 * 1000,
+    failureRatioThreshold: 0.5,
+    failureWindowMs: 60 * 60 * 1000,
+    failureMinSamples: 10,
+    cooldownMs: DEFAULT_SUSPENSION_COOLDOWN_MS,
+    autoEvictionAgeMs: DEFAULT_AUTO_EVICTION_AGE_MS,
+});
+/** Per-peer sample buffer cap. ~24h of 1-Hz traffic. */
+export const DEFAULT_MAX_SAMPLES_PER_PEER = 100_000;
+/**
+ * Pure policy evaluator. Returns the decision the breaker should apply.
+ * No I/O, no clock, no entity mutation — given the same inputs, returns the
+ * same output. The service layer is responsible for calling node.suspend()
+ * / evict() / reactivate() based on this.
+ *
+ * Decision rules:
+ *
+ *   For ACTIVE peers:
+ *     - 24h cost > policy.costSuspensionUsd → SUSPEND/COST_THRESHOLD_EXCEEDED
+ *     - 1h failure ratio > policy.failureRatioThreshold (≥ failureMinSamples
+ *       in window) → SUSPEND/FAILURE_RATIO_EXCEEDED
+ *     - else NONE
+ *
+ *   For SUSPENDED peers:
+ *     - suspended ≥ autoEvictionAgeMs → EVICT/GRACE_PERIOD_EXPIRED
+ *     - cooldown elapsed → REACTIVATE_ELIGIBLE (caller probes + reactivates)
+ *     - else NONE
+ *
+ *   For EVICTED peers: always NONE (terminal under breaker flow).
+ *
+ * Cost takes priority over failure-ratio when both trip, because cost is
+ * the more conservative signal (a malicious peer can manufacture failures
+ * by trickling errors but cannot manufacture spend without actually
+ * burning budget).
+ */
+export function evaluatePolicy(samples, node, policy, now) {
+    if (node.state === FederationNodeState.EVICTED) {
+        return { action: 'NONE', nodeId: node.nodeId };
+    }
+    if (node.state === FederationNodeState.SUSPENDED) {
+        if (shouldAutoEvict(node.stateChangedAt, now, policy.autoEvictionAgeMs)) {
+            return {
+                action: 'EVICT',
+                nodeId: node.nodeId,
+                reason: 'GRACE_PERIOD_EXPIRED',
+            };
+        }
+        if (isCooldownElapsed(node.stateChangedAt, now, policy.cooldownMs)) {
+            return { action: 'REACTIVATE_ELIGIBLE', nodeId: node.nodeId };
+        }
+        return { action: 'NONE', nodeId: node.nodeId };
+    }
+    // ACTIVE: check cost first, then failure ratio. Cost takes priority.
+    const costCutoff = now.getTime() - policy.costWindowMs;
+    let cumUsd = 0;
+    for (const s of samples) {
+        if (s.at.getTime() >= costCutoff)
+            cumUsd += s.usdSpent;
+    }
+    if (cumUsd > policy.costSuspensionUsd) {
+        return {
+            action: 'SUSPEND',
+            nodeId: node.nodeId,
+            reason: 'COST_THRESHOLD_EXCEEDED',
+        };
+    }
+    const failCutoff = now.getTime() - policy.failureWindowMs;
+    let total = 0;
+    let failures = 0;
+    for (const s of samples) {
+        if (s.at.getTime() < failCutoff)
+            continue;
+        total++;
+        if (!s.success)
+            failures++;
+    }
+    if (total >= policy.failureMinSamples) {
+        const ratio = failures / total;
+        if (ratio > policy.failureRatioThreshold) {
+            return {
+                action: 'SUSPEND',
+                nodeId: node.nodeId,
+                reason: 'FAILURE_RATIO_EXCEEDED',
+            };
+        }
+    }
+    return { action: 'NONE', nodeId: node.nodeId };
+}
+export class FederationBreakerService {
+    policy;
+    samples;
+    maxSamplesPerPeer;
+    onTransition;
+    constructor(policy = DEFAULT_BREAKER_POLICY, maxSamplesPerPeer = DEFAULT_MAX_SAMPLES_PER_PEER, onTransition) {
+        this.policy = policy;
+        this.samples = new Map();
+        this.maxSamplesPerPeer = maxSamplesPerPeer;
+        this.onTransition = onTransition;
+    }
+    /** Read the active policy (handy for tests + doctor surface). */
+    getPolicy() {
+        return this.policy;
+    }
+    /**
+     * Record a send outcome for a peer. Called by the coordinator after each
+     * `routing.send` completion. Returns a BreakerDecision describing what,
+     * if anything, the breaker would do for this peer right now — but does
+     * NOT apply it (the caller asks `evaluate(node)` if they want the action
+     * to actually happen). This split lets the coordinator decide whether to
+     * apply on every outcome or batch via tick.
+     *
+     * Negative tokens/usd are clamped to 0. A peer cannot inflate its own
+     * remaining cost ceiling by reporting credits.
+     */
+    recordOutcome(outcome, now = new Date()) {
+        const normalized = {
+            success: outcome.success,
+            tokensUsed: Math.max(0, outcome.tokensUsed ?? 0),
+            usdSpent: Math.max(0, outcome.usdSpent ?? 0),
+            at: outcome.at ?? now,
+        };
+        const buf = this.samples.get(outcome.nodeId) ?? [];
+        buf.push(normalized);
+        // Bounded buffer: drop oldest if over cap. Keeps memory bounded under
+        // sustained high traffic while preserving the most-recent window.
+        if (buf.length > this.maxSamplesPerPeer) {
+            buf.splice(0, buf.length - this.maxSamplesPerPeer);
+        }
+        this.samples.set(outcome.nodeId, buf);
+    }
+    /**
+     * Evaluate the breaker for one peer and apply the resulting transition
+     * to the entity. Returns the decision so callers can observe the outcome.
+     *
+     * `apply` defaults to true — set to false to get the dry-run decision
+     * without mutating the entity (useful for the doctor surface).
+     */
+    evaluate(node, now = new Date(), apply = true) {
+        const buf = this.samples.get(node.nodeId) ?? [];
+        const decision = evaluatePolicy(buf, node, this.policy, now);
+        if (!apply)
+            return decision;
+        let transitioned = false;
+        switch (decision.action) {
+            case 'SUSPEND': {
+                const reason = { reason: decision.reason };
+                transitioned = node.suspend(reason, now);
+                break;
+            }
+            case 'EVICT': {
+                const reason = { reason: decision.reason };
+                transitioned = node.evict(reason, now);
+                break;
+            }
+            case 'REACTIVATE_ELIGIBLE':
+                // The breaker does NOT auto-reactivate. The integrator's health
+                // probe is responsible for confirming the peer is healthy and
+                // calling node.reactivate() itself. We only signal eligibility.
+                break;
+            case 'NONE':
+                break;
+        }
+        if (transitioned && this.onTransition) {
+            // Side-effect listener (ADR-111 Phase 3). Errors are swallowed so a
+            // failing WG propagation can't unwind the entity transition that
+            // already succeeded — coordinator should log via its own audit trail.
+            Promise.resolve(this.onTransition(node, decision)).catch(() => { });
+        }
+        return decision;
+    }
+    /**
+     * Periodic tick — evaluate all known peers. Intended to be called from a
+     * timer or after each batch of outcomes. Returns the decisions for
+     * observability.
+     */
+    tick(nodes, now = new Date()) {
+        return nodes.map((n) => this.evaluate(n, now));
+    }
+    /** Drop a peer's sample buffer (e.g. after reactivate or evict). */
+    forget(nodeId) {
+        this.samples.delete(nodeId);
+    }
+    /**
+     * Snapshot of per-peer aggregates for the doctor surface. Pure read —
+     * does not mutate the buffer.
+     */
+    snapshot(nodeId, now = new Date()) {
+        const buf = this.samples.get(nodeId) ?? [];
+        const costCutoff = now.getTime() - this.policy.costWindowMs;
+        const failCutoff = now.getTime() - this.policy.failureWindowMs;
+        let cumUsd = 0;
+        let total = 0;
+        let failures = 0;
+        for (const s of buf) {
+            if (s.at.getTime() >= costCutoff)
+                cumUsd += s.usdSpent;
+            if (s.at.getTime() >= failCutoff) {
+                total++;
+                if (!s.success)
+                    failures++;
+            }
+        }
+        return {
+            nodeId,
+            sampleCount: buf.length,
+            cumUsdInWindow: cumUsd,
+            failureRatioInWindow: total > 0 ? failures / total : null,
+        };
+    }
+}
+//# sourceMappingURL=federation-breaker-service.js.map

package/node_modules/@claude-flow/plugin-agent-federation/dist/application/federation-breaker-service.js.map

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

package/node_modules/@claude-flow/plugin-agent-federation/dist/application/federation-coordinator.d.ts

@@ -0,0 +1,211 @@
+import { FederationNode, type FederationNodeStateRecord } from '../domain/entities/federation-node.js';
+import { FederationSession } from '../domain/entities/federation-session.js';
+import { type FederationMessageType } from '../domain/entities/federation-envelope.js';
+import { TrustLevel } from '../domain/entities/trust-level.js';
+import { type SuspensionReason } from '../domain/value-objects/federation-node-state.js';
+import { DiscoveryService, type FederationManifest } from '../domain/services/discovery-service.js';
+import { HandshakeService } from '../domain/services/handshake-service.js';
+import { RoutingService, type RoutingResult } from '../domain/services/routing-service.js';
+import { AuditService } from '../domain/services/audit-service.js';
+import { PIIPipelineService } from '../domain/services/pii-pipeline-service.js';
+import { TrustEvaluator, type BootstrapElevationAuditEntry } from './trust-evaluator.js';
+import { PolicyEngine } from './policy-engine.js';
+import { enforceBudget, validateBudget } from '../domain/value-objects/federation-budget.js';
+import type { FederationBreakerService } from './federation-breaker-service.js';
+import type { SpendReporter } from './spend-reporter.js';
+import type { WgMeshService, WgCommand } from '../domain/services/wg-mesh-service.js';
+/**
+ * Optional per-call budget controls (ADR-097 Phase 1). All fields are
+ * optional; omitted means "no limit on that axis" (the default unbounded
+ * budget still has maxHops = 8 to defang recursive delegation loops).
+ */
+export interface SendOptions {
+    readonly budget?: {
+        maxTokens?: number;
+        maxUsd?: number;
+    };
+    readonly maxHops?: number;
+    /**
+     * How many hops this message has already traveled (0 on the originator).
+     * Phase 1 enforces at the send side because there is no inbound dispatcher
+     * yet; callers re-forwarding a received message should pass the original
+     * envelope's hopCount here.
+     */
+    readonly hopCount?: number;
+    /** Caller-reported usage from the previous leg, for cumulative checks. */
+    readonly spent?: {
+        tokens?: number;
+        usd?: number;
+    };
+}
+export interface FederationCoordinatorConfig {
+    readonly nodeId: string;
+    readonly publicKey: string;
+    readonly endpoint: string;
+    readonly capabilities: readonly string[];
+    /** Wire protocols this runtime is prepared to advertise and negotiate. */
+    readonly supportedProtocols?: readonly string[];
+    readonly version?: string;
+}
+export interface FederationStatus {
+    readonly nodeId: string;
+    readonly activeSessions: number;
+    readonly knownPeers: number;
+    readonly trustLevels: Record<string, TrustLevel>;
+    readonly healthy: boolean;
+}
+/**
+ * Optional integrations (ADR-097 Phase 3 upstream + Phase 2.b breaker
+ * wiring). Both are constructor-injected; both default to no-op.
+ *
+ * - `spendReporter` — invoked by reportSpend() when present; persists
+ *   the FederationSpendEvent to whatever backend the integrator wired
+ *   (cost-tracker bus, ruflo memory federation-spend namespace, etc.)
+ * - `breakerService` — invoked by reportSpend() when present; calls
+ *   recordOutcome() so the breaker's in-memory rolling buffer is fed
+ *   without requiring the integrator to wire two parallel pipelines
+ */
+export interface FederationCoordinatorIntegrations {
+    readonly spendReporter?: SpendReporter;
+    readonly breakerService?: FederationBreakerService;
+    /**
+     * ADR-111 Phase 3 — optional WG mesh service. When present, peer state
+     * transitions (evict/reactivate/breaker-suspend) emit `wg set` commands
+     * to a sink supplied by `wgCommandSink`. No-op for peers without a `wg`
+     * manifest block, so wiring the service is safe even in mixed deployments.
+     */
+    readonly wgMesh?: WgMeshService;
+    /**
+     * Where emitted WG commands go. Defaults to the audit log only. Integrators
+     * can plug in a shell executor here (after operator approval — bringing up
+     * a network interface is destructive). Commands include shell-ready
+     * `wg set <iface> ...` strings; the sink should still validate before exec.
+     */
+    readonly wgCommandSink?: (cmd: WgCommand) => void | Promise<void>;
+}
+export declare class FederationCoordinator {
+    private readonly config;
+    private readonly discovery;
+    private readonly handshake;
+    private readonly routing;
+    private readonly audit;
+    private readonly piiPipeline;
+    private readonly trustEvaluator;
+    private readonly policyEngine;
+    private readonly sessions;
+    private initialized;
+    private readonly spendReporter?;
+    private readonly breakerService?;
+    private readonly wgMesh?;
+    private readonly wgCommandSink?;
+    constructor(config: FederationCoordinatorConfig, discovery: DiscoveryService, handshake: HandshakeService, routing: RoutingService, audit: AuditService, piiPipeline: PIIPipelineService, trustEvaluator: TrustEvaluator, policyEngine: PolicyEngine, integrations?: FederationCoordinatorIntegrations);
+    /**
+     * ADR-111 Phase 3 — emit a WG command for an audited peer transition.
+     * No-op if no wgMesh is configured or the peer lacks a `wg` manifest
+     * block. Commands flow to `wgCommandSink` (if any) and always to the
+     * audit log so reactivation is fully traceable.
+     */
+    private emitWgCommand;
+    initialize(manifest: Omit<FederationManifest, 'signature'>): Promise<void>;
+    shutdown(): Promise<void>;
+    joinPeer(endpoint: string, manifest?: FederationManifest): Promise<FederationSession>;
+    leavePeer(nodeId: string): Promise<void>;
+    sendMessage<T>(targetNodeId: string, messageType: FederationMessageType, payload: T, options?: SendOptions): Promise<RoutingResult>;
+    /**
+     * Re-export the budget primitives so external callers (e.g. follow-up
+     * iterations adding receive-side decrement) can reuse them without
+     * dipping into domain/value-objects directly.
+     */
+    static readonly budget: {
+        validate: typeof validateBudget;
+        enforce: typeof enforceBudget;
+    };
+    broadcastMessage<T>(messageType: FederationMessageType, payload: T): Promise<RoutingResult[]>;
+    handleThreatDetection(nodeId: string): void;
+    handleHmacFailure(nodeId: string): void;
+    getStatus(): FederationStatus;
+    /**
+     * ADR-097 Phase 4: per-peer breaker state snapshot for the doctor
+     * surface and `federation_breaker_status` MCP tool.
+     *
+     * Returns one entry per known peer with the entity's stateRecord —
+     * what state, when it changed, why, and which caller's correlation
+     * key triggered it. Pure read; does not mutate.
+     */
+    getPeerStates(): readonly (FederationNodeStateRecord & {
+        readonly nodeId: string;
+    })[];
+    /**
+     * ADR-111 Phase 6: public read of the discovery peer list. Used by
+     * federation_wg_status MCP tool + WG firewall projection. Returns the
+     * full known-peer set (active + suspended + evicted) — filter via
+     * .isActive / state if you only want the live mesh members.
+     */
+    listPeers(): readonly FederationNode[];
+    /**
+     * Aggregated counts for the doctor surface — `{ active: N, suspended: M,
+     * evicted: K }`. Cheap O(peers) sweep; safe to call from a status line.
+     */
+    getPeerStateCounts(): {
+        readonly active: number;
+        readonly suspended: number;
+        readonly evicted: number;
+    };
+    /**
+     * Operator-initiated evict. Returns true on transition, false if the
+     * peer was already EVICTED or unknown. Logs to audit either way.
+     *
+     * Does NOT remove the peer from the discovery registry — `leavePeer`
+     * is the registry-removal API. Eviction is the breaker layer; the peer
+     * remains queryable so the operator can later reactivate.
+     */
+    evictPeer(nodeId: string, reason?: SuspensionReason, correlationId?: string): Promise<boolean>;
+    /**
+     * ADR-097 Phase 3 upstream: report the actual cost of a federated
+     * call. Federation doesn't own model pricing, so the integrator calls
+     * this after the downstream agent completes.
+     *
+     * Fans out to:
+     *   - spendReporter (if injected) — persists to integrator's backend
+     *   - breakerService.recordOutcome (if injected) — feeds the breaker's
+     *     in-memory rolling buffer for cost/failure-ratio thresholds
+     *
+     * Both are no-ops if the corresponding integration isn't wired, so
+     * callers don't need to branch on configuration. Negative tokens/usd
+     * are clamped to 0 at the breaker layer (anti-credit-inflation); the
+     * spend reporter receives the raw values so backends can audit them.
+     *
+     * Auto-fills `ts` if the caller omits it.
+     */
+    reportSpend(input: {
+        readonly peerId: string;
+        readonly taskId?: string;
+        readonly tokensUsed: number;
+        readonly usdSpent: number;
+        readonly success: boolean;
+        readonly ts?: string;
+    }): Promise<void>;
+    /**
+     * Founder-bootstrap trust elevation (ADR-164 §3.5.4 — operator escape hatch
+     * used in the autopilot Day-1 scenario where a freshly-joined BBS peer
+     * needs TRUSTED before organic minInteractions thresholds can accrue).
+     *
+     * Refuses if the target node is not a registered federation peer (returns
+     * null). On success, writes a `trust_level_changed` audit entry tagged
+     * `bootstrap_elevation` with the operator-supplied reason, and returns
+     * the audit entry so the CLI / caller can print it to stdout.
+     */
+    bootstrapElevatePeer(nodeId: string, newLevel: TrustLevel, reason: string): Promise<BootstrapElevationAuditEntry | null>;
+    /**
+     * Operator-initiated reactivate. Used after an integrator-supplied
+     * health probe confirms a SUSPENDED peer is healthy, OR as an
+     * operator-override escape from EVICTED. Returns true on transition.
+     */
+    reactivatePeer(nodeId: string, correlationId?: string): Promise<boolean>;
+    getSession(sessionId: string): FederationSession | undefined;
+    getActiveSessions(): FederationSession[];
+    private establishSession;
+    private findSessionByNodeId;
+    private ensureInitialized;
+}
+//# sourceMappingURL=federation-coordinator.d.ts.map