@kici-dev/compiler 0.1.26 → 0.2.0

package/dist/local-plane/source-provider.js

@@ -0,0 +1,159 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { selectOverlayFiles } from "../remote/uploader.js";
+import path from "node:path";
+import fs from "node:fs/promises";
+import { execFileSync, execSync } from "node:child_process";
+import { makeTempDir } from "@kici-dev/core/tmp";
+//#region src/local-plane/source-provider.ts
+/**
+* LocalSourceProvider — resolve the workdir a `kici run --local` dispatch
+* registers as a `file://` source for the plane.
+*
+* The plane orchestrator's local provider fetches the lock from
+* `<repoBasePath>/.kici/kici.lock.json` and the ephemeral agent clones
+* `file://<repoBasePath>` at a committed sha. So the resolved workdir must be a
+* git repo whose HEAD carries the workflow + lock the run should execute.
+*
+* Two profiles:
+* - **default (isolated):** an isolated tmp clone at HEAD with the local overlay
+*   (dirty + untracked files) applied and committed onto a `kici-local` branch,
+*   so the clone-by-sha the agent performs sees uncommitted work without
+*   touching the developer's tree.
+* - **`--in-place`:** the repo root directly (ambient state, the profile the CI
+*   deploy jobs use). Cleanup is a no-op.
+*/
+/** The `kici-local` branch the isolated profile commits its overlay onto. */
+const LOCAL_RUN_BRANCH = "kici-local";
+/** Max number of overlay files copied concurrently. */
+const COPY_BATCH_SIZE = 32;
+/**
+* Resolve the workdir for an offline routed run.
+*
+* @param opts.inPlace - Use the repo root directly instead of an isolated clone.
+* @param opts.repoRoot - The developer's repo root.
+*/
+async function resolveWorkdir(opts) {
+	requireGitRepo(opts.repoRoot);
+	return opts.inPlace ? resolveInPlace(opts.repoRoot) : resolveIsolated(opts.repoRoot);
+}
+/** In-place: the repo root, triggered at its current branch + HEAD. */
+function resolveInPlace(repoRoot) {
+	const branch = gitOut(repoRoot, [
+		"rev-parse",
+		"--abbrev-ref",
+		"HEAD"
+	]);
+	const sha = gitOut(repoRoot, ["rev-parse", "HEAD"]);
+	return {
+		dir: repoRoot,
+		ref: `refs/heads/${branch}`,
+		sha,
+		branch,
+		cleanup: async () => {}
+	};
+}
+/**
+* Isolated: a tmp clone at HEAD with the local overlay applied and committed
+* onto the `kici-local` branch, then commits so the agent's clone-by-sha
+* carries the work.
+*/
+async function resolveIsolated(repoRoot) {
+	const workdir = await makeTempDir("local-run", { persist: true });
+	const tmpDir = workdir.path;
+	const { sha, existingFiles, deletedFiles } = await selectOverlayFiles(repoRoot);
+	execSync(`git clone --no-hardlinks --quiet ${shellQuote(repoRoot)} ${shellQuote(tmpDir)}`, { stdio: "ignore" });
+	execSync(`git checkout --quiet ${sha}`, {
+		cwd: tmpDir,
+		stdio: "ignore"
+	});
+	await applyOverlay(repoRoot, tmpDir, existingFiles, deletedFiles);
+	execFileSync("git", [
+		"checkout",
+		"-B",
+		LOCAL_RUN_BRANCH
+	], {
+		cwd: tmpDir,
+		stdio: "ignore"
+	});
+	execFileSync("git", ["add", "-A"], {
+		cwd: tmpDir,
+		stdio: "ignore"
+	});
+	if (gitOut(tmpDir, ["status", "--porcelain"])) execFileSync("git", [
+		"-c",
+		"user.email=local@kici.dev",
+		"-c",
+		"user.name=kici local",
+		"commit",
+		"--no-verify",
+		"--no-gpg-sign",
+		"-m",
+		"kici run --local overlay"
+	], {
+		cwd: tmpDir,
+		stdio: "ignore"
+	});
+	const committed = gitOut(tmpDir, ["rev-parse", "HEAD"]);
+	return {
+		dir: tmpDir,
+		ref: `refs/heads/${LOCAL_RUN_BRANCH}`,
+		sha: committed,
+		branch: LOCAL_RUN_BRANCH,
+		cleanup: () => workdir.cleanup()
+	};
+}
+/** Copy overlay files onto the clone and remove local deletions. */
+async function applyOverlay(repoRoot, tmpDir, existingFiles, deletedFiles) {
+	for (let i = 0; i < existingFiles.length; i += COPY_BATCH_SIZE) {
+		const batch = existingFiles.slice(i, i + COPY_BATCH_SIZE);
+		await Promise.all(batch.map((file) => copyOverlayFile(repoRoot, tmpDir, file)));
+	}
+	for (let i = 0; i < deletedFiles.length; i += COPY_BATCH_SIZE) {
+		const batch = deletedFiles.slice(i, i + COPY_BATCH_SIZE);
+		await Promise.all(batch.map((file) => fs.rm(path.join(tmpDir, file), { force: true })));
+	}
+}
+/**
+* Copy a single overlay file, preserving its mode. Symlinks are recreated as
+* links (not dereferenced) — the same shape the remote tarball preserves.
+*/
+async function copyOverlayFile(repoRoot, tmpDir, file) {
+	const src = path.join(repoRoot, file);
+	const dest = path.join(tmpDir, file);
+	await fs.mkdir(path.dirname(dest), { recursive: true });
+	const srcStat = await fs.lstat(src);
+	if (srcStat.isSymbolicLink()) {
+		const target = await fs.readlink(src);
+		await fs.rm(dest, { force: true });
+		await fs.symlink(target, dest);
+		return;
+	}
+	await fs.copyFile(src, dest);
+	await fs.chmod(dest, srcStat.mode);
+}
+/** Throw an actionable error if `repoRoot` is not a git work tree. */
+function requireGitRepo(repoRoot) {
+	try {
+		execSync("git rev-parse --is-inside-work-tree", {
+			cwd: repoRoot,
+			stdio: "ignore"
+		});
+	} catch {
+		throw new Error(`kici run --local needs a git repository, but "${repoRoot}" is not inside a git work tree. Initialize a repo (git init) before running.`);
+	}
+}
+/** Run a git command in `cwd` and return trimmed stdout. */
+function gitOut(cwd, args) {
+	return execFileSync("git", args, {
+		cwd,
+		encoding: "utf8"
+	}).trim();
+}
+/** Minimal single-quote shell escaping for paths passed to git via execSync. */
+function shellQuote(value) {
+	return `'${value.replace(/'/g, `'\\''`)}'`;
+}
+//#endregion
+export { LOCAL_RUN_BRANCH, resolveWorkdir };
+
+//# sourceMappingURL=source-provider.js.map

package/dist/local-plane/trusted-routing.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Route a `kici run --local --trusted` run onto the plane's trusted label set
+ * by appending a routing label to every job's `runsOn` in the workdir lock the
+ * plane orchestrator reads.
+ *
+ * The orchestrator resolves each job's target agent from the lock's `runsOn`
+ * selectors (subset match + smallest-set-wins in the scaler label matcher).
+ * A default run leaves `runsOn` untouched, so a `runsOn: ['default']` job lands
+ * on the sandboxed `['default']` label set — byte-identical to a non-trusted
+ * run. `--trusted` appends the non-reserved `self-hosted` label, which only the
+ * trusted `['default','self-hosted']` label set carries, forcing every job onto
+ * the trusted profile.
+ *
+ * This is routing-by-label to a PRE-CONFIGURED trusted scaler label set — the
+ * `KICI_TRUSTED_ENV` value lives only in that label set's env (the plane's own
+ * config), never on a dispatch payload. The lock patch adds a label
+ * requirement, not the trusted flag itself.
+ */
+/** Handle to restore the lock to its pre-patch bytes. */
+export interface RunsOnLabelInjection {
+    /** Rewrite the original bytes captured before the patch. */
+    restore: () => void;
+}
+/**
+ * Append an exact-match `runsOn` selector for `label` to every job in the lock
+ * at `lockPath`, unless the job already requires it. Returns a `restore()` that
+ * rewrites the original file bytes (call it in a `finally` — for an in-place run
+ * it un-dirties the developer's tree; for an isolated run the throwaway clone is
+ * removed anyway).
+ */
+export declare function injectRunsOnLabel(lockPath: string, label: string): RunsOnLabelInjection;
+//# sourceMappingURL=trusted-routing.d.ts.map

package/dist/local-plane/trusted-routing.js

@@ -0,0 +1,47 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import fs from "node:fs";
+//#region src/local-plane/trusted-routing.ts
+/**
+* Route a `kici run --local --trusted` run onto the plane's trusted label set
+* by appending a routing label to every job's `runsOn` in the workdir lock the
+* plane orchestrator reads.
+*
+* The orchestrator resolves each job's target agent from the lock's `runsOn`
+* selectors (subset match + smallest-set-wins in the scaler label matcher).
+* A default run leaves `runsOn` untouched, so a `runsOn: ['default']` job lands
+* on the sandboxed `['default']` label set — byte-identical to a non-trusted
+* run. `--trusted` appends the non-reserved `self-hosted` label, which only the
+* trusted `['default','self-hosted']` label set carries, forcing every job onto
+* the trusted profile.
+*
+* This is routing-by-label to a PRE-CONFIGURED trusted scaler label set — the
+* `KICI_TRUSTED_ENV` value lives only in that label set's env (the plane's own
+* config), never on a dispatch payload. The lock patch adds a label
+* requirement, not the trusted flag itself.
+*/
+/**
+* Append an exact-match `runsOn` selector for `label` to every job in the lock
+* at `lockPath`, unless the job already requires it. Returns a `restore()` that
+* rewrites the original file bytes (call it in a `finally` — for an in-place run
+* it un-dirties the developer's tree; for an isolated run the throwaway clone is
+* removed anyway).
+*/
+function injectRunsOnLabel(lockPath, label) {
+	const original = fs.readFileSync(lockPath, "utf-8");
+	const lock = JSON.parse(original);
+	for (const workflow of lock.workflows ?? []) for (const job of workflow.jobs ?? []) {
+		const runsOn = job.runsOn ??= [];
+		if (!runsOn.some((m) => m.kind === "exact" && m.value === label)) runsOn.push({
+			kind: "exact",
+			value: label
+		});
+	}
+	fs.writeFileSync(lockPath, JSON.stringify(lock, null, 2) + "\n");
+	return { restore: () => {
+		fs.writeFileSync(lockPath, original);
+	} };
+}
+//#endregion
+export { injectRunsOnLabel };
+
+//# sourceMappingURL=trusted-routing.js.map

package/dist/lockfile/generator.d.ts

@@ -1,5 +1,18 @@
 import type { StepInput, TriggerConfig } from '@kici-dev/sdk';
 import { type LockFile, type LockTrigger, type LockStepEntry, type WorkflowWithSource } from '../types.js';
+import { type SourceLocation } from '../errors/index.js';
+/**
+ * Courtesy compatibility warning for `kici compile`.
+ *
+ * When the current schema version is itself a breaking version
+ * (`floor === version`), locks emitted now stamp `minReaderVersion = version`
+ * and cannot be read by orchestrators older than that version — return a
+ * one-line heads-up naming the required orchestrator schema. When the floor sits
+ * below the current version (`floor < version`) the emitted lock is additive
+ * over older readers down to the floor, so no warning is warranted (return
+ * null). The orchestrator remains the authoritative reject; this is informational.
+ */
+export declare function schemaWindowWarning(floor: number, version: number): string | null;
 /**
  * Detect git repository root by running `git rev-parse --show-toplevel`.
  * Falls back to cwd if not in a git repo.
@@ -47,7 +60,7 @@ export declare function transformTriggers(triggers?: TriggerConfig[]): readonly
  * compiler's naming matches the agent's `extractAndNormalizeSteps` enumeration —
  * the flat-stepIndex invariant.
  */
-export declare function transformSteps(steps: readonly StepInput[], gitRoot: string): readonly LockStepEntry[];
+export declare function transformSteps(steps: readonly StepInput[], gitRoot: string, jobLocation?: SourceLocation): readonly LockStepEntry[];
 /**
  * Serialize lock file to JSON string.
  *

package/dist/lockfile/generator.js

@@ -1,5 +1,8 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { SCHEMA_VERSION as SCHEMA_VERSION$1 } from "../types.js";
+import { compilerError } from "../errors/formatter.js";
+import { locationForJob, locationForWorkflow } from "../errors/source-location.js";
+import "../errors/index.js";
+import { BREAKING_FLOOR as BREAKING_FLOOR$1, SCHEMA_VERSION as SCHEMA_VERSION$1 } from "../types.js";
 import { computeContentHash } from "./hasher.js";
 import { resolveHashFiles } from "./hash-files.js";
 import { analyzePurity } from "./purity-analyzer.js";
@@ -13,6 +16,21 @@ import { normalizeRunsOnAllToMatchers, normalizeRunsOnToMatchers, runsOnPickFrom
 import { execSync } from "node:child_process";
 //#region src/lockfile/generator.ts
 /**
+* Courtesy compatibility warning for `kici compile`.
+*
+* When the current schema version is itself a breaking version
+* (`floor === version`), locks emitted now stamp `minReaderVersion = version`
+* and cannot be read by orchestrators older than that version — return a
+* one-line heads-up naming the required orchestrator schema. When the floor sits
+* below the current version (`floor < version`) the emitted lock is additive
+* over older readers down to the floor, so no warning is warranted (return
+* null). The orchestrator remains the authoritative reject; this is informational.
+*/
+function schemaWindowWarning(floor, version) {
+	if (floor < version) return null;
+	return `This lock uses schema v${version}, a breaking schema version — orchestrators older than v${version} cannot read it. Upgrade the orchestrator to schema v${version} or newer before it can dispatch from this lock.`;
+}
+/**
 * Detect git repository root by running `git rev-parse --show-toplevel`.
 * Falls back to cwd if not in a git repo.
 *
@@ -96,9 +114,11 @@ function generateLockFile(workflowsWithSource) {
 	});
 	return {
 		schemaVersion: SCHEMA_VERSION$1,
+		minReaderVersion: BREAKING_FLOOR$1,
 		source: topLevelSource,
 		contentHash: sha256(JSON.stringify({
 			schemaVersion: SCHEMA_VERSION$1,
+			minReaderVersion: BREAKING_FLOOR$1,
 			source: topLevelSource,
 			workflows
 		})),
@@ -158,7 +178,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.approval !== void 0 && { approval: (assertNonStepApprovalScope(workflow.approval, "workflow"), toLockApproval(workflow.approval)) }
+		...workflow.approval !== void 0 && { approval: (assertNonStepApprovalScope(workflow.approval, "workflow", locationForWorkflow(sourceFile)), toLockApproval(workflow.approval)) }
 	};
 }
 /**
@@ -316,6 +336,14 @@ function toLockWorkflowComplete(t) {
 		...t.source !== void 0 && { source: t.source }
 	};
 }
+function toLockWorkflowsFailedBatch(t) {
+	return {
+		_type: "workflows_failed_batch",
+		accumulateFor: t.accumulateFor,
+		...t.name !== void 0 && { name: t.name },
+		...t.source !== void 0 && { source: t.source }
+	};
+}
 function toLockJobComplete(t) {
 	return {
 		_type: "job_complete",
@@ -383,6 +411,7 @@ function transformOneTrigger(trigger) {
 		case "WebhookTrigger": return [toLockWebhook(trigger)];
 		case "KiciEventTrigger": return [toLockKiciEvent(trigger)];
 		case "WorkflowCompleteTrigger": return [toLockWorkflowComplete(trigger)];
+		case "WorkflowsFailedBatchTrigger": return [toLockWorkflowsFailedBatch(trigger)];
 		case "JobCompleteTrigger": return [toLockJobComplete(trigger)];
 		case "GenericWebhookTrigger": return [toLockGenericWebhook(trigger)];
 		case "ScheduleTrigger": return [toLockSchedule(trigger)];
@@ -478,30 +507,31 @@ function normalizeRunsOnForLock(runsOn, jobName) {
 * The overlap check compares exact matchers only — a glob/regex include and an
 * exact exclude (or vice versa) cannot be statically known to overlap.
 */
-function validateRunsOn(runsOn, jobName) {
+function validateRunsOn(runsOn, jobName, location) {
 	const { include, exclude } = normalizeRunsOnToMatchers(runsOn, `job '${jobName}' runsOn`);
 	const includeExact = new Set(include.filter((m) => m.kind === "exact").map((m) => m.value));
 	const overlap = exclude.filter((m) => m.kind === "exact").map((m) => m.value).filter((v) => includeExact.has(v));
-	if (overlap.length > 0) throw new Error(`Job "${jobName}": labels and exclude overlap on [${overlap.join(", ")}]. A label cannot be both required and excluded.`);
+	if (overlap.length > 0) throw compilerError("E112", `Job "${jobName}": labels and exclude overlap on [${overlap.join(", ")}]. A label cannot be both required and excluded.`, {
+		location,
+		suggestion: "Remove the overlapping label(s) from either runsOn or the exclude set."
+	});
 }
 /**
-* Transform one environment reference (static name or function) into a lock
+* Transform one context reference (static name or function) into a lock
 * `{ value, dynamic }` entry. A function element is analyzed for purity: a pure
 * function becomes an inline expression resolvable at two-phase eval; an impure
 * one carries only the `dynamic` flag (the agent runs an init job to resolve it).
 */
-function transformEnvironmentRef(ref, jobName) {
+function transformContextRef(ref) {
 	if (typeof ref === "function") {
 		const fnSource = ref.toString();
-		const purity = analyzePurity(fnSource);
-		if (purity.pure) return {
+		if (analyzePurity(fnSource).pure) return {
 			value: {
 				_type: "inline",
 				expression: fnSource
 			},
 			dynamic: true
 		};
-		console.warn(`[kici] Job "${jobName}": environment function is not pure (${purity.reason}). An init job will be required, adding ~5-10s delay.`);
 		return {
 			value: "",
 			dynamic: true
@@ -516,15 +546,25 @@ function transformEnvironmentRef(ref, jobName) {
 * Transform a static job to lock file format.
 */
 function transformJob(job, configPath, index, gitRoot, uuidToName) {
-	if (job.runsOn !== void 0 && job.runsOnAll !== void 0) throw new Error(`job '${job.name}': runsOn and runsOnAll are mutually exclusive`);
-	if (job.runsOn === void 0 && job.runsOnAll === void 0) throw new Error(`job '${job.name}': one of runsOn or runsOnAll is required`);
+	const jobLocation = locationForJob(job, configPath);
+	if (job.runsOn !== void 0 && job.runsOnAll !== void 0) throw compilerError("E108", `job '${job.name}': runsOn and runsOnAll are mutually exclusive`, {
+		location: jobLocation,
+		suggestion: "Set exactly one of runsOn (single agent) or runsOnAll (fan-out to every matching agent)."
+	});
+	if (job.runsOn === void 0 && job.runsOnAll === void 0) throw compilerError("E109", `job '${job.name}': one of runsOn or runsOnAll is required`, {
+		location: jobLocation,
+		suggestion: "Add runsOn: \"kici:os:linux\" (or another agent label) to the job."
+	});
 	if (job.onUnreachable !== void 0 && job.runsOnAll === void 0) console.warn(`[kici] job '${job.name}': onUnreachable is ignored without runsOnAll`);
-	if (job.maxParallel !== void 0 && job.maxParallel < 1) throw new Error(`job '${job.name}': maxParallel must be >= 1`);
+	if (job.maxParallel !== void 0 && job.maxParallel < 1) throw compilerError("E110", `job '${job.name}': maxParallel must be >= 1`, {
+		location: jobLocation,
+		suggestion: "Set maxParallel to a positive integer, or remove it to run unbounded."
+	});
 	if (!(job.matrix !== void 0 || job.runsOnAll !== void 0) && (job.maxParallel !== void 0 || job.failFast !== void 0)) console.warn(`[kici] job '${job.name}': maxParallel/failFast are ignored without matrix or runsOnAll (no fan-out to bound)`);
-	if (job.runsOn !== void 0) validateRunsOn(job.runsOn, job.name);
-	const environmentFields = {};
-	const envRefs = job.environments ?? (job.environment !== void 0 ? [job.environment] : void 0);
-	if (envRefs !== void 0 && envRefs.length > 0) environmentFields.environments = envRefs.map((ref) => transformEnvironmentRef(ref, job.name));
+	if (job.runsOn !== void 0) validateRunsOn(job.runsOn, job.name, jobLocation);
+	const contextFields = {};
+	const contextRefs = job.contexts ?? (job.context !== void 0 ? [job.context] : void 0);
+	if (contextRefs !== void 0 && contextRefs.length > 0) contextFields.contexts = contextRefs.map((ref) => transformContextRef(ref));
 	const envFields = {};
 	if (job.env !== void 0) {
 		if (typeof job.env === "function") {
@@ -535,14 +575,16 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 				_type: "inline",
 				expression: fnSource
 			};
-			else console.warn(`[kici] Job "${job.name}": env function is not pure (${purity.reason}). An init job will be required, adding ~5-10s delay.`);
 		} else if (typeof job.env === "object") envFields.env = { ...job.env };
 	}
 	if (job.resources !== void 0) try {
 		validateResourceRequest(job.resources);
 	} catch (err) {
 		const reason = err instanceof Error ? err.message : String(err);
-		throw new Error(`Job "${job.name}": invalid resources -- ${reason}`);
+		throw compilerError("E111", `Job "${job.name}": invalid resources -- ${reason}`, {
+			location: jobLocation,
+			suggestion: "Fix the resources request (valid CPU/memory strings, request <= limit)."
+		});
 	}
 	const concurrencyFields = {};
 	if (job.concurrencyGroup !== void 0) {
@@ -554,7 +596,6 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 				_type: "inline",
 				expression: fnSource
 			};
-			else console.warn(`[kici] Job "${job.name}": concurrencyGroup function is not pure (${purity.reason}). An init job will be required, adding ~5-10s delay.`);
 		} else if (typeof job.concurrencyGroup === "string") concurrencyFields.concurrencyGroup = job.concurrencyGroup;
 	}
 	return {
@@ -567,7 +608,7 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.maxParallel !== void 0 && { maxParallel: job.maxParallel },
 		...job.failFast !== void 0 && { failFast: job.failFast },
 		...resolveNeedsForLock(job.needs, uuidToName),
-		steps: transformSteps(job.steps, gitRoot),
+		steps: transformSteps(job.steps, gitRoot, jobLocation),
 		matrix: job.matrix ? transformMatrix(job.matrix, job.name, configPath) : void 0,
 		include: job.include?.map((inc) => ({ ...inc })),
 		exclude: job.exclude?.map((exc) => ({ ...exc })),
@@ -576,7 +617,8 @@ function transformJob(job, configPath, index, gitRoot, uuidToName) {
 		...job.checkout !== void 0 && { checkout: job.checkout },
 		...job.cache !== void 0 && { cache: normalizeCacheSpecs(job.cache) },
 		...job.container !== void 0 && { container: job.container },
-		...environmentFields,
+		...job.sandbox !== void 0 && { sandbox: job.sandbox },
+		...contextFields,
 		...envFields,
 		...concurrencyFields,
 		...job.onCancel !== void 0 && { hasOnCancel: true },
@@ -589,7 +631,7 @@ 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.approval !== void 0 && { approval: (assertNonStepApprovalScope(job.approval, "job"), toLockApproval(job.approval)) }
+		...job.approval !== void 0 && { approval: (assertNonStepApprovalScope(job.approval, "job", jobLocation), toLockApproval(job.approval)) }
 	};
 }
 /**
@@ -653,15 +695,21 @@ function toLockApproval(c) {
 * 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)`);
+function assertNonStepApprovalScope(c, scope, location) {
+	if (normalizeApproval(c).when === "drift") throw compilerError("E113", `approval.when "drift" is only valid on steps (found at ${scope} scope)`, {
+		location,
+		suggestion: "Move the drift-gated approval onto a step, or use when: \"always\" at job/workflow 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 assertStepApprovalCheckFacet(step, jobLocation) {
+	if (step.approval !== void 0 && normalizeApproval(step.approval).when === "drift" && step.check === void 0) throw compilerError("E114", `step '${step.name || "(unnamed)"}': approval.when "drift" requires a check facet`, {
+		location: step._sourceLocation ?? jobLocation,
+		suggestion: "Add a check facet to the step, or use approval when: \"always\"."
+	});
 }
 /**
 * Transform a job's `steps` array into lock-file entries. Sequential steps and
@@ -670,22 +718,40 @@ function assertStepApprovalCheckFacet(step) {
 * compiler's naming matches the agent's `extractAndNormalizeSteps` enumeration —
 * the flat-stepIndex invariant.
 */
-function transformSteps(steps, gitRoot) {
+function transformSteps(steps, gitRoot, jobLocation) {
+	const anchor = jobLocation ?? {
+		file: "",
+		line: 1,
+		column: 1
+	};
 	const counter = { n: 0 };
 	let groupOrdinal = 0;
 	return steps.map((entry) => {
-		if (isParallelGroup(entry)) return transformParallelGroup(entry, gitRoot, counter, groupOrdinal++);
-		return transformSequentialStep(entry, gitRoot, counter);
+		if (isParallelGroup(entry)) return transformParallelGroup(entry, gitRoot, counter, groupOrdinal++, anchor);
+		return transformSequentialStep(entry, gitRoot, counter, anchor);
 	});
 }
+/** Best step-scoped location: the step's captured call-site, else the job anchor. */
+function stepEntryLocation(entry, jobLocation) {
+	return entry._sourceLocation ?? jobLocation;
+}
 /** Validate and transform a `ParallelGroup` into a `LockParallelStep`. */
-function transformParallelGroup(group, gitRoot, counter, groupOrdinal) {
-	if (group.steps.length === 0) throw new Error("job step: empty parallel group not allowed");
+function transformParallelGroup(group, gitRoot, counter, groupOrdinal, jobLocation) {
+	if (group.steps.length === 0) throw compilerError("E115", "job step: empty parallel group not allowed", {
+		location: jobLocation,
+		suggestion: "Add at least one step to the parallel group, or remove the group."
+	});
 	const seen = /* @__PURE__ */ new Set();
 	const children = group.steps.map((child) => {
-		if (isParallelGroup(child)) throw new Error("job step: nested parallel groups are not supported");
-		const lockChild = transformSequentialStep(child, gitRoot, counter);
-		if (seen.has(lockChild.name)) throw new Error(`job step: duplicate step name '${lockChild.name}' in parallel group`);
+		if (isParallelGroup(child)) throw compilerError("E116", "job step: nested parallel groups are not supported", {
+			location: stepEntryLocation(child, jobLocation),
+			suggestion: "Flatten the nested group — a parallel group may only contain steps."
+		});
+		const lockChild = transformSequentialStep(child, gitRoot, counter, jobLocation);
+		if (seen.has(lockChild.name)) throw compilerError("E117", `job step: duplicate step name '${lockChild.name}' in parallel group`, {
+			location: stepEntryLocation(child, jobLocation),
+			suggestion: "Give each step in a parallel group a unique name."
+		});
 		seen.add(lockChild.name);
 		return lockChild;
 	});
@@ -699,7 +765,7 @@ function transformParallelGroup(group, gitRoot, counter, groupOrdinal) {
 	};
 }
 /** Transform a single sequential step (or bare function) into a `LockStep`. */
-function transformSequentialStep(stepOrFn, gitRoot, counter) {
+function transformSequentialStep(stepOrFn, gitRoot, counter, jobLocation) {
 	if (typeof stepOrFn === "function") {
 		counter.n++;
 		return {
@@ -733,7 +799,7 @@ function transformSequentialStep(stepOrFn, gitRoot, counter) {
 		...step.cleanup !== void 0 && { hasCleanup: true },
 		...step.check !== void 0 && { hasCheck: true },
 		...step.whenInSync !== void 0 && { hasWhenInSync: true },
-		...step.approval !== void 0 && { approval: (assertStepApprovalCheckFacet(step), toLockApproval(step.approval)) }
+		...step.approval !== void 0 && { approval: (assertStepApprovalCheckFacet(step, jobLocation), toLockApproval(step.approval)) }
 	};
 }
 /**
@@ -812,6 +878,6 @@ function serializeLockFile(lockFile, pretty = true) {
 	return JSON.stringify(lockFile, null, pretty ? 2 : void 0);
 }
 //#endregion
-export { computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile, transformSteps, transformTriggers };
+export { computeLockfileHash, detectGitRoot, generateLockFile, schemaWindowWarning, serializeLockFile, transformSteps, transformTriggers };
 
 //# sourceMappingURL=generator.js.map

package/dist/lockfile/index.d.ts

@@ -1,3 +1,5 @@
-export { generateLockFile, serializeLockFile, detectGitRoot, computeLockfileHash, } from './generator.js';
+export { generateLockFile, serializeLockFile, detectGitRoot, computeLockfileHash, schemaWindowWarning, } from './generator.js';
 export { computeContentHash, COMPILE_SCHEMA_VERSION } from './hasher.js';
+export { DynamicValueField, analyzeJobPurity, collectWorkflowPurityWarnings, } from './purity-diagnostics.js';
+export type { JobPurityWarning } from './purity-diagnostics.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/lockfile/index.js

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { COMPILE_SCHEMA_VERSION, computeContentHash } from "./hasher.js";
-import { computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile } from "./generator.js";
-export { COMPILE_SCHEMA_VERSION, computeContentHash, computeLockfileHash, detectGitRoot, generateLockFile, serializeLockFile };
+import { computeLockfileHash, detectGitRoot, generateLockFile, schemaWindowWarning, serializeLockFile } from "./generator.js";
+import { DynamicValueField, analyzeJobPurity, collectWorkflowPurityWarnings } from "./purity-diagnostics.js";
+export { COMPILE_SCHEMA_VERSION, DynamicValueField, analyzeJobPurity, collectWorkflowPurityWarnings, computeContentHash, computeLockfileHash, detectGitRoot, generateLockFile, schemaWindowWarning, serializeLockFile };

package/dist/lockfile/purity-diagnostics.d.ts

@@ -0,0 +1,31 @@
+import type { Job } from '@kici-dev/sdk';
+import type { WorkflowWithSource } from '../types.js';
+/** Which dynamic-value slot on a job carried the impure function. */
+export declare enum DynamicValueField {
+    Context = "context",
+    Env = "env",
+    ConcurrencyGroup = "concurrencyGroup"
+}
+/**
+ * One impure dynamic-value function found on a static job. Each impurity forces
+ * the orchestrator to dispatch an agent-side `__init__` job (~5-10s) instead of
+ * inlining the value, so we surface it to the author at compile / preview time.
+ */
+export interface JobPurityWarning {
+    workflowName: string;
+    sourceFile?: string;
+    jobName: string;
+    field: DynamicValueField;
+    reason: string;
+}
+/**
+ * Analyze a single static job's dynamic-value functions (context(s), env,
+ * concurrencyGroup) for impurity. Returns one warning per impure function.
+ */
+export declare function analyzeJobPurity(job: Job, workflowName: string, sourceFile?: string): JobPurityWarning[];
+/**
+ * Walk every workflow's static jobs and collect impurity warnings. Function-typed
+ * jobs (dynamic job generators) are skipped — their purity is analyzed at dispatch.
+ */
+export declare function collectWorkflowPurityWarnings(workflows: WorkflowWithSource[]): JobPurityWarning[];
+//# sourceMappingURL=purity-diagnostics.d.ts.map