@kici-dev/orchestrator 0.16.0 → 0.18.0

package/dist/pipeline/remote-source-store.d.ts

@@ -1,21 +1,18 @@
 import type { Kysely } from 'kysely';
 import type { Database, RemoteSourceRow } from '../db/types.js';
 /**
- * Deterministic routing key for an org's Platform-relayed remote runs. A
- * Platform-relayed `test.trigger` carries this key; `resolveOrgId` maps it back
- * to the canonical org id via the `remote_sources` row.
+ * Routing key a Platform-relayed `test.trigger` carries; `resolveOrgId` maps it
+ * back to the org id via the `remote_sources` row.
  */
 export declare function remoteRoutingKeyFor(orgId: string): string;
 /**
- * Idempotently upsert the `remote_sources` anchor for an org. Called on every
- * Platform (re)connect once the orchestrator learns its canonical org id from
- * `auth.success`. The unique `(customer_id)` constraint makes this a safe
- * self-heal — re-running updates `cluster_id` if the cluster identity changed.
+ * Idempotently upsert an org's `remote_sources` anchor on every Platform
+ * (re)connect, after `auth.success`. The unique `(customer_id)` constraint
+ * makes it a self-heal that updates a changed `cluster_id`.
  */
 export declare function provisionRemoteSource(db: Kysely<Database>, params: {
     orgId: string;
     clusterId: string | null;
 }): Promise<void>;
-/** Read the auto-provisioned remote-source row for an org, if it exists. */
 export declare function getRemoteSource(db: Kysely<Database>, orgId: string): Promise<RemoteSourceRow | undefined>;
 //# sourceMappingURL=remote-source-store.d.ts.map

package/dist/pipeline/request-idempotency.d.ts

@@ -1,26 +1,23 @@
 import type { Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 /**
- * Atomically claim a run-minting request by its Platform `requestId`. Returns
- * the run id to use. `claimed: false` means a sibling coordinator already owns
- * this requestId (a relay failover re-sent the same request): the caller MUST
- * return `{ newRunId }` WITHOUT creating or dispatching a run, so one user
- * click yields exactly one run.
+ * Atomically claim a run-minting request by its Platform `requestId`, returning
+ * the run id to use. `claimed: false` means a sibling coordinator owns it (a
+ * relay failover re-send): the caller MUST return `{ newRunId }` WITHOUT
+ * creating or dispatching a run, so one click yields exactly one run.
  *
- * Shared by `run.rerun.request` and `run.manual_schedule.request` — both mint a
- * fresh run and both ride the Platform's timeout-driven failover path. HA
- * coordinator siblings share one orchestrator DB, so the `INSERT … ON CONFLICT
- * (request_id) DO NOTHING` is the single point of arbitration: exactly one hop
- * inserts and wins; the loser reads back the winner's `new_run_id`.
+ * Used by `run.rerun.request` and `run.manual_schedule.request`, which both mint
+ * a run and ride the Platform's timeout-driven failover. HA siblings share one
+ * orchestrator DB, so `INSERT … ON CONFLICT (request_id) DO NOTHING` is the
+ * single arbiter; the loser reads back the winner's `new_run_id`.
  */
 export declare function claimRequestId(db: Kysely<Database>, requestId: string): Promise<{
     newRunId: string;
     claimed: boolean;
 }>;
 /**
- * Prune `request_idempotency` rows older than 1h. The request budget is ~10s,
- * so a claimed requestId is never re-sent after an hour; keeping the table
- * bounded avoids unbounded growth on a long-lived coordinator.
+ * Prune `request_idempotency` rows older than 1h: the request budget is ~10s,
+ * so no claimed requestId is re-sent after an hour, and the table stays bounded.
  *
  * @returns the number of rows deleted.
  */

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

@@ -5,15 +5,14 @@ export declare function isCrossRepoGlobalRun(originalRun: OriginalRunRow): boole
  * Re-run an organization-wide run against the commits it recorded: the source
  * repository at `sha`, and the workflow repository at `workflow_sha`.
  *
- * The workflow is read from the workflow repository's lock file at the recorded
- * commit, through that repository's registration — its provider bundle and
- * provider context — never from the registration's current lock entry, which
- * may have moved on. The run goes through the same pipeline a first global run
- * does, so contexts, holds, approval gates, and the workflow repository's
- * credentials apply exactly as they did.
+ * The workflow is read through the workflow repository's registration (provider
+ * bundle and context) from its lock file at the recorded commit, never from the
+ * registration's current lock entry. It dispatches through the first-run global
+ * pipeline, so contexts, holds, approval gates and the workflow repository's
+ * credentials apply as they did.
  *
  * Refuses, naming the workflow repository, when the run recorded no workflow
- * commit or the workflow is no longer registered there. Nothing falls back to a
+ * commit or the workflow is no longer registered there; nothing falls back to a
  * current lock file.
  */
 export declare function rerunCrossRepoGlobalRun(opts: {

package/dist/pipeline/rerun-inputs.d.ts

@@ -11,9 +11,8 @@ import type { TrustPolicyOutcome } from '../security/trust-policy-gate.js';
 import type { WebhookInfo } from '../webhook/handler.js';
 import type { OriginalRunRow, RerunDeps } from './rerun.js';
 /**
- * Load the original webhook payload from object storage. Returns
- * null for cron/schedule runs (no payload was stored) or when the payload
- * cannot be parsed.
+ * Load the original webhook payload from object storage. Null for cron/schedule
+ * runs (none stored) or an unparseable payload.
  */
 export declare function loadWebhookPayload(originalRunId: string, deps: Pick<RerunDeps, 'logStorage'>): Promise<Record<string, unknown> | null>;
 /** The provider bundle + context a re-run resolves out of the original run's row. */
@@ -23,41 +22,33 @@ export interface RerunProviderBinding {
     routingKey: string;
 }
 /**
- * Resolve the provider bundle and stored provider context for a run being
- * re-run.
- *
- * Shared by the workflow re-run and the evaluation-round re-run so the two
- * cannot disagree about which source a run belongs to, or about how its
- * `provider_context` column is parsed.
+ * Resolve the provider bundle and stored provider context for a re-run. Shared
+ * by the workflow and evaluation-round re-runs so they cannot disagree about a
+ * run's source or how `provider_context` is parsed.
  */
 export declare function resolveRerunProviderBinding(originalRun: OriginalRunRow, deps: Pick<RerunDeps, 'providerRegistry'>): RerunProviderBinding;
 /** How a refusal to rebuild a re-run's inputs names the run and the way forward. */
 export interface RerunRefusal {
-    /** The sentence's opening, naming the run: `Cannot re-run …`. */
+    /** `Cannot re-run …`. */
     subject: string;
-    /** How the run relates to its event: `was deciding` for a round, `ran for` for a run. */
+    /** `was deciding` for a round, `ran for` for a run. */
     eventVerb: string;
-    /** What the caller can do instead. */
     remedy: string;
 }
-/** The refusal wording for a global evaluation round. */
 export declare function roundRefusal(originalRun: OriginalRunRow): RerunRefusal;
 /**
  * The provider event name + action the original delivery carried.
  *
- * `execution_runs` records neither: the event name arrives in a provider header,
- * not in the payload, so it cannot be recovered from the stored payload either.
- * The delivery's own `event_log` row is where it lives, and a round's run row
- * carries the delivery id that addresses it. That row is written at the end of
- * the delivery, after the round's failure is recorded, so it is present for
- * every re-run an operator can actually reach.
+ * Neither `execution_runs` nor the stored payload has it (the event name is a
+ * provider header); it lives in the delivery's `event_log` row, addressed by
+ * the run row's delivery id. That row is written at the end of the delivery,
+ * after the round's failure is recorded, so every reachable re-run has it.
  *
- * Addressed by `(org_id, delivery_id)` — the table's own uniqueness — never by
- * the delivery id alone. A generic source's delivery id is taken verbatim from
- * a sender-supplied header, so one tenant can choose an id another tenant's
- * round already carries; a lookup by id alone would then re-evaluate one org's
- * global workflows against another org's event shape, and with no `ORDER BY`
- * the row it picked would not even be stable.
+ * Addressed by `(org_id, delivery_id)` — the table's uniqueness — never by
+ * delivery id alone: a generic source takes it verbatim from a sender-supplied
+ * header, so one tenant can reuse another's id, and an id-only lookup would
+ * re-evaluate one org's globals against another org's event (and pick an
+ * unstable row, with no `ORDER BY`).
  */
 export declare function loadDeliveryEventName(originalRun: OriginalRunRow, deps: Pick<RerunDeps, 'db'>, refusal?: RerunRefusal): Promise<{
     event: string;
@@ -66,12 +57,10 @@ export declare function loadDeliveryEventName(originalRun: OriginalRunRow, deps:
 /** The verdict an approved security hold stands for. */
 export declare const RELEASED_DECISION: TrustPolicyOutcome;
 /**
- * The normalized form of the delivery the round was deciding, stamped with the
- * repository's default branch as the delivery stamped it: the jobs a re-run
- * dispatches carry this event, and an agent derives a new-branch diff from it.
- *
- * Read-only, and it throws — so it runs before the requestId claim, never
- * inside the re-evaluation.
+ * The normalized delivery the round was deciding, stamped with the default
+ * branch as the delivery stamped it: a re-run's jobs carry this event, and an
+ * agent derives a new-branch diff from it. Read-only and throwing, so it runs
+ * before the requestId claim, never inside the re-evaluation.
  */
 export declare function normalizeRoundEvent(originalRun: OriginalRunRow, providerBundle: NonNullable<ReturnType<ProviderRegistry['getByRoutingKey']>>, delivery: {
     event: string;
@@ -79,12 +68,9 @@ export declare function normalizeRoundEvent(originalRun: OriginalRunRow, provide
 }, payload: Record<string, unknown>, refusal?: RerunRefusal): SimulatedEvent;
 /**
  * Stamp the re-evaluated event with the source repository's default branch and
- * changed files.
- *
- * The resolve is unconditional: the delivery path skips it when no trigger in
- * the source repo's lock file uses path patterns, and a scoped re-evaluation
- * has no such lock file to bound it. A bundle with no fetcher, or a fetch
- * error, carries `unavailable`.
+ * changed files. Unconditional, unlike the delivery path: a scoped
+ * re-evaluation has no source lock file to tell whether path patterns are
+ * used. No fetcher, or a fetch error, carries `unavailable`.
  */
 export declare function withChangedFiles(opts: {
     event: SimulatedEvent;

package/dist/pipeline/rerun.d.ts

@@ -1,13 +1,10 @@
 /**
- * Re-run handler for the orchestrator.
+ * Re-run handler: loads a completed run and its stored webhook payload,
+ * re-fetches the lock file at the original SHA, and dispatches a new run
+ * linked by parent_run_id.
  *
- * Loads an original completed run, retrieves its webhook payload from
- * object storage, re-fetches the lock file at the original SHA, and
- * dispatches a new run with parent_run_id linkage.
- *
- * This is NOT a reuse of processWebhook -- it's a separate, simpler function
- * that skips dedup, normalization, trigger matching, and changed files fetching.
- * It goes directly to: lock file parse -> job expansion -> dispatch.
+ * Deliberately not processWebhook: it skips dedup, normalization, trigger
+ * matching and the changed-files fetch (lock file -> job expansion -> dispatch).
  */
 import { type ColdStore } from '@kici-dev/shared';
 import type { Kysely, Selectable } from 'kysely';
@@ -29,13 +26,10 @@ import type { DepCache } from '../cache/index.js';
 import type { PendingBuildTracker } from '../cache/index.js';
 import type { ProcessingDeps } from './processor.js';
 /**
- * Thrown when a rerun is attempted on a run whose row is absent from PG AND
- * the cold-store replay path failed or is unavailable (chunk missing,
- * contentHash mismatch, S3 outage, or cold-store probe disabled). Signals a
- * genuine "we tried to bring the row back and could not".
- *
- * The WS dashboard handler maps this to a structured response that the
- * Platform proxy surfaces as HTTP 410 (`errorCode: 'runArchivedNotRerunnable'`).
+ * Thrown when the run row is absent from PG AND the cold-store replay failed or
+ * is unavailable (chunk missing, contentHash mismatch, S3 outage, or cold-store
+ * probe disabled). The Platform proxy surfaces it as HTTP 410
+ * (`errorCode: 'runArchivedNotRerunnable'`).
  */
 export declare class RunArchivedNotRerunnableError extends Error {
     readonly runId: string;
@@ -60,71 +54,54 @@ export interface RerunDeps {
     buildCoordinator: BuildCoordinator | null;
     pendingBuilds: PendingBuildTracker | null;
     /**
-     * When set, a PG miss on `originalRunId` triggers a cold-store replay of
-     * the chunk containing the row, then a re-read. `null` keeps the "throw
-     * RunArchivedNotRerunnableError on PG miss" path for deployments without
-     * cold-store wired up.
+     * When set, a PG miss on `originalRunId` replays the row's chunk from cold
+     * store and re-reads; `null` throws RunArchivedNotRerunnableError on a miss.
      */
     coldStore: ColdStore | null;
     /**
-     * The live webhook-processing bag, assembled on demand.
-     *
-     * Only the re-run of a failed global evaluation round needs it: that re-run
-     * re-drives the organization-wide pass, which reaches deps an ordinary
-     * workflow re-run never touches (the registration index, the policy reader,
-     * the pending-eval tracker). Supplied by the entry point that already
-     * assembles the bag for the inbound webhook path, so the two cannot drift.
-     * Absent means round re-runs are not available on this deployment.
+     * The live webhook-processing bag, assembled on demand. Only a failed global
+     * eval round's re-run needs it (it re-drives the organization-wide pass, which
+     * reaches the registration index, policy reader and pending-eval tracker). The
+     * inbound webhook entry point supplies it, so the two cannot drift. Absent
+     * means round re-runs are not available on this deployment.
      */
     processingDeps?: (() => ProcessingDeps) | null;
 }
-/**
- * Original run row from execution_runs (selectAll).
- * Aliased to the Kysely Selectable so all column names stay typed
- * as the underlying schema.
- */
+/** Original run row from execution_runs (selectAll). */
 export type OriginalRunRow = Selectable<ExecutionRunTable>;
 export declare function handleRerun(originalRunId: string, triggeredBy: string | null, triggeredByAgentLabel: string | null, deps: RerunDeps, 
 /**
- * Platform-minted `requestId` for this rerun. Stable across an HA relay
- * failover re-send (the Platform re-sends the same message verbatim to a
- * sibling coordinator on a timeout), so it is the idempotency key: after the
- * read-only validation, the first coordinator to claim it creates the run and
- * a failover re-send returns that same run instead of minting a second one.
+ * Platform-minted idempotency key, stable across an HA relay failover re-send
+ * (the Platform re-sends the same message verbatim to a sibling coordinator on
+ * a timeout). After read-only validation, the first coordinator to claim it
+ * creates the run; a re-send returns that same run.
  */
 requestId: string, 
 /**
- * Routing key for the original run, forwarded by Platform via the WS
- * `run.rerun.request` payload. Required to address the cold-store chunk
- * under the right tenant prefix.
+ * Forwarded by the Platform in `run.rerun.request`; addresses the cold-store
+ * chunk under the right tenant prefix.
  */
 routingKeyHint?: string): Promise<{
     newRunId: string;
 }>;
 /**
- * Settle every detached re-evaluation started so far.
- *
- * Nothing in a running orchestrator calls this — the re-evaluation is detached
- * precisely so no request waits on it. It exists so a caller that needs the
- * work to have finished (a test asserting on the pass) can wait for it
- * deterministically instead of racing the microtask queue.
+ * Settle every detached re-evaluation started so far. A running orchestrator
+ * never calls it; it lets a caller such as a test wait deterministically
+ * instead of racing the microtask queue.
  */
 export declare function settlePendingRoundReevaluations(): Promise<void>;
 /**
- * Release a held global evaluation round: re-evaluate the round of its workflow
- * repository from the stored webhook payload with the approved event treated as
- * passing, dispatch what it admits, and settle the held run.
+ * Release a held global evaluation round: re-evaluate it from the stored payload
+ * with the approved event treated as passing, dispatch what it admits, and
+ * settle the held run.
  *
- * Reached from the security queue's workflow release (`resumeWorkflow`), which
- * recognises the held round by its run row. The held row stores no dispatch
- * context: everything is rebuilt from the row, the payload and the delivery's
- * event log entry — the same reconstruction a re-run of a failed round uses —
- * so the release does not depend on how a workflow dispatch context would be
- * replayed.
+ * Reached from `resumeWorkflow`. The held row stores no dispatch context, so
+ * everything is rebuilt from the row, the payload and the delivery's event log
+ * entry — the same reconstruction a failed round's re-run uses.
  *
  * Never throws. A round that cannot be rebuilt or decided fails the held run
- * with the reason, which is the record an approver can read. A release that
- * cannot claim the held row — another release already did — does nothing.
+ * with the reason an approver reads. A release that cannot claim the held row
+ * (another release did) does nothing.
  */
 export declare function releaseHeldGlobalEvalRound(runId: string, deps: ProcessingDeps): Promise<void>;
 //# sourceMappingURL=rerun.d.ts.map

package/dist/pipeline/resolve-sandbox-grant.d.ts

@@ -5,10 +5,7 @@ export interface SandboxRequest {
     capabilities?: string[];
     network?: SandboxNetworkMode;
 }
-/**
- * The resolution outcome: either an authorized grant (possibly `undefined` when
- * the request is a no-op / non-escalating) or a total, loud denial.
- */
+/** An authorized grant (`undefined` for a no-op / non-escalating request) or a total denial. */
 export type SandboxGrantResolution = {
     grant?: ResolvedSandboxGrant;
 } | {
@@ -17,12 +14,10 @@ export type SandboxGrantResolution = {
     };
 };
 /**
- * Resolve a workflow-declared sandbox request against the operator's allow-list
- * (the single enforcement point). Deny is loud and total — a request for any
- * capability or host-network the operator did not allow-list fails the run with
- * a reason naming the offending cap/knob; a disallowed cap is never silently
- * stripped and run anyway. Pure (no I/O), so the allow-list is injected and the
- * function is exhaustively unit-testable.
+ * The single enforcement point of a sandbox request against the operator's
+ * allow-list. Deny is loud and total: any capability or host-network not
+ * allow-listed fails the run with a reason naming it; a disallowed cap is never
+ * silently stripped and run anyway. Pure: the allow-list is injected.
  */
 export declare function resolveSandboxGrant(request: SandboxRequest | undefined, allowList: SandboxAllowList): SandboxGrantResolution;
 //# sourceMappingURL=resolve-sandbox-grant.d.ts.map

package/dist/pipeline/resume-workflow.d.ts

@@ -25,25 +25,22 @@ export type RebuiltWorkflowDispatchContext = Omit<WorkflowDispatchContext, 'glob
     global?: UnmintedGlobalIdentity;
 };
 /**
- * Rebuild a live `WorkflowDispatchContext` from the persisted serializable
- * inputs by re-attaching the orchestrator's live `deps` and reconstructing the
- * provider `bundle` from the live registry (keyed by the stored routing key).
- * Returns null when the provider bundle can no longer be resolved.
+ * Rebuild a dispatch context from the persisted inputs, re-attaching the live
+ * `deps` and the provider `bundle` from the live registry. Returns null when
+ * the provider bundle, or a global run's workflow bundle, no longer resolves.
  *
- * A global run's identity is rebuilt from what was stored at hold time — the
- * workflow commit, branch and provider context it was held at — never from the
- * live registration, which may have moved to a newer commit while the run
- * waited. Its workflow bundle is looked up by the stored workflow routing key,
- * and it has no credentials until {@link withWorkflowRepoCredentials} mints
- * them. Returns null when the workflow bundle can no longer be resolved either.
+ * A global run's identity comes from what was stored at hold time (workflow
+ * commit, branch, provider context), never from the live registration, which
+ * may have moved on while the run waited. Its workflow bundle is looked up by
+ * the stored workflow routing key, and it has no credentials until
+ * {@link withWorkflowRepoCredentials} mints them.
  *
- * The key it looks the bundle up by is `effectiveRoutingKey ?? info.routingKey`
- * — the post-overlay key, the same one `setupDispatchContext` builds
- * `setup.info` from and the same one the run row records. `info.routingKey` is
- * the INBOUND key and never carries the overlay, so on a cross-source or
- * fallback-resolved dispatch it names the source the event arrived on rather
- * than the source the workflow belongs to: the resumed run would get the wrong
- * app, the wrong credentials, and a check poster writing to the wrong place.
+ * The bundle key is `effectiveRoutingKey ?? info.routingKey` — the post-overlay
+ * key `setupDispatchContext` builds `setup.info` from and the run row records.
+ * `info.routingKey` is the INBOUND key and never carries the overlay, so on a
+ * cross-source or fallback-resolved dispatch it names the source the event
+ * arrived on: the resumed run would get the wrong app, the wrong credentials,
+ * and a check poster writing to the wrong place.
  */
 export declare function rebuildWorkflowDispatchContext(inputs: SerializableWorkflowDispatchInputs, deps: ProcessingDeps): RebuiltWorkflowDispatchContext | null;
 /**
@@ -64,28 +61,25 @@ export declare function resumeWorkflow(signal: ReleaseSignal, deps: ProcessingDe
  * the run cancelled, complete the check runs the dispatch already posted, and
  * drop the pending context.
  *
- * The check runs are completed `cancelled`, matching the run row this writes —
- * `cancelHeldRun` sets `execution_runs.status` to `cancelled` with failure class
- * `cancelled`. Without this the workflow and per-job checks stay `queued` on the
- * commit for a run that will never start; see `completeUndispatchedHoldChecks`.
- * It runs before the delete because the pending context is what the check-run
- * names are derived from.
+ * The check runs complete `cancelled`, matching the run row `cancelHeldRun`
+ * writes (status and failure class `cancelled`); otherwise they stay `queued`
+ * for a run that never starts (see `completeUndispatchedHoldChecks`). This runs
+ * before the delete because the check-run names derive from the pending context.
  *
  * The hold row decides whether the `KiCI Security` check is terminalized too:
  * the trust policy's PR-wide hold and the SDK's workflow-level `requireApproval`
  * each posted one pending, while the install gate posted none and must not have
- * one fabricated. That is `postedPendingSecurityCheck`'s job — see it for the
- * per-shape derivation, and for why `queue_type` cannot make the distinction.
+ * one fabricated. See `postedPendingSecurityCheck` for the per-shape derivation
+ * and why `queue_type` cannot make the distinction.
  *
- * This is the single writer of that check for a rejection, on both surfaces the
- * shared applier serves: the dashboard / CLI / MCP reject reaches it through
- * `applyDecision`'s `onWorkflowReject`, and `/kici reject` through the comment
- * handler's. Both therefore render identically on the pull request, and the
- * summary below is the one both check families carry. The returned boolean says
- * whether a security check was actually WRITTEN, so a caller suppresses its own
- * post on the strength of a write rather than of a delegate resolving —
- * a rejection this declines to report (an install gate, or a commit whose other
- * holds are still pending) leaves the caller free to decide for itself.
+ * This is the single writer of that check for a rejection on both surfaces: the
+ * dashboard / CLI / MCP reject (via `applyDecision`'s `onWorkflowReject`) and
+ * `/kici reject` (via the comment handler's), so both render identically and
+ * both check families carry the summary below. The returned boolean says whether
+ * a security check was actually WRITTEN, so a caller suppresses its own post on
+ * a write rather than on a delegate resolving; a rejection this declines to
+ * report (an install gate, or a commit whose other holds are still pending)
+ * leaves the caller free to decide.
  */
 export declare function rejectWorkflow(hold: SecurityCheckHold, deps: ProcessingDeps, db: Kysely<Database> | undefined, reason: string, opts?: {
     runHeld?: boolean;

package/dist/pipeline/route-or-dispatch-jobs.d.ts

@@ -1,13 +1,8 @@
 /**
- * Shared coordinator-route / direct-dispatch machinery for the orchestrator
- * pipeline.
- *
- * The re-run path (`rerun.ts`) and the manual-schedule path
- * (`manual-schedule.ts`) both materialize a workflow's static jobs, try to
- * route them through the cluster coordinator (local dispatch first, then
- * reroute to peers), fall back to direct local dispatch in standalone mode or
- * on a coordinator timeout, and synthesize records for rejected jobs. This
- * module implements that once so a fix lands in a single place.
+ * Shared coordinator-route / direct-dispatch machinery for `rerun.ts` and
+ * `manual-schedule.ts`: materialize static jobs, route through the cluster
+ * coordinator (local first, then peers), fall back to direct local dispatch in
+ * standalone mode or on a coordinator timeout, and synthesize rejected records.
  */
 import { createLogger } from '@kici-dev/shared';
 import type { LockJob, MaterializedJob } from '@kici-dev/engine';
@@ -21,24 +16,22 @@ export interface DispatchedJobEntry {
     matrixValues?: Record<string, unknown>;
     runsOnLabels?: string[];
     /**
-     * The unexpanded job name a materialized child came from. Persisted to
-     * `execution_jobs.base_job_name`, which is the key the rolling-wave scheduler
-     * groups a wave's children by — a NULL there makes the wave gate bail.
+     * Unexpanded job name of a materialized child, persisted to
+     * `execution_jobs.base_job_name`: the rolling-wave scheduler groups a wave by it,
+     * and a NULL makes the wave gate bail.
      */
     baseJobName?: string;
     /**
-     * `gate` marks an invoke-gate row (runs the gate executor, never an agent).
-     * The global-workflow dispatch path registers a gate as a synthetic pending
-     * row and carries its kind through to `execution_jobs.job_kind`.
+     * `gate` marks an invoke-gate row (gate executor, never an agent). The
+     * global-workflow dispatch path carries it to `execution_jobs.job_kind`.
      */
     jobKind?: JobKind;
     /** For a gate job, its wall-clock timeout in ms (orchestrator-swept). */
     timeoutMs?: number;
     /**
-     * The `gitCredentials` map this job's lock entry declared, verbatim.
-     * Persisted to `execution_jobs.git_credentials`, which the credential relay
-     * authorizes a workflow-supplied ref against. Dropping it here would refuse
-     * every declared credential on a job this path registered.
+     * The lock entry's `gitCredentials`, verbatim, persisted to
+     * `execution_jobs.git_credentials`; the credential relay authorizes against it,
+     * so dropping it refuses every declared credential.
      */
     gitCredentials?: Readonly<Record<string, Readonly<Record<string, string>>>>;
 }
@@ -48,7 +41,7 @@ export interface RejectedJobEntry {
 }
 export interface RouteOrDispatchOptions {
     newRunId: string;
-    /** Static jobs before materialization — the helper materializes + handles FanoutError. */
+    /** Unmaterialized; the helper materializes and handles FanoutError. */
     staticJobs: LockJob[];
     workflowName: string;
     repoUrl: string;
@@ -62,18 +55,17 @@ export interface RouteOrDispatchOptions {
     runContext: RunContext;
     /** Per-caller jobConfig shape (schedule dispatchInputs vs. rerun source fallback). */
     buildJobConfig: (mat: MaterializedJob) => Record<string, unknown>;
-    /** Caller's own logger — keeps the originating prefix ('manual-schedule' / 'rerun'). */
+    /** Keeps the caller's log prefix ('manual-schedule' / 'rerun'). */
     logger: ReturnType<typeof createLogger>;
-    /** Human label used in log messages: 'Manual schedule' | 'Re-run'. */
+    /** Log label: 'Manual schedule' | 'Re-run'. */
     label: string;
     coordinator: RunCoordinator | null;
     dispatcher: Dispatcher;
 }
 /**
- * Materialize the static jobs (degrading gracefully on a matrix that can no
- * longer expand), then route them via the coordinator or, in standalone mode /
- * on a coordinator timeout, dispatch directly. Returns the jobs to register
- * with the execution tracker plus any synthetic-rejected IDs to mark failed.
+ * Materialize (degrading on a matrix that can no longer expand), then route via
+ * the coordinator or dispatch directly. Returns jobs to register plus
+ * synthetic-rejected IDs to mark failed.
  */
 export declare function routeOrDispatchJobs(opts: RouteOrDispatchOptions): Promise<{
     dispatchedJobs: DispatchedJobEntry[];
@@ -85,9 +77,6 @@ export interface RegisterDispatchedJobsOptions {
     rejectedJobs: RejectedJobEntry[];
     executionTracker: ExecutionTracker;
 }
-/**
- * Register dispatched jobs with the execution tracker, then mark any
- * synthetic-rejected jobs failed. No-op when nothing was dispatched.
- */
+/** Register dispatched jobs, then fail synthetic-rejected ones. No-op when none dispatched. */
 export declare function registerDispatchedJobs(opts: RegisterDispatchedJobsOptions): Promise<void>;
 //# sourceMappingURL=route-or-dispatch-jobs.d.ts.map

package/dist/pipeline/run-event-context.d.ts

@@ -1,11 +1,10 @@
 /**
  * Resolve the pull-request head context an `execution_runs` row records.
  *
- * `execution_runs.ref` is the branch a run PRESENTS — the BASE branch for a
- * pull request — so it says which branch a run targeted and nothing about where
- * the code came from. These three fields are the missing half, and the OIDC
- * mint reads them: without them a fork pull request and a trusted push to the
- * same base branch mint an identical identity.
+ * `execution_runs.ref` is the branch a run PRESENTS (the BASE branch for a pull
+ * request), saying nothing about where the code came from. The OIDC mint reads
+ * these fields: without them a fork pull request and a trusted push to the same
+ * base branch mint an identical identity.
  */
 import { type SimulatedEvent } from '@kici-dev/engine';
 export interface RunEventContext {
@@ -16,24 +15,20 @@ export interface RunEventContext {
 /**
  * Derive the head context from a normalized event.
  *
- * `isFork` is resolved from the event TYPE, not from the presence of the
- * optional flag. A push, tag or schedule has no fork dimension, so `false` is
- * its true resolved value — not a stand-in. Leaving those unresolved would make
- * every `is_fork = 'false'` cloud trust policy reject legitimate pushes, and the
- * customer's fix for that (accepting `'unresolved'` too) would re-open the hole
- * the claim exists to close.
+ * `isFork` follows the event TYPE, not the optional flag's presence: a push, tag
+ * or schedule has no fork dimension, so `false` is its true value. Leaving it
+ * unresolved would make every `is_fork = 'false'` cloud trust policy reject
+ * legitimate pushes, and the customer's fix (also accepting `'unresolved'`)
+ * would re-open the hole the claim closes.
  *
- * NULL survives for exactly one case: a PR-family event whose payload carries
- * no head repository, so the fork question genuinely has no answer. A lost
- * write leaves all three NULL, which every claim renders as unresolved and a
- * policy that pins them therefore fails closed.
+ * NULL survives only for a PR-family event whose payload has no head
+ * repository. A lost write leaves all three NULL, which every claim renders as
+ * unresolved, so a policy pinning them fails closed.
  *
- * The head repository is what decides that case, NOT the presence of the
- * `isForkPR` flag. Every normalizer derives that flag as `head !== base`, which
- * collapses to `false` when the payload names no head repository — a deleted
- * fork, or a trimmed payload. Reading the flag alone would therefore publish
- * `is_fork = 'false'` for a pull request nobody resolved, which is the fail-OPEN
- * direction this claim exists to remove.
+ * The head repository decides that case, NOT the `isForkPR` flag: normalizers
+ * derive it as `head !== base`, which collapses to `false` with no head
+ * repository (a deleted fork, a trimmed payload), and would publish
+ * `is_fork = 'false'` unresolved — the fail-OPEN direction.
  */
 export declare function resolveRunEventContext(event: Pick<SimulatedEvent, 'type' | 'sourceBranch' | 'headRepo' | 'isForkPR'>): RunEventContext;
 //# sourceMappingURL=run-event-context.d.ts.map