@kici-dev/sdk 0.1.16 → 0.1.18

package/dist/api-types.d.ts

@@ -8,6 +8,8 @@
  * 1. Add the typed method here (with param + return types)
  * 2. Register the handler in the orchestrator's AgentApiRegistry
  */
+import { type OidcTokenResult } from '@kici-dev/engine/protocol/messages/oidc-token-relay';
+export type { OidcTokenResult };
 export interface InfrastructureListResult {
     scalers: Array<{
         name: string;
@@ -28,9 +30,23 @@ export interface InfrastructureApi {
     /** List available scalers and connected agents. */
     list(): Promise<InfrastructureListResult>;
 }
+export interface OidcApi {
+    /**
+     * Request a short-lived OIDC ID token for the current job, bound to
+     * `audience`. The token's identity claims (repository, ref, sha, run/job id)
+     * are derived server-side from the build context and cannot be spoofed by the
+     * workflow. The token is automatically masked in step logs. Only available
+     * inside a running job step (throws otherwise).
+     */
+    token(opts: {
+        audience: string;
+    }): Promise<OidcTokenResult>;
+}
 export interface KiciApi {
     /** Query orchestrator infrastructure (scalers, agents). */
     infrastructure: InfrastructureApi;
+    /** Request short-lived OIDC ID tokens for the current job (build provenance). */
+    oidc: OidcApi;
 }
 /**
  * Low-level transport function used to implement KiciApi.
@@ -42,6 +58,14 @@ export type KiciApiTransport = (method: string, params?: Record<string, unknown>
  *
  * This is the bridge between the typed SDK interface and the untyped WS/IPC
  * transport. Each method call is mapped to { method: 'namespace.method', params }.
+ *
+ * `jobCtx` carries the per-job execution context (the job the step is running
+ * in). It is supplied by the agent's sandbox step context so `oidc.token()` can
+ * bind its request to that job; the workflow author never supplies it. It is
+ * omitted for contexts with no running job (e.g. DynamicJobFn re-evaluation),
+ * where `oidc.token()` throws rather than silently misattributing a token.
  */
-export declare function buildKiciApi(transport: KiciApiTransport): KiciApi;
+export declare function buildKiciApi(transport: KiciApiTransport, jobCtx?: {
+    jobId: string;
+}): KiciApi;
 //# sourceMappingURL=api-types.d.ts.map

package/dist/api-types.js

@@ -1,13 +1,39 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
+import { OIDC_TOKEN_REQUEST_METHOD } from "@kici-dev/engine/protocol/messages/oidc-token-relay";
 //#region src/api-types.ts
 /**
+* Typed KiCI API available to workflows via ctx.kici.
+*
+* Each namespace groups related methods. Under the hood, calls are serialized
+* to { method: 'namespace.method', params } and sent over the agent's WS
+* connection to the orchestrator. Adding a new API method:
+*
+* 1. Add the typed method here (with param + return types)
+* 2. Register the handler in the orchestrator's AgentApiRegistry
+*/
+/**
 * Build a typed KiciApi proxy from a raw transport function.
 *
 * This is the bridge between the typed SDK interface and the untyped WS/IPC
 * transport. Each method call is mapped to { method: 'namespace.method', params }.
+*
+* `jobCtx` carries the per-job execution context (the job the step is running
+* in). It is supplied by the agent's sandbox step context so `oidc.token()` can
+* bind its request to that job; the workflow author never supplies it. It is
+* omitted for contexts with no running job (e.g. DynamicJobFn re-evaluation),
+* where `oidc.token()` throws rather than silently misattributing a token.
 */
-function buildKiciApi(transport) {
-	return { infrastructure: { list: () => transport("infrastructure.list", {}) } };
+function buildKiciApi(transport, jobCtx) {
+	return {
+		infrastructure: { list: () => transport("infrastructure.list", {}) },
+		oidc: { token: (opts) => {
+			if (!jobCtx) return Promise.reject(/* @__PURE__ */ new Error("ctx.kici.oidc.token() is only available inside a running job step"));
+			return transport(OIDC_TOKEN_REQUEST_METHOD, {
+				jobId: jobCtx.jobId,
+				audience: opts.audience
+			});
+		} }
+	};
 }
 //#endregion
 export { buildKiciApi };

package/dist/approval.js

@@ -1,4 +1,4 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 //#region src/approval.ts
 /** Normalize any `RequireApproval` form into `{ clauses, reason?, timeoutSeconds? }`. */
 function normalizeRequireApproval(r) {

package/dist/cache-types.js

@@ -1,4 +1,4 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 import { z } from "zod";
 //#region src/cache-types.ts
 /** Zod schema validating a CacheSpec at compile/serialize time. */

package/dist/context.d.ts

@@ -19,6 +19,52 @@ export interface JobInfo {
     name: string;
     runsOn: string;
 }
+/**
+ * Facts about the agent a `runsOnAll` host-fanout child is pinned to, exposed
+ * as `ctx.agent`. Present only for jobs that use `runsOnAll`.
+ */
+export interface AgentInfo {
+    /** Hostname of the agent. */
+    host: string;
+    /** The agent's label set. */
+    labels: readonly string[];
+    /** Operating-system platform (os.platform()). */
+    platform?: string;
+    /** CPU architecture (os.arch()). */
+    arch?: string;
+}
+/**
+ * Outputs of a matrix job as seen by a downstream `needs:` consumer.
+ * A downstream that consumes a matrix upstream receives this envelope instead of
+ * a flat outputs object, identically under `kici run local` and the remote path.
+ */
+export interface MatrixJobOutputs<T = Record<string, unknown>> {
+    /** Keyed by the combination suffix (the text inside `(...)` of the child name). */
+    byMatrix: Record<string, T>;
+    /** Last-write-wins flat merge across children, in child (name) order. */
+    merged: T;
+}
+/** Runtime discriminator: true when `ctx.jobOutputs(ref)` returned a matrix envelope. */
+export declare function isMatrixJobOutputs(value: Record<string, unknown> | MatrixJobOutputs | HostJobOutputs): value is MatrixJobOutputs;
+/**
+ * Outputs of a `runsOnAll` host-fanout job as seen by a downstream `needs:`
+ * consumer. Keyed by hostname. Unlike {@link MatrixJobOutputs}, the summary does
+ * NOT collapse to a last-write-wins scalar (a fleet footgun): `summary.outputs`
+ * is an array view across hosts, and `succeededHosts`/`failedHosts` name the
+ * per-host outcome.
+ */
+export interface HostJobOutputs<T = Record<string, unknown>> {
+    /** Keyed by hostname. */
+    byHost: Record<string, T>;
+    summary: {
+        succeededHosts: string[];
+        failedHosts: string[];
+        /** Per output key, every host's value (array view; never a collapsing scalar). */
+        outputs: Record<string, unknown[]>;
+    };
+}
+/** Runtime discriminator: true when `ctx.jobOutputs(ref)` returned a host envelope. */
+export declare function isHostJobOutputs(value: Record<string, unknown> | MatrixJobOutputs | HostJobOutputs): value is HostJobOutputs;
 /**
  * Augmentable interface for known secret keys.
  * When augmented via `kici types` (.d.ts generation), narrows get/expose key parameter.
@@ -80,6 +126,17 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * - Undefined for jobs without matrix configuration
      */
     matrix?: MatrixValues;
+    /**
+     * Hostname of the agent this job instance is running on.
+     * Set only for jobs that use `runsOnAll` (host fan-out — one pinned execution
+     * per matching host). Undefined for jobs without host fan-out.
+     */
+    host?: string;
+    /**
+     * Facts about the agent this job instance is pinned to (hostname, labels,
+     * platform, arch). Set only for jobs that use `runsOnAll`. Undefined otherwise.
+     */
+    agent?: AgentInfo;
     /**
      * Raw webhook payload from the git provider.
      * Contains the full, unmodified payload as received from the webhook.
@@ -158,14 +215,22 @@ export interface StepContext<TInputs = Record<string, unknown>> {
     } | ((...args: any[]) => any)): T;
     /**
      * Resolve outputs from a preceding job by reference.
-     * Returns the job's collected outputs (step-keyed for multi-step, flat for run shorthand).
+     *
+     * For a plain upstream this returns the job's collected outputs (step-keyed
+     * for multi-step, flat for run shorthand). For a **matrix** upstream it returns
+     * a {@link MatrixJobOutputs} envelope `{ byMatrix, merged }` keyed by the
+     * combination suffix — identical under `kici run local` and the remote path.
+     * Use {@link isMatrixJobOutputs} (or `'byMatrix' in result`) to discriminate.
      *
      * @example
      * const setupOutputs = ctx.jobOutputs(setupJob);
+     * @example
+     * const m = ctx.jobOutputs(buildMatrixJob);
+     * if (isMatrixJobOutputs(m)) console.log(m.byMatrix['linux, arm64']);
      */
     jobOutputs(ref: {
         name: string;
-    }): Record<string, unknown>;
+    }): Record<string, unknown> | MatrixJobOutputs | HostJobOutputs;
     /**
      * Publish a secret output value from this job.
      * Secret outputs are encrypted before leaving the agent and can be consumed
@@ -188,6 +253,14 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      * under `spec.key` (immutable — first save wins). Scoped per org + ref.
      */
     cache: import('./cache-types.js').CacheApi;
+    /**
+     * Build, sign, and persist a KiCI build-provenance attestation for a produced
+     * artifact. The in-toto statement's identity is derived from a Platform-minted
+     * identity token (unforgeable); the bundle is signed with an ephemeral key and
+     * is offline-verifiable. Pass the artifact via a precomputed digest or a path
+     * the agent digests with SHA-256.
+     */
+    attestProvenance(opts: import('./provenance-types.js').AttestProvenanceOptions): Promise<import('./provenance-types.js').AttestProvenanceResult>;
 }
 export {};
 //# sourceMappingURL=context.d.ts.map

package/dist/context.js

@@ -1,2 +1,14 @@
-import "./chunk-gOLHoazu.js";
-export {};
+import "./chunk-BTugEXQM.js";
+//#region src/context.ts
+/** Runtime discriminator: true when `ctx.jobOutputs(ref)` returned a matrix envelope. */
+function isMatrixJobOutputs(value) {
+	return typeof value === "object" && value !== null && "byMatrix" in value && "merged" in value && typeof value.byMatrix === "object";
+}
+/** Runtime discriminator: true when `ctx.jobOutputs(ref)` returned a host envelope. */
+function isHostJobOutputs(value) {
+	return typeof value === "object" && value !== null && "byHost" in value && "summary" in value && typeof value.byHost === "object";
+}
+//#endregion
+export { isHostJobOutputs, isMatrixJobOutputs };
+
+//# sourceMappingURL=context.js.map

package/dist/dynamic-group.js

@@ -1,4 +1,4 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 //#region src/dynamic-group.ts
 /**
 * Dynamic group helpers for cross-domain needs.

package/dist/errors.js

@@ -1,9 +1,11 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 //#region src/errors.ts
 /**
 * Thrown when accessing a secret key that does not exist in the flat secrets proxy.
 */
 var SecretNotFoundError = class extends Error {
+	key;
+	availableKeys;
 	constructor(key, availableKeys) {
 		super(`Secret "${key}" not found. Available keys: ${availableKeys.join(", ") || "(none)"}. Use ctx.secrets.has('${key}') to check existence, or await ctx.secrets.get('${key}') in a try/catch.`);
 		this.key = key;

package/dist/events/define-event.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 //#region src/events/define-event.ts
 /**
 * Create a typed event definition with a Zod schema.

package/dist/events/event-payloads.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 //#region src/events/event-payloads.ts
 /**
 * Narrow an EventPayload to a specific event type.

package/dist/events/event-payloads.test-d.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 import { describe, expectTypeOf, it } from "vitest";
 //#region src/events/event-payloads.test-d.ts
 describe("EventPayload narrowing", () => {

package/dist/events/index.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 import { isEventType } from "./event-payloads.js";
 import { defineEvent } from "./define-event.js";
 export { defineEvent, isEventType };

package/dist/events/types.js

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

package/dist/fixture.js

@@ -1,4 +1,4 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 //#region src/fixture.ts
 /**
 * Create a test fixture definition.

package/dist/hooks/index.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 //#region src/hooks/index.ts
 /**
 * Normalize HookInput to extract run function and optional timeout.

package/dist/hooks/types.js

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

package/dist/idempotent.js

@@ -1,4 +1,4 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 import { step } from "./step.js";
 import { runIdempotentStep } from "@kici-dev/core/idempotency";
 //#region src/idempotent.ts

package/dist/index.d.ts

@@ -13,21 +13,26 @@ export { isEventType } from './rules/index.js';
 export type { Rule, RuleContext, RuleCheckFn, RuleResult, EventPayload, RuleEvaluationResult, EventBase, PullRequestEventPayload, PushEventPayload, TagEventPayload, CommentEventPayload, ReviewEventPayload, ReviewCommentEventPayload, ReleaseEventPayload, DispatchEventPayload, CreateEventPayload, DeleteEventPayload, StatusEventPayload, WorkflowRunEventPayload, ForkEventPayload, StarEventPayload, WatchEventPayload, WebhookEventPayload, KiciEventPayload, WorkflowCompleteEventPayload, JobCompleteEventPayload, GenericWebhookEventPayload, ScheduleEventPayload, LifecycleEventPayload, GitHubRepository, GitHubUser, GitHubPullRequest, GitHubCommit, GitHubComment, GitHubReview, GitHubRelease, } from './rules/index.js';
 export { validateDag } from './validation/index.js';
 export type { DagNode, DagValidationResult } from './validation/index.js';
-export type { SourceLocation, OutputProxy, Step, StepOptions, StepRunFn, BareStepFn, StepInput, OutputSchema, InferOutputs, Job, JobOptions, GenericInitConfig, ContainerConfig, RunsOnSelector, RunsOn, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
-export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, DYNAMIC_JOB_GROUP_TAG } from './types.js';
-export type { TaggedDynamicJobFn } from './types.js';
+export type { SourceLocation, OutputProxy, Step, StepOptions, StepRunFn, BareStepFn, StepInput, OutputSchema, InferOutputs, Job, JobOptions, GenericInitConfig, MiseInitConfig, InitPreset, InitItem, InitConfig, ContainerConfig, RunsOnSelector, RunsOn, Workflow, WorkflowOptions, Registry, Trigger, DynamicJobFn, DynamicJobContext, JobOrFactory, } from './types.js';
+export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, } from './types.js';
+export type { TaggedDynamicJobFn, ResultAwareDynamicJobConfig, ResultAwareDynamicJobFn, DynamicJobNeed, } from './types.js';
+export { buildNeedsContext } from './needs-context.js';
+export type { UpstreamSnapshot, NeedsContext, NeedEntry, GroupNeedEntry } from './needs-context.js';
 export { CacheSpecSchema, normalizeCacheSpecs } from './cache-types.js';
 export type { CacheSpec, CacheInput } from './cache-types.js';
 export type { CacheRestoreResult, CacheApi } from './cache-types.js';
+export { provenanceSubjectIsPath } from './provenance-types.js';
+export type { AttestProvenanceOptions, AttestProvenanceResult, ProvenanceSubjectInput, } from './provenance-types.js';
 export { dynamicGroup, isDynamicGroupRef, DYNAMIC_GROUP_TAG } from './dynamic-group.js';
 export type { DynamicGroupRef } from './dynamic-group.js';
-export type { StepContext, Logger, WorkflowInfo, JobInfo, RepoInfo, StepSecretsTyped, KnownSecretKeys, } from './context.js';
+export type { StepContext, Logger, WorkflowInfo, JobInfo, AgentInfo, MatrixJobOutputs, HostJobOutputs, RepoInfo, StepSecretsTyped, KnownSecretKeys, } from './context.js';
+export { isMatrixJobOutputs, isHostJobOutputs } from './context.js';
 export { buildKiciApi } from './api-types.js';
 export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, } from './api-types.js';
 export { SecretNotFoundError } from './errors.js';
 export { createStepSecrets } from './secrets.js';
 export type { StepSecrets, TrackedStepSecrets, SecretMeta, SecretFileOptions, MountedFile, StepSecretsFileHost, StepSecretsFileWiring, StepSecretsHandle, StepSecretMountKind, StepSecretMountRecord, } from './secrets.js';
-export { createStepOutputProxy, createJobOutputProxy, resolveStepOutputs, resolveJobOutputs, setStepOutputsMap, setJobOutputsMap, setStepRefMap, getStepOutputsMap, getJobOutputsMap, getStepRefMap, } from './outputs.js';
+export { createStepOutputProxy, createJobOutputProxy, createSnapshotOutputProxy, resolveStepOutputs, resolveJobOutputs, setStepOutputsMap, setJobOutputsMap, setStepRefMap, getStepOutputsMap, getJobOutputsMap, getStepRefMap, } from './outputs.js';
 export type { OutputsMap, StepRefMap } from './outputs.js';
 export type { StaticMatrixArray, StaticMatrixObject, DynamicMatrixFn, DynamicMatrixContext, Matrix, MatrixInclude, MatrixExclude, MatrixValues, } from './matrix/index.js';
 export { isStaticArray, isStaticObject, isDynamicFunction } from './matrix/index.js';

package/dist/index.js

@@ -1,11 +1,12 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 import { buildKiciApi } from "./api-types.js";
 import { normalizeRequireApproval } from "./approval.js";
 import { CacheSpecSchema, normalizeCacheSpecs } from "./cache-types.js";
+import { isHostJobOutputs, isMatrixJobOutputs } from "./context.js";
 import { DYNAMIC_GROUP_TAG, dynamicGroup, isDynamicGroupRef } from "./dynamic-group.js";
 import { SecretNotFoundError } from "./errors.js";
 import { fixture } from "./fixture.js";
-import { createJobOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "./outputs.js";
+import { createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "./outputs.js";
 import { step } from "./step.js";
 import { idempotent, idempotentStep } from "./idempotent.js";
 import { job } from "./job.js";
@@ -40,7 +41,9 @@ import { isEventType } from "./events/event-payloads.js";
 import "./rules/index.js";
 import { validateDag } from "./validation/dag.js";
 import "./validation/index.js";
-import { DYNAMIC_JOB_GROUP_TAG, dynamicJob, getDynamicJobGroup, isDynamicJobFn } from "./types.js";
+import { DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, isDynamicJobFn } from "./types.js";
+import { buildNeedsContext } from "./needs-context.js";
+import { provenanceSubjectIsPath } from "./provenance-types.js";
 import { createStepSecrets } from "./secrets.js";
 import { isDynamicFunction, isStaticArray, isStaticObject } from "./matrix/types.js";
 import { applyIncludeExclude, expandMatrix } from "./matrix/expand.js";
@@ -49,4 +52,4 @@ import { defineEvent } from "./events/define-event.js";
 import "./events/index.js";
 import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
 import { z } from "zod";
-export { CacheSpecSchema, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, cleanup, comment, create, createJobOutputProxy, createStepOutputProxy, createStepSecrets, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, fork, genericWebhook, getDynamicJobGroup, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeCacheSpecs, normalizeRequireApproval, onCancel, onFailure, onSuccess, pr, push, release, resolveJobOutputs, resolveStepOutputs, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };
+export { CacheSpecSchema, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, applyIncludeExclude, beforeStep, buildKiciApi, buildNeedsContext, cleanup, comment, create, createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventType, isHostJobOutputs, isMatrixJobOutputs, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeCacheSpecs, normalizeRequireApproval, onCancel, onFailure, onSuccess, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, z };

package/dist/job.js

@@ -1,15 +1,22 @@
-import "./chunk-gOLHoazu.js";
+import "./chunk-BTugEXQM.js";
 import { createJobOutputProxy } from "./outputs.js";
 import { randomUUID } from "node:crypto";
 //#region src/job.ts
+/** A typed preset is a `'mise'` string or a `{ mise }` object — neither carries `run`. */
+function isPreset(item) {
+	return item === "mise" || typeof item === "object" && item !== null && "mise" in item;
+}
 /**
-* Validate a job's `init` config. `undefined` / `false` are no-ops; every
-* remaining spec (one, or each element of an array) must carry a non-empty
-* `run` command. Throws with the offending index when validation fails.
+* Validate a job's `init` config. `undefined` / `false` / `'auto'` are no-ops;
+* typed presets (`'mise'` / `{ mise }`) carry no `run`, so they need no check.
+* Every remaining generic spec (one, or each element of an array) must carry a
+* non-empty `run` command. Throws with the offending index when validation fails.
 */
 function validateInit(init, jobName) {
-	if (init === void 0 || init === false) return;
-	(Array.isArray(init) ? init : [init]).forEach((spec, i) => {
+	if (init === void 0 || init === false || init === "auto") return;
+	(Array.isArray(init) ? init : [init]).forEach((item, i) => {
+		if (isPreset(item)) return;
+		const spec = item;
 		if (typeof spec.run !== "string" || spec.run.trim().length === 0) throw new Error(`job('${jobName}'): init[${i}].run must be a non-empty command`);
 	});
 }
@@ -25,10 +32,17 @@ function job(nameOrOptions, maybeOptions) {
 		steps = [options.run];
 	}
 	validateInit(options.init, name);
+	if (options.runsOn !== void 0 && options.runsOnAll !== void 0) throw new Error(`job('${name}'): runsOn and runsOnAll are mutually exclusive`);
+	if (options.runsOn === void 0 && options.runsOnAll === void 0) throw new Error(`job('${name}'): one of runsOn or runsOnAll is required`);
+	if (options.onUnreachable !== void 0 && options.runsOnAll === void 0) console.warn(`[kici] job('${name}'): onUnreachable is ignored without runsOnAll`);
 	return {
 		_tag: "Job",
 		name,
-		runsOn: options.runsOn,
+		...options.runsOn !== void 0 && { runsOn: options.runsOn },
+		...options.runsOnAll !== void 0 && { runsOnAll: options.runsOnAll },
+		...options.onUnreachable !== void 0 && { onUnreachable: options.onUnreachable },
+		...options.maxParallel !== void 0 && { maxParallel: options.maxParallel },
+		...options.failFast !== void 0 && { failFast: options.failFast },
 		steps,
 		needs: options.needs,
 		rules: options.rules,

package/dist/matrix/expand.d.ts

@@ -1,25 +1,2 @@
-import type { StaticMatrixArray, StaticMatrixObject, MatrixInclude, MatrixExclude, MatrixValues } from './types.js';
-/**
- * Expand single-dimension matrix (array form) to MatrixValues array.
- * Each value becomes {value: string}.
- */
-export declare function expandSingleDimension(matrix: StaticMatrixArray): MatrixValues[];
-/**
- * Expand multi-dimensional matrix (object form) to MatrixValues array.
- * Uses fast-cartesian to compute cartesian product of all dimensions.
- * Dimension names are sorted for deterministic output.
- */
-export declare function expandMultiDimension(matrix: StaticMatrixObject): MatrixValues[];
-/**
- * Unified expand function that dispatches to single or multi-dimensional expansion.
- */
-export declare function expandMatrix(matrix: StaticMatrixArray | StaticMatrixObject): MatrixValues[];
-/**
- * Apply include/exclude modifications to expanded matrix combinations.
- * Per CONTEXT.md: exclude first (remove matching), then include (add new).
- *
- * Exclude matches if ALL specified dimensions match.
- * Include adds new combinations if they don't already exist.
- */
-export declare function applyIncludeExclude(expanded: MatrixValues[], include?: MatrixInclude[], exclude?: MatrixExclude[]): MatrixValues[];
+export { expandSingleDimension, expandMultiDimension, expandMatrix, applyIncludeExclude, } from '@kici-dev/engine';
 //# sourceMappingURL=expand.d.ts.map

package/dist/matrix/expand.js

@@ -1,66 +1,3 @@
-import "../chunk-gOLHoazu.js";
-import fastCartesian from "fast-cartesian";
-//#region src/matrix/expand.ts
-/**
-* Expand single-dimension matrix (array form) to MatrixValues array.
-* Each value becomes {value: string}.
-*/
-function expandSingleDimension(matrix) {
-	return matrix.map((value) => ({ value }));
-}
-/**
-* Expand multi-dimensional matrix (object form) to MatrixValues array.
-* Uses fast-cartesian to compute cartesian product of all dimensions.
-* Dimension names are sorted for deterministic output.
-*/
-function expandMultiDimension(matrix) {
-	const dimensions = Object.entries(matrix);
-	if (dimensions.length === 0) return [];
-	dimensions.sort((a, b) => a[0].localeCompare(b[0]));
-	const names = dimensions.map(([name]) => name);
-	return fastCartesian(dimensions.map(([, values]) => values)).map((combo) => {
-		const result = {};
-		names.forEach((name, idx) => {
-			result[name] = combo[idx];
-		});
-		return result;
-	});
-}
-/**
-* Unified expand function that dispatches to single or multi-dimensional expansion.
-*/
-function expandMatrix(matrix) {
-	if (Array.isArray(matrix)) return expandSingleDimension(matrix);
-	return expandMultiDimension(matrix);
-}
-/**
-* Apply include/exclude modifications to expanded matrix combinations.
-* Per CONTEXT.md: exclude first (remove matching), then include (add new).
-*
-* Exclude matches if ALL specified dimensions match.
-* Include adds new combinations if they don't already exist.
-*/
-function applyIncludeExclude(expanded, include, exclude) {
-	let result = [...expanded];
-	if (exclude && exclude.length > 0) result = result.filter((combo) => {
-		return !exclude.some((excl) => {
-			const exclEntries = Object.entries(excl);
-			if (exclEntries.length === 0) return false;
-			return exclEntries.every(([key, value]) => combo[key] === value);
-		});
-	});
-	if (include && include.length > 0) for (const incl of include) {
-		const inclKeys = Object.keys(incl);
-		if (inclKeys.length === 0) continue;
-		if (!result.some((combo) => {
-			const comboKeys = Object.keys(combo);
-			if (inclKeys.length !== comboKeys.length) return false;
-			return inclKeys.every((key) => combo[key] === incl[key]);
-		})) result.push(incl);
-	}
-	return result;
-}
-//#endregion
+import "../chunk-BTugEXQM.js";
+import { applyIncludeExclude, expandMatrix, expandMultiDimension, expandSingleDimension } from "@kici-dev/engine";
 export { applyIncludeExclude, expandMatrix, expandMultiDimension, expandSingleDimension };
-
-//# sourceMappingURL=expand.js.map

package/dist/matrix/index.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 import { isDynamicFunction, isStaticArray, isStaticObject } from "./types.js";
 import { applyIncludeExclude, expandMatrix } from "./expand.js";
 export { applyIncludeExclude, expandMatrix, isDynamicFunction, isStaticArray, isStaticObject };

package/dist/matrix/types.d.ts

@@ -1,9 +1,7 @@
 import type { $ as Shell } from 'zx';
 import type { Logger } from '../context.js';
-/** Single-dimension static matrix: array of values */
-export type StaticMatrixArray = string[];
-/** Multi-dimensional static matrix: named dimensions with values */
-export type StaticMatrixObject = Record<string, string[]>;
+export type { StaticMatrixArray, StaticMatrixObject, MatrixInclude, MatrixExclude, MatrixValues, } from '@kici-dev/engine';
+import type { StaticMatrixArray, StaticMatrixObject } from '@kici-dev/engine';
 /**
  * Context passed to dynamic matrix functions.
  * Uses destructured form: async ({$, ctx, log, env}) => values
@@ -36,21 +34,6 @@ export interface DynamicMatrixContext {
 export type DynamicMatrixFn = (context: DynamicMatrixContext) => Promise<StaticMatrixArray | StaticMatrixObject>;
 /** Union type for all matrix forms */
 export type Matrix = StaticMatrixArray | StaticMatrixObject | DynamicMatrixFn;
-/** Include entries for adding specific matrix combinations */
-export type MatrixInclude = Record<string, string>;
-/** Exclude entries for removing specific matrix combinations */
-export type MatrixExclude = Record<string, string>;
-/**
- * Matrix values as exposed to steps.
- * Single-dimension: {value: 'linux'}
- * Multi-dimensional: {os: 'linux', node: '18'}
- */
-export interface MatrixValues {
-    /** Single-dimension: the value */
-    value?: string;
-    /** Multi-dimensional: named properties */
-    [dimension: string]: string | undefined;
-}
 /** Type guard for static array matrices */
 export declare function isStaticArray(m: Matrix): m is StaticMatrixArray;
 /** Type guard for static object matrices */

package/dist/matrix/types.js

@@ -1,4 +1,4 @@
-import "../chunk-gOLHoazu.js";
+import "../chunk-BTugEXQM.js";
 //#region src/matrix/types.ts
 /** Type guard for static array matrices */
 function isStaticArray(m) {

package/dist/needs-context.d.ts

@@ -0,0 +1,32 @@
+import type { OutputProxy, DynamicJobNeed } from './types.js';
+/**
+ * Frozen snapshot of upstream outputs, captured once at first eval of a
+ * result-aware dynamic generator and replayed unchanged on re-eval.
+ *
+ * - `jobs` maps an upstream job name to its outputs record.
+ * - `groups` maps a dynamic group name to its ordered member job names.
+ */
+export interface UpstreamSnapshot {
+    jobs: Record<string, Record<string, unknown>>;
+    groups: Record<string, string[]>;
+}
+/** One entry in the array exposed for a `dynamicGroup(...)` need. */
+export interface GroupNeedEntry {
+    name: string;
+    result: OutputProxy<any>;
+}
+/** A single-job need exposes `{ result }`; a group need exposes an ordered array. */
+export type NeedEntry = {
+    result: OutputProxy<any>;
+} | GroupNeedEntry[];
+/** The resolved `ctx.needs` map keyed by job name or group name. */
+export type NeedsContext = Record<string, NeedEntry>;
+/**
+ * Resolve declared needs against a frozen snapshot into the `ctx.needs` map.
+ *
+ * - A single static/named-job need resolves to `{ result: <proxy over jobs[name]> }`.
+ * - A `dynamicGroup(...)` need resolves to an ordered array of `{ name, result }`,
+ *   one entry per group member in the snapshot's deterministic eval order.
+ */
+export declare function buildNeedsContext(snapshot: UpstreamSnapshot, declaredNeeds: ReadonlyArray<DynamicJobNeed>): NeedsContext;
+//# sourceMappingURL=needs-context.d.ts.map