@kici-dev/orchestrator 0.1.16 → 0.1.17

package/dist/pipeline/pending-workflow-context.d.ts

@@ -0,0 +1,44 @@
+/**
+ * Pending workflow dispatch context store — the workflow-level analogue of the
+ * `pending_job_contexts` store. Persists the serializable inputs of a
+ * `WorkflowDispatchContext` so a workflow whose install gate held can be
+ * resumed (reviewer approve, wait-timer expiry, concurrency slot free) by
+ * rebuilding the dispatch context and re-running `dispatchMatchedWorkflow`.
+ *
+ * Only the serializable inputs are stored — the live `deps` (ProcessingDeps)
+ * and `bundle` (ProviderBundle) are NOT persisted; they are rebuilt from the
+ * live orchestrator on resume.
+ *
+ * Writes to both an in-memory Map (fast read on the same process) and the DB
+ * (crash recovery + cross-orchestrator read), mirroring the pending-job store.
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { WorkflowDispatchContext } from './dispatch-matched-workflow.js';
+/**
+ * The serializable subset of a `WorkflowDispatchContext` — everything except
+ * the live `deps` and `bundle`, which are rebuilt on resume. Every field here
+ * is JSON-safe (the event, payload, and lock file already ride the WS protocol
+ * as JSON).
+ */
+export type SerializableWorkflowDispatchInputs = Omit<WorkflowDispatchContext, 'deps' | 'bundle'>;
+/** Extract the serializable inputs from a live dispatch context. */
+export declare function toSerializableInputs(ctx: WorkflowDispatchContext): SerializableWorkflowDispatchInputs;
+/** Persist the pending workflow context to the in-memory Map and the DB. */
+export declare function storePendingWorkflowContext(db: Kysely<Database> | undefined, inputs: SerializableWorkflowDispatchInputs): Promise<void>;
+/** Load the pending workflow context by run id (memory first, then DB). */
+export declare function loadPendingWorkflowContext(db: Kysely<Database> | undefined, runId: string): Promise<SerializableWorkflowDispatchInputs | null>;
+/** Delete the pending workflow context from the in-memory Map and the DB. */
+export declare function deletePendingWorkflowContext(db: Kysely<Database> | undefined, runId: string): Promise<void>;
+/**
+ * Restore the in-memory Map from the DB on startup, skipping rows whose run has
+ * already reached a terminal state. Mirrors `restorePendingJobContexts`.
+ * Returns the number of restored contexts.
+ */
+export declare function restorePendingWorkflowContexts(db: Kysely<Database>): Promise<number>;
+/**
+ * Clear all entries from the in-memory pending workflow contexts Map.
+ * @internal Exported for testing only.
+ */
+export declare function clearPendingWorkflowContextsMap(): void;
+//# sourceMappingURL=pending-workflow-context.d.ts.map

package/dist/pipeline/processor.d.ts

@@ -112,7 +112,7 @@ export declare function isRootJob(lockJob: LockJob): boolean;
  * Why this exists
  * ----------------
  * The webhook pipeline binds `lockFileFetcher` to the inbound webhook's
- * provider bundle. When an internal-sourced webhook (e.g., the staging
+ * provider bundle. When a local-sourced webhook (e.g., the staging
  * stg-ha-smoke failover-dispatch test) arrives for a repo whose lock file
  * is only accessible via a different provider (e.g., github), the inbound
  * fetcher returns null and trigger matching silently drops the webhook.
@@ -143,7 +143,7 @@ export declare function isRootJob(lockJob: LockJob): boolean;
  * -----------
  * Each fallback fetcher is invoked with the REGISTRATION'S
  * `providerContext`, NOT the inbound normalizer's credentials. This is
- * load-bearing: the InternalWebhookNormalizer returns `{}` as
+ * load-bearing: the LocalWebhookNormalizer returns `{}` as
  * credentials, which would never satisfy a github fetcher that requires
  * `installationId`. The registration carries the correct credentials
  * because it was created via the owning provider's source.
@@ -178,8 +178,10 @@ export declare function resolveLockFileWithFallback(args: {
  * Resolve the customer/org ID for a routing key.
  *
  * Checks the `sources` table first (GitHub App sources), then
- * `generic_webhook_sources` (generic webhook sources). Falls back to
- * '__default__' if neither table has the routing key.
+ * `generic_webhook_sources` (generic webhook sources), then `remote_sources`
+ * (the auto-provisioned anchor for Platform-relayed `kici run remote`, routing
+ * key `remote:<orgId>`). Falls back to '__default__' if none of the three
+ * tables has the routing key.
  */
 export declare function resolveOrgId(db: Kysely<Database>, routingKey: string): Promise<string>;
 /**

package/dist/pipeline/remote-source-store.d.ts

@@ -0,0 +1,21 @@
+import type { Kysely } from 'kysely';
+import type { Database, RemoteSourceRow } from '../db/types.js';
+/**
+ * Deterministic routing key for an org's Platform-relayed remote runs. A
+ * Platform-relayed `test.trigger` carries this key; `resolveOrgId` maps it back
+ * to the canonical org id via the `remote_sources` row.
+ */
+export declare function remoteRoutingKeyFor(orgId: string): string;
+/**
+ * Idempotently upsert the `remote_sources` anchor for an org. Called on every
+ * Platform (re)connect once the orchestrator learns its canonical org id from
+ * `auth.success`. The unique `(customer_id)` constraint makes this a safe
+ * self-heal — re-running updates `cluster_id` if the cluster identity changed.
+ */
+export declare function provisionRemoteSource(db: Kysely<Database>, params: {
+    orgId: string;
+    clusterId: string | null;
+}): Promise<void>;
+/** Read the auto-provisioned remote-source row for an org, if it exists. */
+export declare function getRemoteSource(db: Kysely<Database>, orgId: string): Promise<RemoteSourceRow | undefined>;
+//# sourceMappingURL=remote-source-store.d.ts.map

package/dist/pipeline/resume-workflow.d.ts

@@ -0,0 +1,26 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { ProcessingDeps } from './processor.js';
+import type { ReleaseSignal } from '../environments/held-runs.js';
+import { type WorkflowDispatchContext } from './dispatch-matched-workflow.js';
+import { type SerializableWorkflowDispatchInputs } from './pending-workflow-context.js';
+/**
+ * Rebuild a live `WorkflowDispatchContext` from the persisted serializable
+ * inputs by re-attaching the orchestrator's live `deps` and reconstructing the
+ * provider `bundle` from the live registry (keyed by the stored routing key).
+ * Returns null when the provider bundle can no longer be resolved.
+ */
+export declare function rebuildWorkflowDispatchContext(inputs: SerializableWorkflowDispatchInputs, deps: ProcessingDeps): WorkflowDispatchContext | null;
+/**
+ * Resume a released workflow install-gate hold. Loads the pending context,
+ * rebuilds the dispatch context, and re-dispatches with the gate skipped. On a
+ * lost pending context (or unresolvable provider bundle) the run is failed
+ * loudly rather than silently dropped.
+ */
+export declare function resumeWorkflow(signal: ReleaseSignal, deps: ProcessingDeps, db: Kysely<Database> | undefined): Promise<void>;
+/**
+ * Cancel a rejected workflow install-gate hold: mark the run cancelled and drop
+ * the pending context.
+ */
+export declare function rejectWorkflow(runId: string, deps: ProcessingDeps, db: Kysely<Database> | undefined, reason: string): Promise<void>;
+//# sourceMappingURL=resume-workflow.d.ts.map

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/reporting/execution-tracker.d.ts

@@ -395,6 +395,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