@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/diagnostics/types.d.ts

@@ -1,48 +1,37 @@
-/**
- * Diagnostic health check types.
- *
- * Defines the shape of diagnostic results and check functions
- * used by the diagnostic runner and CLI/HTTP interfaces.
- */
+/** Diagnostic result and check shapes, shared by the runner and the CLI/HTTP interfaces. */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { AgentRegistry } from '../agent/registry.js';
 import type { ScalerManager } from '../scaler/manager.js';
 import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
-/** Result of a single diagnostic check. */
 export interface DiagnosticResult {
     /** Human-readable check name (e.g., "Database connectivity"). */
     name: string;
-    /** Check outcome: pass, warn, or fail. */
     status: 'pass' | 'warn' | 'fail';
     /** Short description of the result. */
     message: string;
-    /** Optional structured details for debugging. */
+    /** Structured details for debugging. */
     details?: Record<string, unknown>;
-    /** How long the check took to run in milliseconds. */
     durationMs: number;
 }
-/** Dependencies available to diagnostic checks. */
 export interface DiagnosticDeps {
-    /** DB connection (optional -- standalone mode may not have DB). */
+    /** Standalone mode may not have a DB. */
     db?: Kysely<Database>;
-    /** Platform WS URL (for connectivity check). */
+    /** Platform WS URL (for the connectivity check). */
     platformUrl?: string;
-    /** Agent registry for checking connected agents. */
     agentRegistry?: AgentRegistry;
-    /** Orchestrator config (for config validity check). */
+    /** Orchestrator config (for the config validity check). */
     config: Record<string, unknown>;
-    /** TLS cert path (for expiry check). */
+    /** TLS cert path (for the expiry check). */
     tlsCertPath?: string;
-    /** Scaler manager for recent spawn-failure health (optional -- no scaler configured). */
+    /** For recent spawn-failure health; absent when no scaler is configured. */
     scalerManager?: ScalerManager;
     /**
-     * Fleet-wide settings reader. When present, a check reads the live
-     * `cluster_settings` value rather than only the configured default — so
-     * `kici-admin diagnose` reports what the cluster is actually doing.
+     * When present, a check reads the live `cluster_settings` value rather than only the
+     * configured default — so `kici-admin diagnose` reports what the cluster actually does.
      */
     clusterSettings?: ClusterSettingsReader;
 }
-/** A diagnostic check function. May return one result or several (e.g. one per scaler backend). */
+/** May return one result or several (e.g. one per scaler backend). */
 export type DiagnosticCheck = (deps: DiagnosticDeps) => Promise<DiagnosticResult | DiagnosticResult[]>;
 //# sourceMappingURL=types.d.ts.map

package/dist/drain/drain-controller.d.ts

@@ -3,29 +3,25 @@
  *
  * While draining, the Dispatcher routes every new job to the Pending queue
  * (Model A / job-level drain), the peer heartbeat advertises `draining: true`
- * (siblings stop rerouting here), and the scaler stops spawning fresh agents.
- * Jobs already executing on agents finish; `jobsRunning()` drops monotonically
- * to zero, at which point the coordinator is quiesced and safe to restart.
+ * (siblings stop rerouting here), and the scaler stops spawning agents.
+ * Executing jobs finish; once `jobsRunning()` drops monotonically to zero the
+ * coordinator is safe to restart.
  *
- * State is in-memory only: an upgrade restart comes back accepting and the
- * existing startup recovery re-dispatches the Pending backlog.
+ * State is in-memory only: an upgrade restart comes back accepting and startup
+ * recovery re-dispatches the Pending backlog.
  */
 export interface DrainControllerDeps {
-    /** Sum of activeJobs across all connected agents (agentRegistry). */
+    /** Sum of activeJobs across connected agents. */
     activeJobsTotal: () => number;
     /**
-     * Count of dispatch_queue rows in Dispatched status. In the single-coordinator
-     * drain-before-upgrade scenario this equals this instance's in-flight jobs; a
-     * per-instance ownership column does not exist on dispatch_queue, so a
-     * multi-coordinator cluster may over-count here (belt-and-suspenders only —
-     * `activeJobsTotal` is the primary signal, and both shrink monotonically once
-     * the dispatcher gate stops new claims).
+     * Count of Dispatched dispatch_queue rows: this instance's in-flight jobs on a
+     * single coordinator. dispatch_queue has no per-instance ownership column, so
+     * a multi-coordinator cluster may over-count; this is belt-and-suspenders
+     * behind `activeJobsTotal`, and both shrink monotonically once the dispatcher
+     * gate stops new claims.
      */
     dispatchedJobsOwned: () => Promise<number>;
-    /**
-     * Optional hook fired whenever the draining flag changes, used to drive the
-     * `kici_orchestrator_draining` metric. Not fired on a no-op (idempotent) call.
-     */
+    /** Fired when the draining flag changes (drives `kici_orchestrator_draining`), not on a no-op. */
     onChange?: (draining: boolean) => void;
 }
 export declare class DrainController {
@@ -36,12 +32,10 @@ export declare class DrainController {
     startDrain(): void;
     stopDrain(): void;
     /**
-     * Live quiesce signal: jobs currently executing on agents versus any row this
-     * instance already claimed (Dispatched) but whose activeJobs increment has not
-     * yet landed. Since draining stops new claims, this set only shrinks, so a
-     * poll on it is guaranteed to converge to zero. Uses `Math.max` (not sum) — the
-     * Dispatched rows are the durable view of the same jobs the in-memory
-     * activeJobs counts, so summing would double-count the common case.
+     * Live quiesce signal covering executing jobs and claimed (Dispatched) rows
+     * whose activeJobs increment has not landed yet. Draining stops new claims,
+     * so a poll converges to zero. `Math.max`, not a sum: both views count the
+     * same jobs, so summing double-counts the common case.
      */
     jobsRunning(): Promise<number>;
     snapshot(): Promise<{

package/dist/entry-helpers.d.ts

@@ -2,7 +2,6 @@
  * Shared helpers for orchestrator entry points (server.ts and standalone.ts).
  *
  * Extracted to eliminate code duplication between the two entry points.
- * Both entry points import these helpers instead of maintaining separate copies.
  */
 import { type SourceProvider, SourceSubtype } from '@kici-dev/engine';
 /**
@@ -75,7 +74,6 @@ export declare function genericProviderTypeToSubtype(providerType: string, optio
 export declare function extractRepoIdentifier(repoUrl: string): string;
 /**
  * Diff two provider source arrays by routingKey.
- * Returns which sources were added and which were removed.
  *
  * Used during config reload to determine which source.register and
  * source.deregister messages to send.

package/dist/events/circuit-breaker.d.ts

@@ -13,9 +13,6 @@ export declare class EventCircuitBreaker {
     private readonly clusterSettings?;
     private rateLimiter;
     constructor(config: EventRouterConfig, clusterSettings?: ClusterSettingsReader | undefined);
-    /**
-     * Check if the current chain depth is within limits.
-     */
     checkChainDepth(currentDepth: number): {
         allowed: boolean;
         reason?: string;

package/dist/events/event-router.d.ts

@@ -102,8 +102,7 @@ export interface EventRouterOptions {
 /**
  * EventRouter delivers internal events to matching workflows via PostgreSQL LISTEN/NOTIFY.
  *
- * Follows the WebhookSecretManager pattern: raw pg.PoolClient for LISTEN,
- * Kysely for queries.
+ * Uses a raw pg.PoolClient for LISTEN and Kysely for queries.
  *
  * On start, performs a catch-up scan for events missed during downtime.
  * On notification, leases the event from DB, matches against registered

package/dist/events/event-store.d.ts

@@ -61,9 +61,6 @@ export declare class EventStore {
      * insert with other transactional work (e.g. cron `tryClaimFire`).
      */
     writeWith(event: NewEventInput, executor: DbExecutor): Promise<string>;
-    /**
-     * Retrieve a single event by ID.
-     */
     getById(id: string): Promise<StoredEvent | null>;
     /**
      * Get a page of unprocessed events for catch-up on start.
@@ -187,13 +184,7 @@ export declare class EventStore {
      * Start periodic cleanup using setInterval.
      */
     startCleanupTimer(): void;
-    /**
-     * Stop periodic cleanup.
-     */
     stopCleanupTimer(): void;
-    /**
-     * Convert a DB row to a StoredEvent.
-     */
     private rowToStoredEvent;
 }
 //# sourceMappingURL=event-store.d.ts.map

package/dist/events/trust-store.d.ts

@@ -53,9 +53,6 @@ export declare class TrustStore {
      * scope check.
      */
     getById(id: string): Promise<TrustEntry | null>;
-    /**
-     * Remove a trust relationship by ID.
-     */
     removeTrust(id: string): Promise<void>;
     /**
      * List all trust relationships for a routing key (as source or target).

package/dist/events/types.d.ts

@@ -2,9 +2,6 @@
  * Event routing configuration and types.
  */
 import { z } from 'zod';
-/**
- * Configuration for the event routing system.
- */
 export interface EventRouterConfig {
     /** Maximum allowed chain depth before circuit breaker trips (default: 10) */
     maxChainDepth: number;
@@ -42,9 +39,6 @@ export interface EventRouterConfig {
      */
     debugFailFirstNAttemptsByEvent?: Record<string, number>;
 }
-/**
- * Reason an event landed in the DLQ.
- */
 export type DlqReason = 'exhausted_retries' | 'non_retryable';
 /** How the router resolved one event against the registered workflows. */
 export declare const EventMatchOutcome: z.ZodEnum<{
@@ -116,8 +110,5 @@ export type EventProcessingState = z.infer<typeof EventProcessingState>;
  * dispatch scheduled another attempt, and pending before its first lease.
  */
 export declare function eventProcessingState(e: StoredEvent): EventProcessingState;
-/**
- * Default event router configuration.
- */
 export declare const DEFAULT_EVENT_ROUTER_CONFIG: EventRouterConfig;
 //# sourceMappingURL=types.d.ts.map

package/dist/firecracker/host-network.d.ts

@@ -1,16 +1,13 @@
 /**
- * Firecracker host-network provisioning.
+ * Firecracker host-network provisioning: the per-coordinator bridge (kici-brN)
+ * and its gateway IP, NetworkManager-unmanaged kici-* interfaces, IP forwarding,
+ * and a disjoint, source-scoped nftables table for NAT and egress isolation.
+ * One pure command builder drives live provisioning, the rendered boot script
+ * and read-only verification.
  *
- * Creates the per-coordinator bridge (kici-brN), assigns its gateway IP,
- * marks kici-* interfaces unmanaged by NetworkManager, enables IP forwarding,
- * and builds a disjoint, source-scoped nftables table for NAT + egress
- * isolation. One pure command-builder drives live provisioning, the rendered
- * boot script, and (read-only) verification.
- *
- * This is HOST setup, distinct from the runtime per-VM isolation the rule
- * builder in `@kici-dev/shared/net` performs (added at spawn / removed at
- * destroy). The two share the nft table name but have separate lifecycles;
- * this module never touches the per-VM rules.
+ * HOST setup only. The per-VM isolation rules from `@kici-dev/shared/net`
+ * (added at spawn, removed at destroy) share the nft table name but have their
+ * own lifecycle, and this module never touches them.
  */
 import { FIRECRACKER_NET_INTERFACES } from './net-interfaces.js';
 export { FIRECRACKER_NET_INTERFACES };
@@ -93,27 +90,24 @@ export interface BridgeHealth {
  * Delete every rule in the table's `forward` chain that no live VM owns.
  *
  * A per-VM rule matches one host address or one exact TAP name; everything else
- * in that chain belongs to this provisioner — the tail `jump baseline`, and on
- * a host provisioned by an older boot script, the six baseline rules that used
- * to sit directly in `forward`. Removing only those makes re-provisioning
- * idempotent and upgrades an old-shaped host in place, without the `delete
- * table` that used to strip every running VM's isolation.
+ * in that chain is this provisioner's: the tail `jump baseline` and, on a host
+ * an older boot script provisioned, the six baseline rules that sat directly in
+ * `forward`. Removing only those makes re-provisioning idempotent and upgrades
+ * an old-shaped host in place, without a `delete table` that strips every
+ * running VM's isolation.
  *
- * One exception, and it is not this provisioner's: on a host that also runs a
- * container-mode agent, the agent installs ONE drop set for its whole
- * {@link JOB_NETWORK_SUBNET} rather than one per job container, so that a
- * customer image's `ENTRYPOINT` cannot run ahead of its own rules. nft reports
- * a subnet source as a prefix object, which is exactly what makes
- * `listForwardRules` report no per-agent identifier — so those rules read as
- * this provisioner's and would be reaped, leaving every job container already
- * running at that moment with no egress filtering until the next job repairs
- * it. They are spared by name.
+ * One exception is not this provisioner's: a container-mode agent on the same
+ * host installs ONE drop set for its whole {@link JOB_NETWORK_SUBNET}, not one
+ * per job container, so a customer image's `ENTRYPOINT` cannot run ahead of its
+ * rules. nft reports a subnet source as a prefix object, so `listForwardRules`
+ * reports no per-agent identifier and those rules read as this provisioner's.
+ * Reaping them would leave every running job container without egress
+ * filtering until the next job repairs it, so they are spared by name.
  *
- * Best-effort: a chain that cannot be read yields no rules, so a fresh host
- * sweeps nothing and provisioning proceeds. A chain whose TEXT cannot be read
- * sweeps nothing either — the spared set is unknown at that point, and deleting
- * an unclassified rule from a chain carrying a security control is the wrong
- * direction to guess in.
+ * Best-effort: an unreadable chain yields no rules, so a fresh host sweeps
+ * nothing and provisioning proceeds. A chain whose TEXT cannot be read sweeps
+ * nothing either: the spared set is unknown, and deleting an unclassified rule
+ * from a chain carrying a security control is the wrong direction to guess in.
  */
 export declare function sweepUnownedForwardRules(cfg: FirecrackerBridgeConfig, opts?: ExecOptions): Promise<number>;
 /** Provision (or heal) one Firecracker host bridge. Throws on any failure. */

package/dist/firecracker/net-interfaces.d.ts

@@ -2,13 +2,10 @@
  * Interface patterns the Firecracker host setup marks unmanaged in
  * NetworkManager.
  *
- * A leaf module on purpose: it imports nothing, so an out-of-package consumer
- * can read the constant without pulling the orchestrator runtime graph in with
- * it. A NetworkManager drift watchdog derives its
- * expected-pattern set from here rather than re-typing the patterns — a second
- * copy desyncs silently the moment a pattern is added. `host-network.ts`
- * re-exports it and renders `NM_CONF_CONTENT` from it, so the drop-in and the
- * watchdog can never disagree.
+ * A leaf module on purpose: an out-of-package consumer (a NetworkManager drift
+ * watchdog) reads the constant without the orchestrator runtime graph, rather
+ * than re-typing a copy that desyncs silently. `host-network.ts` renders
+ * `NM_CONF_CONTENT` from it, so the drop-in and the watchdog never disagree.
  */
 export declare const FIRECRACKER_NET_INTERFACES: readonly ['kici-*'];
 //# sourceMappingURL=net-interfaces.d.ts.map

package/dist/helpers/rate-limiter.d.ts

@@ -19,7 +19,6 @@ export declare class SlidingWindowRateLimiter {
     constructor(maxPerWindow: number, windowMs?: number);
     /**
      * Check if a new event is allowed for the given key.
-     * @param key - The rate limit bucket key.
      * @param maxOverride - Per-call limit override (uses constructor default if omitted).
      */
     check(key: string, maxOverride?: number): {