@kici-dev/orchestrator 0.4.0 → 0.6.0

package/dist/pipeline/global-eval-round.d.ts

@@ -0,0 +1,307 @@
+/**
+ * Tier-2 global eval round — orchestrator side.
+ *
+ * A global workflow can declare a `filter` predicate and `DynamicJobFn`
+ * generators, neither of which the orchestrator may run: author code never
+ * returns to this process. So the candidates that need either one are grouped by
+ * the workflow repo they live in and handed to ONE pre-run job per
+ * (event × workflow repo × registered SHA). That job checks out the workflow
+ * repo and the source repo once, runs every candidate's filter and then its
+ * generators, and reports a verdict per candidate.
+ *
+ * The round precedes any run row by design: its whole purpose is to decide which
+ * global workflows produce a run at all, so creating one up-front would defeat
+ * it.
+ *
+ * This module owns the partition, the grouping, and the dispatch-and-await. The
+ * caller decides what to do with the verdicts.
+ */
+import type { GlobalEvalCandidateResult, LockWorkflow, SimulatedEvent, WorkflowDecision } from '@kici-dev/engine';
+import { type GlobalEvalRoundCache } from '../cache/global-eval-round-cache.js';
+import type { PendingGlobalEvalTracker } from '../cache/pending-global-evals.js';
+import type { ClusterSettingsReader } from '../cluster/cluster-settings-reader.js';
+import type { ProviderBundle } from '../provider-registry.js';
+import type { QueuedJobInput } from '../queue/job-queue.js';
+import type { RegisteredWorkflow } from '../registration/registration-index.js';
+import type { WebhookInfo } from '../webhook/handler.js';
+/** Name prefix identifying a round job in the queue, logs, and the dashboard. */
+export declare const ROUND_JOB_PREFIX = "__globaleval__";
+/** Metric label values for a per-candidate round verdict. */
+export declare const GlobalEvalVerdictOutcome: {
+    /** The candidate's `filter` admitted it and its jobs are dispatching. */
+    readonly Run: 'run';
+    /** The candidate's `filter` returned false — a decided exclusion. */
+    readonly Filtered: 'filtered';
+    /** The round could not decide: it failed, breached a budget, or never reported. */
+    readonly Indeterminate: 'indeterminate';
+};
+export type GlobalEvalVerdictOutcome = (typeof GlobalEvalVerdictOutcome)[keyof typeof GlobalEvalVerdictOutcome];
+/** Metric label values for a dispatched round's outcome. */
+export declare const GlobalEvalRoundResultLabel: {
+    readonly Success: 'success';
+    readonly Error: 'error';
+};
+export type GlobalEvalRoundResultLabel = (typeof GlobalEvalRoundResultLabel)[keyof typeof GlobalEvalRoundResultLabel];
+/** Metric label values for one round-cache lookup. */
+export declare const GlobalEvalCacheLookupResult: {
+    readonly Hit: 'hit';
+    readonly Miss: 'miss';
+    /** The round input could not be serialized, so no key exists to look up. */
+    readonly Unkeyable: 'unkeyable';
+};
+export type GlobalEvalCacheLookupResult = (typeof GlobalEvalCacheLookupResult)[keyof typeof GlobalEvalCacheLookupResult];
+/** One matched global workflow the round may have to decide on. */
+export interface GlobalEvalCandidate {
+    reg: RegisteredWorkflow;
+    lockEntry: LockWorkflow;
+    /**
+     * The trigger-match decision this candidate came from, carried so the round's
+     * verdict can be appended to its trace. Optional because the round itself
+     * never reads it — only the caller that explains an exclusion does.
+     */
+    decision?: WorkflowDecision;
+}
+/**
+ * Stable identity for one candidate across a round's results.
+ *
+ * The registration id alone is unique, but the workflow name is appended so a
+ * lookup reads honestly at the call site and a malformed registration with a
+ * blank id still separates two workflows.
+ */
+export declare function candidateKey(candidate: GlobalEvalCandidate): string;
+/**
+ * Split matched global candidates into those that can dispatch straight away and
+ * those that must go through an eval round first.
+ *
+ * A candidate needs the round when it declares a `filter` (only the agent may
+ * run the predicate) or carries a `DynamicJobFn` (only the agent may run the
+ * generator). Everything else is fully described by the lock file, so routing it
+ * through a round would add a job dispatch and an agent round trip for nothing.
+ */
+export declare function partitionCandidates(candidates: readonly GlobalEvalCandidate[]): {
+    immediate: GlobalEvalCandidate[];
+    needsRound: GlobalEvalCandidate[];
+};
+/**
+ * Group by workflow repo, routing key, and registered SHA.
+ *
+ * All three parts are load-bearing. The repo identifier and the SHA together pin
+ * the exact tree the round checks out, so two registrations of one repo at
+ * different commits can never share a checkout; the routing key pins which
+ * provider bundle mints the clone credentials, so two providers owning the same
+ * repo path stay separate.
+ */
+export declare function groupCandidates(candidates: readonly GlobalEvalCandidate[]): Map<string, GlobalEvalCandidate[]>;
+/** Minimal dispatcher surface the round needs (the real one is the job dispatcher). */
+export interface GlobalEvalDispatcher {
+    dispatch(input: QueuedJobInput): Promise<{
+        status: string;
+        jobId: string;
+    }>;
+    /**
+     * Take a still-queued round job out of the queue when nobody is waiting for
+     * it any more. Optional so a test double can omit it.
+     */
+    cancelQueuedJob?(jobId: string, reason: string): Promise<void>;
+}
+/**
+ * Minimal provider-registry surface: resolving the bundle that owns a routing
+ * key. The round needs it because the workflow repo and the event's source repo
+ * can live behind different providers.
+ */
+export interface GlobalEvalProviderRegistry {
+    getByRoutingKey(routingKey: string): ProviderBundle | undefined;
+}
+/** Minimal agent-registry surface used to pick the round job's platform labels. */
+export interface GlobalEvalAgentRegistry {
+    findAvailable(labels: string[]): Array<{
+        platform: string;
+        arch: string;
+        version?: string | null;
+    }>;
+}
+/**
+ * First agent release whose job runner understands a `globalEvalRound`
+ * dispatch.
+ *
+ * Below it the agent has no round branch at all: the job falls through to the
+ * standard executor, whose `jobConfig` carries no `source.file`, so it either
+ * fails outright or reports success without the `globalEvalComplete` the
+ * orchestrator is waiting for. Either way the round never settles.
+ *
+ * Customers upgrade their orchestrator and their agents on their own schedule
+ * (`.claude/rules/compatibility.md`), so an orchestrator ahead of its fleet is
+ * a supported state and not an error — but it is one this module has to
+ * recognise, because the damage is not confined to the new feature. A global
+ * workflow that merely *contains* a generator now routes through the round, so
+ * an unrecognised round means static jobs that ran yesterday stop running.
+ */
+export declare const MIN_GLOBAL_EVAL_AGENT_VERSION = "0.5.0";
+export interface GlobalEvalRoundDeps {
+    dispatcher: GlobalEvalDispatcher;
+    pendingGlobalEvals: PendingGlobalEvalTracker;
+    /**
+     * Required, unlike the three optional deps below: it is what resolves the
+     * WORKFLOW repo's own provider bundle. Omitting it would leave the round with
+     * no clone URL for the workflow repo at all, so it is not a dep that can
+     * degrade quietly.
+     */
+    providerRegistry: GlobalEvalProviderRegistry;
+    clusterSettings?: ClusterSettingsReader;
+    globalEvalCache?: GlobalEvalRoundCache;
+    agentRegistry?: GlobalEvalAgentRegistry;
+}
+export interface GlobalEvalRoundArgs {
+    deps: GlobalEvalRoundDeps;
+    info: WebhookInfo;
+    event: SimulatedEvent;
+    candidates: readonly GlobalEvalCandidate[];
+    /** Source repo that triggered the event. */
+    repoIdentifier: string;
+    /** Source repo SHA the event lands on. */
+    ref: string;
+    dispatchBundle: ProviderBundle;
+    dispatchCredentials: Record<string, unknown>;
+    /** Cluster defaults for the round budgets and the wait ceiling (`config.ts`). */
+    config: {
+        globalEvalRoundTimeoutMs: number;
+        globalEvalCandidateTimeoutMs: number;
+        globalEvalWaitTimeoutMs: number;
+    };
+}
+/**
+ * Why a fleet cannot decide a round, or `null` when it might.
+ *
+ * Only ONE state is refused: every registered init-runner reports a version, and
+ * every one of them is below the minimum. Everything else returns `null`.
+ *
+ * An empty fleet is not refused — nothing is registered yet, an agent may
+ * register a second from now, and the queue's own unroutable handling already
+ * covers a round nobody picks up.
+ *
+ * A fleet containing even ONE agent whose version cannot be read is not refused
+ * either, and the bar is deliberately that strict rather than "all unknown".
+ * Refusing suppresses every global workflow for the delivery — the exact damage
+ * this function exists to prevent — so it must rest on proof, not on ignorance
+ * about part of the fleet. Getting it wrong in the other direction merely costs
+ * a slow failure with a less useful message.
+ *
+ * Refusing here rather than at dispatch is deliberate. A too-old fleet does not
+ * clear within a retry, so dispatching would spend two full wait ceilings of
+ * inline webhook latency to reach the same verdict — and reach it with a
+ * timeout message that says nothing about agent versions.
+ */
+export declare function unsupportedFleetReason(agentRegistry?: GlobalEvalAgentRegistry): string | null;
+/**
+ * Narrow one wire verdict into a value the dispatch path can trust.
+ *
+ * The round-result schema proves only "array of objects with string keys" — its
+ * `jobs` entries are a deliberate unvalidated pass-through of `LockJob`, whose
+ * single source of truth is a TypeScript interface with no Zod mirror. So every
+ * field is re-checked here rather than dereferenced: `run` is compared, not
+ * coerced, and a generated job missing a usable `name` makes the whole candidate
+ * indeterminate rather than being dropped silently. Fail-closed is the right
+ * direction — a generator whose output we cannot read is a generator whose
+ * verdict we cannot act on, and half-dispatching its jobs would be worse than
+ * reporting that we could not decide.
+ */
+export declare function narrowVerdict(raw: unknown, workflowName: string): GlobalEvalCandidateResult;
+/**
+ * Cap on the joined reason string a decided-nothing round reports.
+ *
+ * The reasons are authored by an agent running author code, so their combined
+ * length is unbounded — and this string travels verbatim into the commit
+ * check's `output.summary`, which GitHub caps at 65535 characters. An overflow
+ * is rejected with a 422 that the best-effort post swallows, so the check
+ * disappears in exactly the case it exists for. Realistic reasons are one short
+ * sentence each; this bound makes that structural instead of lucky.
+ */
+export declare const MAX_ROUND_REASON_CHARS = 4000;
+/**
+ * Truncate `text` to at most `max` UTF-16 code units, marking that it was cut.
+ *
+ * Two edges the naive slice gets wrong, both of which matter because the result
+ * is posted to an API with a hard character limit:
+ *
+ * - A `max` smaller than the marker would make `max - marker.length` negative,
+ *   and appending the marker to an empty slice then returns a string LONGER
+ *   than `max`. Such a `max` cannot carry both content and a marker, so the
+ *   marker itself is truncated instead.
+ * - Slicing at an arbitrary index can cut a surrogate pair in half, leaving a
+ *   lone surrogate that is not valid text. The cut backs off by one unit when
+ *   it lands between the halves of a pair.
+ */
+export declare function truncateReasonText(text: string, max: number): string;
+/**
+ * One round that produced no verdicts after every attempt, described well enough
+ * for the caller to record it.
+ *
+ * There is exactly one of these per failed round — never one per candidate. The
+ * round exists to collapse N candidate workflows into a single pre-run job, so
+ * fanning its failure back out into N run rows and N checks would undo the fan-out
+ * reduction the whole design is for. `workflowNames` is what makes the single
+ * record honest: it names every workflow the failure suppressed.
+ */
+export interface GlobalEvalRoundFailure {
+    /** The last attempt's round-job run id — what an errored run row is written under. */
+    runId: string;
+    /** Repo the suppressed workflows are authored in. */
+    workflowRepoIdentifier: string;
+    /** Every candidate workflow this round suppressed. */
+    workflowNames: string[];
+    /** The last attempt's error. */
+    error: string;
+    /** How many attempts were made before giving up. `0` ⇒ never dispatched. */
+    attempts: number;
+    /**
+     * True when the round itself completed and decided some candidates, leaving
+     * only {@link workflowNames} undecided.
+     *
+     * Recorded as its own record rather than folded into a total failure because
+     * the two read differently to an author: a total failure means nothing from
+     * this repo ran, a partial one means their workflow specifically could not be
+     * decided while its neighbours ran fine. Without it, whether a broken filter
+     * is visible at all depends on how many unrelated global workflows happen to
+     * share a workflow repo — a per-candidate budget breach in a group of one
+     * produces a check, and the identical fault in a group of two produces
+     * nothing.
+     */
+    partial?: boolean;
+}
+/** Every candidate's verdict, plus the rounds that produced none. */
+export interface GlobalEvalRoundsOutcome {
+    /** One verdict per candidate, keyed by {@link candidateKey}. */
+    verdicts: Map<string, GlobalEvalCandidateResult>;
+    /** One entry per round that failed outright — never one per candidate. */
+    failures: GlobalEvalRoundFailure[];
+}
+/**
+ * Run every eval round the candidate set needs and return one verdict per
+ * candidate, plus one failure record per round that produced none.
+ *
+ * Rounds run one group at a time: a group is one dual checkout on one agent, and
+ * a push touching several workflow repos is the uncommon case. A group whose
+ * round fails marks only its own candidates indeterminate — one unreachable
+ * workflow repo must not suppress the workflows living in another.
+ *
+ * The failures are returned rather than recorded here: this module owns the
+ * partition, the grouping, and the dispatch-and-await, and has neither a
+ * database handle nor the inbound provider bundle a commit check must be posted
+ * through.
+ */
+export declare function runGlobalEvalRounds(args: GlobalEvalRoundArgs): Promise<GlobalEvalRoundsOutcome>;
+/**
+ * Meter candidates a round never got to decide on.
+ *
+ * The caller's fail-closed paths — no pending-eval tracker, so a round could
+ * never settle — return before {@link runGlobalEvalRounds} is reached, and they
+ * suppress EVERY global workflow for that delivery. That is this subsystem's
+ * most severe outcome, and without this call it appeared in none of its
+ * metrics: one `logger.warn` was the whole record.
+ *
+ * Counted as `indeterminate` because that is exactly what happened — nothing
+ * evaluated the workflows — which also keeps `candidates` equal to the sum of
+ * the verdicts on every path.
+ */
+export declare function recordUnrunCandidates(count: number): void;
+//# sourceMappingURL=global-eval-round.d.ts.map

package/dist/pipeline/internal-event-pipeline.d.ts

@@ -0,0 +1,140 @@
+/**
+ * Adapter that dispatches an internally-triggered workflow through the SHARED
+ * pipeline (`dispatchMatchedWorkflow`) instead of a bespoke path.
+ *
+ * The bespoke path it replaces resolved no bound contexts, so no context vars,
+ * no scoped secrets and none of the context's protection rules reached an
+ * internally-triggered job; it also dropped every non-static job on the floor.
+ * Routing through the one pipeline is what keeps a fourth such gap from
+ * appearing.
+ */
+import { z } from 'zod';
+import type { LockFile, WorkflowDecision } from '@kici-dev/engine';
+import { type ProcessingDeps } from './processor.js';
+import type { ProviderBundle } from '../provider-registry.js';
+/**
+ * The LIFECYCLE event names the orchestrator emits to itself. They are
+ * `__`-prefixed so they can never collide with a user `kiciEvent()` name, and
+ * each one maps onto a canonical trigger-event type (`__schedule_fire` is the
+ * one that is not a plain de-prefixing).
+ *
+ * NOT the whole set of orchestrator-minted events — the scaler manager mints two
+ * more under the other reserved prefix. NOT the trusted set either: two of these
+ * four are caused by a run and inherit its tier — `ORCHESTRATOR_MINTED_TRUSTED_EVENT_NAMES`
+ * is what the trust classification reads.
+ *
+ * Enumerated so this module compares against a checked value rather than a bare
+ * literal. It is NOT yet the single source: `cron/cron-scheduler.ts`,
+ * `events/event-emitter.ts` and `events/event-router.ts` still spell the same
+ * names inline, and converging them is a sweep this module's blast radius does
+ * not cover. The names are a protocol between those emitters, the router and
+ * this adapter, so a typo in any one of them silently stops matching.
+ */
+export declare const InternalSystemEventName: z.ZodEnum<{
+    __job_complete: "__job_complete";
+    __schedule_fire: "__schedule_fire";
+    __workflow_complete: "__workflow_complete";
+    __workflows_failed_batch: "__workflows_failed_batch";
+}>;
+/**
+ * Context for dispatching one internally-triggered workflow.
+ *
+ * Declared here rather than in `orchestrator-core.ts` because the adapter is
+ * the consumer that defines the shape; the composition root imports it.
+ */
+export interface InternalEventDispatchContext {
+    event: {
+        id: string;
+        eventName: string;
+        payload?: Record<string, unknown>;
+    };
+    routingKey: string;
+    repoIdentifier: string;
+    providerContext: Record<string, unknown>;
+    providerType: 'github' | undefined;
+    /**
+     * Provider bundle for the acting repository, resolved by the composition root
+     * from the live registry.
+     *
+     * Required, not derived here: every dispatch site builds its clone URL as
+     * `bundle?.repoUrlBuilder?.buildCloneUrl(repoIdentifier) ?? ''`, and nothing
+     * downstream resolves a bundle from `deps.providerRegistry`. Passing
+     * `undefined` therefore dispatches every job with an empty repo URL AND
+     * classifies the run as a local-working-tree dispatch (the source-pack build
+     * and the source-cache probe both gate on `!!ctx.bundle`), so no source
+     * tarball is produced and the agent falls through to cloning `''`. It also
+     * carries the clone-token provider and the check-status poster.
+     *
+     * Legitimately `undefined` when the event carries no routing key, or when the
+     * registry has no bundle for it — the same state the pre-pipeline path
+     * rendered as an empty repo URL.
+     */
+    bundle: ProviderBundle | undefined;
+    cronCommitSha: string;
+    /**
+     * The default branch of the registration this event dispatches, or `null`
+     * when it was never captured.
+     *
+     * A `__schedule_fire` run executes the default branch's lock file, so that
+     * branch IS the run's branch — which is what a context's branch restrictions
+     * evaluate. `null` presents no branch and the gate then rejects with its
+     * named-cause verdict; nothing substitutes a value, because a branch nobody
+     * proved is worse than an honest refusal.
+     */
+    registrationDefaultBranch: string | null;
+    /**
+     * The run that summoned this one through an invoke gate, when there is one.
+     *
+     * Set ONLY by the invoke-gate summon path, whose event id is synthesized and
+     * therefore matches no `kici_events` row. Stating the emitting run directly
+     * is what lets a summoned run inherit its summoner's trust tier — the same
+     * inheritance every other user `kiciEvent()` subscriber gets — instead of
+     * always falling back to isolated on a lookup that cannot succeed.
+     */
+    summonedByRunId?: string;
+    /**
+     * Chain depth to stamp on the started run. A webhook-triggered run leaves this
+     * unset (0); a run summoned by an invoke gate carries its summoner's depth + 1
+     * so the chain-depth circuit breaker bounds recursion when it fires its own
+     * gate.
+     */
+    chainDepth?: number;
+}
+/**
+ * The two identities an internal event renders into, which are NOT the same
+ * value for a user `kiciEvent()`:
+ *
+ * - `jobConfigType` is what workflows observe as `ctx.event.type` and what the
+ *   trigger matcher matched against — the literal `kici_event` for a custom
+ *   event.
+ * - `triggerEvent` is what the run carries and forwards to the Platform — the
+ *   actual event name, so the dashboard can say which event fired.
+ *
+ * A system (`__`-prefixed) event renders both from its de-prefixed name, with
+ * `__schedule_fire` collapsing onto `schedule`.
+ */
+export declare function deriveInternalEventIdentity(eventName: string): {
+    jobConfigType: string;
+    triggerEvent: string;
+};
+/**
+ * True when every tier the schema admits carries a rank.
+ *
+ * The `Record<TrustTier, number>` above already fails the build on an unranked
+ * tier, so this can only ever be false if the two drift through a cast. It is
+ * exported so a test asserts it against the live `TrustTierSchema.options`
+ * rather than against a transcription of it — the check has to read the schema
+ * to be worth having.
+ */
+export declare function trustTierRanksCoverEverySchemaTier(): boolean;
+/**
+ * Dispatch one matched workflow for an internal event through the shared
+ * pipeline. Returns the spawned-run summary the bespoke path returned, or
+ * `null` when the decision names a workflow the lock file does not carry.
+ */
+export declare function dispatchInternalEventViaPipeline(decision: WorkflowDecision, lockFile: LockFile, ctx: InternalEventDispatchContext, deps: ProcessingDeps): Promise<{
+    runId: string;
+    repo: string;
+    workflow: string;
+} | null>;
+//# sourceMappingURL=internal-event-pipeline.d.ts.map

package/dist/pipeline/invoke-gate.d.ts

@@ -0,0 +1,164 @@
+/**
+ * Invoke-gate executor.
+ *
+ * An invoke gate is a standard job whose only novel attribute is `invoke`: it
+ * never dispatches steps to an agent. When the gate becomes ready the
+ * orchestrator emits the gate's kici event at the source repo, matches the
+ * repo's opt-in subscribers, dispatches each as a normal in-repo run, and
+ * tracks each spawned run as a **proxy job** in the gate's own run.
+ *
+ * Correlation is a synchronous in-process match-and-dispatch — one orchestrator
+ * serves one org, so the executor matches + dispatches through an injected
+ * `summon` callback and gets the spawned run ids back directly. It ALSO persists
+ * `summoned_by_run_id` / `summoned_by_proxy_job` on each spawned run so proxy
+ * completion still resolves if the run finalizes on another HA instance.
+ *
+ * The gate itself is the aggregating graph node: downstream `needs` edges point
+ * at the gate, and its proxies are its fan-out children (`base_job_name` = the
+ * gate name). A zero-subscriber emit fails the gate by default; `optional: true`
+ * makes it a green skip.
+ */
+import { ExecutionJobStatus } from '@kici-dev/engine';
+import type { LockInvoke, LockJob } from '@kici-dev/engine';
+import type { Kysely } from 'kysely';
+import type { Database } from '../db/types.js';
+import type { ExecutionTracker } from '../reporting/execution-tracker.js';
+/**
+ * The invoke parameters carried from a gate's lock job to its (possibly deferred)
+ * execution. Persisted on the pending job context so a gate released later — or
+ * after a crash-recovery restore — still summons instead of reaching an agent.
+ */
+export interface InvokeGateParams {
+    event: string;
+    payload?: Record<string, unknown>;
+    /** Require-by-default: false fails the gate on zero subscribers. */
+    optional: boolean;
+    /** Fan-out concurrency width applied to the gate's proxy children. */
+    maxParallel?: number;
+    /** Fan-out fail-fast policy applied to the gate's proxy children. */
+    failFast?: boolean;
+    /** The gate's own wall-clock timeout in ms (orchestrator-swept). */
+    timeoutMs?: number;
+}
+/** Extract the invoke parameters from a lock job, or undefined when it is not a gate. */
+export declare function invokeParamsFromLockJob(lockJob: Pick<LockJob, 'invoke' | 'maxParallel' | 'failFast' | 'timeout'> & {
+    invoke?: LockInvoke;
+}): InvokeGateParams | undefined;
+/** True when a lock job is an invoke gate (carries an `invoke` action). */
+export declare function isInvokeGate(lockJob: Pick<LockJob, 'invoke'>): boolean;
+/**
+ * A summon that was REFUSED, as opposed to one that matched nothing.
+ *
+ * The two are not the same verdict and must never render the same. A gate
+ * carrying `optional: true` treats zero summoned runs as a green skip, so a
+ * refusal returned as `[]` would report success for work that was declined.
+ * Throwing this makes the confusion unrepresentable: {@link runInvokeGate}
+ * fails the gate job with the reason, whatever order its own checks run in.
+ */
+export declare class SummonRefusedError extends Error {
+    constructor(reason: string);
+}
+/** One source-repo run summoned by an invoke gate. */
+export interface SummonedRun {
+    /** The spawned run's id. */
+    runId: string;
+    /** The source repo the run belongs to (`owner/repo`). */
+    repo: string;
+    /** The subscribing workflow's name. */
+    workflow: string;
+}
+/** Arguments to the injected `summon` callback. */
+export interface SummonArgs {
+    event: string;
+    payload?: Record<string, unknown>;
+    sourceRepo: string;
+    /** The chain depth to stamp on the summoned runs (already incremented). */
+    chainDepth: number;
+    /** The summoning gate's run id — tag each spawned run so its proxy resolves. */
+    summonedByRunId: string;
+}
+/** Dependencies for {@link runInvokeGate}. */
+export interface InvokeGateDeps {
+    db: Kysely<Database>;
+    /** Insert the proxy rows + mark the gate terminal on a zero-match emit. */
+    executionTracker: Pick<ExecutionTracker, 'addJobsToRun' | 'onJobStatus' | 'reconcileSummonedRunIfTerminal'>;
+    /**
+     * Match the source repo's subscribers to `event`, dispatch each as a normal
+     * in-repo run, and return the spawned run ids. Implemented at the composition
+     * root, where it reuses the orchestrator's event match + trust-policy path.
+     *
+     * An empty array means the event matched no subscriber — a real outcome a
+     * gate may declare `optional`. A REFUSAL raises
+     * {@link SummonRefusedError} instead, so the two can never be read as the
+     * same thing.
+     */
+    summon: (args: SummonArgs) => Promise<SummonedRun[]>;
+    /** Max chain depth allowed for a summon (the circuit breaker's bound). */
+    maxChainDepth: number;
+}
+/** Arguments identifying the gate to run. */
+export interface RunInvokeGateArgs {
+    runId: string;
+    gateJobId: string;
+    gateJobName: string;
+    event: string;
+    payload?: Record<string, unknown>;
+    /** When true, a zero-subscriber emit succeeds; when false it fails the gate. */
+    optional: boolean;
+    sourceRepo: string;
+    chainDepth: number;
+    /** Fan-out concurrency width stamped on the proxy children (`maxParallel`). */
+    maxParallel?: number;
+    /** Fan-out fail-fast policy stamped on the proxy children (`failFast`). */
+    failFast?: boolean;
+}
+/**
+ * Aggregate an invoke gate's status from its proxies' terminal statuses. The
+ * gate stays open (`allTerminal: false`) until every proxy is terminal; then it
+ * is `failed` if any proxy is a failure, else `success`. Pure — the tracker's
+ * aggregation hook drives the DB reads and the gate transition.
+ */
+export declare function aggregateGateStatus(proxyStatuses: readonly string[]): {
+    allTerminal: boolean;
+    status?: ExecutionJobStatus;
+};
+/**
+ * The message a gate naming a reserved event fails with.
+ *
+ * Exported so the gate executor and its test state the same string, and so the
+ * SDK-side error can be compared against it.
+ */
+export declare function reservedEventMessage(event: string, prefix: string): string;
+/** The message a require-by-default gate fails with when nothing subscribes. */
+export declare function zeroSubscriberMessage(sourceRepo: string, event: string): string;
+/**
+ * The proxy job name for a summoned run — the gate name, a `repo:workflow`
+ * variant, and the summoned run id. The run id makes the name **unique per run**:
+ * two summoned runs with the same `repo`+`workflow` (duplicate registrations)
+ * would otherwise share one `job_name`, so the mirror's `job_name` lookup would
+ * resolve one proxy and leave the other hanging. The human-readable label for the
+ * graph is carried separately in `variant_label` (`repo:workflow`).
+ */
+export declare function proxyJobName(gateJobName: string, run: SummonedRun): string;
+/**
+ * Run an invoke gate: summon the source repo's subscribers and create one proxy
+ * child per spawned run. A zero-subscriber emit terminalizes the gate — failed
+ * by default, success under `optional`. When the chain-depth bound is reached
+ * the gate fails without summoning, so an invoke chain cannot loop.
+ */
+export declare function runInvokeGate(deps: InvokeGateDeps, args: RunInvokeGateArgs): Promise<void>;
+/** Dependencies for {@link releaseInvokeGate}. */
+export interface ReleaseInvokeGateDeps {
+    db: Kysely<Database>;
+    executionTracker: ExecutionTracker;
+    invokeGateDeps: InvokeGateDeps;
+}
+/**
+ * Release a ready invoke gate: swap its synthetic needs-pending row for a real
+ * `gate` job row, then run the gate executor. Reads the summoning run's source
+ * repo and chain depth from `execution_runs` (the chain depth bounds recursion).
+ * Shared by the needs-release path (`dispatchReadyJob`) and the root-gate
+ * post-registration nudge, so both go through one code path.
+ */
+export declare function releaseInvokeGate(deps: ReleaseInvokeGateDeps, runId: string, gateJobName: string, params: InvokeGateParams): Promise<void>;
+//# sourceMappingURL=invoke-gate.d.ts.map

package/dist/pipeline/job-contexts.d.ts

@@ -3,43 +3,42 @@
  *
  * A job binds an ordered list of contexts (`LockJob.contexts`). This
  * module resolves that list into concrete context names (static values
- * verbatim, pure-inline dynamic elements evaluated against the event) and folds
- * the per-context secrets/variables last-wins. It keeps the heavy fold logic
+ * verbatim; every dynamic element is resolved by the agent's init job) and
+ * folds the per-context secrets/variables last-wins. It keeps the heavy fold logic
  * out of `dispatchMatchedWorkflow`, which must stay under the function-length cap.
  */
 import { type Context, type HostFacts, type LockJob } from '@kici-dev/engine';
 import type { SecretResolverApi } from '../secrets/secret-resolver.js';
 import type { VariableStore } from '../contexts/variable-store.js';
 /**
- * Placeholder written into the persisted bound-env list for an impure dynamic
- * element the orchestrator cannot resolve at dispatch. The agent's init eval
- * later overwrites the list with the resolved name.
+ * Placeholder written into the persisted bound-env list for a dynamic element
+ * the orchestrator does not resolve at dispatch. The agent's init eval later
+ * overwrites the list with the resolved name.
  */
 export declare const DYNAMIC_ENV_PLACEHOLDER = "(dynamic)";
 /** Ordered resolved context names plus whether any element still needs agent init. */
 export interface ResolvedJobContexts {
-    /** Resolved static + pure-inline names, in order. */
+    /** Resolved static names, in order. */
     names: string[];
-    /** True when an impure dynamic element must be resolved by an agent init job. */
+    /** True when a dynamic element must be resolved by an agent init job. */
     needsInit: boolean;
 }
 /**
  * Resolve the ordered bound-context names from a lock job. Static elements
- * use their value verbatim; pure-inline dynamic elements use the matching
- * pre-evaluated inline name (aligned by index); an impure dynamic element cannot
- * be resolved here and flags `needsInit`.
+ * use their value verbatim; any dynamic element (inline or impure) is resolved
+ * by the agent's init job and flags `needsInit`.
  */
-export declare function resolveJobContextNames(lockJob: LockJob, inlineNames: ReadonlyArray<string | undefined>): ResolvedJobContexts;
+export declare function resolveJobContextNames(lockJob: LockJob): ResolvedJobContexts;
 /**
  * Build the ordered bound-context display list for persistence at dispatch.
  * Unlike {@link resolveJobContextNames}, this never drops an unresolved
- * element: a static element uses its value, a pure-inline element uses its
- * resolved name when known, and any element the orchestrator cannot resolve at
- * dispatch (impure dynamic, or an unresolved pure-inline) becomes the
- * `(dynamic)` placeholder — so the persisted column reflects every declared
- * slot in order. Returns an empty array when the job binds no context.
+ * element: a static element uses its value, and any dynamic element (which the
+ * orchestrator no longer resolves at dispatch) becomes the `(dynamic)`
+ * placeholder — so the persisted column reflects every declared slot in order.
+ * The deferred-init flow-back overwrites the placeholder once the agent
+ * resolves the name. Returns an empty array when the job binds no context.
  */
-export declare function buildJobContextDisplayNames(lockJob: LockJob, inlineNames: ReadonlyArray<string | undefined>): string[];
+export declare function buildJobContextDisplayNames(lockJob: LockJob): string[];
 /** Merged secrets/variables across an ordered list of resolved contexts. */
 export interface MultiEnvMergedData {
     contextVars?: Record<string, string>;