@kici-dev/orchestrator 0.4.0 → 0.5.0

package/dist/cluster/cluster-settings-reader.d.ts

@@ -1,9 +1,46 @@
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 /** Numeric columns on cluster_settings readable via {@link ClusterSettingsReader}. */
-export type ClusterNumberColumn = 'max_github_payload_bytes' | 'event_log_max_payload_bytes' | 'lock_file_max_bytes' | 'webhook_dedup_ttl_ms' | 'contributor_cache_ttl_ms' | 'event_router_event_ttl_seconds' | 'event_router_max_dispatch_attempts' | 'queue_max_depth' | 'reroute_flap_grace_ms' | 'max_fanout_hosts' | 'event_router_rate_limit_per_workflow_per_minute' | 'cache_max_tarball_bytes' | 'cache_ttl_days' | 'check_run_tracking_ttl_days' | 'concurrency_wait_timeout_ms' | 'agent_token_ttl_ms' | 'ownership_db_check_timeout_ms' | 'unroutable_grace_ms';
+export type ClusterNumberColumn = 'max_github_payload_bytes' | 'event_log_max_payload_bytes' | 'lock_file_max_bytes' | 'webhook_dedup_ttl_ms' | 'contributor_cache_ttl_ms' | 'event_router_event_ttl_seconds' | 'event_router_max_dispatch_attempts' | 'queue_max_depth' | 'reroute_flap_grace_ms' | 'max_fanout_hosts' | 'event_router_rate_limit_per_workflow_per_minute' | 'cache_max_tarball_bytes' | 'cache_ttl_days' | 'lockfile_cache_max' | 'lockfile_cache_max_bytes' | 'lockfile_cache_ttl_ms' | 'content_cache_max' | 'content_cache_max_bytes' | 'content_cache_ttl_ms' | 'global_eval_round_timeout_ms' | 'global_eval_candidate_timeout_ms' | 'global_eval_cache_max' | 'global_eval_wait_timeout_ms' | 'check_run_tracking_ttl_days' | 'concurrency_wait_timeout_ms' | 'agent_token_ttl_ms' | 'ownership_db_check_timeout_ms' | 'unroutable_grace_ms' | 'ingest_overflow_claim_timeout_ms';
 /** Text columns on cluster_settings readable via {@link ClusterSettingsReader}. */
 export type ClusterStringColumn = 'dashboard_verified_issuer';
+/** Boolean columns on cluster_settings readable via {@link ClusterSettingsReader}. */
+export type ClusterBooleanColumn = 'global_workflows_enabled';
+/**
+ * Ceiling for the three LRU entry-count knobs — `lockfile_cache_max`,
+ * `content_cache_max`, and `global_eval_cache_max`.
+ *
+ * This is a boot-safety bound, not a policy preference. The underlying LRU
+ * allocates its index arrays eagerly from `max` — several typed arrays plus the
+ * TTL and size arrays the caches ask for — so the cost is paid at construction
+ * with zero entries cached. Measured on the shipped version: an empty cache at
+ * `max` 5,000,000 costs ~191 MB, and at 5,000,000,000 the constructor throws
+ * `RangeError: Invalid array length`.
+ *
+ * That throw is what makes an unbounded knob dangerous rather than merely
+ * wasteful. All three caches are built inside `bootstrapOrchestrator`, so a bad
+ * stored value crashes the orchestrator before its admin API is listening —
+ * and the admin API is the only way `kici-admin cluster-settings` can reach the
+ * stored value. The knob would brick the very tool needed to un-brick it.
+ *
+ * 100,000 is 200x the shipped default of 500 and costs ~4 MB per empty cache,
+ * so it is far above any plausible operator setting while keeping boot bounded.
+ */
+export declare const CACHE_MAX_ENTRIES_CEILING = 100000;
+/**
+ * Bound a stored entry-count knob to something the LRU constructor survives.
+ *
+ * Applied at the read site rather than only at the write site, because the
+ * write-side validation cannot reach a value that is already in the database —
+ * set before the ceiling shipped, or written by any path other than the admin
+ * route. Clamping here is what actually guarantees a stored value cannot
+ * prevent boot.
+ *
+ * A value that is not a usable positive count (NaN, non-finite, below 1) falls
+ * back to the configured default rather than clamping to 1: a 1-entry cache
+ * thrashes silently, which is harder to diagnose than simply ignoring garbage.
+ */
+export declare function clampCacheMaxEntries(value: number, fallback: number): number;
 /**
  * A knob read that keeps "the operator never set this" separate from "we could
  * not read it".
@@ -64,6 +101,21 @@ export declare class ClusterSettingsReader {
      * An empty stored string is unset, matching {@link getString}.
      */
     tryGetString(column: ClusterStringColumn): Promise<ClusterSettingRead<string>>;
+    /**
+     * Resolve a fleet-wide boolean knob without collapsing a read failure into a
+     * default.
+     *
+     * There is deliberately no `getBoolean(column, fallback)` companion. The
+     * security gate that consumes this must tell the reader's outcomes apart
+     * itself: a stored `false` and a NULL both deny today, but they deny for
+     * different reasons, and `{ ok: false }` must deny regardless of what the
+     * configured default happens to be. A convenience wrapper that folded the
+     * failure into the default would be safe only for as long as that default
+     * stayed `false`. A caller that only needs a display value (the dashboard
+     * status badge) folds `{ ok: false }` into the default explicitly at its own
+     * site, where getting it wrong misreports a badge rather than opening a gate.
+     */
+    tryGetBoolean(column: ClusterBooleanColumn): Promise<ClusterSettingRead<boolean>>;
     /**
      * The cluster_settings row version last seen in the cache (0 if never loaded).
      *

package/dist/config.d.ts

@@ -56,9 +56,17 @@ declare const configSchema: z.ZodObject<{
     lockfileCacheMax: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     lockfileCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     lockfileCacheMaxBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    contentCacheMax: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    contentCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    contentCacheMaxBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    globalEvalRoundTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    globalEvalCandidateTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    globalEvalCacheMax: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    globalEvalWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueMaxDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     unroutableGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    globalWorkflowsEnabled: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>, z.ZodTransform<boolean, string | boolean>>;
     queueBackpressureThreshold: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     workerConcurrency: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     concurrencyWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -81,6 +89,7 @@ declare const configSchema: z.ZodObject<{
     ingestOverflowReplayIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     ingestOverflowReplayBatch: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     ingestOverflowMaxAttempts: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    ingestOverflowClaimTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteSpawnWindowMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteAckTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteMaxHops: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -250,9 +259,17 @@ export declare const packagingConfigSchema: z.ZodObject<{
     lockfileCacheMax: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     lockfileCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     lockfileCacheMaxBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    contentCacheMax: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    contentCacheTtlMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    contentCacheMaxBytes: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    globalEvalRoundTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    globalEvalCandidateTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    globalEvalCacheMax: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    globalEvalWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueMaxDepth: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     queueTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     unroutableGraceMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    globalWorkflowsEnabled: z.ZodPipe<z.ZodDefault<z.ZodUnion<readonly [z.ZodBoolean, z.ZodString]>>, z.ZodTransform<boolean, string | boolean>>;
     queueBackpressureThreshold: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     workerConcurrency: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     concurrencyWaitTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -275,6 +292,7 @@ export declare const packagingConfigSchema: z.ZodObject<{
     ingestOverflowReplayIntervalMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     ingestOverflowReplayBatch: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     ingestOverflowMaxAttempts: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
+    ingestOverflowClaimTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteSpawnWindowMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteAckTimeoutMs: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
     rerouteMaxHops: z.ZodDefault<z.ZodCoercedNumber<unknown>>;
@@ -477,9 +495,17 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     lockfileCacheMax: number;
     lockfileCacheTtlMs: number;
     lockfileCacheMaxBytes: number;
+    contentCacheMax: number;
+    contentCacheTtlMs: number;
+    contentCacheMaxBytes: number;
+    globalEvalRoundTimeoutMs: number;
+    globalEvalCandidateTimeoutMs: number;
+    globalEvalCacheMax: number;
+    globalEvalWaitTimeoutMs: number;
     queueMaxDepth: number;
     queueTimeoutMs: number;
     unroutableGraceMs: number;
+    globalWorkflowsEnabled: boolean;
     queueBackpressureThreshold: number;
     workerConcurrency: number;
     concurrencyWaitTimeoutMs: number;
@@ -499,6 +525,7 @@ export declare const envDef: import("@kici-dev/shared/env").DefineEnvResult<{
     ingestOverflowReplayIntervalMs: number;
     ingestOverflowReplayBatch: number;
     ingestOverflowMaxAttempts: number;
+    ingestOverflowClaimTimeoutMs: number;
     rerouteSpawnWindowMs: number;
     rerouteAckTimeoutMs: number;
     rerouteMaxHops: number;

package/dist/content-requirements-cache.d.ts

@@ -0,0 +1,55 @@
+/**
+ * Provider-agnostic LRU cache for source-file contents fetched at a ref.
+ *
+ * Wraps any {@link FileContentsFetcher} with an in-memory LRU cache keyed by
+ * `(provider, repo, sha, path)`. The key is content-addressable by
+ * construction: a commit SHA pins immutable bytes, so a cached entry for a
+ * `(repo, sha, path)` triple can never go stale within the SHA. When the caller
+ * passes a mutable ref (a branch name) instead of a SHA, staleness is bounded by
+ * the TTL, exactly as the lock-file cache handles the same case.
+ *
+ * Mirrors {@link ../lockfile-cache.ts LockFileCache}: same LRU + in-flight
+ * coalescing shape so N concurrent misses for one key run a single fetch.
+ */
+import type { FileContentsFetcher } from '@kici-dev/engine';
+/**
+ * One fetched file's presence + bytes. `present: true` with `bytes: undefined`
+ * is the size-limit case (the file exists but the provider returned no inline
+ * content, e.g. a GitHub file over 1 MiB) — callers MUST treat it as
+ * "content unavailable for matching", never as an absent or empty file.
+ */
+export interface FileContentEntry {
+    readonly present: boolean;
+    readonly bytes?: string;
+}
+export declare class ContentRequirementsCache {
+    private readonly cache;
+    private readonly inFlight;
+    private hits;
+    private misses;
+    constructor(options: {
+        max: number;
+        ttl: number;
+        maxBytes?: number;
+    });
+    /**
+     * Fetch a file's contents at a ref, using the provided fetcher and LRU
+     * caching. Each distinct `(provider, repo, sha, path)` is fetched at most
+     * once; concurrent misses coalesce onto one fetch.
+     *
+     * @param fetcher - Provider-specific file-contents fetcher.
+     * @param repo    - Provider repo identifier ("owner/repo").
+     * @param sha     - Git ref (commit SHA, or a branch/tag name).
+     * @param path    - Repo-relative file path.
+     */
+    get(fetcher: FileContentsFetcher, repo: string, sha: string, path: string): Promise<FileContentEntry>;
+    private fetchAndCache;
+    /** Cache statistics for metrics/monitoring. */
+    getStats(): {
+        hits: number;
+        misses: number;
+        size: number;
+        calculatedSize: number;
+    };
+}
+//# sourceMappingURL=content-requirements-cache.d.ts.map

package/dist/db/migrations/109_cluster_settings_cache_knobs.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=109_cluster_settings_cache_knobs.d.ts.map

package/dist/db/migrations/110_cluster_settings_global_eval_knobs.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=110_cluster_settings_global_eval_knobs.d.ts.map

package/dist/db/migrations/111_cluster_settings_global_eval_wait.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=111_cluster_settings_global_eval_wait.d.ts.map

package/dist/db/migrations/112_execution_runs_workflow_repo.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=112_execution_runs_workflow_repo.d.ts.map

package/dist/db/migrations/113_execution_runs_workflow_repo_index.d.ts

@@ -0,0 +1,30 @@
+import { type Kysely } from 'kysely';
+/**
+ * Add the partial index `idx_execution_runs_workflow_repo` on
+ * `execution_runs (workflow_repo_identifier) WHERE workflow_repo_identifier IS NOT NULL`.
+ *
+ * Matching a workflow registration to its runs keys on the repository that
+ * DEFINES the workflow — `workflow_repo_identifier ?? repo_identifier` — which
+ * the orchestrator expresses as
+ * `workflow_repo_identifier IN (…) OR (workflow_repo_identifier IS NULL AND repo_identifier IN (…))`
+ * (`registration/registration-run-match.ts`). The second arm rides
+ * `idx_execution_runs_repo` from migration 001; the first arm had no index at
+ * all, because migration 112 added the column without one. A planner cannot
+ * use an index for only half a disjunction, so the whole predicate degraded to
+ * a sequential scan over a table that grows with every run — on
+ * `dashboard.registrations.list`, which runs its grouped MAX on every list
+ * request.
+ *
+ * With both arms indexed the planner can BitmapOr them.
+ *
+ * Partial by design, and the partiality is what makes it cheap: the column is
+ * non-null only for a cross-repository organization-wide run, a small minority
+ * of rows, so the index stays a fraction of the table's size and skips every
+ * per-repository run. It also matches the predicate exactly — the first arm
+ * can never match a NULL row, since `NULL IN (…)` is never true.
+ *
+ * Idempotent: `IF NOT EXISTS` makes a re-run a no-op.
+ */
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=113_execution_runs_workflow_repo_index.d.ts.map

package/dist/db/migrations/114_ingest_queue_claim.d.ts

@@ -0,0 +1,4 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=114_ingest_queue_claim.d.ts.map

package/dist/db/migrations/115_global_workflows_cluster_switch.d.ts

@@ -0,0 +1,9 @@
+import { type Kysely } from 'kysely';
+export declare function up(db: Kysely<unknown>): Promise<void>;
+/**
+ * Restores the org column with its original NOT NULL DEFAULT false. A rollback
+ * cannot recover the per-org values the up-migration dropped — they are gone —
+ * so every org comes back at the opt-in default.
+ */
+export declare function down(db: Kysely<unknown>): Promise<void>;
+//# sourceMappingURL=115_global_workflows_cluster_switch.d.ts.map

package/dist/db/types.d.ts

@@ -352,6 +352,12 @@ export interface IngestOverflowBufferTable {
     status: Generated<string>;
     /** Last replay error, or null. */
     last_error: string | null;
+    /**
+     * When the row moved `buffered` → `replaying`; null while it is buffered.
+     * Separate from `captured_at` (which orders the FIFO drain) so a long-buffered
+     * row is not reclaimed the instant a worker picks it up.
+     */
+    claimed_at: ColumnType<Date | null, Date | null | undefined, Date | null>;
 }
 export type DispatchQueueItem = Selectable<DispatchQueueTable>;
 export type NewDispatchQueueItem = Insertable<DispatchQueueTable>;
@@ -471,6 +477,20 @@ export interface ExecutionRunTable {
      * when resolving the actor to a KiCI user.
      */
     trigger_actor_user_id: string | null;
+    /**
+     * The repository that DEFINES this run's workflow, when that is not the
+     * repository the run acted on.
+     *
+     * `repo_identifier` is the repository the run acted on and whose code its
+     * jobs check out. For an organization-wide workflow dispatched against
+     * another repository, the workflow was authored somewhere else, and that
+     * authoring repository is recorded here. NULL means the two are the same —
+     * true of every per-repository run.
+     *
+     * Read by the rerun path, which must resolve the workflow from the
+     * repository that defines it rather than from the one it ran against.
+     */
+    workflow_repo_identifier: string | null;
     /** Human-readable reason why the run failed (null for non-failed runs). */
     failure_reason: string | null;
     /**
@@ -1514,8 +1534,6 @@ export interface OrgSettingsRepoPatternEntry {
 export interface OrgSettingsTable {
     /** Customer/org identifier (primary key) */
     customer_id: string;
-    /** Whether global workflows are enabled for this org */
-    global_workflows_enabled: ColumnType<boolean, boolean | undefined, boolean>;
     /** Repos allowed to author global workflows (null = any repo can author) */
     global_workflow_allowed_repos: ColumnType<OrgSettingsRepoPatternEntry[] | null, OrgSettingsRepoPatternEntry[] | null | undefined | string, OrgSettingsRepoPatternEntry[] | null | string>;
     /** Repos with elevated trust for global workflow execution (null = none) */
@@ -1710,6 +1728,32 @@ export interface ClusterSettingsTable {
     event_router_rate_limit_per_workflow_per_minute: ColumnType<number | null, number | null | undefined, number | null>;
     cache_max_tarball_bytes: ColumnType<string | null, number | null | undefined, number | null>;
     cache_ttl_days: ColumnType<number | null, number | null | undefined, number | null>;
+    /** LRU entry ceiling for the lock-file cache. NULL ⇒ the configured default. Applies at next restart. */
+    lockfile_cache_max: ColumnType<string | null, number | null | undefined, number | null>;
+    /** Byte ceiling for the lock-file cache. NULL ⇒ the configured default. Applies at next restart. */
+    lockfile_cache_max_bytes: ColumnType<string | null, number | null | undefined, number | null>;
+    /** Entry TTL (ms) for the lock-file cache. NULL ⇒ the configured default. Applies at next restart. */
+    lockfile_cache_ttl_ms: ColumnType<string | null, number | null | undefined, number | null>;
+    /** LRU entry ceiling for the Tier-1 content cache. NULL ⇒ the configured default. Applies at next restart. */
+    content_cache_max: ColumnType<string | null, number | null | undefined, number | null>;
+    /** Byte ceiling for the Tier-1 content cache. NULL ⇒ the configured default. Applies at next restart. */
+    content_cache_max_bytes: ColumnType<string | null, number | null | undefined, number | null>;
+    /** Entry TTL (ms) for the Tier-1 content cache. NULL ⇒ the configured default. Applies at next restart. */
+    content_cache_ttl_ms: ColumnType<string | null, number | null | undefined, number | null>;
+    /** Wall-clock budget (ms) for a whole Tier-2 global eval round. NULL ⇒ the configured default. Read per round. */
+    global_eval_round_timeout_ms: ColumnType<string | null, number | null | undefined, number | null>;
+    /** Wall-clock budget (ms) for one candidate inside a round. NULL ⇒ the configured default. Read per round. */
+    global_eval_candidate_timeout_ms: ColumnType<string | null, number | null | undefined, number | null>;
+    /** LRU entry ceiling for the round-result cache. NULL ⇒ the configured default. Applies at next restart. */
+    global_eval_cache_max: ColumnType<string | null, number | null | undefined, number | null>;
+    /**
+     * Orchestrator-side ceiling (ms) on waiting for one eval round to settle.
+     * Distinct from the two budgets above, which the agent enforces on itself: a
+     * round that never reaches an agent — or an agent that wedges before its own
+     * budget starts — is only bounded here. NULL ⇒ the configured default. Read
+     * per round.
+     */
+    global_eval_wait_timeout_ms: ColumnType<string | null, number | null | undefined, number | null>;
     /**
      * Retention window in days for `check_run_tracking` rows. The hourly cleanup
      * sweep deletes rows untouched for longer than this; 0 disables the sweep.
@@ -1722,6 +1766,20 @@ export interface ClusterSettingsTable {
      * 0 disables fast-fail, leaving `queue_timeout_ms` as the only backstop.
      */
     unroutable_grace_ms: ColumnType<number | null, number | null | undefined, number | null>;
+    /**
+     * Fleet-wide master switch for global workflows. NULL ⇒ the orchestrator's
+     * configured default (`KICI_GLOBAL_WORKFLOWS_ENABLED`, default false). Read
+     * per policy decision through `ClusterSettingsReader.tryGetBoolean`, which
+     * reports an unreadable row separately so the gate can fail closed.
+     */
+    global_workflows_enabled: ColumnType<boolean | null, boolean | null | undefined, boolean | null>;
+    /**
+     * How long a `replaying` claim on `ingest_overflow_buffer` may stand before
+     * the drain pass reclaims the row for another worker. NULL ⇒ the
+     * orchestrator's configured default. Must exceed the longest a single
+     * delivery's pipeline can legitimately run.
+     */
+    ingest_overflow_claim_timeout_ms: ColumnType<number | null, number | null | undefined, number | null>;
     concurrency_wait_timeout_ms: ColumnType<string | null, number | null | undefined, number | null>;
     agent_token_ttl_ms: ColumnType<string | null, number | null | undefined, number | null>;
     /**

package/dist/metrics/agent-metrics-aggregator.d.ts

@@ -47,10 +47,10 @@ export declare class AgentMetricsAggregator {
     private store;
     private defaultRetentionMs;
     /**
-     * Optional lookup: agentId → scaler backend name (e.g. `container`,
+     * Optional lookup: agentId → scaler backend type (e.g. `container`,
      * `firecracker`, `bare-metal`). Returning null marks the agent as
      * static / stateful — we then stamp the `scaler` label as `'stateful'`.
-     * Wired from ScalerManager.getBackendName in production. Tests can
+     * Wired from ScalerManager.getBackendType in production. Tests can
      * leave it undefined; in that case the `scaler` label is omitted.
      */
     private readonly getScalerForAgent?;

package/dist/metrics/prometheus.d.ts

@@ -93,6 +93,13 @@ export declare const ingestShedTotal: import("@opentelemetry/api").Counter<impor
 export declare const stateReplayBreakerTripsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /** Total webhook-ingest admissions granted. */
 export declare const ingestAdmittedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Webhook pipelines that threw. Labels:
+ * - phase: post_ack — the delivery was already acknowledged, so the failure
+ *   could not be reported in the response and is only visible here, in the
+ *   event log, and in the queue row.
+ */
+export declare const webhookPipelineFailuresTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /** Set the current buffered-row depth (called by the buffer + replayer). */
 export declare function setIngestOverflowBuffered(value: number): void;
 /** Current buffered-row depth (test helper). */
@@ -291,6 +298,58 @@ export declare const universalGitRegistrationErrorsTotal: import("@opentelemetry
  *   'id_mismatch' (a username-matched link has a different provider_user_id)
  */
 export declare const trustMatchRefusedNoIdTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Candidates handed to a global eval round.
+ *
+ * Equal to `sum(kici_orch_global_eval_verdicts_total)` by construction: every
+ * candidate receives exactly one verdict, including on the fail-closed path
+ * where the round never runs. Kept as its own series because it is the natural
+ * top-line rate and the denominator the outcome breakdown divides — a
+ * divergence between the two would be a bug in the round, never a condition an
+ * operator should watch for.
+ */
+export declare const globalEvalCandidatesTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Per-candidate verdicts a global eval round produced.
+ *
+ * Labels:
+ * - outcome: run (the filter admitted it) | filtered (the filter excluded it) | indeterminate (the round could not decide — a failed round, a budget breach, or a verdict that never arrived)
+ */
+export declare const globalEvalVerdictsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Wall-clock duration of one dispatched global eval round, from dispatch to
+ * settled verdicts. A cache hit records nothing — it never dispatches a round.
+ *
+ * Buckets: 1s to 10min, covering a fast round through the default 120s agent
+ * budget and the 240s orchestrator wait ceiling.
+ *
+ * Labels:
+ * - result: success (the round settled) | error (dispatch rejected, the wait ceiling fired, or the round decided nothing)
+ */
+export declare const globalEvalRoundDurationSeconds: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/**
+ * Jobs a round's `DynamicJobFn` generators produced, summed over the round's
+ * candidates. Recorded once per settled round, including zero.
+ *
+ * Buckets cover the common small fan-outs through a large matrix expansion.
+ */
+export declare const globalEvalJobsGenerated: import("@opentelemetry/api").Histogram<import("@opentelemetry/api").Attributes>;
+/**
+ * Global eval round cache lookups by outcome.
+ *
+ * Three outcomes, not two. An input that cannot be serialized yields no cache
+ * key at all, so it never reaches the cache and registers neither a hit nor a
+ * miss — counting only hits and misses would drop those lookups from the
+ * denominator and make the hit rate read higher than it is.
+ *
+ * Expect a hit rate near zero on a healthy cluster: the key covers the whole
+ * event, so every real push is a miss by construction. This cache is a
+ * redelivery guard, not a steady-state optimization.
+ *
+ * Labels:
+ * - result: hit | miss | unkeyable (the round input could not be serialized)
+ */
+export declare const globalEvalCacheLookupsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Internal events delivered to all matching workflows successfully (after the
  * lease commits processed=true).

package/dist/orchestrator-core.d.ts

@@ -19,6 +19,7 @@ import { EventLogWriter } from './webhook/event-log.js';
 import { AccessLogWriter } from './audit/access-log.js';
 import { Dispatcher } from './agent/dispatcher.js';
 import { LockFileCache } from './lockfile-cache.js';
+import { ContentRequirementsCache } from './content-requirements-cache.js';
 import { DedupCache } from './webhook/dedup.js';
 import { ObserverRegistry } from './ws/observer-registry.js';
 import { IngestAdmissionController } from './webhook/ingest-admission.js';
@@ -34,7 +35,7 @@ import type { ScalerConfig } from './scaler/index.js';
 import type { CacheStorage } from './storage/index.js';
 import { type ProvenanceTrustRoot } from './provenance/trust-root.js';
 import { type ResolvedDashboardEncryptionKey } from './secrets/dashboard-encryption-key.js';
-import { SourceCache, BuildCoordinator, DepCache, UserCache, DispatchCacheRefTracker, PendingBuildTracker, PendingInitTracker, PendingDynamicTracker } from './cache/index.js';
+import { SourceCache, BuildCoordinator, DepCache, UserCache, DispatchCacheRefTracker, PendingBuildTracker, PendingInitTracker, PendingDynamicTracker, PendingGlobalEvalTracker, GlobalEvalRoundCache } from './cache/index.js';
 import { ArtifactStore } from './artifacts/artifact-store.js';
 import { CheckRunReporter } from './reporting/check-run-reporter.js';
 import { StepLogBuffer } from './reporting/step-log-buffer.js';
@@ -98,6 +99,7 @@ export interface OrchestratorSubsystems {
     pendingBuilds: PendingBuildTracker | undefined;
     pendingInits: PendingInitTracker;
     pendingDynamics: PendingDynamicTracker;
+    pendingGlobalEvals: PendingGlobalEvalTracker;
     checkRunReporter: CheckRunReporter;
     stepLogBuffer: StepLogBuffer;
     sourceLocationStore: SourceLocationStore;
@@ -119,6 +121,8 @@ export interface OrchestratorSubsystems {
     tokenStore: AgentTokenStore;
     ownershipTracker: OwnershipTracker;
     lockFileCache: LockFileCache;
+    contentRequirementsCache: ContentRequirementsCache;
+    globalEvalCache: GlobalEvalRoundCache;
     dedup: DedupCache;
     eventRouter: EventRouter;
     /**
@@ -129,6 +133,13 @@ export interface OrchestratorSubsystems {
     eventStore: EventStore;
     eventEmitter: EventEmitter;
     genericSourceManager: GenericSourceManager;
+    /**
+     * Re-register a generic source's provider bundle from its database row.
+     * The webhook pipeline calls it on an exact registry miss so the read side
+     * settles against server truth rather than a stand-in bundle. Shared by the
+     * relay path (server.ts) and the direct-ingress path (app.ts).
+     */
+    ensureProviderBundle: (routingKey: string) => Promise<boolean>;
     trustStore: TrustStore;
     registrationStore: RegistrationStore;
     registrationIndex: RegistrationIndex;

package/dist/pipeline/content-filter.d.ts

@@ -0,0 +1,71 @@
+/**
+ * Tier-1 declarative content-requirements filter (execution-purity model, Part B).
+ *
+ * After Tier-0 trigger matching selects candidate workflows, this step fetches
+ * the source files each candidate's `requires` names — once per distinct
+ * `(repo, sha, path)` via the LRU cache — evaluates the (pure DATA) requirements
+ * with the engine matcher, and drops any candidate that FAILS or is
+ * INDETERMINATE before dispatch. No author code is executed: `requires` is a
+ * declarative query the orchestrator interprets, which is what keeps content
+ * filtering inside the orchestrator under the purity model.
+ *
+ * Fail-visible: a dropped candidate (definite negative, oversize/unparseable
+ * content, a fetch error, or no fetcher/cache available) is logged with the
+ * concrete reason. An indeterminate file NEVER passes silently.
+ */
+import type { FileContentsFetcher, LockContentRequirement } from '@kici-dev/engine';
+import type { ContentRequirementsCache } from '../content-requirements-cache.js';
+/** A workflow candidate carrying the `requires` of the trigger that matched the event. */
+export interface ContentFilterCandidate {
+    readonly name: string;
+    readonly requires?: readonly LockContentRequirement[];
+}
+/** The event the requirements are evaluated against: source repo + ref to fetch files at. */
+export interface ContentFilterEvent {
+    /** Provider repo identifier ("owner/repo"). */
+    readonly repo: string;
+    /** Git ref (commit SHA, or branch/tag) at which files are read. */
+    readonly sha: string;
+}
+export interface ContentFilterOptions {
+    /** Per-delivery file-contents fetcher; `undefined` when the provider has none. */
+    readonly fetcher: FileContentsFetcher | undefined;
+    /** Shared LRU cache; `undefined` when the deployment did not wire one. */
+    readonly cache: ContentRequirementsCache | undefined;
+    /** Delivery id for log correlation. */
+    readonly deliveryId?: string;
+}
+/**
+ * One dropped candidate.
+ *
+ * `indeterminate` separates the two reasons a drop happens, which mean opposite
+ * things to a workflow author: a definite content mismatch is the requirement
+ * doing its job, while an unreadable file, a fetch error, or a provider with no
+ * file-contents fetcher is the requirement never having been evaluated at all.
+ * Both drop the candidate — the filter is fail-visible, so an unevaluable file
+ * never passes — but a trace that renders the second as "excluded" tells an
+ * author their requirement said no when nothing ever read it.
+ */
+export interface DroppedCandidate {
+    readonly name: string;
+    readonly reason: string;
+    /** True when the requirement could not be evaluated, rather than evaluating to false. */
+    readonly indeterminate?: boolean;
+}
+export interface ContentFilterResult<C extends ContentFilterCandidate> {
+    readonly survivors: C[];
+    readonly dropped: DroppedCandidate[];
+}
+/**
+ * Filter candidates by their declarative content requirements.
+ *
+ * Gathers each distinct `(repo, sha, path)` once via the cache, evaluates every
+ * candidate's `requires`, and returns the survivors (pass) split from the
+ * dropped (fail / indeterminate, each logged with its reason). A candidate with
+ * no `requires` always survives without any fetch (the fast path — like an empty
+ * `paths` filter). When a candidate has `requires` but no fetcher/cache is
+ * available, it is dropped as indeterminate (fail-visible), never dispatched
+ * unfiltered.
+ */
+export declare function filterByContentRequirements<C extends ContentFilterCandidate>(candidates: readonly C[], event: ContentFilterEvent, opts: ContentFilterOptions): Promise<ContentFilterResult<C>>;
+//# sourceMappingURL=content-filter.d.ts.map