@kici-dev/orchestrator 0.16.0 → 0.18.0

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

@@ -1,34 +1,27 @@
 /**
- * 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.
+ * Dispatches an internally-triggered workflow through the SHARED pipeline
+ * (`dispatchMatchedWorkflow`), never a bespoke path: a bespoke path resolves no
+ * bound contexts (no context vars, scoped secrets or protection rules) and drops
+ * every non-static job.
  */
 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).
+ * The LIFECYCLE event names the orchestrator emits to itself. The `__` prefix
+ * keeps them from colliding with a user `kiciEvent()` name; each maps onto a
+ * canonical trigger-event type (`__schedule_fire` 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.
+ * NOT every orchestrator-minted event (the scaler manager mints two more under
+ * the other reserved prefix), and NOT the trusted set: two of these four are
+ * caused by a run and inherit its tier — trust classification reads
+ * `ORCHESTRATOR_MINTED_TRUSTED_EVENT_NAMES`.
  *
- * 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.
+ * NOT yet the single source: `cron/cron-scheduler.ts`, `events/event-emitter.ts`
+ * and `events/event-router.ts` still spell the names inline. 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";
@@ -37,10 +30,9 @@ export declare const InternalSystemEventName: z.ZodEnum<{
     __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.
+ * Context for dispatching one internally-triggered workflow. Declared here, not
+ * in `orchestrator-core.ts`: the adapter defines the shape and the composition
+ * root imports it.
  */
 export interface InternalEventDispatchContext {
     event: {
@@ -54,49 +46,44 @@ export interface InternalEventDispatchContext {
     providerType: 'github' | undefined;
     /**
      * Provider bundle for the acting repository, resolved by the composition root
-     * from the live registry.
+     * from the live registry; it also carries the clone-token provider and the
+     * check-status poster.
      *
      * 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.
+     * downstream resolves a bundle from `deps.providerRegistry`. `undefined`
+     * 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 clones `''`.
      *
-     * 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.
+     * Legitimately `undefined` when the event carries no routing key, or the
+     * registry has no bundle for it.
      */
     bundle: ProviderBundle | undefined;
     cronCommitSha: string;
     /**
-     * The default branch of the registration this event dispatches, or `null`
-     * when it was never captured.
+     * The registration's default branch, or `null` when 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.
+     * branch IS the run's branch for a context's branch restrictions. `null`
+     * presents no branch and the gate 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.
+     * The run that summoned this one through an invoke gate. Set ONLY by the
+     * invoke-gate summon path, whose synthesized event id matches no
+     * `kici_events` row; naming the emitting run directly lets the summoned run
+     * inherit its summoner's trust tier instead of 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.
+     * Chain depth to stamp on the started run: unset (0) for a webhook-triggered
+     * run, the summoner's depth + 1 for an invoke-gate summon, so the chain-depth
+     * circuit breaker bounds recursion.
      */
     chainDepth?: number;
 }
@@ -118,19 +105,15 @@ export declare function deriveInternalEventIdentity(eventName: 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.
+ * True when every tier the schema admits carries a rank. Only false if the two
+ * drift through a cast; exported so a test asserts it against the live
+ * `TrustTierSchema.options`, not a transcription of it.
  */
 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.
+ * pipeline. Returns `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;

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

@@ -1,22 +1,20 @@
 /**
- * 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
+ * Invoke-gate executor. An invoke gate is a standard job whose only novel
+ * attribute is `invoke`: it never dispatches steps to an agent. When 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.
+ * One orchestrator serves one org, so match-and-dispatch is synchronous and
+ * in-process through an injected `summon` callback that returns the spawned run
+ * ids. It ALSO persists `summoned_by_run_id` / `summoned_by_proxy_job` on each
+ * spawned run so proxy completion 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.
+ * The gate is the aggregating graph node: downstream `needs` edges point at it,
+ * 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';
@@ -47,24 +45,20 @@ export declare function invokeParamsFromLockJob(lockJob: Pick<LockJob, 'invoke'
 /** 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.
+ * A summon that was REFUSED, as opposed to one that matched nothing. An
+ * `optional: true` gate treats zero summoned runs as a green skip, so a refusal
+ * returned as `[]` would report success for declined work. 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. */
@@ -85,12 +79,9 @@ export interface InvokeGateDeps {
     /**
      * 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.
+     * root, reusing the orchestrator's event match + trust-policy path. An empty
+     * array means no subscriber matched (a gate may declare that `optional`); a
+     * REFUSAL raises {@link SummonRefusedError} instead.
      */
     summon: (args: SummonArgs) => Promise<SummonedRun[]>;
     /** Max chain depth allowed for a summon (the circuit breaker's bound). */
@@ -123,21 +114,18 @@ export declare function aggregateGateStatus(proxyStatuses: readonly string[]): {
     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.
+ * The message a gate naming a reserved event fails with; exported so the
+ * executor, its test and the SDK-side error compare against one string.
  */
 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**:
+ * The proxy job name for a summoned run. The run id makes it **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`).
+ * resolve one proxy and leave the other hanging. The graph label lives in
+ * `variant_label` (`repo:workflow`).
  */
 export declare function proxyJobName(gateJobName: string, run: SummonedRun): string;
 /**
@@ -155,10 +143,9 @@ export interface ReleaseInvokeGateDeps {
 }
 /**
  * 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.
+ * `gate` job row, then run the executor with the source repo and chain depth
+ * (which bounds recursion) read from `execution_runs`. Shared by the
+ * needs-release path (`dispatchReadyJob`) and the root-gate post-registration nudge.
  */
 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,54 +3,41 @@
  *
  * A job binds an ordered list of contexts: the workflow-level names
  * (`LockWorkflow.contexts`) first, then its own (`LockJob.contexts`). This
- * module resolves that list into concrete context names (static values
- * 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.
+ * module resolves that list (dynamic elements via the agent's init job) and
+ * folds per-context secrets/variables last-wins, keeping that fold out of
+ * `dispatchMatchedWorkflow`, which must stay under the function-length cap.
  */
 import { type Context, type HostFacts, type LockJob, type LockWorkflow } 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 a dynamic element
- * the orchestrator does not resolve at dispatch. The agent's init eval later
- * overwrites the list with the resolved name.
+ * Persisted bound-env placeholder for a dynamic element; the agent's init eval
+ * later overwrites it 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 names, in order. */
     names: string[];
-    /** True when a dynamic element must be resolved by an agent init job. */
+    /** A dynamic element must be resolved by an agent init job. */
     needsInit: boolean;
 }
 /** One bound-context element, as a lock job carries it. */
 export type ContextRef = NonNullable<LockJob['contexts']>[number];
 /**
- * The ordered context elements a job binds: the workflow-level names first,
- * then the job's own. Placing the workflow names first means a job-level
- * context wins a key collision, since later contexts override earlier ones.
+ * The ordered context elements a job binds: workflow-level names first, so a
+ * job-level context wins a key collision.
  *
- * A workflow-level name the job also binds statically is dropped from the
- * workflow part, so each context is gated and resolved once, at the job's own
- * position. Every gating site reads its names through this function, so a
- * workflow-level context passes the same gates a job-level one does.
+ * A workflow-level name the job also binds statically is dropped, so each
+ * context is gated and resolved once, at the job's position. Every gating site
+ * reads through this function, so workflow-level contexts pass the same gates.
  */
 export declare function effectiveContextRefs(workflow: Pick<LockWorkflow, 'contexts'>, job: Pick<LockJob, 'contexts'>): ContextRef[];
-/**
- * Resolve the ordered bound-context names from a lock job and its workflow. Static elements
- * use their value verbatim; a dynamic element is resolved by the agent's init
- * job and flags `needsInit`.
- */
+/** Static elements use their value verbatim; a dynamic element flags `needsInit`. */
 export declare function resolveJobContextNames(workflow: Pick<LockWorkflow, 'contexts'>, lockJob: Pick<LockJob, 'contexts'>): 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, 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.
+ * Build the ordered bound-context display list persisted at dispatch. Unlike
+ * {@link resolveJobContextNames}, a dynamic element becomes the `(dynamic)`
+ * placeholder rather than being dropped, so every declared slot is kept in order.
  */
 export declare function buildJobContextDisplayNames(workflow: Pick<LockWorkflow, 'contexts'>, lockJob: Pick<LockJob, 'contexts'>): string[];
 /** Merged secrets/variables across an ordered list of resolved contexts. */
@@ -60,14 +47,10 @@ export interface MultiEnvMergedData {
     jobNamespacedSecrets?: Record<string, Record<string, string>>;
 }
 /**
- * Resolve and fold variables + secrets across the ordered list of matched
- * contexts, last-wins. Each context is resolved with the existing
- * single-env logic (longest-scope-path-wins preserved within each context),
- * then folded in array order so a later context overrides an earlier key.
- * Secrets are also returned namespaced per context so qualified
- * `<env>:<secret>` references still resolve. `entries` carries the matched
- * `Context` for each name (in order); variables and secrets both resolve by the
- * matched context's id, so a glob context contributes what its own row holds.
+ * Resolve and fold variables + secrets across the matched contexts, last-wins
+ * (longest-scope-path-wins within each context). Secrets are also returned
+ * namespaced per context so qualified `<env>:<secret>` references resolve. Both
+ * resolve by the matched row's id, so a glob context contributes its own row.
  */
 export declare function resolveMultiEnvMergedData(args: {
     deps: {

package/dist/pipeline/manual-schedule.d.ts

@@ -1,13 +1,8 @@
 /**
- * Manual schedule handler for the orchestrator.
- *
- * Dispatches a new run for a cron-scheduled workflow triggered manually
- * from the dashboard UI. Uses direct dispatch (not eventRouter.emit) so
- * the newRunId can be returned synchronously in the WS response.
- *
- * This is intentionally separate from the automatic cron path which uses
- * eventRouter fire-and-forget. The manual path needs request/response
- * correlation to return the newRunId to the dashboard.
+ * Dispatches a new run for a cron-scheduled workflow triggered manually from
+ * the dashboard. It dispatches directly, not through the fire-and-forget
+ * `eventRouter.emit` the automatic cron path uses, so the WS response can
+ * return the newRunId synchronously.
  */
 import type { LockScheduleTrigger, LockWorkflow, MaterializedJob } from '@kici-dev/engine';
 import type { RerunDeps } from './rerun.js';
@@ -17,10 +12,9 @@ interface ManualScheduleDeps extends RerunDeps {
 }
 export declare function handleManualSchedule(registrationId: string, triggeredBy: string | null, triggeredByAgentLabel: string | null, deps: ManualScheduleDeps, 
 /**
- * Platform-minted `requestId`. Stable across an HA relay failover re-send, 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 first coordinator to claim it creates the run, and a re-send
+ * returns that same run.
  */
 requestId: string): Promise<{
     newRunId: string;

package/dist/pipeline/needs-scheduler.d.ts

@@ -1,17 +1,15 @@
 /**
  * DB-backed needs-aware dispatch scheduler.
  *
- * Gates ALL needs edges (static-to-static, static-to-dyn-group, dyn-to-static,
- * dyn-to-dyn) with event-driven scheduling instead of concurrent dispatch.
+ * Gates ALL needs edges (static and dynamic-group, either side) with
+ * event-driven scheduling instead of concurrent dispatch.
  *
- * The scheduler is pure DB — no in-memory state. Every scheduling decision is
- * a fresh DB query against execution_jobs + execution_job_needs. This means
- * zero recovery code on orchestrator restart.
+ * Pure DB, no in-memory state: every decision is a fresh query against
+ * execution_jobs + execution_job_needs, so a restart needs no recovery code.
  *
- * Each edge carries a `run_on` status-set (the upstream terminal statuses that
- * satisfy the edge). A downstream edge is dispatch-satisfied when the upstream's
- * terminal status is a member of the edge's run_on set; otherwise the downstream
- * is skipped. A downstream dispatches only when every edge is satisfied.
+ * Each edge carries a `run_on` set of upstream terminal statuses. An upstream
+ * status outside the set skips the downstream; a downstream dispatches only when
+ * every edge is satisfied.
  *
  * Entry points:
  * - insertEdgesForRun: called at run start for static-to-static edges
@@ -32,12 +30,9 @@ export interface SchedulerResult {
     reason?: string;
 }
 /**
- * Check if ALL upstreams of a job are satisfied.
- * Returns { satisfied: true, action: 'dispatch' } when every upstream is
- * terminal and its status is a member of the edge's run_on set. Returns
- * { satisfied: true, action: 'skip', reason } when an upstream is terminal but
- * its status is not in the edge's run_on set. Returns { satisfied: false } when
- * any upstream is not yet terminal.
+ * Check if ALL upstreams of a job are satisfied: `satisfied: false` while any
+ * is non-terminal, `action: 'skip'` when a terminal status is outside its
+ * edge's run_on, otherwise `action: 'dispatch'`.
  */
 export declare function checkAllUpstreamsSatisfied(db: Kysely<Database>, runId: string, jobName: string): Promise<{
     satisfied: boolean;
@@ -47,28 +42,22 @@ export declare function checkAllUpstreamsSatisfied(db: Kysely<Database>, runId:
 /**
  * Insert dependency edges at run start for static-to-static needs.
  *
- * Operates on materialized jobs (matrix-expanded children) and an expansion map
- * (base job name -> the expanded child names). An upstream reference to a base
- * name `test` that fanned into `test (a)` / `test (b)` produces one edge per
- * child, so a downstream `needs: ['test']` waits for ALL children to terminate.
- * Each materialized child likewise inherits the full upstream edge set under its
- * own expanded name.
+ * An upstream base name `test` fanned into `test (a)` / `test (b)` yields one
+ * edge per child, so `needs: ['test']` waits for ALL children; each
+ * materialized child inherits the full upstream edge set under its expanded name.
  *
- * NeedsGroupEntry items are skipped (resolved later via resolveGroupEdges).
- * Root jobs (no needs, no dependsOnGroups) are marked needs_satisfied=true,
- * keyed by expanded name.
+ * NeedsGroupEntry items wait for resolveGroupEdges. Root jobs (no needs, no
+ * dependsOnGroups) are marked needs_satisfied=true.
  */
 export declare function insertEdgesForRun(db: Kysely<Database>, runId: string, jobs: readonly MaterializedJob[], expansionMap: ReadonlyMap<string, readonly string[]>): Promise<void>;
 /**
  * Resolve dynamic group edges after eval completion.
  *
- * For each dependent static job and each member job name, inserts a concrete
- * edge row. Empty groups (0 members) trigger immediate needs_satisfied=true
- * for dependents.
+ * Inserts one edge per (dependent, member); an empty group satisfies its
+ * dependents immediately.
  *
- * CRITICAL: dependentStaticJobs carries the per-job run_on status-set from the
- * NeedsGroupEntry in the lock file. Without this, all group edges would
- * silently default to success-only.
+ * CRITICAL: dependentStaticJobs carries each NeedsGroupEntry's run_on set;
+ * without it every group edge silently defaults to success-only.
  */
 export declare function resolveGroupEdges(db: Kysely<Database>, runId: string, groupName: string, memberJobNames: string[], dependentStaticJobs: Array<{
     jobName: string;
@@ -77,33 +66,27 @@ export declare function resolveGroupEdges(db: Kysely<Database>, runId: string, g
 /**
  * Evaluate downstream jobs after an upstream reaches terminal state.
  *
- * This is the core scheduler hook. For each downstream of the completed job:
- * 1. If the completed status is not in this edge's run_on set, mark the
- *    downstream as 'skip' immediately.
- * 2. Otherwise, check if ALL upstreams are terminal and satisfied.
- * 3. If all satisfied, mark needs_satisfied=true and return for dispatch.
+ * The core scheduler hook: a downstream whose edge's run_on excludes the
+ * completed status skips; one whose upstreams are all satisfied is claimed and
+ * returned for dispatch.
  */
 export declare function evaluateDownstreams(db: Kysely<Database>, runId: string, completedJobName: string, completedStatus: string): Promise<SchedulerResult[]>;
 /**
- * Batch recompute needs_satisfied for specified jobs.
- * Used after group resolution and on orchestrator restart recovery.
- * Returns scheduler results for any jobs that became ready.
+ * Batch recompute needs_satisfied, after group resolution and on restart
+ * recovery. Returns results for jobs that became ready.
  */
 export declare function recomputeNeedsSatisfied(db: Kysely<Database>, runId: string, jobNames: string[]): Promise<SchedulerResult[]>;
 /**
  * Layer 3: defensive scheduler invariant check.
  *
- * Finds jobs that are stuck: needs_satisfied=false, status='pending',
- * all upstreams are terminal, and no pending group resolution.
- * Returns the names of stuck jobs (empty array = no violation).
+ * Returns stuck jobs: needs_satisfied=false, pending, every upstream terminal,
+ * and no group resolution pending.
  */
 export declare function checkSchedulerInvariant(db: Kysely<Database>, runId: string): Promise<string[]>;
 /**
- * Failure-propagation cascade: find all transitive downstreams that should be
- * skipped because a terminal upstream's status is not in their edge's run_on
- * set. At each hop, the propagating job's actual terminal status decides which
- * downstream edges propagate (status not in run_on → the downstream skips and
- * propagates further).
+ * Failure-propagation cascade: every transitive downstream to skip. At each hop
+ * the propagating job's own terminal status decides: outside an edge's run_on,
+ * the downstream skips and propagates further.
  */
 export declare function getFailurePropagationTargets(db: Kysely<Database>, runId: string, failedJobName: string): Promise<string[]>;
 //# sourceMappingURL=needs-scheduler.d.ts.map

package/dist/pipeline/pending-workflow-context.d.ts

@@ -1,32 +1,25 @@
 /**
- * Pending workflow dispatch context store — the workflow-level analogue of the
- * `pending_job_contexts` store. Persists the serializable inputs of a
- * `WorkflowDispatchContext` so a workflow whose install gate held can be
- * resumed (reviewer approve, wait-timer expiry, concurrency slot free) by
- * rebuilding the dispatch context and re-running `dispatchMatchedWorkflow`.
+ * Pending workflow dispatch context store, the workflow-level analogue of
+ * `pending_job_contexts`: persists a held workflow's serializable dispatch
+ * inputs so it can resume (reviewer approve, wait-timer expiry, concurrency
+ * slot free) by re-running `dispatchMatchedWorkflow`. The live `deps` and
+ * `bundle` are rebuilt on resume, never persisted.
  *
- * Only the serializable inputs are stored — the live `deps` (ProcessingDeps)
- * and `bundle` (ProviderBundle) are NOT persisted; they are rebuilt from the
- * live orchestrator on resume.
- *
- * Writes to both an in-memory Map (fast read on the same process) and the DB
- * (crash recovery + cross-orchestrator read), mirroring the pending-job store.
+ * Writes to an in-memory Map (same-process reads) and the DB (crash recovery,
+ * cross-orchestrator reads).
  */
 import { type Kysely } from 'kysely';
 import type { Database } from '../db/types.js';
 import type { WorkflowDispatchContext } from './dispatch-matched-workflow.js';
 import { type SerializableGlobalDispatchIdentity } from './global-dispatch-identity.js';
 /**
- * The serializable subset of a `WorkflowDispatchContext` — everything except
- * the live `deps` and `bundle`, which are rebuilt on resume. Every field here
- * is JSON-safe (the event, payload, and lock file already ride the WS protocol
- * as JSON). A global run's identity is stored without its workflow bundle and
- * credentials, which the resume re-derives.
+ * The JSON-safe subset of a `WorkflowDispatchContext`. A global run's identity
+ * is stored without its workflow bundle and credentials, which the resume
+ * re-derives.
  */
 export type SerializableWorkflowDispatchInputs = Omit<WorkflowDispatchContext, 'deps' | 'bundle' | 'global'> & {
     global?: SerializableGlobalDispatchIdentity;
 };
-/** Stored inputs as a read returns them. */
 export type LoadedWorkflowDispatchInputs = SerializableWorkflowDispatchInputs & {
     /**
      * Set when the row's sealed secret fields could not be decrypted; the
@@ -34,23 +27,16 @@ export type LoadedWorkflowDispatchInputs = SerializableWorkflowDispatchInputs &
      */
     secretsUnavailable?: string;
 };
-/** Extract the serializable inputs from a live dispatch context. */
 export declare function toSerializableInputs(ctx: WorkflowDispatchContext): SerializableWorkflowDispatchInputs;
-/** Persist the pending workflow context to the in-memory Map and the DB. */
 export declare function storePendingWorkflowContext(db: Kysely<Database> | undefined, inputs: SerializableWorkflowDispatchInputs): Promise<void>;
-/** Load the pending workflow context by run id (memory first, then DB). */
+/** Memory first, then DB. */
 export declare function loadPendingWorkflowContext(db: Kysely<Database> | undefined, runId: string): Promise<LoadedWorkflowDispatchInputs | null>;
-/** Delete the pending workflow context from the in-memory Map and the DB. */
 export declare function deletePendingWorkflowContext(db: Kysely<Database> | undefined, runId: string): Promise<void>;
 /**
- * Restore the in-memory Map from the DB on startup, skipping rows whose run has
- * already reached a terminal state. Mirrors `restorePendingJobContexts`.
- * Returns the number of restored contexts.
+ * Restore the in-memory Map from the DB on startup, mirroring
+ * `restorePendingJobContexts`. Returns the number restored.
  */
 export declare function restorePendingWorkflowContexts(db: Kysely<Database>): Promise<number>;
-/**
- * Clear all entries from the in-memory pending workflow contexts Map.
- * @internal Exported for testing only.
- */
+/** @internal Exported for testing only. */
 export declare function clearPendingWorkflowContextsMap(): void;
 //# sourceMappingURL=pending-workflow-context.d.ts.map