@kici-dev/orchestrator 0.17.0 → 0.18.0

package/dist/providers/generic/index.d.ts

@@ -11,8 +11,6 @@ import type { GenericSourceManager } from '../../webhook/generic-sources.js';
 export { GenericWebhookNormalizer } from './normalizer.js';
 export { verifyGenericWebhook, type VerificationMethod, type VerificationConfig, type HmacVerificationConfig, type BearerVerificationConfig, type IpAllowlistVerificationConfig, type NoneVerificationConfig, } from './verification.js';
 /**
- * Create a ProviderBundle for generic webhook sources.
- *
  * Only provides a normalizer -- no git-related methods.
  * The pipeline processor handles missing capabilities gracefully.
  *

package/dist/providers/generic/normalizer.d.ts

@@ -75,7 +75,6 @@ export declare class GenericWebhookNormalizer implements WebhookNormalizer {
      * 5. Returns normalized WebhookData
      *
      * @param routingKey - The routing key for this source (from URL path)
-     * @param rawBody - Raw request body string
      * @param headers - Request headers (lowercase keys)
      * @returns Normalized data or null if source not found/disabled
      */

package/dist/providers/generic/verification.d.ts

@@ -7,39 +7,31 @@
  * - IP allowlist (exact match)
  * - None (no verification, always passes)
  */
-/** Supported verification methods */
 export type VerificationMethod = 'hmac_sha256' | 'bearer_token' | 'ip_allowlist' | 'none';
-/** HMAC-SHA256 verification config */
 export interface HmacVerificationConfig {
     method: 'hmac_sha256';
     secret: string;
     /** Header containing the signature (default: x-signature-256) */
     headerName?: string;
 }
-/** Bearer token verification config */
 export interface BearerVerificationConfig {
     method: 'bearer_token';
     token: string;
     /** Header containing the token (default: authorization) */
     headerName?: string;
 }
-/** IP allowlist verification config */
 export interface IpAllowlistVerificationConfig {
     method: 'ip_allowlist';
     allowlist: string[];
 }
-/** No verification config */
 export interface NoneVerificationConfig {
     method: 'none';
 }
-/** Discriminated union of all verification configs */
 export type VerificationConfig = HmacVerificationConfig | BearerVerificationConfig | IpAllowlistVerificationConfig | NoneVerificationConfig;
 /**
  * Verify a generic webhook request.
  *
- * @param body - Raw request body as string
  * @param headers - Request headers (lowercase keys)
- * @param config - Verification configuration for this source
  * @param clientIp - Client IP address (required for ip_allowlist method)
  * @returns true if verification passes
  */

package/dist/providers/github/auth.d.ts

@@ -55,7 +55,6 @@ export declare class GitHubCloneTokenProvider implements CloneTokenProvider {
     private readonly config;
     readonly provider: 'github';
     constructor(config: GitHubAppConfig);
-    /** Get the GitHub App config for this provider instance. */
     getAppConfig(): GitHubAppConfig;
     /**
      * Create a short-lived installation access token for cloning a repo.

package/dist/providers/github/changed-files.d.ts

@@ -49,7 +49,8 @@ export declare class GitHubChangedFilesFetcher implements ChangedFilesFetcher {
      * @param eventType - GitHub event type ("pull_request" or "push")
      * @param payload - Raw GitHub webhook payload
      * @param credentials - Must be GitHubCredentials with installationId
-     * @returns Array of changed file paths
+     * @returns The changed file paths, with status 'fetched', or 'unavailable' when the
+     *   full set cannot be determined
      */
     getChangedFiles(repoIdentifier: string, eventType: string, payload: unknown, credentials: unknown): Promise<ChangedFilesResult>;
     /**

package/dist/providers/github/file-contents.d.ts

@@ -9,8 +9,6 @@
 import type { FileContentsFetcher } from '@kici-dev/engine';
 import { type GitHubAppConfig } from './auth.js';
 /**
- * GitHub-specific implementation of FileContentsFetcher.
- *
  * The installation id is baked in at construction because the
  * FileContentsFetcher interface is credential-less at call time -- a fetcher
  * instance is scoped to one GitHub App installation.
@@ -21,8 +19,6 @@ export declare class GitHubFileContentsFetcher implements FileContentsFetcher {
     readonly provider: 'github';
     constructor(config: GitHubAppConfig, installationId: number);
     /**
-     * Fetch a file's contents from a GitHub repository at a specific ref.
-     *
      * @param owner - Repository owner (e.g. "my-org")
      * @param repo - Repository name (e.g. "my-app")
      * @param path - Repo-relative file path (e.g. ".kici/workflows/ci.ts")

package/dist/providers/github/lock-file.d.ts

@@ -10,8 +10,6 @@
 import { type LockFileFetcher, type LockFile } from '@kici-dev/engine';
 import { type GitHubAppConfig } from './auth.js';
 /**
- * GitHub-specific implementation of LockFileFetcher.
- *
  * Fetches .kici/kici.lock.json from a GitHub repository using the Contents API.
  * Does NOT include caching -- the orchestrator wraps this fetcher with an LRU cache.
  */
@@ -20,8 +18,6 @@ export declare class GitHubLockFileFetcher implements LockFileFetcher {
     readonly provider: 'github';
     constructor(config: GitHubAppConfig);
     /**
-     * Fetch the lock file from a GitHub repository at a specific ref.
-     *
      * @param repoIdentifier - "owner/repo" format
      * @param ref - Git ref (branch, tag, SHA)
      * @param credentials - Must be GitHubCredentials with installationId

package/dist/providers/github/normalizer.d.ts

@@ -6,16 +6,12 @@
  */
 import type { WebhookNormalizer, SimulatedEvent } from '@kici-dev/engine';
 /**
- * GitHub-specific implementation of WebhookNormalizer.
- *
  * Maps GitHub webhook headers and payloads to KiCI's universal format.
  * Headers are expected lowercase (Hono normalizes them).
  */
 export declare class GitHubWebhookNormalizer implements WebhookNormalizer {
     readonly provider: 'github';
     /**
-     * Extract routing key from GitHub webhook headers.
-     *
      * Uses the X-GitHub-Hook-Installation-Target-ID header which identifies
      * the GitHub App receiving the webhook.
      *
@@ -44,7 +40,7 @@ export declare class GitHubWebhookNormalizer implements WebhookNormalizer {
     /**
      * Normalize a GitHub webhook event into a SimulatedEvent.
      *
-     * Handles all 15 supported GitHub event types:
+     * Handles all 14 supported GitHub event types:
      * - pull_request, push, issue_comment, pull_request_review,
      *   pull_request_review_comment, repository_dispatch, release,
      *   create, delete, status, workflow_run, fork, star, watch
@@ -54,8 +50,6 @@ export declare class GitHubWebhookNormalizer implements WebhookNormalizer {
      */
     normalizeEvent(eventType: string, action: string | null, payload: unknown): SimulatedEvent | null;
     /**
-     * Extract repository identifier from a GitHub webhook payload.
-     *
      * Prefers repository.full_name, falls back to owner.login/name.
      */
     extractRepoIdentifier(payload: unknown): string | null;
@@ -67,8 +61,6 @@ export declare class GitHubWebhookNormalizer implements WebhookNormalizer {
      */
     extractRef(eventType: string, payload: unknown): string;
     /**
-     * Extract GitHub-specific credentials from a webhook payload.
-     *
      * Extracts installationId from payload.installation.id, needed for
      * generating installation tokens for repo access.
      */

package/dist/providers/local/index.d.ts

@@ -19,12 +19,11 @@ export { LocalRepoUrlBuilder } from './repo-url-builder.js';
  * Create a ProviderBundle for a local filesystem (`file://`) source.
  *
  * Provides normalizer, lock file fetcher, and repo URL builder.
- * Clone token provider and changed files fetcher are null since
+ * Clone token provider and changed files fetcher are left undefined since
  * file:// URLs need no auth and local events don't track changed files.
  *
  * @param opts.repoBasePath - Base directory where the repo(s) live on disk
  * @param opts.cloneUrlBase - Optional URL base for clone operations (e.g. git://host/path)
- * @returns Complete ProviderBundle for the local provider
  */
 export declare function createLocalProviderBundle(opts: {
     repoBasePath: string;

package/dist/providers/local/lock-file-fetcher.d.ts

@@ -7,8 +7,6 @@
  */
 import type { LockFileFetcher, LockFile } from '@kici-dev/engine';
 /**
- * Local provider implementation of LockFileFetcher.
- *
  * Reads kici.lock.json from the local filesystem at the path derived from
  * the repoIdentifier (which is expected to be a file:// URL or a local path).
  */
@@ -30,8 +28,6 @@ export declare class LocalLockFileFetcher implements LockFileFetcher {
      */
     constructor(repoBasePath: string);
     /**
-     * Fetch the lock file from the local filesystem.
-     *
      * @param repoIdentifier - Either a file:// URL or a relative path under repoBasePath
      * @param ref - Git ref (ignored for filesystem access -- always reads current state)
      * @param _credentials - Not used (file:// access needs no auth)

package/dist/providers/local/normalizer.d.ts

@@ -9,8 +9,6 @@
  */
 import type { WebhookNormalizer, SimulatedEvent } from '@kici-dev/engine';
 /**
- * Local provider implementation of WebhookNormalizer.
- *
  * Maps the synthetic webhook headers and payloads sent to a local source into
  * KiCI's universal SimulatedEvent format. Payloads use the same GitHub-shaped
  * structure the trigger CLI / post-receive hook build
@@ -19,8 +17,6 @@ import type { WebhookNormalizer, SimulatedEvent } from '@kici-dev/engine';
 export declare class LocalWebhookNormalizer implements WebhookNormalizer {
     readonly provider: 'local';
     /**
-     * Extract routing key from the local-source webhook headers.
-     *
      * Checks x-kici-routing-key first (explicit routing), then falls back
      * to x-kici-source-id (generic source ID format).
      */
@@ -44,15 +40,11 @@ export declare class LocalWebhookNormalizer implements WebhookNormalizer {
      */
     verifySignature(_body: string, _headers: Record<string, string>, _secret: string): boolean;
     /**
-     * Extract repository identifier from a local-source webhook payload.
-     *
      * Local-source events use GitHub-shaped payloads, so we extract from
      * payload.repository.full_name if present.
      */
     extractRepoIdentifier(payload: unknown): string | null;
     /**
-     * Extract ref from a local-source webhook payload.
-     *
      * Local-source events use GitHub-shaped payloads, so extraction logic
      * mirrors GitHub's: push -> payload.after, PR -> payload.pull_request.head.sha.
      */
@@ -62,8 +54,6 @@ export declare class LocalWebhookNormalizer implements WebhookNormalizer {
      */
     extractCredentials(_payload: unknown): Record<string, unknown>;
     /**
-     * Normalize a local-source webhook event into a SimulatedEvent.
-     *
      * Extracts branch information from payload.ref (stripping refs/heads/ prefix)
      * and preserves the raw payload for trigger matching. Falls back to '__local__'
      * when no ref is present.

package/dist/providers/local/repo-url-builder.d.ts

@@ -24,8 +24,6 @@ export declare class LocalRepoUrlBuilder implements RepoUrlBuilder {
      */
     constructor(repoBasePath: string, cloneUrlBase?: string | undefined);
     /**
-     * Build a clone URL for a repo.
-     *
      * If cloneUrlBase is set, uses it directly (for remote agents).
      * If repoIdentifier already starts with 'file://', returns it as-is.
      * Otherwise, prepends 'file://' and the repoBasePath.

package/dist/providers/universal-git/clone-token.d.ts

@@ -32,8 +32,6 @@ export interface UniversalGitAuth extends ProviderGitAuth {
     kind: 'basic' | 'ssh';
 }
 /**
- * Universal-git implementation of CloneTokenProvider.
- *
  * Bound to a single source (orgId + sourceId + config). The orchestrator
  * constructs one per registered universal-git source.
  */

package/dist/providers/universal-git/lock-file.d.ts

@@ -43,8 +43,6 @@ export declare class LockFileTooLargeError extends Error {
     constructor(repoIdentifier: string, sizeBytes: number, limitBytes?: number);
 }
 /**
- * Universal-git implementation of LockFileFetcher.
- *
  * Bound to a single source (orgId + sourceId + config). The orchestrator
  * constructs one per registered universal-git source.
  */

package/dist/providers/universal-git/normalizer.d.ts

@@ -15,8 +15,6 @@
 import type { WebhookNormalizer, SimulatedEvent } from '@kici-dev/engine';
 import { type UniversalGitConfig } from './config.js';
 /**
- * Webhook normalizer for universal-git sources.
- *
  * Each instance is bound to one source's expanded config (preset-resolved
  * `payloadPaths` + `eventMapping`). The orchestrator constructs one per
  * registered `generic_webhook_sources` row with a non-null `git_config`.

package/dist/queue/bootstrap.d.ts

@@ -1,15 +1,7 @@
 /**
- * Orchestrator scheduled-jobs bootstrap helper.
- *
  * Composes `registerOrchestratorScheduledJob()` calls for all the
- * orchestrator's periodic work. Returns an array of handles so the
- * caller (orchestrator-core.ts) can thread them into
- * `setupGracefulShutdown`.
- *
- * Commit 5 ships the infrastructure; Commit 6 migrates the three
- * legacy setInterval schedulers (queue cleanup, secret cleanup,
- * token cleanup) into this helper. Commit 7 adds the
- * `cold-store-archive` entry.
+ * orchestrator's periodic work. The returned handles let orchestrator-core.ts
+ * thread them into `setupGracefulShutdown`.
  */
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
@@ -19,11 +11,7 @@ export interface OrchestratorScheduledJobsDeps {
     instanceId: string;
     routingKey?: string;
 }
-/**
- * Overrides for the per-job handler + cadence. Callers pass the
- * actual tick functions here — the bootstrap helper only composes
- * registrations.
- */
+/** The per-job tick functions and cadences; this helper only composes registrations. */
 export interface OrchestratorScheduledJobRegistrations {
     cleanup?: {
         intervalMs: number;

package/dist/queue/cleanup.d.ts

@@ -17,15 +17,11 @@ export interface CleanupExtras {
     db: Kysely<Database>;
     executionTracker: ExecutionTracker;
     /**
-     * Resolves each expired job's check run to a terminal conclusion.
-     *
-     * Required for correctness, not decoration: this sweep settles a job by
-     * writing `execution_jobs` directly rather than through
-     * `ExecutionTracker.onJobStatus`, so the tracker's terminal-job hook — the
-     * funnel a tracker-driven terminal status reaches the check-run reporter
-     * through — never fires here. Absent, the check run created at trigger match
-     * stays `queued` on the commit forever, which no branch-protection rule
-     * requiring it can ever be satisfied by.
+     * Resolves each expired job's check run to a terminal conclusion. Required for
+     * correctness: this sweep writes `execution_jobs` directly, not through
+     * `ExecutionTracker.onJobStatus`, so the tracker's terminal-job hook to the
+     * check-run reporter never fires. Absent, the check run stays `queued` on the
+     * commit forever, and no branch-protection rule requiring it is ever satisfied.
      */
     checkRunReporter?: Pick<CheckRunReporter, 'updateJobStatus'>;
     /** Terminal dispatch_queue row retention (days); 0 disables. Default 30. */
@@ -34,15 +30,11 @@ export interface CleanupExtras {
     stepLogTtlDays?: number;
     /** Store for `check_run_tracking`; the retention sweep runs only when wired. */
     checkRunTrackingStore?: CheckRunTrackingStore;
-    /**
-     * Database-side retention windows, in days. Absent leaves the history sweep
-     * off entirely, which is what a caller that has not wired it gets.
-     */
+    /** Database-side retention windows, in days. Absent leaves the history sweep off. */
     retentionWindows?: RetentionWindows;
     /**
-     * True when the cold store is configured. Its archivers then own the tables
-     * they register and the history sweep leaves those alone — one owner per
-     * table.
+     * True when the cold store is configured: its archivers own the tables they
+     * register and the history sweep leaves those alone — one owner per table.
      */
     coldStoreEnabled?: boolean;
     /** Live cluster-settings reader; absent ⇒ the config default is used as-is. */
@@ -56,27 +48,23 @@ export interface CleanupExtras {
     logStorageIsS3?: boolean;
     /**
      * Whether ANYTHING could ever have run a job with these selectors — a
-     * registered agent (regardless of capacity) or a scaler backend able to spawn
-     * one.
+     * registered agent (regardless of capacity) or a scaler backend able to spawn one.
      *
-     * Read once per expired job to split the two reasons a queued job never ran:
-     * nothing in the fleet matched its `runsOn` (`unroutable` — a label/fleet
-     * problem an operator has to fix) versus something matched but never produced
-     * a usable agent (`timed_out_stale` — a capacity or provisioning problem).
-     * Both halves are load-bearing: a scaler-managed pool at zero has no
-     * registered agent yet still routes perfectly well, so asking only the agent
-     * registry would report every failed spawn as a bad `runsOn`.
+     * Splits why a queued job never ran: nothing matched its `runsOn`
+     * (`unroutable` — a label/fleet problem for the operator) versus something
+     * matched but never produced a usable agent (`timed_out_stale` — capacity or
+     * provisioning). Both halves are load-bearing: a scaler pool at zero has no
+     * registered agent yet routes fine, so asking only the agent registry would
+     * report every failed spawn as a bad `runsOn`.
      *
-     * Asked both on the unroutable probe's short tick (where a grace window
-     * absorbs a label satisfied moments later by an autoscaled agent) and again
-     * at expiry, which stays the backstop when fast-fail is disabled. Absent →
-     * every expiry stays `timed_out_stale`, the behaviour before the split
-     * existed.
+     * Asked on the unroutable probe's short tick (a grace window absorbs a label an
+     * autoscaled agent satisfies moments later) and again at expiry, the backstop
+     * when fast-fail is disabled. Absent → every expiry stays `timed_out_stale`.
      *
-     * The predicate is allowed to answer "routable" conservatively (the scaler
-     * half matches exact labels only, so a pattern-only `runsOn` reads routable on
-     * a scaler-configured orchestrator). That costs precision on the status, never
-     * safety: the job is terminal either way and the run fails either way.
+     * It may answer "routable" conservatively (the scaler half matches exact labels
+     * only, so a pattern-only `runsOn` reads routable on a scaler-configured
+     * orchestrator). That costs status precision, never safety: the job is terminal
+     * and the run fails either way.
      */
     canRouteLabels?: CanRouteLabels;
     /**
@@ -87,18 +75,12 @@ export interface CleanupExtras {
     pendingGlobalEvals?: TerminalizeDeps['pendingGlobalEvals'];
 }
 /**
- * Run a single cleanup pass: remove expired dedup_cache entries and
- * mark expired dispatch_queue entries.
+ * One cleanup pass: remove expired dedup_cache entries and mark expired
+ * dispatch_queue entries. With `extras`, expired jobs are also forwarded to the
+ * Platform as terminal status so its execution_jobs projection stays in sync.
  *
- * When `extras` is provided, expired jobs are also forwarded to Platform
- * as terminal status updates so the Platform execution_jobs projection
- * stays in sync.
- *
- * Event-log row + payload retention is not here: event_log rows are
- * archived to cold-store and then deleted
- * (see `packages/orchestrator/src/cold-store/tables/event-log.ts`).
- *
- * @returns Counts of cleaned entries.
+ * Event-log retention is not here: event_log rows are archived to cold-store and
+ * then deleted (see `packages/orchestrator/src/cold-store/tables/event-log.ts`).
  */
 export declare function runCleanup(dedup: {
     cleanup(): Promise<number>;
@@ -111,11 +93,8 @@ export declare function runCleanup(dedup: {
     historyRowsPruned: number;
 }>;
 /**
- * Build a per-tick handler for the queue-cleanup scheduled job.
- *
- * The cadence (`intervalMs`) and the periodic wrapper itself live in
- * `packages/orchestrator/src/queue/scheduled-job.ts` — this factory
- * just produces the tick function. `runCleanup` is unchanged.
+ * Per-tick handler for the queue-cleanup scheduled job; the cadence and periodic
+ * wrapper live in `packages/orchestrator/src/queue/scheduled-job.ts`.
  */
 export declare function createCleanupHandler(dedup: {
     cleanup(): Promise<number>;

package/dist/queue/depth-refresher.d.ts

@@ -1,29 +1,20 @@
 /**
  * Periodic refresher for the dispatch-queue depth breakdown.
  *
- * Runs on a fixed interval (default 5s) — short enough that the
- * Prometheus observable-gauge callback (which reads the JobQueue's
- * synchronous cache) never serves data older than one refresh tick,
- * long enough that a single orchestrator does not hammer the DB.
+ * Each tick calls {@link JobQueue.getDepthBreakdown} to refresh the queue's
+ * cache and feeds {@link setDispatchQueueDepthBreakdown}, so
+ * `kici_orch_dispatch_queue_depth` / `..._by_label` are recent when Prometheus
+ * scrapes (the observable-gauge callback reads that synchronous cache). The
+ * default 5s interval keeps data within one tick without hammering the DB.
  *
- * Two responsibilities:
+ * It also watches for sustained backpressure: pending depth at or above
+ * {@link DepthRefresherOptions.thresholdGetter | threshold} for two consecutive
+ * ticks emits a `logger.warn` pointing at the per-label Grafana panel. The
+ * two-in-a-row guard suppresses transient spikes without a cooldown.
  *
- *   1. Call {@link JobQueue.getDepthBreakdown} to refresh the internal
- *      cache and feed {@link setDispatchQueueDepthBreakdown} so
- *      `kici_orch_dispatch_queue_depth` / `..._by_label` are always
- *      recent when Prometheus scrapes.
- *   2. Watch for sustained backpressure: when the pending depth stays
- *      at or above {@link RefresherOptions.thresholdGetter | threshold}
- *      for two consecutive refreshes, emit a `logger.warn` that points
- *      operators at the per-label Grafana panel. The two-in-a-row
- *      guard suppresses transient spikes without needing a cooldown.
- *
- * Threshold is resolved lazily on every tick via `thresholdGetter` so
- * live config reloads (SIGHUP / cluster propagation) take effect
- * immediately without restarting the refresher.
- *
- * A threshold of `0` disables the warning entirely — the refresher
- * still runs so metrics keep flowing.
+ * The threshold is read every tick so live config reloads (SIGHUP / cluster
+ * propagation) apply without a restart. `0` disables the warning; metrics keep
+ * flowing.
  */
 import type { Logger } from '@kici-dev/shared';
 import { type JobQueue } from './job-queue.js';
@@ -31,35 +22,26 @@ export interface DepthRefresherOptions {
     queue: JobQueue;
     logger: Logger;
     /**
-     * How often to refresh the cache / evaluate the warning threshold.
-     * Defaults to 5 seconds — short enough that Prometheus's default 15s
-     * scrape interval never sees data older than one tick.
+     * Default 5 seconds, so Prometheus's default 15s scrape interval never sees
+     * data older than one tick.
      */
     intervalMs?: number;
-    /**
-     * Called on every tick to get the current backpressure warn
-     * threshold. `0` disables warnings.
-     */
+    /** Read every tick: the backpressure warn threshold. `0` disables warnings. */
     thresholdGetter: () => number;
-    /**
-     * Optional hook invoked after each successful tick, for tests.
-     */
+    /** Test hook, invoked after each successful tick. */
     onTick?: (pendingDepth: number) => void;
 }
 export interface DepthRefresher {
-    /** Start the periodic timer. Idempotent. */
+    /** Idempotent. */
     start(): void;
-    /** Stop the periodic timer. Idempotent. */
+    /** Idempotent. */
     stop(): void;
-    /** Run one refresh synchronously (used at startup and in tests). */
+    /** Runs one refresh (used at startup and in tests). */
     refreshNow(): Promise<void>;
 }
 /**
- * Create a dispatch-queue depth refresher.
- *
- * The returned object is NOT started automatically — call `start()`
- * after the orchestrator is otherwise ready. `stop()` must be called
- * during shutdown to avoid leaking the interval handle.
+ * NOT started automatically: call `start()` once the orchestrator is otherwise
+ * ready, and `stop()` during shutdown to avoid leaking the interval handle.
  */
 export declare function createDepthRefresher(options: DepthRefresherOptions): DepthRefresher;
 //# sourceMappingURL=depth-refresher.d.ts.map