@kici-dev/orchestrator 0.0.0 → 0.1.1

package/dist/cluster/peer-client.d.ts

@@ -0,0 +1,190 @@
+/**
+ * WebSocket client for outgoing peer-to-peer connections between orchestrators.
+ *
+ * Follows PlatformClient patterns closely:
+ * - State machine: disconnected -> connecting -> handshaking -> authenticating -> connected
+ * - Exponential backoff with jitter for reconnection
+ * - Periodic heartbeat (30s default)
+ * - Intentional disconnect flag to prevent reconnection
+ *
+ * Authentication uses ECDH key exchange followed by join token (first connect)
+ * or HMAC credential proof (reconnection).
+ */
+import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
+import type { PeerRegistry } from './peer-registry.js';
+type PeerConnectionState = 'disconnected' | 'connecting' | 'handshaking' | 'authenticating' | 'connected';
+export interface PeerClientOptions {
+    /** WebSocket URL of the remote peer orchestrator. */
+    url: string;
+    /** Join token for first-time cluster join (optional if credential file exists). */
+    joinToken?: string;
+    /** Path to the credential file for reconnection. */
+    credentialFile: string;
+    /** This orchestrator's instance ID. */
+    instanceId: string;
+    /** Peer registry to update on heartbeats from remote peer. */
+    peerRegistry: PeerRegistry;
+    /** Callback to get this orchestrator's local agent inventory for heartbeats. */
+    getLocalInventory: () => Omit<PeerHeartbeat, 'type'>;
+    /** Heartbeat interval in ms. Default: 30000 (30s). */
+    heartbeatIntervalMs?: number;
+    /** Maximum reconnect delay in ms. Default: 60000 (60s). */
+    maxReconnectDelayMs?: number;
+    /** Callback when a job reroute request is received from peer. */
+    onJobReroute: (msg: JobReroute) => Promise<void>;
+    /** Callback when a job progress update is received from peer. */
+    onJobProgress: (msg: JobProgress) => void;
+    /** This orchestrator's role. Default: 'coordinator'. */
+    role?: 'coordinator' | 'worker';
+    /** Callback when a job cancel request is received from peer. */
+    onJobCancel: (msg: PeerJobCancel) => void;
+    /** Callback when a log chunk is received from a peer (coordinator side). */
+    onPeerLogChunk?: (chunk: PeerLogChunk) => void;
+    /** Callback when a cache upload request is received from a peer (coordinator side). */
+    onPeerCacheUploadRequest?: (req: PeerCacheUploadRequest) => Promise<PeerCacheUploadResponse>;
+    /** Callback for Raft vote requests. */
+    onRaftVoteRequest?: (msg: RaftVoteRequest) => RaftVoteResponse;
+    /** Callback for Raft vote responses (forwarded to Raft module). */
+    onRaftVoteResponse?: (msg: RaftVoteResponse) => void;
+    /** Callback for Raft append entries (leader heartbeat). */
+    onRaftAppendEntries?: (msg: RaftAppendEntries) => void;
+    /** Callback when a peer.leaving announcement is received. */
+    onPeerLeaving?: (msg: PeerLeaving) => void;
+    /**
+     * Callback when a peer.agent-token.revoke announcement is received.
+     * The local handler should call agentRegistry.disconnectByTokenId(tokenId)
+     * to close every in-flight WS authenticated by the now-revoked token.
+     */
+    onAgentTokenRevoke?: (msg: PeerAgentTokenRevoke) => void;
+    /**
+     * Callback when a config reload request is received from the peer.
+     * Should execute a local config reload and return the result fields,
+     * which are sent back via peer.config.reload.response.
+     *
+     * If undefined, incoming reload requests are answered with success=false.
+     */
+    onPeerConfigReload?: (msg: PeerConfigReload) => Promise<{
+        success: boolean;
+        version?: number;
+        errors?: string[];
+        restartRequired?: string[];
+        fieldsChanged?: string[];
+    }>;
+}
+export declare class PeerClient {
+    private ws;
+    private _state;
+    private heartbeatTimer;
+    private reconnectTimer;
+    private reconnectAttempts;
+    private intentionalDisconnect;
+    private _targetInstanceId;
+    private sessionKey;
+    private readonly ackWaiters;
+    private readonly cacheWaiters;
+    private readonly configReloadWaiters;
+    private readonly url;
+    private readonly joinToken?;
+    private readonly credentialFile;
+    private readonly instanceId;
+    private readonly role;
+    private readonly peerRegistry;
+    private readonly getLocalInventory;
+    private readonly heartbeatIntervalMs;
+    private readonly maxReconnectDelayMs;
+    private readonly onJobReroute;
+    private readonly onJobProgress;
+    private readonly onJobCancel;
+    private readonly onPeerLogChunk?;
+    private readonly onPeerCacheUploadRequest?;
+    private readonly onRaftVoteRequest?;
+    private readonly onRaftVoteResponse?;
+    private readonly onRaftAppendEntries?;
+    private readonly onPeerLeaving?;
+    private readonly onAgentTokenRevoke?;
+    private readonly onPeerConfigReload?;
+    constructor(options: PeerClientOptions);
+    /** Current connection state. */
+    get state(): PeerConnectionState;
+    /** The remote peer's instanceId (set after auth handshake). */
+    get targetInstanceId(): string | null;
+    /**
+     * Initiate connection to the peer orchestrator.
+     */
+    connect(): void;
+    /**
+     * Gracefully disconnect. Does not trigger reconnection.
+     */
+    disconnect(): void;
+    /**
+     * Send a peer protocol message. Returns false if not connected.
+     * Messages are encrypted with the session key.
+     */
+    send(msg: PeerToPeerMessage): boolean;
+    /**
+     * Send a message and wait for an ACK response.
+     * Used for job.reroute which expects job.reroute.ack.
+     *
+     * @returns true if accepted, false if rejected or timeout
+     */
+    sendAndWaitAck(msg: JobReroute, timeoutMs?: number): Promise<boolean>;
+    /**
+     * Send a log chunk to the coordinator (worker -> coordinator relay).
+     * Fire-and-forget: no ACK expected.
+     */
+    sendLogChunk(chunk: PeerLogChunk): boolean;
+    /**
+     * Send a peer.config.reload request to the connected peer and wait for the
+     * matching peer.config.reload.response.
+     *
+     * @returns The response, or null if not connected. Resolves with success=false
+     *   if the peer doesn't reply within the timeout.
+     */
+    sendConfigReloadAndWait(msg: PeerConfigReload, timeoutMs?: number): Promise<PeerConfigReloadResponse | null>;
+    /**
+     * Send a cache upload request to the coordinator and wait for a response
+     * with a pre-signed URL.
+     *
+     * @returns The response with the uploadUrl, or rejects on timeout/disconnect.
+     */
+    sendCacheUploadRequest(req: PeerCacheUploadRequest, timeoutMs?: number): Promise<PeerCacheUploadResponse>;
+    /**
+     * Calculate the reconnection delay with exponential backoff and jitter.
+     */
+    getReconnectDelay(): number;
+    private doConnect;
+    private handleMessage;
+    /**
+     * Determine auth method and send encrypted auth request.
+     *
+     * Credentials are **identity-scoped**, not URL-scoped. A single orchestrator
+     * runs N peer-clients (one per remote peer) and they all share the same
+     * on-disk credential file. The credential represents "this orchestrator's
+     * cluster membership credential", and the server (peer-handler) verifies it
+     * by `instanceId` alone — not by the requester URL. So any peer-client
+     * connecting to any peer can use the same credential, as long as the
+     * `instanceId` on disk matches ours.
+     *
+     * (4-coordinator mesh) bug history: the previous gate was
+     * `cred.coordinatorUrl === this.coordinatorUrl`, which broke the moment a
+     * second peer-client on the same orchestrator tried to authenticate to a
+     * different peer URL — it would see the first peer-client's credential,
+     * reject it (URL mismatch), fall through to the join token, and get
+     * permanently rejected because the token had already been consumed by the
+     * first peer-client. The Option B fix (commit 79f93da4) keyed the match on
+     * `instanceId`; this follow-up (Plan 04 Task 1 cleanup) drops the
+     * `coordinatorUrl` field from the credential file schema entirely because
+     * it was dead weight once the match switched to identity scope.
+     */
+    private sendAuthRequest;
+    private routeMessage;
+    private startHeartbeat;
+    private stopHeartbeat;
+    private scheduleReconnect;
+    private cancelReconnect;
+    private clearAckWaiters;
+    private clearCacheWaiters;
+    private clearConfigReloadWaiters;
+}
+export {};
+//# sourceMappingURL=peer-client.d.ts.map

package/dist/cluster/peer-credentials.d.ts

@@ -0,0 +1,108 @@
+import { Kysely } from 'kysely';
+/**
+ * A peer credential record stored in the coordinator's database.
+ */
+export interface PeerCredential {
+    id: string;
+    instanceId: string;
+    credentialHash: string;
+    role: string;
+    routingKeys: string[];
+    sourceTokenHash: string | null;
+    createdAt: Date;
+    lastSeenAt: Date | null;
+    lastValidatedBy: string | null;
+    expiresAt: Date;
+    revokedAt: Date | null;
+}
+/**
+ * Data persisted in this orchestrator's local credential file
+ * (~/.kici/credential.json). The credential is identity-scoped: one file per
+ * orchestrator, shared across every peer-client this orchestrator runs. See
+ * the `sendAuthRequest` doc in peer-client.ts for the history.
+ */
+export interface CredentialFileData {
+    instanceId: string;
+    credential: string;
+    role: string;
+    /** ISO 8601 timestamp of when this credential was issued. */
+    issuedAt: string;
+}
+/**
+ * Database CRUD operations for peer credentials.
+ * Used by the coordinator to manage credentials for all cluster members.
+ */
+export declare class PeerCredentialStore {
+    private readonly db;
+    constructor(db: Kysely<any>);
+    /**
+     * Save a new peer credential.
+     */
+    save(opts: {
+        instanceId: string;
+        credentialHash: string;
+        role: string;
+        routingKeys: string[];
+        sourceTokenHash?: string;
+        expiryDays?: number;
+    }): Promise<void>;
+    /**
+     * Find a non-revoked, non-expired credential by its hash.
+     */
+    findByCredentialHash(hash: string): Promise<PeerCredential | null>;
+    /**
+     * Find a non-revoked, non-expired credential by instance ID.
+     */
+    findByInstanceId(instanceId: string): Promise<PeerCredential | null>;
+    /**
+     * Update the last_seen_at timestamp for a credential.
+     * Optionally records which coordinator validated it.
+     */
+    updateLastSeen(credentialHash: string, validatedBy?: string): Promise<void>;
+    /**
+     * Revoke a peer's credential by instance ID.
+     */
+    revoke(instanceId: string): Promise<void>;
+    /**
+     * Revoke all active credentials.
+     * @returns The number of credentials revoked.
+     */
+    revokeAll(): Promise<number>;
+    /**
+     * List all active (non-revoked, non-expired) credentials.
+     */
+    listActive(): Promise<PeerCredential[]>;
+}
+/**
+ * Write credential data to a JSON file with restrictive permissions.
+ *
+ * Creates the parent directory (e.g., ~/.kici/) with 0700 if it doesn't exist.
+ * The credential file is written with 0600 permissions (owner read/write only).
+ *
+ * @param filePath - Absolute path to the credential file
+ * @param data - Credential data to persist
+ */
+export declare function writeCredentialFile(filePath: string, data: CredentialFileData): Promise<void>;
+/**
+ * Read credential data from a JSON file.
+ *
+ * @param filePath - Absolute path to the credential file
+ * @returns Parsed credential data, or null if the file doesn't exist
+ */
+export declare function readCredentialFile(filePath: string): Promise<CredentialFileData | null>;
+/**
+ * Construct a PeerCredentialStore bound to a Postgres URL, returning the
+ * store plus a disposer that closes the underlying pool. Lets tests
+ * exercise the real Kysely-backed store without importing pg/kysely.
+ *
+ * Intended for e2e coverage of the store's own CRUD methods — production
+ * code constructs the store with an already-allocated Kysely instance
+ * shared with the orchestrator.
+ */
+export declare function createPeerCredentialStoreFromUrl(databaseUrl: string, opts?: {
+    maxConnections?: number;
+}): Promise<{
+    store: PeerCredentialStore;
+    dispose: () => Promise<void>;
+}>;
+//# sourceMappingURL=peer-credentials.d.ts.map

package/dist/cluster/peer-crypto.d.ts

@@ -0,0 +1,57 @@
+/**
+ * ECDH key exchange and session encryption for peer-to-peer channels.
+ *
+ * Uses X25519 for key agreement and AES-256-GCM for message encryption.
+ * Session keys are derived via HKDF-SHA256 from the ECDH shared secret
+ * and a caller-provided nonce (to ensure per-session uniqueness).
+ *
+ * Wire format for encrypted messages (base64 encoded):
+ *   IV (12 bytes) || AuthTag (16 bytes) || Ciphertext
+ */
+import { type KeyObject } from 'node:crypto';
+/**
+ * An X25519 key pair for ECDH key exchange.
+ * The public key is DER SPKI-encoded for wire transport.
+ */
+export interface EcdhKeyPair {
+    /** DER SPKI-encoded X25519 public key. */
+    publicKey: Buffer;
+    /** X25519 private key object (not exported to wire). */
+    privateKey: KeyObject;
+}
+/**
+ * Generate a new X25519 key pair for ECDH key exchange.
+ *
+ * @returns Key pair with DER SPKI public key and KeyObject private key
+ */
+export declare function generateEcdhKeyPair(): EcdhKeyPair;
+/**
+ * Derive a 32-byte AES-256 session key from an ECDH key exchange.
+ *
+ * Performs X25519 Diffie-Hellman, then derives the session key via
+ * HKDF-SHA256 with the provided nonce as salt.
+ *
+ * @param localPrivateKey - This node's X25519 private key
+ * @param remotePubKeyDer - Remote node's DER SPKI-encoded X25519 public key
+ * @param nonce - Random nonce (used as HKDF salt for per-session uniqueness)
+ * @returns 32-byte session key suitable for AES-256-GCM
+ */
+export declare function deriveSessionKey(localPrivateKey: KeyObject, remotePubKeyDer: Buffer, nonce: Buffer): Buffer;
+/**
+ * Encrypt a plaintext message with a session key using AES-256-GCM.
+ *
+ * @param plaintext - The message to encrypt
+ * @param sessionKey - 32-byte session key from deriveSessionKey
+ * @returns Base64-encoded string: IV (12) || AuthTag (16) || Ciphertext
+ */
+export declare function encryptMessage(plaintext: string, sessionKey: Buffer): string;
+/**
+ * Decrypt a message encrypted with encryptMessage.
+ *
+ * @param encrypted - Base64-encoded string: IV (12) || AuthTag (16) || Ciphertext
+ * @param sessionKey - 32-byte session key (must match the key used for encryption)
+ * @returns Decrypted plaintext string
+ * @throws If the session key is wrong or the ciphertext has been tampered with
+ */
+export declare function decryptMessage(encrypted: string, sessionKey: Buffer): string;
+//# sourceMappingURL=peer-crypto.d.ts.map

package/dist/cluster/peer-handler.d.ts

@@ -0,0 +1,97 @@
+/**
+ * WebSocket handler for incoming peer connections from other orchestrators.
+ *
+ * Accepts WS upgrade, performs ECDH key exchange for encrypted channel,
+ * validates authentication via join token (first connect) or HMAC credential
+ * proof (reconnection), registers the peer in PeerRegistry, and routes
+ * messages bidirectionally. Sends periodic heartbeats to the connecting peer.
+ */
+import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries } from '@kici-dev/engine';
+import type { PeerRegistry } from './peer-registry.js';
+import type { PeerCredentialStore } from './peer-credentials.js';
+import { type JoinTokenManager } from './join-token.js';
+/**
+ * Minimal WebSocket interface for peer connections.
+ * Same pattern as agent/registry.ts WsLike, allowing mock testing.
+ */
+export interface PeerWsLike {
+    send(data: string): void;
+    close(code?: number, reason?: string): void;
+    on(event: string, listener: (...args: unknown[]) => void): void;
+    readyState: number;
+}
+export interface PeerHandlerDeps {
+    /** Join token manager for validating first-time peer tokens. */
+    tokenManager: JoinTokenManager;
+    /** Credential store for session credential CRUD. */
+    credentialStore: PeerCredentialStore;
+    /** Accepted roles for connecting peers. Default: ['coordinator', 'worker'] (accept any). */
+    acceptedRoles?: Array<'coordinator' | 'worker'>;
+    /** This orchestrator's instance ID. */
+    instanceId: string;
+    /** Peer registry to track incoming peers. */
+    peerRegistry: PeerRegistry;
+    /** Callback to get this orchestrator's local agent inventory for heartbeats. */
+    getLocalInventory: () => Omit<PeerHeartbeat, 'type'>;
+    /** Heartbeat interval in ms. Default: 30000 (30s). */
+    heartbeatIntervalMs?: number;
+    /** Auth timeout in ms. Default: 15000 (15s). */
+    authTimeoutMs?: number;
+    /** Callback when a job reroute request is received from peer. */
+    onJobReroute: (msg: JobReroute) => Promise<void>;
+    /** Callback when a job progress update is received from peer. */
+    onJobProgress: (msg: JobProgress) => void;
+    /** Callback when a job cancel request is received from peer. */
+    onJobCancel: (msg: PeerJobCancel) => void;
+    /** Callback when a log chunk is received from a worker peer. */
+    onPeerLogChunk?: (chunk: PeerLogChunk, peerId: string) => void;
+    /** Callback when a cache upload request is received from a worker peer. */
+    onPeerCacheUploadRequest?: (req: PeerCacheUploadRequest, peerId: string) => Promise<PeerCacheUploadResponse>;
+    /** Callback for Raft vote requests. */
+    onRaftVoteRequest?: (msg: RaftVoteRequest) => RaftVoteResponse;
+    /** Callback for Raft vote responses (forwarded to Raft module). */
+    onRaftVoteResponse?: (msg: RaftVoteResponse) => void;
+    /** Callback for Raft append entries (leader heartbeat). */
+    onRaftAppendEntries?: (msg: RaftAppendEntries) => void;
+    /** Callback when a peer.leaving announcement is received. */
+    onPeerLeaving?: (msg: PeerLeaving) => void;
+    /**
+     * Callback when a peer.agent-token.revoke announcement is received.
+     * The local handler should call agentRegistry.disconnectByTokenId(tokenId)
+     * to close every in-flight WS authenticated by the now-revoked token.
+     */
+    onAgentTokenRevoke?: (msg: PeerAgentTokenRevoke) => void;
+    /**
+     * Callback when a config reload request is received from a peer.
+     * Should execute a local config reload and return the result fields,
+     * which are sent back via peer.config.reload.response.
+     *
+     * If undefined, incoming reload requests are answered with success=false
+     * and an error explaining that reload is unavailable on this peer.
+     */
+    onPeerConfigReload?: (msg: PeerConfigReload) => Promise<{
+        success: boolean;
+        version?: number;
+        errors?: string[];
+        restartRequired?: string[];
+        fieldsChanged?: string[];
+    }>;
+}
+/**
+ * Create a handler function for incoming peer WebSocket connections.
+ *
+ * Returns `handleConnection(ws, remoteIp?)` which should be called when a new
+ * WebSocket connection is upgraded on the peer endpoint.
+ */
+export declare function createPeerHandler(deps: PeerHandlerDeps): {
+    handleConnection: (ws: PeerWsLike, remoteIp?: string) => void;
+    sendToPeer: (targetInstanceId: string, msg: PeerToPeerMessage) => boolean;
+    sendAndWaitAck: (targetInstanceId: string, msg: JobReroute, timeoutMs?: number) => Promise<boolean>;
+    sendConfigReloadAndWait: (targetInstanceId: string, msg: PeerConfigReload, timeoutMs?: number) => Promise<PeerConfigReloadResponse | null>;
+    getConnectionCount: () => number;
+    broadcastHeartbeat: (inventory: Omit<PeerHeartbeat, "type">) => void;
+    broadcastAgentTokenRevoke: (msg: PeerAgentTokenRevoke) => void;
+    cleanup: () => void;
+    closeAllInbound: () => void;
+};
+//# sourceMappingURL=peer-handler.d.ts.map

package/dist/cluster/peer-registry.d.ts

@@ -0,0 +1,186 @@
+/**
+ * In-memory peer registry for tracking orchestrator peers in a cluster.
+ *
+ * Maintains peer state including agent inventories from heartbeats,
+ * enabling routing decisions without real-time queries. Follows the
+ * same label-matching semantics as agent/registry.ts for consistency.
+ */
+import type { PeerHeartbeat, PeerCapabilities, ScalerCapacitySummary } from '@kici-dev/engine';
+export interface PeerAgentInfo {
+    agentId: string;
+    labels: string[];
+    activeJobs: number;
+    maxConcurrency: number;
+    platform: string;
+    arch: string;
+    /**
+     * Kubernetes-taint-style mandatory labels inherited from the spawning
+     * scaler. Empty for static agents and warm-pool replenishment spawns.
+     * Cross-peer routing applies the same gate the local label matcher does:
+     * a connected-agent entry only matches when every mandatory label appears
+     * in the required label set.
+     */
+    mandatoryLabels: string[];
+}
+export interface PeerInfo {
+    instanceId: string;
+    connectionId: string;
+    address: string | null;
+    routingKeys: string[];
+    connected: boolean;
+    lastHeartbeatAt: number;
+    agents: PeerAgentInfo[];
+    draining: boolean;
+    capabilities: PeerCapabilities;
+    term: number;
+    leaderId: string | null;
+    /** Scaler-advertised capacity for on-demand backends (from heartbeat). */
+    scalerCapacity?: ScalerCapacitySummary[];
+    /** Shared config version reported by this peer (0 = unknown/legacy). */
+    configVersion: number;
+    /** Registry version reported by this peer (0 = unknown/legacy). */
+    registryVersion: number;
+    /** Cluster role of the peer. */
+    role: 'coordinator' | 'worker';
+    hostname?: string;
+    osRelease?: string;
+    totalMemoryMb?: number;
+    memoryUsedMb?: number;
+    memoryAvailableMb?: number;
+    cpuCount?: number;
+    uptimeSeconds?: number;
+    nodeVersion?: string;
+    runningAsUser?: string | null;
+    runningAsUid?: number | null;
+    version?: string | null;
+}
+export interface PeerRegistryOptions {
+    /** Called when a peer's configVersion is higher than the local version. */
+    onConfigVersionBehind?: (peerVersion: number) => void;
+    /** Called when a peer's registryVersion is higher than the local version. */
+    onRegistryVersionBehind?: (peerVersion: number) => void;
+    /** Called when a peer transitions to disconnected state. */
+    onPeerDisconnected?: (instanceId: string) => void;
+}
+export declare class PeerRegistry {
+    private readonly peers;
+    private localConfigVersion;
+    private localRegistryVersion;
+    private readonly onConfigVersionBehind?;
+    private readonly onRegistryVersionBehind?;
+    private readonly onPeerDisconnected?;
+    constructor(options?: PeerRegistryOptions);
+    /**
+     * Update the local config version for comparison with peer heartbeats.
+     */
+    setLocalConfigVersion(version: number): void;
+    /**
+     * Update the local registry version for comparison with peer heartbeats.
+     */
+    setLocalRegistryVersion(version: number): void;
+    /**
+     * Add or update a peer entry. Sets initial connected state to true.
+     * If the peer already exists and is connected, preserves capabilities
+     * (avoids the incoming handler resetting data set by the outgoing client).
+     * On fresh add or disconnected peer, starts with empty capabilities —
+     * auth response or first heartbeat will populate fresh data.
+     */
+    addPeer(info: {
+        instanceId: string;
+        connectionId: string;
+        address: string | null;
+        routingKeys: string[];
+        role?: 'coordinator' | 'worker';
+    }): void;
+    /**
+     * Remove a peer entirely from the registry.
+     */
+    removePeer(instanceId: string): void;
+    /**
+     * Update peer state from a heartbeat message.
+     * Updates agent inventory, draining status, capabilities, term, leaderId,
+     * and lastHeartbeatAt timestamp.
+     */
+    updateHeartbeat(instanceId: string, heartbeat: PeerHeartbeat): void;
+    /**
+     * Get a single peer by instanceId.
+     */
+    getPeer(instanceId: string): PeerInfo | undefined;
+    /**
+     * Get all tracked peers.
+     */
+    getAllPeers(): PeerInfo[];
+    /**
+     * Get only connected peers.
+     */
+    getConnectedPeers(): PeerInfo[];
+    /**
+     * Find peers whose agents or scaler backends match any of the given label
+     * sets AND have available capacity.
+     *
+     * A peer matches if EITHER:
+     * 1. Connected agents: at least one agent's labels are a superset of a
+     *    required label set with activeJobs < maxConcurrency.
+     * 2. Scaler capacity: at least one scaler backend has activeCount < maxAgents
+     *    AND its label sets overlap with the required label sets (same
+     *    intersection semantics as agent matching).
+     *
+     * Excludes draining peers and disconnected peers.
+     *
+     * @param labelSets - Array of label sets. A peer matches if ANY of its
+     *   agents or scaler backends match ANY of the label sets with capacity.
+     */
+    findPeersWithCapacity(labelSets: string[][]): PeerInfo[];
+    /**
+     * Find peers whose agents or scaler backends match any of the given label sets,
+     * regardless of current capacity. Used to differentiate "no peer handles this label"
+     * from "peers exist but are at capacity".
+     *
+     * Excludes disconnected and draining peers.
+     */
+    findPeersWithLabels(labelSets: string[][]): PeerInfo[];
+    /**
+     * Mark a peer as disconnected and immediately evict its capabilities.
+     * No grace period — disconnected peers have no usable agents or scaler capacity.
+     */
+    markDisconnected(instanceId: string): void;
+    /**
+     * Mark a peer as connected.
+     */
+    markConnected(instanceId: string): void;
+    /**
+     * Check if a peer's last heartbeat is older than the given threshold.
+     */
+    isStale(instanceId: string, thresholdMs: number): boolean;
+    /**
+     * Total number of tracked peers (connected + disconnected).
+     */
+    getPeerCount(): number;
+    /**
+     * Number of currently connected peers.
+     */
+    getConnectedPeerCount(): number;
+    /**
+     * Get count of connected coordinator (non-worker) peers.
+     * Used for Raft quorum calculations — workers don't participate in elections.
+     */
+    getConnectedCoordinatorPeerCount(): number;
+    /**
+     * Evict stale peers whose last heartbeat exceeds the timeout.
+     * Marks them as disconnected and clears their capabilities.
+     * Returns the list of evicted peer instanceIds.
+     *
+     * called on a timer by the coordinator
+     * (2 missed heartbeats at 30s interval = 60s default timeout).
+     */
+    evictStalePeers(staleTimeoutMs: number): string[];
+    /**
+     * Get all peers with role=worker.
+     */
+    getWorkerPeers(): PeerInfo[];
+    /**
+     * Get all peers with role=coordinator.
+     */
+    getCoordinatorPeers(): PeerInfo[];
+}
+//# sourceMappingURL=peer-registry.d.ts.map

package/dist/cluster/raft-state.d.ts

@@ -0,0 +1,36 @@
+/**
+ * Postgres-backed Raft state persistence.
+ *
+ * Stores the minimal Raft persistent state (currentTerm, votedFor, leaderId)
+ * in the raft_state table. One row per cluster (default cluster_id = 'default').
+ * State is loaded on node startup and saved on term/vote/leader transitions.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+export interface RaftPersistentState {
+    currentTerm: number;
+    votedFor: string | null;
+    leaderId: string | null;
+}
+export declare class RaftStateStore {
+    private readonly db;
+    private readonly clusterId;
+    constructor(deps: {
+        db: Kysely<Database>;
+        clusterId?: string;
+    });
+    /**
+     * Load persisted Raft state from the DB.
+     * Returns defaults (term=0, votedFor=null, leaderId=null) if no row exists.
+     */
+    load(): Promise<RaftPersistentState>;
+    /**
+     * Upsert full Raft state into the DB.
+     */
+    save(state: RaftPersistentState): Promise<void>;
+    /**
+     * Update just the leader and term fields (lightweight update for heartbeat acceptance).
+     */
+    updateLeader(leaderId: string, term: number): Promise<void>;
+}
+//# sourceMappingURL=raft-state.d.ts.map