@kici-dev/orchestrator 0.0.0 → 0.1.1

package/dist/config.d.ts

@@ -0,0 +1,249 @@
+/**
+ * Orchestrator configuration.
+ *
+ * This is a thin backward-compatible wrapper around the new config resolution
+ * chain (config/resolver.ts). It preserves the existing synchronous loadConfig()
+ * API so that no other files need changing.
+ *
+ * The new config system lives in config/ and supports:
+ * - YAML config files (config/loader.ts)
+ * - Shared DB config store (config/shared-store.ts)
+ * - 4-layer resolution: env > YAML > DB > defaults (config/resolver.ts)
+ * - KICI_ env var mapping (config/env-overlay.ts)
+ *
+ * Provider configuration (GitHub Apps, etc.) is managed via the `sources` table
+ * and PgSecretStore, not through config. See SourceStore and SourceManager.
+ */
+import { z } from 'zod';
+declare const configSchema: z.ZodObject<{
+    mode: z.ZodDefault<z.ZodEnum<{
+        platform: "platform";
+        hybrid: "hybrid";
+        independent: "independent";
+    }>>;
+    port: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    basePath: z.ZodDefault<z.ZodString>;
+    tlsCertPath: z.ZodOptional<z.ZodString>;
+    platformUrl: z.ZodOptional<z.ZodString>;
+    platformToken: z.ZodOptional<z.ZodString>;
+    dashboardUrl: z.ZodOptional<z.ZodString>;
+    databaseUrl: z.ZodDefault<z.ZodString>;
+    lockfileCacheMax: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    lockfileCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    queueMaxDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    queueTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    queueBackpressureThreshold: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    workerConcurrency: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    concurrencyWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cacheStorageType: z.ZodOptional<z.ZodEnum<{
+        s3: "s3";
+        filesystem: "filesystem";
+    }>>;
+    cacheStoragePath: z.ZodOptional<z.ZodString>;
+    cacheStorageS3Bucket: z.ZodOptional<z.ZodString>;
+    cacheStorageS3Prefix: z.ZodDefault<z.ZodString>;
+    cacheStorageS3Region: z.ZodOptional<z.ZodString>;
+    cacheStorageS3Endpoint: z.ZodOptional<z.ZodString>;
+    cacheStorageS3ExternalEndpoint: z.ZodOptional<z.ZodString>;
+    cacheStorageS3ForcePathStyle: z.ZodOptional<z.ZodPipe<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>, z.ZodTransform<boolean, "true" | "false">>>;
+    cacheStorageFsPath: z.ZodOptional<z.ZodString>;
+    cacheStorageFsBaseUrl: z.ZodOptional<z.ZodString>;
+    logStorageS3Bucket: z.ZodOptional<z.ZodString>;
+    cacheTtlDays: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cacheBuildTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    cacheMaxTarballBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    webhookPayloadDir: z.ZodOptional<z.ZodString>;
+    scalerConfigPath: z.ZodOptional<z.ZodString>;
+    scalerConfigDir: z.ZodOptional<z.ZodString>;
+    machineLedgerDir: z.ZodOptional<z.ZodString>;
+    staleDetectorScanIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    staleDetectorThresholdMultiplier: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    jobHeartbeatIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    secretKey: z.ZodOptional<z.ZodString>;
+    secretKeyFile: z.ZodOptional<z.ZodString>;
+    secretKeyOld: z.ZodOptional<z.ZodString>;
+    secretKeyFileOld: z.ZodOptional<z.ZodString>;
+    bootstrapAdminToken: z.ZodOptional<z.ZodString>;
+    pgCustomerSecrets: z.ZodPipe<z.ZodDefault<z.ZodEnum<{
+        true: "true";
+        false: "false";
+    }>>, z.ZodTransform<boolean, "true" | "false">>;
+    agentAuth: z.ZodDefault<z.ZodEnum<{
+        token: "token";
+        none: "none";
+    }>>;
+    agentTokenTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    eventRouterMaxChainDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    eventRouterRateLimitPerWorkflowPerMinute: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    eventRouterEventTtlSeconds: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    eventRouterCleanupIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    eventRouterMaxDispatchAttempts: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    eventRouterLeaseDurationMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    eventRouterRetryBaseBackoffMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    eventRouterRetryMaxBackoffMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    eventRouterRetryScanIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    eventLogMaxPayloadBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    logLevel: z.ZodDefault<z.ZodEnum<{
+        error: "error";
+        debug: "debug";
+        info: "info";
+        warn: "warn";
+    }>>;
+    nodeEnv: z.ZodDefault<z.ZodEnum<{
+        development: "development";
+        production: "production";
+        test: "test";
+    }>>;
+    internalProviderRepoPath: z.ZodOptional<z.ZodString>;
+    internalProviderCloneUrl: z.ZodOptional<z.ZodString>;
+    autoMigrate: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
+    agentMaxReconnectDelayMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    skipS3SentinelValidation: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<boolean, string>>;
+    otelExporterOtlpEndpoint: z.ZodOptional<z.ZodString>;
+    cluster: z.ZodPrefault<z.ZodObject<{
+        instanceId: z.ZodDefault<z.ZodOptional<z.ZodString>>;
+        address: z.ZodOptional<z.ZodString>;
+        joinToken: z.ZodOptional<z.ZodString>;
+        credentialFile: z.ZodDefault<z.ZodString>;
+        autoRotateCredentials: z.ZodDefault<z.ZodBoolean>;
+        peers: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string[], string | undefined>>;
+        raftElectionTimeoutMinMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        raftElectionTimeoutMaxMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        raftHeartbeatMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        peerHeartbeatIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        peerMaxReconnectDelayMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        role: z.ZodDefault<z.ZodEnum<{
+            coordinator: "coordinator";
+            worker: "worker";
+        }>>;
+        coordinatorUrl: z.ZodOptional<z.ZodString>;
+        coordinatorUrls: z.ZodPipe<z.ZodOptional<z.ZodString>, z.ZodTransform<string[], string | undefined>>;
+        peerStaleTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        electionGracePeriodMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+        singleNode: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>, z.ZodTransform<boolean, string | boolean>>;
+        trustedProxies: z.ZodPipe<z.ZodDefault<z.ZodString>, z.ZodTransform<string[], string>>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+/**
+ * App configuration type. Includes computed instanceId for multi-instance support.
+ *
+ * Provider configuration (GitHub Apps) is now managed via the sources table
+ * and SourceManager, not through config.
+ */
+export type AppConfig = z.infer<typeof configSchema> & {
+    /** Unique identifier for this orchestrator instance, generated at startup */
+    instanceId: string;
+    /** Object storage settings (populated from legacy env vars or SharedConfig) */
+    storage?: {
+        type?: 's3' | 'filesystem';
+        bucket?: string;
+        prefix?: string;
+        region?: string;
+        endpoint?: string;
+        externalEndpoint?: string;
+        forcePathStyle?: boolean;
+        logBucket?: string;
+        /** Filesystem backend: absolute base directory for cached blobs. */
+        fsBasePath?: string;
+        /** Filesystem backend: base URL the agent uses to reach this orchestrator. */
+        fsBaseUrl?: string;
+    };
+};
+/**
+ * Env-var definition for the orchestrator. Exported so the docs generator and
+ * the deploy-stg pre-validator can re-parse without going through process.env.
+ *
+ * Note: passes the inner `baseSchema` (a ZodObject) so describe() can walk
+ * `.shape`, but uses the outer `configSchema` (with .superRefine) as the parser
+ * so cross-field rules still fire.
+ */
+export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
+    mode: "platform" | "hybrid" | "independent";
+    port: number;
+    basePath: string;
+    databaseUrl: string;
+    lockfileCacheMax: number;
+    lockfileCacheTtlMs: number;
+    queueMaxDepth: number;
+    queueTimeoutMs: number;
+    queueBackpressureThreshold: number;
+    workerConcurrency: number;
+    concurrencyWaitTimeoutMs: number;
+    cacheStorageS3Prefix: string;
+    cacheTtlDays: number;
+    cacheBuildTimeoutMs: number;
+    cacheMaxTarballBytes: number;
+    staleDetectorScanIntervalMs: number;
+    staleDetectorThresholdMultiplier: number;
+    jobHeartbeatIntervalMs: number;
+    pgCustomerSecrets: boolean;
+    agentAuth: "token" | "none";
+    agentTokenTtlMs: number;
+    eventRouterMaxChainDepth: number;
+    eventRouterRateLimitPerWorkflowPerMinute: number;
+    eventRouterEventTtlSeconds: number;
+    eventRouterCleanupIntervalMs: number;
+    eventRouterMaxDispatchAttempts: number;
+    eventRouterLeaseDurationMs: number;
+    eventRouterRetryBaseBackoffMs: number;
+    eventRouterRetryMaxBackoffMs: number;
+    eventRouterRetryScanIntervalMs: number;
+    eventLogMaxPayloadBytes: number;
+    logLevel: "error" | "debug" | "info" | "warn";
+    nodeEnv: "development" | "production" | "test";
+    autoMigrate: boolean;
+    agentMaxReconnectDelayMs: number;
+    skipS3SentinelValidation: boolean;
+    cluster: {
+        instanceId: string;
+        credentialFile: string;
+        autoRotateCredentials: boolean;
+        peers: string[];
+        raftElectionTimeoutMinMs: number;
+        raftElectionTimeoutMaxMs: number;
+        raftHeartbeatMs: number;
+        peerHeartbeatIntervalMs: number;
+        peerMaxReconnectDelayMs: number;
+        role: "coordinator" | "worker";
+        coordinatorUrls: string[];
+        peerStaleTimeoutMs: number;
+        electionGracePeriodMs: number;
+        singleNode: boolean;
+        trustedProxies: string[];
+        address?: string | undefined;
+        joinToken?: string | undefined;
+        coordinatorUrl?: string | undefined;
+    };
+    tlsCertPath?: string | undefined;
+    platformUrl?: string | undefined;
+    platformToken?: string | undefined;
+    dashboardUrl?: string | undefined;
+    cacheStorageType?: "s3" | "filesystem" | undefined;
+    cacheStoragePath?: string | undefined;
+    cacheStorageS3Bucket?: string | undefined;
+    cacheStorageS3Region?: string | undefined;
+    cacheStorageS3Endpoint?: string | undefined;
+    cacheStorageS3ExternalEndpoint?: string | undefined;
+    cacheStorageS3ForcePathStyle?: boolean | undefined;
+    cacheStorageFsPath?: string | undefined;
+    cacheStorageFsBaseUrl?: string | undefined;
+    logStorageS3Bucket?: string | undefined;
+    webhookPayloadDir?: string | undefined;
+    scalerConfigPath?: string | undefined;
+    scalerConfigDir?: string | undefined;
+    machineLedgerDir?: string | undefined;
+    secretKey?: string | undefined;
+    secretKeyFile?: string | undefined;
+    secretKeyOld?: string | undefined;
+    secretKeyFileOld?: string | undefined;
+    bootstrapAdminToken?: string | undefined;
+    internalProviderRepoPath?: string | undefined;
+    internalProviderCloneUrl?: string | undefined;
+    otelExporterOtlpEndpoint?: string | undefined;
+}>;
+export declare function loadConfig(): AppConfig;
+export {};
+//# sourceMappingURL=config.d.ts.map

package/dist/cron/cron-scheduler.d.ts

@@ -0,0 +1,78 @@
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { RegistrationIndex } from '../registration/registration-index.js';
+import type { EventRouter } from '../events/event-router.js';
+import type { CronStore } from './cron-store.js';
+interface CronSchedulerOptions {
+    db: Kysely<Database>;
+    registrationIndex: RegistrationIndex;
+    cronStore: CronStore;
+    eventRouter: EventRouter;
+    evaluationIntervalMs?: number;
+}
+/**
+ * Raft-leader-only cron evaluator.
+ *
+ * Only the current Raft leader evaluates cron schedules. On becoming leader,
+ * loads the last-fired cache from the DB, recovers missed schedules (fires
+ * once per schedule), then starts periodic evaluation.
+ *
+ * On losing leadership, stops evaluation immediately.
+ *
+ * Atomicity: each fire wraps `cronStore.tryClaimFire` and
+ * `eventRouter.emitInTx` in a single Postgres transaction. `pg_notify`
+ * inside that tx is queued by Postgres until commit, so a rollback discards
+ * both the `cron_last_fired` write AND the listener notification together.
+ * This closes the previous silent-loss window where a crash between claim
+ * and emit advanced `last_fired_at` without persisting an event row.
+ */
+export declare class CronScheduler {
+    private readonly db;
+    private readonly registrationIndex;
+    private readonly cronStore;
+    private readonly eventRouter;
+    private readonly evaluationIntervalMs;
+    private timer;
+    private isLeader;
+    private lastFiredCache;
+    constructor(options: CronSchedulerOptions);
+    /**
+     * Called when this orchestrator becomes the Raft leader.
+     * Loads last-fired cache, recovers missed schedules, starts periodic evaluation.
+     */
+    onBecomeLeader(): Promise<void>;
+    /**
+     * Called when this orchestrator loses Raft leadership.
+     * Stops the evaluation timer immediately.
+     */
+    onLoseLeadership(): void;
+    /**
+     * Stop the scheduler entirely. Clears timer and resets leader state.
+     */
+    stop(): void;
+    /**
+     * Reload the last-fired cache from the database.
+     * Called after registration changes as defense-in-depth to ensure
+     * the in-memory cache stays current even if registration IDs change.
+     */
+    refreshCache(): Promise<void>;
+    /**
+     * Evaluate all cron schedules and fire those that are due.
+     *
+     * For each schedule: uses croner to compute the most recent past scheduled
+     * time. If that time is after the last-fired-at (or no last-fired exists),
+     * fires the schedule.
+     */
+    evaluate(): Promise<void>;
+    /**
+     * Recover missed schedules after becoming leader.
+     * Same logic as evaluate() but logs recovery context.
+     */
+    private recoverMissedSchedules;
+    /**
+     * Evaluate a single registration and fire if due.
+     */
+    private evaluateRegistration;
+}
+export {};
+//# sourceMappingURL=cron-scheduler.d.ts.map

package/dist/cron/cron-store.d.ts

@@ -0,0 +1,38 @@
+import type { Kysely, Transaction } from 'kysely';
+import type { Database } from '../db/types.js';
+type DbExecutor = Kysely<Database> | Transaction<Database>;
+/**
+ * DB persistence for cron last-fired tracking.
+ *
+ * Tracks the last time each cron-triggered workflow registration was fired.
+ * Used by CronScheduler for fire-once-on-recovery after leader transitions.
+ * Uses upsert (INSERT ON CONFLICT UPDATE) for atomic idempotent writes.
+ */
+export declare class CronStore {
+    private readonly db;
+    constructor(db: Kysely<Database>);
+    /**
+     * Atomically claim a cron fire: only succeeds if no other orchestrator has
+     * already fired this registration at a time >= firedAt.
+     *
+     * Uses INSERT ... ON CONFLICT with a WHERE guard so the upsert only writes
+     * when `last_fired_at < firedAt` (or the row doesn't exist yet).
+     *
+     * Accepts an optional executor (Kysely DB handle or Transaction). The cron
+     * fire path passes a Transaction so the claim and the subsequent
+     * `kici_events` insert + `pg_notify` commit atomically — closing the
+     * "claim succeeds but emit fails" silent-loss window that existed when
+     * these were separate transactions.
+     *
+     * Returns true if this call won the race (the fire should proceed).
+     * Returns false if another node already recorded a fire >= firedAt.
+     */
+    tryClaimFire(registrationId: string, firedAt: Date, executor?: DbExecutor): Promise<boolean>;
+    /**
+     * Get all last-fired records as a Map<registrationId, lastFiredAt>.
+     * Used for bulk loading during leader recovery.
+     */
+    getAll(): Promise<Map<string, Date>>;
+}
+export {};
+//# sourceMappingURL=cron-store.d.ts.map

package/dist/dashboard/handler.d.ts

@@ -0,0 +1,243 @@
+/**
+ * Dashboard handler for the orchestrator.
+ *
+ * Responds to dashboard.* and run.* WS messages from Platform by querying the local
+ * execution_jobs and execution_steps tables and reading logs from LogStorage.
+ *
+ * Supported messages:
+ * - dashboard.run.detail: returns jobs with nested steps for a run
+ * - dashboard.step.logs: returns log lines for a specific step
+ * - dashboard.payload: returns the original webhook payload for a run
+ * - run.rerun.request: re-runs a completed workflow run
+ * - run.cancel.request: cancels a running workflow run
+ */
+import type { Kysely } from 'kysely';
+import { type ColdStore } from '@kici-dev/shared';
+import type { DashboardRunDetailRequest, DashboardStepLogsRequest, DashboardPayloadRequest, DashboardOrchLogsRequest, DashboardEventLogListRequest, DashboardEventLogDetailRequest, DashboardEventLogPayloadStreamRequest, DashboardAccessLogListRequest, RunRerunRequest, RunCancelRequest, ManualScheduleRequest } from '@kici-dev/engine';
+import type { Database } from '../db/types.js';
+import type { LogStorage } from '../reporting/log-storage.js';
+import type { AccessLogWriter } from '../audit/access-log.js';
+interface DashboardHandlerDeps {
+    db: Kysely<Database>;
+    logStorage: LogStorage;
+    /** Send a response message back to Platform over the WS connection. */
+    send: (msg: unknown) => void;
+    /** This orchestrator's instance ID, included in job detail responses. */
+    orchestratorId?: string;
+    /** Access log writer — records one row per read / mutation with actor attribution. */
+    accessLog?: AccessLogWriter;
+    /** Org ID for access_log rows (null when the orchestrator isn't org-scoped). */
+    orgId?: string | null;
+    /** Routing key for access_log rows (null when not run-scoped). */
+    routingKey?: string | null;
+    /**
+     * Long-lived cold-store handle for read fallback. When set, run /
+     * job / step lookups fall through to S3 if the row has aged out of
+     * PG. `null` means the orchestrator is running without cold-store
+     * configured — handler then returns its pre-Phase-C behavior.
+     */
+    coldStore?: ColdStore | null;
+    /**
+     * Callback for handling re-run requests.
+     * Returns { newRunId } on success or throws on failure.
+     *
+     * Phase F — `routingKey` is forwarded from the Platform (read from
+     * Platform's denormalized `execution_runs.routing_key`) so the
+     * orchestrator can probe its cold-store under the right tenant
+     * prefix when the run row is missing from PG. Optional for back-
+     * compat with mixed deploys; absent means the orchestrator falls
+     * back to the legacy "no PG row → throw" path.
+     */
+    onRerun: (runId: string, triggeredBy: string | null, routingKey?: string) => Promise<{
+        newRunId: string;
+    }>;
+    /**
+     * Callback for handling cancel requests.
+     * Returns { cancelledJobs } on success or throws on failure.
+     * The force flag indicates whether to force-cancel (SIGKILL, skip hooks).
+     */
+    onCancel: (runId: string, cancelledBy: string | null, force?: boolean) => Promise<{
+        cancelledJobs: number;
+    }>;
+    /**
+     * Callback for handling manual schedule trigger requests.
+     * Returns { newRunId } on success or throws on failure.
+     */
+    onManualSchedule: (registrationId: string, triggeredBy: string | null) => Promise<{
+        newRunId: string;
+    }>;
+}
+export declare class DashboardHandler {
+    private readonly db;
+    private readonly logStorage;
+    private readonly send;
+    private readonly orchestratorId;
+    private readonly accessLog;
+    private orgId;
+    private routingKey;
+    private readonly onRerun;
+    private readonly onCancel;
+    private readonly onManualSchedule;
+    private readonly coldStore;
+    constructor(deps: DashboardHandlerDeps);
+    /**
+     * Update the bound orgId + routingKey. Called from server.ts after resolving
+     * the single tenant org from the `sources` / `generic_webhook_sources` table.
+     *
+     * NOTE: this binding is the **fallback** for `recordAccess`. Run-targeted
+     * handlers resolve the run-owning org per-request via `resolveOrgForRun`;
+     * the bound pair is consulted only when the per-target lookup yields no
+     * result (e.g. cold-archived run, deleted source). On a multi-tenant
+     * orchestrator the bound pair is non-deterministic (server.ts:937-955
+     * picks the first row from a `LIMIT 1` query with no `ORDER BY`), so it
+     * MUST NOT be the source of truth for `access_log.org_id`.
+     */
+    setOrgContext(orgId: string | null, routingKey: string | null): void;
+    /**
+     * Resolve the run-owning org from `execution_runs.routing_key` plus a
+     * sources/generic_webhook_sources lookup on that routing key. Returns
+     * `null` when the run row is missing (e.g. cold-archived) so the caller
+     * can fall back to the handler-bound context.
+     *
+     * Returns `{ orgId, routingKey }` where either field can be null:
+     * - `routingKey` is non-null whenever the PG run row was found, even if
+     *   the source row has since been deleted (best-effort attribution).
+     * - `orgId` is null only when the routing key has no matching source row.
+     */
+    private resolveOrgForRun;
+    /**
+     * Resolve the org owning a routing key by consulting both source tables
+     * (GitHub-app `sources` first, then `generic_webhook_sources`). Used
+     * directly for `handleRerunRequest` (which gets a `routingKey` hint from
+     * Platform — Phase F denormalization) and indirectly via
+     * `resolveOrgForRun`.
+     */
+    private resolveOrgForRoutingKey;
+    /**
+     * Resolve the org from a `workflow_registrations` row. Returns null when
+     * the registration is missing (caller falls back to bound context).
+     */
+    private resolveOrgForRegistration;
+    /**
+     * Apply a per-target resolution result, falling back to the handler-bound
+     * orgId / routingKey when the resolution is null or its individual fields
+     * are null. This is the merge point that makes the bound context a
+     * fallback rather than the source of truth.
+     */
+    private contextOrFallback;
+    /**
+     * Write an access_log row for a handler invocation. The caller resolves
+     * the run-owning org via `resolveOrgForRun` (or the registration / event-
+     * log equivalents) and threads it in here so each row carries the org
+     * that owns the target — not the handler-bound (multi-tenant: non-
+     * deterministic) pair. Best-effort; the writer swallows failures.
+     */
+    private recordAccess;
+    /**
+     * Handle a dashboard.run.detail request.
+     * Queries execution_jobs and execution_steps for the given runId,
+     * builds a nested job/step tree, and sends the response.
+     */
+    handleRunDetail(msg: DashboardRunDetailRequest): Promise<void>;
+    /**
+     * Handle a dashboard.step.logs request.
+     * Looks up the step's log_path and reads content from LogStorage.
+     */
+    handleStepLogs(msg: DashboardStepLogsRequest): Promise<void>;
+    /**
+     * Handle a dashboard.payload request.
+     * Reads the webhook payload from log storage for the given runId.
+     */
+    handlePayload(msg: DashboardPayloadRequest): Promise<void>;
+    /**
+     * Handle a dashboard.orch.logs request.
+     * Reads orchestration + provisioning log files from LogStorage for the given run/job.
+     * Provisioning logs are returned with phase "provisioning" so the dashboard can
+     * render them in a separate collapsible section.
+     */
+    handleOrchLogs(msg: DashboardOrchLogsRequest): Promise<void>;
+    /**
+     * Handle a run.rerun.request.
+     * Delegates to the onRerun callback which invokes handleRerun from the rerun module.
+     *
+     * Resolution: prefer `msg.routingKey` (Phase F denormalization hint from
+     * Platform — `execution_runs.routing_key` mirror). The hint is the ONLY
+     * org context we have when the run row has been cold-archived out of PG,
+     * so consult sources/generic_webhook_sources directly. If the hint is
+     * absent, fall back to `resolveOrgForRun` against the warm PG row.
+     */
+    handleRerunRequest(msg: RunRerunRequest): Promise<void>;
+    /**
+     * Handle a run.cancel.request.
+     * Delegates to the onCancel callback which sends job.cancel to agents.
+     */
+    handleCancelRequest(msg: RunCancelRequest): Promise<void>;
+    /**
+     * Handle a dashboard.event-log.list request.
+     *
+     * Returns a paginated page of inbound webhook delivery rows owned by this
+     * orchestrator (`event_log` table) for the given org. Pagination uses an
+     * opaque cursor (received_at + id) so concurrent inserts don't shift pages.
+     *
+     * Filters: routingKey, event, status, fromTimestamp/toTimestamp,
+     * deliveryId substring. All optional.
+     */
+    handleEventLogList(msg: DashboardEventLogListRequest): Promise<void>;
+    /**
+     * Handle a dashboard.access-log.list request.
+     *
+     * Returns a paginated page of access_log rows for the given org. Used by
+     * the dashboard "Data access" tab to show who read what (and when).
+     *
+     * Every filter is optional; the orchestrator scopes on orgId then applies
+     * each supplied filter independently. Records its own access_log row
+     * under action='access_log.list.read' so there's a meta-audit of who
+     * looked at the audit log.
+     */
+    handleAccessLogList(msg: DashboardAccessLogListRequest): Promise<void>;
+    /**
+     * Handle a dashboard.event-log.detail request.
+     *
+     * Returns the metadata row only — the webhook body bytes stream over a
+     * separate chunked-WS path (`handleEventLogPayloadStream` below) so
+     * Platform never holds the full body in memory and the dashboard can
+     * render progress as bytes arrive. When `payload_omitted=true` the row's
+     * `payloadOmitted`/`payloadOmittedReason` fields tell the dashboard to
+     * skip issuing a stream request.
+     */
+    handleEventLogDetail(msg: DashboardEventLogDetailRequest): Promise<void>;
+    /**
+     * Handle a dashboard.event-log.payload.stream request.
+     *
+     * Reads the gzipped body from LogStorage, decompresses it, slices the
+     * decompressed bytes into 64 KiB chunks, base64-encodes each, and emits a
+     * sequence of `dashboard.event-log.payload.chunk` messages. The first
+     * chunk carries `totalBytes`; the last chunk carries `isLast=true`.
+     *
+     * The single audit row (`event_log.payload.read`) is written at the start
+     * of the stream — outcome `allowed` when the row exists and the body
+     * begins streaming, `not_found` / `denied` when the request resolves to
+     * an empty/error stream. Per-chunk audits would inflate the access-log
+     * volume without adding attribution detail.
+     *
+     * Pacing: a `setImmediate` yield between sends keeps the WS connection
+     * from saturating. For a 5 MB cap (the wishlist's worst case) this means
+     * ~80 yields per stream — negligible.
+     */
+    handleEventLogPayloadStream(msg: DashboardEventLogPayloadStreamRequest): Promise<void>;
+    /**
+     * Handle a run.manual_schedule.request.
+     * Delegates to the onManualSchedule callback which invokes handleManualSchedule.
+     */
+    handleManualScheduleRequest(msg: ManualScheduleRequest): Promise<void>;
+    /**
+     * Phase C cold-store fallback: fetch the run + its jobs + its steps
+     * from S3 when the PG copy has been archived. Bounded scan: stops at
+     * the warm cutoff (older entries don't exist in cold-store yet by
+     * construction). Each row is filtered by `run_id` because chunks
+     * span multiple runs.
+     */
+    private fetchArchivedRunDetail;
+}
+export {};
+//# sourceMappingURL=handler.d.ts.map

package/dist/db/client.d.ts

@@ -0,0 +1,13 @@
+import pg from 'pg';
+import { Kysely } from 'kysely';
+import { createPool as _createPool } from '@kici-dev/shared';
+import type { Database } from './types.js';
+/**
+ * Create PostgreSQL connection pool.
+ */
+export declare const createPool: typeof _createPool;
+/**
+ * Create Kysely database instance typed to the orchestrator schema.
+ */
+export declare function createDb(pool: pg.Pool): Kysely<Database>;
+//# sourceMappingURL=client.d.ts.map

package/dist/db/migration-provider.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Static migration provider for bundled builds.
+ *
+ * Rolldown doesn't support dynamic `import()` of migration files at runtime,
+ * so we statically import all migrations and provide them to Kysely's Migrator.
+ */
+import type { MigrationProvider } from 'kysely/migration';
+export declare function createMigrationProvider(): MigrationProvider;
+//# sourceMappingURL=migration-provider.d.ts.map

package/dist/db/migrations/001_initial.d.ts

@@ -0,0 +1,8 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<any>): Promise<void>;
+/**
+ * Rollback drops everything created above. Uses CASCADE on table drops to cut
+ * through the FK graph without relying on exact topological order.
+ */
+export declare function down(db: Kysely<any>): Promise<void>;
+//# sourceMappingURL=001_initial.d.ts.map

package/dist/db/migrations/002_config_versions_key_version.d.ts

@@ -0,0 +1,16 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add key_version column to config_versions so that sensitive-field encryption
+ * can be rotated via `kici-admin rotate-key`.
+ *
+ * Existing rows are backfilled to 1 via the DEFAULT clause (every historical
+ * row was encrypted under the first master-key generation). After rotation,
+ * `SharedConfigStore` writes the next integer (MAX(key_version) + 1) and
+ * stores the active generation alongside the ciphertext.
+ *
+ * No index is needed: rotation does a full-table scan; reads are by
+ * `version` primary key and never filter on `key_version`.
+ */
+export declare function up(db: Kysely<any>): Promise<void>;
+export declare function down(db: Kysely<any>): Promise<void>;
+//# sourceMappingURL=002_config_versions_key_version.d.ts.map