@kici-dev/sdk 0.1.21 → 0.1.22

package/dist/api-types.d.ts

@@ -58,6 +58,22 @@ export interface InventoryApi {
     /** Look up one host by agent id; null when the host is not in the roster. */
     get(agentId: string): Promise<HostInventoryEntry | null>;
 }
+export interface HostApi {
+    /**
+     * Signal the orchestrator that the host this job runs on is about to reboot,
+     * and resolve once the orchestrator acks (which sets a persisted
+     * reboot-pending flag holding the pinned post-restart job). After this
+     * resolves, the agent issues the OS reboot once the current step completes.
+     *
+     * Used by the SDK `restartHost()` step. `deadlineMs` overrides the
+     * orchestrator's default host-reboot deadline. Only meaningful inside a
+     * running job step on an agent; a local `kici run` rejects (no orchestrator
+     * to ack, and a local run cannot reboot a remote host).
+     */
+    requestReboot(opts?: {
+        deadlineMs?: number;
+    }): Promise<void>;
+}
 export interface KiciApi {
     /** Query orchestrator infrastructure (scalers, agents). */
     infrastructure: InfrastructureApi;
@@ -65,6 +81,8 @@ export interface KiciApi {
     inventory: InventoryApi;
     /** Request short-lived OIDC ID tokens for the current job (build provenance). */
     oidc: OidcApi;
+    /** Host-lifecycle operations on the agent's own host (e.g. reboot). */
+    host: HostApi;
 }
 /**
  * Low-level transport function used to implement KiciApi.

package/dist/api-types.js

@@ -36,7 +36,8 @@ function buildKiciApi(transport, jobCtx) {
 				jobId: jobCtx.jobId,
 				audience: opts.audience
 			});
-		} }
+		} },
+		host: { requestReboot: (opts) => transport("host.requestReboot", { ...opts?.deadlineMs !== void 0 ? { deadlineMs: opts.deadlineMs } : {} }) }
 	};
 }
 //#endregion

package/dist/approval.d.ts

@@ -1,8 +1,9 @@
 /**
  * Workflow-author API for declaring a manual approval gate at step, job, or
- * workflow level. The author writes `requireApproval`; the compiler normalizes
- * it into the lock file's `approval` block, and the orchestrator turns it into
- * a held element at dispatch time.
+ * workflow level. The author writes `approval`; the compiler normalizes it
+ * into the lock file's `approval` block, and the orchestrator turns it into a
+ * held element at dispatch time (for `when: 'always'`) or the agent turns it
+ * into a mid-step drift gate (for `when: 'drift'`).
  */
 /** A single approver clause: any member of a team, or a specific user. */
 export type ApproverClause = {
@@ -10,25 +11,39 @@ export type ApproverClause = {
 } | {
     user: string;
 };
+/**
+ * When the gate fires.
+ *
+ * - `always` (default) — gate BEFORE the element runs, with a static reason.
+ *   Valid at step / job / workflow scope.
+ * - `drift` — gate BETWEEN a step's `check` and `run`, only when `check`
+ *   returns drift in apply mode. Step-scope only; requires a `check` facet.
+ */
+export type ApprovalWhen = 'always' | 'drift';
 /**
  * Declarative approval requirement.
  *
  * - `true` — pause for ANY org member with the approval permission.
  * - `ApproverClause[]` — a flat AND list (all clauses must be satisfied).
- * - object form — clauses plus an optional human `reason` and a per-gate
- *   `timeout` (seconds) that overrides the org-default expiry.
+ * - object form — clauses plus an optional `when`, a human `reason`, and a
+ *   per-gate `timeout` (seconds) that overrides the org-default expiry.
  */
-export type RequireApproval = true | ApproverClause[] | {
-    approvers: ApproverClause[];
+export type ApprovalConfig = true | ApproverClause[] | {
+    when?: ApprovalWhen;
+    approvers?: ApproverClause[];
     reason?: string;
     timeout?: number;
 };
 /** The normalized shape written into the lock file. */
-export interface NormalizedRequireApproval {
+export interface NormalizedApproval {
     clauses: ApproverClause[];
     reason?: string;
     timeoutSeconds?: number;
+    when: ApprovalWhen;
 }
-/** Normalize any `RequireApproval` form into `{ clauses, reason?, timeoutSeconds? }`. */
-export declare function normalizeRequireApproval(r: RequireApproval): NormalizedRequireApproval;
+/**
+ * Normalize any `ApprovalConfig` form into
+ * `{ clauses, reason?, timeoutSeconds?, when }`. `when` defaults to `'always'`.
+ */
+export declare function normalizeApproval(c: ApprovalConfig): NormalizedApproval;
 //# sourceMappingURL=approval.d.ts.map

package/dist/approval.js

@@ -1,16 +1,26 @@
 import "./chunk-BTugEXQM.js";
 //#region src/approval.ts
-/** Normalize any `RequireApproval` form into `{ clauses, reason?, timeoutSeconds? }`. */
-function normalizeRequireApproval(r) {
-	if (r === true) return { clauses: [] };
-	if (Array.isArray(r)) return { clauses: r };
+/**
+* Normalize any `ApprovalConfig` form into
+* `{ clauses, reason?, timeoutSeconds?, when }`. `when` defaults to `'always'`.
+*/
+function normalizeApproval(c) {
+	if (c === true) return {
+		clauses: [],
+		when: "always"
+	};
+	if (Array.isArray(c)) return {
+		clauses: c,
+		when: "always"
+	};
 	return {
-		clauses: r.approvers,
-		reason: r.reason,
-		timeoutSeconds: r.timeout
+		clauses: c.approvers ?? [],
+		...c.reason !== void 0 && { reason: c.reason },
+		...c.timeout !== void 0 && { timeoutSeconds: c.timeout },
+		when: c.when ?? "always"
 	};
 }
 //#endregion
-export { normalizeRequireApproval };
+export { normalizeApproval };
 
 //# sourceMappingURL=approval.js.map

package/dist/context.d.ts

@@ -261,6 +261,15 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * the agent digests with SHA-256.
      */
     attestProvenance(opts: import('./provenance-types.js').AttestProvenanceOptions): Promise<import('./provenance-types.js').AttestProvenanceResult>;
+    /**
+     * Upstream needs resolved for this job, keyed by upstream job or group name.
+     * `ctx.needs.<job>.result` is the upstream's outputs proxy and
+     * `ctx.needs.<job>.status` its terminal status (`success | failed | skipped |
+     * …`). A group / matrix / `runsOnAll` fan-out upstream is an ordered array of
+     * `{ name, result, status }`, one entry per child. Undefined for a job with no
+     * declared `needs`.
+     */
+    needs?: import('./needs-context.js').NeedsContext;
 }
 export {};
 //# sourceMappingURL=context.d.ts.map

package/dist/dynamic-group.d.ts

@@ -6,22 +6,24 @@
  *
  * Usage in workflow definition:
  *   needs: [dynamicGroup('test-shards')]
- *   needs: [dynamicGroup('test-shards', { ifFailed: 'run' })]
+ *   needs: [dynamicGroup('test-shards', { when: 'always' })]
  */
+import type { NeedsWhenInput } from './types.js';
 declare const DYNAMIC_GROUP_TAG: unique symbol;
 export interface DynamicGroupRef {
     readonly [DYNAMIC_GROUP_TAG]: true;
     readonly group: string;
-    readonly ifFailed?: 'skip' | 'run';
+    /** Run condition for the edge: keyword sugar or a raw upstream-status set. */
+    readonly when?: NeedsWhenInput;
 }
 /**
  * Create a reference to a dynamic job group for use in a static job's `needs` array.
  *
  * @param name - The group name (must match the name used in `dynamicJob(name, fn)`)
- * @param opts - Optional failure policy override
+ * @param opts - Optional run condition for the edge
  */
 export declare function dynamicGroup(name: string, opts?: {
-    ifFailed?: 'skip' | 'run';
+    when?: NeedsWhenInput;
 }): DynamicGroupRef;
 /** Type guard to check if a value is a DynamicGroupRef. */
 export declare function isDynamicGroupRef(value: unknown): value is DynamicGroupRef;

package/dist/dynamic-group.js

@@ -1,27 +1,17 @@
 import "./chunk-BTugEXQM.js";
 //#region src/dynamic-group.ts
-/**
-* Dynamic group helpers for cross-domain needs.
-*
-* A DynamicGroupRef allows static jobs to declare a dependency on a dynamic
-* job group by name, without knowing the concrete generated job names.
-*
-* Usage in workflow definition:
-*   needs: [dynamicGroup('test-shards')]
-*   needs: [dynamicGroup('test-shards', { ifFailed: 'run' })]
-*/
 const DYNAMIC_GROUP_TAG = Symbol.for("kici:dynamicGroup");
 /**
 * Create a reference to a dynamic job group for use in a static job's `needs` array.
 *
 * @param name - The group name (must match the name used in `dynamicJob(name, fn)`)
-* @param opts - Optional failure policy override
+* @param opts - Optional run condition for the edge
 */
 function dynamicGroup(name, opts) {
 	return {
 		[DYNAMIC_GROUP_TAG]: true,
 		group: name,
-		...opts?.ifFailed && { ifFailed: opts.ifFailed }
+		...opts?.when !== void 0 && { when: opts.when }
 	};
 }
 /** Type guard to check if a value is a DynamicGroupRef. */

package/dist/host-restart.d.ts

@@ -0,0 +1,58 @@
+/**
+ * Workflow-level host restart + wait-for-host-alive steps.
+ *
+ * KiCI agents run ON each host while executing a job, so a workflow can reboot
+ * the machine it runs on (the Ansible `reboot` + `wait_for_connection` pattern,
+ * adapted to KiCI's no-remote-exec model). The flow is job-boundary:
+ *
+ * - `restartHost()` is the LAST step of a "restart" job. It signals the
+ *   orchestrator that this host is about to reboot (which holds the pinned
+ *   post-restart job and treats the imminent disconnect as expected), reports
+ *   success, and the agent issues the OS reboot once the step completes.
+ * - The post-restart work is a SEPARATE job pinned to the same host
+ *   (`runsOn: [hostId]`) that `needs` the restart job. The orchestrator holds
+ *   it until the host completes a reboot cycle, then dispatches it.
+ * - `waitForHostAlive(probe)` is the optional first step of that post-restart
+ *   job: the "host is back" guarantee comes free from the pinned-hold (the job
+ *   only dispatches after the agent reconnects); this step adds a
+ *   service-readiness gate for hosts where "agent connected" ≠ "services ready".
+ */
+import type { Step } from './types.js';
+export interface WaitForHostAliveOptions {
+    /** Step name surfaced in logs. Defaults to 'wait-for-host-alive'. */
+    name?: string;
+    /** Time between successive probe invocations, ms. Defaults to 3000. */
+    intervalMs?: number;
+    /** Total time budget for readiness, ms. Defaults to 300000 (5 min). */
+    timeoutMs?: number;
+}
+/**
+ * Optional first step of a post-restart job. Polls a readiness probe until it
+ * resolves (services back up after a reboot). The host being reconnected is
+ * already guaranteed by the pinned-hold; this gates on service readiness.
+ *
+ * A probe that throws/rejects keeps polling (the `waitFor` swallow-errors
+ * default — the "poll until healthy" pattern). Any non-null resolution means
+ * "ready". Exceeding `timeoutMs` fails the step ("services did not come up").
+ */
+export declare function waitForHostAlive(probe: () => Promise<unknown> | unknown, opts?: WaitForHostAliveOptions): Step<unknown>;
+export interface RestartHostOptions {
+    /**
+     * Max time the orchestrator waits for the host to return after the reboot,
+     * ms. Defaults to the orchestrator's `KICI_HOST_REBOOT_DEADLINE_MS`.
+     */
+    deadlineMs?: number;
+}
+/**
+ * Reboot the host this job runs on. MUST be the last step of a "restart" job;
+ * the post-restart work goes in a separate job that `needs` this one and is
+ * pinned to the same host (`runsOn: [hostId]`). The orchestrator holds that job
+ * until the host completes a reboot cycle, then dispatches it.
+ *
+ * The step signals the orchestrator (reboot-pending) and reports success; the
+ * agent issues the actual OS reboot after the step completes. Rebooting needs
+ * host privilege: if the OS reboot primitive is denied, the step fails with a
+ * clear privilege error and the orchestrator clears the reboot-pending flag.
+ */
+export declare function restartHost(opts?: RestartHostOptions): Step<void>;
+//# sourceMappingURL=host-restart.d.ts.map

package/dist/host-restart.js

@@ -0,0 +1,63 @@
+import "./chunk-BTugEXQM.js";
+import { step } from "./step.js";
+import { waitForStep } from "./wait-for.js";
+//#region src/host-restart.ts
+/**
+* Workflow-level host restart + wait-for-host-alive steps.
+*
+* KiCI agents run ON each host while executing a job, so a workflow can reboot
+* the machine it runs on (the Ansible `reboot` + `wait_for_connection` pattern,
+* adapted to KiCI's no-remote-exec model). The flow is job-boundary:
+*
+* - `restartHost()` is the LAST step of a "restart" job. It signals the
+*   orchestrator that this host is about to reboot (which holds the pinned
+*   post-restart job and treats the imminent disconnect as expected), reports
+*   success, and the agent issues the OS reboot once the step completes.
+* - The post-restart work is a SEPARATE job pinned to the same host
+*   (`runsOn: [hostId]`) that `needs` the restart job. The orchestrator holds
+*   it until the host completes a reboot cycle, then dispatches it.
+* - `waitForHostAlive(probe)` is the optional first step of that post-restart
+*   job: the "host is back" guarantee comes free from the pinned-hold (the job
+*   only dispatches after the agent reconnects); this step adds a
+*   service-readiness gate for hosts where "agent connected" ≠ "services ready".
+*/
+/**
+* Optional first step of a post-restart job. Polls a readiness probe until it
+* resolves (services back up after a reboot). The host being reconnected is
+* already guaranteed by the pinned-hold; this gates on service readiness.
+*
+* A probe that throws/rejects keeps polling (the `waitFor` swallow-errors
+* default — the "poll until healthy" pattern). Any non-null resolution means
+* "ready". Exceeding `timeoutMs` fails the step ("services did not come up").
+*/
+function waitForHostAlive(probe, opts = {}) {
+	return waitForStep(opts.name ?? "wait-for-host-alive", {
+		check: async () => {
+			return await probe() ?? true;
+		},
+		intervalMs: opts.intervalMs ?? 3e3,
+		timeoutMs: opts.timeoutMs ?? 3e5
+	});
+}
+/**
+* Reboot the host this job runs on. MUST be the last step of a "restart" job;
+* the post-restart work goes in a separate job that `needs` this one and is
+* pinned to the same host (`runsOn: [hostId]`). The orchestrator holds that job
+* until the host completes a reboot cycle, then dispatches it.
+*
+* The step signals the orchestrator (reboot-pending) and reports success; the
+* agent issues the actual OS reboot after the step completes. Rebooting needs
+* host privilege: if the OS reboot primitive is denied, the step fails with a
+* clear privilege error and the orchestrator clears the reboot-pending flag.
+*/
+function restartHost(opts = {}) {
+	return step("restart-host", { run: async (ctx) => {
+		ctx.log.info("Requesting host reboot…");
+		await ctx.kici.host.requestReboot({ deadlineMs: opts.deadlineMs });
+		ctx.log.info("Reboot acknowledged; host will reboot after this step completes.");
+	} });
+}
+//#endregion
+export { restartHost, waitForHostAlive };
+
+//# sourceMappingURL=host-restart.js.map

package/dist/index.d.ts

@@ -1,8 +1,8 @@
 export { step } from './step.js';
 export { job } from './job.js';
 export { workflow } from './workflow.js';
-export { normalizeRequireApproval } from './approval.js';
-export type { RequireApproval, ApproverClause, NormalizedRequireApproval } from './approval.js';
+export { normalizeApproval } from './approval.js';
+export type { ApprovalConfig, ApprovalWhen, ApproverClause, NormalizedApproval, } from './approval.js';
 export { pr, push, tag, comment, review, reviewComment, release, dispatch, create, delete as delete, status, workflowRun, fork, star, watch, webhook, kiciEvent, workflowComplete, jobComplete, genericWebhook, schedule, lifecycle, } from './triggers/index.js';
 export type { TriggerConfig, PrTriggerConfig, PushTriggerConfig, TagTriggerConfig, CommentTriggerConfig, ReviewTriggerConfig, ReviewCommentTriggerConfig, ReleaseTriggerConfig, DispatchTriggerConfig, CreateTriggerConfig, DeleteTriggerConfig, StatusTriggerConfig, WorkflowRunTriggerConfig, ForkTriggerConfig, StarTriggerConfig, WatchTriggerConfig, WebhookTriggerConfig, BranchPattern, BodyMatchPattern, PrEvent, PushEvent, PrConfigInput, PushConfigInput, TagConfigInput, CommentConfigInput, CommentAction, CommentSource, ReviewConfigInput, ReviewAction, ReviewState, ReviewCommentConfigInput, ReviewCommentAction, ReleaseConfigInput, ReleaseAction, DispatchConfigInput, CreateConfigInput, DeleteConfigInput, RefType, StatusConfigInput, StatusState, WorkflowRunConfigInput, WorkflowRunAction, ForkConfigInput, StarConfigInput, StarAction, WatchConfigInput, WatchAction, WebhookConfigInput, KiciEventConfigInput, KiciEventTriggerConfig, WorkflowCompleteConfigInput, WorkflowCompleteTriggerConfig, WorkflowCompleteStatus, JobCompleteConfigInput, JobCompleteTriggerConfig, JobCompleteStatus, GenericWebhookConfigInput, GenericWebhookTriggerConfig, GenericWebhookAuthMethod, GenericWebhookHmacAuth, GenericWebhookApiKeyAuth, GenericWebhookAuth, ScheduleConfigInput, ScheduleTriggerConfig, LifecycleEvent, LifecycleConfigInput, LifecycleTriggerConfig, } from './triggers/index.js';
 export { onCancel, cleanup, onSuccess, onFailure, beforeStep, afterStep } from './hooks/index.js';
@@ -15,7 +15,7 @@ export { validateDag } from './validation/index.js';
 export type { DagNode, DagValidationResult } from './validation/index.js';
 export type { SourceLocation, OutputProxy, Step, StepOptions, StepOptionsBase, StepOptionsPlain, StepOptionsWithCheck, StepRunFn, BareStepFn, StepInput, OutputSchema, InferOutputs, Job, JobOptions, GenericInitConfig, MiseInitConfig, InitPreset, InitItem, InitConfig, ContainerConfig, RunsOnSelector, RunsOn, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
 export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, } from './types.js';
-export type { TaggedDynamicJobFn, ResultAwareDynamicJobConfig, ResultAwareDynamicJobFn, DynamicJobNeed, } from './types.js';
+export type { TaggedDynamicJobFn, ResultAwareDynamicJobConfig, ResultAwareDynamicJobFn, DynamicJobNeed, NeedsWhen, NeedsWhenInput, } from './types.js';
 export { buildNeedsContext } from './needs-context.js';
 export type { UpstreamSnapshot, NeedsContext, NeedEntry, GroupNeedEntry } from './needs-context.js';
 export { CacheSpecSchema, normalizeCacheSpecs } from './cache-types.js';
@@ -28,7 +28,7 @@ export type { DynamicGroupRef } from './dynamic-group.js';
 export type { StepContext, Logger, WorkflowInfo, JobInfo, AgentInfo, MatrixJobOutputs, HostJobOutputs, RepoInfo, StepSecretsTyped, KnownSecretKeys, } from './context.js';
 export { isMatrixJobOutputs, isHostJobOutputs } from './context.js';
 export { buildKiciApi } from './api-types.js';
-export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, InventoryApi, HostInventoryEntry, InventorySelector, } from './api-types.js';
+export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, InventoryApi, HostApi, HostInventoryEntry, InventorySelector, } from './api-types.js';
 export { SecretNotFoundError } from './errors.js';
 export { createStepSecrets } from './secrets.js';
 export type { StepSecrets, TrackedStepSecrets, SecretMeta, SecretFileOptions, MountedFile, StepSecretsFileHost, StepSecretsFileWiring, StepSecretsHandle, StepSecretMountKind, StepSecretMountRecord, } from './secrets.js';
@@ -46,5 +46,7 @@ export { idempotent, idempotentStep } from './idempotent.js';
 export type { IdempotentOptions, IdempotentResult } from './idempotent.js';
 export { waitFor, waitForStep, WaitForTimeoutError } from './wait-for.js';
 export type { WaitForOptions, WaitForResult } from './wait-for.js';
+export { waitForHostAlive, restartHost } from './host-restart.js';
+export type { WaitForHostAliveOptions, RestartHostOptions } from './host-restart.js';
 export { z } from 'zod';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,6 +1,6 @@
 import "./chunk-BTugEXQM.js";
 import { buildKiciApi } from "./api-types.js";
-import { normalizeRequireApproval } from "./approval.js";
+import { normalizeApproval } from "./approval.js";
 import { CacheSpecSchema, normalizeCacheSpecs } from "./cache-types.js";
 import { isHostJobOutputs, isMatrixJobOutputs } from "./context.js";
 import { DYNAMIC_GROUP_TAG, dynamicGroup, isDynamicGroupRef } from "./dynamic-group.js";
@@ -8,6 +8,8 @@ import { SecretNotFoundError } from "./errors.js";
 import { fixture } from "./fixture.js";
 import { createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "./outputs.js";
 import { step } from "./step.js";
+import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
+import { restartHost, waitForHostAlive } from "./host-restart.js";
 import { idempotent, idempotentStep } from "./idempotent.js";
 import { job } from "./job.js";
 import { workflow } from "./workflow.js";
@@ -50,6 +52,5 @@ import { applyIncludeExclude, expandMatrix } from "./matrix/expand.js";
 import "./matrix/index.js";
 import { defineEvent } from "./events/define-event.js";
 import "./events/index.js";
-import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
 import { z } from "zod";
-export { CacheSpecSchema, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, buildNeedsContext, cleanup, comment, create, createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isHostJobOutputs, isMatrixJobOutputs, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeCacheSpecs, normalizeRequireApproval, onCancel, onFailure, onSuccess, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };
+export { CacheSpecSchema, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, buildNeedsContext, cleanup, comment, create, createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isHostJobOutputs, isMatrixJobOutputs, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeApproval, normalizeCacheSpecs, onCancel, onFailure, onSuccess, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, restartHost, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForHostAlive, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };

package/dist/job.js

@@ -66,7 +66,7 @@ function job(nameOrOptions, maybeOptions) {
 		resources: options.resources,
 		init: options.init,
 		...options.cache !== void 0 && { cache: options.cache },
-		...options.requireApproval !== void 0 && { requireApproval: options.requireApproval },
+		...options.approval !== void 0 && { approval: options.approval },
 		result: createJobOutputProxy(name)
 	};
 }

package/dist/needs-context.d.ts

@@ -1,31 +1,38 @@
 import type { OutputProxy, DynamicJobNeed } from './types.js';
+import type { ExecutionJobStatus } from '@kici-dev/engine';
 /**
- * Frozen snapshot of upstream outputs, captured once at first eval of a
- * result-aware dynamic generator and replayed unchanged on re-eval.
+ * Frozen snapshot of upstream outputs + statuses, captured once at first eval of
+ * a result-aware dynamic generator and replayed unchanged on re-eval.
  *
  * - `jobs` maps an upstream job name to its outputs record.
  * - `groups` maps a dynamic group name to its ordered member job names.
+ * - `statuses` maps an upstream job name to its terminal status. Absent entries
+ *   default to `success` (the only status that satisfies a default needs edge,
+ *   so an upstream resolved into the snapshot is success unless told otherwise).
  */
 export interface UpstreamSnapshot {
     jobs: Record<string, Record<string, unknown>>;
     groups: Record<string, string[]>;
+    statuses?: Record<string, ExecutionJobStatus>;
 }
 /** One entry in the array exposed for a `dynamicGroup(...)` need. */
 export interface GroupNeedEntry {
     name: string;
     result: OutputProxy<any>;
+    status: ExecutionJobStatus;
 }
-/** A single-job need exposes `{ result }`; a group need exposes an ordered array. */
+/** A single-job need exposes `{ result, status }`; a group need exposes an ordered array. */
 export type NeedEntry = {
     result: OutputProxy<any>;
+    status: ExecutionJobStatus;
 } | GroupNeedEntry[];
 /** The resolved `ctx.needs` map keyed by job name or group name. */
 export type NeedsContext = Record<string, NeedEntry>;
 /**
  * Resolve declared needs against a frozen snapshot into the `ctx.needs` map.
  *
- * - A single static/named-job need resolves to `{ result: <proxy over jobs[name]> }`.
- * - A `dynamicGroup(...)` need resolves to an ordered array of `{ name, result }`,
+ * - A single static/named-job need resolves to `{ result: <proxy over jobs[name]>, status }`.
+ * - A `dynamicGroup(...)` need resolves to an ordered array of `{ name, result, status }`,
  *   one entry per group member in the snapshot's deterministic eval order.
  */
 export declare function buildNeedsContext(snapshot: UpstreamSnapshot, declaredNeeds: ReadonlyArray<DynamicJobNeed>): NeedsContext;

package/dist/needs-context.js

@@ -19,11 +19,15 @@ function needKey(need) {
 		key: need.name
 	};
 }
+/** Read an upstream's terminal status from the snapshot, defaulting to success. */
+function statusFor(snapshot, name) {
+	return snapshot.statuses?.[name] ?? "success";
+}
 /**
 * Resolve declared needs against a frozen snapshot into the `ctx.needs` map.
 *
-* - A single static/named-job need resolves to `{ result: <proxy over jobs[name]> }`.
-* - A `dynamicGroup(...)` need resolves to an ordered array of `{ name, result }`,
+* - A single static/named-job need resolves to `{ result: <proxy over jobs[name]>, status }`.
+* - A `dynamicGroup(...)` need resolves to an ordered array of `{ name, result, status }`,
 *   one entry per group member in the snapshot's deterministic eval order.
 */
 function buildNeedsContext(snapshot, declaredNeeds) {
@@ -32,9 +36,13 @@ function buildNeedsContext(snapshot, declaredNeeds) {
 		const { kind, key } = needKey(need);
 		if (kind === "group") out[key] = (snapshot.groups[key] ?? []).map((name) => ({
 			name,
-			result: createSnapshotOutputProxy(name, snapshot.jobs[name])
+			result: createSnapshotOutputProxy(name, snapshot.jobs[name]),
+			status: statusFor(snapshot, name)
 		}));
-		else out[key] = { result: createSnapshotOutputProxy(key, snapshot.jobs[key]) };
+		else out[key] = {
+			result: createSnapshotOutputProxy(key, snapshot.jobs[key]),
+			status: statusFor(snapshot, key)
+		};
 	}
 	return out;
 }

package/dist/step.js

@@ -1,4 +1,5 @@
 import "./chunk-BTugEXQM.js";
+import { normalizeApproval } from "./approval.js";
 import { createStepOutputProxy } from "./outputs.js";
 //#region src/step.ts
 /**
@@ -59,6 +60,7 @@ function step(nameOrRunOrOptions, runOrOptions) {
 		options = nameOrRunOrOptions;
 	}
 	if (options.check && !options.summarize) throw new Error("summarize is required when check is set");
+	if (options.approval !== void 0 && normalizeApproval(options.approval).when === "drift" && !options.check) throw new Error("approval.when \"drift\" requires a check facet");
 	return {
 		_tag: "Step",
 		name,
@@ -74,7 +76,7 @@ function step(nameOrRunOrOptions, runOrOptions) {
 		rules: options.rules,
 		onCancel: options.onCancel,
 		cleanup: options.cleanup,
-		...options.requireApproval !== void 0 && { requireApproval: options.requireApproval },
+		...options.approval !== void 0 && { approval: options.approval },
 		_sourceLocation,
 		result: createStepOutputProxy(name)
 	};

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod';
 import type { $ as Shell } from 'zx';
-import type { ResourceRequest, RunsOnAllInput, OnUnreachableMode } from '@kici-dev/engine';
+import type { ResourceRequest, RunsOnAllInput, OnUnreachableMode, NeedsWhen, ExecutionJobStatus } from '@kici-dev/engine';
 import type { StepContext, Logger } from './context.js';
 import type { TriggerConfig } from './triggers/types.js';
 import type { Rule } from './rules/types.js';
@@ -9,8 +9,15 @@ import type { HookInput } from './hooks/types.js';
 import type { KiciApi } from './api-types.js';
 import type { DynamicGroupRef } from './dynamic-group.js';
 import type { EventPayload } from './events/event-payloads.js';
-import type { RequireApproval } from './approval.js';
-export type { ResourceRequest, ResourceSpec, RunsOnAllInput, OnUnreachableMode, } from '@kici-dev/engine';
+import type { ApprovalConfig } from './approval.js';
+export type { ResourceRequest, ResourceSpec, RunsOnAllInput, OnUnreachableMode, NeedsWhen, } from '@kici-dev/engine';
+/**
+ * Author-facing run condition for a `needs` edge: keyword sugar
+ * (`'on-success'` | `'always'` | `'on-skip'` | `'on-failure'`) or a raw set of
+ * upstream terminal statuses. Resolved to a normalized status-set at compile
+ * time; the downstream runs when the upstream's terminal status is a member.
+ */
+export type NeedsWhenInput = NeedsWhen | ExecutionJobStatus[];
 /** Source location captured at a step() call site. */
 export interface SourceLocation {
     readonly file: string;
@@ -65,8 +72,8 @@ export interface Step<TResult = void> {
     readonly onCancel?: HookInput;
     /** Always runs after step (success, failure, or cancel). */
     readonly cleanup?: HookInput;
-    /** Pause for a manual human approval before this step runs. */
-    readonly requireApproval?: RequireApproval;
+    /** Pause for a manual human approval (before this step, or on drift). */
+    readonly approval?: ApprovalConfig;
     /** Internal: source location captured at step() call site. Not part of public API. */
     readonly _sourceLocation?: SourceLocation;
     /**
@@ -107,8 +114,8 @@ export interface StepOptionsBase {
     onCancel?: HookInput;
     /** Always runs after step (success, failure, or cancel). */
     cleanup?: HookInput;
-    /** Pause for a manual human approval before this step runs. */
-    requireApproval?: RequireApproval;
+    /** Pause for a manual human approval (before this step, or on drift). */
+    approval?: ApprovalConfig;
 }
 /**
  * Plain step options: `run` takes only the context — the existing, fully
@@ -249,10 +256,10 @@ declare const DYNAMIC_JOB_NEEDS_TAG: unique symbol;
  */
 export type DynamicJobNeed = Job | string | DynamicGroupRef | {
     name: string;
-    ifFailed?: 'skip' | 'run';
+    when?: NeedsWhenInput;
 } | {
     group: string;
-    ifFailed?: 'skip' | 'run';
+    when?: NeedsWhenInput;
 };
 /**
  * Options-object form of {@link dynamicJob}: a result-aware generator that is
@@ -391,10 +398,10 @@ export interface Job {
     readonly steps: readonly StepInput[];
     readonly needs?: ReadonlyArray<Job | string | DynamicGroupRef | {
         name: string;
-        ifFailed: 'skip' | 'run';
+        when?: NeedsWhenInput;
     } | {
         group: string;
-        ifFailed: 'skip' | 'run';
+        when?: NeedsWhenInput;
     }>;
     /** Rules for conditional execution */
     readonly rules?: Rule[];
@@ -457,7 +464,7 @@ export interface Job {
     /** Declarative cache: restored before steps, saved after the job on key miss. */
     readonly cache?: import('./cache-types.js').CacheInput;
     /** Pause for a manual human approval before this job dispatches. */
-    readonly requireApproval?: RequireApproval;
+    readonly approval?: ApprovalConfig;
     /**
      * Type-safe proxy for accessing this job's outputs.
      * For multi-step jobs: jobRef.result.stepName.field
@@ -510,10 +517,10 @@ export interface JobOptions {
     run?: (ctx: StepContext) => Promise<any>;
     needs?: Array<Job | string | DynamicGroupRef | {
         name: string;
-        ifFailed: 'skip' | 'run';
+        when?: NeedsWhenInput;
     } | {
         group: string;
-        ifFailed: 'skip' | 'run';
+        when?: NeedsWhenInput;
     }>;
     /** Rules that must pass for job to execute */
     rules?: Rule[];
@@ -591,7 +598,7 @@ export interface JobOptions {
     /** Declarative cache: restored before steps, saved after the job on key miss. */
     cache?: import('./cache-types.js').CacheInput;
     /** Pause for a manual human approval before this job dispatches. */
-    requireApproval?: RequireApproval;
+    approval?: ApprovalConfig;
 }
 /**
  * Private npm registry declaration. Tells the agent to authenticate against
@@ -670,7 +677,7 @@ export interface Workflow {
         readonly max?: number;
     };
     /** Pause for a manual human approval before the whole workflow dispatches. */
-    readonly requireApproval?: RequireApproval;
+    readonly approval?: ApprovalConfig;
 }
 /** Options for workflow() factory */
 export interface WorkflowOptions {
@@ -723,7 +730,7 @@ export interface WorkflowOptions {
         max?: number;
     };
     /** Pause for a manual human approval before the whole workflow dispatches. */
-    requireApproval?: RequireApproval;
+    approval?: ApprovalConfig;
 }
 export type { TriggerConfig, PrTriggerConfig, PushTriggerConfig } from './triggers/types.js';
 export type { Rule, RuleContext, RuleCheckFn, RuleResult } from './rules/types.js';

package/dist/workflow.js

@@ -76,7 +76,7 @@ function workflow(name, options) {
 		onSuccess: options.onSuccess,
 		onFailure: options.onFailure,
 		concurrency: options.concurrency,
-		requireApproval: options.requireApproval
+		approval: options.approval
 	};
 }
 //#endregion

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/sdk",
-  "version": "0.1.21",
+  "version": "0.1.22",
   "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
   "keywords": [
     "ci",
@@ -49,8 +49,8 @@
     "micromatch": "^4.0.8",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.21",
-    "@kici-dev/engine": "0.1.21"
+    "@kici-dev/core": "0.1.22",
+    "@kici-dev/engine": "0.1.22"
   },
   "devDependencies": {
     "@types/micromatch": "^4.0.10"

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/sdk@0.1.21",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.21/1834e1a9-6047-4754-a53b-056d1a5e091c",
+  "name": "@kici-dev/sdk@0.1.22",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.1.22/fea982d5-064e-481c-8436-fbd07a92a3c8",
   "creationInfo": {
-    "created": "2026-06-23T05:10:13Z",
+    "created": "2026-06-24T06:03:05Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -146,9 +146,9 @@
       "homepage": "https://ericsmekens.github.io/jsep/tree/master/packages/regex#readme"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.21",
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.1.22",
       "name": "@kici-dev/core",
-      "versionInfo": "0.1.21",
+      "versionInfo": "0.1.22",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -159,16 +159,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.21"
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.1.22"
         }
       ],
       "description": "Light shared utilities for the KiCI stack (logging, errors, formatting, crypto, zx init, the TypeScript ESM loader hook). No server-side dependencies.",
       "homepage": "https://kici.dev"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.21",
+      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.1.22",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.1.21",
+      "versionInfo": "0.1.22",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -179,7 +179,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.21"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.22"
         }
       ],
       "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",
@@ -188,7 +188,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/sdk",
-      "versionInfo": "0.1.21",
+      "versionInfo": "0.1.22",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -199,7 +199,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.21"
+          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.1.22"
         }
       ],
       "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
@@ -1584,68 +1584,68 @@
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.135.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-jose-6.2.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.4",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-safe-regex-2.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.21",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.1.22",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.21",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.1.22",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.21",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.1.22",
       "relationshipType": "DEPENDS_ON"
     },
     {