@kici-dev/sdk 0.1.27 → 0.2.0

package/dist/job-outputs.test-d.js

@@ -0,0 +1,164 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { isHostJobOutputs, isMatrixJobOutputs } from "./context.js";
+import { dynamicGroup } from "./dynamic-group.js";
+import { step } from "./step.js";
+import { job } from "./job.js";
+import { workflow } from "./workflow.js";
+import { describe, expectTypeOf, it } from "vitest";
+//#region src/job-outputs.test-d.ts
+describe("Job<TOutputs> — merged-steps inference", () => {
+	it("infers a nested output map keyed by step name for a multi-step job", () => {
+		const j = job("ci", {
+			runsOn: "kici:os:linux",
+			steps: [step("build", { run: async () => ({ version: "1.0" }) }), step("test", { run: async () => ({ passed: true }) })]
+		});
+		expectTypeOf(j.result.build.version).toEqualTypeOf();
+		expectTypeOf(j.result.test.passed).toEqualTypeOf();
+	});
+	it("rejects reading an unknown output field of a declared step", () => {
+		job("ci", {
+			runsOn: "kici:os:linux",
+			steps: [step("build", { run: async () => ({ version: "1.0" }) })]
+		}).result.build.nope;
+	});
+	it("rejects reading an undeclared step name", () => {
+		job("ci", {
+			runsOn: "kici:os:linux",
+			steps: [step("build", { run: async () => ({ version: "1.0" }) })]
+		}).result.other;
+	});
+	it("infers a flat output shape for the run: shorthand", () => {
+		const flat = job("flat", {
+			runsOn: "kici:os:linux",
+			run: async () => ({ url: "x" })
+		});
+		expectTypeOf(flat.result.url).toEqualTypeOf();
+		flat.result.nope;
+	});
+	it("honours an explicit output-type override for a dynamically-shaped job", () => {
+		expectTypeOf(job("dyn", {
+			runsOn: "kici:os:linux",
+			steps: [step(async () => ({}))]
+		}).result.n).toEqualTypeOf();
+	});
+	it("omits id-less steps and falls back to the loose shape", () => {
+		expectTypeOf(job("idless", {
+			runsOn: "kici:os:linux",
+			steps: [step(async () => ({ x: 1 }))]
+		}).result.anything).toEqualTypeOf();
+	});
+	it("keeps a typed job assignable to the bare Job type", () => {
+		expectTypeOf(job("ci", {
+			runsOn: "kici:os:linux",
+			steps: [step("build", { run: async () => ({ version: "1.0" }) })]
+		})).toEqualTypeOf();
+	});
+});
+describe("Job<void> — void run-shorthand assignability", () => {
+	it("makes a void run-shorthand job assignable to JobOrFactory (inline)", () => {
+		workflow("wf", { jobs: [job("setup", {
+			runsOn: "kici:os:linux",
+			run: async ({ $ }) => {
+				await $`echo hi`;
+			}
+		})] });
+		expectTypeOf().toMatchTypeOf();
+	});
+	it("makes a void run-shorthand job assignable to JobOrFactory (const-extracted)", () => {
+		const setup = job("setup", {
+			runsOn: "kici:os:linux",
+			run: async ({ $ }) => {
+				await $`echo hi`;
+			}
+		});
+		expectTypeOf(setup).toMatchTypeOf();
+		workflow("wf", { jobs: [setup] });
+	});
+	it("resolves result to never for a void run-shorthand job", () => {
+		expectTypeOf(job("setup", {
+			runsOn: "kici:os:linux",
+			run: async () => {}
+		}).result).toEqualTypeOf();
+	});
+	it("leaves a value-returning run job untouched (regression guard)", () => {
+		const flat = job("flat", {
+			runsOn: "kici:os:linux",
+			run: async () => ({ url: "x" })
+		});
+		expectTypeOf(flat.result.url).toEqualTypeOf();
+		expectTypeOf(flat).toMatchTypeOf();
+	});
+});
+describe("typed ctx.needs from job references", () => {
+	const ci = job("ci", {
+		runsOn: "kici:os:linux",
+		steps: [step("build", { run: async () => ({ version: "1.0" }) }), step("test", { run: async () => ({ passed: true }) })]
+	});
+	it("threads a referenced job’s inferred outputs into ctx.needs", () => {
+		job("deploy", {
+			runsOn: "kici:os:linux",
+			needs: [ci],
+			run: async (ctx) => {
+				expectTypeOf(ctx.needs.ci.result.build.version).toEqualTypeOf();
+				expectTypeOf(ctx.needs.ci.result.test.passed).toEqualTypeOf();
+			}
+		});
+	});
+	it("rejects an undeclared need and an unknown field through a need", () => {
+		job("deploy2", {
+			runsOn: "kici:os:linux",
+			needs: [ci],
+			run: async (ctx) => {
+				ctx.needs.other;
+				ctx.needs.ci.result.build.nope;
+			}
+		});
+	});
+	it("keeps string-form needs loose", () => {
+		job("loose", {
+			runsOn: "kici:os:linux",
+			needs: ["ci"],
+			run: async (ctx) => {
+				expectTypeOf(ctx.needs.ci.result).toEqualTypeOf();
+			}
+		});
+	});
+	it("falls back to the loose open map when a group need is mixed in (no regression)", () => {
+		job("mixed", {
+			runsOn: "kici:os:linux",
+			needs: [ci, dynamicGroup("shards")],
+			run: async (ctx) => {
+				expectTypeOf(ctx.needs.ci).not.toBeNever();
+				expectTypeOf(ctx.needs.shards).not.toBeNever();
+			}
+		});
+	});
+});
+describe("envelope-generic jobOutputs for typed refs", () => {
+	const ci = job("ci", {
+		runsOn: "kici:os:linux",
+		steps: [step("build", { run: async () => ({ version: "1.0" }) })]
+	});
+	const ctx = null;
+	it("types a job-ref jobOutputs as the plain | matrix | host union of the inferred shape", () => {
+		expectTypeOf(ctx.jobOutputs(ci)).toEqualTypeOf();
+	});
+	it("narrows to the typed matrix envelope via isMatrixJobOutputs", () => {
+		const out = ctx.jobOutputs(ci);
+		if (isMatrixJobOutputs(out)) {
+			expectTypeOf(out.byMatrix).toEqualTypeOf();
+			expectTypeOf(out.merged.build.version).toEqualTypeOf();
+		}
+	});
+	it("narrows to the typed host envelope via isHostJobOutputs", () => {
+		const out = ctx.jobOutputs(ci);
+		if (isHostJobOutputs(out)) expectTypeOf(out.byHost).toEqualTypeOf();
+	});
+	it("keeps a string-name ref on the loose union", () => {
+		expectTypeOf(ctx.jobOutputs({ name: "ci" })).toEqualTypeOf();
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=job-outputs.test-d.js.map

package/dist/job.d.ts

@@ -1,31 +1,93 @@
-import type { Job, JobOptions } from './types.js';
+import type { Job, JobOptions, StepInput, InferJobOutputsFromSteps, StepContextWithNeeds } from './types.js';
+import type { StepContext } from './context.js';
 /**
- * Create a job with an explicit name.
+ * Create a job with an explicit name; run shorthand with typed `ctx.needs`.
+ *
+ * When the job declares `needs: [jobRef, …]`, the `run:` function's `ctx.needs`
+ * is typed from the tuple — job references thread their inferred outputs, so
+ * `ctx.needs.<job>.result.<field>` is checked (string / `{ name }` entries stay
+ * loose). Outputs are inferred flat from the run function's return type.
+ */
+export declare function job<TName extends string, const TNeeds extends readonly unknown[], TRun extends (ctx: StepContextWithNeeds<TNeeds>) => Promise<any>>(name: TName, options: Omit<JobOptions, 'needs' | 'run' | 'steps'> & {
+    needs: TNeeds;
+    run: TRun;
+    steps?: undefined;
+}): Job<Awaited<ReturnType<TRun>>, TName>;
+/**
+ * Create a job with an explicit name; outputs inferred from the run shorthand.
+ *
+ * The `run:` shorthand infers a **flat** output shape from the run function's
+ * return type (`job.result.<field>`), matching the runtime's single-step
+ * flattening.
+ */
+export declare function job<TName extends string, TRun extends (ctx: StepContext) => Promise<any>>(name: TName, options: JobOptions & {
+    run: TRun;
+    steps?: undefined;
+}): Job<Awaited<ReturnType<TRun>>, TName>;
+/**
+ * Create a job with an explicit name; outputs inferred from the steps tuple.
+ *
+ * A `steps:` job infers a **nested** output shape keyed by step name
+ * (`job.result.<step>.<field>`) via {@link InferJobOutputsFromSteps} — name
+ * your steps to get typed cross-job reads (id-less steps contribute nothing).
  *
  * @example
  * const build = job('build', {
- *   runsOn: 'linux',
+ *   runsOn: 'kici:os:linux',
  *   steps: [checkout, install, compile],
  * });
+ */
+export declare function job<TName extends string, const TSteps extends readonly StepInput[]>(name: TName, options: JobOptions & {
+    steps: TSteps;
+    run?: undefined;
+}): Job<InferJobOutputsFromSteps<TSteps>, TName>;
+/**
+ * Create a job with an explicit name and an explicit output-type override.
+ *
+ * Pass the output shape as a type argument (`job<MyOutputs>('name', {...})`) for
+ * dynamically-shaped jobs the inference can't reproduce. With no type argument
+ * (and no `run` / `steps` to infer from) it defaults to the loose
+ * `Record<string, unknown>`, so a bare job keeps compiling.
  *
  * @example
- * // With rules and description
  * const build = job('build', {
- *   runsOn: 'linux',
+ *   runsOn: 'kici:os:linux',
  *   steps: [checkout, install, compile],
  *   rules: [rule('env: CI')],
  *   description: 'Build the project',
  * });
  */
-export declare function job(name: string, options: JobOptions): Job;
+export declare function job<TOutputs = Record<string, unknown>, TName extends string = string>(name: TName, options: JobOptions): Job<TOutputs, TName>;
+/**
+ * Create a job with auto-generated ID; run shorthand with typed `ctx.needs`.
+ */
+export declare function job<const TNeeds extends readonly unknown[], TRun extends (ctx: StepContextWithNeeds<TNeeds>) => Promise<any>>(options: Omit<JobOptions, 'needs' | 'run' | 'steps'> & {
+    needs: TNeeds;
+    run: TRun;
+    steps?: undefined;
+}): Job<Awaited<ReturnType<TRun>>>;
 /**
- * Create a job with auto-generated ID.
+ * Create a job with auto-generated ID; outputs inferred from the run shorthand.
+ */
+export declare function job<TRun extends (ctx: StepContext) => Promise<any>>(options: JobOptions & {
+    run: TRun;
+    steps?: undefined;
+}): Job<Awaited<ReturnType<TRun>>>;
+/**
+ * Create a job with auto-generated ID; outputs inferred from the steps tuple.
  *
  * @example
  * const build = job({
- *   runsOn: 'linux',
+ *   runsOn: 'kici:os:linux',
  *   steps: [checkout, install],
  * });
  */
-export declare function job(options: JobOptions): Job;
+export declare function job<const TSteps extends readonly StepInput[]>(options: JobOptions & {
+    steps: TSteps;
+    run?: undefined;
+}): Job<InferJobOutputsFromSteps<TSteps>>;
+/**
+ * Create a job with auto-generated ID and an explicit output-type override.
+ */
+export declare function job<TOutputs = Record<string, unknown>>(options: JobOptions): Job<TOutputs>;
 //# sourceMappingURL=job.d.ts.map

package/dist/job.js

@@ -1,5 +1,6 @@
 import "./rolldown-runtime-ClRpJifh.js";
 import { createJobOutputProxy } from "./outputs.js";
+import { isKnownCapability } from "@kici-dev/engine";
 import { randomUUID } from "node:crypto";
 //#region src/job.ts
 /** A typed preset is a `'mise'` string or a `{ mise }` object — neither carries `run`. */
@@ -21,6 +22,17 @@ function validateInit(init, jobName) {
 	});
 }
 /**
+* Validate a job's `sandbox` escape-hatch request. An unknown capability name
+* is a typo that would never match the operator allow-list, so it is rejected
+* at author time (security is still enforced deny-by-default at dispatch — this
+* is a correctness/UX guard). Capability form is normalized by the dispatch
+* resolver, so both `NET_ADMIN` and `CAP_NET_ADMIN` are accepted here.
+*/
+function validateSandbox(sandbox, jobName) {
+	if (sandbox === void 0) return;
+	for (const cap of sandbox.capabilities ?? []) if (!isKnownCapability(cap)) throw new Error(`job('${jobName}'): unknown Linux capability '${cap}' in sandbox.capabilities`);
+}
+/**
 * Implementation of job() factory.
 */
 function job(nameOrOptions, maybeOptions) {
@@ -32,6 +44,7 @@ function job(nameOrOptions, maybeOptions) {
 		steps = [options.run];
 	}
 	validateInit(options.init, name);
+	validateSandbox(options.sandbox, name);
 	const firstContext = options.contexts?.[0];
 	const concurrencyGroup = options.concurrencyGroup ?? (typeof firstContext === "string" ? firstContext : void 0);
 	if (options.context !== void 0 && options.contexts !== void 0) throw new Error(`job('${name}'): context and contexts are mutually exclusive — use one`);
@@ -57,6 +70,7 @@ function job(nameOrOptions, maybeOptions) {
 		exclude: options.exclude,
 		checkout: options.checkout,
 		container: options.container,
+		...options.sandbox !== void 0 && { sandbox: options.sandbox },
 		context: options.context,
 		contexts: options.contexts,
 		env: options.env,

package/dist/matrix/expand.d.ts

@@ -1,2 +1,2 @@
-export { expandSingleDimension, expandMultiDimension, expandMatrix, applyIncludeExclude, } from '@kici-dev/engine';
+export { expandMatrix, applyIncludeExclude } from '@kici-dev/engine';
 //# sourceMappingURL=expand.d.ts.map

package/dist/matrix/expand.js

@@ -1,3 +1,3 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { applyIncludeExclude, expandMatrix, expandMultiDimension, expandSingleDimension } from "@kici-dev/engine";
-export { applyIncludeExclude, expandMatrix, expandMultiDimension, expandSingleDimension };
+import { applyIncludeExclude, expandMatrix } from "@kici-dev/engine";
+export { applyIncludeExclude, expandMatrix };

package/dist/needs-context.d.ts

@@ -15,17 +15,24 @@ export interface UpstreamSnapshot {
     groups: Record<string, string[]>;
     statuses?: Record<string, ExecutionJobStatus>;
 }
+/**
+ * A single-job need entry: the upstream's outputs proxy plus its terminal
+ * status. `T` is the upstream's inferred output shape (defaults to the loose
+ * `Record<string, unknown>`); a typed `needs: [jobRef]` threads the reference's
+ * outputs here so `ctx.needs.<job>.result.<field>` is checked.
+ */
+export interface SingleNeedEntry<T = Record<string, unknown>> {
+    result: OutputProxy<T>;
+    status: ExecutionJobStatus;
+}
 /** One entry in the array exposed for a `dynamicGroup(...)` need. */
-export interface GroupNeedEntry {
+export interface GroupNeedEntry<T = Record<string, unknown>> {
     name: string;
-    result: OutputProxy<any>;
+    result: OutputProxy<T>;
     status: ExecutionJobStatus;
 }
 /** A single-job need exposes `{ result, status }`; a group need exposes an ordered array. */
-export type NeedEntry = {
-    result: OutputProxy<any>;
-    status: ExecutionJobStatus;
-} | GroupNeedEntry[];
+export type NeedEntry<T = Record<string, unknown>> = SingleNeedEntry<T> | GroupNeedEntry[];
 /** The resolved `ctx.needs` map keyed by job name or group name. */
 export type NeedsContext = Record<string, NeedEntry>;
 /**

package/dist/outputs.d.ts

@@ -1,4 +1,4 @@
-import type { OutputProxy } from './types.js';
+import type { OutputProxy, SourceLocation } from './types.js';
 /**
  * Shared mutable map that steps write their outputs to and proxies read from.
  * Keys are step/job names, values are the outputs records.
@@ -42,14 +42,29 @@ export declare function getJobOutputsMap(): OutputsMap;
  * Get the current step ref map.
  */
 export declare function getStepRefMap(): StepRefMap;
+/**
+ * Minimal shape the step output proxy needs from a step: a name that may be
+ * assigned after the proxy is created (id-less steps are named `step-N` when the
+ * job's steps are enumerated at execution start), plus the optional source
+ * location for a helpful error when the name is still unresolved.
+ */
+export interface StepNameRef {
+    readonly name: string;
+    readonly _sourceLocation?: SourceLocation;
+}
 /**
  * Create a Proxy over step outputs that resolves property access lazily
  * against the module-global step outputs map.
  *
- * @param stepName - The name of the step whose outputs to proxy
+ * The proxy reads `stepRef.name` at ACCESS time rather than capturing the name
+ * string at creation. Id-less steps have `name === ''` when the proxy is built;
+ * the runner assigns `step-N` onto the same step object before any run function
+ * executes, so `.result` resolves under the final name by the time it is used.
+ *
+ * @param stepRef - The step whose (possibly later-assigned) name identifies its outputs
  * @returns A Proxy that resolves property access at runtime
  */
-export declare function createStepOutputProxy<T>(stepName: string): OutputProxy<T>;
+export declare function createStepOutputProxy<T>(stepRef: StepNameRef): OutputProxy<T>;
 /**
  * Create a Proxy over job outputs that resolves property access lazily
  * against the module-global job outputs map.
@@ -60,7 +75,7 @@ export declare function createStepOutputProxy<T>(stepName: string): OutputProxy<
  * @param jobName - The name of the job whose outputs to proxy
  * @returns A Proxy that resolves property access at runtime
  */
-export declare function createJobOutputProxy(jobName: string): OutputProxy<any>;
+export declare function createJobOutputProxy<TOutputs = any>(jobName: string): OutputProxy<TOutputs>;
 /**
  * Output proxy bound to a specific outputs object (not the module-global map).
  *

package/dist/outputs.js

@@ -66,30 +66,44 @@ function getStepRefMap() {
 * Create a Proxy over step outputs that resolves property access lazily
 * against the module-global step outputs map.
 *
-* @param stepName - The name of the step whose outputs to proxy
+* The proxy reads `stepRef.name` at ACCESS time rather than capturing the name
+* string at creation. Id-less steps have `name === ''` when the proxy is built;
+* the runner assigns `step-N` onto the same step object before any run function
+* executes, so `.result` resolves under the final name by the time it is used.
+*
+* @param stepRef - The step whose (possibly later-assigned) name identifies its outputs
 * @returns A Proxy that resolves property access at runtime
 */
-function createStepOutputProxy(stepName) {
+function createStepOutputProxy(stepRef) {
+	const unresolvedError = () => {
+		const loc = stepRef._sourceLocation;
+		const at = loc ? ` (step defined at ${loc.file}:${loc.line})` : "";
+		return /* @__PURE__ */ new Error(`This step has no name yet; .result is only available inside another step's run function${at}. Name the step to reference its outputs before execution.`);
+	};
 	return new Proxy({}, {
 		get(_target, prop, receiver) {
 			if (typeof prop === "symbol") return Reflect.get(_target, prop, receiver);
 			if (WELL_KNOWN_STRING_PROPS.has(prop)) return Reflect.get(_target, prop, receiver);
-			const outputs = _stepOutputsMap.get(stepName);
-			if (!outputs) throw new Error(`Step '${stepName}' has not produced outputs yet`);
+			if (!stepRef.name) throw unresolvedError();
+			const outputs = _stepOutputsMap.get(stepRef.name);
+			if (!outputs) throw new Error(`Step '${stepRef.name}' has not produced outputs yet`);
 			return outputs[prop];
 		},
 		ownKeys() {
-			const outputs = _stepOutputsMap.get(stepName);
+			if (!stepRef.name) return [];
+			const outputs = _stepOutputsMap.get(stepRef.name);
 			if (!outputs) return [];
 			return Reflect.ownKeys(outputs);
 		},
 		has(_target, prop) {
-			const outputs = _stepOutputsMap.get(stepName);
+			if (!stepRef.name) return false;
+			const outputs = _stepOutputsMap.get(stepRef.name);
 			if (!outputs) return false;
 			return prop in outputs;
 		},
 		getOwnPropertyDescriptor(_target, prop) {
-			const outputs = _stepOutputsMap.get(stepName);
+			if (!stepRef.name) return void 0;
+			const outputs = _stepOutputsMap.get(stepRef.name);
 			if (!outputs) return void 0;
 			if (prop in outputs) return {
 				configurable: true,

package/dist/parallel.d.ts

@@ -32,7 +32,7 @@ export declare function isParallelGroup(x: unknown): x is ParallelGroup;
 /**
  * Flatten a job's `steps` into a flat list where each parallel group's children
  * are inlined in array order (the group wrapper is dropped). Used by single-
- * process consumers (the local executor and dry-run preview) that surface each
+ * process consumers (the test runner and dry-run preview) that surface each
  * child as its own step but do not run a concurrent scheduler; the concurrent
  * agent path expands groups into observable concurrent tasks instead.
  */

package/dist/parallel.js

@@ -21,7 +21,7 @@ function isParallelGroup(x) {
 /**
 * Flatten a job's `steps` into a flat list where each parallel group's children
 * are inlined in array order (the group wrapper is dropped). Used by single-
-* process consumers (the local executor and dry-run preview) that surface each
+* process consumers (the test runner and dry-run preview) that surface each
 * child as its own step but do not run a concurrent scheduler; the concurrent
 * agent path expands groups into observable concurrent tasks instead.
 */

package/dist/provenance-types.d.ts

@@ -33,9 +33,9 @@ export type AttestProvenanceResult = {
     bundleMediaType: string;
 } | {
     /**
-     * The Platform mint failed transiently, so only the identity token is
-     * deferred: the statement was frozen + signed at build time and is minted
-     * later (automatically on Platform recovery, or via
+     * The identity-token mint failed transiently, so only the identity token
+     * is deferred: the statement was frozen + signed at build time and the
+     * token is minted later (automatically when the mint recovers, or via
      * `kici-admin attestations retry`). The job still completes successfully.
      */
     deferred: true;

package/dist/rules/context.d.ts

@@ -0,0 +1,33 @@
+import type { ChangedFilesStatus } from '@kici-dev/engine';
+import type { EventPayload } from '../events/event-payloads.js';
+import type { FanoutPosition } from '../fanout-context.js';
+import type { RuleContext } from './types.js';
+/**
+ * Thrown when a rule reads `ctx.changedFiles` but the diff is not available
+ * (`changedFilesStatus !== 'fetched'`). `evaluateRules` re-throws this rather
+ * than folding it into a `passed=false` skip, so the job fails loudly instead
+ * of silently mis-evaluating a path-based gate.
+ */
+export declare class ChangedFilesUnavailableError extends Error {
+    readonly changedFilesStatus: ChangedFilesStatus;
+    readonly eventType?: string;
+    constructor(status: ChangedFilesStatus, eventType?: string);
+}
+/** Input for {@link createRuleContext}. */
+export interface CreateRuleContextInput {
+    event: EventPayload | Record<string, unknown>;
+    changedFiles?: string[];
+    /** Defaults to `'fetched'` — a caller that passes a real list needs no status. */
+    changedFilesStatus?: ChangedFilesStatus;
+    env?: Record<string, string | undefined>;
+    dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>;
+    fanout?: FanoutPosition;
+}
+/**
+ * Build a RuleContext. `changedFiles` is exposed as a getter: it returns the
+ * list when `changedFilesStatus === 'fetched'`, otherwise it throws
+ * `ChangedFilesUnavailableError`. This is the single construction site for a
+ * rule context across the agent, the compiler test-runner, and tests.
+ */
+export declare function createRuleContext(input: CreateRuleContextInput): RuleContext;
+//# sourceMappingURL=context.d.ts.map

package/dist/rules/context.js

@@ -0,0 +1,51 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { $ } from "zx";
+//#region src/rules/context.ts
+/**
+* Thrown when a rule reads `ctx.changedFiles` but the diff is not available
+* (`changedFilesStatus !== 'fetched'`). `evaluateRules` re-throws this rather
+* than folding it into a `passed=false` skip, so the job fails loudly instead
+* of silently mis-evaluating a path-based gate.
+*/
+var ChangedFilesUnavailableError = class extends Error {
+	changedFilesStatus;
+	eventType;
+	constructor(status, eventType) {
+		super(`ctx.changedFiles is not available (status: ${status}` + (eventType ? `, event: ${eventType}` : "") + "). Changed files are only defined for push / pull_request events with a computable diff. Guard with ctx.changedFilesStatus before accessing, e.g. `if (ctx.changedFilesStatus !== 'fetched') return true`.");
+		this.name = "ChangedFilesUnavailableError";
+		this.changedFilesStatus = status;
+		this.eventType = eventType;
+	}
+};
+/**
+* Build a RuleContext. `changedFiles` is exposed as a getter: it returns the
+* list when `changedFilesStatus === 'fetched'`, otherwise it throws
+* `ChangedFilesUnavailableError`. This is the single construction site for a
+* rule context across the agent, the compiler test-runner, and tests.
+*/
+function createRuleContext(input) {
+	const status = input.changedFilesStatus ?? "fetched";
+	const files = input.changedFiles ?? [];
+	const eventType = typeof input.event.type === "string" ? input.event.type : void 0;
+	const base = {
+		event: input.event,
+		changedFilesStatus: status,
+		env: input.env ?? {},
+		dispatchInputs: input.dispatchInputs ?? {},
+		...input.fanout && { fanout: input.fanout },
+		$
+	};
+	Object.defineProperty(base, "changedFiles", {
+		enumerable: true,
+		configurable: true,
+		get() {
+			if (status !== "fetched") throw new ChangedFilesUnavailableError(status, eventType);
+			return files;
+		}
+	});
+	return base;
+}
+//#endregion
+export { ChangedFilesUnavailableError, createRuleContext };
+
+//# sourceMappingURL=context.js.map

package/dist/rules/evaluator.d.ts

@@ -6,6 +6,16 @@ import type { Rule, RuleContext, RuleResult } from './types.js';
 export interface RuleEvaluationResult {
     allPassed: boolean;
     results: RuleResult[];
+    /**
+     * Set iff a rule's check() threw — an evaluation failure, NOT a clean
+     * `return false`. Consumers fail-hard on this (surface the error + fail the
+     * job/step) instead of treating a crashed gate as a silent skip, which would
+     * be a false green. A clean false leaves this undefined.
+     */
+    evaluationError?: {
+        label: string;
+        message: string;
+    };
 }
 /**
  * Evaluate rules sequentially with fail-fast behavior.

package/dist/rules/evaluator.js

@@ -1,4 +1,5 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { ChangedFilesUnavailableError } from "./context.js";
 import { toErrorMessage } from "@kici-dev/core";
 //#region src/rules/evaluator.ts
 /**
@@ -17,6 +18,7 @@ import { toErrorMessage } from "@kici-dev/core";
 async function evaluateRules(rules, context, _label, onRuleResult) {
 	const results = [];
 	let allPassed = true;
+	let evaluationError;
 	for (const rule of rules) {
 		const startTime = Date.now();
 		let passed = false;
@@ -24,8 +26,13 @@ async function evaluateRules(rules, context, _label, onRuleResult) {
 		try {
 			passed = await rule.check(context);
 		} catch (e) {
+			if (e instanceof ChangedFilesUnavailableError) throw e;
 			passed = false;
 			error = toErrorMessage(e);
+			evaluationError = {
+				label: rule.label,
+				message: error
+			};
 		}
 		const durationMs = Date.now() - startTime;
 		const result = {
@@ -43,7 +50,8 @@ async function evaluateRules(rules, context, _label, onRuleResult) {
 	}
 	return {
 		allPassed,
-		results
+		results,
+		evaluationError
 	};
 }
 //#endregion

package/dist/rules/index.d.ts

@@ -1,5 +1,7 @@
 export { rule, skip, onlyOnFirstHost, onlyOnLastHost, onlyOnFanoutIndex } from './rule.js';
 export { evaluateRules, type RuleEvaluationResult } from './evaluator.js';
+export { createRuleContext, ChangedFilesUnavailableError } from './context.js';
+export type { CreateRuleContextInput } from './context.js';
 export type { Rule, RuleCheckFn, RuleContext, RuleResult, EventPayload } from './types.js';
 export { isEventType } from '../events/event-payloads.js';
 export type { EventBase, PullRequestEventPayload, PushEventPayload, TagEventPayload, CommentEventPayload, ReviewEventPayload, ReviewCommentEventPayload, ReleaseEventPayload, DispatchEventPayload, CreateEventPayload, DeleteEventPayload, StatusEventPayload, WorkflowRunEventPayload, ForkEventPayload, StarEventPayload, WatchEventPayload, WebhookEventPayload, KiciEventPayload, WorkflowCompleteEventPayload, JobCompleteEventPayload, GenericWebhookEventPayload, ScheduleEventPayload, LifecycleEventPayload, GitHubRepository, GitHubUser, GitHubPullRequest, GitHubCommit, GitHubComment, GitHubReview, GitHubRelease, } from '../events/event-payloads.js';

package/dist/rules/index.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip } from "./rule.js";
+import { ChangedFilesUnavailableError, createRuleContext } from "./context.js";
 import { evaluateRules } from "./evaluator.js";
 import { isEventType } from "../events/event-payloads.js";
-export { evaluateRules, isEventType, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip };
+export { ChangedFilesUnavailableError, createRuleContext, evaluateRules, isEventType, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip };