@kici-dev/sdk 0.3.0 → 0.5.0

package/dist/filter-context.d.ts

@@ -0,0 +1,32 @@
+import type { $ as Shell } from 'zx';
+import type { ChangedFilesStatus } from '@kici-dev/engine';
+import type { EventPayload } from './events/event-payloads.js';
+import type { RepoInfo } from './context.js';
+import type { FilterContext } from './filter.js';
+/** Input for {@link createFilterContext}. */
+export interface CreateFilterContextInput {
+    /** The repo whose event triggered this evaluation. */
+    sourceRepo: RepoInfo;
+    /** The repo that registered the workflow. */
+    workflowRepo: RepoInfo;
+    event: EventPayload | Record<string, unknown>;
+    changedFiles?: string[];
+    /** Defaults to `'fetched'` — a caller that passes a real list needs no status. */
+    changedFilesStatus?: ChangedFilesStatus;
+    env?: Record<string, string | undefined>;
+    /** zx shell handed to the filter. Defaults to the ambient `$`. */
+    $?: typeof Shell;
+}
+/**
+ * Build a `FilterContext` — the single construction site for the context a
+ * workflow's `filter` predicate receives, mirroring {@link createRuleContext}.
+ *
+ * `changedFiles` is installed through the shared accessor, so it throws
+ * `ChangedFilesUnavailableError` when the diff is unavailable instead of
+ * reading as an empty list. That matters more here than in a rule: a `false`
+ * verdict dispatches none of the workflow's own jobs, and on the
+ * organization-wide path it produces no run at all — so a silently-empty diff
+ * would suppress the workflow with nothing left to inspect.
+ */
+export declare function createFilterContext(input: CreateFilterContextInput): FilterContext;
+//# sourceMappingURL=filter-context.d.ts.map

package/dist/filter-context.js

@@ -0,0 +1,36 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { defineChangedFilesGetter, eventTypeOf } from "./rules/changed-files.js";
+import { $ } from "zx";
+//#region src/filter-context.ts
+/**
+* Build a `FilterContext` — the single construction site for the context a
+* workflow's `filter` predicate receives, mirroring {@link createRuleContext}.
+*
+* `changedFiles` is installed through the shared accessor, so it throws
+* `ChangedFilesUnavailableError` when the diff is unavailable instead of
+* reading as an empty list. That matters more here than in a rule: a `false`
+* verdict dispatches none of the workflow's own jobs, and on the
+* organization-wide path it produces no run at all — so a silently-empty diff
+* would suppress the workflow with nothing left to inspect.
+*/
+function createFilterContext(input) {
+	const status = input.changedFilesStatus ?? "fetched";
+	const base = {
+		sourceRepo: input.sourceRepo,
+		workflowRepo: input.workflowRepo,
+		event: input.event,
+		changedFilesStatus: status,
+		env: input.env ?? {},
+		$: input.$ ?? $
+	};
+	defineChangedFilesGetter(base, {
+		files: input.changedFiles ?? [],
+		status,
+		eventType: eventTypeOf(input.event)
+	});
+	return base;
+}
+//#endregion
+export { createFilterContext };
+
+//# sourceMappingURL=filter-context.js.map

package/dist/filter.d.ts

@@ -0,0 +1,81 @@
+import type { $ as Shell } from 'zx';
+import type { ChangedFilesStatus } from '@kici-dev/engine';
+import type { EventPayload } from './events/event-payloads.js';
+import type { RepoInfo } from './context.js';
+/**
+ * Context handed to a workflow's `filter`, on an evaluating agent with the
+ * tree(s) on disk. An organization-wide workflow is evaluated once per
+ * (event × workflow repo), before any run row exists; a same-repo workflow is
+ * evaluated once per dispatch-bound job and once per generator, where
+ * `sourceRepo` and `workflowRepo` are the same repo. See `FilterFn` for what
+ * that means for the predicate you write, and which jobs it skips.
+ *
+ * **The context carries no secrets.** Not because nothing has been resolved
+ * yet — on the same-repo path a job's bound contexts, their vars and scoped
+ * secrets, its context rules and its approval hold are all resolved BEFORE the
+ * evaluating job is queued — but because this context deliberately does not
+ * carry them. `filter` sees no `scoped_secrets` and no source-repo credentials
+ * beyond the clone token, whichever path it runs on.
+ *
+ * `sourceRepo.path` is an absolute path on the evaluating agent. Its CONTENTS
+ * are stable across evaluations and the later sandbox run; the path itself is
+ * not (different workDir, possibly a different machine). Read through it; never
+ * embed it in a job name, an output, or anything compared across calls.
+ *
+ * `sourceRepo.ref` and `sourceRepo.sha` are optional on `RepoInfo` and may be
+ * absent for an event that carries no single ref — guard before reading them.
+ */
+export interface FilterContext {
+    /** The repo whose push triggered this evaluation. */
+    sourceRepo: RepoInfo;
+    /** The repo that registered the workflow. Identical to `sourceRepo` for a non-global workflow. */
+    workflowRepo: RepoInfo;
+    /** Normalized event envelope that triggered this evaluation. */
+    event: EventPayload;
+    /**
+     * Files changed in this event (push / pull_request diff, computed from the
+     * checkout). Reading this throws `ChangedFilesUnavailableError` when the diff
+     * is not available (`changedFilesStatus !== 'fetched'`) — e.g. a
+     * schedule/tag/manual event. Guard with `changedFilesStatus` first when a
+     * filter runs on such events:
+     * `if (ctx.changedFilesStatus !== 'fetched') return true`.
+     *
+     * The throw is deliberate and mirrors `RuleContext.changedFiles`: a `false`
+     * verdict dispatches none of the workflow's own jobs, so a silently-empty
+     * list would make a path-based gate suppress it invisibly. How invisibly
+     * depends on the path — an organization-wide workflow leaves no run at all,
+     * a same-repo one leaves a `success` run carrying only its `__init__*`
+     * evaluation jobs, whose log records the verdict.
+     */
+    changedFiles: string[];
+    /** Availability of `changedFiles` (see `changedFiles`). */
+    changedFilesStatus: ChangedFilesStatus;
+    /** Environment variables. */
+    env: Record<string, string | undefined>;
+    /** zx shell executor. */
+    $: typeof Shell;
+}
+/**
+ * A workflow-level pre-dispatch predicate.
+ *
+ * **It must be pure and deterministic.** For an organization-wide workflow it is
+ * called once per (event × workflow repo). For a same-repo workflow it is called
+ * once for every job that reaches dispatch and once for every job generator, so
+ * a workflow with ten jobs calls it ten times for one event, each on its own
+ * agent with its own checkout and its own `ctx.$` shell. Two consequences to
+ * design for: anything the predicate does — an API call, a shell command, a
+ * write — happens that many times, so keep it cheap and side-effect free; and if
+ * it can return different answers for the same event, the workflow will
+ * partially dispatch, running some jobs and not others.
+ *
+ * "Reaches dispatch" excludes two same-repo cases: a job **held for approval**
+ * and a job **rejected by a context rule** are never filtered. Each already has
+ * a gate — the hold or the rule — so an approved job dispatches with no filter
+ * verdict having been taken. A path filter therefore cannot stop an approval
+ * request for a job the change does not concern.
+ *
+ * Decide from `ctx` alone — the event, the changed files, and the checked-out
+ * tree — and the same event always yields the same verdict.
+ */
+export type FilterFn = (ctx: FilterContext) => boolean | Promise<boolean>;
+//# sourceMappingURL=filter.d.ts.map

package/dist/filter.js

@@ -0,0 +1,2 @@
+import "./rolldown-runtime-ClRpJifh.js";
+export {};

package/dist/index.d.ts

@@ -33,6 +33,9 @@ export { dynamicGroup, isDynamicGroupRef, DYNAMIC_GROUP_TAG } from './dynamic-gr
 export type { DynamicGroupRef } from './dynamic-group.js';
 export type { StepContext, Logger, WorkflowInfo, JobInfo, AgentInfo, MatrixJobOutputs, HostJobOutputs, RepoInfo, StepSecretsTyped, KnownSecretKeys, } from './context.js';
 export { isMatrixJobOutputs, isHostJobOutputs } from './context.js';
+export type { FilterContext, FilterFn } from './filter.js';
+export { createFilterContext } from './filter-context.js';
+export type { CreateFilterContextInput } from './filter-context.js';
 export type { FanoutPosition } from './fanout-context.js';
 export { buildKiciApi } from './api-types.js';
 export type { KiciApi, KiciApiTransport, InfrastructureApi, InfrastructureListResult, InventoryApi, HostApi, HostInventoryEntry, InventorySelector, } from './api-types.js';

package/dist/index.js

@@ -6,6 +6,8 @@ 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 { ChangedFilesUnavailableError } from "./rules/changed-files.js";
+import { createFilterContext } from "./filter-context.js";
 import { fixture } from "./fixture.js";
 import { createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "./outputs.js";
 import { step } from "./step.js";
@@ -42,7 +44,7 @@ import { defineDispatchInputs } from "./triggers/dispatch-inputs.js";
 import "./triggers/index.js";
 import { afterStep, beforeStep, cleanup, onCancel, onFailure, onSuccess } from "./hooks/index.js";
 import { onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip } from "./rules/rule.js";
-import { ChangedFilesUnavailableError, createRuleContext } from "./rules/context.js";
+import { createRuleContext } from "./rules/context.js";
 import { evaluateRules } from "./rules/evaluator.js";
 import { isEventType } from "./events/event-payloads.js";
 import "./rules/index.js";
@@ -59,4 +61,4 @@ import { defineEvent, isEventDefinition } from "./events/define-event.js";
 import "./events/index.js";
 import { agentVersionConverge } from "./fleet/agent-version-converge.js";
 import { z } from "zod";
-export { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema, CacheSpecSchema, ChangedFilesUnavailableError, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, agentVersionConverge, applyIncludeExclude, beforeStep, buildKiciApi, buildNeedsContext, checkStep, cleanup, comment, create, createJobOutputProxy, createRuleContext, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineDispatchInputs, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, flattenStepInputs, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventDefinition, isEventType, isHostJobOutputs, isMatrixJobOutputs, isParallelGroup, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeApproval, normalizeCacheSpecs, onCancel, onFailure, onSuccess, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, parallel, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, restartHost, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForHostAlive, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, workflowsFailedBatch, z };
+export { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema, CacheSpecSchema, ChangedFilesUnavailableError, DYNAMIC_GROUP_TAG, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, SecretNotFoundError, WaitForTimeoutError, afterStep, agentVersionConverge, applyIncludeExclude, beforeStep, buildKiciApi, buildNeedsContext, checkStep, cleanup, comment, create, createFilterContext, createJobOutputProxy, createRuleContext, createSnapshotOutputProxy, createStepOutputProxy, createStepSecrets, defineDispatchInputs, defineEvent, del as delete, dispatch, dynamicGroup, dynamicJob, evaluateRules, expandMatrix, fixture, flattenStepInputs, fork, genericWebhook, getDynamicJobGroup, getDynamicJobNeeds, getJobOutputsMap, getStepOutputsMap, getStepRefMap, idempotent, idempotentStep, isDynamicFunction, isDynamicGroupRef, isDynamicJobFn, isEventDefinition, isEventType, isHostJobOutputs, isMatrixJobOutputs, isParallelGroup, isStaticArray, isStaticObject, job, jobComplete, kiciEvent, lifecycle, normalizeApproval, normalizeCacheSpecs, onCancel, onFailure, onSuccess, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, parallel, pr, provenanceSubjectIsPath, push, release, resolveJobOutputs, resolveStepOutputs, restartHost, review, reviewComment, rule, schedule, setJobOutputsMap, setStepOutputsMap, setStepRefMap, skip, star, status, step, tag, validateDag, waitFor, waitForHostAlive, waitForStep, watch, webhook, workflow, workflowComplete, workflowRun, workflowsFailedBatch, z };

package/dist/rules/changed-files.d.ts

@@ -0,0 +1,37 @@
+import type { ChangedFilesStatus } from '@kici-dev/engine';
+/**
+ * Thrown when a rule or a workflow `filter` reads `ctx.changedFiles` but the
+ * diff is not available (`changedFilesStatus !== 'fetched'`). `evaluateRules`
+ * re-throws this rather than folding it into a `passed=false` skip, so the job
+ * fails loudly instead of silently mis-evaluating a path-based gate; the global
+ * eval round reports the candidate indeterminate for the same reason.
+ */
+export declare class ChangedFilesUnavailableError extends Error {
+    readonly changedFilesStatus: ChangedFilesStatus;
+    readonly eventType?: string;
+    constructor(status: ChangedFilesStatus, eventType?: string);
+}
+/** Read an event's `type` discriminant, when it carries a string one. */
+export declare function eventTypeOf(event: unknown): string | undefined;
+/**
+ * Install the throwing `changedFiles` accessor shared by `RuleContext` and
+ * `FilterContext`.
+ *
+ * Both contexts contract `changedFiles` to **throw** when the diff is
+ * unavailable rather than read as an empty list: a path-based gate that
+ * silently sees no changes suppresses work invisibly, and for a `filter` it
+ * suppresses every job the workflow declares. On the organization-wide path
+ * that leaves no run row at all; on the same-repo path it leaves a `success`
+ * run carrying only the workflow's `__init__*` evaluation jobs.
+ *
+ * The behaviour lives here, in one `Object.defineProperty`, precisely because a
+ * plain `{ changedFiles: [] }` property satisfies both context types with no
+ * error anywhere: a second construction site could violate the contract and
+ * still typecheck. Every builder of either context calls this.
+ */
+export declare function defineChangedFilesGetter(target: object, input: {
+    files: string[];
+    status: ChangedFilesStatus;
+    eventType?: string;
+}): void;
+//# sourceMappingURL=changed-files.d.ts.map

package/dist/rules/changed-files.js

@@ -0,0 +1,54 @@
+import "../rolldown-runtime-ClRpJifh.js";
+//#region src/rules/changed-files.ts
+/**
+* Thrown when a rule or a workflow `filter` reads `ctx.changedFiles` but the
+* diff is not available (`changedFilesStatus !== 'fetched'`). `evaluateRules`
+* re-throws this rather than folding it into a `passed=false` skip, so the job
+* fails loudly instead of silently mis-evaluating a path-based gate; the global
+* eval round reports the candidate indeterminate for the same reason.
+*/
+var ChangedFilesUnavailableError = class extends Error {
+	changedFilesStatus;
+	eventType;
+	constructor(status, eventType) {
+		super(`ctx.changedFiles is not available (status: ${status}` + (eventType ? `, event: ${eventType}` : "") + "). Changed files are only defined for push / pull_request events with a computable diff. Guard with ctx.changedFilesStatus before accessing, e.g. `if (ctx.changedFilesStatus !== 'fetched') return true`.");
+		this.name = "ChangedFilesUnavailableError";
+		this.changedFilesStatus = status;
+		this.eventType = eventType;
+	}
+};
+/** Read an event's `type` discriminant, when it carries a string one. */
+function eventTypeOf(event) {
+	const type = event?.type;
+	return typeof type === "string" ? type : void 0;
+}
+/**
+* Install the throwing `changedFiles` accessor shared by `RuleContext` and
+* `FilterContext`.
+*
+* Both contexts contract `changedFiles` to **throw** when the diff is
+* unavailable rather than read as an empty list: a path-based gate that
+* silently sees no changes suppresses work invisibly, and for a `filter` it
+* suppresses every job the workflow declares. On the organization-wide path
+* that leaves no run row at all; on the same-repo path it leaves a `success`
+* run carrying only the workflow's `__init__*` evaluation jobs.
+*
+* The behaviour lives here, in one `Object.defineProperty`, precisely because a
+* plain `{ changedFiles: [] }` property satisfies both context types with no
+* error anywhere: a second construction site could violate the contract and
+* still typecheck. Every builder of either context calls this.
+*/
+function defineChangedFilesGetter(target, input) {
+	Object.defineProperty(target, "changedFiles", {
+		enumerable: true,
+		configurable: true,
+		get() {
+			if (input.status !== "fetched") throw new ChangedFilesUnavailableError(input.status, input.eventType);
+			return input.files;
+		}
+	});
+}
+//#endregion
+export { ChangedFilesUnavailableError, defineChangedFilesGetter, eventTypeOf };
+
+//# sourceMappingURL=changed-files.js.map

package/dist/rules/context.d.ts

@@ -1,18 +1,9 @@
 import type { ChangedFilesStatus } from '@kici-dev/engine';
 import type { EventPayload } from '../events/event-payloads.js';
 import type { FanoutPosition } from '../fanout-context.js';
+import type { RepoInfo } from '../context.js';
 import type { RuleContext } from './types.js';
-/**
- * Thrown when a rule reads `ctx.changedFiles` but the diff is not available
- * (`changedFilesStatus !== 'fetched'`). `evaluateRules` re-throws this rather
- * than folding it into a `passed=false` skip, so the job fails loudly instead
- * of silently mis-evaluating a path-based gate.
- */
-export declare class ChangedFilesUnavailableError extends Error {
-    readonly changedFilesStatus: ChangedFilesStatus;
-    readonly eventType?: string;
-    constructor(status: ChangedFilesStatus, eventType?: string);
-}
+export { ChangedFilesUnavailableError } from './changed-files.js';
 /** Input for {@link createRuleContext}. */
 export interface CreateRuleContextInput {
     event: EventPayload | Record<string, unknown>;
@@ -22,6 +13,16 @@ export interface CreateRuleContextInput {
     env?: Record<string, string | undefined>;
     dispatchInputs?: Readonly<Record<string, string | number | boolean | null>>;
     fanout?: FanoutPosition;
+    /**
+     * The repo whose event triggered this run. Supplied for a global workflow.
+     *
+     * `path` is an absolute path into the evaluating machine's work directory and
+     * is NOT stable across evaluations — read the tree through it, never compare
+     * it. `ref` / `sha` are optional on `RepoInfo`; do not assume either is set.
+     */
+    sourceRepo?: RepoInfo;
+    /** The repo that registered the workflow. Identical to `sourceRepo` outside a global workflow. */
+    workflowRepo?: RepoInfo;
 }
 /**
  * Build a RuleContext. `changedFiles` is exposed as a getter: it returns the

package/dist/rules/context.js

@@ -1,23 +1,8 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { ChangedFilesUnavailableError, defineChangedFilesGetter, eventTypeOf } from "./changed-files.js";
 import { $ } from "zx";
 //#region src/rules/context.ts
 /**
-* Thrown when a rule reads `ctx.changedFiles` but the diff is not available
-* (`changedFilesStatus !== 'fetched'`). `evaluateRules` re-throws this rather
-* than folding it into a `passed=false` skip, so the job fails loudly instead
-* of silently mis-evaluating a path-based gate.
-*/
-var ChangedFilesUnavailableError = class extends Error {
-	changedFilesStatus;
-	eventType;
-	constructor(status, eventType) {
-		super(`ctx.changedFiles is not available (status: ${status}` + (eventType ? `, event: ${eventType}` : "") + "). Changed files are only defined for push / pull_request events with a computable diff. Guard with ctx.changedFilesStatus before accessing, e.g. `if (ctx.changedFilesStatus !== 'fetched') return true`.");
-		this.name = "ChangedFilesUnavailableError";
-		this.changedFilesStatus = status;
-		this.eventType = eventType;
-	}
-};
-/**
 * Build a RuleContext. `changedFiles` is exposed as a getter: it returns the
 * list when `changedFilesStatus === 'fetched'`, otherwise it throws
 * `ChangedFilesUnavailableError`. This is the single construction site for a
@@ -25,23 +10,20 @@ var ChangedFilesUnavailableError = class extends Error {
 */
 function createRuleContext(input) {
 	const status = input.changedFilesStatus ?? "fetched";
-	const files = input.changedFiles ?? [];
-	const eventType = typeof input.event.type === "string" ? input.event.type : void 0;
 	const base = {
 		event: input.event,
 		changedFilesStatus: status,
 		env: input.env ?? {},
 		dispatchInputs: input.dispatchInputs ?? {},
 		...input.fanout && { fanout: input.fanout },
+		...input.sourceRepo && { sourceRepo: input.sourceRepo },
+		...input.workflowRepo && { workflowRepo: input.workflowRepo },
 		$
 	};
-	Object.defineProperty(base, "changedFiles", {
-		enumerable: true,
-		configurable: true,
-		get() {
-			if (status !== "fetched") throw new ChangedFilesUnavailableError(status, eventType);
-			return files;
-		}
+	defineChangedFilesGetter(base, {
+		files: input.changedFiles ?? [],
+		status,
+		eventType: eventTypeOf(input.event)
 	});
 	return base;
 }

package/dist/rules/evaluator.js

@@ -1,5 +1,6 @@
 import "../rolldown-runtime-ClRpJifh.js";
-import { ChangedFilesUnavailableError } from "./context.js";
+import { ChangedFilesUnavailableError } from "./changed-files.js";
+import "./context.js";
 import { toErrorMessage } from "@kici-dev/core";
 //#region src/rules/evaluator.ts
 /**

package/dist/rules/index.js

@@ -1,6 +1,7 @@
 import "../rolldown-runtime-ClRpJifh.js";
+import { ChangedFilesUnavailableError } from "./changed-files.js";
 import { onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip } from "./rule.js";
-import { ChangedFilesUnavailableError, createRuleContext } from "./context.js";
+import { createRuleContext } from "./context.js";
 import { evaluateRules } from "./evaluator.js";
 import { isEventType } from "../events/event-payloads.js";
 export { ChangedFilesUnavailableError, createRuleContext, evaluateRules, isEventType, onlyOnFanoutIndex, onlyOnFirstHost, onlyOnLastHost, rule, skip };

package/dist/rules/types.d.ts

@@ -1,6 +1,7 @@
 import type { $ as Shell } from 'zx';
 import type { EventPayload } from '../events/event-payloads.js';
 import type { FanoutPosition } from '../fanout-context.js';
+import type { RepoInfo } from '../context.js';
 export type { EventPayload } from '../events/event-payloads.js';
 /**
  * Context passed to rule check functions.
@@ -21,6 +22,14 @@ export interface RuleContext {
     changedFiles: string[];
     /** Availability of `changedFiles` (see `changedFiles`). */
     changedFilesStatus: import('@kici-dev/engine').ChangedFilesStatus;
+    /**
+     * The repo whose event triggered this run. Present for a global workflow and
+     * for any evaluation that runs with a checkout; undefined otherwise.
+     * Read through `.path`; never embed it in a job name (see FilterContext).
+     */
+    sourceRepo?: RepoInfo;
+    /** The repo that registered the workflow. Identical to `sourceRepo` outside a global workflow. */
+    workflowRepo?: RepoInfo;
     /** Environment variables */
     env: Record<string, string | undefined>;
     /** Operator-supplied, validated + coerced workflow-dispatch inputs. Empty when none declared. */

package/dist/testing/step-context.js

@@ -2,8 +2,8 @@ import "../rolldown-runtime-ClRpJifh.js";
 import { resolveJobOutputs, resolveStepOutputs } from "../outputs.js";
 import { createStepSecrets } from "../secrets.js";
 import { isEventDefinition } from "../events/define-event.js";
-import { initZx } from "@kici-dev/core";
 import { $ } from "zx";
+import { initZx } from "@kici-dev/core";
 import { chmodSync, mkdtempSync, rmSync, writeFileSync } from "node:fs";
 import { tmpdir } from "node:os";
 import { dirname, join } from "node:path";

package/dist/triggers/pr.js

@@ -38,6 +38,8 @@ function pr(config) {
 		sourceBranches: Object.freeze([...sourceBranches]),
 		paths: Object.freeze([...paths]),
 		repos: Object.freeze([...repos]),
+		...config?.requires !== void 0 && { requires: Object.freeze([...config.requires]) },
+		...config?.commitMessage !== void 0 && { commitMessage: config.commitMessage },
 		...config?.description !== void 0 && { description: config.description }
 	};
 	return Object.freeze(result);

package/dist/triggers/push.js

@@ -38,6 +38,8 @@ function push(config) {
 		tags: Object.freeze([...tags]),
 		paths: Object.freeze([...paths]),
 		repos: Object.freeze([...repos]),
+		...config?.requires !== void 0 && { requires: Object.freeze([...config.requires]) },
+		...config?.commitMessage !== void 0 && { commitMessage: config.commitMessage },
 		...config?.description !== void 0 && { description: config.description }
 	};
 	return Object.freeze(result);

package/dist/triggers/tag.js

@@ -21,6 +21,8 @@ function tag(config) {
 		_tag: "TagTrigger",
 		patterns: Object.freeze([...patterns]),
 		repos: Object.freeze([...repos]),
+		...config?.requires !== void 0 && { requires: Object.freeze([...config.requires]) },
+		...config?.commitMessage !== void 0 && { commitMessage: config.commitMessage },
 		...config?.description !== void 0 && { description: config.description }
 	};
 	return Object.freeze(result);

package/dist/triggers/types.d.ts

@@ -3,6 +3,8 @@
  * Supports both glob patterns and regex patterns for branch/path matching.
  */
 import type { z } from 'zod';
+import type { ContentRequirement, TextMatch } from '@kici-dev/engine';
+export type { ContentRequirement, ContentFormat, TextMatch } from '@kici-dev/engine';
 /**
  * A declared map of typed workflow-dispatch inputs: `{ name: ZodSchema }`.
  * Each schema must fall within the closed dispatch-input subset (extracted by
@@ -44,6 +46,10 @@ export interface PrTriggerConfig {
     readonly sourceBranches: readonly BranchPattern[];
     readonly paths: readonly string[];
     readonly repos: readonly BranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 /**
@@ -55,6 +61,10 @@ export interface PushTriggerConfig {
     readonly tags: readonly BranchPattern[];
     readonly paths: readonly string[];
     readonly repos: readonly BranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 /**
@@ -64,6 +74,10 @@ export interface TagTriggerConfig {
     readonly _tag: 'TagTrigger';
     readonly patterns: readonly BranchPattern[];
     readonly repos: readonly BranchPattern[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 /**
@@ -72,6 +86,10 @@ export interface TagTriggerConfig {
 export interface TagConfigInput {
     readonly patterns?: string | RegExp | (string | RegExp)[];
     readonly repos?: string | RegExp | (string | RegExp)[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 export type CommentAction = 'created' | 'edited' | 'deleted';
@@ -558,6 +576,10 @@ export interface PrConfigInput {
     readonly source?: string | RegExp | (string | RegExp)[];
     readonly paths?: string[];
     readonly repos?: string | RegExp | (string | RegExp)[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 /**
@@ -569,6 +591,10 @@ export interface PushConfigInput {
     readonly tags?: string | RegExp | (string | RegExp)[];
     readonly paths?: string[];
     readonly repos?: string | RegExp | (string | RegExp)[];
+    /** Declarative static content filter over source files at the event ref (AND-ed). */
+    readonly requires?: readonly ContentRequirement[];
+    /** Declarative static filter over the event's commit message / PR title+body. */
+    readonly commitMessage?: TextMatch;
     readonly description?: string;
 }
 /**

package/dist/types.d.ts

@@ -2,7 +2,8 @@ import type { z } from 'zod';
 import type { $ as Shell } from 'zx';
 import type { RetryBackoff } from '@kici-dev/core';
 import type { ResourceRequest, RunsOnAllInput, OnUnreachableMode, NeedsWhen, ExecutionJobStatus } from '@kici-dev/engine';
-import type { StepContext, Logger } from './context.js';
+import type { StepContext, Logger, RepoInfo } from './context.js';
+import type { FilterFn } from './filter.js';
 import type { SingleNeedEntry, NeedsContext } from './needs-context.js';
 import type { TriggerConfig } from './triggers/types.js';
 import type { Rule } from './rules/types.js';
@@ -308,6 +309,14 @@ export interface DynamicJobContext {
     env: Record<string, string | undefined>;
     /** Typed KiCI API — orchestrator queries over WS (e.g., kici.infrastructure.list()) */
     kici: KiciApi;
+    /**
+     * The repo whose event triggered this run. Present for a global workflow and
+     * for any evaluation that runs with a checkout; undefined otherwise.
+     * Read through `.path`; never embed it in a job name (see FilterContext).
+     */
+    sourceRepo?: RepoInfo;
+    /** The repo that registered the workflow. Identical to `sourceRepo` outside a global workflow. */
+    workflowRepo?: RepoInfo;
 }
 /**
  * Async function that generates jobs dynamically at runtime.
@@ -845,6 +854,23 @@ export interface Workflow {
     readonly on?: TriggerConfig[];
     /** Rules for conditional execution */
     readonly rules?: Rule[];
+    /**
+     * Pre-dispatch predicate deciding whether this workflow applies to the event's
+     * source repo. A `false` result suppresses the workflow's jobs — none is
+     * dispatched, and none is reported as skipped.
+     *
+     * An organization-wide workflow is evaluated once per (event × workflow repo)
+     * before any run row is created, so a `false` verdict produces no run. A
+     * same-repo workflow is evaluated once per job and once per job generator,
+     * after the run row exists — so a run is recorded showing the evaluation and
+     * none of the workflow's own jobs. Because it runs once per job there, the
+     * predicate must be cheap, side-effect free, and deterministic; see `FilterFn`.
+     *
+     * One same-repo exception: a job **held for approval** or **rejected by a
+     * context rule** is not filtered at all. The hold or the rule is its gate, so
+     * an approved job dispatches with no filter verdict having been taken.
+     */
+    readonly filter?: FilterFn;
     /** Optional description */
     readonly description?: string;
     /**
@@ -899,6 +925,26 @@ export interface WorkflowOptions {
     on?: Trigger | Trigger[];
     /** Rules that must pass for workflow to execute */
     rules?: Rule[];
+    /**
+     * Pre-dispatch predicate deciding whether this workflow applies to the event's
+     * source repo. Runs on an evaluating agent with the tree(s) on disk, and a
+     * `false` result suppresses the workflow's jobs — none is dispatched, and none
+     * is reported as skipped.
+     *
+     * An organization-wide workflow is evaluated once per (event × workflow repo)
+     * before any run row is created, so a `false` verdict produces no run. A
+     * same-repo workflow is evaluated once per job and once per job generator,
+     * after the run row exists — so a run is recorded showing the evaluation and
+     * none of the workflow's own jobs. Because it runs once per job there, the
+     * predicate must be cheap, side-effect free, and deterministic; see `FilterFn`.
+     *
+     * One same-repo exception: a job **held for approval** or **rejected by a
+     * context rule** is not filtered at all. The hold or the rule is its gate, so
+     * an approved job dispatches with no filter verdict having been taken.
+     *
+     * See `FilterContext` for what it receives and what it deliberately does not.
+     */
+    filter?: FilterFn;
     /** Optional description for documentation */
     description?: string;
     /**

package/dist/workflow.js

@@ -60,12 +60,14 @@ function workflow(name, options) {
 	if (options.installEnv) {
 		for (const [i, ref] of options.installEnv.entries()) if (!isQualifiedSecretRef(ref)) throw new Error(`workflow('${name}'): installEnv[${i}] must use qualified <context>:<secret-name> syntax (got: ${ref})`);
 	}
+	if (options.filter !== void 0 && typeof options.filter !== "function") throw new Error(`workflow('${name}'): filter must be a function (got: ${typeof options.filter})`);
 	return {
 		_tag: "Workflow",
 		name,
 		jobs: options.jobs,
 		on: normalizeTriggers(options.on),
 		rules: options.rules,
+		filter: options.filter,
 		description: options.description,
 		hashFiles: options.hashFiles,
 		registries: options.registries,

package/package.json

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

package/sbom.spdx.json

@@ -2,10 +2,10 @@
   "spdxVersion": "SPDX-2.3",
   "dataLicense": "CC0-1.0",
   "SPDXID": "SPDXRef-DOCUMENT",
-  "name": "@kici-dev/sdk@0.3.0",
-  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.3.0/d6c98e6b-cc60-4e6c-a027-ad3272eb60b7",
+  "name": "@kici-dev/sdk@0.5.0",
+  "documentNamespace": "https://kici.dev/sbom/%40kici-dev%2Fsdk/0.5.0/ce1a88a9-f83c-40fc-b642-cfdfb3ab5f7c",
   "creationInfo": {
-    "created": "2026-08-09T01:30:17Z",
+    "created": "2026-08-15T19:15:41Z",
     "creators": [
       "Tool: kici-sbom-generator"
     ]
@@ -146,9 +146,9 @@
       "homepage": "https://ericsmekens.github.io/jsep/tree/master/packages/regex#readme"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-core-0.3.0",
+      "SPDXID": "SPDXRef-Package--kici-dev-core-0.5.0",
       "name": "@kici-dev/core",
-      "versionInfo": "0.3.0",
+      "versionInfo": "0.5.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -159,16 +159,16 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/core@0.3.0"
+          "referenceLocator": "pkg:npm/%40kici-dev/core@0.5.0"
         }
       ],
       "description": "Light shared utilities for the KiCI stack (logging, errors, formatting, crypto, zx init, the TypeScript ESM loader hook). No server-side dependencies.",
       "homepage": "https://kici.dev"
     },
     {
-      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.3.0",
+      "SPDXID": "SPDXRef-Package--kici-dev-engine-0.5.0",
       "name": "@kici-dev/engine",
-      "versionInfo": "0.3.0",
+      "versionInfo": "0.5.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -179,7 +179,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.3.0"
+          "referenceLocator": "pkg:npm/%40kici-dev/engine@0.5.0"
         }
       ],
       "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.",
@@ -188,7 +188,7 @@
     {
       "SPDXID": "SPDXRef-RootPackage",
       "name": "@kici-dev/sdk",
-      "versionInfo": "0.3.0",
+      "versionInfo": "0.5.0",
       "downloadLocation": "NOASSERTION",
       "filesAnalyzed": false,
       "licenseConcluded": "NOASSERTION",
@@ -199,7 +199,7 @@
         {
           "referenceCategory": "PACKAGE-MANAGER",
           "referenceType": "purl",
-          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.3.0"
+          "referenceLocator": "pkg:npm/%40kici-dev/sdk@0.5.0"
         }
       ],
       "description": "TypeScript SDK for defining KiCI workflows. Import into `.kici/workflows/*.ts` to declare workflows, jobs, steps, triggers, rules, and matrix configurations.",
@@ -1491,6 +1491,26 @@
       ],
       "description": "A logger for just about everything."
     },
+    {
+      "SPDXID": "SPDXRef-Package-yaml-2.9.0",
+      "name": "yaml",
+      "versionInfo": "2.9.0",
+      "downloadLocation": "https://registry.npmjs.org/yaml/-/yaml-2.9.0.tgz",
+      "filesAnalyzed": false,
+      "licenseConcluded": "NOASSERTION",
+      "licenseDeclared": "ISC",
+      "copyrightText": "NOASSERTION",
+      "supplier": "NOASSERTION",
+      "externalRefs": [
+        {
+          "referenceCategory": "PACKAGE-MANAGER",
+          "referenceType": "purl",
+          "referenceLocator": "pkg:npm/yaml@2.9.0"
+        }
+      ],
+      "description": "JavaScript parser and stringifier for YAML",
+      "homepage": "https://eemeli.org/yaml/"
+    },
     {
       "SPDXID": "SPDXRef-Package-zod-4.4.3",
       "name": "zod",
@@ -1584,68 +1604,73 @@
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-oxc-transform-0.140.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-picocolors-1.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-winston-daily-rotate-file-5.0.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-winston-3.19.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-core-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-zx-8.8.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-jose-6.2.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-jsonpath-plus-10.4.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-picomatch-4.0.5",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-safe-regex-2.1.1",
       "relationshipType": "DEPENDS_ON"
     },
     {
-      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.3.0",
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.5.0",
+      "relatedSpdxElement": "SPDXRef-Package-yaml-2.9.0",
+      "relationshipType": "DEPENDS_ON"
+    },
+    {
+      "spdxElementId": "SPDXRef-Package--kici-dev-engine-0.5.0",
       "relatedSpdxElement": "SPDXRef-Package-zod-4.4.3",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.3.0",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-core-0.5.0",
       "relationshipType": "DEPENDS_ON"
     },
     {
       "spdxElementId": "SPDXRef-RootPackage",
-      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.3.0",
+      "relatedSpdxElement": "SPDXRef-Package--kici-dev-engine-0.5.0",
       "relationshipType": "DEPENDS_ON"
     },
     {