@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/cluster/leader-gated-scheduler.d.ts

@@ -14,16 +14,12 @@ export interface LeaderGatedSchedulerOptions {
     onBecomeLeader?: () => Promise<void> | void;
     /** Whether to unref the interval timer. Default true; pass false to keep the loop alive. */
     unref?: boolean;
-    /**
-     * Logger for the lifecycle + tick-error lines. Pass the owning class's logger so the log
-     * prefix stays that of the scheduler site; defaults to a `leader-gated-scheduler` logger.
-     */
+    /** The owning class's logger, to keep its log prefix; defaults to `leader-gated-scheduler`. */
     logger?: SchedulerLogger;
 }
 /**
- * Raft-leader-only periodic scheduler. Encapsulates the become -> (optional async setup) ->
- * start-interval / lose -> stop lifecycle that the orchestrator's leader-gated schedulers share.
- * The interval runs only while this node is the leader. `stop()` is final: no
+ * Raft-leader-only periodic scheduler: become -> (optional async setup) -> start interval;
+ * lose -> stop. The interval runs only while this node is the leader. `stop()` is final: no
  * later leadership change starts another tenure.
  */
 export declare class LeaderGatedScheduler {
@@ -32,18 +28,13 @@ export declare class LeaderGatedScheduler {
     private leader;
     private readonly logger;
     /**
-     * Monotonic tenure counter. Bumped on every leadership transition
-     * (onBecomeLeader / onLoseLeadership / stop). onBecomeLeader captures its
-     * tenure at entry and re-checks it after the awaited setup: if it changed
-     * during the async setup, leadership was revoked (or superseded by a newer
-     * tenure) mid-flight and this stale tenure must NOT start the interval — that
-     * would leak a timer running tick() while no longer leader.
+     * Monotonic tenure counter, bumped on every leadership transition (onBecomeLeader /
+     * onLoseLeadership / stop). onBecomeLeader re-checks it after the awaited setup: if it
+     * changed, this stale tenure must NOT start the interval, or a timer leaks running tick()
+     * while no longer leader.
      */
     private generation;
-    /**
-     * Set by {@link stop}: the owning process is shutting down, so no later
-     * leadership change starts another tenure.
-     */
+    /** Set by {@link stop}: no later leadership change starts another tenure. */
     private stopped;
     constructor(opts: LeaderGatedSchedulerOptions);
     get isLeader(): boolean;

package/dist/cluster/orphan-recovery.d.ts

@@ -6,7 +6,7 @@
  * to prevent multiple orchestrators from racing to recover the same run.
  *
  * Recovery logic:
- * 1. Find runs with status='running' and stale last update (> threshold)
+ * 1. Find runs with status='running' that started before the stale threshold
  * 2. Check if the coordinator is still a connected peer
  * 3. If coordinator is disconnected/unknown, this is an orphan run
  * 4. Check job statuses: terminal jobs stay, stuck jobs get marked failed
@@ -23,15 +23,15 @@ interface OrphanRecoveryDeps {
     raft: RaftNode;
     peerRegistry: PeerRegistry;
     executionTracker: ExecutionTracker;
-    /** Reader for fleet-wide cluster tunables (reroute flap-grace override). */
+    /** Source of the reroute flap-grace override. */
     clusterSettings: ClusterSettingsReader;
     /** Cluster default for the reroute flap-grace window (config.rerouteFlapGraceMs). */
     rerouteFlapGraceFallbackMs: number;
     /** Scan interval in ms. Default: 60000 (1 minute). */
     scanIntervalMs?: number;
-    /** How long a run must be stale before considered orphaned. Default: 5 minutes. */
+    /** Default: 5 minutes. */
     staleThresholdMs?: number;
-    /** How long a stuck job must have no heartbeat before marking as failed. Default: 3 minutes. */
+    /** Default: 3 minutes. */
     jobStuckThresholdMs?: number;
 }
 export declare class OrphanRecovery {
@@ -46,51 +46,29 @@ export declare class OrphanRecovery {
     private readonly jobStuckThresholdMs;
     private scanTimer;
     constructor(deps: OrphanRecoveryDeps);
-    /**
-     * Start periodic orphan recovery scans.
-     * Only runs recovery logic when this node is the Raft leader.
-     */
+    /** Recovery logic runs only while this node is the Raft leader. */
     start(): void;
-    /**
-     * Stop periodic orphan recovery scans.
-     */
     stop(): void;
-    /**
-     * Scan for orphaned runs and recover them.
-     * Only runs when this node is the Raft leader.
-     */
     scanForOrphans(): Promise<void>;
     /**
      * Release concurrency slots still marked `active` for a run that has already
      * finished. Run once per leader transition (`start()`), which covers a boot
      * and a failover.
      *
-     * A slot outlives its run whenever the release path did not run — a
-     * coordinator crash between "the run finished" and "the slot was released".
-     * On a `max: 1` deploy gate a single leaked slot blocks every later deploy
-     * forever, and nothing else would ever notice: the DB says the slot is held
-     * and the run that held it is gone.
-     *
-     * `getActiveRuns` reconciles the same way inside its own transaction on every
-     * acquire, so this is the sweep for a scope nobody happens to ask about —
-     * which is why once per leader transition is enough.
+     * A coordinator crash between "the run finished" and "the slot was released"
+     * leaks the slot; on a `max: 1` deploy gate it blocks every later deploy
+     * forever, and nothing else notices. `getActiveRuns` reconciles the same way
+     * on every acquire, so this only sweeps scopes nobody asks about — hence once
+     * per leader transition is enough.
      */
     releaseLeakedConcurrencySlots(): Promise<void>;
-    /**
-     * Attempt to recover a single potentially orphaned run.
-     */
     private recoverRun;
     /**
-     * Whether any job of the run moved within the stale window — a heartbeat, a
-     * start, or a completion. A crashed coordinator stops producing all three, so
-     * a genuinely orphaned run becomes eligible again within one window; a healthy
-     * long run never does.
+     * Whether any job had a heartbeat, start or completion within the stale
+     * window. A crashed coordinator stops all three, so an orphaned run becomes
+     * eligible within one window; a healthy long run never does.
      */
     private hasRecentProgress;
-    /**
-     * Check if a coordinator with the given routing key is still connected
-     * as a peer in the cluster.
-     */
     private isCoordinatorStillConnected;
 }
 export {};

package/dist/cluster/peer-auth-coordinator.d.ts

@@ -39,15 +39,9 @@ export declare class PeerAuthCoordinator {
         instanceId: string;
         joinToken?: string;
         joinWaitTimeoutMs?: number;
-        /**
-         * Issues this coordinator its own credential when a decision finds no
-         * credential and no join token. Only a coordinator wires it.
-         */
+        /** Self-issues a credential when there is none and no join token. Coordinator-only. */
         selfIssue?: () => Promise<CoordinatorCredentialOutcome>;
-        /**
-         * Asks this coordinator's own cluster database whether it holds a rejected
-         * credential as valid. Only a coordinator with a database wires it.
-         */
+        /** Asks the own cluster DB whether it holds a rejected credential as valid. */
         corroborateRejection?: (credential: string) => Promise<RejectionCorroboration>;
     });
     /** Run `fn` exclusively against the credential file. */

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

@@ -41,17 +41,14 @@ export declare enum PeerMutualAuthFailure {
 }
 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). */
+    /** For a first-time cluster join; optional when the credential file exists. */
     joinToken?: string;
-    /** Path to the credential file for reconnection. */
     credentialFile: string;
     /** Shared per-orchestrator coordinator that owns the credential file. */
     authCoordinator: PeerAuthCoordinator;
-    /** This orchestrator's instance ID. */
     instanceId: string;
-    /** Peer registry to update on heartbeats from remote peer. */
+    /** Updated on the remote peer's heartbeats. */
     peerRegistry: PeerRegistry;
     /**
      * Where the dialled address came from. A static target reconnects with
@@ -68,51 +65,42 @@ export interface PeerClientOptions {
     handshakeTimeoutMs?: number;
     /** Called when a discovered target fails mutual authentication; the client then stays down. */
     onMutualAuthFailed?: (failure: PeerMutualAuthFailure) => void;
-    /** Callback to get this orchestrator's local agent inventory for heartbeats. */
+    /** This orchestrator's local agent inventory, for heartbeats. */
     getLocalInventory: () => Omit<PeerHeartbeat, 'type'>;
-    /** Heartbeat interval in ms. Default: 30000 (30s). */
+    /** In ms. Default: 30000. */
     heartbeatIntervalMs?: number;
-    /** Maximum reconnect delay in ms. Default: 60000 (60s). */
+    /** In ms. Default: 60000. */
     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, fromPeerId: string, reply: (m: JobProgressAck) => void) => void;
     /**
-     * Callback invoked once this client reaches the `connected` state (initial
-     * connect AND every reconnect). Carries this client's peer URL.
+     * Called on reaching `connected`: the initial connect AND every reconnect.
+     * Carries this client's peer URL.
      */
     onConnected?: (url: string) => void;
-    /** Callback when a coordinator ACKs a terminal job.progress this worker sent. */
+    /** A coordinator ACKed a terminal job.progress this worker sent. */
     onJobProgressAck?: (msg: JobProgressAck) => void;
-    /** This orchestrator's role. Default: 'coordinator'. */
+    /** 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). */
+    /** Coordinator side. */
     onPeerLogChunk?: (chunk: PeerLogChunk) => void;
-    /** Callback when a cache upload request is received from a peer (coordinator side). */
+    /** 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). */
+    /** Forwarded to the Raft module. */
     onRaftVoteResponse?: (msg: RaftVoteResponse) => void;
-    /** Callback for Raft append entries (leader heartbeat). */
+    /** The 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 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.
+     * Runs a local config reload; the result is sent back as
+     * peer.config.reload.response. If undefined, requests get success=false.
      */
     onPeerConfigReload?: (msg: PeerConfigReload) => Promise<{
         success: boolean;
@@ -122,18 +110,15 @@ export interface PeerClientOptions {
         fieldsChanged?: string[];
     }>;
     /**
-     * Callback invoked once the remote peer accepts our auth handshake,
-     * carrying the remote peer's instanceId. Used by callers that initially
-     * register this client in `sub.peerClients` keyed by a placeholder (URL
-     * or stale id) to re-key the map by the canonical instanceId so later
-     * Platform-mediated discovery dedupes against the same client.
+     * Called once the remote peer accepts the auth handshake. Lets a caller that
+     * keyed `sub.peerClients` by a placeholder (URL or stale id) re-key it by the
+     * canonical instanceId, so later Platform-mediated discovery dedupes against
+     * the same client.
      */
     onAuthenticated?: (targetInstanceId: string) => void;
     /**
-     * Callback when a peer.logs.collect.request is received from the peer. Builds
-     * this node's subtree bundle and streams it back via the supplied `send`
-     * (peer.logs.collect.chunk frames, or a peer.logs.collect.error on failure).
-     * If undefined, incoming collect requests are ignored.
+     * Streams this node's subtree bundle back as peer.logs.collect.chunk frames,
+     * or a peer.logs.collect.error on failure. If undefined, requests are ignored.
      */
     onLogsCollectRequest?: PeerLogsCollectResponder;
     /**
@@ -190,7 +175,7 @@ export declare class PeerClient {
     private readonly authCoordinator;
     /** Set true between deciding token-join and receiving the auth response. */
     private isJoiner;
-    /** complete() callback for the in-flight token-join, if this client is joiner. */
+    /** complete() for the in-flight token-join, when this client is the joiner. */
     private joinComplete;
     /** The credential string this client last built a proof with. */
     private lastProvedCredential;
@@ -223,33 +208,24 @@ export declare class PeerClient {
     private readonly onScalerReloadRequest?;
     private readonly onPeerForgetRequest?;
     constructor(options: PeerClientOptions);
-    /** Current connection state. */
     get state(): PeerConnectionState;
-    /** The remote peer's instanceId (set after auth handshake). */
+    /** Set after the auth handshake. */
     get targetInstanceId(): string | null;
-    /**
-     * Initiate connection to the peer orchestrator.
-     */
     connect(): void;
-    /**
-     * Gracefully disconnect. Does not trigger reconnection.
-     */
+    /** Graceful; does not trigger reconnection. */
     disconnect(): void;
     /**
-     * Send a peer protocol message. Returns false if not connected.
-     * Messages are encrypted with the session key.
+     * Encrypts with the session key. Returns false if not connected.
      */
     send(msg: PeerToPeerMessage): boolean;
     /**
-     * Send a message and wait for an ACK response.
-     * Used for job.reroute which expects job.reroute.ack.
+     * Send a job.reroute and wait for its 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.
+     * Worker -> coordinator log relay. Fire-and-forget: no ACK expected.
      */
     sendLogChunk(chunk: PeerLogChunk): boolean;
     /**
@@ -299,15 +275,12 @@ export declare class PeerClient {
      */
     sendLogsCollectAndWait(msg: PeerLogsCollectRequest, timeoutMs: number): Promise<Buffer>;
     /**
-     * Send a cache upload request to the coordinator and wait for a response
-     * with a pre-signed URL.
+     * Ask the coordinator for a pre-signed cache upload 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.
-     */
+    /** Exponential backoff with jitter. */
     getReconnectDelay(): number;
     private doConnect;
     private handleMessage;
@@ -335,29 +308,26 @@ export declare class PeerClient {
     /** The server proved itself: register the peer and start the connected session. */
     private completeAcceptance;
     /**
-     * Handle a rejected peer.auth.response. For the three credential-divergence
-     * reasons, delegate to the coordinator (which deletes the shared file only if
-     * no sibling has refreshed it, preventing a revocation cascade). A failed
-     * token-join releases the in-flight join so siblings can retry. Config-error
-     * reasons (role mismatch / missing auth method / protocol version) skip the
-     * coordinator entirely — deletion would not help.
+     * Handle a rejected peer.auth.response. The credential-divergence reasons go
+     * to the coordinator, which deletes the shared file only if no sibling has
+     * refreshed it (preventing a revocation cascade). A failed token-join releases
+     * the in-flight join so siblings can retry. Config-error reasons (role
+     * mismatch / missing auth method / protocol version) skip the coordinator:
+     * deletion would not help.
      */
     private handleAuthRejected;
     /**
-     * Determine auth method and send encrypted auth request.
+     * Choose the auth method and send the 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.
+     * Credentials are **identity-scoped**, not URL-scoped: every peer-client of
+     * one orchestrator shares one on-disk credential file, and the server
+     * (peer-handler) verifies it by `instanceId` alone. So any peer-client can use
+     * it, as long as the `instanceId` on disk matches ours.
      *
-     * The auth-method decision is delegated to the shared `PeerAuthCoordinator`,
-     * which serializes sibling peer-clients so exactly one token-joins per
-     * reconnect storm (the rest reuse the freshly-written credential). This
-     * client never reads or writes the credential file directly.
+     * The shared `PeerAuthCoordinator` decides the method and serializes sibling
+     * peer-clients, so exactly one token-joins per reconnect storm (the rest reuse
+     * the freshly written credential). This client never reads or writes the
+     * credential file directly.
      */
     private sendAuthRequest;
     /**

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

@@ -5,14 +5,10 @@ export declare enum PeerCredentialIssuance {
     Self = "self"
 }
 /**
- * `metadata` key set when a coordinator retires the self-issued credential its
- * previous run left behind. An operator revoke never sets it, which is how a
- * retirement is told apart from a revoke.
+ * `metadata` key set when a coordinator retires its previous run's self-issued
+ * credential. An operator revoke never sets it, which tells the two apart.
  */
 export declare const RETIRED_BY_INSTANCE_KEY = "retiredByInstance";
-/**
- * A peer credential record stored in the coordinator's database.
- */
 export interface PeerCredential {
     id: string;
     instanceId: string;
@@ -28,10 +24,9 @@ export interface PeerCredential {
     metadata: Record<string, unknown>;
 }
 /**
- * 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.
+ * The local credential file (~/.kici/credential.json). Identity-scoped: one file
+ * per orchestrator, shared by all its peer-clients (see `sendAuthRequest` in
+ * peer-client.ts).
  */
 export interface CredentialFileData {
     instanceId: string;
@@ -40,25 +35,17 @@ export interface CredentialFileData {
     /** 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.
- */
+/** The coordinator's DB store of every cluster member's credential. */
 export declare class PeerCredentialStore {
     private readonly db;
     constructor(db: Kysely<any>);
     /**
-     * Save a new peer credential, revoking any prior active credential for the
-     * same instanceId (the `peer_credentials_active_uniq` partial unique index
-     * permits exactly one active credential per instanceId).
+     * Save a credential, revoking the instanceId's prior active one
+     * (`peer_credentials_active_uniq` permits one active credential per instanceId).
      *
-     * Returns `{ revokedCount }` — how many previously-active credentials this
-     * save revoked. Because a coordinator's peer-clients share one
-     * identity-scoped credential, a `revokedCount > 0` here means every sibling
-     * peer-client of `instanceId` that was authenticating with the old
-     * credential is now invalidated and will be rejected on its next proof. The
-     * caller logs this so a revoke that cascades sibling rejections is visible in
-     * the orchestrator logs.
+     * `revokedCount > 0` means every sibling peer-client of `instanceId` still on the
+     * old shared credential is rejected on its next proof; the caller logs it so a
+     * cascade of sibling rejections is visible.
      */
     save(opts: {
         instanceId: string;
@@ -71,13 +58,9 @@ export declare class PeerCredentialStore {
     }): Promise<{
         revokedCount: number;
     }>;
-    /**
-     * Find a non-revoked, non-expired credential by its hash.
-     */
+    /** Non-revoked, non-expired credential by hash. */
     findByCredentialHash(hash: string): Promise<PeerCredential | null>;
-    /**
-     * Find a non-revoked, non-expired credential by instance ID.
-     */
+    /** Newest non-revoked, non-expired credential for the instance. */
     findByInstanceId(instanceId: string): Promise<PeerCredential | null>;
     /**
      * The credential row for `instanceId` that nobody revoked, expired or not.
@@ -87,60 +70,31 @@ export declare class PeerCredentialStore {
     /** The most recently revoked credential row for `instanceId`, or null. */
     findLatestRevokedByInstanceId(instanceId: string): Promise<PeerCredential | null>;
     /**
-     * Revoke `instanceId`'s unrevoked, self-issued row whose hash is
-     * `credentialHash`, recording who retired it. Every condition sits in the
-     * WHERE clause, so a row that changed meanwhile is left alone.
-     * Returns whether a row was retired.
+     * Revoke `instanceId`'s unrevoked self-issued row with `credentialHash`,
+     * recording who retired it. Every condition is in the WHERE clause, so a row
+     * that changed meanwhile is left alone. Returns whether a row was retired.
      */
     retireSelfIssued(opts: {
         instanceId: string;
         credentialHash: string;
         retiredByInstance: string;
     }): Promise<boolean>;
-    /**
-     * Update the last_seen_at timestamp for a credential.
-     * Optionally records which coordinator validated it.
-     */
+    /** Bump last_seen_at; optionally record the validating coordinator. */
     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.
-     */
+    /** @returns The number of credentials revoked. */
     revokeAll(): Promise<number>;
-    /**
-     * List all active (non-revoked, non-expired) credentials.
-     */
+    /** Non-revoked, non-expired credentials, oldest first. */
     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
- */
+/** Write the credential file 0600, creating its parent directory 0700 if missing. */
 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
- */
+/** @returns The parsed credential file, or null if it does not 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 tests of the store's own CRUD methods — production
- * code constructs the store with an already-allocated Kysely instance
- * shared with the orchestrator.
+ * A store bound to a Postgres URL plus a pool disposer, so tests exercise the real
+ * store without importing pg/kysely. Test-only: production passes the
+ * orchestrator's shared Kysely instance.
  */
 export declare function createPeerCredentialStoreFromUrl(databaseUrl: string, opts?: {
     maxConnections?: number;

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

@@ -18,48 +18,27 @@
  *   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). */
+    /** Never sent on the 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
+ * Derive a 32-byte AES-256 session key: X25519 Diffie-Hellman, then HKDF-SHA256
+ * with the nonce as salt for per-session uniqueness.
  */
 export declare function deriveSessionKey(localPrivateKey: KeyObject, remotePubKeyDer: Buffer, nonce: Buffer): Buffer;
 /**
- * Encrypt a plaintext message with a session key using AES-256-GCM.
+ * AES-256-GCM with a 32-byte session key.
  *
- * @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.
+ * Decrypt the output of 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;

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

@@ -4,7 +4,6 @@ import type { PeerRegistry } from './peer-registry.js';
 import { PeerRequestWaiters } from './peer-request-waiters.js';
 /** What forgetting did on one coordinator. */
 export interface PeerForgetResult {
-    /** The coordinator that answered. */
     coordinator: string;
     outcome: PeerForgetOutcome;
     detail: string;
@@ -92,8 +91,9 @@ export declare function backstopConsequence(instanceId: string): string;
  * Drop `instanceId` from `registry` when it names a peer that left the
  * cluster. Kept, with the reason: a connected peer (its next heartbeat would
  * register it again), a peer heard from inside its liveness window (it may be
- * partitioned rather than gone; see `peerLivenessWindow`), and a peer whose removal would switch the
- * event-provision backstop back on, unless the request acknowledged that.
+ * partitioned rather than gone; see `peerLivenessWindow`), and a peer whose
+ * removal would switch the event-provision backstop back on, unless the request
+ * acknowledged that.
  */
 export declare function forgetDepartedPeer(registry: PeerRegistry, selfInstanceId: string, instanceId: string, guards: PeerForgetGuards): Omit<PeerForgetResult, 'coordinator'>;
 /** Answers a forget request a sibling coordinator fanned out. */