@kici-dev/engine 0.12.0 → 0.14.0

package/dist/protocol/messages/platform-orchestrator.d.ts

@@ -2985,6 +2985,7 @@ export declare const platformToOrchestratorMessageSchema: z.ZodDiscriminatedUnio
         "held_run.request": "held_run.request";
         "job.cancel": "job.cancel";
         "org_settings.dashboard_write_policy.update": "org_settings.dashboard_write_policy.update";
+        "peer.forget": "peer.forget";
         purge_chunk: "purge_chunk";
         "registration.delete": "registration.delete";
         "registration.disable": "registration.disable";
@@ -3001,6 +3002,8 @@ export declare const platformToOrchestratorMessageSchema: z.ZodDiscriminatedUnio
         "runs.list.read": "runs.list.read";
         "scaler.agents.read": "scaler.agents.read";
         "scaler.capacity.read": "scaler.capacity.read";
+        "scaler.orphan.stop": "scaler.orphan.stop";
+        "scaler.orphans.read": "scaler.orphans.read";
         "secret.delete": "secret.delete";
         "secret.list.read": "secret.list.read";
         "secret.reveal": "secret.reveal";

package/dist/trigger/decision-trace.d.ts

@@ -30,6 +30,12 @@ export interface WorkflowDecision {
     checks: TraceEntry[];
     /** Summary reason */
     summary: string;
+    /**
+     * The `paths` lists of triggers that matched only because the changed files
+     * were unavailable while a git range existed. Set only when no trigger
+     * matched outright; the agent decides these from its clone.
+     */
+    deferredPaths?: string[][];
 }
 /**
  * Max characters of any free-text field a trace entry carries, so an

package/dist/trigger/diff-range.d.ts

@@ -0,0 +1,66 @@
+/**
+ * Which files an event changed, expressed as a git range.
+ *
+ * The one definition the orchestrator's changed-files fetchers and the agent's
+ * clone diff share, so both layers reach the same answer from the same event.
+ * Pure — no I/O and no `node:*` import — because the engine barrel is
+ * browser-safe.
+ */
+import { z } from 'zod';
+export declare const diffRangeKindSchema: z.ZodEnum<{
+    deleted: "deleted";
+    "new-branch": "new-branch";
+    none: "none";
+    pr: "pr";
+    "two-dot": "two-dot";
+}>;
+export type DiffRangeKind = z.infer<typeof diffRangeKindSchema>;
+declare const Kind: {
+    deleted: "deleted";
+    "new-branch": "new-branch";
+    none: "none";
+    pr: "pr";
+    "two-dot": "two-dot";
+};
+export type DiffRange = 
+/** `git diff base..head` — a push to an existing branch. */
+{
+    kind: (typeof Kind)['two-dot'];
+    base: string;
+    head: string;
+}
+/** Three-dot `defaultBranch...head` — the files a new branch adds. */
+ | {
+    kind: (typeof Kind)['new-branch'];
+    defaultBranch: string;
+    head: string;
+}
+/** A deleted branch: no files changed. */
+ | {
+    kind: typeof Kind.deleted;
+}
+/** Three-dot `base...HEAD` — a pull request. */
+ | {
+    kind: typeof Kind.pr;
+    base: string;
+}
+/** No range exists: nobody can compute a diff for this event. */
+ | {
+    kind: typeof Kind.none;
+};
+/** The event fields a range is read from; `SimulatedEvent` and the SDK `EventPayload` both fit. */
+export interface DiffRangeEvent {
+    type: string;
+    targetBranch?: string;
+    baseBranch?: string;
+    defaultBranch?: string;
+    payload?: Record<string, unknown>;
+}
+/** Whether a SHA is git's all-zero placeholder (a created or deleted ref). */
+export declare function isZeroSha(sha: string): boolean;
+/** The git range an event changed, or `none` when no diff exists anywhere. */
+export declare function resolveDiffRange(event: DiffRangeEvent): DiffRange;
+/** Whether a range lets an agent compute the diff the orchestrator could not. */
+export declare function isDeferrableRange(range: DiffRange): boolean;
+export {};
+//# sourceMappingURL=diff-range.d.ts.map

package/dist/trigger/diff-range.js

@@ -0,0 +1,68 @@
+import "../rolldown-runtime-ClRpJifh.js";
+import { z } from "zod";
+//#region src/trigger/diff-range.ts
+/**
+* Which files an event changed, expressed as a git range.
+*
+* The one definition the orchestrator's changed-files fetchers and the agent's
+* clone diff share, so both layers reach the same answer from the same event.
+* Pure — no I/O and no `node:*` import — because the engine barrel is
+* browser-safe.
+*/
+const diffRangeKindSchema = z.enum([
+	"two-dot",
+	"new-branch",
+	"deleted",
+	"pr",
+	"none"
+]);
+const Kind = diffRangeKindSchema.enum;
+const ZERO_SHA_RE = /^0+$/;
+/** Whether a SHA is git's all-zero placeholder (a created or deleted ref). */
+function isZeroSha(sha) {
+	return ZERO_SHA_RE.test(sha);
+}
+function nonEmptyString(value) {
+	return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function defaultBranchOf(event) {
+	if (event.defaultBranch) return event.defaultBranch;
+	const repository = event.payload?.repository;
+	if (repository === null || typeof repository !== "object") return void 0;
+	return nonEmptyString(repository.default_branch);
+}
+/** The git range an event changed, or `none` when no diff exists anywhere. */
+function resolveDiffRange(event) {
+	if (event.type === "pull_request") {
+		const base = event.baseBranch ?? event.targetBranch;
+		return base ? {
+			kind: Kind.pr,
+			base
+		} : { kind: Kind.none };
+	}
+	if (event.type !== "push") return { kind: Kind.none };
+	const before = nonEmptyString(event.payload?.before);
+	const after = nonEmptyString(event.payload?.after);
+	if (!before || !after) return { kind: Kind.none };
+	if (isZeroSha(after)) return { kind: Kind.deleted };
+	if (!isZeroSha(before)) return {
+		kind: Kind["two-dot"],
+		base: before,
+		head: after
+	};
+	const defaultBranch = defaultBranchOf(event);
+	if (!defaultBranch || defaultBranch === event.targetBranch) return { kind: Kind.none };
+	return {
+		kind: Kind["new-branch"],
+		defaultBranch,
+		head: after
+	};
+}
+/** Whether a range lets an agent compute the diff the orchestrator could not. */
+function isDeferrableRange(range) {
+	return range.kind === Kind["two-dot"] || range.kind === Kind["new-branch"] || range.kind === Kind.pr;
+}
+//#endregion
+export { diffRangeKindSchema, isDeferrableRange, isZeroSha, resolveDiffRange };
+
+//# sourceMappingURL=diff-range.js.map

package/dist/trigger/matcher.d.ts

@@ -17,10 +17,23 @@ 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;
+/** Set by a push/pr trigger whose `paths` check passed only because the diff was unavailable. */
+/** Trace value of a `paths` check that read an unavailable diff. */
+export declare const UnavailablePathsTrace: {
+    /** A git range exists: the agent decides from its clone. */
+    readonly DecidedOnAgent: '[unavailable — decided on agent]';
+    /** No range the agent can diff: the workflow runs conservatively. */
+    readonly Conservative: '[unavailable — matched conservatively]';
+};
+/** Appended to a matched decision's summary when its paths are left to the agent. */
+export declare const DEFERRED_PATHS_SUMMARY_SUFFIX = " \u2014 paths decided on the agent";
+export interface TriggerMatchNotes {
+    conservativePaths?: readonly string[];
+}
 /**
  * Match a trigger against a simulated event.
  */
-export declare function matchTrigger(trigger: LockTrigger, event: SimulatedEvent, traces: TraceEntry[]): boolean;
+export declare function matchTrigger(trigger: LockTrigger, event: SimulatedEvent, traces: TraceEntry[], notes?: TriggerMatchNotes): boolean;
 /**
  * Match all triggers for a workflow against an event.
  * Returns WorkflowDecision with full trace.

package/dist/trigger/matcher.js

@@ -2,6 +2,7 @@ import "../rolldown-runtime-ClRpJifh.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 { isDeferrableRange, resolveDiffRange } from "./diff-range.js";
 import { matchJsonPath, matchJsonPathNot } from "./jsonpath-matcher.js";
 //#region src/trigger/matcher.ts
 /**
@@ -142,10 +143,37 @@ function evaluateCommitMessageFilter(trigger, event, traces) {
 	}));
 	return result.pass;
 }
+/** Set by a push/pr trigger whose `paths` check passed only because the diff was unavailable. */
+/** Trace value of a `paths` check that read an unavailable diff. */
+const UnavailablePathsTrace = {
+	/** A git range exists: the agent decides from its clone. */
+	DecidedOnAgent: "[unavailable — decided on agent]",
+	/** No range the agent can diff: the workflow runs conservatively. */
+	Conservative: "[unavailable — matched conservatively]"
+};
+/** Appended to a matched decision's summary when its paths are left to the agent. */
+const DEFERRED_PATHS_SUMMARY_SUFFIX = " — paths decided on the agent";
+/**
+* Evaluate a push/pr trigger's `paths` list and trace it. An `unavailable`
+* diff matches; when the event still has a git range, the match is recorded in
+* `notes` so the workflow's path decision moves to the agent's clone.
+*/
+function checkTriggerPaths(paths, event, traces, notes) {
+	if (paths.length === 0) return true;
+	const changedFiles = event.changedFiles ?? [];
+	const { include, exclude } = splitStringPatterns(paths);
+	const unavailable = event.changedFilesStatus === "unavailable";
+	const deferrable = unavailable && isDeferrableRange(resolveDiffRange(event));
+	const matches = matchPathPatterns(paths, changedFiles, event.changedFilesStatus);
+	const value = !unavailable ? `[${changedFiles.join(", ")}]` : deferrable ? UnavailablePathsTrace.DecidedOnAgent : UnavailablePathsTrace.Conservative;
+	traces.push(createTraceEntry("paths", `include: [${include.join(", ")}] exclude: [${exclude.join(", ")}]`, value, matches));
+	if (deferrable && notes) notes.conservativePaths = paths;
+	return matches;
+}
 /**
 * Match a PR trigger against a simulated event.
 */
-function matchPrTrigger(trigger, event, traces) {
+function matchPrTrigger(trigger, event, traces, notes) {
 	if (event.type !== "pull_request") {
 		traces.push(createTraceEntry("event type", "pull_request", event.type, false));
 		return false;
@@ -171,13 +199,7 @@ function matchPrTrigger(trigger, event, traces) {
 		traces.push(createTraceEntry("source branch", trigger.sourceBranches.map((p) => p.pattern).join("|"), event.sourceBranch, matches));
 		if (!matches) return false;
 	}
-	if (trigger.paths.length > 0) {
-		const changedFiles = event.changedFiles ?? [];
-		const { include, exclude } = splitStringPatterns(trigger.paths);
-		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 (!checkTriggerPaths(trigger.paths, event, traces, notes)) return false;
 	if (!evaluateCommitMessageFilter(trigger, event, traces)) return false;
 	if (!evaluateRepoFilter(trigger, event, traces)) return false;
 	return true;
@@ -185,7 +207,7 @@ function matchPrTrigger(trigger, event, traces) {
 /**
 * Match a push trigger against a simulated event.
 */
-function matchPushTrigger(trigger, event, traces) {
+function matchPushTrigger(trigger, event, traces, notes) {
 	if (event.type !== "push") {
 		traces.push(createTraceEntry("event type", "push", event.type, false));
 		return false;
@@ -196,13 +218,7 @@ function matchPushTrigger(trigger, event, traces) {
 		traces.push(createTraceEntry("branch", trigger.branches.map((p) => p.pattern).join("|"), event.targetBranch, matches));
 		if (!matches) return false;
 	}
-	if (trigger.paths.length > 0) {
-		const changedFiles = event.changedFiles ?? [];
-		const { include, exclude } = splitStringPatterns(trigger.paths);
-		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 (!checkTriggerPaths(trigger.paths, event, traces, notes)) return false;
 	if (!evaluateCommitMessageFilter(trigger, event, traces)) return false;
 	if (!evaluateRepoFilter(trigger, event, traces)) return false;
 	return true;
@@ -737,10 +753,10 @@ function matchLifecycleTrigger(trigger, event, traces) {
 /**
 * Match a trigger against a simulated event.
 */
-function matchTrigger(trigger, event, traces) {
+function matchTrigger(trigger, event, traces, notes) {
 	switch (trigger._type) {
-		case "pr": return matchPrTrigger(trigger, event, traces);
-		case "push": return matchPushTrigger(trigger, event, traces);
+		case "pr": return matchPrTrigger(trigger, event, traces, notes);
+		case "push": return matchPushTrigger(trigger, event, traces, notes);
 		case "tag": return matchTagTrigger(trigger, event, traces);
 		case "comment": return matchCommentTrigger(trigger, event, traces);
 		case "review": return matchReviewTrigger(trigger, event, traces);
@@ -772,13 +788,29 @@ function matchTrigger(trigger, event, traces) {
 function matchWorkflowTriggers(workflow, event) {
 	const allTraces = [];
 	if (workflow.triggers.length === 0) return createWorkflowDecision(workflow.name, false, [], void 0, "No triggers defined");
+	let firstDeferred;
+	const deferredPaths = [];
 	for (let i = 0; i < workflow.triggers.length; i++) {
 		const trigger = workflow.triggers[i];
 		if (trigger == null) continue;
 		const triggerTraces = [];
-		if (matchTrigger(trigger, event, triggerTraces)) return createWorkflowDecision(workflow.name, true, triggerTraces, i, `Matched trigger ${i + 1} (${trigger._type})`);
+		const notes = {};
+		if (matchTrigger(trigger, event, triggerTraces, notes)) {
+			if (notes.conservativePaths === void 0) return createWorkflowDecision(workflow.name, true, triggerTraces, i, `Matched trigger ${i + 1} (${trigger._type})`);
+			deferredPaths.push([...notes.conservativePaths]);
+			firstDeferred ??= {
+				index: i,
+				traces: triggerTraces,
+				type: trigger._type
+			};
+			continue;
+		}
 		allTraces.push(...triggerTraces);
 	}
+	if (firstDeferred) return {
+		...createWorkflowDecision(workflow.name, true, firstDeferred.traces, firstDeferred.index, `Matched trigger ${firstDeferred.index + 1} (${firstDeferred.type})${DEFERRED_PATHS_SUMMARY_SUFFIX}`),
+		deferredPaths
+	};
 	return createWorkflowDecision(workflow.name, false, allTraces, void 0, "No triggers matched");
 }
 /**
@@ -788,6 +820,6 @@ function matchAllWorkflows(workflows, event) {
 	return workflows.map((w) => matchWorkflowTriggers(w, event));
 }
 //#endregion
-export { matchAllWorkflows, matchBranchPattern, matchPathPatterns, matchRepoPatterns, matchTrigger, matchWorkflowTriggers };
+export { DEFERRED_PATHS_SUMMARY_SUFFIX, UnavailablePathsTrace, matchAllWorkflows, matchBranchPattern, matchPathPatterns, matchRepoPatterns, matchTrigger, matchWorkflowTriggers };
 
 //# sourceMappingURL=matcher.js.map

package/dist/trigger/types.d.ts

@@ -1131,6 +1131,12 @@ export interface SimulatedEvent {
     isForkPR?: boolean;
     /** Base branch ref for PR events (the branch being merged into). */
     baseBranch?: string;
+    /**
+     * The repository's default branch, when the delivery names it. A new-branch
+     * push diffs against it (`resolveDiffRange`); absent, the range falls back to
+     * `payload.repository.default_branch`.
+     */
+    defaultBranch?: string;
     /** Sender username from the webhook payload (e.g. GitHub login). */
     senderUsername?: string;
     /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/engine",
-  "version": "0.12.0",
+  "version": "0.14.0",
   "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",
   "keywords": [
     "ci",
@@ -23,7 +23,7 @@
   },
   "license": "AGPL-3.0-only",
   "engines": {
-    "node": ">=24"
+    "node": ">=24.5.0"
   },
   "type": "module",
   "files": [

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/engine@0.12.0",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.12.0/26df8fdf-b46b-49db-86d9-b586bd3124fa",
+  "name": "@kici-dev/engine@0.14.0",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.14.0/1e6771dc-3781-402f-8aa7-93c6edb56fcc",
   "creationInfo": {
-    "created": "2026-09-28T05:10:36Z",
+    "created": "2026-10-02T14:42:42Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -54,7 +54,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.12.0",
+      "versionInfo": "0.14.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -65,7 +65,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.12.0"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.14.0"
         }
       ],
       "description": "Shared business logic for the KiCI CI/CD stack: protocol, triggers, state machine, and provider interfaces used by the Platform relay, orchestrator, and compiler.",