@kici-dev/orchestrator 0.17.0 → 0.19.0

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

@@ -1,15 +1,15 @@
 /**
  * WebSocket handler for incoming peer connections from other orchestrators.
  *
- * Accepts WS upgrade, performs ECDH key exchange, and authenticates the peer
- * with mutual-v2: `peer.hello` advertises the scheme, the peer proves its
- * credential (or, on first join, its join token) with an HMAC over the
- * handshake transcript, and this server answers with its own proof and
- * switches to the application key. A join token never arrives here: the peer
- * sends the token's routing segment, and the role and routing key come from
- * the join_tokens row. A request in the scheme earlier releases used is refused
- * with PEER_MUTUAL_AUTH_REQUIRED_REASON. Registers the peer in PeerRegistry and
- * routes messages bidirectionally. Sends periodic heartbeats to the peer.
+ * Performs ECDH key exchange and authenticates the peer with mutual-v2:
+ * `peer.hello` advertises the scheme, the peer proves its credential (or, on
+ * first join, its join token) with an HMAC over the handshake transcript, and
+ * this server answers with its own proof and switches to the application key.
+ * A join token never arrives here: the peer sends the token's routing segment,
+ * and the role and routing key come from the join_tokens row. A request in the
+ * scheme earlier releases used is refused with PEER_MUTUAL_AUTH_REQUIRED_REASON.
+ * Registers the peer in PeerRegistry, routes messages both ways, and sends
+ * periodic heartbeats.
  */
 import { type PeerHeartbeat, type PeerToPeerMessage, type JobReroute, type JobProgress, type JobProgressAck, type PeerScalerEvent, type PeerJobCancel, type PeerLogChunk, type PeerCacheUploadRequest, type PeerCacheUploadResponse, type PeerConfigReload, type PeerConfigReloadResponse, type PeerScalerOrphansRequest, type PeerForgetRequest, type PeerForgetResponse, type PeerScalerOrphansResponse, type PeerClusterSettingsRequest, type WorkerClusterSettings, type PeerLogsCollectRequest, type PeerLeaving, type PeerAgentTokenRevoke, type RaftVoteRequest, type RaftVoteResponse, type RaftAppendEntries, type PeerScalerReloadRequest, type PeerScalerReloadResponse } from '@kici-dev/engine';
 import { type PeerRegistry } from './peer-registry.js';
@@ -19,10 +19,7 @@ import type { PEER_REQUEST_TIMEOUT } from './peer-request-waiters.js';
 import type { ScalerFileReload } from '../scaler/file-reload.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.
- */
+/** Minimal WebSocket surface (like agent/registry.ts WsLike), so tests can mock it. */
 export interface PeerWsLike {
     send(data: string): void;
     close(code?: number, reason?: string): void;
@@ -30,63 +27,49 @@ export interface PeerWsLike {
     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). */
+    /** 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. */
+    /** This orchestrator's local agent inventory, sent in heartbeats. */
     getLocalInventory: () => Omit<PeerHeartbeat, 'type'>;
     /**
-     * The Platform-pushed worker ceiling this coordinator enforces, or `null`
-     * when none was ever received (admit worker joins freely). Read at each
-     * worker-peer admission. Served from the persisted PlanHeadroomStore, so it
-     * survives a Platform disconnect — the coordinator keeps enforcing the last
-     * known ceiling rather than resetting to unlimited.
+     * The Platform-pushed worker ceiling, read at each worker-peer admission;
+     * `null` when none was ever received (admit freely). Served from the
+     * persisted PlanHeadroomStore, so the last known ceiling survives a Platform
+     * disconnect rather than resetting to unlimited.
      */
     getWorkerCeiling?: () => Promise<number | null>;
     /** 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, fromPeerId: string, reply: (m: JobProgressAck) => void) => void;
-    /** Callback when a scaler provisioning event is forwarded by a worker peer. */
+    /** A scaler provisioning event a worker peer forwarded. */
     onPeerScalerEvent?: (msg: PeerScalerEvent, fromPeerId: string) => 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. */
+    /** A log chunk a worker peer relayed. */
     onPeerLogChunk?: (chunk: PeerLogChunk, peerId: string) => void;
-    /** Callback when a cache upload request is received from a worker peer. */
+    /** A cache upload request 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). */
+    /** Forwarded to the Raft module. */
     onRaftVoteResponse?: (msg: RaftVoteResponse) => void;
-    /** Callback for Raft append entries (leader heartbeat). */
+    /** 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.
+     * Should call agentRegistry.disconnectByTokenId(tokenId) to close every
+     * in-flight WS authenticated by the 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.
+     * Runs a local config reload; the result goes back via
+     * peer.config.reload.response. If undefined, requests are answered with
+     * success=false and an error saying reload is unavailable on this peer.
      */
     onPeerConfigReload?: (msg: PeerConfigReload) => Promise<{
         success: boolean;
@@ -96,41 +79,36 @@ export interface PeerHandlerDeps {
         fieldsChanged?: string[];
     }>;
     /**
-     * Callback when a peer.clusterSettings.request arrives from a DB-less worker.
-     * Resolves the worker-relevant settings snapshot (async DB read) and the
-     * current cluster_settings version; the result is sent back via
-     * peer.clusterSettings.response. If undefined, requests are answered with the
-     * config-default snapshot at version 0.
+     * Resolves a DB-less worker's settings snapshot and the cluster_settings
+     * version, sent back via peer.clusterSettings.response. If undefined,
+     * requests are answered with the config-default snapshot at version 0.
      */
     onPeerClusterSettingsRequest?: (msg: PeerClusterSettingsRequest) => Promise<{
         version: number;
         settings: WorkerClusterSettings;
     }>;
     /**
-     * Callback when a peer.logs.collect.request arrives from an incoming-dialed
-     * peer. Builds this node's subtree bundle and streams it back through `send`
-     * (peer.logs.collect.chunk frames, or a peer.logs.collect.error on failure).
-     * If undefined, incoming collect requests are ignored.
+     * Builds this node's subtree bundle and streams it back through `send`
+     * (peer.logs.collect.chunk frames, or peer.logs.collect.error on failure).
+     * If undefined, collect requests are ignored.
      */
     onLogsCollectRequest?: (msg: PeerLogsCollectRequest, send: (out: PeerToPeerMessage) => boolean) => Promise<void>;
     /**
-     * Answers a peer.scaler.orphans.request a coordinator forwarded to this node
-     * (`kici-admin scaler orphans --target`). A request from a peer that is not
-     * a coordinator is refused before it reaches the handler. If undefined,
-     * requests are answered with ok=false.
+     * Answers a forwarded peer.scaler.orphans.request (`kici-admin scaler orphans
+     * --target`). A non-coordinator peer's request is refused before it reaches
+     * the handler. If undefined, requests are answered with ok=false.
      */
     onScalerOrphansRequest?: ScalerOrphansRequestHandler;
     /**
-     * Reloads this node's scaler config for a peer.scaler.reload.request
-     * (`kici-admin scaler reload`). A request from a peer that is not a
-     * coordinator is refused before it reaches the handler. If undefined,
-     * requests are answered `rejected`.
+     * Reloads this node's scaler config (`kici-admin scaler reload`). A
+     * non-coordinator peer's request is refused before it reaches the handler. If
+     * undefined, requests are answered `rejected`.
      */
     onScalerReloadRequest?: ScalerFileReload;
     /**
      * Forgets a departed peer a sibling coordinator forgot (`kici-admin peer
-     * forget`). A request from a peer that is not a coordinator is refused. If
-     * undefined, requests are answered with outcome `error`.
+     * forget`). A non-coordinator peer's request is refused. If undefined,
+     * requests are answered with outcome `error`.
      */
     onPeerForgetRequest?: PeerForgetRequestHandler;
 }
@@ -141,22 +119,20 @@ export declare const ADVERTISED_PEER_AUTH_SCHEMES: readonly string[];
  * a proof or a token, or names no scheme.
  */
 export declare function isLegacyPeerAuthRequest(raw: unknown): boolean;
-/**
- * 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.
- */
 /**
  * Whether a joining peer may be admitted against the plan ceiling.
  *
  * Only workers are gated: a coordinator peer holds its own Platform connection
  * and is counted there, and a peer advertising no role registers as a
- * coordinator (see PeerRegistry.addPeer), so neither is gated here. A `null`
- * ceiling — none ever received — admits freely. The ceiling is ABSOLUTE, so the
- * join is admitted only while the currently-connected worker count is below it.
+ * coordinator (see PeerRegistry.addPeer). A `null` ceiling (none ever received)
+ * admits freely. The ceiling is ABSOLUTE: admit only while the connected worker
+ * count is below it.
  */
 export declare function shouldAdmitWorker(role: string | undefined, ceiling: number | null, connectedWorkerCount: number): boolean;
+/**
+ * Returns `handleConnection(ws, remoteIp?)`, called for each WebSocket upgraded
+ * on the peer endpoint.
+ */
 export declare function createPeerHandler(deps: PeerHandlerDeps): {
     handleConnection: (ws: PeerWsLike, remoteIp?: string) => void;
     sendToPeer: (targetInstanceId: string, msg: PeerToPeerMessage) => boolean;

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

@@ -1,9 +1,6 @@
 /**
- * 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.
+ * In-memory registry of cluster peers, including heartbeat agent inventories, so
+ * routing needs no real-time queries. Label matching follows agent/registry.ts.
  */
 import type { PeerAuthScheme, PeerHeartbeat, PeerCapabilities, ScalerCapacitySummary } from '@kici-dev/engine';
 /** Which side of a peer link authenticated: the peer dialled us, or we dialled it. */
@@ -24,17 +21,14 @@ export interface PeerAgentInfo {
     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.
+     * Taint-style mandatory labels inherited from the spawning scaler; empty for
+     * static agents and warm-pool replenishment spawns. Cross-peer routing matches
+     * only when every one is in the required label set, like the local matcher.
      */
     mandatoryLabels: string[];
     /**
-     * Name of the scaler backend that spawned this agent, or null for static
-     * (stateful) agents not bound to any scaler. Surfaced in diagnostics so the
-     * dashboard can group a peer's agents under the correct scaler row.
+     * The spawning scaler backend, or null for static (stateful) agents; the
+     * dashboard groups a peer's agents under this scaler row.
      */
     scalerName?: string | null;
 }
@@ -60,9 +54,7 @@ export interface PeerInfo {
     registryVersion: number;
     /** Cluster-settings version reported by this peer (0 = unknown/legacy). */
     clusterSettingsVersion: number;
-    /** Cluster role of the peer. */
     role: 'coordinator' | 'worker';
-    /** The authentication scheme of each link direction. */
     authScheme: PeerAuthSchemes;
     hostname?: string;
     osRelease?: string;
@@ -77,18 +69,15 @@ export interface PeerInfo {
     version?: string | null;
 }
 export interface PeerRegistryOptions {
-    /** Called when a peer's configVersion is higher than the local version. */
+    /** Each `...VersionBehind` fires when a peer reports a higher version than local. */
     onConfigVersionBehind?: (peerVersion: number) => void;
-    /** Called when a peer's registryVersion is higher than the local version. */
     onRegistryVersionBehind?: (peerVersion: number) => void;
-    /** Called when a peer's clusterSettingsVersion is higher than the local version. */
     onClusterSettingsVersionBehind?: (peerVersion: number) => void;
-    /** Called when a peer transitions to disconnected state. */
     onPeerDisconnected?: (instanceId: string) => void;
     /**
-     * Called when the connected-peer set changes (a fresh add or a
-     * markDisconnected), so a coordinator can re-report its `cluster.membership`
-     * snapshot to the Platform without waiting for the periodic interval.
+     * Fires when the connected set changes (fresh add or markDisconnected), so a
+     * coordinator re-reports `cluster.membership` to the Platform before the
+     * periodic interval.
      */
     onMembershipChange?: () => void;
 }
@@ -103,26 +92,15 @@ export declare class PeerRegistry {
     private readonly onPeerDisconnected?;
     private readonly onMembershipChange?;
     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;
-    /**
-     * Update the local cluster-settings version for comparison with peer
-     * heartbeats. A worker sets this after pulling a snapshot so it stops
-     * re-firing the version-behind hook on every subsequent heartbeat.
-     */
+    /** A worker sets this after pulling a snapshot, so the behind-hook stops re-firing. */
     setLocalClusterSettingsVersion(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.
+     * Add or update a peer as connected. An already-connected peer keeps its
+     * capabilities, so the incoming handler cannot reset what the outgoing client
+     * set; a fresh or disconnected peer starts empty until the auth response or
+     * first heartbeat fills it.
      */
     addPeer(info: {
         instanceId: string;
@@ -133,37 +111,20 @@ export declare class PeerRegistry {
     }): void;
     /** Record the scheme one direction of the link authenticated with, or null when it closed. */
     setAuthScheme(instanceId: string, direction: PeerLinkDirection, scheme: PeerAuthScheme | null): 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.
+     * Apply a heartbeat to the peer's state.
      *
-     * A heartbeat is an ingress into the label-matching domain, so every label
-     * it carries is folded here rather than at each comparison site. A peer
-     * running an older build sends the case its operator typed — `Docker` — and
-     * every consumer of `PeerInfo` compares against folded job selectors, so a
-     * consumer that forgets to fold silently stops counting that peer's agents.
-     * Folding on arrival means a consumer cannot forget.
+     * Every label is folded here, on ingress, not at each comparison site: an older
+     * peer build sends the operator's case (`Docker`), and a `PeerInfo` consumer that
+     * forgot to fold would silently stop counting that peer's agents.
      *
-     * Identifiers are deliberately NOT folded: `agentId`, `scalerName`, and the
-     * scaler's `name` / `type` are opaque and case-sensitive.
+     * Identifiers are NOT folded: `agentId`, `scalerName`, and the scaler's
+     * `name` / `type` are opaque and case-sensitive.
      */
     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
@@ -173,73 +134,43 @@ export declare class PeerRegistry {
      * 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).
+     *    AND one of its label sets is a superset of a required label set and
+     *    passes that set's mandatory-label gate (the same subset-plus-gate check
+     *    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.
+     * Like {@link findPeersWithCapacity} without the capacity filter, to tell "no
+     * peer handles this label" from "peers exist but are at capacity".
      */
     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.
+     * Evict capabilities immediately, with no grace period: a disconnected peer has
+     * 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.
-     */
+    /** An unknown peer counts as stale. */
     isStale(instanceId: string, thresholdMs: number): boolean;
-    /**
-     * Total number of tracked peers (connected + disconnected).
-     */
+    /** Connected and 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.
-     */
+    /** For Raft quorum: workers do not take part 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).
+     * Mark peers past the heartbeat timeout disconnected; returns their ids. The
+     * coordinator calls it on a timer (2 missed heartbeats at 30s = 60s default).
      */
     evictStalePeers(staleTimeoutMs: number): string[];
-    /**
-     * Get all peers with role=worker.
-     */
     getWorkerPeers(): PeerInfo[];
     /**
-     * Currently-connected worker peers.
-     *
-     * A peer that advertises no role registers as a coordinator (see `addPeer`),
-     * so a worker predating the role field is not counted here. That under-counts,
-     * which errs permissive, and it self-heals as workers upgrade.
+     * A peer advertising no role registers as a coordinator (`addPeer`), so a worker
+     * predating the role field is not counted: under-counting errs permissive and
+     * self-heals as workers upgrade.
      */
     getConnectedWorkerPeers(): PeerInfo[];
-    /**
-     * Get all peers with role=coordinator.
-     */
     getCoordinatorPeers(): PeerInfo[];
 }
 //# sourceMappingURL=peer-registry.d.ts.map

package/dist/cluster/plan-headroom-store.d.ts

@@ -10,12 +10,10 @@ export interface StoredPlanHeadroom {
     updatedAt: Date;
 }
 /**
- * The orchestrator's cache of the Platform-owned worker ceiling.
- *
- * Persisted so a coordinator restarting during a Platform outage keeps
- * enforcing the last known ceiling instead of resetting to unlimited. Same
- * ownership shape as `org_trust_policy`: the Platform writes it, the
- * orchestrator only reads it back.
+ * Persisted cache of the Platform-owned worker ceiling, so a coordinator
+ * restarting during a Platform outage keeps the last known ceiling instead of
+ * unlimited. Like `org_trust_policy`, the Platform writes it and the orchestrator
+ * only reads it back.
  */
 export declare class PlanHeadroomStore {
     private readonly db;

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

@@ -1,9 +1,8 @@
 /**
  * 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.
+ * One raft_state row per cluster (default cluster_id = 'default'), loaded on
+ * node startup and saved on term/vote/leader transitions.
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
@@ -19,14 +18,8 @@ export declare class RaftStateStore {
         db: Kysely<Database>;
         clusterId?: string;
     });
-    /**
-     * Load persisted Raft state from the DB.
-     * Returns defaults (term=0, votedFor=null, leaderId=null) if no row exists.
-     */
+    /** Returns term=0, votedFor=null, leaderId=null when no row exists. */
     load(): Promise<RaftPersistentState>;
-    /**
-     * Upsert full Raft state into the DB.
-     */
     save(state: RaftPersistentState): Promise<void>;
     /**
      * Upsert full Raft state unless the stored term is newer. A coordinator that
@@ -34,9 +27,7 @@ export declare class RaftStateStore {
      * coordinators may already have elected a leader in a newer term.
      */
     saveUnlessNewerTerm(state: RaftPersistentState): Promise<void>;
-    /**
-     * Update just the leader and term fields (lightweight update for heartbeat acceptance).
-     */
+    /** Lightweight leader + term update on heartbeat acceptance. */
     updateLeader(leaderId: string, term: number): Promise<void>;
 }
 //# sourceMappingURL=raft-state.d.ts.map

package/dist/cluster/raft.d.ts

@@ -32,7 +32,7 @@ interface RaftNodeDeps {
     electionTimeoutMinMs?: number;
     electionTimeoutMaxMs?: number;
     leaderHeartbeatMs?: number;
-    /** Grace period in ms before dormant-mode self-election. Default: 0 (no grace period). */
+    /** Grace period in ms before dormant-mode self-election. Default: 0. */
     gracePeriodMs?: number;
 }
 export declare class RaftNode {
@@ -60,94 +60,59 @@ export declare class RaftNode {
     private stopped;
     private electionTimer;
     private leaderHeartbeatTimer;
-    /** Votes received during the current election as candidate. */
     private votesReceived;
     /**
-     * Consecutive elections where no peer responded with a vote.
-     * When this exceeds the threshold, the node force-self-elects as a safety
-     * valve against delayed WebSocket close detection (peer appears "connected"
-     * but is actually dead).
+     * Consecutive elections no peer answered. Past the threshold the node
+     * force-self-elects: a safety valve against delayed WebSocket close detection
+     * (a dead peer still appears connected).
      */
     private consecutiveUnansweredElections;
     constructor(deps: RaftNodeDeps);
-    /**
-     * Start the Raft node. Loads persisted state from DB and starts
-     * as follower with election timer.
-     */
+    /** Loads persisted state and starts as a follower with an election timer. */
     start(): Promise<void>;
     /**
-     * Stop the Raft node. Clears its timers, ends its leadership (so the
-     * leader-only services stop with it), and persists its state. Every election
-     * input after this is ignored until the next {@link start}. A second call does
-     * nothing.
+     * Clears the timers, ends leadership (so the leader-only services stop with
+     * it), and persists state. Every election input after this is ignored until
+     * the next {@link start}. A second call does nothing.
      */
     stop(): Promise<void>;
-    /** Whether this node is the current leader. */
     isLeader(): boolean;
-    /** Get the current known leader's instance ID. */
     getLeaderId(): string | null;
-    /** Get the current Raft term. */
     getCurrentTerm(): number;
-    /** Get the current role (for testing/diagnostics). */
+    /** For testing and diagnostics. */
     getRole(): RaftRole;
     /**
-     * Handle a peer.leaving announcement from a gracefully shutting down peer.
-     * If the leaving peer is the current leader, immediately clear leaderId and
-     * start a new election. Otherwise, no election action (peer registry update
-     * is done by the caller before calling this method).
+     * Handle a peer.leaving announcement. If the leaving peer is the leader, clear
+     * leaderId and start a new election at once; otherwise do nothing (the caller
+     * updates the peer registry first).
      */
     handlePeerLeaving(instanceId: string): void;
-    /**
-     * Reset the election timer with a randomized timeout.
-     * On expiry, starts an election.
-     */
+    /** Restart the election timer with a randomized timeout. */
     resetElectionTimer(): void;
     private clearElectionTimer;
     /**
      * Notify Raft that a peer disconnected. If this node is a follower or
      * candidate, reset the election timer to a short value so Raft quickly
      * re-evaluates whether it should self-elect (dormant mode).
-     * Without this, the node waits for the full election timeout (3-5s)
+     * Without this, the node waits for the full election timeout (5-10s by default)
      * before discovering all peers are gone.
      */
     onPeerDisconnected(): void;
     /**
-     * Start a new election. Increment term, vote for self, request votes
-     * from peers. If no peers are connected, self-elect immediately
-     * (dormant mode for single-orchestrator deployments).
+     * Increment the term, vote for self and request votes. With no peers
+     * connected, self-elect at once (dormant mode).
      */
     private startElection;
-    /**
-     * Handle an incoming vote request from another candidate.
-     */
     handleVoteRequest(msg: RaftVoteRequest): RaftVoteResponse;
-    /**
-     * Handle a vote response from a peer.
-     */
     handleVoteResponse(msg: RaftVoteResponse): void;
-    /**
-     * Check if we have a majority of votes to become leader.
-     * Cluster size = connected peers + self.
-     */
+    /** Cluster size = connected coordinator peers + self. */
     private checkMajority;
-    /**
-     * Transition to leader role. Start heartbeat timer, persist state,
-     * call onBecomeLeader callback.
-     */
     private becomeLeader;
-    /**
-     * Step down from leader/candidate to follower.
-     */
     private stepDown;
-    /**
-     * Start sending periodic leader heartbeats (raft.append.entries).
-     */
+    /** Periodic leader heartbeats (raft.append.entries). */
     private startLeaderHeartbeat;
     private sendHeartbeat;
     private clearLeaderHeartbeat;
-    /**
-     * Handle an incoming append entries (heartbeat) from a leader.
-     */
     handleAppendEntries(msg: RaftAppendEntries): void;
 }
 export {};