@kici-dev/engine 0.4.0 → 0.6.0

package/dist/trigger/matcher.js

@@ -1,6 +1,7 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { createTraceEntry, createWorkflowDecision } from "./decision-trace.js";
-import { getCompiledRegex, getGlobMatcher } from "./compiled-matchers.js";
+import { evaluateTextMatch } from "./text-match.js";
+import { TraceCheck, createCommitMessageTraceEntry, createTraceEntry, createWorkflowDecision } from "./decision-trace.js";
+import { getCompiledRegex, getGlobMatcher, getRepoGlobMatcher } from "./compiled-matchers.js";
 import { matchJsonPath, matchJsonPathNot } from "./jsonpath-matcher.js";
 //#region src/trigger/matcher.ts
 /**
@@ -35,7 +36,21 @@ function splitBranchPatterns(patterns) {
 */
 function matchBranchPattern(pattern, branch) {
 	if (pattern.type === "glob") return getGlobMatcher(pattern.pattern)(branch);
-	else return getCompiledRegex(pattern.pattern, pattern.flags).test(branch);
+	else return getCompiledRegex(pattern.pattern, pattern.flags, "branch/tag/repo pattern").test(branch);
+}
+/**
+* Match a repo pattern against a repository identifier.
+*
+* Same shape as {@link matchBranchPattern}, but glob patterns compile through
+* {@link getRepoGlobMatcher} so a dot-prefixed identifier (`.hidden/repo`) is
+* matched by `**`. Repo identifiers are org/name pairs, not paths, so there is
+* no dotfile convention to respect — and `repos: ['**']` means every repo.
+*
+* Regex patterns are unaffected: `dot` is a glob option with no regex analogue.
+*/
+function matchRepoPattern(pattern, repo) {
+	if (pattern.type === "glob") return getRepoGlobMatcher(pattern.pattern)(repo);
+	return getCompiledRegex(pattern.pattern, pattern.flags, "branch/tag/repo pattern").test(repo);
 }
 /**
 * Match any of the branch patterns.
@@ -73,10 +88,10 @@ function matchRepoPatterns(repos, sourceRepo) {
 	if (repos.length === 0) return true;
 	const { include, exclude } = splitBranchPatterns(repos);
 	if (exclude.length > 0) {
-		if (exclude.some((p) => matchBranchPattern(p, sourceRepo))) return false;
+		if (exclude.some((p) => matchRepoPattern(p, sourceRepo))) return false;
 	}
 	if (include.length === 0) return true;
-	return include.some((p) => matchBranchPattern(p, sourceRepo));
+	return include.some((p) => matchRepoPattern(p, sourceRepo));
 }
 /**
 * Evaluate repo pattern filter for a trigger against an event.
@@ -86,17 +101,48 @@ function matchRepoPatterns(repos, sourceRepo) {
 function evaluateRepoFilter(trigger, event, traces) {
 	if (trigger.repos?.length) {
 		if (!event.sourceRepo) {
-			traces.push(createTraceEntry("repo", "required", "(missing)", false));
+			traces.push(createTraceEntry(TraceCheck.RepoFilter, "required", "(missing)", false));
 			return false;
 		}
 		const { include, exclude } = splitBranchPatterns(trigger.repos);
 		const repoMatch = matchRepoPatterns(trigger.repos, event.sourceRepo);
-		traces.push(createTraceEntry("repo", `include:[${include.map((p) => p.pattern).join(",")}] exclude:[${exclude.map((p) => p.pattern).join(",")}]`, event.sourceRepo, repoMatch));
+		traces.push(createTraceEntry(TraceCheck.RepoFilter, `include:[${include.map((p) => p.pattern).join(",")}] exclude:[${exclude.map((p) => p.pattern).join(",")}]`, event.sourceRepo, repoMatch));
 		if (!repoMatch) return false;
 	}
 	return true;
 }
 /**
+* Evaluate a trigger's `commitMessage` filter. Returns true when the trigger
+* declares none (the fast path).
+*
+* An event with no message is INDETERMINATE, not a clean exclusion: the filter
+* is fail-visible, mirroring the Tier-1 `requires` gate, so a workflow whose
+* declared gate was never evaluated does not run.
+*/
+function evaluateCommitMessageFilter(trigger, event, traces) {
+	const match = trigger.commitMessage;
+	if (!match) return true;
+	if (event.commitMessage === void 0) {
+		traces.push(createCommitMessageTraceEntry({
+			match,
+			text: void 0,
+			passed: false,
+			indeterminate: true,
+			reason: "no commit message in payload (provider carries none for this event)"
+		}));
+		return false;
+	}
+	const result = evaluateTextMatch(event.commitMessage, match);
+	traces.push(createCommitMessageTraceEntry({
+		match,
+		text: event.commitMessage,
+		passed: result.pass,
+		indeterminate: result.indeterminate !== void 0,
+		...result.indeterminate !== void 0 && { reason: result.indeterminate }
+	}));
+	return result.pass;
+}
+/**
 * Match a PR trigger against a simulated event.
 */
 function matchPrTrigger(trigger, event, traces) {
@@ -132,6 +178,7 @@ function matchPrTrigger(trigger, event, traces) {
 		traces.push(createTraceEntry("paths", `include: [${include.join(", ")}] exclude: [${exclude.join(", ")}]`, event.changedFilesStatus === "unavailable" ? "[unavailable — matched conservatively]" : `[${changedFiles.join(", ")}]`, matches));
 		if (!matches) return false;
 	}
+	if (!evaluateCommitMessageFilter(trigger, event, traces)) return false;
 	if (!evaluateRepoFilter(trigger, event, traces)) return false;
 	return true;
 }
@@ -156,6 +203,7 @@ function matchPushTrigger(trigger, event, traces) {
 		traces.push(createTraceEntry("paths", `include: [${include.join(", ")}] exclude: [${exclude.join(", ")}]`, event.changedFilesStatus === "unavailable" ? "[unavailable — matched conservatively]" : `[${changedFiles.join(", ")}]`, matches));
 		if (!matches) return false;
 	}
+	if (!evaluateCommitMessageFilter(trigger, event, traces)) return false;
 	if (!evaluateRepoFilter(trigger, event, traces)) return false;
 	return true;
 }
@@ -174,6 +222,7 @@ function matchTagTrigger(trigger, event, traces) {
 		traces.push(createTraceEntry("tag pattern", trigger.patterns.map((p) => p.pattern).join("|"), event.targetBranch, matches));
 		if (!matches) return false;
 	}
+	if (!evaluateCommitMessageFilter(trigger, event, traces)) return false;
 	if (!evaluateRepoFilter(trigger, event, traces)) return false;
 	return true;
 }
@@ -213,7 +262,7 @@ function matchCommentTrigger(trigger, event, traces) {
 			traces.push(createTraceEntry("bodyMatch (glob)", trigger.bodyMatch.pattern, body, matches));
 			if (!matches) return false;
 		} else {
-			const matches = getCompiledRegex(trigger.bodyMatch.pattern, trigger.bodyMatch.flags).test(body);
+			const matches = getCompiledRegex(trigger.bodyMatch.pattern, trigger.bodyMatch.flags, "comment bodyMatch").test(body);
 			traces.push(createTraceEntry("bodyMatch (regex)", trigger.bodyMatch.pattern, body, matches));
 			if (!matches) return false;
 		}
@@ -493,12 +542,14 @@ function matchKiciEventTrigger(trigger, event, traces) {
 	traces.push(createTraceEntry("event name", trigger.eventName, eventName, nameMatches));
 	if (!nameMatches) return false;
 	if (trigger.match && Object.keys(trigger.match).length > 0) {
-		const matches = matchJsonPath(event.payload.payload ?? {}, trigger.match);
+		const eventPayload = event.payload.payload ?? {};
+		const matches = matchJsonPath(eventPayload, trigger.match);
 		traces.push(createTraceEntry("jsonpath match", JSON.stringify(trigger.match), "(payload)", matches));
 		if (!matches) return false;
 	}
 	if (trigger.not && Object.keys(trigger.not).length > 0) {
-		const passes = matchJsonPathNot(event.payload.payload ?? {}, trigger.not);
+		const eventPayload = event.payload.payload ?? {};
+		const passes = matchJsonPathNot(eventPayload, trigger.not);
 		traces.push(createTraceEntry("jsonpath not", JSON.stringify(trigger.not), "(payload)", passes));
 		if (!passes) return false;
 	}

package/dist/trigger/text-match.d.ts

@@ -0,0 +1,27 @@
+import type { LockTextMatch, TextMatch } from './types.js';
+/** A definite verdict, or fail-visible indeterminate. Mirrors `ContentRequirementResult`. */
+export interface TextMatchResult {
+    readonly pass: boolean;
+    /** Set (with `pass: false`) when the match could not be evaluated. */
+    readonly indeterminate?: string;
+}
+/**
+ * Compile a `/pattern/flags` (or bare-pattern) string, rejecting a ReDoS-prone
+ * pattern. Returns `null` when the pattern is syntactically invalid or fails the
+ * `safe-regex` star-height heuristic — callers treat `null` as indeterminate.
+ *
+ * Always compiles a FRESH RegExp. A `g`-flagged instance carries `lastIndex`
+ * across `.test()` calls, so a cached one would return alternating verdicts for
+ * the same input.
+ */
+export declare function compileSafeRegex(source: string): RegExp | null;
+/** True when the matcher carries at least one populated query key. */
+export declare function textMatchHasQuery(m: TextMatch | LockTextMatch): boolean;
+/** Render the populated keys for a decision-trace `pattern` field. */
+export declare function describeTextMatch(m: LockTextMatch): string;
+/**
+ * Evaluate a text match. Every entry in every list is a conjunct, and every
+ * populated key ANDs with the others; an empty matcher passes.
+ */
+export declare function evaluateTextMatch(text: string, m: LockTextMatch): TextMatchResult;
+//# sourceMappingURL=text-match.d.ts.map

package/dist/trigger/text-match.js

@@ -0,0 +1,86 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import safeRegex from "safe-regex";
+//#region src/trigger/text-match.ts
+/**
+* The single definition of what `contains` / `notContains` / `matches` /
+* `notMatches` mean.
+*
+* Two sites consume it: the Tier-0 `commitMessage` trigger filter (in
+* `matcher.ts`) and the Tier-1 `requires` content filter (in
+* `content-requirements.ts`). Sharing one function is what keeps them from
+* drifting into two dialects of the same vocabulary.
+*
+* Pure string logic — it imports only `safe-regex` and no Node built-in, so it
+* belongs in the browser-safe barrel rather than a subpath export.
+*/
+/**
+* Compile a `/pattern/flags` (or bare-pattern) string, rejecting a ReDoS-prone
+* pattern. Returns `null` when the pattern is syntactically invalid or fails the
+* `safe-regex` star-height heuristic — callers treat `null` as indeterminate.
+*
+* Always compiles a FRESH RegExp. A `g`-flagged instance carries `lastIndex`
+* across `.test()` calls, so a cached one would return alternating verdicts for
+* the same input.
+*/
+function compileSafeRegex(source) {
+	const wrapped = /^\/(.+)\/([gimsuy]*)$/.exec(source);
+	const pattern = wrapped ? wrapped[1] : source;
+	const flags = wrapped ? wrapped[2] : "";
+	let re;
+	try {
+		re = new RegExp(pattern, flags);
+	} catch {
+		return null;
+	}
+	return safeRegex(re) ? re : null;
+}
+/** True when the matcher carries at least one populated query key. */
+function textMatchHasQuery(m) {
+	const populated = (v) => Array.isArray(v) ? v.length > 0 : v !== void 0 && v !== null;
+	return populated(m.contains) || populated(m.notContains) || populated(m.matches) || populated(m.notMatches);
+}
+/** Render the populated keys for a decision-trace `pattern` field. */
+function describeTextMatch(m) {
+	const parts = [];
+	if (m.contains?.length) parts.push(`contains: [${m.contains.join(", ")}]`);
+	if (m.notContains?.length) parts.push(`notContains: [${m.notContains.join(", ")}]`);
+	if (m.matches?.length) parts.push(`matches: [${m.matches.join(", ")}]`);
+	if (m.notMatches?.length) parts.push(`notMatches: [${m.notMatches.join(", ")}]`);
+	if (m.ignoreCase) parts.push("ignoreCase");
+	return parts.length > 0 ? parts.join("; ") : "(no query)";
+}
+/** Evaluate every regex in `sources`; `expectMatch` selects matches vs notMatches. */
+function evaluateRegexes(text, sources, expectMatch) {
+	for (const source of sources) {
+		const re = compileSafeRegex(source);
+		if (!re) return {
+			pass: false,
+			indeterminate: `unsafe or invalid regex: ${source}`
+		};
+		if (re.test(text) !== expectMatch) return { pass: false };
+	}
+	return { pass: true };
+}
+/**
+* Evaluate a text match. Every entry in every list is a conjunct, and every
+* populated key ANDs with the others; an empty matcher passes.
+*/
+function evaluateTextMatch(text, m) {
+	const fold = (s) => m.ignoreCase === true ? s.toLowerCase() : s;
+	const haystack = fold(text);
+	for (const needle of m.contains ?? []) if (!haystack.includes(fold(needle))) return { pass: false };
+	for (const needle of m.notContains ?? []) if (haystack.includes(fold(needle))) return { pass: false };
+	if (m.matches?.length) {
+		const result = evaluateRegexes(text, m.matches, true);
+		if (!result.pass) return result;
+	}
+	if (m.notMatches?.length) {
+		const result = evaluateRegexes(text, m.notMatches, false);
+		if (!result.pass) return result;
+	}
+	return { pass: true };
+}
+//#endregion
+export { compileSafeRegex, describeTextMatch, evaluateTextMatch, textMatchHasQuery };
+
+//# sourceMappingURL=text-match.js.map

package/dist/trigger/types.d.ts

@@ -29,6 +29,15 @@
  * 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).
+ * Schema version 33 (additive): adds `requires` (declarative static content filter) to the push/pr/tag git-event triggers.
+ * Schema version 34 (additive): adds LockWorkflow.hasFilter (workflow-level pre-dispatch filter predicate).
+ * Schema version 35 (additive): adds `commitMessage` (LockTextMatch) to the push/pr/tag
+ *   git-event triggers, and contains/notContains/notMatches to LockContentRequirement.
+ * Schema version 36 (additive): adds LockJob.invoke (invokeSource gate, incl. optional).
+ * Schema version 37 (additive): adds LockJob.gitCredentials (named git credential refs).
+ * Schema version 38 (additive): adds container.auth (private-registry credentials for the job image).
+ * Schema version 39 (additive): adds container.dockerfile/context/target/args (build the
+ *   job's image from a Dockerfile in the repo) and container.auth.registry.
  */
 import { z } from 'zod';
 import type { ProviderType } from '../provider/types.js';
@@ -41,7 +50,7 @@ import { ExecutionJobStatus } from '../protocol/messages/execution-status.js';
  * 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;
+export declare const SCHEMA_VERSION: 39;
 /**
  * Oldest lock schema version this codebase can still read correctly — the lower
  * bound of the acceptance window.
@@ -54,8 +63,8 @@ export declare const SCHEMA_VERSION: 32;
  * 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.
+ * recent breaking bump; v31 through v35 were additive, so a v30 lock still
+ * reads correctly.
  */
 export declare const BREAKING_FLOOR: 30;
 /**
@@ -92,6 +101,121 @@ export interface LockBranchPattern {
     readonly pattern: string;
     readonly flags?: string;
 }
+/**
+ * A declarative query over one piece of text: literal substrings and/or a
+ * regex, in either direction. Pure DATA the orchestrator interprets — never
+ * author code — so it is safe to evaluate inside the orchestrator under the
+ * execution-purity model.
+ *
+ * Every entry in a list is a CONJUNCT: `contains: [a, b]` means the text
+ * contains `a` AND contains `b`. OR is expressed by declaring two triggers,
+ * since a workflow's trigger list is already "first match wins".
+ *
+ * This is the SDK-facing shape a workflow author writes; the compiler
+ * normalizes it to {@link LockTextMatch}.
+ */
+export interface TextMatch {
+    /** Literal substring(s). Every entry must be present. */
+    readonly contains?: string | readonly string[];
+    /** Literal substring(s). No entry may be present. */
+    readonly notContains?: string | readonly string[];
+    /** Regex(es), as a RegExp or a `/pattern/flags` string. Every one must match. */
+    readonly matches?: string | RegExp | readonly (string | RegExp)[];
+    /** Regex(es). None may match. */
+    readonly notMatches?: string | RegExp | readonly (string | RegExp)[];
+    /**
+     * Case-insensitive comparison for `contains`/`notContains` ONLY. Default false.
+     * It deliberately does not touch the regex keys: a regex already carries its
+     * own flags, and injecting `i` into a pattern whose author omitted it would
+     * silently change its meaning.
+     */
+    readonly ignoreCase?: boolean;
+}
+/**
+ * Lock-file form of {@link TextMatch}. The compiler normalizes every key to a
+ * flat array, and every regex to a `/pattern/flags` string, so the orchestrator
+ * matcher has exactly one shape to interpret.
+ */
+export interface LockTextMatch {
+    readonly contains?: readonly string[];
+    readonly notContains?: readonly string[];
+    /** Always in `/pattern/flags` form. */
+    readonly matches?: readonly string[];
+    /** Always in `/pattern/flags` form. */
+    readonly notMatches?: readonly string[];
+    readonly ignoreCase?: boolean;
+}
+/**
+ * How a file's bytes are parsed before a content query runs.
+ * `auto` picks by extension: `.json` → json, `.yaml`/`.yml` → yaml, else text.
+ */
+export type ContentFormat = 'json' | 'yaml' | 'text' | 'auto';
+/**
+ * Declarative static content filter: a query over the bytes of one source file
+ * at the event's ref. Pure DATA the orchestrator's own matcher interprets — never
+ * author code — so it is safe to evaluate in the orchestrator (Part B of the
+ * execution-purity model). Query keys
+ * (`exists`/`match`/`not`/`contains`/`notContains`/`matches`/`notMatches`) are
+ * AND-ed within an entry; `absent` is mutually exclusive with them and passes
+ * only when the file is missing.
+ *
+ * This is the SDK-facing shape a workflow author writes, which accepts a scalar
+ * or `RegExp` where the lock form ({@link LockContentRequirement}) carries a flat
+ * array of `/pattern/flags` strings — the compiler normalizes one to the other.
+ */
+export interface ContentRequirement {
+    /** Repo-relative path of the file to query. */
+    readonly file: string;
+    /** Parse format; defaults to `auto` when unset. */
+    readonly format?: ContentFormat;
+    /** JSONPath expressions that must each resolve to ≥1 node (json/yaml only). */
+    readonly exists?: readonly string[];
+    /** JSONPath → expected-value map; every expression must match (json/yaml only). */
+    readonly match?: Record<string, unknown>;
+    /** JSONPath → value map; passes only when NONE match (json/yaml only). */
+    readonly not?: Record<string, unknown>;
+    /** Literal substring(s) that must ALL be present in the raw file text. */
+    readonly contains?: string | readonly string[];
+    /** Literal substring(s) of which NONE may be present in the raw file text. */
+    readonly notContains?: string | readonly string[];
+    /** Regex(es) that must ALL match the raw file text (RegExp or `/pattern/flags`). */
+    readonly matches?: string | RegExp | readonly (string | RegExp)[];
+    /** Regex(es) of which NONE may match the raw file text. */
+    readonly notMatches?: string | RegExp | readonly (string | RegExp)[];
+    /** Case-insensitive `contains`/`notContains`. Default false. */
+    readonly ignoreCase?: boolean;
+    /** When true, the entry passes only if the file is absent. Excludes all query keys. */
+    readonly absent?: boolean;
+}
+/**
+ * Lock-file form of {@link ContentRequirement}. The compiler normalizes each
+ * raw-text key to the flat {@link LockTextMatch} shape, so the orchestrator
+ * matcher has one shape to interpret.
+ */
+export interface LockContentRequirement {
+    readonly file: string;
+    readonly format?: ContentFormat;
+    readonly exists?: readonly string[];
+    readonly match?: Record<string, unknown>;
+    readonly not?: Record<string, unknown>;
+    readonly contains?: readonly string[];
+    readonly notContains?: readonly string[];
+    readonly matches?: readonly string[];
+    readonly notMatches?: readonly string[];
+    readonly ignoreCase?: boolean;
+    readonly absent?: boolean;
+}
+/**
+ * Resolve a content requirement's parse format to a concrete value. An explicit
+ * non-`auto` format is returned as-is; `auto` (or unset) is resolved by the file
+ * extension: `.json` → json, `.yaml`/`.yml` → yaml, everything else text.
+ *
+ * Yaml-free (pure string logic) so it lives in the browser-safe barrel and is
+ * the single source of truth for both the compiler's compile-time serializer and
+ * the orchestrator's eval-time matcher — the two can never disagree about how a
+ * file's format is picked.
+ */
+export declare function resolveContentFormat(file: string, format: ContentFormat | undefined): 'json' | 'yaml' | 'text';
 /**
  * PR trigger in lock file.
  * Optimized for orchestrator event matching - flat structure with all filters accessible.
@@ -103,6 +227,10 @@ export interface LockPrTrigger {
     readonly sourceBranches: readonly LockBranchPattern[];
     readonly paths: readonly string[];
     readonly repos?: readonly LockBranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly LockContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: LockTextMatch;
 }
 /**
  * Push trigger in lock file.
@@ -113,6 +241,10 @@ export interface LockPushTrigger {
     readonly branches: readonly LockBranchPattern[];
     readonly paths: readonly string[];
     readonly repos?: readonly LockBranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly LockContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: LockTextMatch;
 }
 /**
  * Tag trigger in lock file.
@@ -122,6 +254,10 @@ export interface LockTagTrigger {
     readonly _type: 'tag';
     readonly patterns: readonly LockBranchPattern[];
     readonly repos?: readonly LockBranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly LockContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: LockTextMatch;
 }
 /**
  * Comment trigger in lock file.
@@ -426,17 +562,27 @@ export type LockStepEntry = LockStep | LockParallelStep;
 /** Type guard distinguishing a parallel group from an ordinary lock step. */
 export declare function isLockParallelStep(entry: LockStepEntry): entry is LockParallelStep;
 /**
- * Inline expression value for pure dynamic functions.
- * The compiler serializes pure functions as { _type: 'inline', expression: '(event) => ...' }
- * and the orchestrator evaluates them via vm.runInNewContext at dispatch time.
- * struct with discriminant and expression field.
- * _type: 'inline' alongside existing 'static' and 'dynamic' discriminants.
+ * Serialized inline expression for a dynamic env/context/concurrencyGroup
+ * field, shaped as `{ _type: 'inline', expression: '(event) => ...' }`
+ * alongside the existing 'static' and 'dynamic' discriminants.
+ *
+ * @deprecated Schema v11 inline expressions are no longer evaluated in the
+ * orchestrator. Dynamic env/context/concurrencyGroup fields are resolved on the
+ * eval agent's init-runner. The compiler no longer emits this type; readers keep
+ * recognizing it only to defer an old lock's field to the init round. Removed at
+ * the next major (v1.0.0).
  */
 export interface LockInlineValue {
     readonly _type: 'inline';
     readonly expression: string;
 }
-/** Type guard for inline expression values */
+/**
+ * Type guard for inline expression values.
+ *
+ * @deprecated See {@link LockInlineValue}. Retained only so a reader can
+ * recognize an old lock's inline field and defer it to the eval agent's
+ * init-runner. Removed at the next major (v1.0.0).
+ */
 export declare function isLockInlineValue(value: unknown): value is LockInlineValue;
 /**
  * Author-facing keyword sugar for a `needs` edge's run condition. Each keyword
@@ -595,9 +741,34 @@ export interface ResolvedSandboxGrant {
     /** Run the container as this user (operator-config path only in Phase 2). */
     user?: string;
 }
+/**
+ * Invoke-gate action carried on a lock job (compiled from `invokeSource()`).
+ * A job carrying this never runs steps on an agent: the orchestrator emits the
+ * named kici event at the source repo and gates on the runs it triggers.
+ */
+export interface LockInvoke {
+    /** The kici event name to emit; source-repo workflows subscribe with `kiciEvent({ name })`. */
+    readonly event: string;
+    /** Target scope. `'source'` targets exactly the source repo (the only v1 scope). */
+    readonly scope: 'source';
+    /** Optional event payload delivered to subscribers. */
+    readonly payload?: Readonly<Record<string, unknown>>;
+    /**
+     * When true, a zero-subscriber emit succeeds immediately (the repo may opt
+     * out). Absent/false (the default) fails the gate on zero subscribers.
+     */
+    readonly optional?: boolean;
+}
 export interface LockJob {
     readonly _type: 'static';
     readonly name: string;
+    /**
+     * Invoke-gate action. When set, the job is a gate: it never dispatches steps
+     * to an agent; the orchestrator emits `invoke.event` at the source repo and
+     * tracks each triggered run as a proxy child. Additive — an older
+     * orchestrator that does not understand it ignores it (the gate stays inert).
+     */
+    readonly invoke?: LockInvoke;
     /** Single-agent targeting matchers. Absent when the job uses `runsOnAll` instead. */
     readonly runsOn?: readonly LabelMatcher[];
     readonly excludeLabels?: readonly LabelMatcher[];
@@ -607,6 +778,16 @@ export interface LockJob {
      * `any` picks any available agent. Absent on a `runsOnAll` fan-out job.
      */
     readonly runsOnPick?: RunsOnPick;
+    /**
+     * Named git credentials for this job, as SECRET NAMES in qualified
+     * `<context>:<secret-name>` form — never credential material.
+     *
+     * `default` is used when a call names no credential; any other key is
+     * referenced by name. Additive: an older orchestrator that does not
+     * understand it simply passes it through in `jobConfig`, and an older agent
+     * ignores it (git falls back to its own mechanisms, exactly as before).
+     */
+    readonly gitCredentials?: Readonly<Record<string, Readonly<Record<string, string>>>>;
     /**
      * Host fan-out predicate (mutually exclusive with `runsOn`). When set, the job
      * fans out to every roster host matching the predicate, one pinned child per host.
@@ -640,21 +821,28 @@ export interface LockJob {
     readonly rules?: readonly LockRule[];
     readonly description?: string;
     /**
-     * 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.
+     * Bound contexts in merge order. Each entry is a static name; `dynamic` is set
+     * when it is a function resolved on the eval agent's init-runner. Later entries
+     * override earlier ones on name collisions. The `LockInlineValue` shape is a
+     * deprecated form still accepted from old locks (see {@link LockInlineValue}).
      */
     readonly contexts?: ReadonlyArray<{
         value: string | LockInlineValue;
         dynamic: boolean;
     }>;
-    /** Static environment variables or inline expression (pure function). */
+    /**
+     * Static environment variables. A deprecated `LockInlineValue` shape is still
+     * accepted from old locks (see {@link LockInlineValue}).
+     */
     readonly env?: Record<string, string> | LockInlineValue;
-    /** When true, env is dynamic (function) -- resolved at orchestrator two-phase eval or inline. */
+    /** When true, env is dynamic (function) -- resolved on the eval agent's init-runner. */
     readonly dynamicEnv?: boolean;
-    /** Concurrency group name (static string) or inline expression (pure function). */
+    /**
+     * Concurrency group name (static string). A deprecated `LockInlineValue` shape
+     * is still accepted from old locks (see {@link LockInlineValue}).
+     */
     readonly concurrencyGroup?: string | LockInlineValue;
-    /** When true, concurrencyGroup is dynamic (function) -- resolved at orchestrator two-phase eval or inline. */
+    /** When true, concurrencyGroup is dynamic (function) -- resolved on the eval agent's init-runner. */
     readonly dynamicConcurrencyGroup?: boolean;
     /** Total job wall-clock timeout in milliseconds (init + all steps + hooks). Threaded to the agent via jobConfig. */
     readonly timeout?: number;
@@ -666,15 +854,55 @@ export interface LockJob {
     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.)
+     * bare image string, or an object naming exactly one image source: a
+     * finalized `image`, or a `dockerfile` the agent builds from the cloned tree
+     * before the job starts. 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`, including `ContainerRegistryAuth`; the engine
+     * cannot import the SDK, so it is inlined here.)
      */
     readonly container?: string | {
-        readonly image: string;
+        /** Finalized image to pull. Exactly one of `image` / `dockerfile` is set. */
+        readonly image?: string;
+        /**
+         * Repo-relative Dockerfile the agent builds before the job runs.
+         *
+         * The agent re-validates this path against the resolved workdir: a lock
+         * file is repo content, so a path that escapes the tree must be refused
+         * on the agent too, not only by the SDK that wrote it.
+         */
+        readonly dockerfile?: string;
+        /** Repo-relative build context. Defaults to the repository root. */
+        readonly context?: string;
+        /** Build stage to stop at. */
+        readonly target?: string;
+        /**
+         * Build arguments. Plain strings — never secret references, because a
+         * build argument is recorded in the built image's history.
+         */
+        readonly args?: Record<string, string>;
         readonly env?: Record<string, string>;
+        /**
+         * Private-registry credentials for pulling `image`.
+         *
+         * Flattened `Sourced<Name>` pairs: exactly one half of each pair is
+         * set — `*Secret` names a `<context>:<secret-name>` entry to resolve,
+         * `*Value` carries material supplied at run time.
+         */
+        readonly auth?: {
+            readonly username?: string;
+            readonly usernameSecret?: string;
+            readonly usernameValue?: string;
+            readonly tokenSecret?: string;
+            readonly tokenValue?: string;
+            /**
+             * Registry host the credentials belong to. Derived from `image` when
+             * one is set; REQUIRED with `dockerfile`, whose base image is named
+             * inside the Dockerfile and cannot be read back out reliably.
+             */
+            readonly registry?: string;
+        };
     };
     /**
      * Workflow-declared per-job sandbox escape-hatch request (container jobs
@@ -769,6 +997,13 @@ export interface LockWorkflow {
     readonly timeout?: number;
     /** Normalized approval gate; when set the whole run is held before any job dispatches. */
     readonly approval?: LockApproval;
+    /**
+     * True when the workflow declares a `filter` predicate. A bare flag, not a
+     * source reference: `LockWorkflow.source` already identifies the module and
+     * export, so the eval agent loads it and reads `.filter` off the workflow
+     * object. Mirrors the `dynamicEnv` / `dynamicConcurrencyGroup` convention.
+     */
+    readonly hasFilter?: boolean;
 }
 /**
  * Complete lock file structure.
@@ -783,7 +1018,7 @@ export interface LockWorkflow {
  * v8 adds runsOn polymorphic type (string | string[] | selector) and excludeLabels.
  * v9 adds repos/notRepos repo pattern fields to git-event triggers for global workflow matching.
  * v10 removes notRepos/notPaths fields; negative patterns use ! prefix in repos/paths arrays.
- * v11 adds LockInlineValue type for pure function inline evaluation.
+ * v11 adds the LockInlineValue type (deprecated; inline dynamic fields are resolved on the eval agent).
  * v12 adds workflow-level registries and installEnv for private npm registry auth.
  * v13 adds job-level and workflow-level timeout.
  */
@@ -869,6 +1104,13 @@ export interface SimulatedEvent {
      * to the previous owner.
      */
     senderUserId?: string;
+    /**
+     * Text a `commitMessage` trigger filter is tested against: the full head-commit
+     * message for push/tag, or PR title + body for pull-request events. Absent when
+     * the provider payload carries none — which a `commitMessage` filter treats as
+     * INDETERMINATE (fail-visible), never as an empty string.
+     */
+    commitMessage?: string;
     /** Repository identifier where the event occurred (e.g., "owner/repo").
      *  Used by global workflow repo pattern matching. */
     sourceRepo?: string;