@kici-dev/orchestrator 0.1.16 → 0.1.18

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

@@ -0,0 +1,33 @@
+/**
+ * Local filesystem (`file://`) source provider implementations.
+ *
+ * Provides a complete provider bundle for cloning a git repository that is
+ * already present on the agent's filesystem, with no remote forge, no webhook
+ * signature verification, and no network clone. Uses file:// URLs for cloning
+ * and reads lock files directly from the filesystem.
+ *
+ * Classes:
+ * - LocalWebhookNormalizer -> WebhookNormalizer (extracts from custom headers)
+ * - LocalLockFileFetcher -> LockFileFetcher (reads from local filesystem)
+ * - LocalRepoUrlBuilder -> RepoUrlBuilder (returns file:// URLs)
+ */
+import type { ProviderBundle } from '../../provider-registry.js';
+export { LocalWebhookNormalizer } from './normalizer.js';
+export { LocalLockFileFetcher } from './lock-file-fetcher.js';
+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
+ * 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;
+    cloneUrlBase?: string;
+}): ProviderBundle;
+//# sourceMappingURL=index.d.ts.map

package/dist/providers/local/local-source-config.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Configuration for a local filesystem (`file://`) source, stored as JSONB in
+ * `generic_webhook_sources.git_config` and discriminated from universal-git
+ * config by the row's `provider_type='local'`.
+ *
+ * A local source clones a git repository that already exists on the agent's
+ * filesystem (host path for bare-metal scalers, image-bundled / rootfs /
+ * bind-mounted path for container + Firecracker scalers). The orchestrator does
+ * not verify in-agent reachability — that is the operator's responsibility.
+ */
+import { z } from 'zod';
+export declare const LocalSourceConfigSchema: z.ZodObject<{
+    repoBasePath: z.ZodString;
+    cloneUrlBase: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+export type LocalSourceConfig = z.infer<typeof LocalSourceConfigSchema>;
+//# sourceMappingURL=local-source-config.d.ts.map

package/dist/providers/{internal → local}/lock-file-fetcher.d.ts

@@ -1,22 +1,22 @@
 /**
- * Internal lock file fetcher for E2E tests.
+ * Local filesystem lock file fetcher.
  *
  * Implements the LockFileFetcher interface from @kici-dev/engine by reading
- * kici.lock.json directly from the local filesystem. Used when the internal
+ * kici.lock.json directly from the local filesystem. Used when the local
  * provider processes webhooks for repos accessible via file:// URLs.
  */
 import type { LockFileFetcher, LockFile } from '@kici-dev/engine';
 /**
- * Internal provider implementation of LockFileFetcher.
+ * 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).
  */
-export declare class InternalLockFileFetcher implements LockFileFetcher {
+export declare class LocalLockFileFetcher implements LockFileFetcher {
     private readonly repoBasePath;
-    readonly provider: "internal";
+    readonly provider: "local";
     /**
-     * @param repoBasePath - Base directory for test repos. When repoIdentifier
+     * @param repoBasePath - Base directory for the repo(s). When repoIdentifier
      *   starts with 'file://', it is stripped and used as-is. Otherwise
      *   repoBasePath is used as the root.
      */

package/dist/providers/{internal → local}/normalizer.d.ts

@@ -1,25 +1,25 @@
 /**
- * Internal webhook normalizer for E2E tests.
+ * Local filesystem source webhook normalizer.
  *
- * Implements the WebhookNormalizer interface from @kici-dev/engine for internal
- * webhook sources. Used by the provider-agnostic E2E test suite to trigger the
- * full webhook processing pipeline without GitHub dependencies.
- *
- * Verification is always skipped (internal sources use verification='none').
- * Event type and routing key are extracted from custom headers.
+ * Implements the WebhookNormalizer interface from @kici-dev/engine for local
+ * (`file://`) sources. Drives the full webhook processing pipeline without a
+ * remote forge: signature verification is skipped (local sources use
+ * verification='none'), and event type / routing key are extracted from custom
+ * headers.
  */
 import type { WebhookNormalizer, SimulatedEvent, AccessCacheInvalidation } from '@kici-dev/engine';
 /**
- * Internal provider implementation of WebhookNormalizer.
+ * Local provider implementation of WebhookNormalizer.
  *
- * Maps internal webhook headers and payloads to KiCI's universal SimulatedEvent format.
- * Designed for E2E tests where payloads use normalized provider-agnostic structures
+ * 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
  * (e.g., {ref: 'refs/heads/master', repository: {full_name: 'test/repo'}}).
  */
-export declare class InternalWebhookNormalizer implements WebhookNormalizer {
-    readonly provider: "internal";
+export declare class LocalWebhookNormalizer implements WebhookNormalizer {
+    readonly provider: "local";
     /**
-     * Extract routing key from internal webhook headers.
+     * 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).
@@ -38,42 +38,42 @@ export declare class InternalWebhookNormalizer implements WebhookNormalizer {
     /**
      * Verify signature -- always returns true.
      *
-     * Internal sources use verification='none'. Actual verification is not
-     * needed for E2E test infrastructure where both sender and receiver
-     * are controlled by the test harness.
+     * Local sources use verification='none' — there is no remote forge to sign
+     * the payload. The operator is responsible for only registering repos they
+     * trust (see docs/user/providers/local-file.md).
      */
     verifySignature(_body: string, _headers: Record<string, string>, _secret: string): boolean;
     /**
-     * Extract repository identifier from an internal webhook payload.
+     * Extract repository identifier from a local-source webhook payload.
      *
-     * Internal events mimic GitHub-shaped payloads in E2E tests,
-     * so we extract from payload.repository.full_name if present.
+     * 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 an internal webhook payload.
+     * Extract ref from a local-source webhook payload.
      *
-     * Internal events use GitHub-shaped payloads, so extraction logic
+     * Local-source events use GitHub-shaped payloads, so extraction logic
      * mirrors GitHub's: push -> payload.after, PR -> payload.pull_request.head.sha.
      */
     extractRef(eventType: string, payload: unknown): string;
     /**
-     * Extract credentials -- internal sources carry no provider credentials.
+     * Extract credentials -- local sources carry no provider credentials.
      */
     extractCredentials(_payload: unknown): Record<string, unknown>;
     /**
-     * Normalize an internal webhook event into a SimulatedEvent.
+     * 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 '__internal__'
+     * and preserves the raw payload for trigger matching. Falls back to '__local__'
      * when no ref is present.
      */
     normalizeEvent(eventType: string, _action: string | null, payload: unknown): SimulatedEvent | null;
     /**
-     * Map membership-related internal webhook events to ContributorCache
+     * Map membership-related local-source webhook events to ContributorCache
      * invalidations.
      *
-     * Internal E2E payloads are GitHub-shaped by design, so the mapping
+     * Local-source payloads are GitHub-shaped by design, so the mapping
      * mirrors the GitHub normalizer exactly:
      *
      * - `member`: repo-user
@@ -81,8 +81,8 @@ export declare class InternalWebhookNormalizer implements WebhookNormalizer {
      * - `membership`: user-in-org
      * - `team` (repo-scoped actions only): repo
      *
-     * This lets Bucket C E2E tests exercise the invalidation path through
-     * `sendInternalWebhook()` without requiring a real GitHub App.
+     * This lets membership-invalidation paths be exercised through
+     * `sendLocalWebhook()` without requiring a real GitHub App.
      */
     getAccessCacheInvalidations(eventType: string, _action: string | null, payload: unknown): AccessCacheInvalidation[];
 }

package/dist/providers/{internal → local}/repo-url-builder.d.ts

@@ -1,5 +1,5 @@
 /**
- * Internal repo URL builder for E2E tests.
+ * Local filesystem repo URL builder.
  *
  * Implements the RepoUrlBuilder interface from @kici-dev/engine by returning
  * file:// URLs for local filesystem access, or network URLs (git://, http://)
@@ -7,16 +7,16 @@
  */
 import type { RepoUrlBuilder } from '@kici-dev/engine';
 /**
- * Internal provider implementation of RepoUrlBuilder.
+ * Local provider implementation of RepoUrlBuilder.
  *
  * Builds clone URLs for repository access. When cloneUrlBase is set (e.g. to
  * a git:// daemon URL), uses it for clone URLs so remote agents on different
  * machines can clone. Otherwise falls back to file:// URLs for local access.
  */
-export declare class InternalRepoUrlBuilder implements RepoUrlBuilder {
+export declare class LocalRepoUrlBuilder implements RepoUrlBuilder {
     private readonly repoBasePath;
     private readonly cloneUrlBase?;
-    readonly provider: "internal";
+    readonly provider: "local";
     /**
      * @param repoBasePath - Base directory where test repos live on disk
      * @param cloneUrlBase - Optional URL base for clone operations (e.g. git://host/path).
@@ -34,8 +34,8 @@ export declare class InternalRepoUrlBuilder implements RepoUrlBuilder {
     /**
      * Build a raw file URL -- returns empty string.
      *
-     * Internal repos have no web UI, so raw file URLs are not applicable.
-     * The lock file is fetched via InternalLockFileFetcher (filesystem) instead.
+     * Local repos have no web UI, so raw file URLs are not applicable.
+     * The lock file is fetched via LocalLockFileFetcher (filesystem) instead.
      */
     buildRawFileUrl(_repoIdentifier: string, _ref: string, _path: string): string;
 }

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
@@ -395,6 +423,39 @@ export declare class ExecutionTracker {
         triggerEvent?: string;
         commitMessage?: string;
     }): Promise<void>;
+    /**
+     * Record a run paused at the workflow install gate (a `registries:` /
+     * `installEnv:` protection rule returned hold / wait / queue). Writes an
+     * `execution_runs` row in the `held` state — alive and resumable — so the
+     * dashboard run list surfaces the paused workflow. No jobs are tracked: the
+     * workflow-scoped held_runs row + pending workflow context (written by the
+     * caller) keep the run from being counted complete. Idempotent on runId.
+     */
+    recordRunHeld(args: {
+        runId: string;
+        workflowName: string;
+        provider: string;
+        repoIdentifier: string;
+        ref: string;
+        sha: string;
+        deliveryId: string | null;
+        providerContext: Record<string, unknown>;
+        routingKey: string;
+        environmentName?: string;
+        reason: string;
+        triggerEvent?: string;
+        commitMessage?: string;
+    }): Promise<void>;
+    /**
+     * Flip a `held` run back to `pending` so the resumed dispatch can proceed
+     * into job dispatch. Returns true when a held row was found and updated.
+     */
+    resumeHeldRun(runId: string): Promise<boolean>;
+    /**
+     * Cancel a held run (reviewer rejected the install gate). Flips the held row
+     * to `cancelled` and fires the status-change forward so Platform projects it.
+     */
+    cancelHeldRun(runId: string, reason: string): Promise<void>;
     /**
      * Mark a run as failed immediately with a reason message.
      *

package/dist/routes/admin-events.d.ts

@@ -26,15 +26,14 @@ interface AdminEventRouteDeps {
     rbac: RbacEnforcer;
     /**
      * The in-process bundle registry. The POST /generic-sources handler
-     * registers an internal / universal-git bundle into this registry
+     * registers a local / universal-git bundle into this registry
      * immediately after the source row lands in the DB, so the next
      * webhook against that source resolves the right normalizer without
      * waiting for an orchestrator restart.
      */
     providerRegistry: ProviderRegistry;
-    /** Needed by `registerProviderBundleForSource` to gate internal-bundle
-     *  registration on `canServeGenericProviderType` and read the
-     *  `internalProviderRepoPath` / `internalProviderCloneUrl` config. */
+    /** Passed through to `registerProviderBundleForSource` (universal-git bundle
+     *  build reads cluster config; local bundles read the row's own git_config). */
     config: AppConfig;
     /** Required for universal-git source registration — `null` is allowed;
      *  rows with `git_config` are skipped + metric-bumped in that case. */

package/dist/routes/uploads.d.ts

@@ -1,38 +1,48 @@
 /**
- * REST endpoints for test run upload management.
+ * Test-run upload provisioning.
  *
- * POST /api/v1/uploads/init           - Initialize an upload (returns signed URL + public key)
- * GET  /api/v1/uploads/:uploadId/status - Check upload status
- *
- * Uploads support the repo state transfer mechanism: CLI uploads an encrypted
- * tarball of changed files to S3 via a pre-signed URL, then references the
- * upload ID in the test trigger request.
+ * Mints an upload record and a presigned PUT URL + ephemeral X25519 public key
+ * for the overlay tarball. The developer encrypts the tarball with the returned
+ * public key and PUTs it directly to the object store; a test trigger then
+ * references the upload id. This is invoked by the Platform-first
+ * `test.relay.uploads.init` relay handler — the developer never reaches the
+ * orchestrator's HTTP API directly.
  */
-import { Hono } from 'hono';
-import type { AppConfig } from '../config.js';
-import type { TokenManager } from '../secrets/token-manager.js';
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { CacheStorage } from '../storage/types.js';
-/**
- * Dependencies for upload routes.
- */
-export interface UploadRouteDeps {
-    config: AppConfig;
+/** Parameters for {@link initTestUpload}. */
+export interface InitTestUploadParams {
+    routingKey: string;
+    sha?: string;
+    fileCount?: number;
+    compressedSize?: number;
+    /** PAT/actor identity that owns this upload, written to `test_uploads.created_by`. */
+    createdBy?: string | null;
+    /**
+     * When true, presign with the host-facing internal endpoint. When false (the
+     * Platform-relayed path), presign with the external/dev-reachable endpoint so
+     * a developer on a different network can PUT directly to the object store.
+     */
+    internal?: boolean;
+}
+/** Result of {@link initTestUpload}. */
+export interface InitTestUploadResult {
+    uploadId: string;
+    signedUrl: string;
+    publicKey: string;
+    expiresIn: number;
+}
+/** Dependencies for {@link initTestUpload}. */
+export interface InitTestUploadDeps {
     db: Kysely<Database>;
-    tokenManager?: TokenManager;
     cacheStorage?: CacheStorage;
 }
-/** Hono env type for upload routes with context variables. */
-type UploadEnv = {
-    Variables: {
-        userId: string;
-        routingKey: string | null;
-    };
-};
 /**
- * Create Hono routes for upload management endpoints.
+ * Mint an upload record and return a presigned PUT URL + ephemeral X25519
+ * public key. The encryption keypair is generated per upload; the private key
+ * is stored orchestrator-side for post-PUT decryption. The `internal` flag
+ * selects the host-facing vs the external/dev-reachable presign endpoint.
  */
-export declare function createUploadRoutes(deps: UploadRouteDeps): Hono<UploadEnv>;
-export {};
+export declare function initTestUpload(deps: InitTestUploadDeps, params: InitTestUploadParams): Promise<InitTestUploadResult>;
 //# sourceMappingURL=uploads.d.ts.map