@kici-dev/sdk 0.1.17 → 0.1.19

package/dist/context.d.ts

@@ -19,6 +19,20 @@ 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
@@ -31,7 +45,26 @@ export interface MatrixJobOutputs<T = Record<string, unknown>> {
     merged: T;
 }
 /** Runtime discriminator: true when `ctx.jobOutputs(ref)` returned a matrix envelope. */
-export declare function isMatrixJobOutputs(value: Record<string, unknown> | MatrixJobOutputs): value is MatrixJobOutputs;
+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.
@@ -93,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.
@@ -186,7 +230,7 @@ export interface StepContext<TInputs = Record<string, unknown>> {
      */
     jobOutputs(ref: {
         name: string;
-    }): Record<string, unknown> | MatrixJobOutputs;
+    }): 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

package/dist/context.js

@@ -4,7 +4,11 @@ import "./chunk-BTugEXQM.js";
 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 { isMatrixJobOutputs };
+export { isHostJobOutputs, isMatrixJobOutputs };
 
 //# sourceMappingURL=context.js.map

package/dist/index.d.ts

@@ -14,8 +14,10 @@ export type { Rule, RuleContext, RuleCheckFn, RuleResult, EventPayload, RuleEval
 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, MiseInitConfig, InitPreset, InitItem, InitConfig, 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 { 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';
@@ -23,14 +25,14 @@ 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, MatrixJobOutputs, RepoInfo, StepSecretsTyped, KnownSecretKeys, } from './context.js';
-export { isMatrixJobOutputs } 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

@@ -2,11 +2,11 @@ import "./chunk-BTugEXQM.js";
 import { buildKiciApi } from "./api-types.js";
 import { normalizeRequireApproval } from "./approval.js";
 import { CacheSpecSchema, normalizeCacheSpecs } from "./cache-types.js";
-import { isMatrixJobOutputs } from "./context.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";
@@ -41,7 +41,8 @@ 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";
@@ -51,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, 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 };
+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

@@ -32,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/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

package/dist/needs-context.js

@@ -0,0 +1,44 @@
+import "./chunk-BTugEXQM.js";
+import { createSnapshotOutputProxy } from "./outputs.js";
+//#region src/needs-context.ts
+function needKey(need) {
+	if (typeof need === "string") return {
+		kind: "job",
+		key: need
+	};
+	if ("group" in need) return {
+		kind: "group",
+		key: need.group
+	};
+	if ("name" in need) return {
+		kind: "job",
+		key: need.name
+	};
+	return {
+		kind: "job",
+		key: need.name
+	};
+}
+/**
+* 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.
+*/
+function buildNeedsContext(snapshot, declaredNeeds) {
+	const out = {};
+	for (const need of declaredNeeds) {
+		const { kind, key } = needKey(need);
+		if (kind === "group") out[key] = (snapshot.groups[key] ?? []).map((name) => ({
+			name,
+			result: createSnapshotOutputProxy(name, snapshot.jobs[name])
+		}));
+		else out[key] = { result: createSnapshotOutputProxy(key, snapshot.jobs[key]) };
+	}
+	return out;
+}
+//#endregion
+export { buildNeedsContext };
+
+//# sourceMappingURL=needs-context.js.map

package/dist/outputs.d.ts

@@ -61,6 +61,18 @@ export declare function createStepOutputProxy<T>(stepName: string): OutputProxy<
  * @returns A Proxy that resolves property access at runtime
  */
 export declare function createJobOutputProxy(jobName: string): OutputProxy<any>;
+/**
+ * Output proxy bound to a specific outputs object (not the module-global map).
+ *
+ * Used to expose a frozen upstream-job snapshot as `ctx.needs.<job>.result` for
+ * result-aware dynamic generators. The snapshot is captured once at eval and
+ * replayed unchanged on re-eval, so the proxy reads a fixed `outputs` object
+ * rather than the live module-global job-outputs map.
+ *
+ * @param jobName - The upstream job whose outputs to proxy (used in error text)
+ * @param outputs - The frozen outputs object, or undefined if the job produced none
+ */
+export declare function createSnapshotOutputProxy(jobName: string, outputs: Record<string, unknown> | undefined): OutputProxy<any>;
 /**
  * Resolve step outputs by step reference (Step object or bare function).
  * Used by ctx.outputsOf() implementation.

package/dist/outputs.js

@@ -140,6 +140,41 @@ function createJobOutputProxy(jobName) {
 	});
 }
 /**
+* Output proxy bound to a specific outputs object (not the module-global map).
+*
+* Used to expose a frozen upstream-job snapshot as `ctx.needs.<job>.result` for
+* result-aware dynamic generators. The snapshot is captured once at eval and
+* replayed unchanged on re-eval, so the proxy reads a fixed `outputs` object
+* rather than the live module-global job-outputs map.
+*
+* @param jobName - The upstream job whose outputs to proxy (used in error text)
+* @param outputs - The frozen outputs object, or undefined if the job produced none
+*/
+function createSnapshotOutputProxy(jobName, outputs) {
+	return new Proxy({}, {
+		get(_target, prop, receiver) {
+			if (typeof prop === "symbol") return Reflect.get(_target, prop, receiver);
+			if (WELL_KNOWN_STRING_PROPS.has(prop)) return Reflect.get(_target, prop, receiver);
+			if (!outputs) throw new Error(`Upstream job '${jobName}' has no frozen outputs in the generator snapshot`);
+			return outputs[prop];
+		},
+		ownKeys() {
+			return outputs ? Reflect.ownKeys(outputs) : [];
+		},
+		has(_target, prop) {
+			return outputs ? prop in outputs : false;
+		},
+		getOwnPropertyDescriptor(_target, prop) {
+			if (!outputs) return void 0;
+			if (prop in outputs) return {
+				configurable: true,
+				enumerable: true,
+				value: outputs[prop]
+			};
+		}
+	});
+}
+/**
 * Resolve step outputs by step reference (Step object or bare function).
 * Used by ctx.outputsOf() implementation.
 *
@@ -175,6 +210,6 @@ function resolveJobOutputs(ref, outputsMap) {
 	return outputs;
 }
 //#endregion
-export { createJobOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap };
+export { createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap };
 
 //# sourceMappingURL=outputs.js.map

package/dist/types.d.ts

@@ -1,6 +1,6 @@
 import type { z } from 'zod';
 import type { $ as Shell } from 'zx';
-import type { ResourceRequest } from '@kici-dev/engine';
+import type { ResourceRequest, RunsOnAllInput, OnUnreachableMode } from '@kici-dev/engine';
 import type { StepContext, Logger } from './context.js';
 import type { TriggerConfig } from './triggers/types.js';
 import type { Rule } from './rules/types.js';
@@ -10,7 +10,7 @@ import type { KiciApi } from './api-types.js';
 import type { DynamicGroupRef } from './dynamic-group.js';
 import type { EventPayload } from './events/event-payloads.js';
 import type { RequireApproval } from './approval.js';
-export type { ResourceRequest, ResourceSpec } from '@kici-dev/engine';
+export type { ResourceRequest, ResourceSpec, RunsOnAllInput, OnUnreachableMode, } from '@kici-dev/engine';
 /** Source location captured at a step() call site. */
 export interface SourceLocation {
     readonly file: string;
@@ -108,13 +108,16 @@ export type Trigger = TriggerConfig;
  * the re-evaluation must produce a job with the same name and the same steps.
  *
  * - `ctx.event` is deterministic — frozen from the original webhook payload.
+ * - `ctx.needs` is deterministic — a snapshot of upstream outputs frozen at first
+ *   eval and replayed unchanged on re-eval, like `ctx.event`. Present only on
+ *   result-aware generators created via `dynamicJob(group, { needs, generate })`.
  * - `$`, `env`, and `kici` can return different results between eval and re-eval
  *   (different agent, different time, different infrastructure state).
  *
- * **Guidance:** derive job names and structure from `ctx.event` data whenever
- * possible. If you use `kici.infrastructure.list()` or shell commands to
- * determine job names, be aware that changes between eval and re-eval will
- * cause a non-determinism warning (or failure if a job disappears).
+ * **Guidance:** derive job names and structure from `ctx.event` / `ctx.needs`
+ * data whenever possible. If you use `kici.infrastructure.list()` or shell
+ * commands to determine job names, be aware that changes between eval and re-eval
+ * will cause a non-determinism warning (or failure if a job disappears).
  */
 export interface DynamicJobContext {
     /** zx shell executor for running commands */
@@ -126,6 +129,12 @@ export interface DynamicJobContext {
         };
         /** Normalized event envelope that triggered this run. */
         event?: EventPayload;
+        /**
+         * Frozen outputs of declared upstream needs (result-aware generators only).
+         * Single-job needs expose `ctx.needs.<job>.result.<field>`; group needs
+         * expose an ordered array of `{ name, result }`.
+         */
+        needs?: import('./needs-context.js').NeedsContext;
     };
     /** Structured logger */
     log: Logger;
@@ -167,16 +176,56 @@ export interface TaggedDynamicJobFn extends DynamicJobFn {
  * Tag a DynamicJobFn with a group name for cross-domain needs.
  * Static jobs can then depend on this group via `needs: [dynamicGroup('name')]`.
  *
+ * Two forms:
+ * - **Function form** (event-only): `dynamicJob('shards', async ({ ctx }) => [...])`.
+ *   Dispatched at webhook time; deterministic from `ctx.event` alone.
+ * - **Options form** (result-aware): `dynamicJob('reports', { needs, generate })`.
+ *   Deferred until every job/group in `needs` completes, then `generate` is
+ *   evaluated with the upstreams' frozen outputs available as `ctx.needs`.
+ *
  * @param groupName - The group name (must match what static jobs reference)
- * @param fn - The dynamic job generator function
+ * @param fnOrConfig - The generator function, or a result-aware `{ needs, generate }` config
  */
-export declare function dynamicJob(groupName: string, fn: DynamicJobFn): TaggedDynamicJobFn;
+export declare function dynamicJob(groupName: string, fnOrConfig: DynamicJobFn | ResultAwareDynamicJobConfig): TaggedDynamicJobFn;
 /**
  * Get the group name from a DynamicJobFn, if it was tagged with dynamicJob().
  * Returns undefined for untagged functions.
  */
 export declare function getDynamicJobGroup(fn: DynamicJobFn): string | undefined;
 export { DYNAMIC_JOB_GROUP_TAG };
+declare const DYNAMIC_JOB_NEEDS_TAG: unique symbol;
+/**
+ * One declared upstream edge for a result-aware generator.
+ * Same shape as the elements of {@link JobOptions.needs}.
+ */
+export type DynamicJobNeed = Job | string | DynamicGroupRef | {
+    name: string;
+    ifFailed?: 'skip' | 'run';
+} | {
+    group: string;
+    ifFailed?: 'skip' | 'run';
+};
+/**
+ * Options-object form of {@link dynamicJob}: a result-aware generator that is
+ * deferred until its declared `needs` complete, then evaluated with their frozen
+ * outputs available as `ctx.needs`.
+ */
+export interface ResultAwareDynamicJobConfig {
+    /** Upstream jobs/groups whose outputs the generator reads via `ctx.needs`. */
+    needs: ReadonlyArray<DynamicJobNeed>;
+    /** The generator. Receives `ctx.needs` resolved from the frozen upstream snapshot. */
+    generate: DynamicJobFn;
+}
+/** A {@link DynamicJobFn} tagged with declared needs (result-aware). */
+export interface ResultAwareDynamicJobFn extends TaggedDynamicJobFn {
+    readonly [DYNAMIC_JOB_NEEDS_TAG]: ReadonlyArray<DynamicJobNeed>;
+}
+/**
+ * Read the declared needs from a result-aware generator.
+ * Returns undefined for event-only generators (the function form of dynamicJob).
+ */
+export declare function getDynamicJobNeeds(fn: DynamicJobFn): ReadonlyArray<DynamicJobNeed> | undefined;
+export { DYNAMIC_JOB_NEEDS_TAG };
 /**
  * Container configuration for job execution.
  * When set, all steps run inside the specified container.
@@ -254,8 +303,8 @@ export type InitConfig = InitItem | InitItem[] | 'auto' | false;
  * the agent's self-reported platform facts.
  */
 export interface RunsOnSelector {
-    labels: string | string[];
-    exclude?: string | string[];
+    labels: string | RegExp | (string | RegExp)[];
+    exclude?: string | RegExp | (string | RegExp)[];
 }
 /**
  * Polymorphic runsOn type: string shorthand, array shorthand, or full selector object.
@@ -263,18 +312,33 @@ export interface RunsOnSelector {
  * - `['kici:os:linux', 'gpu']` — multi-label shorthand (all must match)
  * - `{ labels: ['kici:os:linux'], exclude: ['kici:host:box-01'] }` — full selector
  *
+ * A plain string is matched exactly; a string containing glob metachars (`*?[]{}`) is a
+ * glob; a `RegExp` is a regex. Patterns are validated for ReDoS at compile time.
+ *
  * **Targeting `kici:` labels:** `runsOn` may target any agent label, including the
  * `kici:`-namespaced auto-labels (`kici:os:`, `kici:arch:`, `kici:host:`, `kici:agent:`,
  * `kici:scaler:`, `kici:role:`). Targeting is a requirement on candidate agents, never a
  * grant. `kici:scaler:` / `kici:agent:` are deployment-specific, so prefer custom labels
  * for portable pool targeting. Users still cannot *set* `kici:` labels on agents.
  */
-export type RunsOn = string | string[] | RunsOnSelector;
+export type RunsOn = string | RegExp | (string | RegExp)[] | RunsOnSelector;
 /** Job definition returned by job() factory */
 export interface Job {
     readonly _tag: 'Job';
     readonly name: string;
-    readonly runsOn: RunsOn;
+    /** Single-agent targeting. Mutually exclusive with `runsOnAll`. */
+    readonly runsOn?: RunsOn;
+    /**
+     * Host fan-out: run one pinned execution per roster host matching the predicate.
+     * Mutually exclusive with `runsOn`.
+     */
+    readonly runsOnAll?: RunsOnAllInput;
+    /** Failure policy for unreachable durable hosts when using `runsOnAll`. */
+    readonly onUnreachable?: OnUnreachableMode;
+    /** Fan-out concurrency width (sliding window; `1` = serial). Applies to matrix and `runsOnAll`. */
+    readonly maxParallel?: number;
+    /** Halt the fan-out on first child failure, skipping the remainder. Default `false`. */
+    readonly failFast?: boolean;
     readonly steps: readonly StepInput[];
     readonly needs?: ReadonlyArray<Job | string | DynamicGroupRef | {
         name: string;
@@ -355,7 +419,36 @@ export interface Job {
 }
 /** Options for job() factory */
 export interface JobOptions {
-    runsOn: RunsOn;
+    /** Single-agent targeting. Mutually exclusive with `runsOnAll`. */
+    runsOn?: RunsOn;
+    /**
+     * Host fan-out: run one pinned execution per roster host matching the predicate.
+     * The author writes a label string (`'role:web'`), an array with `!`-prefixed
+     * excludes (`['kici:os:linux', 'role:db', '!kici:host:db-01']`), or the
+     * structured `{ include: [{ all: [...] }], exclude?: [...] }` form.
+     * Mutually exclusive with `runsOn`.
+     */
+    runsOnAll?: RunsOnAllInput;
+    /**
+     * Failure policy for unreachable durable hosts when using `runsOnAll`:
+     * `'skip'` omits them, `'fail'` fails the run, `'hold'` (default) queues a
+     * pinned child and waits. Only meaningful alongside `runsOnAll`.
+     */
+    onUnreachable?: OnUnreachableMode;
+    /**
+     * Fan-out concurrency width: the maximum number of fan-out children (matrix
+     * combinations or `runsOnAll` hosts) that run at once. A sliding window —
+     * each child that reaches a terminal state releases the next held sibling.
+     * `1` = strictly serial (rolling). Applies to both matrix and `runsOnAll`
+     * fan-out; ignored on a non-fan-out job. Must be `>= 1`.
+     */
+    maxParallel?: number;
+    /**
+     * Halt the fan-out on the first child failure: stop releasing new children
+     * and skip the ones still held. Default `false` (every child runs regardless
+     * of sibling outcomes). Applies to both matrix and `runsOnAll` fan-out.
+     */
+    failFast?: boolean;
     /**
      * Steps to execute in this job. Accepts Step objects and bare async functions.
      * Mutually exclusive with `run`.

package/dist/types.js

@@ -11,15 +11,27 @@ const DYNAMIC_JOB_GROUP_TAG = Symbol.for("kici:dynamicJobGroup");
 * Tag a DynamicJobFn with a group name for cross-domain needs.
 * Static jobs can then depend on this group via `needs: [dynamicGroup('name')]`.
 *
+* Two forms:
+* - **Function form** (event-only): `dynamicJob('shards', async ({ ctx }) => [...])`.
+*   Dispatched at webhook time; deterministic from `ctx.event` alone.
+* - **Options form** (result-aware): `dynamicJob('reports', { needs, generate })`.
+*   Deferred until every job/group in `needs` completes, then `generate` is
+*   evaluated with the upstreams' frozen outputs available as `ctx.needs`.
+*
 * @param groupName - The group name (must match what static jobs reference)
-* @param fn - The dynamic job generator function
+* @param fnOrConfig - The generator function, or a result-aware `{ needs, generate }` config
 */
-function dynamicJob(groupName, fn) {
-	const tagged = fn;
+function dynamicJob(groupName, fnOrConfig) {
+	const isConfig = typeof fnOrConfig !== "function";
+	const tagged = isConfig ? fnOrConfig.generate : fnOrConfig;
 	Object.defineProperty(tagged, DYNAMIC_JOB_GROUP_TAG, {
 		value: groupName,
 		enumerable: false
 	});
+	if (isConfig) Object.defineProperty(tagged, DYNAMIC_JOB_NEEDS_TAG, {
+		value: fnOrConfig.needs,
+		enumerable: false
+	});
 	return tagged;
 }
 /**
@@ -29,7 +41,15 @@ function dynamicJob(groupName, fn) {
 function getDynamicJobGroup(fn) {
 	return fn[DYNAMIC_JOB_GROUP_TAG];
 }
+const DYNAMIC_JOB_NEEDS_TAG = Symbol.for("kici:dynamicJobNeeds");
+/**
+* Read the declared needs from a result-aware generator.
+* Returns undefined for event-only generators (the function form of dynamicJob).
+*/
+function getDynamicJobNeeds(fn) {
+	return fn[DYNAMIC_JOB_NEEDS_TAG];
+}
 //#endregion
-export { DYNAMIC_JOB_GROUP_TAG, dynamicJob, getDynamicJobGroup, isDynamicJobFn };
+export { DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, isDynamicJobFn };
 
 //# sourceMappingURL=types.js.map

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kici-dev/sdk",
-  "version": "0.1.17",
+  "version": "0.1.19",
   "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
   "keywords": [
     "ci",
@@ -47,10 +47,10 @@
   },
   "dependencies": {
     "micromatch": "^4.0.8",
-    "zod": "^4.3.6",
+    "zod": "^4.4.3",
     "zx": "^8.8.5",
-    "@kici-dev/core": "0.1.17",
-    "@kici-dev/engine": "0.1.17"
+    "@kici-dev/core": "0.1.19",
+    "@kici-dev/engine": "0.1.19"
   },
   "devDependencies": {
     "@types/micromatch": "^4.0.10"