@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/concurrency/dispatch-next-queued.d.ts

@@ -1,15 +1,11 @@
 /**
- * Slot-release dispatch helpers for the long-poll concurrency protocol.
+ * Slot-release dispatch for the long-poll concurrency protocol. When a group
+ * slot frees (run completed, cancelled or superseded), the FIFO-oldest queued
+ * row's agent, parked on its second `waitForConcurrencyAck` call, is woken and
+ * continues on the WS it got the original dispatch on.
  *
- * When a concurrency-group slot frees (run completed, run cancelled, run
- * superseded), the orchestrator picks the FIFO-oldest queued row and wakes up
- * the agent that's parked on its second `waitForConcurrencyAck` call. The
- * agent then continues with normal step execution against the same WS
- * connection it received the original dispatch on.
- *
- * If the in-memory waiter is missing (orchestrator restart, agent already
- * disconnected), the dequeued DB row is marked completed so the slot doesn't
- * get permanently stuck on a phantom holder.
+ * A missing in-memory waiter (orchestrator restart, agent disconnected) marks
+ * the dequeued row completed so the slot is not stuck on a phantom holder.
  */
 import type { AgentRegistry } from '../agent/registry.js';
 import type { ConcurrencyQueueManager } from './queue-manager.js';
@@ -17,23 +13,16 @@ import type { ConcurrencyWaiters } from './waiters.js';
 export interface DispatchNextQueuedDeps {
     /** The DB arbiter. */
     queueManager: ConcurrencyQueueManager;
-    /** Agent registry for finding the waiter's WS. */
     registry: AgentRegistry;
-    /** In-memory waiter map. */
     waiters: ConcurrencyWaiters;
 }
 /**
  * Try to dequeue the next queued entry for `(group, routingKey)` and notify
- * the waiting agent's WS with `concurrency.ack { action: 'proceed' }`.
- *
- * No-op if the queue is empty. When a dequeued waiter is missing or its
- * agent is gone (orphaned row, agent disconnected), the helper LOOPS to the
- * next queued row instead of stopping — otherwise a single orphan would
- * permanently mask all live waiters behind it (orphans sort first by
- * `created_at ASC`).
+ * the waiting agent's WS with `job.concurrency.ack { action: 'proceed' }`.
  *
- * Bounded by a defensive iteration cap so we never accidentally infinite-loop
- * on a queue manager that returns the same row repeatedly.
+ * No-op on an empty queue. A missing waiter or gone agent LOOPS to the next
+ * row; stopping would let one orphan (they sort first by `created_at ASC`)
+ * permanently mask every live waiter behind it.
  */
 export declare function tryDispatchNextQueued(deps: DispatchNextQueuedDeps, group: string, routingKey: string): Promise<void>;
 export interface AgentDisconnectDeps {
@@ -41,11 +30,10 @@ export interface AgentDisconnectDeps {
     queueManager: ConcurrencyQueueManager;
 }
 /**
- * Build the agent-disconnect cleanup callback. Drops every waiter owned by
- * the disconnecting agent and marks their `concurrency_groups` rows as
- * cancelled so the queue manager doesn't try to dispatch a phantom run.
+ * Agent-disconnect cleanup: drop the agent's waiters and cancel their
+ * `concurrency_groups` rows so the queue manager never dispatches a phantom run.
  *
- * Returns a no-arg-async closure suitable for passing to the agent WS handler.
+ * Returns an async `(agentId)` closure suitable for passing to the agent WS handler.
  */
 export declare function buildOnConcurrencyAgentDisconnect(deps: AgentDisconnectDeps): (agentId: string) => Promise<void>;
 //# sourceMappingURL=dispatch-next-queued.d.ts.map

package/dist/concurrency/queue-manager.d.ts

@@ -1,13 +1,11 @@
 /**
  * The arbiter of `concurrency: { group, max }`.
  *
- * Every decision is a transaction against `concurrency_groups`, which is what
- * makes `max` mean the same thing across a restart and across every coordinator
- * in a cluster. A process-local map cannot: a restart came back with an empty
- * map and let a second run deploy alongside the one already deploying, and two
- * coordinators each held their own map so `max: 1` was never cluster-wide.
- * `concurrency: { group, max: 1 }` is the guard customers use to serialise
- * deploys and migrations, so "usually right" is not a useful guarantee.
+ * Every decision is a transaction against `concurrency_groups`, so `max` holds
+ * across a restart and across every coordinator in a cluster. A process-local
+ * map cannot: a restart empties it and lets a second run deploy alongside the
+ * first, and each coordinator would hold its own map. Customers use
+ * `max: 1` to serialise deploys and migrations, so "usually right" is not enough.
  */
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
@@ -37,22 +35,16 @@ export declare class ConcurrencyQueueManager {
     private readonly db;
     constructor(db: Kysely<Database>);
     /**
-     * Serialise every arbitration for one (routingKey, groupKey) scope.
-     *
-     * A transaction-scoped advisory lock, so it is released on commit or
-     * rollback with no cleanup path to get wrong. Counting active rows and
-     * inserting one are two statements, and without the lock two coordinators
-     * both read `count < max` and both insert — which is exactly the
-     * double-deploy the cap exists to prevent.
+     * Serialise every arbitration for one (routingKey, groupKey) scope. A
+     * transaction-scoped advisory lock, released on commit or rollback with no
+     * cleanup path. Without it two coordinators both read `count < max` and both
+     * insert — the double-deploy the cap exists to prevent.
      */
     private static lockScope;
     /**
-     * Try to take a slot in a concurrency group.
-     *
-     * Idempotent: a run that already holds an active slot re-acquires it without
-     * consuming a second one, which the partial unique index on
-     * `(routing_key, group_key, run_id) WHERE status = 'active'` also enforces at
-     * the DB level.
+     * Idempotent: a run already holding an active slot re-acquires it without
+     * consuming a second, also enforced by the partial unique index on
+     * `(routing_key, group_key, run_id) WHERE status = 'active'`.
      *
      * @returns whether this run holds a slot afterwards.
      */
@@ -62,51 +54,27 @@ export declare class ConcurrencyQueueManager {
     /** Release this run's slot in a group. No-op when it holds none. */
     releaseSlot(groupKey: string, routingKey: string, runId: string): Promise<void>;
     /**
-     * The runs holding an active slot, oldest first.
-     *
-     * A run whose `execution_runs` row is already terminal is excluded and its
-     * slot is released in the same transaction. A slot outlives its run whenever
-     * the release path did not run — a coordinator crash between "the run
-     * finished" and "the slot was released" — and a leaked slot on a `max: 1`
-     * deploy gate blocks every later deploy forever.
+     * The runs holding an active slot, oldest first. A run whose `execution_runs`
+     * row is terminal is excluded and its slot released in the same transaction:
+     * a coordinator crash between run finish and slot release leaks the slot, and
+     * on a `max: 1` deploy gate that blocks every later deploy forever.
      */
     getActiveRuns(groupKey: string, routingKey: string): Promise<string[]>;
     /** The oldest active run, which `cancelInProgress` supersedes. */
     getOldestRun(groupKey: string, routingKey: string): Promise<string | null>;
-    /**
-     * Active run ids for a scope, reconciled against `execution_runs`. Must be
-     * called with the scope lock already held.
-     */
+    /** Active run ids reconciled against `execution_runs`. Caller holds the scope lock. */
     private static activeRunIds;
-    /**
-     * Enqueue a job that is waiting for a concurrency slot.
-     * Inserts a row with status='queued' into concurrency_groups.
-     */
     enqueue(opts: EnqueueOptions): Promise<void>;
-    /**
-     * Dequeue the oldest queued job for a concurrency group.
-     * Returns null if no queued jobs exist.
-     */
+    /** Promote the oldest queued job of a group to active; null when none is queued. */
     dequeueNext(groupKey: string, routingKey: string): Promise<QueuedJob | null>;
-    /**
-     * Promote the oldest queued waiter to `active`. Must be called with the scope
-     * lock already held.
-     */
+    /** Promote the oldest queued waiter to `active`. Caller holds the scope lock. */
     private static promoteOldestQueued;
-    /**
-     * Cancel all queued entries for a run.
-     * Marks them as 'cancelled' with a completion timestamp.
-     */
     cancelQueued(runId: string): Promise<void>;
-    /**
-     * Mark a concurrency group entry as completed.
-     * Called when a job finishes (success/failed/cancelled).
-     */
+    /** Called when a job finishes (success/failed/cancelled). */
     markCompleted(runId: string, groupKey: string, routingKey: string): Promise<void>;
     /**
-     * Handle job completion: mark completed and return next queued job if any.
-     * This is the main coordination point: when a slot opens, the next
-     * queued job should be dispatched.
+     * Release the run's slot and return the promoted next queued job, if any —
+     * the caller dispatches it.
      */
     onJobComplete(groupKey: string, routingKey: string, runId: string): Promise<QueuedJob | null>;
 }

package/dist/concurrency/waiters.d.ts

@@ -1,55 +1,39 @@
 /**
  * In-memory waiter registry for the long-poll concurrency protocol.
  *
- * When the orchestrator acks a `concurrency.report` with `{ action: 'wait' }`,
+ * When the orchestrator acks a `job.concurrency.report` with `{ action: 'wait' }`,
  * the agent stays connected on the same WS waiting for an unsolicited follow-up
- * `concurrency.ack`. This module tracks which agent is parked on which queued
- * run so that, when a slot frees, we can find the right WS to wake up.
+ * `job.concurrency.ack`; this tracks which agent is parked on which queued run.
  *
- * The store is keyed on `(groupKey, routingKey)` tuples and preserves FIFO
- * order within each scope (the same ordering invariant the queue manager uses
- * in `concurrency_groups.created_at`).
+ * Keyed on `(groupKey, routingKey)`, FIFO within each scope (the queue
+ * manager's `concurrency_groups.created_at` ordering).
  *
- * State is in-memory only — orchestrator restarts drop all WS connections
- * anyway, so a queued waiter that survived a restart would have no agent to
- * notify. The slot-release helper handles the missing-waiter case by marking
- * the just-dequeued entry completed (effectively cancelling it).
+ * In-memory only: a restart drops every WS anyway. The slot-release helper
+ * marks a dequeued entry with no waiter completed (effectively cancelled).
  */
 export interface WaiterEntry {
     /** The run id queued behind a held slot. */
     runId: string;
-    /** The job id the agent is parked on. */
     jobId: string;
-    /** The agent id holding the WS connection. */
+    /** The agent holding the WS connection. */
     agentId: string;
 }
 export declare class ConcurrencyWaiters {
-    /** Scoped state: `${routingKey}\0${groupKey}` -> ordered FIFO of waiters. */
+    /** `${routingKey}\0${groupKey}` -> FIFO of waiters. */
     private readonly waiters;
     private scopeKey;
-    /**
-     * Register a waiter for the given (group, routingKey). FIFO order is
-     * preserved across multiple registrations.
-     */
     register(groupKey: string, routingKey: string, entry: WaiterEntry): void;
     /**
-     * Pop the FIFO-first waiter whose runId matches the given runId. Returns
-     * undefined if no waiter for that runId is registered (e.g. after an
-     * orchestrator restart, or because the WS already disconnected and called
-     * dropForAgent).
-     *
-     * Matches by runId (not "shift the head") because the queue-manager's
-     * `dequeueNext()` may pick a specific row; the in-memory tracker has to
-     * follow the DB's verdict, not the in-memory FIFO head independently.
+     * Pop the first waiter for `runId`; undefined when none (orchestrator
+     * restart, or the WS already disconnected and called dropForAgent). Matches
+     * by runId, not the FIFO head, because `dequeueNext()` picks the row and the
+     * in-memory tracker must follow the DB's verdict.
      */
     popByRunId(groupKey: string, routingKey: string, runId: string): WaiterEntry | undefined;
     /**
-     * Drop all waiters owned by the given agent. Returns the dropped entries so
-     * the caller can `cancelQueued(runId)` the matching DB rows and emit failure
-     * events.
-     *
-     * Called from the agent-handler `onClose` so a disconnect doesn't leave a
-     * queued row dangling forever.
+     * Drop the agent's waiters, returning them so the caller can
+     * `cancelQueued(runId)` and emit failure events. Called from the
+     * agent-handler `onClose` so a disconnect never leaves a queued row dangling.
      */
     dropForAgent(agentId: string): WaiterEntry[];
     /** Number of registered waiters. Test-only. */

package/dist/config/encryption.d.ts

@@ -4,7 +4,6 @@ export declare const REDACTED_VALUE = "***REDACTED***";
  * Get a value at a nested path in an object.
  * Returns undefined if the path doesn't exist.
  *
- * @param obj - The object to traverse
  * @param path - Dot-separated path (e.g., 'providers.github.appId')
  */
 export declare function deepGet(obj: Record<string, unknown>, path: string): unknown;
@@ -25,7 +24,6 @@ export declare function deepSet(obj: Record<string, unknown>, path: string, valu
  * providers.github is an array of 2 items resolves to:
  * ['providers.github.0.privateKey', 'providers.github.1.privateKey']
  *
- * @param obj - The object to inspect
  * @param pattern - Dot-separated path with optional '*' wildcards
  * @returns Array of concrete dot-separated paths that exist in the object
  */

package/dist/config/loader.d.ts

@@ -19,7 +19,6 @@ export declare const SENSITIVE_FIELD_PATHS: readonly ['platform.token', 'secrets
  * Load and validate the local orchestrator YAML configuration.
  *
  * @param configPath - Explicit path to the config file (highest precedence)
- * @returns Validated LocalConfig
  * @throws Error if explicit path doesn't exist, or if validation fails
  */
 export declare function loadLocalConfig(configPath?: string): Promise<LocalConfig>;

package/dist/config/reload.d.ts

@@ -15,13 +15,7 @@ import type { Logger } from '@kici-dev/shared';
 import type { AppConfig, SharedConfig } from './types.js';
 import type { SharedConfigStore } from './shared-store.js';
 import type { ScalerFileReloadResult } from '../scaler/file-reload.js';
-/**
- * Source of a reload trigger.
- */
 export type ReloadSource = 'sighup' | 'http' | 'cluster' | 'cli';
-/**
- * Result of a reload operation.
- */
 export interface ReloadResult {
     success: boolean;
     version?: number;

package/dist/config/resolver.d.ts

@@ -17,13 +17,9 @@ import type { AppConfig, SharedConfig } from './types.js';
 export interface LocalPhaseResult {
     /** The raw local config (from YAML + env overlay) */
     local: Record<string, unknown>;
-    /** Resolved database URL */
     databaseUrl: string;
-    /** Resolved instance ID */
     instanceId: string;
-    /** Resolved server port */
     port: number;
-    /** Resolved instance mode */
     mode: OrchestratorMode;
 }
 /**

package/dist/config/shared-store.d.ts

@@ -75,7 +75,6 @@ export declare class SharedConfigStore {
      * Validates with sharedConfigSchema, encrypts sensitive fields,
      * and stores as a new immutable version.
      *
-     * @param config - The config object to save
      * @param createdBy - Who created this version (e.g., "cli:seed", "api:set")
      * @param description - Human-readable change description
      * @returns The new version number
@@ -92,7 +91,6 @@ export declare class SharedConfigStore {
      * Rollback to a specific version.
      * Reads the target version and creates a new version as a copy.
      *
-     * @param targetVersion - Version number to rollback to
      * @param createdBy - Who initiated the rollback
      * @returns The new version number
      * @throws Error if target version doesn't exist

package/dist/config/types.d.ts

@@ -109,7 +109,6 @@ export interface SharedConfig {
 export interface AppConfig {
     /** Unique identifier for this orchestrator instance */
     instanceId: string;
-    /** Operating mode */
     mode: OrchestratorMode;
     /** PostgreSQL connection URL */
     databaseUrl: string;
@@ -213,9 +212,7 @@ export interface AppConfig {
     /** Inbound webhook delivery log: soft cap (bytes). Oversized deliveries are
      *  recorded with payload_omitted=true rather than 413'd. */
     eventLogMaxPayloadBytes: number;
-    /** Log level */
     logLevel: 'debug' | 'info' | 'warn' | 'error';
-    /** Node environment */
     nodeEnv: 'development' | 'production' | 'test';
 }
 /**

package/dist/content-requirements-cache.d.ts

@@ -37,7 +37,6 @@ export declare class ContentRequirementsCache {
      * caching. Each distinct `(provider, repo, sha, path)` is fetched at most
      * once; concurrent misses coalesce onto one fetch.
      *
-     * @param fetcher - Provider-specific file-contents fetcher.
      * @param repo    - Provider repo identifier ("owner/repo").
      * @param sha     - Git ref (commit SHA, or a branch/tag name).
      * @param path    - Repo-relative file path.

package/dist/contexts/context-store.d.ts

@@ -77,8 +77,6 @@ export declare class ContextStore {
     /** Update a context. Returns the updated row, or null if not found. */
     update(orgId: string, id: string, updates: ContextUpdateInput): Promise<Context | null>;
     /**
-     * Delete a context.
-     *
      * Bindings, variables, and source overrides cascade away via their FK.
      * Terminal held-run history survives with a null `context_id` (the FK
      * uses ON DELETE SET NULL). Pending held runs still reference the

package/dist/contexts/held-runs.d.ts

@@ -46,7 +46,6 @@ export declare const SecurityHoldReason: z.ZodEnum<{
     workflow_modification: "workflow_modification";
 }>;
 export type SecurityHoldReason = z.infer<typeof SecurityHoldReason>;
-/** Data required to create a held run. */
 export interface CreateHeldRunData {
     runId: string;
     jobId: string;
@@ -134,7 +133,6 @@ export interface ReleaseSignal {
      */
     triggerSource: TriggerSource;
 }
-/** Options for listing held runs. */
 export interface ListHeldRunsOptions {
     status?: string;
     limit?: number;

package/dist/contexts/variable-store.d.ts

@@ -16,7 +16,6 @@ export declare class VariableStore {
     listVars(orgId: string, contextId: string): Promise<ContextVariable[]>;
     /** Upsert an org-level variable. */
     setVar(orgId: string, contextId: string, key: string, value: string, locked?: boolean): Promise<void>;
-    /** Delete an org-level variable. */
     deleteVar(orgId: string, contextId: string, key: string): Promise<void>;
     /** List source overrides for a specific source (routing key). */
     listSourceOverrides(orgId: string, contextId: string, routingKey: string): Promise<ContextSourceOverride[]>;
@@ -24,7 +23,6 @@ export declare class VariableStore {
     listAllSourceOverrides(orgId: string, contextId: string): Promise<ContextSourceOverride[]>;
     /** Upsert a source override. */
     setSourceOverride(orgId: string, contextId: string, routingKey: string, key: string, value: string): Promise<void>;
-    /** Delete a source override. */
     deleteSourceOverride(orgId: string, contextId: string, routingKey: string, key: string): Promise<void>;
     /**
      * Get resolved variables for a context, optionally merged with source overrides.

package/dist/dashboard/attestation-filters.d.ts

@@ -2,14 +2,13 @@ import { type Kysely } from 'kysely';
 import type { AttestationListFilters } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
 /**
- * The org-wide attestations base query: joins `attestations` to `execution_jobs`
- * (for the job name) and `execution_runs` (for repository / workflow context).
+ * The org-wide attestations base query, joined to `execution_jobs` (job name) and
+ * `execution_runs` (repository / workflow).
  *
- * `attestations.run_id` / `job_id` are TEXT while the
- * `execution_*` keys are `uuid`; Postgres won't compare `uuid = text` implicitly,
- * so the join casts the uuid side to text — mirroring `resolveAttestationsForRun`.
- * The `execution_runs` join is a LEFT join so a row with no matching run still
- * lists (repository / workflow come back null).
+ * `attestations.run_id` / `job_id` are TEXT while the `execution_*` keys are `uuid`,
+ * and Postgres won't compare `uuid = text` implicitly, so the joins cast the uuid side
+ * to text, mirroring `resolveAttestationsForRun`. The `execution_runs` join is LEFT so
+ * a row with no matching run still lists (repository / workflow come back null).
  */
 export declare function baseAttestationsQuery(db: Kysely<Database>): import("kysely").SelectQueryBuilder<{
     access_log: import("../db/types.js").AccessLogTable;
@@ -77,15 +76,12 @@ export declare function baseAttestationsQuery(db: Kysely<Database>): import("kys
 }, "attestations" | "execution_jobs" | "execution_runs", {}>;
 export type AttestationsBaseQuery = ReturnType<typeof baseAttestationsQuery>;
 /**
- * Base query for the deferred-attestation outbox (`pending_attestations`),
- * joined to `execution_jobs` (job name) and `execution_runs` (repo / workflow
- * context) for the org-wide list's pending summaries.
+ * Base query for the deferred-attestation outbox (`pending_attestations`), joined like
+ * `baseAttestationsQuery` for the org-wide list's pending summaries.
  *
- * Same uuid/text mismatch as `baseAttestationsQuery`: `pending_attestations`
- * `run_id` / `job_id` are TEXT while the `execution_*` keys are `uuid`, and
- * Postgres won't compare `uuid = text` implicitly — so the joins cast the uuid
- * side to text. Both joins are LEFT joins so a pending row with no matching
- * run / job still lists (repository / workflow / job name come back null).
+ * The joins cast the uuid side to text for the same uuid/text mismatch. Both joins are
+ * LEFT so a pending row with no matching run / job still lists (repository / workflow /
+ * job name come back null).
  */
 export declare function basePendingAttestationsQuery(db: Kysely<Database>): import("kysely").SelectQueryBuilder<{
     access_log: import("../db/types.js").AccessLogTable;
@@ -152,9 +148,8 @@ export declare function basePendingAttestationsQuery(db: Kysely<Database>): impo
     workflow_registrations: import("../db/types.js").WorkflowRegistrationsTable;
 }, "execution_jobs" | "execution_runs" | "pending_attestations", {}>;
 /**
- * Apply org-wide attestation filters to the base query. Digest is exact-match;
- * name is an ILIKE substring; status / repository / workflow / job are equality;
- * created_at gets `>=` / `<=` bounds for the date range. Absent filters are
+ * Digest is exact-match; name is an ILIKE substring; status / repository / workflow /
+ * job are equality; created_at gets inclusive `>=` / `<=` bounds. Absent filters are
  * skipped.
  */
 export declare function applyAttestationFilters(qb: AttestationsBaseQuery, filters: AttestationListFilters): AttestationsBaseQuery;