@kici-dev/engine 0.1.26 → 0.2.0

package/dist/trigger/matcher.d.ts

@@ -1,5 +1,5 @@
-import type { LockWorkflow, LockBranchPattern, SimulatedEvent } from './types.js';
-import { type WorkflowDecision } from './decision-trace.js';
+import type { LockTrigger, LockWorkflow, LockBranchPattern, SimulatedEvent, ChangedFilesStatus } from './types.js';
+import { type TraceEntry, type WorkflowDecision } from './decision-trace.js';
 /**
  * Match a branch pattern against a branch name.
  */
@@ -9,7 +9,7 @@ export declare function matchBranchPattern(pattern: LockBranchPattern, branch: s
  * Patterns prefixed with ! are exclusions. Remaining patterns are inclusions.
  * An all-negation array has implicit match-all semantics for non-excluded files.
  */
-export declare function matchPathPatterns(paths: readonly string[], changedFiles: string[]): boolean;
+export declare function matchPathPatterns(paths: readonly string[], changedFiles: string[], status?: ChangedFilesStatus): boolean;
 /**
  * Match repo patterns against a source repository identifier.
  * Patterns with ! prefix in the pattern string are exclusions.
@@ -17,6 +17,10 @@ export declare function matchPathPatterns(paths: readonly string[], changedFiles
  * Empty array = no filtering (matches all repos).
  */
 export declare function matchRepoPatterns(repos: readonly LockBranchPattern[], sourceRepo: string): boolean;
+/**
+ * Match a trigger against a simulated event.
+ */
+export declare function matchTrigger(trigger: LockTrigger, event: SimulatedEvent, traces: TraceEntry[]): boolean;
 /**
  * Match all triggers for a workflow against an event.
  * Returns WorkflowDecision with full trace.

package/dist/trigger/matcher.js

@@ -1,7 +1,7 @@
 import "../rolldown-runtime-ClRpJifh.js";
 import { createTraceEntry, createWorkflowDecision } from "./decision-trace.js";
+import { getCompiledRegex, getGlobMatcher } from "./compiled-matchers.js";
 import { matchJsonPath, matchJsonPathNot } from "./jsonpath-matcher.js";
-import picomatch from "picomatch";
 //#region src/trigger/matcher.ts
 /**
 * Trigger matching engine for evaluating workflow triggers against webhook events.
@@ -34,8 +34,8 @@ function splitBranchPatterns(patterns) {
 * Match a branch pattern against a branch name.
 */
 function matchBranchPattern(pattern, branch) {
-	if (pattern.type === "glob") return picomatch.isMatch(branch, pattern.pattern);
-	else return new RegExp(pattern.pattern, pattern.flags).test(branch);
+	if (pattern.type === "glob") return getGlobMatcher(pattern.pattern)(branch);
+	else return getCompiledRegex(pattern.pattern, pattern.flags).test(branch);
 }
 /**
 * Match any of the branch patterns.
@@ -50,17 +50,18 @@ function matchAnyBranch(patterns, branch) {
 * Patterns prefixed with ! are exclusions. Remaining patterns are inclusions.
 * An all-negation array has implicit match-all semantics for non-excluded files.
 */
-function matchPathPatterns(paths, changedFiles) {
+function matchPathPatterns(paths, changedFiles, status) {
 	if (paths.length === 0) return true;
+	if (status === "unavailable") return true;
 	if (changedFiles.length === 0) return false;
 	const { include, exclude } = splitStringPatterns(paths);
 	let relevantFiles = changedFiles;
 	if (exclude.length > 0) {
-		relevantFiles = changedFiles.filter((file) => !exclude.some((pattern) => picomatch.isMatch(file, pattern)));
+		relevantFiles = changedFiles.filter((file) => !exclude.some((pattern) => getGlobMatcher(pattern)(file)));
 		if (relevantFiles.length === 0) return false;
 	}
 	if (include.length === 0) return true;
-	return relevantFiles.some((file) => include.some((pattern) => picomatch.isMatch(file, pattern)));
+	return relevantFiles.some((file) => include.some((pattern) => getGlobMatcher(pattern)(file)));
 }
 /**
 * Match repo patterns against a source repository identifier.
@@ -127,8 +128,8 @@ function matchPrTrigger(trigger, event, traces) {
 	if (trigger.paths.length > 0) {
 		const changedFiles = event.changedFiles ?? [];
 		const { include, exclude } = splitStringPatterns(trigger.paths);
-		const matches = matchPathPatterns(trigger.paths, changedFiles);
-		traces.push(createTraceEntry("paths", `include: [${include.join(", ")}] exclude: [${exclude.join(", ")}]`, `[${changedFiles.join(", ")}]`, matches));
+		const matches = matchPathPatterns(trigger.paths, changedFiles, event.changedFilesStatus);
+		traces.push(createTraceEntry("paths", `include: [${include.join(", ")}] exclude: [${exclude.join(", ")}]`, event.changedFilesStatus === "unavailable" ? "[unavailable — matched conservatively]" : `[${changedFiles.join(", ")}]`, matches));
 		if (!matches) return false;
 	}
 	if (!evaluateRepoFilter(trigger, event, traces)) return false;
@@ -151,8 +152,8 @@ function matchPushTrigger(trigger, event, traces) {
 	if (trigger.paths.length > 0) {
 		const changedFiles = event.changedFiles ?? [];
 		const { include, exclude } = splitStringPatterns(trigger.paths);
-		const matches = matchPathPatterns(trigger.paths, changedFiles);
-		traces.push(createTraceEntry("paths", `include: [${include.join(", ")}] exclude: [${exclude.join(", ")}]`, `[${changedFiles.join(", ")}]`, matches));
+		const matches = matchPathPatterns(trigger.paths, changedFiles, event.changedFilesStatus);
+		traces.push(createTraceEntry("paths", `include: [${include.join(", ")}] exclude: [${exclude.join(", ")}]`, event.changedFilesStatus === "unavailable" ? "[unavailable — matched conservatively]" : `[${changedFiles.join(", ")}]`, matches));
 		if (!matches) return false;
 	}
 	if (!evaluateRepoFilter(trigger, event, traces)) return false;
@@ -208,11 +209,11 @@ function matchCommentTrigger(trigger, event, traces) {
 	if (trigger.bodyMatch) {
 		const body = event.payload.comment?.body ?? "";
 		if (trigger.bodyMatch.type === "glob") {
-			const matches = picomatch.isMatch(body, trigger.bodyMatch.pattern);
+			const matches = getGlobMatcher(trigger.bodyMatch.pattern)(body);
 			traces.push(createTraceEntry("bodyMatch (glob)", trigger.bodyMatch.pattern, body, matches));
 			if (!matches) return false;
 		} else {
-			const matches = new RegExp(trigger.bodyMatch.pattern, trigger.bodyMatch.flags).test(body);
+			const matches = getCompiledRegex(trigger.bodyMatch.pattern, trigger.bodyMatch.flags).test(body);
 			traces.push(createTraceEntry("bodyMatch (regex)", trigger.bodyMatch.pattern, body, matches));
 			if (!matches) return false;
 		}
@@ -354,7 +355,7 @@ function matchDeleteTrigger(trigger, event, traces) {
 }
 /**
 * Match a status trigger against a simulated event.
-* Checks context via picomatch and state filter.
+* Checks context via glob matching and state filter.
 */
 function matchStatusTrigger(trigger, event, traces) {
 	if (event.type !== "status") {
@@ -364,7 +365,7 @@ function matchStatusTrigger(trigger, event, traces) {
 	traces.push(createTraceEntry("event type", "status", event.type, true));
 	if (trigger.contexts.length > 0) {
 		const context = event.payload.context ?? "";
-		const matches = trigger.contexts.some((pattern) => picomatch.isMatch(context, pattern));
+		const matches = trigger.contexts.some((pattern) => getGlobMatcher(pattern)(context));
 		traces.push(createTraceEntry("context", trigger.contexts.join("|"), context, matches));
 		if (!matches) return false;
 	}
@@ -540,6 +541,42 @@ function matchWorkflowCompleteTrigger(trigger, event, traces) {
 	return true;
 }
 /**
+* Match a workflows_failed_batch trigger against a simulated event.
+*
+* The trigger participates in two phases:
+*  - A failed `workflow_complete` event is an accumulation input — it matches
+*    (respecting optional name/source filters) so the orchestrator buffers the
+*    run into the batch window instead of dispatching now.
+*  - A synthetic `workflows_failed_batch` event is the dispatch trigger — the
+*    orchestrator emits it once per window and it matches to dispatch the
+*    subscribing workflow a single time.
+*/
+function matchWorkflowsFailedBatchTrigger(trigger, event, traces) {
+	if (event.type === "workflow_complete") {
+		const status = event.payload.status ?? "";
+		const isFailed = status === "failed";
+		traces.push(createTraceEntry("status", "failed", status, isFailed));
+		if (!isFailed) return false;
+	} else if (event.type !== "workflows_failed_batch") {
+		traces.push(createTraceEntry("event type", "workflow_complete|workflows_failed_batch", event.type, false));
+		return false;
+	}
+	traces.push(createTraceEntry("event type", "workflows_failed_batch", event.type, true));
+	if (trigger.name) {
+		const workflowName = event.payload.workflowName ?? "";
+		const matches = workflowName === trigger.name;
+		traces.push(createTraceEntry("workflow name", trigger.name, workflowName, matches));
+		if (!matches) return false;
+	}
+	if (trigger.source) {
+		const sourceRepo = event.payload.sourceRepo ?? "";
+		const matches = sourceRepo === trigger.source;
+		traces.push(createTraceEntry("source", trigger.source, sourceRepo, matches));
+		if (!matches) return false;
+	}
+	return true;
+}
+/**
 * Match a job_complete trigger against a simulated event.
 * Checks workflow name, job name, status array, and source filter.
 */
@@ -669,6 +706,7 @@ function matchTrigger(trigger, event, traces) {
 		case "webhook": return matchWebhookTrigger(trigger, event, traces);
 		case "kici_event": return matchKiciEventTrigger(trigger, event, traces);
 		case "workflow_complete": return matchWorkflowCompleteTrigger(trigger, event, traces);
+		case "workflows_failed_batch": return matchWorkflowsFailedBatchTrigger(trigger, event, traces);
 		case "job_complete": return matchJobCompleteTrigger(trigger, event, traces);
 		case "generic_webhook": return matchGenericWebhookTrigger(trigger, event, traces);
 		case "schedule": return matchScheduleTrigger(trigger, event, traces);
@@ -699,6 +737,6 @@ function matchAllWorkflows(workflows, event) {
 	return workflows.map((w) => matchWorkflowTriggers(w, event));
 }
 //#endregion
-export { matchAllWorkflows, matchBranchPattern, matchPathPatterns, matchRepoPatterns, matchWorkflowTriggers };
+export { matchAllWorkflows, matchBranchPattern, matchPathPatterns, matchRepoPatterns, matchTrigger, matchWorkflowTriggers };
 
 //# sourceMappingURL=matcher.js.map

package/dist/trigger/schedule-key.d.ts

@@ -0,0 +1,14 @@
+/**
+ * Stable identity of a schedule trigger for last-fired bookkeeping.
+ *
+ * Two schedule triggers are "the same schedule" iff they share a cron
+ * expression AND timezone — they fire at the same instants and dispatch
+ * identically (the trigger matcher keys on cronExpression). The orchestrator's
+ * `cron_last_fired` table is keyed by (registration_id, this key) so every
+ * distinct schedule of a workflow is fired and tracked independently.
+ *
+ * The format is intentionally trivial (newline-joined) so migration SQL can
+ * reproduce it byte-for-byte: `cronExpression || E'\n' || timezone`.
+ */
+export declare function scheduleTriggerKey(cronExpression: string, timezone: string): string;
+//# sourceMappingURL=schedule-key.d.ts.map

package/dist/trigger/schedule-key.js

@@ -0,0 +1,21 @@
+import "../rolldown-runtime-ClRpJifh.js";
+//#region src/trigger/schedule-key.ts
+/**
+* Stable identity of a schedule trigger for last-fired bookkeeping.
+*
+* Two schedule triggers are "the same schedule" iff they share a cron
+* expression AND timezone — they fire at the same instants and dispatch
+* identically (the trigger matcher keys on cronExpression). The orchestrator's
+* `cron_last_fired` table is keyed by (registration_id, this key) so every
+* distinct schedule of a workflow is fired and tracked independently.
+*
+* The format is intentionally trivial (newline-joined) so migration SQL can
+* reproduce it byte-for-byte: `cronExpression || E'\n' || timezone`.
+*/
+function scheduleTriggerKey(cronExpression, timezone) {
+	return `${cronExpression}\n${timezone}`;
+}
+//#endregion
+export { scheduleTriggerKey };
+
+//# sourceMappingURL=schedule-key.js.map

package/dist/trigger/trigger-event-type.d.ts

@@ -6,7 +6,7 @@
  * compile-time failures in any exhaustive Record<TriggerEventType, ...>
  * (e.g., the dashboard icon map).
  */
-export declare const TRIGGER_EVENT_TYPES: readonly ["pull_request", "push", "tag", "comment", "review", "review_comment", "release", "dispatch", "create", "delete", "status", "workflow_run", "fork", "star", "watch", "webhook", "kici_event", "workflow_complete", "job_complete", "generic_webhook", "schedule", "lifecycle", "rerun", "manual_schedule"];
+export declare const TRIGGER_EVENT_TYPES: readonly ['pull_request', 'push', 'tag', 'comment', 'review', 'review_comment', 'release', 'dispatch', 'create', 'delete', 'status', 'workflow_run', 'fork', 'star', 'watch', 'webhook', 'kici_event', 'workflow_complete', 'workflows_failed_batch', 'job_complete', 'generic_webhook', 'schedule', 'lifecycle', 'rerun', 'manual_schedule'];
 export type TriggerEventType = (typeof TRIGGER_EVENT_TYPES)[number];
 export declare const TRIGGER_EVENT_META: Record<TriggerEventType, {
     label: string;

package/dist/trigger/trigger-event-type.js

@@ -27,6 +27,7 @@ const TRIGGER_EVENT_TYPES = [
 	"webhook",
 	"kici_event",
 	"workflow_complete",
+	"workflows_failed_batch",
 	"job_complete",
 	"generic_webhook",
 	"schedule",
@@ -53,6 +54,7 @@ const TRIGGER_EVENT_META = {
 	webhook: { label: "Webhook" },
 	kici_event: { label: "KiCI event" },
 	workflow_complete: { label: "Workflow complete" },
+	workflows_failed_batch: { label: "Workflows failed batch" },
 	job_complete: { label: "Job complete" },
 	generic_webhook: { label: "Generic webhook" },
 	schedule: { label: "Schedule" },

package/dist/trigger/types.d.ts

@@ -1,25 +1,34 @@
 /**
  * Lock file types for the trigger matching engine.
  * Single source of truth -- replaces local copies in @kici-dev/compiler and @kici-dev/orchestrator.
- * Schema version 4: adds 4 internal event routing trigger types (kici_event, workflow_complete,
+ *
+ * Bump-history convention: every entry is annotated `additive` (older readers
+ * tolerate the new lock because unknown fields are ignored) or `BREAKING` (an
+ * older reader would mis-parse the lock). Every `BREAKING` bump moves
+ * `BREAKING_FLOOR` (below) to that version in the SAME commit.
+ *
+ * Schema version 4 (additive): adds 4 internal event routing trigger types (kici_event, workflow_complete,
  * job_complete, generic_webhook).
- * Schema version 6: replaces job-level contexts with environment/env/concurrencyGroup.
- * Schema version 8: adds runsOn polymorphic type (string | string[] | selector) and excludeLabels.
- * Schema version 9: adds repos/notRepos repo pattern fields to git-event triggers for global workflow matching.
- * Schema version 10: removes notRepos/notPaths fields, negative patterns use ! prefix in repos/paths arrays.
- * Schema version 11: adds LockInlineValue type for pure function inline evaluation.
- * Schema version 14: adds declarative cache specs to LockJob and LockStep.
- * Schema version 15: adds per-job init config(s) to LockJob.
- * Schema version 16: adds normalized approval config to LockWorkflow/LockJob/LockStep.
- * Schema version 17: widens LockJob.init to typed presets ('mise' / { mise }) and 'auto' detection.
- * Schema version 18: adds LockJob.runsOnAll host fan-out predicate + onUnreachable policy.
- * Schema version 19: adds LockJob.maxParallel/failFast fan-out concurrency (rolling waves).
- * Schema version 20: runsOn/runsOnAll/excludeLabels carry LabelMatcher (exact|regex) for glob+regex selectors.
- * Schema version 23: adds LockDispatchTrigger.inputs (typed dispatch inputs descriptors).
- * Schema version 24: adds LockJob.runsOnPick (deterministic single-host selection).
- * Schema version 25: adds LockStep.retry (step retry policy data subset; retryIf is execution-only).
- * Schema version 26: adds LockJob.includeUninitialized (runsOnAll fans out to declared-but-un-agented hosts, bringing up a temporary init-runner per fresh box).
- * Schema version 27: adds LockScheduleTrigger.inputs (defaults-only schedule dispatch inputs).
+ * Schema version 6 (BREAKING): replaces job-level contexts with environment/env/concurrencyGroup.
+ * Schema version 8 (additive): adds runsOn polymorphic type (string | string[] | selector) and excludeLabels.
+ * Schema version 9 (additive): adds repos/notRepos repo pattern fields to git-event triggers for global workflow matching.
+ * Schema version 10 (BREAKING): removes notRepos/notPaths fields, negative patterns use ! prefix in repos/paths arrays.
+ * Schema version 11 (additive): adds LockInlineValue type for pure function inline evaluation.
+ * Schema version 14 (additive): adds declarative cache specs to LockJob and LockStep.
+ * Schema version 15 (additive): adds per-job init config(s) to LockJob.
+ * Schema version 16 (additive): adds normalized approval config to LockWorkflow/LockJob/LockStep.
+ * Schema version 17 (additive): widens LockJob.init to typed presets ('mise' / { mise }) and 'auto' detection.
+ * Schema version 18 (additive): adds LockJob.runsOnAll host fan-out predicate + onUnreachable policy.
+ * Schema version 19 (additive): adds LockJob.maxParallel/failFast fan-out concurrency (rolling waves).
+ * Schema version 20 (BREAKING): runsOn/runsOnAll/excludeLabels carry LabelMatcher (exact|regex) for glob+regex selectors.
+ * Schema version 23 (additive): adds LockDispatchTrigger.inputs (typed dispatch inputs descriptors).
+ * Schema version 24 (additive): adds LockJob.runsOnPick (deterministic single-host selection).
+ * Schema version 25 (additive): adds LockStep.retry (step retry policy data subset; retryIf is execution-only).
+ * Schema version 26 (additive): adds LockJob.includeUninitialized (runsOnAll fans out to declared-but-un-agented hosts, bringing up a temporary init-runner per fresh box).
+ * Schema version 27 (additive): adds LockScheduleTrigger.inputs (defaults-only schedule dispatch inputs).
+ * Schema version 30 (BREAKING): renames job-level `environments` to `contexts`.
+ * Schema version 31 (additive): adds the workflows_failed_batch lock trigger.
+ * Schema version 32 (additive): adds LockJob.sandbox (per-job escape-hatch request).
  */
 import { z } from 'zod';
 import type { ProviderType } from '../provider/types.js';
@@ -27,8 +36,28 @@ import type { ApproverClause } from '../approval/types.js';
 import type { InputsDescriptorMap } from '../inputs/descriptor.js';
 import { LabelMatcher } from '../labels-match.js';
 import { ExecutionJobStatus } from '../protocol/messages/execution-status.js';
-/** Schema version - increment on breaking changes */
-export declare const SCHEMA_VERSION: 29;
+/**
+ * Schema version the compiler emits into every lock file. Incremented on ANY
+ * schema change (additive or breaking); the bump-history comment above records
+ * which. See `BREAKING_FLOOR` for the compatibility-window semantics.
+ */
+export declare const SCHEMA_VERSION: 32;
+/**
+ * Oldest lock schema version this codebase can still read correctly — the lower
+ * bound of the acceptance window.
+ *
+ * A lock at `schemaVersion >= BREAKING_FLOOR` parses correctly here even if it
+ * is newer than `SCHEMA_VERSION` (additive bumps add fields this reader ignores).
+ * A lock below the floor was produced by an SDK whose breaking change this
+ * reader predates and must be rejected (it would mis-parse silently otherwise).
+ *
+ * Bump rule: move this to the current `SCHEMA_VERSION` ONLY in the commit that
+ * lands a `BREAKING` schema change (see the bump-history convention above). It
+ * currently sits at 30 because v30 (`environments`→`contexts`) was the most
+ * recent breaking bump; v31 and v32 were additive, so a v30 lock still reads
+ * correctly.
+ */
+export declare const BREAKING_FLOOR: 30;
 /**
  * Normalized approval config carried in the lock file. Produced by the compiler
  * from an SDK `approval` at any of the three levels; consumed by the
@@ -247,6 +276,21 @@ export interface LockWorkflowCompleteTrigger {
     readonly status?: readonly string[];
     readonly source?: string;
 }
+/**
+ * Workflows-failed-batch trigger in lock file.
+ *
+ * Accumulates failed workflow completions over `accumulateFor` ms and fires the
+ * subscribing workflow once per window with the batched run list. The matcher
+ * treats a failed `workflow_complete` event as an accumulation input and a
+ * synthetic `workflows_failed_batch` event as the dispatch trigger.
+ */
+export interface LockWorkflowsFailedBatchTrigger {
+    readonly _type: 'workflows_failed_batch';
+    /** Accumulation window in milliseconds; the window opens on the first failure. */
+    readonly accumulateFor: number;
+    readonly name?: string;
+    readonly source?: string;
+}
 /**
  * Job completion trigger in lock file.
  * Matches when a specific job within a workflow finishes execution.
@@ -307,7 +351,7 @@ export interface LockLifecycleTrigger {
     readonly description?: string;
 }
 /** Union of all trigger types */
-export type LockTrigger = LockPrTrigger | LockPushTrigger | LockTagTrigger | LockCommentTrigger | LockReviewTrigger | LockReviewCommentTrigger | LockReleaseTrigger | LockDispatchTrigger | LockCreateTrigger | LockDeleteTrigger | LockStatusTrigger | LockWorkflowRunTrigger | LockForkTrigger | LockStarTrigger | LockWatchTrigger | LockWebhookTrigger | LockKiciEventTrigger | LockWorkflowCompleteTrigger | LockJobCompleteTrigger | LockGenericWebhookTrigger | LockScheduleTrigger | LockLifecycleTrigger;
+export type LockTrigger = LockPrTrigger | LockPushTrigger | LockTagTrigger | LockCommentTrigger | LockReviewTrigger | LockReviewCommentTrigger | LockReleaseTrigger | LockDispatchTrigger | LockCreateTrigger | LockDeleteTrigger | LockStatusTrigger | LockWorkflowRunTrigger | LockForkTrigger | LockStarTrigger | LockWatchTrigger | LockWebhookTrigger | LockKiciEventTrigger | LockWorkflowCompleteTrigger | LockWorkflowsFailedBatchTrigger | LockJobCompleteTrigger | LockGenericWebhookTrigger | LockScheduleTrigger | LockLifecycleTrigger;
 /**
  * Matrix configuration in lock file.
  * Static matrices are expanded at orchestrator, dynamic at agent runtime.
@@ -402,9 +446,9 @@ export declare function isLockInlineValue(value: unknown): value is LockInlineVa
  */
 export declare const NeedsWhen: z.ZodEnum<{
     always: "always";
-    "on-success": "on-success";
-    "on-skip": "on-skip";
     "on-failure": "on-failure";
+    "on-skip": "on-skip";
+    "on-success": "on-success";
 }>;
 export type NeedsWhen = z.infer<typeof NeedsWhen>;
 /**
@@ -414,23 +458,29 @@ export type NeedsWhen = z.infer<typeof NeedsWhen>;
  * gating stays a pure status-set membership test.
  */
 export declare const NeedsRunOn: z.ZodArray<z.ZodEnum<{
-    skipped: "skipped";
-    success: "success";
-    pending: "pending";
-    running: "running";
-    failed: "failed";
     cancelled: "cancelled";
     cancelling: "cancelling";
+    drift_dropped: "drift_dropped";
+    failed: "failed";
+    pending: "pending";
     queued: "queued";
     recovering: "recovering";
+    running: "running";
+    skipped: "skipped";
+    success: "success";
     timed_out_stale: "timed_out_stale";
-    drift_dropped: "drift_dropped";
+    unroutable: "unroutable";
 }>>;
 export type NeedsRunOn = z.infer<typeof NeedsRunOn>;
 /**
  * Resolve the author-facing `when` (keyword sugar | raw status-set | unset) to
  * the normalized status-set. An unset `when` defaults to success-only — the
  * downstream runs only when the upstream succeeded.
+ *
+ * Always a fresh array. The keyword arm used to hand back the shared
+ * `WHEN_TO_RUN_ON` entry itself, so every lock-file edge compiled from the same
+ * keyword aliased one array and any caller that sorted or mutated its result
+ * silently reordered the keyword's expansion for every other edge.
  */
 export declare function resolveWhenToRunOn(when: NeedsWhen | ExecutionJobStatus[] | undefined): ExecutionJobStatus[];
 /**
@@ -440,17 +490,18 @@ export declare function resolveWhenToRunOn(when: NeedsWhen | ExecutionJobStatus[
 export declare const NeedsEntrySchema: z.ZodObject<{
     name: z.ZodString;
     runOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-        skipped: "skipped";
-        success: "success";
-        pending: "pending";
-        running: "running";
-        failed: "failed";
         cancelled: "cancelled";
         cancelling: "cancelling";
+        drift_dropped: "drift_dropped";
+        failed: "failed";
+        pending: "pending";
         queued: "queued";
         recovering: "recovering";
+        running: "running";
+        skipped: "skipped";
+        success: "success";
         timed_out_stale: "timed_out_stale";
-        drift_dropped: "drift_dropped";
+        unroutable: "unroutable";
     }>>>;
 }, z.core.$strip>;
 export type NeedsEntry = z.infer<typeof NeedsEntrySchema>;
@@ -461,17 +512,18 @@ export type NeedsEntry = z.infer<typeof NeedsEntrySchema>;
 export declare const NeedsGroupEntrySchema: z.ZodObject<{
     group: z.ZodString;
     runOn: z.ZodDefault<z.ZodArray<z.ZodEnum<{
-        skipped: "skipped";
-        success: "success";
-        pending: "pending";
-        running: "running";
-        failed: "failed";
         cancelled: "cancelled";
         cancelling: "cancelling";
+        drift_dropped: "drift_dropped";
+        failed: "failed";
+        pending: "pending";
         queued: "queued";
         recovering: "recovering";
+        running: "running";
+        skipped: "skipped";
+        success: "success";
         timed_out_stale: "timed_out_stale";
-        drift_dropped: "drift_dropped";
+        unroutable: "unroutable";
     }>>>;
 }, z.core.$strip>;
 export type NeedsGroupEntry = z.infer<typeof NeedsGroupEntrySchema>;
@@ -506,9 +558,9 @@ export type RunsOnAllInput = string | RegExp | readonly (string | RegExp)[] | {
  * never return), independent of this policy.
  */
 export declare const OnUnreachableMode: z.ZodEnum<{
+    fail: "fail";
     hold: "hold";
     skip: "skip";
-    fail: "fail";
 }>;
 export type OnUnreachableMode = z.infer<typeof OnUnreachableMode>;
 /**
@@ -523,6 +575,26 @@ export declare const RunsOnPick: z.ZodEnum<{
     deterministic: "deterministic";
 }>;
 export type RunsOnPick = z.infer<typeof RunsOnPick>;
+/** Container network posture: 'default' (bridge), 'none' (loopback-only), 'host' (host netns; gated). */
+export declare const SANDBOX_NETWORK_MODES: readonly ['default', 'none', 'host'];
+export type SandboxNetworkMode = (typeof SANDBOX_NETWORK_MODES)[number];
+/**
+ * The dispatch-resolved, allow-listed per-job sandbox escape hatch. Produced
+ * orchestrator-side at dispatch (the agent never resolves it) and applied
+ * additively over the hardened container baseline by the agent. The lock carries
+ * the workflow-declared request (`LockJob.sandbox`); this is the resolved grant
+ * the orchestrator authorized against the operator's `org_settings` allow-list.
+ */
+export interface ResolvedSandboxGrant {
+    /** Extra Linux capabilities added back over CapDrop:['ALL'] (bare form, e.g. 'NET_ADMIN'). */
+    capabilities?: string[];
+    /** Network override; when set it wins over the config network mode. */
+    network?: SandboxNetworkMode;
+    /** Force a read-only rootfs (operator-config path only in Phase 2). */
+    readonlyRootfs?: boolean;
+    /** Run the container as this user (operator-config path only in Phase 2). */
+    user?: string;
+}
 export interface LockJob {
     readonly _type: 'static';
     readonly name: string;
@@ -568,11 +640,11 @@ export interface LockJob {
     readonly rules?: readonly LockRule[];
     readonly description?: string;
     /**
-     * Deployment environments in merge order. Each entry is a static name or inline
+     * Bound contexts in merge order. Each entry is a static name or inline
      * expression (pure function); `dynamic` is set when it is a function resolved at
      * two-phase eval. Later entries override earlier ones on name collisions.
      */
-    readonly environments?: ReadonlyArray<{
+    readonly contexts?: ReadonlyArray<{
         value: string | LockInlineValue;
         dynamic: boolean;
     }>;
@@ -592,6 +664,29 @@ export interface LockJob {
      * (`requests`) and kernel-side enforcement (`limits`) on the spawned agent.
      */
     readonly resources?: import('../scaler/resource-types.js').ResourceRequest;
+    /**
+     * Container image selecting the container execution backend on the agent. A
+     * bare image string or an object with `image` + optional `env`. When set, the
+     * agent's `determineExecutionMode` routes the job to the container sandbox
+     * (top priority), so the orchestrator threads it through dispatch as
+     * `jobConfig.container`. (Shape mirrors the SDK `string | ContainerConfig`;
+     * the engine cannot import the SDK, so it is inlined here.)
+     */
+    readonly container?: string | {
+        readonly image: string;
+        readonly env?: Record<string, string>;
+    };
+    /**
+     * Workflow-declared per-job sandbox escape-hatch request (container jobs
+     * only). The orchestrator resolves it at dispatch against the operator's
+     * `org_settings` allow-list into a `ResolvedSandboxGrant` (a non-allow-listed
+     * request fails the run); the agent never reads this field. Additive — an
+     * older orchestrator that does not understand it ignores it.
+     */
+    readonly sandbox?: {
+        readonly capabilities?: string[];
+        readonly network?: SandboxNetworkMode;
+    };
     /** Normalized approval gate; when set the job is held before dispatch. */
     readonly approval?: LockApproval;
 }
@@ -622,13 +717,13 @@ export type LockJobOrFactory = LockJob | LockDynamicJobFn;
 /**
  * Private npm registry declaration in the lock file.
  * Carries the URL/scope/secret-reference but NOT the resolved token —
- * the orchestrator resolves the token at dispatch time via the per-environment
+ * the orchestrator resolves the token at dispatch time via the per-context
  * secretResolver.resolveForJob path.
  */
 export interface LockRegistry {
     readonly url: string;
     readonly scope?: string;
-    /** Qualified secret reference: `<environment>:<secret-name>`. */
+    /** Qualified secret reference: `<context>:<secret-name>`. */
     readonly tokenSecret: string;
     readonly alwaysAuth?: boolean;
 }
@@ -660,7 +755,7 @@ export interface LockWorkflow {
      */
     readonly registries?: readonly LockRegistry[];
     /**
-     * Extra qualified secret refs (`<environment>:<secret-name>`) to project as
+     * Extra qualified secret refs (`<context>:<secret-name>`) to project as
      * env vars on the install subprocess for use with a customer-committed `.kici/.npmrc`.
      */
     readonly installEnv?: readonly string[];
@@ -694,6 +789,14 @@ export interface LockWorkflow {
  */
 export interface LockFile {
     readonly schemaVersion: typeof SCHEMA_VERSION;
+    /**
+     * The newest breaking schema version at emit time (the compiler stamps
+     * `BREAKING_FLOOR`). A reader whose own `SCHEMA_VERSION` is below this value
+     * predates a breaking change the lock relies on and must reject it. Absent on
+     * pre-window locks, in which case the reader falls back to exact-match
+     * strictness (see `assertLockFileSchemaCompatible`).
+     */
+    readonly minReaderVersion?: number;
     readonly source: LockSource;
     /** SHA-256 hash of the serialized lock file content (excluding this field). Changes only when workflows, triggers, jobs, or bundle hashes change. */
     readonly contentHash: string;
@@ -705,6 +808,24 @@ export interface LockFile {
 export declare function isLockStaticJob(job: LockJobOrFactory): job is LockJob;
 /** Type guard for dynamic job generators */
 export declare function isLockDynamicJobFn(job: LockJobOrFactory): job is LockDynamicJobFn;
+/**
+ * Availability of the changed-files list for path-filter evaluation.
+ *
+ * Distinguishes three states that a bare `string[]` collapses into one:
+ * - `skipped` — no trigger has path patterns, so the fetch never ran. Path
+ *   filters are not evaluated (today's no-fetch fast path).
+ * - `fetched` — the fetch succeeded and the list is authoritative; an empty
+ *   list genuinely means "no files changed" and does NOT match a path filter.
+ * - `unavailable` — the diff could not be determined (a provider capability
+ *   gap such as universal-git PR events, or upstream degradation). Path
+ *   filters match conservatively so a real change is never silently dropped.
+ */
+export declare const changedFilesStatusSchema: z.ZodEnum<{
+    fetched: "fetched";
+    skipped: "skipped";
+    unavailable: "unavailable";
+}>;
+export type ChangedFilesStatus = z.infer<typeof changedFilesStatusSchema>;
 /**
  * Simulated event payload structure for trigger matching.
  *
@@ -720,8 +841,18 @@ export interface SimulatedEvent {
     targetBranch: string;
     /** PR source branch (only for PRs) */
     sourceBranch?: string;
+    /** Pull-request number for PR-family events (pull_request / review / review_comment); undefined otherwise. */
+    prNumber?: number;
     /** Changed files (for path filtering) */
     changedFiles?: string[];
+    /**
+     * Availability of {@link changedFiles} for path-filter evaluation. When
+     * `unavailable`, path filters match conservatively instead of inferring a
+     * no-match from an empty list. Optional for backward compatibility with the
+     * compiler/test CLI, which never fetches a diff (treated as legacy `fetched`
+     * exact-match semantics).
+     */
+    changedFilesStatus?: ChangedFilesStatus;
     /** Which provider originated this event. Optional for backward compatibility with compiler/test CLI. */
     provider?: ProviderType;
     /** Whether this PR comes from a fork (head repo != base repo). Only set for PR events. */