@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/pipeline/processor.d.ts

@@ -0,0 +1,326 @@
+/**
+ * Core webhook processing pipeline.
+ *
+ * Connects all orchestrator modules into a complete processing flow:
+ * dedup -> normalize event -> fetch lock file -> get changed files ->
+ * match triggers -> cache check -> dispatch jobs
+ *
+ * Uses the ProviderRegistry for all provider-specific operations.
+ * No direct GitHub/Octokit references -- fully provider-agnostic.
+ *
+ * Decision traces are forwarded to Platform via platformClient.send() (which buffers
+ * internally when disconnected -- the caller does NOT check connection state).
+ */
+import { type Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { WebhookInfo } from '../webhook/handler.js';
+import type { DedupCache } from '../webhook/dedup.js';
+import type { ProviderRegistry, ProviderBundle } from '../provider-registry.js';
+import type { LockFileCache } from '../lockfile-cache.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { PlatformClient } from '../ws/platform-client.js';
+import type { QueuedJobInput } from '../queue/job-queue.js';
+import type { SourceCache } from '../cache/index.js';
+import type { BuildCoordinator } from '../cache/index.js';
+import type { DepCache } from '../cache/index.js';
+import type { PendingBuildTracker } from '../cache/index.js';
+import type { PendingInitTracker } from '../cache/pending-inits.js';
+import type { PendingDynamicTracker } from '../cache/pending-dynamics.js';
+import type { CommitStatusReporter } from '../reporting/commit-status.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { RunCoordinator } from '../cluster/coordinator.js';
+import type { LogStorage } from '../reporting/log-storage.js';
+import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { ContributorCache } from '../security/contributor-cache.js';
+import type { LockFile as FullLockFile, LockWorkflow, SimulatedEvent, WebhookNormalizer } from '@kici-dev/engine';
+import type { EventRouter } from '../events/event-router.js';
+import type { RegistrationStore } from '../registration/registration-store.js';
+import type { RegistrationIndex } from '../registration/registration-index.js';
+import type { CronScheduler } from '../cron/cron-scheduler.js';
+import type { GlobalWorkflowPolicy } from '../security/global-workflow-policy.js';
+import type { EventLogWriter } from '../webhook/event-log.js';
+import { EventLogSource } from '@kici-dev/engine';
+import type { LockJob } from '@kici-dev/engine';
+import type { EnvironmentStore } from '../environments/environment-store.js';
+import type { VariableStore } from '../environments/variable-store.js';
+import type { TrustResolver, IdentityLink, PermissionLevel } from '../security/trust-resolver.js';
+import type { HeldRunStore } from '../environments/held-runs.js';
+import type { WorkflowDecision } from '@kici-dev/engine';
+/**
+ * Pending dispatch context for jobs gated by the needs scheduler.
+ * Keyed by `${runId}:${jobName}`. Populated at processWebhook time for all
+ * non-root static jobs. Consumed by the onJobReady callback when the scheduler
+ * determines a job's upstreams are all satisfied.
+ *
+ * Entries are cleaned up after dispatch or when the run completes.
+ */
+interface PendingJobContext {
+    jobInput: QueuedJobInput;
+    runsOnLabels: string[];
+}
+/**
+ * Store a pending dispatch context for a job that will be dispatched later
+ * by the needs scheduler. The key is `${runId}:${jobName}`.
+ * Writes to both in-memory Map and DB table for crash recovery.
+ * @internal Exported for testing
+ */
+export declare function storePendingJobContext(db: Kysely<Database> | undefined, runId: string, jobName: string, ctx: PendingJobContext): Promise<void>;
+/**
+ * Consume and remove a pending dispatch context for a job.
+ * Returns undefined if no context is stored (e.g. job was already dispatched).
+ * Deletes from both in-memory Map and DB table.
+ *
+ * Cluster correctness: `storePendingJobContext` writes to both the local
+ * in-memory Map and the shared DB. In an HA cluster the peer that ingested
+ * the webhook stores the context, but `onJobReady` fires on whichever peer
+ * tracked the upstream job's completion — which, for a rerouted upstream,
+ * is a different peer whose Map is empty. Falling through to an atomic
+ * `DELETE ... RETURNING` ensures exactly one peer claims the context.
+ * @internal Exported for testing
+ */
+export declare function consumePendingJobContext(db: Kysely<Database> | undefined, runId: string, jobName: string): Promise<PendingJobContext | undefined>;
+/**
+ * Clean up all pending dispatch contexts for a run (called on run completion).
+ * Deletes from both in-memory Map and DB table.
+ */
+export declare function cleanupPendingJobContexts(db: Kysely<Database> | undefined, runId: string): Promise<void>;
+/**
+ * Restore all pending job contexts from DB into the in-memory Map.
+ * Called on startup before the needs scheduler recovery loop so that
+ * dispatchReadyJob has context available for recovered jobs.
+ */
+export declare function restorePendingJobContexts(db: Kysely<Database>): Promise<number>;
+/**
+ * Clear all entries from the in-memory pending job contexts Map.
+ * @internal Exported for testing only.
+ */
+export declare function clearPendingJobContextsMap(): void;
+/**
+ * Determine if a lock job is a "root" job (no concrete needs and no dependsOnGroups).
+ * Root jobs can be dispatched immediately; non-root jobs wait for the scheduler.
+ */
+export declare function isRootJob(lockJob: LockJob): boolean;
+/**
+ * Attempt to resolve a lock file for (repoIdentifier, ref) using the inbound
+ * webhook's provider bundle first, then falling back to other provider bundles
+ * registered against the SAME customer's registrations for the SAME repo.
+ *
+ * Why this exists
+ * ----------------
+ * The webhook pipeline binds `lockFileFetcher` to the inbound webhook's
+ * provider bundle. When an internal-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.
+ * This resolver lets the pipeline consult OTHER bundles whose registrations
+ * prove they own the repo for the same tenant.
+ *
+ * Tenant boundary (security-critical)
+ * -----------------------------------
+ * The fallback iterates ONLY registrations returned by
+ * `registrationIndex.getByOrgAndRepo(customerId, repoIdentifier)`. That
+ * index is keyed by `${customerId}|${repoIdentifier}`, so cross-customer
+ * leakage is structurally impossible — a customer-B registration for
+ * `owner/repo` will never be returned when we pass `customerId = 'custA'`.
+ * The resolver also skips any registration whose `routingKey` matches the
+ * inbound routing key (no self-recursion) and dedupes by routing key so a
+ * repo with many workflows registered through the same source only
+ * triggers one fallback fetch.
+ *
+ * Ordering
+ * --------
+ * Registrations are consulted in the order returned by the index (which
+ * preserves insertion order = createdAt ascending). The first non-null
+ * lock file wins. If all fallbacks return null the function returns null
+ * and the caller falls through to the existing `Lock file not found`
+ * global-workflow-matching path.
+ *
+ * Credentials
+ * -----------
+ * Each fallback fetcher is invoked with the REGISTRATION'S
+ * `providerContext`, NOT the inbound normalizer's credentials. This is
+ * load-bearing: the InternalWebhookNormalizer 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.
+ */
+export declare function resolveLockFileWithFallback(args: {
+    inboundBundle: ProviderBundle;
+    inboundRoutingKey: string;
+    repoIdentifier: string;
+    ref: string;
+    inboundCredentials: unknown;
+    customerId: string;
+    providerRegistry: ProviderRegistry;
+    registrationIndex: RegistrationIndex | undefined;
+    lockFileCache: LockFileCache;
+    deliveryId: string;
+}): Promise<{
+    lockFile: FullLockFile | null;
+    resolvedVia: 'inbound' | 'fallback' | 'miss';
+    fallbackRoutingKey?: string;
+    /** The winning provider bundle when resolvedVia='fallback'. Used by the dispatch
+     *  site to swap repoUrlBuilder and cloneTokenProvider (Layer 4 cross-provider fix). */
+    fallbackBundle?: ProviderBundle;
+    /** The winning registration's providerContext when resolvedVia='fallback'.
+     *  Carries installationId etc. for clone token issuance. */
+    fallbackCredentials?: Record<string, unknown>;
+}>;
+/**
+ * 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.
+ */
+export declare function resolveOrgId(db: Kysely<Database>, routingKey: string): Promise<string>;
+/**
+ * Map GitHub webhook event types to lock file trigger type strings.
+ * Used for global workflow matching via RegistrationIndex.getGlobalByTriggerType().
+ */
+export declare function eventTypeToTriggerType(eventType: string): string;
+/**
+ * Extract a human-readable trigger event string from webhook info.
+ * Combines event type with action (e.g. "push", "pull_request:opened").
+ */
+export declare function buildTriggerEvent(event: string, action: string | null | undefined): string;
+/**
+ * Extract the first line of the commit message from a webhook payload.
+ * Handles push (head_commit.message) and PR (pull_request.title) events.
+ */
+/**
+ * Best-effort extraction of a repository identifier from a generic webhook
+ * payload for cross-source dispatch (phase 28.5). Generic webhooks have no
+ * canonical repo shape, so we probe the conventions a sender is most likely
+ * to use:
+ *
+ *   1. GitHub-style `repository.full_name` (`owner/repo`)
+ *   2. GitHub-style `repository.owner.login` + `repository.name`
+ *   3. Flat `repository` string (e.g. `{"repository": "owner/repo"}`)
+ *
+ * Returns null when no recognisable repo field is present, in which case the
+ * cross-source repo lookup is skipped (event-name fan-out still runs).
+ */
+export declare function extractInboundRepoIdentifier(payload: unknown): string | null;
+export declare function extractCommitMessage(event: string, payload: unknown): string | undefined;
+/**
+ * Build a human-readable summary for a security hold check.
+ */
+export declare function buildSecurityHoldSummary(reason: string, tier: string, contributorUsername?: string): string;
+/**
+ * Dependencies for the processing pipeline.
+ * All injected for testability. Fully provider-agnostic.
+ *
+ * sourceCache and buildCoordinator are optional for backward compatibility --
+ * existing tests and deployments without cache configured still work.
+ */
+export interface ProcessingDeps {
+    dedup: DedupCache;
+    providerRegistry: ProviderRegistry;
+    lockFileCache: LockFileCache;
+    dispatcher: Dispatcher;
+    /** Null/undefined in Independent mode. send() buffers when disconnected. */
+    platformClient?: PlatformClient;
+    /** Directory for writing raw webhook payloads. If set, writes {dir}/{repo}/{deliveryId}/payload.json. */
+    webhookPayloadDir?: string;
+    /** Bundle cache for compiled workflow bundles. Optional -- if not set, cache is bypassed. */
+    sourceCache?: SourceCache;
+    /** Build coordinator for deduplicating concurrent builds. Optional -- if not set, cache is bypassed. */
+    buildCoordinator?: BuildCoordinator;
+    /** Dep cache for dependency tarballs. Optional -- if not set, dep caching is bypassed. */
+    depCache?: DepCache;
+    /** Pending build tracker -- waits for build agents to finish before dispatching execution jobs. */
+    pendingBuilds?: PendingBuildTracker;
+    /** Pending init tracker -- waits for init agents to resolve dynamic fields before static dispatch. */
+    pendingInits?: PendingInitTracker;
+    /** Pending dynamic tracker -- waits for agents to evaluate DynamicJobFn and return generated LockJob[]. */
+    pendingDynamics?: PendingDynamicTracker;
+    /** Commit status reporter for setting pending/success/failure/error on commits. Optional. */
+    commitStatusReporter?: CommitStatusReporter;
+    /** Execution tracker for DB persistence. Optional -- if not set, execution tracking is skipped. */
+    executionTracker?: ExecutionTracker;
+    /** Agent registry for determining execution target platform/arch. Optional -- if not set, defaults to linux/x64. */
+    agentRegistry?: AgentRegistry;
+    /** Run coordinator for multi-orchestrator job routing. Optional -- if not set, all jobs dispatch locally (single-orchestrator mode). */
+    coordinator?: RunCoordinator;
+    /** Secret resolver for dispatch-time secret resolution. Optional -- if not set, secrets are not resolved. */
+    secretResolver?: SecretResolver;
+    /** Optional callback when source locations are extracted from a lock file workflow. */
+    onSourceLocationsExtracted?: (workflowName: string, jobName: string, sourceLocations: Array<{
+        file: string;
+        line: number;
+        column: number;
+    } | undefined>) => void;
+    /** Event router for registering lock file event subscriptions. Optional -- if not set, event routing is inactive. */
+    eventRouter?: EventRouter;
+    /** Registration store for persisting workflow registrations. Optional -- if not set, registration is skipped. */
+    registrationStore?: RegistrationStore;
+    /** Registration index for in-memory lookup. Optional -- if not set, registration is skipped. */
+    registrationIndex?: RegistrationIndex;
+    /** Cron scheduler for cache refresh after registration changes. Optional -- if not set, cron cache refresh is skipped. */
+    cronScheduler?: CronScheduler;
+    /** Database connection for ephemeral key storage. Optional -- if not set, cross-job secret output support is inactive. */
+    db?: Kysely<Database>;
+    /** Secret key (KICI_SECRET_KEY) for encrypting ephemeral private keys. Required when db is set. */
+    secretKey?: string;
+    /** Log storage backend for persisting webhook payloads. Optional -- if not set, payload storage is skipped. */
+    logStorage?: LogStorage;
+    /** Environment store for looking up deployment environments. Optional -- if not set, environment features are inactive. */
+    environmentStore?: EnvironmentStore;
+    /** Variable store for resolving environment variables. Optional -- if not set, environment vars are not merged. */
+    variableStore?: VariableStore;
+    /** Held run store for persisting protection rule holds. Optional -- if not set, holds are not persisted. */
+    heldRunStore?: HeldRunStore;
+    /** Trust resolver for determining contributor trust tiers. Optional -- if not set, trust resolution is skipped. */
+    trustResolver?: TrustResolver;
+    /** Identity links pushed from Platform for trust resolution. Optional -- defaults to empty. */
+    identityLinks?: IdentityLink[];
+    /** ci_trust permission levels per user ID from Platform push. Optional -- defaults to empty. */
+    orgMemberPermissions?: Map<string, PermissionLevel>;
+    /** Global workflow policy for org-level permission enforcement. Optional -- if not set, global workflows are unrestricted. */
+    globalWorkflowPolicy?: GlobalWorkflowPolicy;
+    /** Inbound webhook delivery log writer. Optional -- if not set, deliveries are not persisted to event_log. */
+    eventLog?: EventLogWriter;
+    /** Where this delivery arrived: 'relay' (Platform WS) or 'direct' (HTTP).
+     *  Used by the eventLog writer to populate the source column. Defaults to
+     *  'direct' when omitted (independent / direct paths). */
+    eventLogSource?: EventLogSource;
+    /** Contributor permission cache. Optional -- if not set, membership-webhook
+     *  invalidations silently no-op. In platform/hybrid mode the singleton is
+     *  created in server.ts and threaded through both the Platform-relay WS
+     *  path and the generic webhook HTTP path. */
+    contributorCache?: ContributorCache;
+}
+/**
+ * Check if any trigger in the lock file workflows uses path filters.
+ * Used to skip the changedFilesFetcher call when no path patterns are configured,
+ * saving one provider API call per webhook.
+ */
+export declare function anyTriggerHasPathPatterns(workflows: LockWorkflow[]): boolean;
+export { processWebhook } from './process-webhook.js';
+/**
+ * Dispatch a job that has become ready via the needs scheduler.
+ *
+ * Called by the onJobReady callback registered on the execution tracker.
+ * Consumes the pending dispatch context stored at processWebhook time,
+ * dispatches the job through the normal dispatcher path, and updates the
+ * execution tracker with the real job ID.
+ */
+export declare function dispatchReadyJob(runId: string, jobName: string, dispatcher: Dispatcher, executionTracker?: ExecutionTracker, coordinator?: RunCoordinator, db?: Kysely<Database>): Promise<void>;
+/**
+ * Check whether a webhook event is a push to the repository's default branch.
+ * Used to trigger registration extraction for workflow event subscriptions.
+ *
+ * Resolution order for the default branch:
+ *   1. `normalizer.extractDefaultBranch?(payload)` — provider-specific hook
+ *      (universal-git reads a JSONPath from the source's `payloadPaths.defaultBranch`).
+ *   2. Fallback to `payload.repository.default_branch` — the GitHub-shaped
+ *      default that most forges mirror.
+ */
+export declare function isDefaultBranchPush(info: WebhookInfo, event: SimulatedEvent, payload: Record<string, unknown>, normalizer: WebhookNormalizer): boolean;
+/**
+ * Create a serializable summary of a workflow decision for Platform forwarding.
+ */
+export declare function summarizeDecision(decision: WorkflowDecision): Record<string, unknown>;
+//# sourceMappingURL=processor.d.ts.map

package/dist/pipeline/rerun.d.ts

@@ -0,0 +1,79 @@
+/**
+ * Re-run handler for the orchestrator.
+ *
+ * Loads an original completed run, retrieves its webhook payload from
+ * object storage, re-fetches the lock file at the original SHA, and
+ * dispatches a new run with parent_run_id linkage.
+ *
+ * This is NOT a reuse of processWebhook -- it's a separate, simpler function
+ * that skips dedup, normalization, trigger matching, and changed files fetching.
+ * It goes directly to: lock file parse -> job expansion -> dispatch.
+ */
+import { type ColdStore } from '@kici-dev/shared';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { LogStorage } from '../reporting/log-storage.js';
+import type { ProviderRegistry } from '../provider-registry.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+import type { JobQueue } from '../queue/job-queue.js';
+import type { PlatformClient } from '../ws/platform-client.js';
+import type { CommitStatusReporter } from '../reporting/commit-status.js';
+import type { RunCoordinator } from '../cluster/coordinator.js';
+import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { EventRouter } from '../events/event-router.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { SourceCache } from '../cache/index.js';
+import type { BuildCoordinator } from '../cache/index.js';
+import type { DepCache } from '../cache/index.js';
+import type { PendingBuildTracker } from '../cache/index.js';
+/**
+ * Thrown when a rerun is attempted on an archived run AND the cold-store
+ * replay path failed (chunk missing, contentHash mismatch, S3 outage, or
+ * cold-store probe disabled). Phase F replaced the Phase-C "rerun is
+ * blocked" semantics with a real replay path; this error now signals
+ * a genuine "we tried to bring the row back and could not".
+ *
+ * The WS dashboard handler maps this to a structured response that the
+ * Platform proxy surfaces as HTTP 410 (`errorCode: 'runArchivedNotRerunnable'`).
+ */
+export declare class RunArchivedNotRerunnableError extends Error {
+    readonly runId: string;
+    readonly code: "runArchivedNotRerunnable";
+    constructor(runId: string);
+}
+export interface RerunDeps {
+    db: Kysely<Database>;
+    logStorage: LogStorage;
+    providerRegistry: ProviderRegistry;
+    executionTracker: ExecutionTracker;
+    dispatcher: Dispatcher;
+    jobQueue: JobQueue;
+    platformClient: PlatformClient | null;
+    commitStatusReporter: CommitStatusReporter | null;
+    coordinator: RunCoordinator | null;
+    secretResolver: SecretResolver | null;
+    eventRouter: EventRouter | null;
+    agentRegistry: AgentRegistry;
+    sourceCache: SourceCache | null;
+    depCache: DepCache | null;
+    buildCoordinator: BuildCoordinator | null;
+    pendingBuilds: PendingBuildTracker | null;
+    /**
+     * Phase F — when set, a PG miss on `originalRunId` triggers a
+     * cold-store replay of the chunk containing the row, then a re-read.
+     * `null` keeps the legacy "throw RunArchivedNotRerunnableError on PG
+     * miss" path for deployments without cold-store wired up.
+     */
+    coldStore: ColdStore | null;
+}
+export declare function handleRerun(originalRunId: string, triggeredBy: string | null, deps: RerunDeps, 
+/**
+ * Phase F — routing key for the original run, forwarded by Platform
+ * via the WS `run.rerun.request` payload. Required to address the
+ * cold-store chunk under the right tenant prefix.
+ */
+routingKeyHint?: string): Promise<{
+    newRunId: string;
+}>;
+//# sourceMappingURL=rerun.d.ts.map

package/dist/pipeline/test-pipeline.d.ts

@@ -0,0 +1,110 @@
+/**
+ * Test pipeline processor for CLI-initiated test runs.
+ *
+ * Reuses the existing webhook processing pipeline steps (lock file fetch,
+ * trigger matching, job dispatch) but injects a synthetic event instead
+ * of processing a real webhook. This avoids the anti-pattern of calling
+ * processWebhook() directly (which expects WebhookInfo from a real webhook).
+ *
+ * Key differences from processWebhook():
+ * - Skips dedup check (test runs are always unique)
+ * - Skips webhook normalization (event is already in SimulatedEvent shape)
+ * - Skips repo extraction from payload (routing key is provided directly)
+ * - deliveryId has `test:` prefix for identification
+ * - Execution runs are marked with is_test_run=true and fixture_id
+ * - Supports direct workflow execution (bypass trigger matching)
+ */
+import type { LockFileCache } from '../lockfile-cache.js';
+import type { Dispatcher } from '../agent/dispatcher.js';
+import type { CommitStatusReporter } from '../reporting/commit-status.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+import type { AgentRegistry } from '../agent/registry.js';
+import type { ProviderRegistry } from '../provider-registry.js';
+import type { SourceCache } from '../cache/index.js';
+import type { BuildCoordinator } from '../cache/index.js';
+import type { DepCache } from '../cache/index.js';
+import type { PendingBuildTracker } from '../cache/index.js';
+import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { LogStorage } from '../reporting/log-storage.js';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+/**
+ * Input for a test trigger request.
+ */
+export interface TestTriggerInput {
+    /** Unique fixture identifier from the CLI. */
+    fixtureId: string;
+    /** The simulated event to inject into the pipeline. */
+    event: {
+        type: string;
+        action?: string;
+        targetBranch: string;
+        sourceBranch?: string;
+        payload: Record<string, unknown>;
+        changedFiles?: string[];
+    };
+    /** Routing key for provider lookup and lock file fetch. */
+    routingKey: string;
+    /** Reference to uploaded tarball (optional). */
+    uploadId?: string;
+    /** Fixture secret context mappings (optional). */
+    secrets?: Record<string, string>;
+    /** Direct workflow run -- bypass triggers (optional). */
+    workflowName?: string;
+    /** Resolved overlay metadata for tarball download + decryption. */
+    resolvedOverlay?: {
+        tarballUrl: string;
+        cliPublicKey: string;
+        orchestratorPrivateKey: string;
+    };
+    /** Request trace ID from the HTTP request. */
+    requestId: string;
+    /** JSON-stringified lock file content for local repos with no remote. */
+    inlineLockFile?: string;
+    /** When true, repo has no remote -- skip provider lookup, skip clone. */
+    fullRepo?: boolean;
+}
+/**
+ * Result of processing a test trigger.
+ */
+interface TestTriggerResult {
+    /** Unique run identifier. */
+    runId: string;
+    /** Whether the test trigger was accepted or rejected. */
+    status: 'accepted' | 'rejected';
+    /** Reason for rejection (if rejected). */
+    reason?: string;
+    /** Dispatched job IDs. */
+    jobIds: string[];
+}
+/**
+ * Dependencies for the test pipeline processor.
+ * All injected for testability.
+ */
+export interface TestPipelineDeps {
+    lockFileCache: LockFileCache;
+    dispatcher: Dispatcher;
+    executionTracker?: ExecutionTracker;
+    commitStatusReporter?: CommitStatusReporter;
+    sourceCache?: SourceCache;
+    buildCoordinator?: BuildCoordinator;
+    depCache?: DepCache;
+    pendingBuilds?: PendingBuildTracker;
+    secretResolver?: SecretResolver;
+    agentRegistry: AgentRegistry;
+    providerRegistry: ProviderRegistry;
+    /** Log storage for persisting test fixture payloads. Optional -- if not set, payload storage is skipped. */
+    logStorage?: LogStorage;
+    /** Database connection for environment protection checks. Optional. */
+    db?: Kysely<Database>;
+}
+/**
+ * Process a test trigger through the existing pipeline.
+ *
+ * Reuses pipeline steps starting from lock file fetch, skipping webhook
+ * normalization and dedup. Supports both trigger-matched and direct
+ * workflow execution modes.
+ */
+export declare function processTestTrigger(input: TestTriggerInput, deps: TestPipelineDeps): Promise<TestTriggerResult>;
+export {};
+//# sourceMappingURL=test-pipeline.d.ts.map

package/dist/provider-registry.d.ts

@@ -0,0 +1,122 @@
+/**
+ * Provider registry for the orchestrator.
+ *
+ * Maps routing keys to implementation bundles containing all provider capabilities.
+ * Static registration (no dynamic loading) -- providers are registered at startup.
+ *
+ * Each routing key (e.g., "github:12345") maps to its own ProviderBundle instance
+ * with per-app credentials. This supports multiple GitHub Apps (or other providers)
+ * registered simultaneously, each with its own appId/privateKey pair.
+ *
+ * The registry is the single entry point for all provider-specific operations:
+ * webhook normalization, lock file fetching, changed files retrieval,
+ * clone token creation, and URL building.
+ */
+import type { WebhookNormalizer, LockFileFetcher, ChangedFilesFetcher, CloneTokenProvider, RepoUrlBuilder, ContributorResolver, CheckStatusPoster, ProviderType } from '@kici-dev/engine';
+/**
+ * Complete set of provider capabilities.
+ *
+ * Only normalizer is required -- non-Git providers (e.g., generic webhooks)
+ * don't need lock file fetching, changed files, clone tokens, or URL building.
+ * The pipeline processor already handles missing provider capabilities by
+ * skipping operations.
+ */
+export interface ProviderBundle {
+    normalizer: WebhookNormalizer;
+    lockFileFetcher?: LockFileFetcher;
+    changedFilesFetcher?: ChangedFilesFetcher;
+    cloneTokenProvider?: CloneTokenProvider;
+    repoUrlBuilder?: RepoUrlBuilder;
+    contributorResolver?: ContributorResolver;
+    checkStatusPoster?: CheckStatusPoster;
+}
+/**
+ * Registry mapping routing keys to their implementation bundles.
+ *
+ * Routing keys have the format "{provider}:{id}" (e.g., "github:12345").
+ * Each routing key gets its own ProviderBundle with per-app credentials.
+ *
+ * Usage (multi-app):
+ *   const registry = new ProviderRegistry();
+ *   registry.registerByRoutingKey('github:12345', bundleForApp1);
+ *   registry.registerByRoutingKey('github:67890', bundleForApp2);
+ *   const bundle = registry.getByRoutingKey('github:12345');
+ *
+ * Usage (backward-compatible single-app):
+ *   registry.register('github', bundle);
+ *   const bundle = registry.get('github');
+ */
+export declare class ProviderRegistry {
+    private readonly bundles;
+    /**
+     * Register a provider bundle by routing key.
+     *
+     * Each routing key gets its own bundle with per-app credentials.
+     * Routing keys have the format "{provider}:{id}" (e.g., "github:12345").
+     */
+    registerByRoutingKey(routingKey: string, bundle: ProviderBundle): void;
+    /**
+     * Register a provider implementation bundle by provider type.
+     *
+     * Backward-compatible: stores the bundle under a synthetic routing key
+     * "{type}:default". Only works for single-app scenarios.
+     *
+     * For multi-app support, use registerByRoutingKey() instead.
+     */
+    register(type: ProviderType, bundle: ProviderBundle): void;
+    /**
+     * Get the provider bundle for a given type.
+     *
+     * Backward-compatible: returns the first bundle matching the provider type
+     * prefix. For multi-app, use getByRoutingKey() instead.
+     */
+    get(type: ProviderType): ProviderBundle | undefined;
+    /**
+     * Get the provider bundle by routing key.
+     * Routing keys have the format "{provider}:{id}" (e.g., "github:12345").
+     *
+     * Falls back to get(providerType) if exact key is not found,
+     * for backward compatibility with single-app registration.
+     */
+    getByRoutingKey(routingKey: string): ProviderBundle | undefined;
+    /**
+     * Get just the normalizer for a routing key.
+     * Convenience method for webhook handling.
+     */
+    getNormalizerByRoutingKey(routingKey: string): WebhookNormalizer | undefined;
+    /**
+     * Iterate over all registered bundles.
+     */
+    getAll(): IterableIterator<[string, ProviderBundle]>;
+    /**
+     * Check if a provider type has at least one registered bundle.
+     */
+    has(type: ProviderType): boolean;
+    /**
+     * Get all registered routing keys.
+     */
+    getRoutingKeys(): string[];
+    /**
+     * Get routing keys matching a specific provider type.
+     *
+     * @param type - Provider type (e.g., "github")
+     * @returns Array of routing keys matching the type prefix
+     */
+    getRoutingKeysForProvider(type: ProviderType): string[];
+    /**
+     * Remove a routing key and its bundle.
+     * Used during config reload when apps are removed.
+     */
+    unregister(routingKey: string): boolean;
+    /**
+     * Check if a routing key is for a generic webhook source.
+     * Generic routing keys have the format "generic:{orgId}:{sourceId}".
+     */
+    static isGenericRoutingKey(routingKey: string): boolean;
+    /**
+     * Remove all registered bundles.
+     * Used during full config rebuild on reload.
+     */
+    clear(): void;
+}
+//# sourceMappingURL=provider-registry.d.ts.map

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

@@ -0,0 +1,23 @@
+/**
+ * Generic webhook provider implementations for KiCI.
+ *
+ * Unlike Git providers (GitHub, GitLab, Bitbucket), the generic provider
+ * only implements WebhookNormalizer. Git-related methods (lock file fetching,
+ * changed files, clone tokens, URL building) are not applicable for
+ * arbitrary webhook sources.
+ */
+import type { ProviderBundle } from '../../provider-registry.js';
+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.
+ *
+ * @param sourceManager - GenericSourceManager for source config lookup
+ * @returns ProviderBundle with normalizer only
+ */
+export declare function createGenericProviderBundle(sourceManager: GenericSourceManager): ProviderBundle;
+//# sourceMappingURL=index.d.ts.map