@kici-dev/engine 0.1.27 → 0.3.0

package/dist/matrix/expand.js

@@ -1,10 +1,65 @@
 import "../rolldown-runtime-ClRpJifh.js";
 //#region src/matrix/expand.ts
 /**
+* Thrown when a matrix value does not match the documented contract — a
+* `string[]` or a `Record<string, string[]>`. A static matrix is guaranteed by
+* the lock-file schema, but a dynamic matrix returns arbitrary runtime data, so
+* the contract has to be enforced here rather than by the type system.
+*/
+var MatrixShapeError = class MatrixShapeError extends Error {
+	name = "MatrixShapeError";
+	constructor(message) {
+		super(message);
+		Object.setPrototypeOf(this, MatrixShapeError.prototype);
+	}
+};
+/** Describe a rejected value for an error message, without dumping it wholesale. */
+function describeValue(value) {
+	if (value === null) return "null";
+	if (value === void 0) return "undefined";
+	if (Array.isArray(value)) return "an array";
+	if (typeof value === "string") return `a string (${JSON.stringify(value)})`;
+	if (typeof value === "object") return "an object";
+	return `a ${typeof value}`;
+}
+/** Coerce one matrix element, rejecting anything that has no sensible string form. */
+function coerceElement(value, where) {
+	if (typeof value === "string") return value;
+	if (typeof value === "number" || typeof value === "boolean") return String(value);
+	throw new MatrixShapeError(`matrix ${where} must contain strings, got ${describeValue(value)}`);
+}
+/**
+* Validate and normalize a matrix value. Accepts the two documented shapes,
+* coercing numeric and boolean elements to strings (they already reach job
+* names as strings), and rejects everything else with the contract in the
+* message. Dimensions are sorted here so expansion stays deterministic.
+*/
+function normalizeMatrixInput(input) {
+	if (Array.isArray(input)) return {
+		kind: "array",
+		values: Array.from(input, (v, i) => coerceElement(v, `values[${i}]`))
+	};
+	if (input === null || typeof input !== "object") {
+		const suffix = typeof input === "string" ? " — a bare string is read as one dimension per character; split it into an array" : "";
+		throw new MatrixShapeError(`matrix must be a string array or an object of string arrays, got ${describeValue(input)}${suffix}`);
+	}
+	const dimensions = [];
+	for (const [name, values] of Object.entries(input)) {
+		if (!Array.isArray(values)) throw new MatrixShapeError(`matrix dimension "${name}" must be an array, got ${describeValue(values)}`);
+		dimensions.push([name, Array.from(values, (v, i) => coerceElement(v, `dimension "${name}"[${i}]`))]);
+	}
+	dimensions.sort((a, b) => a[0].localeCompare(b[0]));
+	return {
+		kind: "object",
+		dimensions
+	};
+}
+/**
 * Compute the cartesian product of the given value sets in row-major order.
 * An empty set list yields a single empty tuple; any empty set yields no tuples.
 */
 function cartesianProduct(sets) {
+	if (sets.some((set) => set.length === 0)) return [];
 	return sets.reduce((acc, set) => acc.flatMap((tuple) => set.map((value) => [...tuple, value])), [[]]);
 }
 /**
@@ -24,20 +79,54 @@ function expandMultiDimension(matrix) {
 	if (dimensions.length === 0) return [];
 	dimensions.sort((a, b) => a[0].localeCompare(b[0]));
 	const names = dimensions.map(([name]) => name);
-	return cartesianProduct(dimensions.map(([, values]) => values)).map((combo) => {
-		const result = {};
-		names.forEach((name, idx) => {
-			result[name] = combo[idx];
-		});
-		return result;
-	});
+	return cartesianProduct(dimensions.map(([, values]) => values)).map((combo) => Object.fromEntries(names.map((name, idx) => [name, combo[idx]])));
+}
+/**
+* Validated entry point: normalizes an untrusted matrix value, then dispatches
+* to single- or multi-dimensional expansion. {@link expandSingleDimension} and
+* {@link expandMultiDimension} remain available for a caller that already holds
+* a typed value; this is the one to use for anything crossing a runtime
+* boundary, such as the return value of a dynamic matrix function.
+*/
+function expandMatrix(input) {
+	const normalized = normalizeMatrixInput(input);
+	if (normalized.kind === "array") return expandSingleDimension(normalized.values);
+	return expandMultiDimension(Object.fromEntries(normalized.dimensions));
 }
 /**
-* Unified expand function that dispatches to single or multi-dimensional expansion.
+* How many combinations a matrix would expand to, computed WITHOUT building
+* them. Callers use this to refuse an oversized matrix before allocating it —
+* the product is checked, never materialized.
 */
-function expandMatrix(matrix) {
-	if (Array.isArray(matrix)) return expandSingleDimension(matrix);
-	return expandMultiDimension(matrix);
+function matrixCombinationCount(input) {
+	const normalized = normalizeMatrixInput(input);
+	if (normalized.kind === "array") return normalized.values.length;
+	if (normalized.dimensions.length === 0) return 0;
+	return normalized.dimensions.reduce((acc, [, values]) => acc * values.length, 1);
+}
+/** Stable identity for a combination: its key/value pairs, key-sorted. */
+function combinationKey(combo) {
+	return JSON.stringify(Object.entries(combo).filter(([, value]) => value !== void 0).sort((a, b) => a[0].localeCompare(b[0])));
+}
+/**
+* The first combination whose key collides with an earlier one, or `null` when
+* every combination is distinct.
+*
+* `keyOf` decides what "the same combination" means. Callers that own a job name
+* pass a renderer for the expanded name, because the collision that actually
+* hurts is two children sharing a name — they are indistinguishable to an
+* operator and ambiguous as a needs-edge target. Two structurally different
+* combinations can still render the same name, so name-keying is strictly
+* stronger than the structural default.
+*/
+function findDuplicateCombination(combos, keyOf = combinationKey) {
+	const seen = /* @__PURE__ */ new Set();
+	for (const combo of combos) {
+		const key = keyOf(combo);
+		if (seen.has(key)) return combo;
+		seen.add(key);
+	}
+	return null;
 }
 /**
 * Apply include/exclude modifications to expanded matrix combinations.
@@ -62,11 +151,11 @@ function applyIncludeExclude(expanded, include, exclude) {
 			const comboKeys = Object.keys(combo);
 			if (inclKeys.length !== comboKeys.length) return false;
 			return inclKeys.every((key) => combo[key] === incl[key]);
-		})) result.push(incl);
+		})) result.push(Object.fromEntries([...inclKeys].sort((a, b) => a.localeCompare(b)).map((key) => [key, incl[key]])));
 	}
 	return result;
 }
 //#endregion
-export { applyIncludeExclude, cartesianProduct, expandMatrix, expandMultiDimension, expandSingleDimension };
+export { MatrixShapeError, applyIncludeExclude, cartesianProduct, expandMatrix, expandMultiDimension, expandSingleDimension, findDuplicateCombination, matrixCombinationCount, normalizeMatrixInput };
 
 //# sourceMappingURL=expand.js.map

package/dist/matrix/format.d.ts

@@ -5,6 +5,11 @@ import type { MatrixValues } from './expand.js';
  * Multi-dimensional: "linux, 18"
  */
 export declare function formatMatrixSuffix(matrixValues: MatrixValues): string;
-/** Expanded child job name: `${baseName} (${suffix})`. MUST match the local executor. */
+/**
+ * Expanded child job name: `${baseName} (${suffix})`. The `(...)` wrapper is
+ * load-bearing, not decoration: `variantLabelOf` (fanout/materialize.ts) and
+ * `buildMatrixOutputsEnvelope` (the orchestrator's `byMatrix` key) both recover
+ * the suffix by slicing it back out of the name.
+ */
 export declare function formatExpandedJobName(baseName: string, matrixValues: MatrixValues): string;
 //# sourceMappingURL=format.d.ts.map

package/dist/matrix/format.js

@@ -10,7 +10,12 @@ function formatMatrixSuffix(matrixValues) {
 	if (defined.length === 1 && defined[0][0] === "value") return defined[0][1];
 	return defined.map(([, v]) => v).join(", ");
 }
-/** Expanded child job name: `${baseName} (${suffix})`. MUST match the local executor. */
+/**
+* Expanded child job name: `${baseName} (${suffix})`. The `(...)` wrapper is
+* load-bearing, not decoration: `variantLabelOf` (fanout/materialize.ts) and
+* `buildMatrixOutputsEnvelope` (the orchestrator's `byMatrix` key) both recover
+* the suffix by slicing it back out of the name.
+*/
 function formatExpandedJobName(baseName, matrixValues) {
 	return `${baseName} (${formatMatrixSuffix(matrixValues)})`;
 }

package/dist/mcp/held-run-resolve.d.ts

@@ -1,13 +1,3 @@
-/**
- * Shared held-run resolution for the `kici approve` / `kici reject` commands and
- * the developer MCP `approve_run` / `reject_run` tools.
- *
- * Both surfaces first list the pending holds for a run, then resolve the one
- * the caller named via `job` / `step` (or the sole pending hold when there is
- * exactly one and no filter is given). The resolution is a pure function so it
- * can be unit-tested without HTTP, and it stays import-free so it is safe to
- * re-export from the browser-facing engine barrel.
- */
 /** Hold scope, mirroring the engine `HoldScope` enum. */
 export type HeldRunScope = 'workflow' | 'job' | 'step';
 /** A pending-hold row as returned by the held-runs list. */
@@ -18,6 +8,13 @@ export interface HeldRunSummary {
     holdScope?: HeldRunScope;
     stepIndex?: number | null;
     status: string;
+    /**
+     * Persisted `held_runs.hold_type`, when the orchestrator's list response
+     * carried one. Optional and un-normalized: callers pass it through
+     * `normalizePersistedHoldType` before branching. Absent from an older
+     * orchestrator's response.
+     */
+    holdType?: string;
     /** Computed drift payload for a `when: 'drift'` step hold; absent otherwise. */
     payload?: {
         summaryMarkdown: string;

package/dist/mcp/held-run-resolve.js

@@ -1,6 +1,32 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { HeldRunStatus } from "../context/held-run-status.js";
 //#region src/mcp/held-run-resolve.ts
 /**
+* Shared held-run resolution for the `kici approve` / `kici reject` commands and
+* the developer MCP `approve_run` / `reject_run` tools.
+*
+* Both surfaces first list the pending holds for a run, then resolve the one
+* the caller named via `job` / `step` (or the sole pending hold when there is
+* exactly one and no filter is given). The resolution is a pure function so it
+* can be unit-tested without HTTP, and it imports nothing beyond the shared
+* held-run vocabulary, so it is safe to re-export from the browser-facing
+* engine barrel.
+*/
+/**
+* Name a hold the way the caller would type it: the literal `jobId` (so an
+* `__install__…` sentinel or an opaque legacy id is reproduced verbatim), with
+* the step index prefixed for a step-scoped hold.
+*/
+function describeHold(hold) {
+	const job = hold.jobId || "(unnamed hold)";
+	if (hold.holdScope === "step" && hold.stepIndex != null) return `step ${hold.stepIndex} of ${job}`;
+	return job;
+}
+/** The distinct hold descriptions, in listing order, for an error message. */
+function listCandidates(holds) {
+	return [...new Set(holds.map(describeHold))].join(", ");
+}
+/**
 * Resolve the held-run id matching the filter from a list of pending holds.
 *
 * - `step` requires `job` and matches a `step`-scoped hold whose step index
@@ -9,7 +35,7 @@ import "../rolldown-runtime-ClRpJifh.js";
 * - With no filter, the sole pending hold is used; ambiguity is an error.
 */
 function resolveHeldRunId(holds, filter) {
-	const pending = holds.filter((h) => h.status === "pending");
+	const pending = holds.filter((h) => h.status === HeldRunStatus.enum.pending);
 	if (pending.length === 0) return {
 		ok: false,
 		error: "No pending approval holds found for this run."
@@ -19,12 +45,12 @@ function resolveHeldRunId(holds, filter) {
 			ok: false,
 			error: "--step requires --job to identify the held step."
 		};
-		return pickSingle(pending.filter((h) => h.holdScope === "step" && h.jobId === filter.job && String(h.stepIndex ?? "") === filter.step), `step ${filter.step} of job '${filter.job}'`);
+		return pickSingle(pending.filter((h) => h.holdScope === "step" && h.jobId === filter.job && String(h.stepIndex ?? "") === filter.step), `step ${filter.step} of job '${filter.job}'`, pending);
 	}
-	if (filter.job !== void 0) return pickSingle(pending.filter((h) => h.jobId === filter.job && h.holdScope !== "step"), `job '${filter.job}'`);
+	if (filter.job !== void 0) return pickSingle(pending.filter((h) => h.jobId === filter.job && h.holdScope !== "step"), `job '${filter.job}'`, pending);
 	if (pending.length > 1) return {
 		ok: false,
-		error: "Multiple pending holds for this run. Use --job <name> (and --step <index>) to choose one."
+		error: `Multiple pending holds for this run. Use --job <name> (and --step <index>) to choose one. Candidates: ${listCandidates(pending)}.`
 	};
 	return {
 		ok: true,
@@ -32,14 +58,14 @@ function resolveHeldRunId(holds, filter) {
 		hold: pending[0]
 	};
 }
-function pickSingle(matches, label) {
+function pickSingle(matches, label, pending) {
 	if (matches.length === 0) return {
 		ok: false,
-		error: `No pending hold found for ${label}.`
+		error: `No pending hold found for ${label}. Pending holds: ${listCandidates(pending)}.`
 	};
 	if (matches.length > 1) return {
 		ok: false,
-		error: `Multiple pending holds match ${label}; cannot disambiguate.`
+		error: `Multiple pending holds match ${label}; cannot disambiguate. Candidates: ${listCandidates(matches)}.`
 	};
 	return {
 		ok: true,

package/dist/metrics/catalog-policy.js

@@ -259,10 +259,6 @@ const METRIC_LABEL_POLICY = {
 		"v8js.gc.type": { maxUniqueValues: 6 },
 		scaler: { values: AGENT_SCALER_VALUES }
 	},
-	"v8js.memory.heap.limit": {
-		"v8js.heap.space.name": { maxUniqueValues: 20 },
-		scaler: { values: AGENT_SCALER_VALUES }
-	},
 	"v8js.memory.heap.used": {
 		"v8js.heap.space.name": { maxUniqueValues: 20 },
 		scaler: { values: AGENT_SCALER_VALUES }
@@ -274,6 +270,10 @@ const METRIC_LABEL_POLICY = {
 	"v8js.memory.heap.space.physical_size": {
 		"v8js.heap.space.name": { maxUniqueValues: 20 },
 		scaler: { values: AGENT_SCALER_VALUES }
+	},
+	"v8js.resource.active": {
+		"v8js.resource.type": { maxUniqueValues: 20 },
+		scaler: { values: AGENT_SCALER_VALUES }
 	}
 };
 //#endregion