@kici-dev/orchestrator 0.9.1 → 0.11.0

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

@@ -21,6 +21,21 @@ import type { Signer } from './signer.js';
 export declare const DEFAULT_ORG_ID = "__default__";
 /** ID-token lifetime (seconds). */
 export declare const ORCHESTRATOR_ID_TOKEN_TTL_SECONDS = 600;
+/**
+ * Longest an agent mint waits for the provenance signer before it answers
+ * `{ deferred: true, code: 'unavailable' }`. Half the agent's `agent.api`
+ * timeout, so the deferred answer crosses the WebSocket and sandbox hops and
+ * reaches the step before the agent gives up on the call.
+ */
+export declare const ORCHESTRATOR_MINT_SIGNER_WAIT_MS: number;
+/**
+ * Minimum spacing between two warnings about mints deferred for want of a
+ * signing key. The first deferral after a signer was last available warns at
+ * once; later ones within the interval are counted into the next warning.
+ */
+export declare const MINT_DEFER_WARN_INTERVAL_MS = 60000;
+/** Logged when an agent mint defers because no provenance signing key is ready. */
+export declare const MINT_DEFERRED_NO_SIGNER_MESSAGE = "provenance signing key is not provisioned; deferring the identity-token mint";
 export declare class OrchestratorMintRunNotFoundError extends Error {
 }
 export declare class OrchestratorMintJobNotFoundError extends Error {
@@ -77,12 +92,18 @@ export declare class OrchestratorMintSignerUnavailableError extends Error {
 export interface OrchestratorOidcTokenHandlerDeps {
     dispatcher: OrchestratorMintOwnershipResolver;
     /**
-     * Lazily resolve the orchestrator's signing key. Resolved on first token
-     * request (not at boot) so it is unaffected by the Raft leader-election race —
-     * by the time an agent requests a token the cluster has a leader and the key
-     * exists. May return null while the key is still being reconciled.
+     * Lazily resolve the orchestrator's signing key. May return null while the
+     * key is still being reconciled. The handler waits at most
+     * {@link ORCHESTRATOR_MINT_SIGNER_WAIT_MS} for it; a null or a later answer
+     * defers the mint.
      */
     resolveSigner: () => Promise<Signer | null>;
+    /**
+     * Whether this node is the Raft leader, named in the deferral warning so an
+     * operator can tell a non-leader waiting on the leader from a leader that
+     * could not create the key.
+     */
+    isLeader?: () => boolean;
     /** Mint deps except the signer (supplied lazily via `resolveSigner`). */
     mint: Omit<OrchestratorMintDeps, 'signer'>;
     /**

package/dist/oidc/reconcile-signing-key.d.ts

@@ -3,10 +3,13 @@
  * one `active` key exists and returns a live `Signer` bound to it.
  *
  *  - `db` custody: the private key is a random keypair generated + persisted
- *    (master-key-wrapped) in the DB. Generation is LEADER-GATED so an HA cluster
- *    never races two active keys; every node then loads the one active row. A
- *    non-leader that finds no active row yet returns null this tick and is
- *    retried on the next leadership/boot cycle.
+ *    (master-key-wrapped) in the DB. Any node with signing enabled may create it
+ *    when no key of any custody is active; the leader gets the first chance (see
+ *    `createKeyCreationGate`). The write is an atomic compare-and-activate, so
+ *    nodes that race converge on the one key that won and every node signs with
+ *    that key. An active key of another custody kind is never replaced here:
+ *    the node refuses to sign, and `kici-admin signing-key rotate` is the
+ *    explicit move to db custody.
  *  - `aws-kms` / `command` custody: the key lives outside KiCI, so every node
  *    resolves the SAME kid and `upsertActive` is idempotent across the fleet.
  */
@@ -14,10 +17,32 @@ import type { JWK } from 'jose';
 import { type OrchestratorSignerConfig } from './orchestrator-signer-factory.js';
 import type { Signer } from './signer.js';
 import type { OrchestratorSigningKeyRepo } from '../db/repos/signing-keys-repo.js';
+/**
+ * How long a non-leader leaves key creation to the Raft leader before it
+ * creates the key itself. Kept well under the mint's signer wait so the first
+ * mint on a non-leader of a cluster whose leader has signing disabled still
+ * gets a token instead of a deferral.
+ */
+export declare const NON_LEADER_KEY_CREATE_GRACE_MS = 2000;
+/**
+ * Decide whether this node may create the db-custody key right now. The leader
+ * always may. A non-leader may once `graceMs` has passed since it first asked,
+ * so a cluster whose leader never creates the key (signing disabled on it, or
+ * no leader elected) still gets one.
+ */
+export declare function createKeyCreationGate(opts: {
+    isLeader: () => boolean;
+    graceMs: number;
+    now?: () => number;
+}): () => boolean;
 export interface ReconcileSigningKeyDeps {
-    repo: Pick<OrchestratorSigningKeyRepo, 'getActiveRow' | 'upsertActive'>;
+    repo: Pick<OrchestratorSigningKeyRepo, 'getActiveRow' | 'upsertActive' | 'activateIfCurrent'>;
     config: OrchestratorSignerConfig;
-    isLeader: () => boolean;
+    /**
+     * Whether this node may create the db-custody key now that none is usable.
+     * Consulted only by `db` custody; see `createKeyCreationGate`.
+     */
+    mayCreateKey: () => boolean;
     /** The orchestrator master key (`KICI_SECRET_KEY`), for `db` custody wrapping. */
     secretKey: string | undefined;
     /**

package/dist/oidc/resolve-signer.d.ts

@@ -1,12 +1,12 @@
 /**
  * Bounded wait for the orchestrator's provenance signer.
  *
- * A mint that arrives before the leader has generated the key must NOT fall
+ * A mint that arrives before any node has generated the key must NOT fall
  * back to a Platform-signed bundle (it would fail verification against the
  * orchestrator trust root), so the resolver waits for the key instead of
  * deferring on the first miss. But the wait exists for ONE condition — a
- * reconcile that returns `null` because a non-leader has not yet seen the row
- * the leader is about to write. A reconcile that THROWS is a different answer:
+ * reconcile that returns `null` because a non-leader is still leaving key
+ * creation to the leader. A reconcile that THROWS is a different answer:
  * a signing key sealed under a master key this process does not hold, or `db`
  * custody with no master key at all. Neither changes across the wait, so
  * retrying it for the full window only turns every mint into a silent
@@ -31,10 +31,16 @@ export interface ResolveSignerOptions {
     /** Injectable for tests. */
     sleep?: (ms: number) => Promise<void>;
 }
+/** Per-call override of the resolver's wait. */
+export interface ResolveSignerCallBudget {
+    /** Attempts for this call only, in place of the configured `maxAttempts`. */
+    maxAttempts: number;
+}
 /**
  * Build a memoizing resolver: the first successful reconcile is cached for the
- * life of the process, a null reconcile is retried up to `maxAttempts` times,
- * and a thrown reconcile ends the call at once with `null`.
+ * life of the process, a null reconcile is retried up to `maxAttempts` times
+ * (or the call's own budget), and a thrown reconcile ends the call at once with
+ * `null`.
  */
-export declare function createBoundedSignerResolver(opts: ResolveSignerOptions): () => Promise<Signer | null>;
+export declare function createBoundedSignerResolver(opts: ResolveSignerOptions): (budget?: ResolveSignerCallBudget) => Promise<Signer | null>;
 //# sourceMappingURL=resolve-signer.d.ts.map

package/dist/pipeline/decorating-secret-resolver.d.ts

@@ -12,7 +12,7 @@
  * wins.
  */
 import type { HostFacts } from '@kici-dev/engine';
-import type { SecretResolverApi, ResolvedSecretMeta } from '../secrets/secret-resolver.js';
+import type { MatchedContextRef, ResolvedSecretMeta, SecretResolutionAttribution, SecretResolverApi } from '../secrets/secret-resolver.js';
 /** Decrypted CLI-uploaded local secrets: flat keys + per-context namespaces. */
 export interface CliSecrets {
     flat: Record<string, string>;
@@ -21,13 +21,15 @@ export interface CliSecrets {
 export declare class DecoratingSecretResolver implements SecretResolverApi {
     private readonly base;
     private readonly cli;
+    /** The wrapped resolver's binding count, when it offers one. */
+    readonly countContextBindings?: (contextId: string) => Promise<number>;
     constructor(base: SecretResolverApi, cli: CliSecrets);
-    resolveForJob(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, string>>;
+    resolveForContext(orgId: string, context: MatchedContextRef, hostCtx?: HostFacts, attribution?: SecretResolutionAttribution): Promise<Record<string, string>>;
     resolveNamedInternal(orgId: string, scope: string, key: string, opts?: {
         store?: string;
         runId?: string;
         jobId?: string;
     }): Promise<string | null>;
-    resolveForJobWithMeta(orgId: string, contextName: string, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
+    resolveForContextWithMeta(orgId: string, context: MatchedContextRef, hostCtx?: HostFacts): Promise<Record<string, ResolvedSecretMeta>>;
 }
 //# sourceMappingURL=decorating-secret-resolver.d.ts.map

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

@@ -16,16 +16,20 @@
 import { ExecutionJobStatus, InitFailureCategory, CacheRefScope, HoldScope, TriggerSource } from '@kici-dev/engine';
 import type { LabelMatcher, LockWorkflow, LockJob, ApprovalRequirement, HostTargetSelector, SimulatedEvent, WorkflowDecision, MaterializedJob, ResolvedHostAgent, UpstreamSnapshot, HostFacts } from '@kici-dev/engine';
 import { type HostRosterStore } from '../agent/host-roster.js';
+import type { RerunLineage } from '../reporting/execution-tracker.js';
 import { NEEDS_PENDING_JOB_ID_PREFIX } from '../db/synthetic-job-ids.js';
 import { gatherInvokeResults } from '../orchestrator-core.js';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { ProviderBundle } from '../provider-registry.js';
+import { type GlobalDispatchIdentity } from './global-dispatch-identity.js';
 import type { Dispatcher } from '../agent/dispatcher.js';
 import type { QueuedJobInput } from '../queue/job-queue.js';
 import type { TrustResolution } from '../security/trust-resolver.js';
 import type { TrustPolicyOutcome } from '../security/trust-policy-gate.js';
 import type { CreateHeldRunData } from '../contexts/held-runs.js';
+import { type DeferredContextResolution } from './held-context-data.js';
 import { type NpmRegistrySpec } from './install-secrets-resolver.js';
+import type { InstallGateRecord } from './install-gate.js';
 import { type ProcessingDeps } from './processor.js';
 /**
  * Trusted refs (write+ contributor, default-branch) get the org-shared cache
@@ -60,23 +64,21 @@ export interface WorkflowDispatchContext {
     payload: unknown;
     repoIdentifier: string;
     /**
-     * The repository that DEFINES the workflow being dispatched. `repoIdentifier`
-     * is the repository the run acts on; for an organization-wide workflow the
-     * two are different repositories, and every run row this dispatch writes has
-     * to say which one defined it.
+     * The repository that defines the workflow. Equals `repoIdentifier` unless
+     * `global` is set.
      *
      * REQUIRED, for the same reason `securityDecision` is: a dispatch path that
      * does not state it must not compile. Left optional, a new caller omits it
      * silently and every row it records claims the workflow lives in the
      * repository the run acted on — a null marker is read as that fact, not as
      * "unknown" (`registration/registration-run-match.ts`).
-     *
-     * Every caller today states `repoIdentifier` or a value equal to it, because
-     * no cross-repository global dispatch enters this function — the global path
-     * builds its job inputs directly and dispatches them itself. The recording
-     * sites narrow, so stating the acted-on repository records nothing.
      */
     workflowRepoIdentifier: string;
+    /**
+     * Set when the workflow is defined in another repository; `repoIdentifier`
+     * is then the event's source repository.
+     */
+    global?: GlobalDispatchIdentity;
     credentials: Record<string, unknown>;
     event: SimulatedEvent;
     eventWithFiles: SimulatedEvent;
@@ -131,6 +133,19 @@ export interface WorkflowDispatchContext {
     triggeredBy?: string | null;
     /** Agent provenance label when the run was initiated through an agent credential. */
     triggeredByAgentLabel?: string | null;
+    /**
+     * Re-run lineage for `execution_runs.parent_run_id` / `original_run_id`: the
+     * run this one re-runs and the root of its re-run chain. Set by the re-run of
+     * an organization-wide run; absent for every first run.
+     */
+    rerunLineage?: RerunLineage;
+    /**
+     * The trigger event the run's OIDC subject derives from, when it is not the
+     * run's own `triggerEvent`. A re-run records `rerun` as its trigger event,
+     * which carries no pull-request dimension, so it states the original run's
+     * event here to keep the subject a re-run of a fork pull request presents.
+     */
+    subjectTriggerEvent?: string;
     /** True only when invoked from the cross-source dispatch shell. */
     crossSource: boolean;
     /**
@@ -305,6 +320,14 @@ export interface WorkflowDispatchContext {
      * exposes them as `ctx.dispatchInputs`. Undefined for webhook runs.
      */
     dispatchInputs?: Record<string, unknown>;
+    /**
+     * What the workflow install gate recorded when it held this dispatch: the
+     * contexts that held, which the hold's approval covers, and the ones it
+     * admitted. Stored with the held dispatch and read by its release, which
+     * gates every context the approval did not cover. Unset on any other
+     * dispatch.
+     */
+    installGateRecord?: InstallGateRecord;
 }
 /**
  * The minimal slice of a dispatch context the needs catch-up + ready-recompute
@@ -443,6 +466,13 @@ interface JobEnvData {
         serveraddress: string;
     };
     held?: boolean;
+    /**
+     * Set when the job's bound contexts admitted its reject rules: what a later
+     * dispatch resolves the context data from when the job is stored as a
+     * pending dispatch context (held, waiting on upstream jobs, or outside its
+     * wave window) instead of dispatching now. Carries no secret value.
+     */
+    contextResolution?: DeferredContextResolution;
     /**
      * Pending approval hold for this job, set when a context policy or
      * explicit lock `approval` requires human sign-off. The dispatch loop turns
@@ -795,6 +825,20 @@ export declare function resolveWorkflowDockerfileBuilds(workflow: LockWorkflow,
  * on the hold rows before giving up and leaving the check unclosable.
  */
 export declare const PENDING_CHECK_MARK_ATTEMPTS = 3;
+export declare function postPendingHoldCheck(args: {
+    poster: NonNullable<NonNullable<WorkflowDispatchContext['bundle']>['checkStatusPoster']>;
+    store: NonNullable<ProcessingDeps['heldRunStore']>;
+    orgId: string;
+    /** Every hold that gates the one check run this post writes. */
+    heldRunIds: readonly string[];
+    repoIdentifier: string;
+    sha: string;
+    summary: string;
+    credentials: unknown;
+    /** Log fields naming the hold, and the message a failed POST is reported under. */
+    logContext: Record<string, unknown>;
+    postFailureMessage: string;
+}): Promise<void>;
 /**
  * Open the needs gate for any job whose upstreams already reached terminal
  * before this run's edges existed.
@@ -901,6 +945,12 @@ export interface GeneratedJobConfig {
      * site below, which is what the credential relay authorizes a request against.
      */
     gitCredentials?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+    /**
+     * What a later dispatch resolves the job's context data from, when the job
+     * binds a context. A generated job stored as a pending dispatch context
+     * carries no context data at rest.
+     */
+    contextResolution?: DeferredContextResolution;
 }
 /**
  * Split generated configs into pinned (host-pin dispatch) and unpinned (normal
@@ -912,12 +962,11 @@ export declare function partitionGeneratedConfigsByPin(configs: readonly Generat
     pinnedConfigs: GeneratedJobConfig[];
     unpinnedConfigs: GeneratedJobConfig[];
 };
-export declare function resolveGeneratedJobConfigs(args: {
+/** Inputs {@link resolveGeneratedJobConfigs} builds every generated job's config from. */
+interface ResolveGeneratedJobConfigsArgs {
     ctx: WorkflowDispatchContext;
     workflow: LockWorkflow;
     fullLockFile: WorkflowDispatchContext['fullLockFile'];
-    resolvedSecrets: Record<string, string> | undefined;
-    resolvedNamespacedSecrets: Record<string, Record<string, string>> | undefined;
     runPublicKeyBase64: string | undefined;
     npmRegistries: NpmRegistrySpec[] | undefined;
     installEnvSecrets: Record<string, string> | undefined;
@@ -925,7 +974,31 @@ export declare function resolveGeneratedJobConfigs(args: {
     dynamicEntry: BuildPrepResult['dynamicEntries'][number];
     /** Frozen upstream snapshot threaded into each generated job's dynamicSource for re-eval. */
     upstreamSnapshot?: UpstreamSnapshot;
-}): Promise<GeneratedJobConfig[]>;
+}
+/** A generated job its contexts' protection gates held, with the hold they decided. */
+export interface HeldGeneratedJob {
+    config: GeneratedJobConfig;
+    envData: JobEnvData;
+}
+/**
+ * The generated jobs split by their context gate verdict. A job the gates
+ * rejected, or whose resolution threw, appears in neither list: it is recorded
+ * on the run as failed.
+ */
+export interface GeneratedJobResolution {
+    /** Jobs cleared to dispatch, carrying their resolved context data. */
+    dispatchable: GeneratedJobConfig[];
+    /** Jobs to hold; their context secrets are not resolved. */
+    held: HeldGeneratedJob[];
+}
+/**
+ * Gate each generated job on its bound contexts and build the job configs.
+ *
+ * A job the context rules reject is recorded on the run as failed and returned
+ * in neither list. A job whose resolution throws is recorded on the run as
+ * failed too, and dropped from both lists.
+ */
+export declare function resolveGeneratedJobConfigs(args: ResolveGeneratedJobConfigsArgs): Promise<GeneratedJobResolution>;
 /**
  * Recompute the needs gate for `jobNames` and act on whatever became ready:
  * open the gate for a satisfied job, terminalize a job an upstream's status
@@ -938,6 +1011,25 @@ export declare function resolveGeneratedJobConfigs(args: {
  */
 export declare function recomputeAndApplyReady(ctx: NeedsSchedulingContext, jobNames: readonly string[]): Promise<void>;
 export { gatherInvokeResults };
+/**
+ * The `held_runs` row the org trust policy's PR-wide hold writes for `runId`.
+ *
+ * Shared by the per-workflow hold below and the held pre-run evaluation round,
+ * so both land in the same queue and release through the same route.
+ */
+export declare function buildSecurityHoldData(runId: string, decision: Extract<TrustPolicyOutcome, {
+    action: 'hold';
+}>): {
+    runId: string;
+    jobId: "__fork_pr__";
+    contextId: null;
+    holdType: "security";
+    queueType: 'security';
+    reason: "fork_pr";
+    expiresAt: Date;
+    scope: "workflow";
+    triggerSource: "context";
+};
 /**
  * Dispatch a single matched workflow.
  *

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

@@ -0,0 +1,121 @@
+/**
+ * Shared fixtures for the `dispatchMatchedWorkflow` test files.
+ *
+ * Kept out of any `*.test.ts` file so importing it does not re-register another
+ * file's suites in the importer.
+ */
+import { type Mock } from 'vitest';
+import type { ProviderType } from '@kici-dev/engine';
+import type { QueuedJobInput } from '../queue/job-queue.js';
+import type { WorkflowDispatchContext } from './dispatch-matched-workflow.js';
+/** Provider of the inbound event every {@link makeSingleJobContext} fixture carries. */
+export declare const TEST_INBOUND_PROVIDER: ProviderType;
+/** Overrides {@link makeSingleJobContext} accepts. */
+export interface SingleJobContextOptions {
+    bundle: WorkflowDispatchContext['bundle'];
+    fullRepo?: boolean;
+    testRun?: {
+        fixtureId: string;
+    };
+    db?: unknown;
+    executionTracker?: unknown;
+    withBuildInfra?: boolean;
+    withBuildMiss?: boolean;
+    localWorkingTree?: boolean;
+    runWideFlatSecrets?: Record<string, string>;
+    jobContext?: string;
+    /** Workflow-level context names (`LockWorkflow.contexts`) bound by every job. */
+    workflowContexts?: string[];
+    secretResolver?: unknown;
+    checkMode?: string;
+    jobContainer?: unknown;
+    jobSandbox?: {
+        capabilities?: string[];
+        network?: string;
+    };
+    sandboxAllowListReader?: unknown;
+    jobMatrix?: unknown;
+    contextConcurrencyLimit?: number | null;
+    /** Set wait_timer_seconds on the jobContext row, so its gate returns `wait`. */
+    contextWaitTimerSeconds?: number | null;
+    heldRunStore?: unknown;
+    /** Append a dynamic job fn, so dispatch spawns a deferred dynamic entry. */
+    withDynamicEntry?: boolean;
+    /** Give the static job a dynamic matrix, so its init is deferred. */
+    withDeferredInit?: boolean;
+    /** Declare a workflow-level filter, so every job defers to the init round. */
+    withFilter?: boolean;
+    pendingDynamics?: unknown;
+    pendingInits?: unknown;
+    /** Give the static job an explicit SDK requireApproval. */
+    jobApproval?: unknown;
+    /** Give the job a dynamic env, so its init is deferred without a matrix. */
+    withDynamicEnv?: boolean;
+    /** Bind the job to a DYNAMIC context, resolved only by the init round. */
+    withDynamicContext?: boolean;
+    /** A contextStore stub used verbatim (overrides the jobContext-derived one). */
+    contextStore?: unknown;
+    /**
+     * A checkRunReporter stub, so a case can observe the queued check runs the
+     * dispatch setup phase creates against the commit.
+     */
+    checkRunReporter?: unknown;
+}
+/**
+ * A context row named `name` with no rules, always enabled; `rowOver` replaces
+ * any column.
+ */
+export declare function makeJobContextRow(name: string, over: SingleJobContextOptions, rowOver?: Record<string, unknown>): {
+    id: string;
+    org_id: string;
+    name: string;
+    type: string;
+    glob_pattern: null;
+    branch_restrictions: null;
+    trigger_type_filters: null;
+    repo_patterns: null;
+    concurrency_limit: number | null;
+    concurrency_strategy: null;
+    concurrency_timeout_ms: null;
+    required_reviewers: null;
+    wait_timer_seconds: number | null;
+    hold_expiry_seconds: null;
+    minimum_trust: null;
+    allow_local_execution: boolean;
+    enabled: boolean;
+    created_at: Date;
+    updated_at: Date;
+    created_by: null;
+};
+/**
+ * Assemble a minimal real `WorkflowDispatchContext` for a single static job,
+ * with a capturing dispatcher and all optional deps absent unless overridden.
+ * This is the test-mode shape: `bundle` may be undefined and `trustResolution`
+ * is undefined (single-orch, no holds, no trust).
+ */
+export declare function makeSingleJobContext(over: SingleJobContextOptions): {
+    ctx: WorkflowDispatchContext;
+    dispatched: QueuedJobInput[];
+};
+/** An execution-tracker stub covering the calls a gated dispatch makes. */
+export interface GateTracker {
+    addJobsToRun: Mock;
+    onExecutionStarted: Mock;
+    onJobStatus: Mock;
+    holdRunForPendingJobs: Mock;
+    releasePendingJobsHold: Mock;
+    recordInitFailureRun: Mock;
+}
+/**
+ * Resolve once every background task a dispatch started has finished. Each task
+ * (a dynamic entry, a deferred init job) takes a pending-jobs token before
+ * `dispatchMatchedWorkflow` returns and gives it back when it settles, so the
+ * two counts match only when none is still running. A negative assertion made
+ * after this cannot pass by running before the task reached its decision.
+ */
+export declare function awaitDispatchTasksSettled(tracker: GateTracker): Promise<void>;
+/** A fresh {@link GateTracker}. */
+export declare function makeGateTracker(): GateTracker;
+/** Enough Kysely surface for the hold path: counts, upserts, and one transaction. */
+export declare function makeHoldDb(): Record<string, unknown>;
+//# sourceMappingURL=dispatch-matched-workflow.test-helpers.d.ts.map

package/dist/pipeline/global-dispatch-identity.d.ts

@@ -0,0 +1,76 @@
+/**
+ * The workflow-repository identity of a dispatch whose workflow is defined in
+ * another repository (a global workflow), and the seams that decide which
+ * repository each dispatch concern reads.
+ *
+ * Policy — contexts, install secrets, the user-cache namespace — follows the
+ * repository that defines the workflow. Checkout and the event stay with the
+ * repository the event came from. For a same-repository dispatch every helper
+ * collapses to the event's own values.
+ */
+import type { ProviderBundle } from '../provider-registry.js';
+import type { WorkflowRepoProvenance } from '../reporting/execution-tracker.js';
+/** The workflow repository of a run whose workflow is defined in another repository. */
+export interface GlobalDispatchIdentity {
+    /** `owner/repo` that defines the workflow. */
+    readonly workflowRepoIdentifier: string;
+    /** Commit of the registration the run executes. `null` when the registration predates commit tracking. */
+    readonly workflowSha: string | null;
+    /** Branch the registration was taken from (`workflow_registrations.default_branch`). */
+    readonly workflowBranch: string | null;
+    /** Routing key of the source that registered the workflow repository. */
+    readonly workflowRoutingKey: string;
+    /** Provider context (e.g. the installation) the workflow repository's credentials are minted with. */
+    readonly workflowProviderContext: Record<string, unknown>;
+    /** The workflow repository's provider bundle (may differ from the inbound one). */
+    readonly workflowBundle: ProviderBundle | undefined;
+    /** Credentials minted for the workflow repository. */
+    readonly workflowCredentials: Record<string, unknown>;
+}
+interface IdentityCtx {
+    repoIdentifier: string;
+    event: {
+        targetBranch: string;
+    };
+    global?: GlobalDispatchIdentity;
+}
+/** Repository whose contexts, install secrets and lock the run uses. */
+export declare function policyRepo(ctx: IdentityCtx): string;
+/** Branch context branch rules check. A global run presents its registration's branch; `''` matches no rule. */
+export declare function policyBranch(ctx: IdentityCtx): string;
+/** User-cache namespace. A global run gets its own (workflow repo, source repo) namespace. */
+export declare function cacheRepoIdFor(ctx: IdentityCtx): string;
+/**
+ * Routing key whose per-source variable overrides layer over a context's
+ * variables. A global run reads the workflow repository's source, so the
+ * event's source cannot override the variables of a context it does not own.
+ */
+export declare function policyRoutingKey(ctx: {
+    info: {
+        routingKey: string;
+    };
+    global?: GlobalDispatchIdentity;
+}): string;
+/** Provenance recorded on the run row; `undefined` for a same-repo run. */
+export declare function workflowRepoProvenance(ctx: IdentityCtx): WorkflowRepoProvenance | undefined;
+/**
+ * The dual-checkout job-config fields of a dispatch, with the workflow
+ * repository's clone URL built by its own provider bundle. Empty for a
+ * same-repository dispatch. Throws when the workflow bundle cannot build a
+ * clone URL: a global job without a workflow-repository URL cannot run.
+ */
+export declare function globalJobConfigFor(ctx: IdentityCtx): Record<string, unknown>;
+/** Job-config fields the agent uses for the dual checkout. */
+export declare function globalJobConfigFields(ctx: IdentityCtx, workflowRepoUrl: string): Record<string, unknown>;
+/**
+ * The part of a {@link GlobalDispatchIdentity} a held run stores: everything
+ * but the live provider bundle and the minted credentials, both of which a
+ * resume re-derives from `workflowRoutingKey`. The commit, branch and provider
+ * context are the ones captured when the run was held, so a resumed run
+ * executes the workflow commit it was held at, not the live registration's.
+ */
+export type SerializableGlobalDispatchIdentity = Omit<GlobalDispatchIdentity, 'workflowBundle' | 'workflowCredentials'>;
+/** The stored form of a global identity: its fields named one by one, so no live object or token rides along. */
+export declare function toSerializableGlobalIdentity(g: GlobalDispatchIdentity): SerializableGlobalDispatchIdentity;
+export {};
+//# sourceMappingURL=global-dispatch-identity.d.ts.map

package/dist/pipeline/global-dispatch.d.ts

@@ -0,0 +1,91 @@
+import type { LockJobOrFactory, LockWorkflow, SimulatedEvent } from '@kici-dev/engine';
+import type { WebhookInfo } from '../webhook/handler.js';
+import type { ProviderBundle } from '../provider-registry.js';
+import type { RegisteredWorkflow } from '../registration/registration-index.js';
+import type { TrustResolution } from '../security/trust-resolver.js';
+import type { TrustPolicyOutcome } from '../security/trust-policy-gate.js';
+import { type WorkflowDispatchContext } from './dispatch-matched-workflow.js';
+import type { GlobalEvalCandidate } from './global-eval-round.js';
+import type { ProcessingDeps } from './processor.js';
+/**
+ * A global candidate handed to the pipeline, with the exact job set to dispatch.
+ *
+ * A round-cleared candidate carries its static jobs, the jobs the round
+ * generated, and its result-aware `DynamicJobFn` entries, which the pipeline
+ * evaluates on its deferred path once their upstreams complete
+ * (`RoundClearedCandidate`). A candidate the event's trust verdict settles
+ * before any round carries its lock-file job list as declared, `DynamicJobFn`
+ * entries included: the pipeline's trust gate rejects or ignores it before any
+ * job is expanded.
+ */
+export interface ResolvedGlobalCandidate {
+    candidate: GlobalEvalCandidate;
+    jobs: readonly LockJobOrFactory[];
+}
+/**
+ * A candidate the evaluation round cleared, or one that never needed the round.
+ * Its only `DynamicJobFn` entries are result-aware ones: every needs-free
+ * generator was already expanded by the round.
+ */
+export type RoundClearedCandidate = ResolvedGlobalCandidate;
+/** Inputs of one global candidate's dispatch. */
+export interface GlobalCandidateDispatchArgs {
+    info: WebhookInfo;
+    deps: ProcessingDeps;
+    payload: unknown;
+    /**
+     * The bundle that checks out the source repository and posts its checks.
+     * The inbound event's bundle, or another source's when a cross-provider
+     * lock-file fallback resolved one.
+     */
+    sourceBundle: ProviderBundle;
+    /** Routing key `sourceBundle` belongs to, when it is not `info.routingKey`. */
+    sourceRoutingKey?: string;
+    sourceRepoIdentifier: string;
+    /** Credentials of `sourceBundle` for the source repository. */
+    sourceCredentials: Record<string, unknown>;
+    event: SimulatedEvent;
+    eventWithFiles: SimulatedEvent;
+    /** The event's commit SHA. */
+    ref: string;
+    resolvedOrgId: string;
+    /** The event's trust resolution, recorded on the run and read by `minimumTrust`. */
+    trustResolution: TrustResolution | undefined;
+    /** The event's trust-policy verdict; a `hold` holds the global run. */
+    securityDecision: TrustPolicyOutcome;
+    /** The candidate and its final job list (static and round-generated entries). */
+    resolved: ResolvedGlobalCandidate;
+}
+/**
+ * Credentials for the workflow repository, minted by its own provider bundle
+ * with the registration's provider context. Throws when the mint fails.
+ */
+export declare function mintWorkflowRepoCredentials(workflowBundle: ProviderBundle, reg: Pick<RegisteredWorkflow, 'repoIdentifier' | 'providerContext'>): Promise<Record<string, unknown>>;
+/**
+ * A global workflow's lock entry with `jobs` as the job list to dispatch.
+ *
+ * The workflow `filter` was already decided before the run existed — by the
+ * eval round, or by the run a re-run repeats — so it is dropped here. Otherwise
+ * every job would defer to an init job that evaluates it a second time.
+ */
+export declare function dispatchableGlobalWorkflow(lockEntry: LockWorkflow, jobs: readonly LockJobOrFactory[]): LockWorkflow;
+/**
+ * The lock file a global run hands the pipeline: the one workflow it runs, with
+ * the dependency-cache key of the lock file that entry came from.
+ *
+ * The key is what the pipeline probes the dependency cache with, and what the
+ * build job publishes a tarball under, so a global run shares cache entries
+ * with every other run of the same lock. `reg` must describe the lock file
+ * `workflow` came from: a caller that read the entry at another commit passes
+ * that commit's key. A registration that recorded no key installs its
+ * dependencies on the agent.
+ */
+export declare function globalRunLockFile(workflow: LockWorkflow, reg: Pick<RegisteredWorkflow, 'sourceFile' | 'lockfileHash' | 'siblingsDigest'>): WorkflowDispatchContext['fullLockFile'];
+/**
+ * Dispatches one global candidate through the shared pipeline. Returns the run
+ * id, or undefined when no run was created: the workflow repository has no
+ * provider bundle, its credentials cannot be minted, or the candidate has no
+ * job to dispatch.
+ */
+export declare function dispatchGlobalCandidateViaPipeline(args: GlobalCandidateDispatchArgs): Promise<string | undefined>;
+//# sourceMappingURL=global-dispatch.d.ts.map