@kici-dev/engine 0.1.21 → 0.1.23

package/dist/trigger/types.js

@@ -1,4 +1,5 @@
 import "../chunk-BTugEXQM.js";
+import { ExecutionJobStatus, TERMINAL_JOB_STATES } from "../protocol/messages/execution-status.js";
 import { z } from "zod";
 //#region src/trigger/types.ts
 /**
@@ -18,35 +19,67 @@ import { z } from "zod";
 * 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 - increment on breaking changes */
-const SCHEMA_VERSION = 21;
+const SCHEMA_VERSION = 26;
 /** 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.
+* Author-facing keyword sugar for a `needs` edge's run condition. Each keyword
+* resolves (at compile time) to a set of upstream terminal statuses; the
+* downstream edge is dispatch-satisfied when the upstream's terminal status is
+* a member of that set.
 */
-const IfFailedPolicy = z.enum(["skip", "run"]);
+const NeedsWhen = z.enum([
+	"on-success",
+	"always",
+	"on-skip",
+	"on-failure"
+]);
+/**
+* Normalized, DB-evaluable run condition for a `needs` edge: the non-empty set
+* of upstream terminal statuses that satisfy the edge. The lock file and the
+* orchestrator scheduler only ever see this resolved set (never a keyword), so
+* gating stays a pure status-set membership test.
+*/
+const NeedsRunOn = z.array(ExecutionJobStatus).nonempty();
+const WHEN_TO_RUN_ON = {
+	"on-success": [ExecutionJobStatus.enum.success],
+	always: [...TERMINAL_JOB_STATES],
+	"on-skip": [ExecutionJobStatus.enum.success, ExecutionJobStatus.enum.skipped],
+	"on-failure": [ExecutionJobStatus.enum.failed, ExecutionJobStatus.enum.timed_out_stale]
+};
 /**
-* Needs entry with per-edge failure policy.
-* Used in lock file needs arrays for explicit ifFailed override.
+* 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.
+*/
+function resolveWhenToRunOn(when) {
+	if (when === void 0) return [ExecutionJobStatus.enum.success];
+	if (Array.isArray(when)) return when;
+	return WHEN_TO_RUN_ON[when];
+}
+/**
+* Needs entry carrying the normalized run-on status-set.
+* Used in lock file needs arrays for an explicit per-edge run condition.
 */
 const NeedsEntrySchema = z.object({
 	name: z.string(),
-	ifFailed: IfFailedPolicy.default(IfFailedPolicy.enum.skip)
+	runOn: NeedsRunOn.default([ExecutionJobStatus.enum.success])
 });
 /**
-* Needs group entry with per-edge failure policy.
+* Needs group entry carrying the normalized run-on status-set.
 * Used in lock file needs arrays for dynamic group dependencies.
 */
 const NeedsGroupEntrySchema = z.object({
 	group: z.string(),
-	ifFailed: IfFailedPolicy.default(IfFailedPolicy.enum.skip)
+	runOn: NeedsRunOn.default([ExecutionJobStatus.enum.success])
 });
 /**
 * Failure policy for a host fan-out (`runsOnAll`) when an expected durable host
@@ -65,6 +98,14 @@ const OnUnreachableMode = z.enum([
 	"fail",
 	"hold"
 ]);
+/**
+* Single-agent selection policy when multiple agents match a `runsOn` selector.
+*
+* - `deterministic` (default): sort matching candidates by `agentId` and pick the
+*   lowest, so a run-once-on-one-host job is reproducible across re-runs.
+* - `any`: pick any available agent (load spread).
+*/
+const RunsOnPick = z.enum(["deterministic", "any"]);
 /** Type guard for static jobs */
 function isLockStaticJob(job) {
 	return job._type === "static";
@@ -74,6 +115,6 @@ function isLockDynamicJobFn(job) {
 	return job._type === "dynamic";
 }
 //#endregion
-export { IfFailedPolicy, NeedsEntrySchema, NeedsGroupEntrySchema, OnUnreachableMode, SCHEMA_VERSION, isLockDynamicJobFn, isLockInlineValue, isLockStaticJob };
+export { NeedsEntrySchema, NeedsGroupEntrySchema, NeedsRunOn, NeedsWhen, OnUnreachableMode, RunsOnPick, SCHEMA_VERSION, isLockDynamicJobFn, isLockInlineValue, isLockStaticJob, resolveWhenToRunOn };
 
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/engine",
-  "version": "0.1.21",
+  "version": "0.1.23",
   "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",
@@ -53,6 +53,14 @@
       "import": "./dist/labels/compile.js",
       "types": "./dist/labels/compile.d.ts"
     },
+    "./environment/host-match": {
+      "import": "./dist/environment/host-match.js",
+      "types": "./dist/environment/host-match.d.ts"
+    },
+    "./environment/scope-template": {
+      "import": "./dist/environment/scope-template.js",
+      "types": "./dist/environment/scope-template.d.ts"
+    },
     "./protocol/dashboard-global-workflows": {
       "import": "./dist/protocol/dashboard-global-workflows.js",
       "types": "./dist/protocol/dashboard-global-workflows.d.ts"

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.21",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.1.21/e80a4720-81f4-4549-ae95-80ee7a5c127e",
+  "name": "@kici-dev/engine@0.1.23",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fengine/0.1.23/8d393c8b-11ae-4191-987e-130f8fca7033",
   "creationInfo": {
-    "created": "2026-06-23T05:10:06Z",
+    "created": "2026-06-25T11:12:41Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -54,7 +54,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.1.21",
+      "versionInfo": "0.1.23",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -65,7 +65,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.21"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.1.23"
         }
       ],
       "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.",