@kici-dev/orchestrator 0.17.0 → 0.19.0

package/dist/queue/scheduled-job.d.ts

@@ -1,26 +1,20 @@
 /**
- * Orchestrator scheduled-job wrapper.
+ * Orchestrator scheduled-job wrapper. Mirrors the Platform's wrapper in
+ * observable surface (the Prometheus metrics, structured logs, an audit row on
+ * failure) but uses `setInterval`: the orchestrator deliberately takes no
+ * pg-boss dependency.
  *
- * Mirrors the Platform's scheduled-job wrapper in observable
- * surface (5 Prometheus metrics + structured logs + audit row on
- * failure) but uses `setInterval` instead of pg-boss — the orchestrator
- * has no pg-boss dependency and we're not adding one.
+ * Every orchestrator periodic job MUST use this wrapper, as the cleanup jobs
+ * in queue/cleanup.ts and secrets/cleanup.ts do.
  *
- * Every orchestrator periodic job MUST use this wrapper, as the cleanup
- * jobs in queue/cleanup.ts and secrets/cleanup.ts do.
- *
- * `triggerNow()` on the returned handle forces one off-cadence tick
- * (used by the admin `/api/v1/admin/scheduled-jobs/:name/trigger`
- * endpoint and by tests). It does NOT reset the interval
- * timer — a real tick still fires at the scheduled cadence after.
+ * `triggerNow()` forces one off-cadence tick (for the admin
+ * `/api/v1/admin/scheduled-jobs/:name/trigger` endpoint and tests). It does
+ * NOT reset the interval timer.
  */
 import { z } from 'zod';
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
-/**
- * All registered orchestrator scheduled-job names. Adding a new
- * periodic job MUST add its name here before it can register.
- */
+/** Every orchestrator scheduled-job name; a new periodic job MUST be added here. */
 export declare const OrchestratorScheduledJobName: z.ZodEnum<{
     cleanup: "cleanup";
     "cold-store-archive": "cold-store-archive";
@@ -36,14 +30,11 @@ export interface OrchestratorScheduledJobOptions {
     name: OrchestratorScheduledJobName;
     /** Tick cadence. Must be > 0. */
     intervalMs: number;
-    /** Handler called per tick. Exceptions are caught and metered. */
+    /** Called per tick; exceptions are caught and metered. */
     handler: () => Promise<void>;
-    /**
-     * Orchestrator instance ID — appears on failure access-log rows as
-     * `actor_id` alongside `actor_type='system'`.
-     */
+    /** The `actor_id` (with `actor_type='system'`) on failure access-log rows. */
     instanceId: string;
-    /** DB used for failure audit rows. If omitted, failures are logs-only. */
+    /** For failure audit rows; without it, failures are logs-only. */
     db?: Kysely<Database>;
     /** Routing key for failure access-log partitioning (null = not scoped). */
     routingKey?: string;
@@ -56,35 +47,22 @@ export interface OrchestratorScheduledJobHandle {
     readonly name: OrchestratorScheduledJobName;
     /** Clears the interval. Safe to call multiple times. */
     stop(): void;
-    /**
-     * Force one off-cadence tick and await it (success or failure).
-     * Returns the tick's outcome so callers such as the admin route can report it.
-     */
+    /** Force one off-cadence tick and return its outcome, success or failure. */
     triggerNow(): Promise<{
         ok: boolean;
         durationMs: number;
         error?: string;
     }>;
 }
-/**
- * Readonly snapshot of per-job metric state. Used by the admin
- * `/api/v1/admin/scheduled-jobs` route to surface last-run info.
- */
+/** Per-job metric state, for the admin `/api/v1/admin/scheduled-jobs` route. */
 export declare function getOrchestratorJobMetricState(): ReadonlyMap<string, {
     consecutiveFailures: number;
     lastSuccessAt: Date | null;
     lastFailureAt: Date | null;
 }>;
-/**
- * Look up a registered scheduled job's handle by name. Returns
- * `undefined` if the job isn't registered on this instance. Used by
- * the admin trigger-now endpoint.
- */
+/** For the admin trigger-now endpoint; `undefined` when not registered here. */
 export declare function findOrchestratorScheduledJob(name: OrchestratorScheduledJobName): OrchestratorScheduledJobHandle | undefined;
-/**
- * Clear the scheduled-job registry. Intended for tests only —
- * production code should keep a stable set of registered jobs.
- */
+/** Tests only: production keeps a stable set of registered jobs. */
 export declare function __resetOrchestratorScheduledJobsForTesting(): void;
 export declare function registerOrchestratorScheduledJob(opts: OrchestratorScheduledJobOptions): OrchestratorScheduledJobHandle;
 //# sourceMappingURL=scheduled-job.d.ts.map

package/dist/queue/terminalize-unroutable.d.ts

@@ -8,19 +8,19 @@ import type { AgentRegistry } from '../agent/registry.js';
 import { type AgentFitJob, type ScalerAgentView } from '../scaler/agent-fit.js';
 import type { ExpiredJobInfo } from './job-queue.js';
 /**
- * Whether ANYTHING could ever run a job with these selectors — a registered
+ * Whether ANYTHING could ever run a job with these selectors: a registered
  * agent (regardless of capacity) that can run it, or a scaler backend able to
  * spawn one.
  *
- * `job`, when given, is what the agent must be able to do beyond its labels:
- * above all start the job's container (`canAgentRunJob`). Absent, any
- * label-matching agent counts.
+ * `job`, when given, is what the agent must do beyond its labels, above all
+ * start the job's container (`canAgentRunJob`). Absent, any label-matching
+ * agent counts.
  *
- * The predicate is allowed to answer "routable" conservatively: the scaler half
- * matches exact labels only, so a pattern-only `runsOn` reads routable on a
+ * 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 precision on the status and on
- * how quickly the job settles, never safety — a job that reads routable
- * falls through to the queue-timeout backstop.
+ * settle time, never safety — such a job falls through to the queue-timeout
+ * backstop.
  */
 export type CanRouteLabels = (requiredLabels: string[], requiredPatterns: LabelMatcher[], excludeLabels: string[], excludePatterns: LabelMatcher[], job?: AgentFitJob) => boolean;
 /**
@@ -47,11 +47,10 @@ export interface TerminalizeDeps {
      * the webhook request awaiting its verdict.
      *
      * A round job is the one queue entry with an in-process awaiter and no
-     * `execution_runs` row — the round decides whether any run exists at all —
-     * so the rest of this function skips it entirely and the awaiter would
-     * otherwise wait out its full ceiling for a job the queue has already
-     * declared dead. With the shipped defaults that is a 120s definitive
-     * fast-fail followed by a 240s wait, twice.
+     * `execution_runs` row (the round decides whether any run exists), so the
+     * rest of this function skips it and the awaiter would otherwise wait out
+     * its full ceiling for a dead job: with the shipped defaults, a 120s
+     * definitive fast-fail followed by a 240s wait, twice.
      */
     pendingGlobalEvals?: Pick<PendingGlobalEvalTracker, 'reject'>;
 }
@@ -78,14 +77,13 @@ export declare enum UnroutableCause {
 export declare function unroutableMessage(job: JobRoutingFacts, cause?: UnroutableCause): string;
 /**
  * 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)
+ * its `runsOn` (`unroutable` — a label/fleet problem an operator must fix)
  * versus something matched but never produced a usable agent
  * (`timed_out_stale` — a capacity or provisioning problem).
  *
- * Shared by the unroutable probe (which asks on a short tick, gated by a grace
- * window) and the queue-expiry sweep (which asks once at expiry, as the
- * backstop). One verdict, two moments in time — a second copy of this logic is
- * exactly the drift this module exists to prevent.
+ * Shared by the unroutable probe (short tick, gated by a grace window) and the
+ * queue-expiry sweep (once at expiry, as the backstop): one verdict, two
+ * moments, so never copy this logic.
  */
 export declare function classifyUnroutable(job: JobRoutingFacts, canRouteLabels?: CanRouteLabels): {
     status: ExecutionJobStatus;

package/dist/queue/unroutable-probe.d.ts

@@ -3,17 +3,15 @@ import type { Database } from '../db/types.js';
 import type { JobQueue, UnroutableCandidate } from './job-queue.js';
 import { type CanRouteLabels } from './terminalize-unroutable.js';
 /**
- * The shipped default grace, mirrored from `config.ts`. Used only to derive a
- * sane tick cadence when the env default is 0 (fast-fail disabled at startup
- * but re-enableable live via the `unroutable_grace_ms` cluster setting).
+ * The shipped default grace, mirrored from `config.ts`. Only derives a tick
+ * cadence when the env default is 0 (fast-fail disabled at startup but
+ * re-enableable live via the `unroutable_grace_ms` cluster setting).
  */
 export declare const DEFAULT_UNROUTABLE_GRACE_MS = 120000;
 /**
- * Probe cadence, derived from the grace rather than configured separately.
- *
- * The tick is an implementation detail of the grace window — it only has to be
- * fine-grained enough that the grace elapses on time — not independent policy,
- * so it deliberately does not earn its own cluster knob.
+ * Probe cadence, derived from the grace. The tick only has to be fine-grained
+ * enough that the grace elapses on time; it is not independent policy, so it
+ * deliberately has no cluster knob of its own.
  */
 export declare function probeTickIntervalMs(graceMs: number): number;
 /** Writes the operator-facing routing reason onto a still-queued job. */
@@ -30,23 +28,18 @@ export interface UnroutableProbeDeps {
     batchLimit?: number;
 }
 /**
- * Write the routing reason onto a job that is still waiting to be routed.
- *
- * The status guard matters: the reason is a statement about a job that has not
- * been picked up, so it must never annotate one that already started or
- * finished between the probe's read and this write.
+ * The status guard matters: the reason describes a job not yet picked up, so it
+ * must never annotate one that started or finished between the probe's read
+ * and this write.
  */
 export declare function makeRoutingReasonWriter(db: Kysely<Database>): SetRoutingReason;
 /**
- * Build the per-tick handler for the unroutable probe.
- *
- * The probe consults the SAME routability predicate the queue-expiry sweep uses
- * — one verdict, two moments in time — but asks on a short tick instead of once
- * an hour. On the first unroutable verdict it records the reason (so the cause
- * is visible while the job still waits) and starts a grace clock; only once the
- * job has been CONTINUOUSLY unroutable for the whole grace does it terminalize.
- * A job that reads routable again has both cleared, so a scaler reload or an
- * agent reconnect can never cost it its place in the queue.
+ * The per-tick handler. It uses the SAME routability predicate as the
+ * queue-expiry sweep, on a short tick instead of once an hour. The first
+ * unroutable verdict records the reason (visible while the job still waits) and
+ * starts a grace clock; only a job CONTINUOUSLY unroutable for the whole grace
+ * is terminalized. A job that reads routable again has both cleared, so a
+ * scaler reload or agent reconnect never costs it its place in the queue.
  */
 export declare function createUnroutableProbeHandler(deps: UnroutableProbeDeps): () => Promise<void>;
 //# sourceMappingURL=unroutable-probe.d.ts.map

package/dist/registration/extractor.d.ts

@@ -20,9 +20,6 @@ export declare function hasRepoPatterns(trigger: LockTrigger): boolean;
 /**
  * Extract workflows that have at least one trigger with repo patterns.
  * These are "global workflows" that match events across repositories.
- *
- * @param lockFile - The compiled lock file to extract from
- * @returns Workflows that have at least one trigger with repo patterns
  */
 export declare function extractGlobalWorkflows(lockFile: LockFile): LockWorkflow[];
 /**
@@ -34,9 +31,6 @@ export declare function extractGlobalWorkflows(lockFile: LockFile): LockWorkflow
  * generic webhook targets an externally-hosted repo. The
  * per-event lock file pipeline remains the primary matching path for
  * same-source git events; registration is an additive index.
- *
- * @param lockFile - The compiled lock file to extract from
- * @returns Workflows that have at least one registerable trigger or repo patterns
  */
 export declare function extractRegisterableWorkflows(lockFile: LockFile): LockWorkflow[];
 /** Exposed for testing */

package/dist/registration/registration-index.d.ts

@@ -93,9 +93,6 @@ export declare class RegistrationIndex {
      * Called when a peer heartbeat reports a higher registryVersion.
      */
     refreshIfNeeded(remoteVersion: number): Promise<void>;
-    /**
-     * Get the current in-memory version.
-     */
     getVersion(): number;
     /**
      * Look up a single registration by ID (includes disabled entries).
@@ -107,9 +104,6 @@ export declare class RegistrationIndex {
      * Used for event routing (e.g., find all workflows listening for 'kici_event').
      */
     getByTriggerType(triggerType: string): RegisteredWorkflow[];
-    /**
-     * Get all workflows registered for a specific routing key and repo.
-     */
     getByRoutingKeyAndRepo(routingKey: string, repoIdentifier: string): RegisteredWorkflow[];
     /**
      * Cross-source webhook lookup: return all webhook-trigger registrations

package/dist/registration/registration-store.d.ts

@@ -118,13 +118,7 @@ export declare class RegistrationStore {
      * Get all registrations (for index loading on startup).
      */
     getAll(): Promise<RegistrationRow[]>;
-    /**
-     * Get registrations for a specific routing key.
-     */
     getByRoutingKey(routingKey: string): Promise<RegistrationRow[]>;
-    /**
-     * Get registrations for a specific routing key + repo pair.
-     */
     getByRoutingKeyAndRepo(routingKey: string, repoIdentifier: string): Promise<RegistrationRow[]>;
     /**
      * Get a single registration by ID. Returns null if not found.
@@ -134,9 +128,6 @@ export declare class RegistrationStore {
      * Delete a single registration by ID. Returns true if deleted.
      */
     deleteById(id: string): Promise<boolean>;
-    /**
-     * Delete all registrations for a routing key + repo pair.
-     */
     deleteByRoutingKeyAndRepo(routingKey: string, repoIdentifier: string): Promise<void>;
     /**
      * Get the current registry version (for cluster sync).

package/dist/reporting/agent-failure-category.d.ts

@@ -1,9 +1,7 @@
 /**
- * Derive a coarse, trusted run-failure classification from existing signals.
- *
- * Pure derivation — no heuristics, no flaky/regression detection (that's a
- * deferred phase). KiCI computes this from data it already records, so the
- * resulting category is a trusted field on the agent run-result.
+ * A coarse run-failure classification, derived purely from data KiCI already records —
+ * no heuristics, no flaky/regression detection — so the category is a trusted field on
+ * the agent run-result.
  */
 import { AgentFailureCategory } from '@kici-dev/engine';
 export interface FailureSignals {