@claude-flow/cli 3.66.1 → 3.67.0

package/node_modules/@claude-flow/plugin-agent-federation/dist/domain/services/handshake-service.d.ts

@@ -0,0 +1,62 @@
+import { FederationNode } from '../entities/federation-node.js';
+import { FederationSession } from '../entities/federation-session.js';
+export interface HandshakeChallenge {
+    readonly challengeId: string;
+    readonly nonce: string;
+    readonly timestamp: string;
+    readonly sourceNodeId: string;
+    readonly targetNodeId: string;
+}
+export interface HandshakeChallengeResponse {
+    readonly challengeId: string;
+    readonly signedNonce: string;
+    readonly publicKey: string;
+    readonly capabilities: readonly string[];
+}
+export interface HandshakeResult {
+    readonly success: boolean;
+    readonly session?: FederationSession;
+    readonly error?: string;
+    /** The peer answered with the key pinned for its node id. False means the key was only claimed. */
+    readonly pinned?: boolean;
+}
+export interface HandshakeServiceDeps {
+    generateSessionId: () => string;
+    generateSessionToken: () => string;
+    generateNonce: () => string;
+    signChallenge: (nonce: string) => Promise<string>;
+    verifySignature: (nonce: string, signature: string, publicKey: string) => Promise<boolean>;
+    /** The Ed25519 key (hex) the operator pinned for a node id. Without a pin, a handshake proves nothing about who answered. */
+    pinnedKeyFor?: (nodeId: string) => string | undefined;
+    getLocalNodeId: () => string;
+    getLocalPublicKey: () => string;
+    getLocalCapabilities: () => readonly string[];
+}
+export interface HandshakeConfig {
+    readonly sessionTtlMs: number;
+    readonly maxSessionTtlMs: number;
+    readonly heartbeatIntervalMs: number;
+    readonly challengeTimeoutMs: number;
+}
+export declare class HandshakeService {
+    private readonly deps;
+    private readonly config;
+    private readonly pendingChallenges;
+    constructor(deps: HandshakeServiceDeps, config?: Partial<HandshakeConfig>);
+    initiateHandshake(remoteNode: FederationNode): Promise<HandshakeChallenge>;
+    respondToHandshake(challenge: HandshakeChallenge): Promise<HandshakeChallengeResponse>;
+    verifyChallenge(response: HandshakeChallengeResponse, remoteNode: FederationNode): Promise<HandshakeResult>;
+    /**
+     * Establish a capability-limited session from discovery evidence.
+     *
+     * A signed manifest proves that the advertised key bound the protocol list;
+     * it does not prove live challenge response, so this path never elevates
+     * beyond VERIFIED. Endpoint-only peers remain UNTRUSTED with no negotiated
+     * optional capabilities. A future wire handshake may elevate either session
+     * after authenticating a response received from the remote process.
+     */
+    establishDiscoverySession(remoteNode: FederationNode, verifiedManifest: boolean): FederationSession;
+    renewSession(session: FederationSession): FederationSession;
+    private cleanExpiredChallenges;
+}
+//# sourceMappingURL=handshake-service.d.ts.map

package/node_modules/@claude-flow/plugin-agent-federation/dist/domain/services/pii-pipeline-service.d.ts

@@ -0,0 +1,65 @@
+import { TrustLevel } from '../entities/trust-level.js';
+export type PIIType = 'email' | 'ssn' | 'credit_card' | 'api_key' | 'password' | 'name' | 'address' | 'phone' | 'ip_address' | 'jwt' | 'aws_key' | 'private_key' | 'database_url' | 'github_token';
+export type PIIAction = 'block' | 'redact' | 'hash' | 'pass';
+export interface PIIDetection {
+    readonly type: PIIType;
+    readonly value: string;
+    readonly confidence: number;
+    readonly offset: number;
+    readonly context: string;
+}
+export interface PIIPolicyConfig {
+    defaultAction: PIIAction;
+    overrides: Partial<Record<PIIType, {
+        action: PIIAction;
+        trustLevelOverride?: Partial<Record<TrustLevel, PIIAction>>;
+    }>>;
+    hashAlgorithm: 'sha256' | 'blake3';
+    hashSalt: string;
+    redactionPlaceholder: string;
+}
+export interface PIICalibration {
+    type: PIIType;
+    falsePositiveRate: number;
+    falseNegativeRate: number;
+    adjustedThreshold: number;
+    totalOverrides: number;
+    lastCalibrated: string;
+}
+export interface PIITransformResult {
+    readonly originalText: string;
+    readonly transformedText: string;
+    readonly detections: readonly PIIDetection[];
+    readonly actionsApplied: readonly {
+        type: PIIType;
+        action: PIIAction;
+    }[];
+    readonly blocked: boolean;
+}
+export interface PIIConfidenceThresholds {
+    autoBlock: number;
+    autoRedact: number;
+    flagForReview: number;
+    ignore: number;
+}
+export interface PIIPipelineServiceDeps {
+    hashFunction: (value: string, salt: string) => string;
+}
+export declare class PIIPipelineService {
+    private readonly deps;
+    private readonly policy;
+    private readonly calibrations;
+    private readonly confidenceThresholds;
+    constructor(deps: PIIPipelineServiceDeps, policy?: Partial<PIIPolicyConfig>, confidenceThresholds?: Partial<PIIConfidenceThresholds>);
+    detect(text: string): PIIDetection[];
+    classify(detections: PIIDetection[]): Map<PIIType, PIIDetection[]>;
+    evaluate(detection: PIIDetection, trustLevel: TrustLevel): PIIAction;
+    transform(text: string, trustLevel: TrustLevel): PIITransformResult;
+    updateCalibration(type: PIIType, calibration: PIICalibration): void;
+    getCalibration(type: PIIType): PIICalibration | undefined;
+    private computeConfidence;
+    private getEffectiveThreshold;
+    static defaultPolicy(): PIIPolicyConfig;
+    static defaultPolicyMatrix(): Record<PIIType, Record<TrustLevel, PIIAction>>;
+}
+//# sourceMappingURL=pii-pipeline-service.d.ts.map

package/node_modules/@claude-flow/plugin-agent-federation/dist/domain/services/routing-service.d.ts

@@ -0,0 +1,54 @@
+import { FederationEnvelope, type FederationEnvelopeProps, type FederationMessageType } from '../entities/federation-envelope.js';
+import { FederationSession } from '../entities/federation-session.js';
+import { TrustLevel } from '../entities/trust-level.js';
+export type RoutingMode = 'direct' | 'broadcast' | 'consensus';
+export interface RoutingResult {
+    readonly success: boolean;
+    readonly mode: RoutingMode;
+    readonly envelopeId: string;
+    readonly targetNodeIds: readonly string[];
+    readonly error?: string;
+    readonly latencyMs?: number;
+}
+export interface ConsensusProposal {
+    readonly proposalId: string;
+    readonly proposerNodeId: string;
+    readonly messageType: FederationMessageType;
+    readonly payload: unknown;
+    readonly quorumRequired: number;
+    readonly votes: Map<string, boolean>;
+    readonly createdAt: Date;
+    readonly expiresAt: Date;
+}
+export interface RoutingServiceDeps {
+    generateEnvelopeId: () => string;
+    generateNonce: () => string;
+    signEnvelope: (payload: string, sessionToken: string) => string;
+    verifyEnvelope: (payload: string, signature: string, sessionToken: string) => boolean;
+    scanPii: (text: string, trustLevel: number) => {
+        transformedText: string;
+        scanResult: FederationEnvelopeProps['piiScanResult'];
+    };
+    sendToNode: (nodeId: string, envelope: FederationEnvelope) => Promise<void>;
+    getActiveSessions: () => FederationSession[];
+    getLocalNodeId: () => string;
+    /** Current peer authority; absent peers/resolvers receive the untrusted PII policy. */
+    getPeerTrustLevel?: (nodeId: string) => TrustLevel | undefined;
+}
+export declare class RoutingService {
+    private readonly deps;
+    private readonly pendingProposals;
+    constructor(deps: RoutingServiceDeps);
+    selectMode(messageType: FederationMessageType): RoutingMode;
+    send<T>(session: FederationSession, messageType: FederationMessageType, payload: T): Promise<RoutingResult>;
+    broadcast<T>(messageType: FederationMessageType, payload: T): Promise<RoutingResult[]>;
+    propose<T>(messageType: FederationMessageType, payload: T, quorumFraction?: number): Promise<ConsensusProposal>;
+    recordVote(proposalId: string, nodeId: string, vote: boolean): boolean;
+    isConsensusReached(proposalId: string): {
+        reached: boolean;
+        approved: boolean;
+    };
+    verifyInboundEnvelope(envelope: FederationEnvelope, sessionToken: string): boolean;
+    cleanExpiredProposals(): void;
+}
+//# sourceMappingURL=routing-service.d.ts.map

package/node_modules/@claude-flow/plugin-agent-federation/dist/domain/services/wg-firewall-service.d.ts

@@ -0,0 +1,71 @@
+/**
+ * ADR-111 Phase 4 — Trust-graded firewall projection.
+ *
+ * Projects the WG_NETWORK_GATES table (defined in wg-mesh-service.ts) into
+ * concrete kernel-firewall rules. Two backends:
+ *
+ *   - `nftables` for Linux — atomic `nft -f <file>` loader, family `inet`,
+ *     hook `input` (interface-scoped to the WG iface).
+ *   - `pf` for macOS — `pfctl -a ruflo-fed -f <file>`, anchor-scoped so
+ *     ruflo's rules don't collide with the operator's main pf ruleset.
+ *
+ * Like Phase 2's WgMeshService this is a **pure-projection** service: it
+ * returns rule strings + the shell command the operator runs. It never
+ * shells out or modifies kernel state itself. Operator review is mandatory
+ * because `pf` / `nft` reloads atomically replace the active ruleset for
+ * the targeted scope — a typo here can drop ssh.
+ *
+ * v1 scope: the four trust levels VERIFIED/ATTESTED/TRUSTED/PRIVILEGED.
+ * UNTRUSTED peers are never in the mesh (excluded by WgMeshService) so
+ * they don't need a firewall rule either — implicit drop policy.
+ */
+import { FederationNode } from '../entities/federation-node.js';
+export type WgFirewallPlatform = 'linux-nftables' | 'darwin-pf';
+export interface WgFirewallServiceConfig {
+    /** Target platform. Default: auto-detect from process.platform. */
+    readonly platform?: WgFirewallPlatform;
+    /** WG interface name to scope rules to. Defaults to `ruflo-fed`. */
+    readonly interfaceName?: string;
+    /** Where the operator should write the rule file. Used for the load-command string. */
+    readonly rulePath?: string;
+    /** pf anchor (macOS only). Defaults to `ruflo-fed`. */
+    readonly pfAnchor?: string;
+}
+export interface WgFirewallRuleSet {
+    /** The full rule-file content the operator writes to disk. */
+    readonly content: string;
+    /** The shell command the operator runs to load it. */
+    readonly loadCmd: string;
+    /** Recommended file path (informational — the operator decides). */
+    readonly rulePath: string;
+    /** Per-peer rule projections for audit/inspection. */
+    readonly peerProjections: ReadonlyArray<{
+        readonly nodeId: string;
+        readonly trustLabel: string;
+        readonly meshIP: string;
+        readonly rules: readonly string[];
+    }>;
+}
+export declare class WgFirewallService {
+    private readonly platform;
+    private readonly interfaceName;
+    private readonly rulePath;
+    private readonly pfAnchor;
+    constructor(config?: WgFirewallServiceConfig);
+    getPlatform(): WgFirewallPlatform;
+    /**
+     * Project the current peer set into a complete rule file (nftables or pf)
+     * scoped to the WG interface.
+     *
+     * Peers below WG_MIN_MESH_TRUST (UNTRUSTED) are dropped — they have no
+     * mesh IP and shouldn't appear in firewall allow rules anyway. Peers
+     * without `metadata.wgMeshIP` are skipped (a stale manifest with no WG
+     * block; the mesh layer already excludes them).
+     */
+    projectRules(peers: readonly FederationNode[]): WgFirewallRuleSet;
+    private renderNftables;
+    private renderPf;
+    private defaultRulePath;
+    private trustLabel;
+}
+//# sourceMappingURL=wg-firewall-service.d.ts.map

package/node_modules/@claude-flow/plugin-agent-federation/dist/domain/services/wg-mesh-service.d.ts

@@ -0,0 +1,156 @@
+/**
+ * ADR-111 Phase 2 — WgMeshService.
+ *
+ * Pure-projection service: takes the federation peer registry + local
+ * WG identity and produces (a) a `wg-quick`-compatible config string,
+ * (b) per-peer `wg set` commands the operator runs to converge an
+ * already-running interface, and (c) the AllowedIPs slice that maps to
+ * each peer's trust level.
+ *
+ * Deliberately does NOT shell out. Bringing up a network interface
+ * requires root and modifies system state — per CLAUDE.md's
+ * destructive-actions guidance the service emits the commands; the
+ * operator (or a thin shell wrapper they audit) runs them.
+ *
+ * Phase 3 (breaker integration) consumes this service: peer state
+ * transitions invoke removeAllowedIPs/removePeer/restoreAllowedIPs,
+ * which produce commands without side effects.
+ */
+import { TrustLevel } from '../entities/trust-level.js';
+import { FederationNode } from '../entities/federation-node.js';
+import type { WgLocalKey } from '../value-objects/wg-config.js';
+export interface WgPortRule {
+    readonly proto: 'tcp' | 'udp' | 'all';
+    readonly port?: number;
+    readonly portRange?: readonly [number, number];
+}
+/**
+ * Trust-level → reachability. ADR-111's `WG_NETWORK_GATES`.
+ *
+ * Note: WireGuard's `AllowedIPs` is L3 routing, not L4 ACL — these port
+ * rules describe what the L4 firewall (Phase 4: nftables/pf) should
+ * enforce. v1 (this phase) only produces the rules; Phase 4 projects
+ * them into kernel firewall syntax. Until then, callers using v1
+ * fall back to the simpler "AllowedIPs = peer's mesh IP" model (option
+ * (b) in the ADR — app-layer auth carries the access decision).
+ */
+export declare const WG_NETWORK_GATES: Record<TrustLevel, readonly WgPortRule[]>;
+/**
+ * Minimum trust level whose peers get a `[Peer]` block in the WG config.
+ * UNTRUSTED stays out of the mesh entirely — it's the explicit drop bucket.
+ */
+export declare const WG_MIN_MESH_TRUST: TrustLevel;
+export interface WgPeerFields {
+    readonly wgPublicKey: string;
+    readonly wgMeshIP: string;
+    readonly wgEndpoint: string;
+}
+/**
+ * Return the validated peer wg fields, or null if any is malformed or
+ * out-of-range. Callers treat null as "peer not eligible for mesh" — the
+ * peer stays in the federation discovery registry but is excluded from
+ * the wg config and any wg commands.
+ */
+export declare function readSafePeerWgFields(peer: FederationNode): WgPeerFields | null;
+export interface WgMeshServiceConfig {
+    /** Local interface name. Defaults to `ruflo-fed`. */
+    readonly interfaceName?: string;
+    /** Local UDP listen port. WireGuard's standard is 51820. */
+    readonly listenPort?: number;
+    /** Mesh subnet for AllowedIPs filtering. Defaults to DEFAULT_MESH_SUBNET. */
+    readonly meshSubnet?: string;
+}
+export interface WgPeerSummary {
+    readonly nodeId: string;
+    readonly trustLevel: TrustLevel;
+    readonly trustLabel: string;
+    readonly meshIP: string;
+    readonly endpoint: string;
+    readonly publicKey: string;
+    readonly state: 'active' | 'suspended' | 'evicted';
+    readonly allowedIPs: readonly string[];
+}
+/**
+ * A planned `wg(8)` mutation. Service consumers either execute these or
+ * surface them to the operator. Strings are validated for shell metachars
+ * before being formatted into a command — callers should still review.
+ */
+export interface WgCommand {
+    readonly verb: 'set-allowed-ips' | 'remove-allowed-ips' | 'remove-peer' | 'add-peer';
+    /** Public key of the peer this command targets. */
+    readonly peerPublicKey: string;
+    /** Render to a `wg set <iface> peer <pk> ...` shell-ready string. */
+    readonly cmd: string;
+    /** Human-readable rationale for audit logs. */
+    readonly rationale: string;
+}
+export declare class WgMeshService {
+    private readonly interfaceName;
+    private readonly listenPort;
+    private readonly meshSubnet;
+    private localKey;
+    private localMeshIP;
+    /** Per-peer AllowedIPs after the last applyTrustLevelToAllowedIPs() call. Drives restore from breaker. */
+    private readonly lastAppliedAllowedIPs;
+    /** Peer-pubkey → suspended flag for breaker integration. */
+    private readonly suspended;
+    /** Peer-pubkey → evicted flag. */
+    private readonly evicted;
+    constructor(config?: WgMeshServiceConfig);
+    /** Bind the local WG identity. Required before buildInterfaceConfig(). */
+    setLocalIdentity(key: WgLocalKey, meshIP: string): void;
+    getInterfaceName(): string;
+    getMeshSubnet(): string;
+    /**
+     * Build a `wg-quick`-compatible config string from current peers.
+     *
+     * Peers below WG_MIN_MESH_TRUST (UNTRUSTED) are excluded entirely.
+     * Suspended peers stay in the config but with `AllowedIPs =` empty
+     * (soft-block). Evicted peers are dropped completely.
+     *
+     * Operator writes this to `/etc/wireguard/<interface>.conf` and runs
+     * `wg-quick up <interface>`.
+     */
+    buildInterfaceConfig(peers: readonly FederationNode[]): string;
+    /**
+     * Compute the AllowedIPs slice for a peer at its current trust level.
+     * v1: each peer gets its own /32 mesh IP. Phase 4 will narrow this
+     * further via firewall rules; v1 keeps L3 broad and relies on the app
+     * layer + trust gates for access decisions.
+     */
+    computeAllowedIPs(peer: FederationNode, meshIP: string): readonly string[];
+    /**
+     * Apply trust level → AllowedIPs as a `wg set` command for an
+     * already-running interface. Used when a peer joins or its trust level
+     * changes without needing a full config rewrite.
+     */
+    applyTrustLevelToAllowedIPs(peer: FederationNode, meshIP: string, pubkey: string): WgCommand;
+    /**
+     * Phase 3 hook — peer SUSPENDED. Clear AllowedIPs (soft-block: keeps
+     * the peer's public key registered with the interface but blocks all
+     * routing to/from it).
+     */
+    removeAllowedIPs(peer: FederationNode, pubkey: string, reason?: string): WgCommand;
+    /**
+     * Phase 3 hook — peer reactivated. Restore the AllowedIPs slice that
+     * was active before suspension. Returns null if the peer was never
+     * suspended (idempotent).
+     */
+    restoreAllowedIPs(peer: FederationNode, meshIP: string, pubkey: string): WgCommand | null;
+    /**
+     * Phase 3 hook — peer EVICTED. Terminal removal from the mesh; the
+     * peer's `[Peer]` block is dropped on next config rebuild and an
+     * immediate `wg set <iface> peer <pk> remove` is emitted to flush
+     * runtime state without a config reload.
+     */
+    removePeer(peer: FederationNode, pubkey: string, reason?: string): WgCommand;
+    /** Summarize the mesh state for `federation_wg_status` (Phase 6) and audit. */
+    summarize(peers: readonly FederationNode[]): readonly WgPeerSummary[];
+    /**
+     * Defense-in-depth: validate that all bits we splice into a shell
+     * command are alphanumeric / base64 / WG-allowed chars. Refuses the
+     * command rather than ship a substring that might escape its slot.
+     */
+    private formatCmd;
+}
+//# sourceMappingURL=wg-mesh-service.d.ts.map

package/node_modules/@claude-flow/plugin-agent-federation/dist/domain/services/wg-witness-service.d.ts

@@ -0,0 +1,98 @@
+/**
+ * ADR-111 Phase 5 — Witness attestation chain for WG mesh mutations.
+ *
+ * Every coordination change (peer added/suspended/evicted/reactivated,
+ * keypair rotated) appends a signed entry to an append-only log
+ * `.claude-flow/federation/wg-changes.log`. The signature is over a
+ * canonical JSON encoding of the entry's content fields, using the
+ * operator's federation Ed25519 key — the same identity that signs
+ * federation manifests, so anyone who already trusts the manifest chain
+ * automatically trusts the WG change chain.
+ *
+ * Append-only via O_APPEND open + entries chained by prevHash (sha256 of
+ * the previous entry's canonical bytes). Tampering with history requires
+ * forging a chain of signatures with the operator's key.
+ *
+ * The periodic ruflo witness regen (plugins/ruflo-core/scripts/witness/)
+ * includes wg-changes.log as one of its watched artifacts (operator wires
+ * this via witness-fixes.json).
+ *
+ * Pure service: emits the canonical bytes and the signature to write.
+ * Caller does the I/O so this stays unit-testable without fs mocks.
+ */
+import type { WgCommand } from './wg-mesh-service.js';
+export type WgWitnessEventType = 'peer-added' | 'peer-removed-suspended' | 'peer-restored' | 'peer-evicted' | 'key-rotated' | 'interface-config-applied';
+/**
+ * Canonical fields of a witness entry. The hash + signature are computed
+ * over these in a stable JSON encoding (sorted keys, no whitespace).
+ */
+export interface WgWitnessContent {
+    readonly version: '1';
+    readonly type: WgWitnessEventType;
+    readonly timestamp: string;
+    readonly nodeId: string;
+    /** Public key of the affected peer, if any. */
+    readonly peerPublicKey?: string;
+    /** Mesh IP affected, if any. */
+    readonly meshIP?: string;
+    /** wg command that was emitted, if any. */
+    readonly wgCommand?: string;
+    /** Human-readable rationale for the audit log. */
+    readonly rationale: string;
+    /** Hash of the previous entry in the chain (sha256 hex), or empty for the genesis entry. */
+    readonly prevHash: string;
+}
+/**
+ * Full witness entry as it appears on disk — content + the operator's
+ * Ed25519 signature over the canonical encoding of content.
+ */
+export interface WgWitnessEntry {
+    readonly content: WgWitnessContent;
+    readonly hash: string;
+    readonly signature: string;
+}
+export interface WgWitnessSigner {
+    /** Returns an Ed25519 signature (base64) over the given canonical bytes. */
+    sign(bytes: Buffer): Promise<string>;
+}
+/**
+ * Stable JSON serialization for hashing/signing. Keys are sorted; no
+ * whitespace; undefined fields omitted. Same shape on every host so
+ * cross-host verifiers produce identical hashes.
+ */
+export declare function canonicalizeContent(content: WgWitnessContent): Buffer;
+export declare function hashContent(content: WgWitnessContent): string;
+export declare class WgWitnessService {
+    private readonly nodeId;
+    private readonly signer;
+    private lastHash;
+    constructor(nodeId: string, signer: WgWitnessSigner);
+    /**
+     * Override the previous-hash pointer (used when resuming from an existing
+     * log on disk). Caller reads the last entry from `wg-changes.log` and
+     * passes its `hash` here before appending more.
+     */
+    setLastHash(hash: string): void;
+    /** Build + sign an entry. Caller is responsible for the actual append-write. */
+    build(type: WgWitnessEventType, fields: Omit<WgWitnessContent, 'version' | 'type' | 'timestamp' | 'nodeId' | 'prevHash'>): Promise<WgWitnessEntry>;
+    /**
+     * Convenience: take a WgCommand emitted by WgMeshService Phase 2/3 and
+     * produce a witness entry of the right type. Maps verb → eventType.
+     */
+    attestWgCommand(cmd: WgCommand, meshIP?: string): Promise<WgWitnessEntry>;
+}
+/**
+ * Verify a single entry's signature + hash. Caller verifies the chain by
+ * iterating entries and confirming each entry's `prevHash` equals the
+ * preceding entry's `hash`.
+ */
+export declare function verifyWitnessEntry(entry: WgWitnessEntry, verify: (bytes: Buffer, signature: string) => Promise<boolean>): Promise<boolean>;
+/**
+ * Verify a full chain — every entry valid + chain link unbroken.
+ */
+export declare function verifyWitnessChain(entries: readonly WgWitnessEntry[], verify: (bytes: Buffer, signature: string) => Promise<boolean>): Promise<{
+    ok: boolean;
+    failedAt?: number;
+    reason?: string;
+}>;
+//# sourceMappingURL=wg-witness-service.d.ts.map

package/node_modules/@claude-flow/plugin-agent-federation/dist/domain/value-objects/federation-budget.d.ts

@@ -0,0 +1,89 @@
+/**
+ * Federation budget + hop counter (ADR-097 Phase 1).
+ *
+ * Carried in {@link FederationEnvelope} alongside the existing
+ * sourceNodeId/targetNodeId/payload. Sender supplies the original limits;
+ * each outbound hop increments hopCount and decrements remaining budget.
+ *
+ * Phase 1 enforces at the *send* side because there is no inbound
+ * dispatcher today (sendToNode is a stub — see researcher report).
+ * Phase 2 will move the decrement to receive once the inbound path lands.
+ *
+ * Security invariants pinned by the reviewer (audit_1776853149979 follow-up):
+ *
+ *   1. validateBudget rejects NaN, ±Infinity, negative numbers, and
+ *      non-integer hop counts. Returns a discriminated result so callers
+ *      cannot accidentally use a bad budget unchecked.
+ *   2. enforceBudget runs check-then-decrement in a single synchronous
+ *      function with no awaits inside — two concurrent send calls cannot
+ *      both pass the pre-check.
+ *   3. Errors return constant strings ("HOP_LIMIT_EXCEEDED" /
+ *      "BUDGET_EXCEEDED") with no remaining-budget echo so a caller can't
+ *      use the error response as an oracle for the threshold.
+ */
+/** Maximum hops a federation message may travel before the breaker opens. */
+export declare const DEFAULT_MAX_HOPS = 8;
+/**
+ * Caller-supplied budget. All fields are optional; omitted fields are
+ * treated as Infinity for the corresponding axis. Created via validateBudget;
+ * never construct directly.
+ */
+export interface Budget {
+    readonly maxHops: number;
+    readonly maxTokens: number;
+    readonly maxUsd: number;
+}
+/** Discriminated result of validating raw user input into a Budget. */
+export type BudgetValidationResult = {
+    ok: true;
+    budget: Budget;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Validate a raw budget object. Pure, no side effects. Caller obtains either
+ * a guaranteed-safe Budget or a structured error suitable for logging.
+ *
+ * Accepts undefined/null and returns a default unbounded budget (maxHops =
+ * DEFAULT_MAX_HOPS, tokens/usd = Infinity). This preserves backward
+ * compatibility for callers that don't pass a budget at all.
+ */
+export declare function validateBudget(raw: unknown, overrideMaxHops?: unknown): BudgetValidationResult;
+/**
+ * Enforcement decision returned by enforceBudget. Discriminated so the
+ * caller can map directly to a constant-string error — no remaining-budget
+ * echo on the failure side (anti-oracle).
+ */
+export type BudgetEnforcement = {
+    ok: true;
+    nextHopCount: number;
+    remaining: Budget;
+} | {
+    ok: false;
+    reason: 'HOP_LIMIT_EXCEEDED' | 'BUDGET_EXCEEDED';
+};
+/**
+ * Atomic (single synchronous function, no internal awaits) hop check.
+ *
+ * Returns the hopCount value the OUTBOUND envelope should carry plus the
+ * remaining budget that downstream peers will see. Callers must use the
+ * returned values; mutating the input Budget is forbidden (it's readonly).
+ *
+ * Contract:
+ *   - hopCount represents how many hops the message has already taken.
+ *   - The next outbound hop increments it: nextHopCount = hopCount + 1.
+ *   - The check fires AFTER increment: nextHopCount must be <= maxHops.
+ *   - This means maxHops=0 refuses to forward at all, which matches the
+ *     ADR's "no remote delegation allowed" semantic.
+ *
+ * tokensSpent / usdSpent are caller-reported actuals from the immediately
+ * preceding leg (or 0 on the originator). The check fires on the
+ * *post-spend* totals so a leg that overshoots is caught before the next
+ * outbound dispatch.
+ */
+export declare function enforceBudget(budget: Budget, hopCount: number, spent?: {
+    tokens: number;
+    usd: number;
+}): BudgetEnforcement;
+//# sourceMappingURL=federation-budget.d.ts.map