@kici-dev/engine 0.1.16 → 0.1.18

package/dist/trigger/types.d.ts

@@ -11,12 +11,17 @@
  * 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.
  */
 import { z } from 'zod';
 import type { ProviderType } from '../provider/types.js';
 import type { ApproverClause } from '../approval/types.js';
+import { LabelMatcher } from '../labels-match.js';
 /** Schema version - increment on breaking changes */
-export declare const SCHEMA_VERSION: 16;
+export declare const SCHEMA_VERSION: 20;
 /**
  * Normalized approval config carried in the lock file. Produced by the compiler
  * from an SDK `requireApproval` at any of the three levels; consumed by the
@@ -346,6 +351,17 @@ export interface LockInlineValue {
 }
 /** Type guard for inline expression values */
 export declare function isLockInlineValue(value: unknown): value is LockInlineValue;
+/**
+ * Per-edge failure policy for a `needs` dependency: `skip` propagates an
+ * upstream failure to the downstream job (default), `run` runs the downstream
+ * job regardless of the upstream outcome. Single source of truth for this
+ * value across lock-file schemas and protocol messages.
+ */
+export declare const IfFailedPolicy: z.ZodEnum<{
+    run: "run";
+    skip: "skip";
+}>;
+export type IfFailedPolicy = z.infer<typeof IfFailedPolicy>;
 /**
  * Needs entry with per-edge failure policy.
  * Used in lock file needs arrays for explicit ifFailed override.
@@ -374,11 +390,59 @@ export type NeedsGroupEntry = z.infer<typeof NeedsGroupEntrySchema>;
  * Static job in lock file.
  * Contains all orchestrator-readable information for scheduling.
  */
+/** Normalized runsOnAll predicate: OR of AND-groups (include), minus exclude matchers. */
+export interface RunsOnAllPredicate {
+    /** OR across groups; AND within a group. */
+    readonly include: readonly (readonly LabelMatcher[])[];
+    /** Matchers that disqualify a host (AND-NOT, applied to the union). */
+    readonly exclude: readonly LabelMatcher[];
+}
+/** Author-facing input forms for runsOnAll (string | RegExp | array-with-! | structured). */
+export type RunsOnAllInput = string | RegExp | readonly (string | RegExp)[] | {
+    readonly include: readonly {
+        readonly all: readonly (string | RegExp)[];
+    }[];
+    readonly exclude?: readonly (string | RegExp)[];
+};
+/**
+ * Failure policy for a host fan-out (`runsOnAll`) when an expected durable host
+ * is in the declared roster but not currently reachable.
+ *
+ * - `skip`: omit the unreachable durable host (fan out to reachable hosts only).
+ * - `fail`: fail the run init if any expected durable host is unreachable.
+ * - `hold`: queue a pinned child for each unreachable durable host and wait for
+ *   it to (re)connect (the durable default).
+ *
+ * Ephemeral hosts that are not live are always skipped (a scaled-down node may
+ * never return), independent of this policy.
+ */
+export declare const OnUnreachableMode: z.ZodEnum<{
+    skip: "skip";
+    fail: "fail";
+    hold: "hold";
+}>;
+export type OnUnreachableMode = z.infer<typeof OnUnreachableMode>;
 export interface LockJob {
     readonly _type: 'static';
     readonly name: string;
-    readonly runsOn: string | readonly string[];
-    readonly excludeLabels?: readonly string[];
+    /** Single-agent targeting matchers. Absent when the job uses `runsOnAll` instead. */
+    readonly runsOn?: readonly LabelMatcher[];
+    readonly excludeLabels?: readonly LabelMatcher[];
+    /**
+     * 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.
+     */
+    readonly runsOnAll?: RunsOnAllPredicate;
+    /** Failure policy for unreachable durable hosts in a `runsOnAll` fan-out. */
+    readonly onUnreachable?: OnUnreachableMode;
+    /**
+     * Fan-out concurrency width (sliding window; `1` = serial). When set on a
+     * fan-out job (matrix or `runsOnAll`), only the first `maxParallel` children
+     * dispatch; the rest are held `wave_gated` and released one-per-terminal.
+     */
+    readonly maxParallel?: number;
+    /** Halt the fan-out on first child failure, skipping the held remainder. Default `false`. */
+    readonly failFast?: boolean;
     readonly needs: readonly (string | NeedsEntry | NeedsGroupEntry)[];
     /** Group names this job depends on (populated by compiler from dynamicGroup refs). */
     readonly dependsOnGroups?: readonly string[];
@@ -423,6 +487,15 @@ export interface LockDynamicJobFn {
     };
     /** Group name for cross-domain needs (set when dynamicJob('name', fn) is used). */
     readonly group?: string;
+    /**
+     * Declared upstream needs for a result-aware generator. When present the
+     * generator's eval job is deferred until these upstreams complete, then run
+     * with their frozen outputs available as ctx.needs. Same normalized shape as
+     * a static job's `needs`.
+     */
+    readonly needs?: readonly (string | NeedsEntry | NeedsGroupEntry)[];
+    /** True when this dynamic entry was authored as dynamicJob(group, { needs, generate }). */
+    readonly resultAware?: boolean;
 }
 /** Job or dynamic job generator */
 export type LockJobOrFactory = LockJob | LockDynamicJobFn;

package/dist/trigger/types.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 import { z } from "zod";
 //#region src/trigger/types.ts
 /**
@@ -14,20 +14,31 @@ import { z } from "zod";
 * 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 - increment on breaking changes */
-const SCHEMA_VERSION = 16;
+const SCHEMA_VERSION = 20;
 /** Type guard for inline expression values */
 function isLockInlineValue(value) {
 	return typeof value === "object" && value !== null && value._type === "inline";
 }
 /**
+* Per-edge failure policy for a `needs` dependency: `skip` propagates an
+* upstream failure to the downstream job (default), `run` runs the downstream
+* job regardless of the upstream outcome. Single source of truth for this
+* value across lock-file schemas and protocol messages.
+*/
+const IfFailedPolicy = z.enum(["skip", "run"]);
+/**
 * Needs entry with per-edge failure policy.
 * Used in lock file needs arrays for explicit ifFailed override.
 */
 const NeedsEntrySchema = z.object({
 	name: z.string(),
-	ifFailed: z.enum(["skip", "run"]).default("skip")
+	ifFailed: IfFailedPolicy.default(IfFailedPolicy.enum.skip)
 });
 /**
 * Needs group entry with per-edge failure policy.
@@ -35,8 +46,25 @@ const NeedsEntrySchema = z.object({
 */
 const NeedsGroupEntrySchema = z.object({
 	group: z.string(),
-	ifFailed: z.enum(["skip", "run"]).default("skip")
+	ifFailed: IfFailedPolicy.default(IfFailedPolicy.enum.skip)
 });
+/**
+* Failure policy for a host fan-out (`runsOnAll`) when an expected durable host
+* is in the declared roster but not currently reachable.
+*
+* - `skip`: omit the unreachable durable host (fan out to reachable hosts only).
+* - `fail`: fail the run init if any expected durable host is unreachable.
+* - `hold`: queue a pinned child for each unreachable durable host and wait for
+*   it to (re)connect (the durable default).
+*
+* Ephemeral hosts that are not live are always skipped (a scaled-down node may
+* never return), independent of this policy.
+*/
+const OnUnreachableMode = z.enum([
+	"skip",
+	"fail",
+	"hold"
+]);
 /** Type guard for static jobs */
 function isLockStaticJob(job) {
 	return job._type === "static";
@@ -46,6 +74,6 @@ function isLockDynamicJobFn(job) {
 	return job._type === "dynamic";
 }
 //#endregion
-export { NeedsEntrySchema, NeedsGroupEntrySchema, SCHEMA_VERSION, isLockDynamicJobFn, isLockInlineValue, isLockStaticJob };
+export { IfFailedPolicy, NeedsEntrySchema, NeedsGroupEntrySchema, OnUnreachableMode, SCHEMA_VERSION, isLockDynamicJobFn, isLockInlineValue, isLockStaticJob };
 
 //# sourceMappingURL=types.js.map

package/dist/webhook/signature.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 import { createHmac, timingSafeEqual } from "node:crypto";
 //#region src/webhook/signature.ts
 /**

package/dist/ws/close-codes.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 //#region src/ws/close-codes.ts
 /**
 * Unified WebSocket close codes for KiCI connections.

package/dist/ws/rate-limiter.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 //#region src/ws/rate-limiter.ts
 /**
 * WebSocket rate limiter with two-tier token bucket (messages + bytes).
@@ -18,6 +18,8 @@ import "../chunk-gOLHoazu.js";
 * When tokens are exhausted, returns a retryAfterMs estimate.
 */
 var TokenBucket = class {
+	capacity;
+	refillRate;
 	tokens;
 	lastRefill;
 	constructor(capacity, refillRate) {

package/dist/ws/ws-like.js

@@ -1,2 +1,2 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 export {};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/engine",
-  "version": "0.1.16",
+  "version": "0.1.18",
   "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",
@@ -49,6 +49,10 @@
       "import": "./dist/webhook/signature.js",
       "types": "./dist/webhook/signature.d.ts"
     },
+    "./labels/compile": {
+      "import": "./dist/labels/compile.js",
+      "types": "./dist/labels/compile.d.ts"
+    },
     "./protocol/dashboard-global-workflows": {
       "import": "./dist/protocol/dashboard-global-workflows.js",
       "types": "./dist/protocol/dashboard-global-workflows.d.ts"
@@ -65,10 +69,26 @@
       "import": "./dist/protocol/cluster-name.js",
       "types": "./dist/protocol/cluster-name.d.ts"
     },
+    "./protocol/messages/oidc-token-relay": {
+      "import": "./dist/protocol/messages/oidc-token-relay.js",
+      "types": "./dist/protocol/messages/oidc-token-relay.d.ts"
+    },
     "./provenance/schema": {
       "import": "./dist/provenance/schema.js",
       "types": "./dist/provenance/schema.d.ts"
     },
+    "./provenance/dsse": {
+      "import": "./dist/provenance/dsse.js",
+      "types": "./dist/provenance/dsse.d.ts"
+    },
+    "./provenance/bundle": {
+      "import": "./dist/provenance/bundle.js",
+      "types": "./dist/provenance/bundle.d.ts"
+    },
+    "./provenance/verify": {
+      "import": "./dist/provenance/verify.js",
+      "types": "./dist/provenance/verify.d.ts"
+    },
     "./metrics/catalog": {
       "import": "./dist/metrics/metric-catalog.generated.js",
       "types": "./dist/metrics/metric-catalog.generated.d.ts"
@@ -79,12 +99,15 @@
     }
   },
   "dependencies": {
+    "jose": "^6.1.0",
     "jsonpath-plus": "^10.4.0",
     "picomatch": "^4.0.4",
-    "zod": "^4.3.6"
+    "safe-regex": "^2.1.1",
+    "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@types/node": "^24.12.0"
+    "@types/node": "^24.12.0",
+    "@types/safe-regex": "^1.1.6"
   },
   "scripts": {
     "build": "node ../../scripts/build-ts.mjs && tsc --emitDeclarationOnly",

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/engine@0.1.16",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.1.16/33d50570-d86e-4a27-b1c9-26cef35a15c7",
+  "name": "@kici-dev/engine@0.1.18",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.1.18/fe01b1af-8e27-4bc2-a638-9b00ac77e671",
   "creationInfo": {
-    "created": "2026-06-12T09:41:34Z",
+    "created": "2026-06-17T10:55:42Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -54,7 +54,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.1.16",
+      "versionInfo": "0.1.18",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -65,12 +65,32 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.16"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.18"
         }
       ],
       "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.",
       "homepage": "https://kici.dev"
     },
+    {
+      "SPDXID": "SPDXRef-Package-jose-6.2.3",
+      "name": "jose",
+      "versionInfo": "6.2.3",
+      "downloadLocation": "https://registry.npmjs.org/jose/-/jose-6.2.3.tgz",
+      "filesAnalyzed": false,
+      "licenseConcluded": "NOASSERTION",
+      "licenseDeclared": "MIT",
+      "copyrightText": "NOASSERTION",
+      "supplier": "NOASSERTION",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:npm/jose@6.2.3"
+        }
+      ],
+      "description": "JWA, JWS, JWE, JWT, JWK, JWKS for Node.js, Browser, Cloudflare Workers, Deno, Bun, and other Web-interoperable runtimes",
+      "homepage": "https://github.com/panva/jose"
+    },
     {
       "SPDXID": "SPDXRef-Package-jsep-1.4.0",
       "name": "jsep",
@@ -132,10 +152,50 @@
       "homepage": "https://github.com/micromatch/picomatch"
     },
     {
-      "SPDXID": "SPDXRef-Package-zod-4.3.6",
+      "SPDXID": "SPDXRef-Package-regexp-tree-0.1.27",
+      "name": "regexp-tree",
+      "versionInfo": "0.1.27",
+      "downloadLocation": "https://registry.npmjs.org/regexp-tree/-/regexp-tree-0.1.27.tgz",
+      "filesAnalyzed": false,
+      "licenseConcluded": "NOASSERTION",
+      "licenseDeclared": "MIT",
+      "copyrightText": "NOASSERTION",
+      "supplier": "NOASSERTION",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:npm/regexp-tree@0.1.27"
+        }
+      ],
+      "description": "Regular Expressions parser in JavaScript",
+      "homepage": "https://github.com/DmitrySoshnikov/regexp-tree"
+    },
+    {
+      "SPDXID": "SPDXRef-Package-safe-regex-2.1.1",
+      "name": "safe-regex",
+      "versionInfo": "2.1.1",
+      "downloadLocation": "https://registry.npmjs.org/safe-regex/-/safe-regex-2.1.1.tgz",
+      "filesAnalyzed": false,
+      "licenseConcluded": "NOASSERTION",
+      "licenseDeclared": "MIT",
+      "copyrightText": "NOASSERTION",
+      "supplier": "NOASSERTION",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:npm/safe-regex@2.1.1"
+        }
+      ],
+      "description": "detect possibly catastrophic, exponential-time regular expressions",
+      "homepage": "https://github.com/davisjam/safe-regex"
+    },
+    {
+      "SPDXID": "SPDXRef-Package-zod-4.4.3",
       "name": "zod",
-      "versionInfo": "4.3.6",
-      "downloadLocation": "https://registry.npmjs.org/zod/-/zod-4.3.6.tgz",
+      "versionInfo": "4.4.3",
+      "downloadLocation": "https://registry.npmjs.org/zod/-/zod-4.4.3.tgz",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
       "licenseDeclared": "MIT",
@@ -145,7 +205,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/zod@4.3.6"
+          "referenceLocator": "pkg:npm/zod@4.4.3"
         }
       ],
       "description": "TypeScript-first schema declaration and validation library with static type inference",
@@ -168,6 +228,11 @@
       "relatedSpdxElement": "SPDXRef-Package-jsep-1.4.0",
       "relationshipType": "DEPENDS_ON"
     },
+    {
+      "spdxElementId": "SPDXRef-RootPackage",
+      "relatedSpdxElement": "SPDXRef-Package-jose-6.2.3",
+      "relationshipType": "DEPENDS_ON"
+    },
     {
       "spdxElementId": "SPDXRef-RootPackage",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
@@ -180,7 +245,12 @@
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package-zod-4.3.6",
+      "relatedSpdxElement": "SPDXRef-Package-safe-regex-2.1.1",
+      "relationshipType": "DEPENDS_ON"
+    },
+    {
+      "spdxElementId": "SPDXRef-RootPackage",
+      "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
@@ -197,6 +267,11 @@
       "spdxElementId": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relatedSpdxElement": "SPDXRef-Package-jsep-1.4.0",
       "relationshipType": "DEPENDS_ON"
+    },
+    {
+      "spdxElementId": "SPDXRef-Package-safe-regex-2.1.1",
+      "relatedSpdxElement": "SPDXRef-Package-regexp-tree-0.1.27",
+      "relationshipType": "DEPENDS_ON"
     }
   ]
 }

package/dist/protocol/messages/observe.js

@@ -1,70 +0,0 @@
-import "../../chunk-gOLHoazu.js";
-import { ExecutionRunStatus } from "./execution-status.js";
-import { z } from "zod";
-//#region src/protocol/messages/observe.ts
-/** Subscribe to observe a running test execution. */
-const observeSubscribeSchema = z.object({
-	type: z.literal("observe.subscribe"),
-	runId: z.string(),
-	token: z.string(),
-	lastSeenSequence: z.number().optional()
-});
-/** Run status update sent to observer. */
-const observeStatusSchema = z.object({
-	type: z.literal("observe.status"),
-	runId: z.string(),
-	status: ExecutionRunStatus,
-	jobName: z.string().optional(),
-	timestamp: z.number()
-});
-/** Log chunk sent to observer. */
-const observeLogSchema = z.object({
-	type: z.literal("observe.log"),
-	runId: z.string(),
-	jobId: z.string(),
-	jobName: z.string(),
-	stepIndex: z.number(),
-	stepName: z.string(),
-	lines: z.array(z.string()),
-	sequence: z.number(),
-	timestamp: z.number()
-});
-/** Step lifecycle event sent to observer. */
-const observeStepSchema = z.object({
-	type: z.literal("observe.step"),
-	runId: z.string(),
-	jobId: z.string(),
-	jobName: z.string(),
-	stepName: z.string(),
-	state: z.enum([
-		"pending",
-		"running",
-		"success",
-		"failed",
-		"skipped"
-	]),
-	durationMs: z.number().optional(),
-	timestamp: z.number()
-});
-/** Run completion summary sent to observer. */
-const observeCompleteSchema = z.object({
-	type: z.literal("observe.complete"),
-	runId: z.string(),
-	status: z.enum([
-		"success",
-		"failed",
-		"cancelled"
-	]),
-	summary: z.object({
-		totalDurationMs: z.number(),
-		jobs: z.array(z.object({
-			name: z.string(),
-			status: z.string(),
-			durationMs: z.number().optional()
-		}))
-	})
-});
-//#endregion
-export { observeCompleteSchema, observeLogSchema, observeStatusSchema, observeStepSchema, observeSubscribeSchema };
-
-//# sourceMappingURL=observe.js.map

package/dist/protocol/messages/test-run.js

@@ -1,52 +0,0 @@
-import "../../chunk-gOLHoazu.js";
-import { z } from "zod";
-//#region src/protocol/messages/test-run.ts
-/** Simulated event shape embedded in test trigger messages. */
-const testEventSchema = z.object({
-	type: z.string(),
-	action: z.string().optional(),
-	targetBranch: z.string(),
-	sourceBranch: z.string().optional(),
-	payload: z.record(z.string(), z.unknown()),
-	changedFiles: z.array(z.string()).optional()
-});
-/** Test trigger sent by CLI to orchestrator to initiate a test run. */
-const testTriggerSchema = z.object({
-	type: z.literal("test.trigger"),
-	messageId: z.string(),
-	fixtureId: z.string(),
-	event: testEventSchema,
-	uploadId: z.string().optional(),
-	routingKey: z.string(),
-	secrets: z.record(z.string(), z.string()).optional(),
-	workflowName: z.string().optional()
-});
-/** Test trigger response from orchestrator to CLI. */
-const testTriggerResponseSchema = z.object({
-	type: z.literal("test.trigger.response"),
-	messageId: z.string(),
-	runId: z.string(),
-	observeUrl: z.string(),
-	status: z.enum(["accepted", "rejected"]),
-	reason: z.string().optional()
-});
-/** Test cancel request sent by CLI to orchestrator. */
-const testCancelSchema = z.object({
-	type: z.literal("test.cancel"),
-	messageId: z.string(),
-	runId: z.string()
-});
-/** Test cancel response from orchestrator to CLI. */
-const testCancelResponseSchema = z.object({
-	type: z.literal("test.cancel.response"),
-	messageId: z.string(),
-	status: z.enum([
-		"cancelled",
-		"not_found",
-		"already_complete"
-	])
-});
-//#endregion
-export { testCancelResponseSchema, testCancelSchema, testEventSchema, testTriggerResponseSchema, testTriggerSchema };
-
-//# sourceMappingURL=test-run.js.map