@kici-dev/orchestrator 0.0.0 → 0.1.2

package/dist/pipeline/dispatch-matched-workflow.d.ts

@@ -0,0 +1,102 @@
+/**
+ * Per-workflow dispatch pipeline.
+ *
+ * Handles everything that happens AFTER a workflow has been matched against an
+ * incoming webhook: payload storage, cache + build coordination, secret
+ * resolution, per-job environment evaluation, static job dispatch (cluster +
+ * single-orch paths), execution-tracker registration, deferred init dispatch
+ * for jobs with dynamic fields, and deferred dynamic-job-fn dispatch for
+ * `_type:'dynamic'` lock entries.
+ *
+ * Splits the historic 2438-line `dispatchMatchedWorkflow` into typed phase
+ * helpers so each piece can be reasoned about independently. The main
+ * exported function is a narrative orchestrator that threads the typed
+ * results through the pipeline.
+ */
+import type { LockWorkflow, SimulatedEvent, WorkflowDecision } from '@kici-dev/engine';
+import type { WebhookInfo } from '../webhook/handler.js';
+import type { ProviderBundle } from '../provider-registry.js';
+import type { TrustResolution } from '../security/trust-resolver.js';
+import { type ProcessingDeps } from './processor.js';
+/**
+ * Context for dispatching a single matched workflow.
+ *
+ * Captures every per-workflow closure dependency so the dispatch body is
+ * callable from BOTH the same-source path AND the cross-source delegation
+ * shell. `crossSource` is the discriminator the helper uses to override the
+ * dispatch `deliveryId` so fan-out targets land on their composite dedup
+ * slot (`${inbound.deliveryId}:${reg.id}`) instead of the inbound delivery
+ * id.
+ */
+export interface WorkflowDispatchContext {
+    info: WebhookInfo;
+    deps: ProcessingDeps;
+    bundle: ProviderBundle;
+    payload: unknown;
+    repoIdentifier: string;
+    credentials: Record<string, unknown>;
+    event: SimulatedEvent;
+    eventWithFiles: SimulatedEvent;
+    ref: string;
+    fullLockFile: {
+        workflows: readonly LockWorkflow[];
+        lockfileHash?: string;
+        source: {
+            file: string;
+        };
+    };
+    resolvedOrgId: string;
+    workflow: LockWorkflow;
+    decision: WorkflowDecision;
+    runId: string;
+    trustResolution: TrustResolution | undefined;
+    lockFileSource: string | undefined;
+    /** True only when invoked from the cross-source dispatch shell. */
+    crossSource: boolean;
+    /** Composite dedup key `${info.deliveryId}:${reg.id}` (cross-source only). */
+    crossSourceDeliveryId?: string;
+    /**
+     * Routing key to use for dispatched QueuedJobInput + log / tracker rows.
+     * Same-source: equal to `info.routingKey`. Cross-source: equal to
+     * `reg.routingKey` (the registration's owning source, NOT the inbound
+     * generic routing key).
+     */
+    effectiveRoutingKey?: string;
+    /**
+     * Provider identifier to use for dispatched QueuedJobInput + tracker rows.
+     * Same-source: equal to `info.provider`. Cross-source: equal to
+     * `regBundle.normalizer.provider` (the registration's provider type,
+     * e.g. 'github').
+     */
+    effectiveProvider?: string;
+    /**
+     * Extra jobConfig fields merged into every dispatched QueuedJobInput by
+     * this helper. Cross-source callers use this to inject provenance fields
+     * (`crossSource: true`, `inboundRoutingKey`, `inboundEventName`,
+     * `workflowRepoUrl`, `workflowRef`, `workflowSha`,
+     * `workflowRepoIdentifier`) that downstream agents / dashboards need for
+     * correct clone + logging.
+     */
+    extraJobConfig?: Record<string, unknown>;
+}
+export interface DispatchMatchedWorkflowResult {
+    /** Number of jobs successfully dispatched (non-rejected). */
+    dispatchedJobCount: number;
+}
+/**
+ * Dispatch a single matched workflow.
+ *
+ * Narrative orchestrator: each phase is a typed helper that returns a typed
+ * result the next phase consumes. The function reads top-to-bottom as the
+ * pipeline:
+ *   A. setup → wrapped dispatcher + overlaid info
+ *   B. cache + build → buildPrep with cache URLs and build-job state
+ *   C. workflow secrets + ephemeral key → secret bundle
+ *   D. per-job env evaluation → job env data + deferred-init queue
+ *   E+F+G. static job dispatch → dispatchedJobs / rejectedJobs
+ *   H. execution-tracker registration + edges + rejected-mark
+ *   I. deferred init dispatch (fire-and-forget per job)
+ *   J. deferred dynamic dispatch (fire-and-forget per dynamic entry)
+ */
+export declare function dispatchMatchedWorkflow(ctx: WorkflowDispatchContext): Promise<DispatchMatchedWorkflowResult>;
+//# sourceMappingURL=dispatch-matched-workflow.d.ts.map

package/dist/pipeline/inline-eval.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Inline expression evaluator for pure dynamic functions.
+ *
+ * Evaluates serialized arrow functions from the lockfile (LockInlineValue)
+ * in a sandboxed VM context at dispatch time, eliminating the init-job
+ * round-trip for pure functions.
+ */
+/**
+ * Evaluate an inline expression that returns a string.
+ *
+ * @param expression - Serialized arrow function, e.g. '(event) => event.ref.split("/").pop()'
+ * @param event - Normalized webhook event payload
+ * @returns The string result
+ * @throws TypeError if result is not a string
+ * @throws Error on timeout or sandbox violation
+ */
+export declare function evaluateInlineString(expression: string, event: object): string;
+/**
+ * Evaluate an inline expression that returns a Record<string, string>.
+ *
+ * @param expression - Serialized arrow function, e.g. '(event) => ({ NODE_ENV: event.env })'
+ * @param event - Normalized webhook event payload
+ * @returns The record result
+ * @throws TypeError if result is not a plain object
+ * @throws Error on timeout or sandbox violation
+ */
+export declare function evaluateInlineRecord(expression: string, event: object): Record<string, string>;
+//# sourceMappingURL=inline-eval.d.ts.map

package/dist/pipeline/install-secrets-resolver.d.ts

@@ -0,0 +1,73 @@
+/**
+ * Resolve workflow-level `registries:` and `installEnv:` declarations into the
+ * per-dispatch fields the agent needs to authenticate `npm install` against
+ * private registries.
+ *
+ * Each `tokenSecret` / `installEnv[]` entry uses the qualified
+ * `<environment>:<secret-name>` syntax. The resolver:
+ *
+ *   1. Parses every qualified ref and groups by environment name.
+ *   2. Fires the per-environment protection-rule pipeline once per unique env
+ *      (branch / trust / concurrency / reviewer / wait-timer). Any non-pass
+ *      result rejects the whole workflow dispatch — v1 does not yet support
+ *      workflow-scoped held-runs, so a `hold` from the reviewer-gate is
+ *      surfaced as a reject with a clear reason.
+ *   3. Resolves secrets per environment via `secretResolver.resolveForJob`
+ *      (which writes its own audit log lines).
+ *   4. Validates each registry URL scheme: HTTPS always allowed; `http://`
+ *      allowed only for loopback / `*.local` hosts OR when the org operator
+ *      has flipped `org_settings.allow_http_npm_registries=true`.
+ *   5. Strips the resolved auth entirely when the contributor-trust tier is
+ *      not `trusted` (defense in depth: even if a misconfigured environment
+ *      lets an unknown contributor through the protection-pipeline trust
+ *      gate, this strip ensures fork PRs never see registry tokens — the
+ *      install fails naturally because the deps are unreachable).
+ *
+ * Pure helper: no imports of the dispatch giant. Tested in isolation in
+ * `install-secrets-resolver.test.ts`.
+ */
+import type { LockRegistry } from '@kici-dev/engine';
+import type { TrustResolution } from '../security/trust-resolver.js';
+import type { SecretResolver } from '../secrets/secret-resolver.js';
+import type { EnvironmentStore } from '../environments/environment-store.js';
+import { type JobDispatchContext } from '../environments/protection/pipeline.js';
+/** Registry spec carried on the dispatch message (token already resolved). */
+export interface NpmRegistrySpec {
+    url: string;
+    scope?: string;
+    alwaysAuth: boolean;
+    token: string;
+}
+export interface ResolveInstallSecretsArgs {
+    registries: readonly LockRegistry[] | undefined;
+    installEnv: readonly string[] | undefined;
+    allowHttpNpmRegistries: boolean;
+    resolvedOrgId: string;
+    trustResolution: TrustResolution | undefined;
+    environmentStore: EnvironmentStore | undefined;
+    secretResolver: SecretResolver | undefined;
+    protectionContext: JobDispatchContext;
+}
+export type ResolveInstallSecretsResult = {
+    decision: 'pass';
+    npmRegistries: NpmRegistrySpec[] | undefined;
+    installEnvSecrets: Record<string, string> | undefined;
+    contributorStripped: boolean;
+} | {
+    decision: 'reject';
+    reason: string;
+};
+/** Parse `<environment>:<secret-name>`. Returns null on malformed input. */
+export declare function parseQualifiedSecretRef(ref: string): {
+    envName: string;
+    secretName: string;
+} | null;
+/** Validate a registry URL's scheme against the org's http allow-toggle. */
+export declare function validateRegistryUrlScheme(url: string, allowHttp: boolean): {
+    ok: true;
+} | {
+    ok: false;
+    reason: string;
+};
+export declare function resolveInstallSecrets(args: ResolveInstallSecretsArgs): Promise<ResolveInstallSecretsResult>;
+//# sourceMappingURL=install-secrets-resolver.d.ts.map

package/dist/pipeline/manual-schedule.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Manual schedule handler for the orchestrator.
+ *
+ * Dispatches a new run for a cron-scheduled workflow triggered manually
+ * from the dashboard UI. Uses direct dispatch (not eventRouter.emit) so
+ * the newRunId can be returned synchronously in the WS response.
+ *
+ * This is intentionally separate from the automatic cron path which uses
+ * eventRouter fire-and-forget. The manual path needs request/response
+ * correlation to return the newRunId to the dashboard.
+ */
+import type { RerunDeps } from './rerun.js';
+import type { RegistrationIndex } from '../registration/registration-index.js';
+interface ManualScheduleDeps extends RerunDeps {
+    registrationIndex: RegistrationIndex;
+}
+export declare function handleManualSchedule(registrationId: string, triggeredBy: string | null, deps: ManualScheduleDeps): Promise<{
+    newRunId: string;
+}>;
+export {};
+//# sourceMappingURL=manual-schedule.d.ts.map

package/dist/pipeline/needs-scheduler.d.ts

@@ -0,0 +1,85 @@
+/**
+ * DB-backed needs-aware dispatch scheduler ( through).
+ *
+ * This module is the core of 's behavioral change: it replaces the
+ * "concurrent dispatch" model with event-driven scheduling that gates ALL
+ * needs edges (static-to-static, static-to-dyn-group, dyn-to-static, dyn-to-dyn).
+ *
+ * The scheduler is pure DB — no in-memory state. Every scheduling decision is
+ * a fresh DB query against execution_jobs + execution_job_needs. This means
+ * zero recovery code on orchestrator restart.
+ *
+ * Entry points:
+ * - insertEdgesForRun: called at run start for static-to-static edges
+ * - resolveGroupEdges: called on dynamic-eval completion
+ * - evaluateDownstreams: called from onJobStatus(terminal)
+ * - recomputeNeedsSatisfied: batch recompute after group resolution
+ * - checkSchedulerInvariant: Layer 3 defensive check
+ * - getFailurePropagationTargets: cascade for transitive skip
+ */
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { NeedsEntry, NeedsGroupEntry } from '@kici-dev/engine';
+/** Result of evaluating downstream jobs after an upstream completes. */
+export interface SchedulerResult {
+    jobName: string;
+    action: 'dispatch' | 'skip';
+    reason?: string;
+}
+/** Minimal lock job shape needed by insertEdgesForRun. */
+interface LockJobLike {
+    readonly name: string;
+    readonly needs: readonly (string | NeedsEntry | NeedsGroupEntry)[];
+    readonly dependsOnGroups?: readonly string[];
+}
+/**
+ * Insert dependency edges at run start for static-to-static needs.
+ * NeedsGroupEntry items are skipped (resolved later via resolveGroupEdges).
+ * Root jobs (no needs, no dependsOnGroups) are marked needs_satisfied=true.
+ */
+export declare function insertEdgesForRun(db: Kysely<Database>, runId: string, lockJobs: readonly LockJobLike[]): Promise<void>;
+/**
+ * Resolve dynamic group edges after eval completion.
+ *
+ * For each dependent static job and each member job name, inserts a concrete
+ * edge row. Empty groups (0 members) trigger immediate needs_satisfied=true
+ * for dependents.
+ *
+ * CRITICAL: dependentStaticJobs carries per-job ifFailed policy from the
+ * NeedsGroupEntry in the lock file. Without this, all group edges would
+ * silently default to 'skip'.
+ */
+export declare function resolveGroupEdges(db: Kysely<Database>, runId: string, groupName: string, memberJobNames: string[], dependentStaticJobs: Array<{
+    jobName: string;
+    ifFailed: 'skip' | 'run';
+}>): Promise<void>;
+/**
+ * Evaluate downstream jobs after an upstream reaches terminal state.
+ *
+ * This is the core scheduler hook. For each downstream of the completed job:
+ * 1. If upstream failed and edge has if_failed='skip', mark downstream as 'skip'
+ * 2. Otherwise, check if ALL upstreams are terminal
+ * 3. If all satisfied, mark needs_satisfied=true and return for dispatch
+ */
+export declare function evaluateDownstreams(db: Kysely<Database>, runId: string, completedJobName: string, completedStatus: string): Promise<SchedulerResult[]>;
+/**
+ * Batch recompute needs_satisfied for specified jobs.
+ * Used after group resolution and on orchestrator restart recovery.
+ * Returns scheduler results for any jobs that became ready.
+ */
+export declare function recomputeNeedsSatisfied(db: Kysely<Database>, runId: string, jobNames: string[]): Promise<SchedulerResult[]>;
+/**
+ * Layer 3: defensive scheduler invariant check.
+ *
+ * Finds jobs that are stuck: needs_satisfied=false, status='pending',
+ * all upstreams are terminal, and no pending group resolution.
+ * Returns the names of stuck jobs (empty array = no violation).
+ */
+export declare function checkSchedulerInvariant(db: Kysely<Database>, runId: string): Promise<string[]>;
+/**
+ * cascade: find all transitive downstreams that should be skipped
+ * due to failure propagation. Only follows edges where if_failed='skip'.
+ */
+export declare function getFailurePropagationTargets(db: Kysely<Database>, runId: string, failedJobName: string): Promise<string[]>;
+export {};
+//# sourceMappingURL=needs-scheduler.d.ts.map

package/dist/pipeline/process-webhook.d.ts

@@ -0,0 +1,38 @@
+/**
+ * Webhook processing pipeline.
+ *
+ * Splits the historic 1339-line `processWebhook` into typed phase helpers so
+ * each piece can be reasoned about independently. The main exported function
+ * is a narrative orchestrator that threads the typed results through the
+ * pipeline:
+ *
+ *   dedup -> provider -> normalize -> (cross-source dispatch | per-repo path)
+ *   per-repo path: extract repo + creds -> trust resolution -> lock file fetch
+ *     -> (no lock file: global dispatch & return)
+ *     -> security hold + workflow modifications -> default-branch registration
+ *     -> match triggers -> dispatch matched same-source -> dispatch globals
+ *     -> forward traces & event log
+ *
+ * Internal helpers are pure phase functions returning typed results; the only
+ * top-level export is `processWebhook`, callable from server.ts / app.ts.
+ */
+import type { WebhookInfo } from '../webhook/handler.js';
+import { type ProcessingDeps } from './processor.js';
+/**
+ * Process a webhook through the complete pipeline.
+ *
+ * Flow:
+ *   1. Dedup + provider lookup -> contributor cache invalidation -> normalize
+ *   2. Cross-source dispatch (generic webhook fan-out, optional)
+ *   3. Extract repo + credentials, handle /kici approval comments
+ *   4. Trust resolution for PR events
+ *   5. Lock file fetch (with multi-provider fallback)
+ *      - No lock file: dispatch global workflows for this event (same org) and return
+ *   6. Workflow modification detection + security hold check status
+ *   7. Default-branch registration
+ *   8. Match triggers + dispatch matched same-source workflows
+ *   9. Match + dispatch global workflows for OTHER repos
+ *  10. Forward Platform trace + record event log
+ */
+export declare function processWebhook(info: WebhookInfo, deps: ProcessingDeps): Promise<void>;
+//# sourceMappingURL=process-webhook.d.ts.map