@kici-dev/orchestrator 0.4.0 → 0.6.0

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

@@ -9,8 +9,8 @@
  * make Mimir cardinality grow with the number of agents that have ever
  * existed (every ephemeral firecracker microVM minted a fresh ID), which
  * is unbounded. The caller-side dashboard filters by `scaler` instead,
- * which has a fixed enum of values (`stateful` / `container` /
- * `firecracker` / `bare-metal`).
+ * which has a fixed enum of values (`stateful`, plus every
+ * `ScalerBackendType`).
  *
  * Aggregation rules per metric kind:
  *   - counter / upDownCounter / gauge → SUM across agents in the pool
@@ -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

@@ -34,14 +34,97 @@ interface ScalerUsageRow {
  * the on-disk ledger snapshot. Per-scaler rows omit `machinePool`.
  */
 export declare function setScalerUsageBreakdown(rows: ScalerUsageRow[]): void;
+interface WarmPoolGaugeRow {
+    /** Operator-chosen scaler name that owns the pool. */
+    scaler: string;
+    /** Normalized label set the pool keeps agents ready for. */
+    labelSet: string;
+    target: number;
+    ready: number;
+    inFlight: number;
+}
+/**
+ * Replace the current warm-pool fill state.
+ *
+ * Called by ScalerManager after each warm-pool tick and after a config reload,
+ * so the gauges follow the pool rather than the scrape.
+ */
+export declare function setWarmPoolGauges(rows: WarmPoolGaugeRow[]): void;
+/**
+ * Total warm-pool spawns started.
+ * Labels:
+ * - scaler: operator-chosen scaler name that owns the pool.
+ */
+export declare const scalerWarmPoolSpawnsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Record a warm-pool spawn starting. */
+export declare function incWarmPoolSpawns(scaler: string): void;
+/**
+ * Total warm-pool agents destroyed as surplus to the pool's target — either
+ * past `idleTimeoutSeconds`, or immediately when a config reload lowers the
+ * target. Both paths run through the same destroy callback, so the counter
+ * covers both.
+ * Labels:
+ * - scaler: operator-chosen scaler name that owns the pool.
+ */
+export declare const scalerWarmPoolReapedTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/** Record a warm-pool agent being destroyed. */
+export declare function incWarmPoolReaped(scaler: string): void;
 /** Increment the spawn-refusal counter (called by ScalerManager when a request fails the cap check). */
 export declare function incScalerSpawnRefusals(): void;
+/**
+ * Why an event scaler's cluster-wide cap check failed.
+ *
+ * `reason` label for `kici_orch_scaler_cap_lock_failures_total`. The two are a
+ * different fault with a different operator response, so they must not share a
+ * series any more than either may share one with a plain capacity refusal.
+ * - `contended` — the advisory lock was still held when the wait budget
+ *   expired. The database is healthy; several coordinators are scaling one hot
+ *   scaler at once. Raise the scaler's cap, or the wait budget.
+ * - `unreachable` — the cap could not be evaluated at all (connection lost,
+ *   statement timeout, schema error). Event autoscaling is stalled on the
+ *   database and no cap arithmetic is happening anywhere.
+ */
+export declare const ScalerCapLockFailureReason: {
+    readonly Contended: 'contended';
+    readonly Unreachable: 'unreachable';
+};
+export type ScalerCapLockFailureReason = (typeof ScalerCapLockFailureReason)[keyof typeof ScalerCapLockFailureReason];
+/**
+ * Total event-scaler cluster-wide cap checks that failed, so their spawn was
+ * refused without the cap ever being evaluated.
+ *
+ * Deliberately NOT folded into `kici_orch_scaler_spawn_refusals_total`: that
+ * series means "the cluster is full", and the operator response is to add
+ * capacity or raise a cap. This one means the cap could not be evaluated, so
+ * event spawns fail closed for a reason that has nothing to do with capacity.
+ * Labels:
+ * - reason: contended (the lock wait budget expired) | unreachable (the cap could not be evaluated at all)
+ */
+export declare const scalerCapLockFailuresTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Record `count` pending jobs re-driven through the scaler by `trigger`
  * (`hook` = capacity-freed callback, `sweep` = leader-gated backstop).
  * Called by the dispatcher's metrics facade.
  */
 export declare function incScalerRedispatch(trigger: ScalerRedispatchTrigger, count: number): void;
+/** Record a scale-up event emitted for `scaler`. */
+export declare function incScalerScaleUpEmitted(scaler: string): void;
+/** Record a scale-down event emitted for `scaler` with the teardown `reason`. */
+export declare function incScalerScaleDownEmitted(scaler: string, reason: string): void;
+/** Record an event-scaler provision that timed out before its agent registered. */
+export declare function incScalerExternalProvisionTimeout(scaler: string): void;
+/** Record an adoption lookup that could not reach its spawn record. */
+export declare function incScalerAdoptionLookupFailure(): void;
+/** Set the current count of in-flight (provisioning + active) external agents for `scaler`. */
+export declare function setScalerExternalProvisioningActive(scaler: string, count: number): void;
+/**
+ * Set how many event-scaler provisions the leader has been unable to see an
+ * agent for, for at least the flap grace. Zero on every non-leader, and on a
+ * leader whose sweep is blocked.
+ */
+export declare function setScalerReapUnseenProvisions(count: number): void;
+/** Set whether this coordinator's provision reaper is standing down (1) or sweeping (0). */
+export declare function setScalerReapBlocked(blocked: boolean): void;
 /**
  * Merge current per-label counts with explicit `0`s for previously-seen labels
  * whose queue has drained. Mutates `everSeen` to include the current labels.
@@ -93,6 +176,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). */
@@ -121,13 +211,27 @@ export declare const webhooksProcessedTotal: import("@opentelemetry/api").Counte
 /**
  * Org trust-policy gate decisions.
  * Labels:
- * - arm: which policy arm decided — workflow_modification | fork_pr | unknown_contributor | none (the PR passed)
- * - action: pass | hold | reject
+ * - arm: which policy arm decided — fork_pr | none (the verdict carried no reason)
+ * - action: pass | ignore | hold | reject
  *
  * Incremented once per evaluated PR event, including passes, so the ratio of
  * gated to ungated PRs is visible rather than only the gated ones.
  */
 export declare const trustPolicyDecisionsTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Fork pull-request events dropped by the org fork policy before any run row,
+ * check status, or job dispatch existed.
+ * Labels:
+ * - provider: the inbound delivery's provider (github, …)
+ *
+ * @conditionallyEmitted An org that does not ignore fork PRs emits no series.
+ *
+ * Distinct from `kici_orch_trust_policy_decisions_total{action="ignore"}`,
+ * which counts the verdict wherever it is reached: this counts the drop the
+ * ingest path actually performed, so a verdict that stopped being enforced
+ * shows as a divergence between the two rather than as silence.
+ */
+export declare const forkEventsIgnoredTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Duration of trigger matching operations (lock file evaluation).
  * Buckets: 1ms to 5s covering fast rejects through complex evaluations.
@@ -221,7 +325,7 @@ export type ScalerSpawnFailureBound = (typeof ScalerSpawnFailureBound)[keyof typ
 /**
  * Total scaler agent spawn failures.
  * Labels:
- * - backend: scaler backend type (bare-metal | container | firecracker | unknown)
+ * - backend: scaler backend type (bare-metal | container | event | firecracker | unknown)
  * - bound: true (job-bound spawn) | false (warm-pool/unbound)
  */
 export declare const scalerSpawnFailuresTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
@@ -291,6 +395,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).
@@ -312,6 +468,17 @@ export declare const eventRetryTotal: import("@opentelemetry/api").Counter<impor
  * - reason: why the event was DLQ'd (exhausted_retries)
  */
 export declare const eventDlqTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
+/**
+ * Startup catch-up scans that threw. Emits no labels.
+ *
+ * The scan recovers the internal-event backlog a restart left behind, and it
+ * runs behind a boot latch that the composition root resolves after startup
+ * continues — so a failure cannot fail the bootstrap and is otherwise invisible
+ * until the backlog quietly ages into the DLQ. This counter is what an alert
+ * fires on; the accompanying `Deferred catch-up scan failed` log line carries
+ * the reason.
+ */
+export declare const eventCatchUpFailuresTotal: import("@opentelemetry/api").Counter<import("@opentelemetry/api").Attributes>;
 /**
  * Dispatch leases that timed out before the holding node finalised them
  * (signals a node crash mid-dispatch). Emits no labels.

package/dist/oidc/oidc-mint-registration.d.ts

@@ -56,9 +56,13 @@ export interface OidcMintRegistrationInput {
     };
     db: Kysely<Database>;
     orchestratorId: string;
-    testMode: boolean;
-    testMintDeferAudience?: string;
-    testMintRejectAudience?: string;
+    /**
+     * Test-only fault-injection predicate forwarded to the relay mint handler,
+     * supplied only by the build-time test double. Only ever defers — the
+     * anti-forgery choke point is preserved. Undefined (the shipped default) means
+     * no fault injection.
+     */
+    initialMintFault?: (audience: string) => boolean;
 }
 /** Decide which mint handler (if any) backs `OIDC_TOKEN_REQUEST_METHOD`. */
 export declare function selectOidcMintRegistration(input: OidcMintRegistrationInput): OidcMintRegistration | undefined;

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';
@@ -28,21 +29,23 @@ import { IngestOverflowBuffer } from './webhook/ingest-overflow-buffer.js';
 import { IngestOverflowReplayer } from './webhook/ingest-overflow-replayer.js';
 import { AgentMetricsAggregator } from './metrics/agent-metrics-aggregator.js';
 import { SourceLocationStore } from './app.js';
-import { ExecutionJobStatus, type LabelMatcher, type PeerHeartbeat, type PeerLogsCollectRequest, type PeerToPeerMessage, type ResolvedSandboxGrant } from '@kici-dev/engine';
+import { ExecutionJobStatus, type PeerHeartbeat, type PeerLogsCollectRequest, type PeerToPeerMessage, type InvokeResult } from '@kici-dev/engine';
 import { ScalerManager } from './scaler/index.js';
 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 type { ProcessingDeps } from './pipeline/processor.js';
+import type { InvokeGateDeps, SummonArgs, SummonedRun } from './pipeline/invoke-gate.js';
 import { StepLogBuffer } from './reporting/step-log-buffer.js';
 import { type LogStorage } from './reporting/log-storage.js';
 import { ExecutionTracker, type ExecutionTrackerDeps } from './reporting/execution-tracker.js';
 import { LogWriter } from './reporting/log-writer.js';
 import { type NormalizedLogChunk } from './reporting/log-chunk-sink.js';
-import { PeerRegistry, PeerClient, createPeerHandler, RaftNode, OrphanRecovery, RunCoordinator } from './cluster/index.js';
+import { PeerRegistry, PeerClient, createPeerHandler, RaftNode, OrphanRecovery, RunCoordinator, PlanHeadroomStore } from './cluster/index.js';
 import { SourceStore, SourceManager } from './sources/index.js';
 import { PgSecretStore, AuditLogger, SecretResolver } from './secrets/index.js';
 import type { SecretStore } from '@kici-dev/engine';
@@ -50,11 +53,13 @@ import type { AdminRouteDeps } from './routes/admin.js';
 import { AgentTokenStore } from './agent/token-store.js';
 import { OwnershipTracker } from './agent/ownership-tracker.js';
 import { EventStore } from './events/event-store.js';
-import { EventRouter } from './events/event-router.js';
+import { EventRouter, type EventMatchContext } from './events/event-router.js';
 import { EventEmitter } from './events/event-emitter.js';
 import { TrustStore } from './events/trust-store.js';
+import type { OrchestratorFaultInjection } from './testing/fault-injection.js';
 import { GenericSourceManager } from './webhook/generic-sources.js';
 import { GenericSourcesChangeListener } from './webhook/generic-sources-listener.js';
+import { DashboardWritePolicyChangeListener } from './policy/dashboard-write-policy-listener.js';
 import { RegistrationStore } from './registration/registration-store.js';
 import { RegistrationIndex } from './registration/registration-index.js';
 import { CronScheduler } from './cron/cron-scheduler.js';
@@ -98,6 +103,7 @@ export interface OrchestratorSubsystems {
     pendingBuilds: PendingBuildTracker | undefined;
     pendingInits: PendingInitTracker;
     pendingDynamics: PendingDynamicTracker;
+    pendingGlobalEvals: PendingGlobalEvalTracker;
     checkRunReporter: CheckRunReporter;
     stepLogBuffer: StepLogBuffer;
     sourceLocationStore: SourceLocationStore;
@@ -119,8 +125,12 @@ export interface OrchestratorSubsystems {
     tokenStore: AgentTokenStore;
     ownershipTracker: OwnershipTracker;
     lockFileCache: LockFileCache;
+    contentRequirementsCache: ContentRequirementsCache;
+    globalEvalCache: GlobalEvalRoundCache;
     dedup: DedupCache;
     eventRouter: EventRouter;
+    /** Invoke-gate dependencies (summon callback + chain-depth bound). */
+    invokeGateDeps: InvokeGateDeps;
     /**
      * Event store for custom internal events (system + custom). Exposed
      * here so the dashboard handler can serve the per-org DLQ surface
@@ -129,6 +139,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;
@@ -142,6 +159,10 @@ export interface OrchestratorSubsystems {
     getLocalInventory: () => Omit<PeerHeartbeat, 'type'>;
     broadcastHeartbeatToAllPeers: () => void;
     broadcastAgentTokenRevoke: (tokenId: string) => void;
+    /** Platform-owned worker-ceiling cache, read by the peer-handler admission gate. */
+    planHeadroomStore: PlanHeadroomStore;
+    /** Late-bind the coordinator's cluster.membership reporter (see ClusterInfra). */
+    setMembershipReporter: (report: () => void) => void;
     joinHandler: JoinHandler;
     configReloader: ConfigReloader;
     localConfigVersion: number;
@@ -153,6 +174,12 @@ export interface OrchestratorSubsystems {
      * Platform when a generic source is added/removed at runtime.
      */
     genericSourcesChangeListener: GenericSourcesChangeListener;
+    /**
+     * Dashboard-write policy hot-reload listener. Keeps every coordinator's
+     * cached policy map — and the capability snapshot it advertises to the
+     * control plane — in step with a `kici-admin` write served by any peer.
+     */
+    dashboardWritePolicyChangeListener: DashboardWritePolicyChangeListener;
     /** Inbound webhook delivery log writer (event_log table + object-storage payloads). */
     eventLogWriter: EventLogWriter;
     /** Access log writer (read + mutation attribution for dashboard + admin). */
@@ -193,6 +220,17 @@ export interface OrchestratorSubsystems {
     ingestOverflowBuffer: IngestOverflowBuffer;
     /** Background replayer draining the overflow buffer once capacity recovers. */
     ingestOverflowReplayer: IngestOverflowReplayer;
+    /**
+     * The live direct-ingress `ProcessingDeps` bag, assembled inside `createApp`.
+     *
+     * A mode hook that has to resume a held run needs the same bag the pipeline
+     * that created the hold used — otherwise the resume runs against a second,
+     * hand-assembled bag that can silently diverge from it. `createApp` runs
+     * AFTER `onSubsystemsReady`, so this throws until it has, which is why every
+     * caller must invoke it lazily (inside a release callback, never at wiring
+     * time).
+     */
+    buildProcessingDeps: () => ProcessingDeps;
 }
 /**
  * Mode-specific hooks injected by each entry point.
@@ -262,22 +300,6 @@ export interface OrchestratorHooks {
  * are skipped here — group fan-in is resolved separately by the scheduler.
  */
 export declare function upstreamBaseNamesFromNeeds(needs: unknown): string[];
-/**
- * Partition a lock job's `runsOn` / `excludeLabels` matchers into exact label
- * strings and regex patterns for internal-event (cron / `ctx.emit`) dispatch.
- * Lock jobs carry `runsOn` as `LabelMatcher[]`; the coordinator routing and the
- * direct dispatcher both need exact labels for the indexed/SQL fast path and
- * regex patterns as a separate JS post-filter — never the raw matcher objects.
- */
-export declare function internalJobRunsOnSelectors(job: {
-    runsOn?: readonly LabelMatcher[];
-    excludeLabels?: readonly LabelMatcher[];
-}): {
-    runsOnLabels: string[];
-    runsOnPatterns: LabelMatcher[];
-    excludeLabels: string[];
-    excludePatterns: LabelMatcher[];
-};
 /**
  * Parse an `execution_jobs.outputs` cell (string JSON or object) to a plain
  * object, or null when empty / unparseable.
@@ -308,6 +330,22 @@ export declare function buildUpstreamStatusesByBase(rows: Array<{
     job_name: string;
     status?: string | null;
 }>): Record<string, ExecutionJobStatus> | undefined;
+/**
+ * For each declared need that names an invoke gate, gather its per-run results
+ * from the gate's proxy children — `{ repo, workflow, runId, status, outputs }`,
+ * one entry per proxy. `outputs` is the proxy's non-secret mirrored outputs (the
+ * same `execution_jobs.outputs` cell `mirrorSummonedRunOntoProxy` writes); a
+ * repo's secret outputs live in `run_secret_outputs` and are never read here.
+ * Keyed by gate name; a gate that summoned zero subscribers yields an empty
+ * array (so `.result` stays an `InvokeResult[]`), while a declared need that is
+ * a regular job (no gate row) yields no key.
+ *
+ * Shared by both `ctx.needs['<gate>'].result` construction paths: the
+ * DynamicJobFn generator (via `gatherUpstreamSnapshot`) and a standard
+ * `run:`/step job (via `mergeUpstreamOutputs` → the `upstreamInvokeResults`
+ * dispatch field).
+ */
+export declare function gatherInvokeResults(db: Kysely<Database>, runId: string, gateNames: readonly string[]): Promise<Record<string, InvokeResult[]>>;
 /**
  * Fold a `runsOnAll` upstream's host children into the `byHost` envelope
  * `{ byHost: { '<host>': outputs }, summary: { succeededHosts, failedHosts, outputs } }`.
@@ -358,14 +396,43 @@ export declare function mergeUpstreamOutputs(db: Kysely<Database>, runId: string
     mergedSecrets: Record<string, string> | undefined;
     upstreamJobOutputs: Record<string, Record<string, unknown>> | undefined;
     upstreamJobStatuses: Record<string, ExecutionJobStatus> | undefined;
+    upstreamInvokeResults: Record<string, InvokeResult[]> | undefined;
 }>;
-export declare function buildInternalJobConfigForWorkflow(workflow: any, job: any, sandboxGrant?: ResolvedSandboxGrant, firedSchedule?: {
-    cronExpression?: string;
-    timezone?: string;
-}): Record<string, unknown>;
+export declare function buildOnEventMatched(dispatcherRef: {
+    current: Dispatcher | null;
+}, providerRegistryRef: {
+    current: ProviderRegistry;
+}, processingDepsRef: {
+    current: (() => ProcessingDeps) | null;
+}): (event: any, lockFile: any, matchedWorkflows: any[], context?: EventMatchContext) => Promise<void>;
+/**
+ * Build the invoke-gate `summon` callback: match the source repo's own opt-in
+ * `kiciEvent({ name })` subscribers, dispatch each as a normal in-repo run, and
+ * return the spawned run ids so the gate can correlate a proxy job per run.
+ *
+ * This is the composition-root half of the invoke gate — it reuses the same
+ * in-process match + dispatch path the internal-event router uses
+ * (`matchKiciEventSubscribers` + `dispatchInternalEventViaPipeline`), scoped to
+ * the source repo. The gate executor (`runInvokeGate`) enforces the chain-depth
+ * bound and persists the summon↔spawn correlation.
+ */
+export declare function buildSummonCallback(dispatcherRef: {
+    current: Dispatcher | null;
+}, providerRegistryRef: {
+    current: ProviderRegistry;
+}, eventRouter: EventRouter, processingDepsRef: {
+    current: (() => ProcessingDeps) | null;
+}): (args: SummonArgs) => Promise<SummonedRun[]>;
 export declare function bootstrapOrchestrator(config: AppConfig, hooks: OrchestratorHooks, options?: {
     otelSdk?: {
         shutdown(): Promise<void>;
     };
+    /**
+     * Test-only fault-injection policy. Undefined in production (server.ts /
+     * standalone.ts pass nothing), so every seam sees an undefined policy and
+     * runs with no fault injection. A test-only entrypoint passes a policy to
+     * drive the seams directly.
+     */
+    faultInjection?: OrchestratorFaultInjection;
 }): Promise<void>;
 //# sourceMappingURL=orchestrator-core.d.ts.map

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

package/dist/pipeline/direct-ingress-deps.d.ts

@@ -0,0 +1,100 @@
+/**
+ * The `ProcessingDeps` bag the DIRECT-INGRESS pipeline runs on.
+ *
+ * Two pipelines assemble this bag. `server.ts` builds the one the Platform WS
+ * relay hands to `processWebhook`; this module builds the one every HTTP
+ * ingress uses — the direct GitHub route, the generic webhook routes, and the
+ * internal-event dispatch adapter. On an independent orchestrator there is no
+ * relay, so this is the ONLY bag it ever has.
+ *
+ * It lives outside `app.ts` because it is the seam an approval defect hides in.
+ * A field the composition root forgets is invisible: the pipeline reads it as
+ * `undefined`, every guard downstream is written to degrade rather than throw,
+ * and the feature is silently inert. Assembling the bag in a function with a
+ * declared return type is what lets a test assert the wiring directly instead
+ * of asserting it through a 2,000-line composition root that no test
+ * constructs.
+ */
+import type { ProcessingDeps } from './processor.js';
+import { TrustDirectoryStore } from '../security/trust-directory-store.js';
+import { TrustPolicyStore } from '../security/trust-policy-store.js';
+import type { SourceLocationData } from '../reporting/check-run-summary.js';
+/**
+ * Everything the bag reads that `AppDependencies` already carries.
+ *
+ * Declared structurally rather than as `AppDependencies` so this module does
+ * not import `app.ts` (which imports it) and so the fields the bag actually
+ * consumes are enumerated in one readable place. `AppDependencies` satisfies it
+ * by construction — the `createApp` call site is the compiler's check of that.
+ */
+export interface DirectIngressDepsSource {
+    db: ProcessingDeps['db'] & {};
+    config: {
+        mode: NonNullable<ProcessingDeps['orchestratorMode']>;
+        secretKey?: string | undefined;
+        instanceId?: string | undefined;
+        rosterGraceMs?: number | undefined;
+        maxFanoutHosts?: number | undefined;
+        globalEvalRoundTimeoutMs?: number | undefined;
+        globalEvalCandidateTimeoutMs?: number | undefined;
+        globalEvalWaitTimeoutMs?: number | undefined;
+    };
+    dedup: ProcessingDeps['dedup'];
+    providerRegistry: ProcessingDeps['providerRegistry'];
+    ensureProviderBundle?: ProcessingDeps['ensureProviderBundle'];
+    lockFileCache: ProcessingDeps['lockFileCache'];
+    contentRequirementsCache?: ProcessingDeps['contentRequirementsCache'];
+    dispatcher: ProcessingDeps['dispatcher'];
+    platformClient?: ProcessingDeps['platformClient'];
+    sourceCache?: ProcessingDeps['sourceCache'];
+    buildCoordinator?: ProcessingDeps['buildCoordinator'];
+    depCache?: ProcessingDeps['depCache'];
+    pendingBuilds?: ProcessingDeps['pendingBuilds'];
+    pendingInits?: ProcessingDeps['pendingInits'];
+    pendingDynamics?: ProcessingDeps['pendingDynamics'];
+    pendingGlobalEvals?: ProcessingDeps['pendingGlobalEvals'];
+    globalEvalCache?: ProcessingDeps['globalEvalCache'];
+    checkRunReporter?: ProcessingDeps['checkRunReporter'];
+    executionTracker?: ProcessingDeps['executionTracker'];
+    eventRouter?: ProcessingDeps['eventRouter'];
+    invokeGateDeps?: ProcessingDeps['invokeGateDeps'];
+    registrationStore?: ProcessingDeps['registrationStore'];
+    registrationIndex?: ProcessingDeps['registrationIndex'];
+    secretResolver?: ProcessingDeps['secretResolver'];
+    sandboxAllowListReader?: ProcessingDeps['sandboxAllowListReader'];
+    logStorage?: ProcessingDeps['logStorage'];
+    contextStore?: ProcessingDeps['contextStore'];
+    variableStore?: ProcessingDeps['variableStore'];
+    heldRunStore?: ProcessingDeps['heldRunStore'];
+    coordinator?: ProcessingDeps['coordinator'];
+    cronScheduler?: ProcessingDeps['cronScheduler'];
+    globalWorkflowPolicy?: ProcessingDeps['globalWorkflowPolicy'];
+    eventLogWriter?: ProcessingDeps['eventLog'];
+    accessLogWriter?: ProcessingDeps['accessLogWriter'];
+    hostRosterStore?: ProcessingDeps['hostRosterStore'];
+    clusterSettings?: ProcessingDeps['clusterSettings'];
+}
+/** The per-process stores this factory owns, exposed so the caller can reuse them. */
+export interface DirectIngressStores {
+    trustDirectoryStore: TrustDirectoryStore;
+    trustPolicyStore: TrustPolicyStore;
+}
+/**
+ * Build the direct-ingress `ProcessingDeps` factory.
+ *
+ * The returned function assembles a fresh bag per call, so every field reads
+ * the CURRENT subsystem instance — the provider registry is swapped wholesale
+ * on a source reload, and a bag captured once would keep dispatching through
+ * the replaced one.
+ *
+ * The two stores are constructed once here rather than per call: both are
+ * stateless over the database handle, and one of them is read on every PR
+ * delivery.
+ */
+export declare function createDirectIngressProcessingDeps(deps: DirectIngressDepsSource, hooks: {
+    onSourceLocationsExtracted: (workflowName: string, jobName: string, locations: Array<SourceLocationData | undefined>) => void;
+}): {
+    build: () => ProcessingDeps;
+    stores: DirectIngressStores;
+};
+//# sourceMappingURL=direct-ingress-deps.d.ts.map