@kici-dev/compiler 0.1.20 → 0.1.22

package/dist/llm-context/llms.txt

@@ -14,6 +14,7 @@ The full markdown bundle of every page indexed here is available at https://docs
 
 - [Basic workflow patterns](https://docs.kici.dev/user/patterns/basic/): Basic CI, PR-only / push-only filters, multiple triggers, manual-only workflows
 - [Conditionals & matrix patterns](https://docs.kici.dev/user/patterns/conditionals-matrix/): Conditional execution with rules, matrix builds (static + dynamic), dynamic job generation
+- [Host restart & wait-for-alive](https://docs.kici.dev/user/patterns/host-restart/): Reboot the host a workflow runs on and continue after it comes back
 - [Integration patterns](https://docs.kici.dev/user/patterns/integrations/): Workflow chaining, generic webhooks, Stripe, self-hosted git forges, plain GitHub repos
 - [Pattern reference](https://docs.kici.dev/user/patterns/reference/): Step context, examples repository, GitHub check run output — cross-cutting reference for all patterns
 - [Scheduling & event patterns](https://docs.kici.dev/user/patterns/scheduling-and-events/): Nightly cron, workflow-complete-triggered deploys, custom event chaining
@@ -44,7 +45,7 @@ The full markdown bundle of every page indexed here is available at https://docs
 ## Workflow features
 
 - [Account and sign-in](https://docs.kici.dev/user/account-and-login/): How your KiCI account relates to sign-in methods, and how to change the way you sign in.
-- [Approval gates](https://docs.kici.dev/user/approvals/): Pause a workflow for human sign-off at step, job, or workflow granularity with requireApproval
+- [Approval gates](https://docs.kici.dev/user/approvals/): Pause a workflow for human sign-off at step, job, or workflow granularity with approval
 - [Concurrency groups](https://docs.kici.dev/user/concurrency/): Control parallel execution with auto-cancel and queue modes
 - [Dashboard](https://docs.kici.dev/user/dashboard/): Web UI for monitoring workflow runs, managing sources, secrets, and organization settings.
 - [Dynamic values](https://docs.kici.dev/user/dynamic-values/)
@@ -52,6 +53,7 @@ The full markdown bundle of every page indexed here is available at https://docs
 - [Environments](https://docs.kici.dev/user/environments/): Configure deployment environments with variables, secrets, and protection rules
 - [Event system](https://docs.kici.dev/user/events/): How KiCI's event model works -- event types, the registration model, event matching, and circuit breaker protection
 - [Global workflows](https://docs.kici.dev/user/global-workflows/): Cross-repo workflows that run on events from any repo in the same org
+- [Idempotent steps and check mode](https://docs.kici.dev/user/idempotent-steps/): Declare desired state with a step check facet, then run in apply or --check preview mode
 - [Private npm registries](https://docs.kici.dev/user/private-registries/): Authenticate `npm install` against private registries (CodeArtifact, GitHub Packages, Verdaccio, …) from a workflow's `.kici/package.json`
 - [Build provenance and attestations](https://docs.kici.dev/user/provenance/): Generate and verify signed SLSA provenance for the artifacts your workflows build
 - [Secrets](https://docs.kici.dev/user/secrets/): How to access secrets in KiCI workflow steps

package/dist/local-executor/index.js

@@ -15,7 +15,7 @@ import path from "node:path";
 import pc from "picocolors";
 import { writeFile } from "node:fs/promises";
 import { logger } from "@kici-dev/core";
-import { matchAllWorkflows } from "@kici-dev/engine";
+import { CheckMode, CheckStepOutcome, matchAllWorkflows } from "@kici-dev/engine";
 import os from "node:os";
 //#region src/local-executor/index.ts
 /**
@@ -169,7 +169,8 @@ async function runWorkflowBody(workflow, ctx, options, secrets, kiciDir, concurr
 				kiciDir,
 				execDir: ctx.execDir,
 				jobOutputsMap,
-				signal
+				signal,
+				checkMode: options.checkMode
 			});
 		},
 		isSuccess: (result) => result.status === "success" || result.status === "skipped"
@@ -305,6 +306,11 @@ async function executeLocal(options) {
 			if (!isQuiet) logger.info(pc.green(`JUnit XML written to ${options.junit}`));
 		}
 		if (!isQuiet) displayLocalSummary(workflowResults);
+		if (options.checkMode === CheckMode.enum["check-fail-on-drift"] && hasDrift(workflowResults)) {
+			if (!isQuiet) logger.info(pc.yellow("Drift detected in check mode (--fail-on-drift): exiting with code 2"));
+			if (materialized && !options.keep) await materialized.cleanup();
+			process.exit(2);
+		}
 		return allSucceeded;
 	} finally {
 		if (materialized) if (allSucceeded && !options.keep) await materialized.cleanup();
@@ -312,6 +318,13 @@ async function executeLocal(options) {
 	}
 }
 /**
+* True when any step across all workflows reported drift (`dry-run` outcome) —
+* the signal `check-fail-on-drift` uses to exit non-zero.
+*/
+function hasDrift(results) {
+	return results.some((wf) => wf.jobs.some((job) => (job.steps ?? []).some((s) => s.checkOutcome === CheckStepOutcome.enum["dry-run"])));
+}
+/**
 * Get default concurrency based on available CPU parallelism.
 */
 function getDefaultConcurrency() {

package/dist/local-executor/job-runner.d.ts

@@ -8,6 +8,7 @@
  * - Single-job step-by-step execution with rules, abort, and output chaining
  */
 import type { Workflow, OutputsMap } from '@kici-dev/sdk';
+import { CheckMode } from '@kici-dev/engine';
 import type { SimulatedEvent } from '@kici-dev/engine';
 import type { ParsedSecrets } from '../test-runner/secrets-file.js';
 import type { ResolvedJob, LocalJobResult } from './types.js';
@@ -24,6 +25,8 @@ export interface JobExecutionContext {
     execDir: string;
     jobOutputsMap: OutputsMap;
     signal: AbortSignal;
+    /** Run mode for idempotent steps. Defaults to `apply` when unset. */
+    checkMode?: CheckMode;
 }
 /**
  * Resolve all jobs in a workflow, expanding matrix jobs and evaluating dynamic jobs.

package/dist/local-executor/job-runner.js

@@ -8,7 +8,8 @@ import { toEventPayload } from "./to-event-payload.js";
 import { pathToFileURL } from "node:url";
 import path from "node:path";
 import { applyIncludeExclude, expandMatrix, isDynamicJobFn, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "@kici-dev/sdk";
-import { formatMatrixSuffix } from "@kici-dev/engine";
+import { CheckMode, CheckStepOutcome, formatMatrixSuffix } from "@kici-dev/engine";
+import { runIdempotentStep } from "@kici-dev/core/idempotency";
 //#region src/local-executor/job-runner.ts
 /**
 * Job resolution (matrix/dynamic) and single-job execution with step context.
@@ -51,6 +52,45 @@ function resolveNeedName(need) {
 	return need.name;
 }
 /**
+* Run one local step honoring the run-level {@link CheckMode}, reusing the
+* `runIdempotentStep` primitive for checked steps (never hand-rolled branching).
+* Mirrors the agent step loop's check phase so `kici run local --check` and a
+* remote check run produce identical per-step outcomes.
+*/
+async function runLocalStepWithCheckMode(step, ctx, checkMode) {
+	if (!step.check) {
+		if (checkMode !== CheckMode.enum.apply) return {
+			checkOutcome: CheckStepOutcome.enum.no_check,
+			status: "skipped",
+			outputs: void 0
+		};
+		return {
+			status: "success",
+			outputs: await step.run(ctx)
+		};
+	}
+	const res = await runIdempotentStep({
+		name: step.name,
+		check: () => step.check(ctx),
+		summarize: step.summarize,
+		apply: (drift) => step.run(ctx, drift),
+		whenInSync: step.whenInSync ? () => step.whenInSync(ctx) : void 0
+	}, {
+		dryRun: checkMode !== CheckMode.enum.apply,
+		yes: true,
+		log: (line) => ctx.log.info(line)
+	});
+	const driftSummary = res.drift != null ? step.summarize(res.drift) : void 0;
+	const status = res.outcome === CheckStepOutcome.enum.applied ? "success" : "skipped";
+	const mappedStatus = res.outcome === CheckStepOutcome.enum["dry-run"] ? "success" : status;
+	return {
+		checkOutcome: res.outcome,
+		status: mappedStatus,
+		outputs: res.result,
+		...driftSummary !== void 0 && { driftSummary }
+	};
+}
+/**
 * Maintain the base-name `{ byMatrix, merged }` envelope as each matrix child
 * completes. `merged` is rebuilt last-write-wins in suffix order so the result
 * is deterministic regardless of child completion order — matching the remote
@@ -101,7 +141,12 @@ async function resolveJobs(workflow, event) {
 					scalers: [],
 					agents: []
 				}) },
-				oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available during local execution")) }
+				inventory: {
+					query: () => Promise.resolve([]),
+					get: () => Promise.resolve(null)
+				},
+				oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available during local execution")) },
+				host: { requestReboot: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.host.requestReboot() is not available during local execution")) }
 			}
 		});
 		for (const genJob of generatedJobs) {
@@ -267,14 +312,18 @@ async function executeResolvedJobInner(resolvedJob, context, startTime) {
 		formatter.logStepStart(expandedName, normalizedStep.name);
 		const stepStart = Date.now();
 		try {
-			const outputs = await normalizedStep.run(stepCtx);
+			const checkMode = context.checkMode ?? CheckMode.enum.apply;
+			const phase = await runLocalStepWithCheckMode(normalizedStep, stepCtx, checkMode);
+			const outputs = phase.outputs;
 			const stepDuration = Date.now() - stepStart;
 			formatter.logStepComplete(expandedName, normalizedStep.name, stepDuration);
 			const stepResult = {
 				name: normalizedStep.name,
-				status: "success",
+				status: phase.status,
 				durationMs: stepDuration,
-				outputs
+				outputs,
+				...phase.checkOutcome !== void 0 && { checkOutcome: phase.checkOutcome },
+				...phase.driftSummary !== void 0 && { driftSummary: phase.driftSummary }
 			};
 			if (outputs != null) outputsMap.set(normalizedStep.name, outputs);
 			stepResults.push(stepResult);

package/dist/local-executor/output-streamer.js

@@ -95,7 +95,9 @@ function formatLocalJsonResult(results) {
 					name: step.name,
 					status: step.status,
 					durationMs: step.durationMs,
-					...step.error && { error: step.error.message }
+					...step.error && { error: step.error.message },
+					...step.checkOutcome && { checkOutcome: step.checkOutcome },
+					...step.driftSummary && { driftSummary: step.driftSummary }
 				})),
 				...job.ruleResults && job.ruleResults.length > 0 && { ruleResults: job.ruleResults.map((r) => ({
 					label: r.label,

package/dist/local-executor/types.d.ts

@@ -1,4 +1,5 @@
 import type { MatrixValues, Job } from '@kici-dev/sdk';
+import type { CheckMode } from '@kici-dev/engine';
 import type { JobResult } from '../test-runner/job-executor.js';
 /**
  * All CLI flags for `kici run local`.
@@ -42,6 +43,12 @@ export interface RunLocalOptions {
     inPlace?: boolean;
     /** --keep: always retain the isolated tmp checkout (default: keep only on failure) */
     keep?: boolean;
+    /**
+     * Run mode resolved from --check / --fail-on-drift. Threads to the agent step
+     * loop: `apply` (default) converges, `check` previews drift, `check-fail-on-drift`
+     * previews drift and fails the run if any step reports drift. Defaults to `apply`.
+     */
+    checkMode?: CheckMode;
 }
 /**
  * A job after matrix expansion with resolved values.

package/dist/lockfile/generator.js

@@ -5,10 +5,10 @@ import { resolveHashFiles } from "./hash-files.js";
 import { analyzePurity } from "./purity-analyzer.js";
 import path from "node:path";
 import { readFileSync } from "node:fs";
-import { getDynamicJobGroup, getDynamicJobNeeds, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isStaticArray, isStaticObject, normalizeCacheSpecs, normalizeRequireApproval } from "@kici-dev/sdk";
+import { getDynamicJobGroup, getDynamicJobNeeds, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isStaticArray, isStaticObject, normalizeApproval, normalizeCacheSpecs } from "@kici-dev/sdk";
 import { sha256 } from "@kici-dev/core";
 import { PackageManager, detectPackageManagerSync, detectYarnFlavorSync } from "@kici-dev/core/package-manager";
-import { validateResourceRequest } from "@kici-dev/engine";
+import { resolveWhenToRunOn, validateResourceRequest } from "@kici-dev/engine";
 import { normalizeRunsOnAllToMatchers, normalizeRunsOnToMatchers } from "@kici-dev/engine/labels/compile";
 import { execSync } from "node:child_process";
 //#region src/lockfile/generator.ts
@@ -158,7 +158,7 @@ function transformWorkflow(workflow, sourceFile, exportRef, bundleSource, gitRoo
 			...workflow.concurrency.max !== void 0 && { max: workflow.concurrency.max }
 		} },
 		...workflow.timeout !== void 0 && { timeout: workflow.timeout },
-		...workflow.requireApproval !== void 0 && { approval: toLockApproval(workflow.requireApproval) }
+		...workflow.approval !== void 0 && { approval: (assertNonStepApprovalScope(workflow.approval, "workflow"), toLockApproval(workflow.approval)) }
 	};
 }
 /**
@@ -565,12 +565,13 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.timeout !== void 0 && { timeout: job.timeout },
 		...job.resources !== void 0 && { resources: job.resources },
 		...job.init !== void 0 && { init: job.init },
-		...job.requireApproval !== void 0 && { approval: toLockApproval(job.requireApproval) }
+		...job.approval !== void 0 && { approval: (assertNonStepApprovalScope(job.approval, "job"), toLockApproval(job.approval)) }
 	};
 }
 /**
 * Resolve needs to lock file format.
-* Handles strings, Job objects, DynamicGroupRef, and object forms with ifFailed policy.
+* Handles strings, Job objects, DynamicGroupRef, and object forms with a `when`
+* run condition (normalized to a `runOn` status-set via the engine helper).
 * Uses the UUID-to-renamed-name mapping so that references to id-less jobs
 * resolve to their lock file names (job-N) instead of the original UUIDs.
 */
@@ -582,26 +583,26 @@ function resolveNeedsForLock(needs, uuidToName) {
 	else if (isDynamicGroupRef(need)) {
 		resolvedNeeds.push({
 			group: need.group,
-			ifFailed: need.ifFailed ?? "skip"
+			runOn: resolveWhenToRunOn(need.when)
 		});
 		groups.push(need.group);
+	} else if ("_tag" in need && need._tag === "Job") {
+		const name = need.name;
+		resolvedNeeds.push(uuidToName?.get(name) ?? name);
 	} else if ("group" in need && typeof need.group === "string") {
 		const g = need;
 		resolvedNeeds.push({
 			group: g.group,
-			ifFailed: g.ifFailed ?? "skip"
+			runOn: resolveWhenToRunOn(g.when)
 		});
 		groups.push(g.group);
-	} else if ("ifFailed" in need && "name" in need) {
+	} else {
 		const n = need;
 		const name = uuidToName?.get(n.name) ?? n.name;
 		resolvedNeeds.push({
 			name,
-			ifFailed: n.ifFailed
+			runOn: resolveWhenToRunOn(n.when)
 		});
-	} else {
-		const name = need.name;
-		resolvedNeeds.push(uuidToName?.get(name) ?? name);
 	}
 	return {
 		needs: resolvedNeeds,
@@ -613,15 +614,31 @@ function resolveNeedsForLock(needs, uuidToName) {
 * Assigns counter-based IDs to unnamed steps (bare functions and id-less steps).
 * Counter only increments for unnamed entries; named steps keep their names.
 */
-/** Map an SDK `requireApproval` to the normalized lock `approval` block. */
-function toLockApproval(r) {
-	const n = normalizeRequireApproval(r);
+/** Map an SDK `approval` to the normalized lock `approval` block. */
+function toLockApproval(c) {
+	const n = normalizeApproval(c);
 	return {
 		clauses: n.clauses,
 		...n.reason !== void 0 && { reason: n.reason },
-		...n.timeoutSeconds !== void 0 && { timeoutSeconds: n.timeoutSeconds }
+		...n.timeoutSeconds !== void 0 && { timeoutSeconds: n.timeoutSeconds },
+		when: n.when
 	};
 }
+/**
+* Validate an approval config at job/workflow scope: `when: 'drift'` is a
+* step-scope-only gate (it fires between a step's check and run), so it is a
+* compile error anywhere else.
+*/
+function assertNonStepApprovalScope(c, scope) {
+	if (normalizeApproval(c).when === "drift") throw new Error(`approval.when "drift" is only valid on steps (found at ${scope} scope)`);
+}
+/**
+* Validate a step's approval config: `when: 'drift'` fires between the step's
+* check and run, so it requires a `check` facet. A compile error otherwise.
+*/
+function assertStepApprovalCheckFacet(step) {
+	if (step.approval !== void 0 && normalizeApproval(step.approval).when === "drift" && step.check === void 0) throw new Error(`step '${step.name || "(unnamed)"}': approval.when "drift" requires a check facet`);
+}
 function transformSteps(steps, gitRoot) {
 	let stepCounter = 0;
 	return steps.map((stepOrFn) => {
@@ -650,7 +667,9 @@ function transformSteps(steps, gitRoot) {
 			},
 			...step.onCancel !== void 0 && { hasOnCancel: true },
 			...step.cleanup !== void 0 && { hasCleanup: true },
-			...step.requireApproval !== void 0 && { approval: toLockApproval(step.requireApproval) }
+			...step.check !== void 0 && { hasCheck: true },
+			...step.whenInSync !== void 0 && { hasWhenInSync: true },
+			...step.approval !== void 0 && { approval: (assertStepApprovalCheckFacet(step), toLockApproval(step.approval)) }
 		};
 	});
 }

package/dist/remote/config.d.ts

@@ -9,6 +9,8 @@ export interface GlobalConfig {
     endpoint?: string;
     /** Platform relay URL */
     platformEndpoint?: string;
+    /** OIDC issuer URL the PAT was minted against (provenance; from OAuth login) */
+    oidcIssuer?: string;
     /** Routing key for webhook source identification (e.g., 'github:42') */
     routingKey?: string;
     /** Personal access token (from OAuth login) */

package/dist/remote/config.js

@@ -14,6 +14,7 @@ function sanitizeConfig(raw) {
 	if (typeof obj.token === "string") config.token = obj.token;
 	if (typeof obj.endpoint === "string") config.endpoint = obj.endpoint;
 	if (typeof obj.platformEndpoint === "string") config.platformEndpoint = obj.platformEndpoint;
+	if (typeof obj.oidcIssuer === "string") config.oidcIssuer = obj.oidcIssuer;
 	if (typeof obj.routingKey === "string") config.routingKey = obj.routingKey;
 	if (typeof obj.pat === "string") config.pat = obj.pat;
 	if (typeof obj.patId === "string") config.patId = obj.patId;

package/dist/remote/platform-client.d.ts

@@ -10,6 +10,7 @@
  * The overlay tarball does NOT flow through here: `initUpload` returns an
  * external presigned URL the CLI PUTs to directly (data plane).
  */
+import type { CheckMode, HostTargetSelector } from '@kici-dev/engine';
 export declare class AuthenticationError extends Error {
     constructor(message?: string);
 }
@@ -70,6 +71,17 @@ export interface PlatformTriggerInput {
     secrets?: Record<string, string>;
     encryptedSecrets?: string;
     encryptedSecretsKey?: string;
+    /**
+     * Run mode for the dispatched run (`apply` | `check` | `check-fail-on-drift`).
+     * The Platform relays it onto the dispatch event so the orchestrator runs the
+     * agent step loop in the requested mode. Omitted means `apply`.
+     */
+    checkMode?: CheckMode;
+    /**
+     * Host narrowing from `kici run --target`. The Platform relays it verbatim to
+     * the orchestrator, which intersects each runsOnAll roster with it.
+     */
+    target?: HostTargetSelector;
 }
 export interface PlatformTriggerResponse {
     runId: string;

package/dist/templates/package-json.js

@@ -1,6 +1,6 @@
 import "../chunk-BTugEXQM.js";
 //#region src/templates/package-json.ts
-const sdkVersion = "0.1.20";
+const sdkVersion = "0.1.22";
 /**
 * Generate package.json content for .kici/ directory
 *

package/dist/test-runner/job-executor.d.ts

@@ -1,5 +1,6 @@
 import type { Job, Workflow } from '@kici-dev/sdk';
 import type { OutputsMap, StepRefMap } from '@kici-dev/sdk';
+import type { CheckStepOutcome } from '@kici-dev/engine';
 import type { SimulatedEvent } from '@kici-dev/engine';
 import type { RuleResult } from '@kici-dev/sdk';
 import type { ParsedSecrets } from './secrets-file.js';
@@ -15,10 +16,14 @@ interface SdkOutputSetters {
 }
 export interface StepResult {
     name: string;
-    status: 'success' | 'failure';
+    status: 'success' | 'failure' | 'skipped';
     durationMs: number;
     error?: Error;
     outputs?: Record<string, unknown>;
+    /** Idempotent per-step outcome under a non-default check mode. */
+    checkOutcome?: CheckStepOutcome;
+    /** Human-readable drift summary, present when drift was detected. */
+    driftSummary?: string;
 }
 export interface JobResult {
     name: string;

package/dist/test-runner/step-context.js

@@ -133,7 +133,12 @@ function createStepContext(workflowInfo, jobInfo, repoRoot, inputs = {}, matrix,
 				scalers: [],
 				agents: []
 			}) },
-			oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available in the local test runner")) }
+			inventory: {
+				query: () => Promise.resolve([]),
+				get: () => Promise.resolve(null)
+			},
+			oidc: { token: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is not available in the local test runner")) },
+			host: { requestReboot: () => Promise.reject(/* @__PURE__ */ new Error("ctx.kici.host.requestReboot() is not available in the local test runner")) }
 		},
 		cache: {
 			restore: async () => ({ hit: false }),

package/dist/types.d.ts

@@ -12,18 +12,23 @@
  * v15 adds per-job init config(s).
  * v17 widens per-job init to typed presets ('mise' / { mise }) and 'auto' detection.
  */
-import type { ResourceRequest, ApproverClause, RunsOnAllPredicate, OnUnreachableMode, LabelMatcher } from '@kici-dev/engine';
+import type { ResourceRequest, ApproverClause, RunsOnAllPredicate, OnUnreachableMode, LabelMatcher, ExecutionJobStatus } from '@kici-dev/engine';
 /**
  * Normalized approval config carried in the lock file. Mirrors the engine
- * `LockApproval` type. Produced by the compiler from an SDK `requireApproval`.
+ * `LockApproval` type. Produced by the compiler from an SDK `approval` config.
  */
 export interface LockApproval {
     readonly clauses: ApproverClause[];
     readonly reason?: string;
     readonly timeoutSeconds?: number;
+    /**
+     * When the gate fires. `always` (default) gates before the element; `drift`
+     * gates between a step's check and run on detected drift (step scope only).
+     */
+    readonly when: 'always' | 'drift';
 }
 /** Schema version - re-exported from engine as single source of truth */
-export declare const SCHEMA_VERSION: 20;
+export declare const SCHEMA_VERSION: 22;
 /**
  * Source file reference with meaningful path.
  * Format: file is relative path from git root, export uses hash syntax.
@@ -334,6 +339,15 @@ export interface LockStep {
     readonly hasOnCancel?: boolean;
     /** Whether this step has a cleanup hook. */
     readonly hasCleanup?: boolean;
+    /**
+     * Whether this step declares an idempotent `check` facet. When true the
+     * orchestrator knows the step is check-capable and a run can be dispatched in
+     * check mode. The check/apply closures themselves are never serialized — the
+     * agent re-evaluates the real workflow TypeScript.
+     */
+    readonly hasCheck?: boolean;
+    /** Whether this step declares a `whenInSync` facet (produces outputs when in sync). */
+    readonly hasWhenInSync?: boolean;
     /** Normalized approval gate; when set the step pauses for a human approval. */
     readonly approval?: LockApproval;
 }
@@ -358,15 +372,15 @@ export declare function isLockInlineValue(value: unknown): value is LockInlineVa
  * (e.g., `kici:role:builder`, `kici:role:init-runner`) are injected by the orchestrator
  * for internal job types (build/init) and are not user-settable.
  */
-/** Needs entry with per-edge failure policy (mirrors engine NeedsEntry). */
+/** Needs entry with per-edge run-on status-set (mirrors engine NeedsEntry). */
 export interface LockNeedsEntry {
     readonly name: string;
-    readonly ifFailed: 'skip' | 'run';
+    readonly runOn: ExecutionJobStatus[];
 }
 /** Needs group entry for dynamic group dependencies (mirrors engine NeedsGroupEntry). */
 export interface LockNeedsGroupEntry {
     readonly group: string;
-    readonly ifFailed: 'skip' | 'run';
+    readonly runOn: ExecutionJobStatus[];
 }
 export interface LockJob {
     readonly _type: 'static';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/compiler",
-  "version": "0.1.20",
+  "version": "0.1.22",
   "description": "Compiler and CLI for KiCI workflows. Compiles `.kici/workflows/*.ts` to a `kici.lock.json` file consumed by the orchestrator and agents, and runs workflows locally or against a remote orchestrator.",
   "keywords": [
     "ci",
@@ -63,11 +63,11 @@
     "yaml": "^2.9.0",
     "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.20",
-    "@kici-dev/engine": "0.1.20"
+    "@kici-dev/core": "0.1.22",
+    "@kici-dev/engine": "0.1.22"
   },
   "peerDependencies": {
-    "@kici-dev/sdk": "0.1.20"
+    "@kici-dev/sdk": "0.1.22"
   },
   "devDependencies": {
     "@types/proper-lockfile": "^4.1.4"