@kici-dev/orchestrator 0.1.17 → 0.1.18

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

@@ -1,5 +1,5 @@
 import { type Kysely } from 'kysely';
-import type { ResourceRequest } from '@kici-dev/engine';
+import { type LabelMatcher, type ResourceRequest } from '@kici-dev/engine';
 import type { Database } from '../db/types.js';
 /** Info about an expired dispatch_queue entry, returned by markExpired(). */
 export interface ExpiredJobInfo {
@@ -92,12 +92,26 @@ export interface QueuedJobInput {
     requestId?: string;
     /** Labels that the dispatched agent must NOT have. */
     excludeLabels?: string[];
+    /** Regex matchers the agent's labels must satisfy (JS post-filter on the exact @> prefilter). */
+    runsOnPatterns?: LabelMatcher[];
+    /** Regex matchers that disqualify an agent (JS post-filter). */
+    excludePatterns?: LabelMatcher[];
     /**
      * Per-job resource request and limit (K8s-style). Drives scaler cap accounting
      * (`requests`) and kernel-side enforcement on the spawned agent (`limits`).
      * Stored inside `jobConfig` JSON; this typed field is a convenience for callers.
      */
     resources?: ResourceRequest;
+    /**
+     * For a runsOnAll host-fanout child: the agent this job is pinned to. The
+     * dispatcher routes it only to that agent; the drain never hands it to another.
+     */
+    pinnedAgentId?: string;
+    /**
+     * For a pinned child: which orchestrator instance owns the pinned agent's live
+     * WS (null = not currently connected). Used by the cross-cluster pin reroute.
+     */
+    connectedInstanceId?: string | null;
 }
 /**
  * Full queued job as stored in the database.
@@ -135,11 +149,17 @@ export interface QueuedJob {
     requestId?: string;
     /** Labels that the dispatched agent must NOT have. */
     excludeLabels: string[];
+    /** Regex matchers the agent's labels must satisfy (JS post-filter on the exact @> prefilter). */
+    runsOnPatterns: LabelMatcher[];
+    /** Regex matchers that disqualify an agent (JS post-filter). */
+    excludePatterns: LabelMatcher[];
     /**
      * Per-job resource request and limit (K8s-style). Materialized from `jobConfig.resources`
      * by `rowToQueuedJob` so callers can read it without re-parsing the JSON column.
      */
     resources?: ResourceRequest;
+    /** For a runsOnAll host-fanout child: the agent this job is pinned to. */
+    pinnedAgentId?: string;
 }
 /**
  * DB-backed FIFO job dispatch queue using Kysely (PostgreSQL only).
@@ -188,7 +208,46 @@ export declare class JobQueue {
      *   (empty for static / non-scaler agents).
      * @returns The matching job, or null if none found.
      */
-    dequeueForLabels(agentLabels: string[], agentMandatoryLabels?: string[]): Promise<QueuedJob | null>;
+    dequeueForLabels(agentLabels: string[], agentMandatoryLabels?: string[], agentId?: string): Promise<QueuedJob | null>;
+    /**
+     * Build the shared drain WHERE chain (status / expiry / exact-label @> /
+     * exclude-label / pin / mandatory-label gate) common to both drain passes.
+     * The pattern columns are NOT filtered here — each pass adds its own
+     * pattern-free / pattern-bearing guard on top.
+     */
+    private drainBaseQuery;
+    /**
+     * Fast path: claim the oldest pending pattern-free row. The
+     * `runs_on_patterns = '[]' AND exclude_patterns = '[]'` guard restricts this
+     * pass to rows that need no JS post-filter, so the single-row atomic claim
+     * (FOR UPDATE SKIP LOCKED) keeps the original hot-path semantics intact.
+     */
+    private claimPatternFree;
+    /**
+     * Pattern path: load a small batch of pattern-bearing candidate rows, apply
+     * the JS regex post-filter (matcherSatisfiedBy), and atomically claim the
+     * first match by id with a conditional `status = Pending` guard. The claim is
+     * a conditional UPDATE rather than relying on the SELECT lock alone because
+     * the JS filter runs after the per-statement lock window has closed, so two
+     * agents could both pass the filter for the same row; the `where status =
+     * Pending` makes exactly one of them win. The claim transitions the row to
+     * Dispatched, matching the value the caller-side markDispatched would set
+     * (which then re-sets it idempotently).
+     */
+    private claimWithPatterns;
+    /**
+     * Atomically claim the oldest pending job pinned to a specific agent. Used by
+     * the eager pin drain when the pinned agent (re)registers or frees a slot —
+     * the host-fanout analog of `dispatchBoundJob`'s eager path. Ignores the exact
+     * label gate: the pin was resolved against the roster at materialize time.
+     *
+     * Still applies the JS regex post-filter (`jobPatternsSatisfiedBy`) when
+     * `agentLabels` is supplied, mirroring `dequeueById`: a pinned child whose
+     * `runsOn`/`exclude` patterns no longer match the agent's current labels must
+     * not be claimed. The single matching authority is the engine's
+     * `matcherSatisfiedBy` (never a Postgres `~`).
+     */
+    dequeueByPinnedAgent(agentId: string, agentLabels?: string[]): Promise<QueuedJob | null>;
     /**
      * Atomically claim a specific pending job by ID, validating it still
      * matches the agent's labels and isn't expired.

package/dist/reporting/execution-tracker.d.ts

@@ -202,6 +202,12 @@ export declare class ExecutionTracker {
         jobName: string;
         matrixValues?: Record<string, unknown>;
         runsOnLabels?: string[];
+        baseJobName?: string;
+        variantKind?: string;
+        variantLabel?: string;
+        waveGated?: boolean;
+        waveMaxParallel?: number;
+        waveFailFast?: boolean;
     }>, routingKey?: string, 
     /** Secret context names dispatched with jobs (for context-disable job lookup). */
     dispatchedContexts?: string[], 
@@ -237,6 +243,13 @@ export declare class ExecutionTracker {
      * which peer owns the downstream dispatch.
      */
     findSyntheticJobId(runId: string, jobName: string): Promise<string | undefined>;
+    /**
+     * Find the synthetic deferred-eval placeholder job ID for a result-aware
+     * dynamic generator's eval job. Mirrors {@link findSyntheticJobId} but keys on
+     * the `dynamic-eval-pending-<evalJobName>-` prefix that registerDeferredEvalJob
+     * uses, so dispatchEvalJob can swap it for the real eval job id.
+     */
+    findDynamicEvalSyntheticId(runId: string, evalJobName: string): Promise<string | undefined>;
     /**
      * Run `fn` while holding a per-run lock, serializing the run-mutating methods
      * (`onJobStatus`, `addJobsToRun`) so a status reply cannot interleave with the
@@ -258,6 +271,9 @@ export declare class ExecutionTracker {
         jobName: string;
         matrixValues?: Record<string, unknown>;
         runsOnLabels?: string[];
+        baseJobName?: string;
+        variantKind?: string;
+        variantLabel?: string;
     }>, dispatchedContexts?: string[], 
     /** Synthetic job ID to replace (e.g. needs-pending-deploy-{uuid}). */
     replaceSyntheticId?: string): Promise<void>;
@@ -339,6 +355,18 @@ export declare class ExecutionTracker {
      * so recursive skip propagation terminates naturally.
      */
     private runSchedulerHook;
+    /**
+     * Rolling-wave hook: fires beside the needs-scheduler when a fan-out child of
+     * a bounded wave (`maxParallel` set) reaches terminal. Reads the completed
+     * child's row to recover the base + wave policy, asks {@link evaluateWave}
+     * what to do, then performs it:
+     *
+     * - `release`: clear the next held sibling's `wave_gated` flag and fire the
+     *   onJobReady callback (the existing ready→dispatch path).
+     * - `skip-remaining`: mark every still-held sibling `skipped` (failFast).
+     * - `noop`: nothing — a later terminal will free the next slot.
+     */
+    private runWaveSchedulerHook;
     /**
      * Phase 9: stuck-jobs invariant check ( Layer 3).
      * Before declaring a run complete, verify no stuck jobs exist. If any are