@kici-dev/sdk 0.0.0 → 0.1.2

package/dist/triggers/workflow-complete.js

@@ -0,0 +1,32 @@
+import "../chunk-gOLHoazu.js";
+//#region src/triggers/workflow-complete.ts
+/**
+* Create a workflow completion trigger configuration.
+*
+* @example
+* // Match any workflow completion
+* workflowComplete()
+*
+* // Match specific workflow by name
+* workflowComplete({ name: 'CI' })
+*
+* // Match successful completions only
+* workflowComplete({ name: 'CI', status: ['success'] })
+*
+* // Cross-repo source filter
+* workflowComplete({ name: 'CI', status: ['success'], source: 'org/repo' })
+*/
+function workflowComplete(config) {
+	const result = {
+		_tag: "WorkflowCompleteTrigger",
+		...config?.name !== void 0 && { name: config.name },
+		...config?.status !== void 0 && { status: Object.freeze([...config.status]) },
+		...config?.source !== void 0 && { source: config.source },
+		...config?.description !== void 0 && { description: config.description }
+	};
+	return Object.freeze(result);
+}
+//#endregion
+export { workflowComplete };
+
+//# sourceMappingURL=workflow-complete.js.map

package/dist/triggers/workflow-run.d.ts

@@ -0,0 +1,17 @@
+/**
+ * Workflow run trigger helper - creates triggers for workflow_run events.
+ * Returns a frozen WorkflowRunTriggerConfig directly.
+ */
+import type { WorkflowRunConfigInput, WorkflowRunTriggerConfig } from './types.js';
+/**
+ * Create a workflow run trigger configuration.
+ *
+ * @example
+ * // Match any workflow run event
+ * workflowRun()
+ *
+ * // Match specific workflows and conclusions
+ * workflowRun({ workflows: ['CI'], actions: ['completed'], conclusions: ['success'] })
+ */
+export declare function workflowRun(config?: WorkflowRunConfigInput): WorkflowRunTriggerConfig;
+//# sourceMappingURL=workflow-run.d.ts.map

package/dist/triggers/workflow-run.js

@@ -0,0 +1,29 @@
+import "../chunk-gOLHoazu.js";
+import { asArray, toBranchPattern } from "./types.js";
+//#region src/triggers/workflow-run.ts
+/**
+* Create a workflow run trigger configuration.
+*
+* @example
+* // Match any workflow run event
+* workflowRun()
+*
+* // Match specific workflows and conclusions
+* workflowRun({ workflows: ['CI'], actions: ['completed'], conclusions: ['success'] })
+*/
+function workflowRun(config) {
+	const repos = config?.repos ? asArray(config.repos).map(toBranchPattern) : [];
+	const result = {
+		_tag: "WorkflowRunTrigger",
+		actions: Object.freeze(config?.actions ? [...config.actions] : []),
+		workflows: Object.freeze(config?.workflows ? [...config.workflows] : []),
+		conclusions: Object.freeze(config?.conclusions ? [...config.conclusions] : []),
+		repos: Object.freeze([...repos]),
+		...config?.description !== void 0 && { description: config.description }
+	};
+	return Object.freeze(result);
+}
+//#endregion
+export { workflowRun };
+
+//# sourceMappingURL=workflow-run.js.map

package/dist/types.d.ts

@@ -0,0 +1,483 @@
+import type { z } from 'zod';
+import type { $ as Shell } from 'zx';
+import type { ResourceRequest } 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';
+import type { Matrix, MatrixInclude, MatrixExclude } from './matrix/types.js';
+import type { HookInput } from './hooks/types.js';
+import type { KiciApi } from './api-types.js';
+import type { DynamicGroupRef } from './dynamic-group.js';
+export type { ResourceRequest, ResourceSpec } from '@kici-dev/engine';
+/** Source location captured at a step() call site. */
+export interface SourceLocation {
+    readonly file: string;
+    readonly line: number;
+    readonly column: number;
+}
+/**
+ * OutputProxy<T> represents a lazy proxy over step/job outputs.
+ * At the type level it mirrors T's shape for type-safe property access.
+ * At runtime it's a Proxy that defers property access to an OutputsMap.
+ */
+export type OutputProxy<T> = {
+    readonly [K in keyof T]: T[K];
+};
+/** Output schema type - record of Zod types */
+export type OutputSchema = Record<string, z.ZodTypeAny>;
+/** Infer the output type from an output schema */
+export type InferOutputs<T extends OutputSchema> = z.infer<z.ZodObject<T>>;
+/**
+ * Step definition returned by step() factory.
+ *
+ * TResult is the inferred return type of the run function (defaults to void for backward compat).
+ * The optional `outputs` field holds a Zod schema for runtime validation but does NOT drive the generic.
+ */
+export interface Step<TResult = void> {
+    readonly _tag: 'Step';
+    /** Step name. Empty string for id-less steps (compiler assigns counter IDs). */
+    readonly name: string;
+    /** Optional Zod schema for runtime output validation. */
+    readonly outputs?: OutputSchema;
+    readonly run: (ctx: StepContext) => Promise<TResult>;
+    /** When true, job proceeds even if this step fails (recorded as failed but not fatal). */
+    readonly continueOnError?: boolean;
+    /** Step-level timeout in milliseconds. Overrides the agent's default (30 minutes). */
+    readonly timeout?: number;
+    /** Step-level conditional rules (evaluated agent-side). */
+    readonly rules?: Rule[];
+    /** Runs on cancellation. */
+    readonly onCancel?: HookInput;
+    /** Always runs after step (success, failure, or cancel). */
+    readonly cleanup?: HookInput;
+    /** Internal: source location captured at step() call site. Not part of public API. */
+    readonly _sourceLocation?: SourceLocation;
+    /**
+     * Type-safe proxy for accessing this step's outputs.
+     * Only meaningful when TResult is non-void. Accessing .result on a void step is a compile-time error.
+     * At runtime, resolves against the shared outputs map populated by the workflow runner.
+     */
+    readonly result: TResult extends void ? never : OutputProxy<TResult>;
+}
+/**
+ * Bare async function accepted directly in the steps array.
+ * Counter-named at compile time, return-type-inferred, no Zod validation.
+ */
+export type BareStepFn<TResult = void> = (ctx: StepContext) => Promise<TResult>;
+/**
+ * Union type for items accepted in a job's steps array.
+ * Accepts both Step objects and bare async functions.
+ */
+export type StepInput = Step<any> | BareStepFn<any>;
+/** Options for step() factory - simple form (just async function) */
+export type StepRunFn = (ctx: StepContext) => Promise<void>;
+/** Options for step() factory - full form with outputs and generic return type */
+export interface StepOptions<TResult = void> {
+    /** Optional Zod schema for runtime output validation. */
+    outputs?: OutputSchema;
+    run: (ctx: StepContext) => Promise<TResult>;
+    /** When true, job proceeds even if this step fails (recorded as failed but not fatal). */
+    continueOnError?: boolean;
+    /** Step-level timeout in milliseconds. Overrides the agent's default (30 minutes). */
+    timeout?: number;
+    /** Step-level conditional rules (evaluated agent-side). */
+    rules?: Rule[];
+    /** Runs on cancellation. */
+    onCancel?: HookInput;
+    /** Always runs after step (success, failure, or cancel). */
+    cleanup?: HookInput;
+}
+/** Trigger type (config objects returned by pr()/push() factory functions) */
+export type Trigger = TriggerConfig;
+/**
+ * Context passed to dynamic job generator functions.
+ * Uses destructured form: async ({$, ctx, log, env}) => jobs
+ *
+ * **Determinism requirement:** the executing agent re-evaluates the DynamicJobFn
+ * to extract step closures (functions can't be serialized). For a given job name,
+ * 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.
+ * - `$`, `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).
+ */
+export interface DynamicJobContext {
+    /** zx shell executor for running commands */
+    $: typeof Shell;
+    /** Event context and workflow metadata */
+    ctx: {
+        workflow: {
+            name: string;
+        };
+        event?: Record<string, unknown>;
+    };
+    /** Structured logger */
+    log: Logger;
+    /** Environment variables */
+    env: Record<string, string | undefined>;
+    /** Typed KiCI API — orchestrator queries over WS (e.g., kici.infrastructure.list()) */
+    kici: KiciApi;
+}
+/**
+ * Async function that generates jobs dynamically at runtime.
+ * Signature: async ({$, ctx, log, env}) => Job[]
+ *
+ * **Determinism contract:** this function is called twice — once during the eval
+ * phase (to discover which jobs to create) and once during execution (to extract
+ * step closures for the specific job being run). The second call must produce a
+ * job with the same name and equivalent steps as the first call.
+ *
+ * A mismatch in sibling job names triggers a warning; a missing target job
+ * causes a hard failure with a clear determinism error.
+ *
+ * See `docs/architecture/dynamic-jobs.md` for the full re-evaluation flow.
+ */
+export type DynamicJobFn = (context: DynamicJobContext) => Promise<Job[]>;
+/**
+ * A job definition or an async function that generates jobs.
+ * Used in workflow jobs array for mixing static and dynamic jobs.
+ */
+export type JobOrFactory = Job | DynamicJobFn;
+/**
+ * Type guard to check if a JobOrFactory is a dynamic job generator.
+ */
+export declare function isDynamicJobFn(item: JobOrFactory): item is DynamicJobFn;
+declare const DYNAMIC_JOB_GROUP_TAG: unique symbol;
+/** A DynamicJobFn tagged with a group name via dynamicJob(). */
+export interface TaggedDynamicJobFn extends DynamicJobFn {
+    readonly [DYNAMIC_JOB_GROUP_TAG]: string;
+}
+/**
+ * Tag a DynamicJobFn with a group name for cross-domain needs.
+ * Static jobs can then depend on this group via `needs: [dynamicGroup('name')]`.
+ *
+ * @param groupName - The group name (must match what static jobs reference)
+ * @param fn - The dynamic job generator function
+ */
+export declare function dynamicJob(groupName: string, fn: DynamicJobFn): 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 };
+/**
+ * Container configuration for job execution.
+ * When set, all steps run inside the specified container.
+ */
+export interface ContainerConfig {
+    /** Docker image name (e.g., 'node:20-alpine') */
+    image: string;
+    /** Additional environment variables for the container */
+    env?: Record<string, string>;
+}
+/**
+ * Structured runsOn selector with required and excluded labels.
+ * Used when jobs need to target specific agents while excluding others.
+ *
+ * **Reserved namespace:** Labels with the `kici:` prefix are reserved for internal use
+ * (e.g., `kici:role:builder`, `kici:role:init-runner`). User-supplied labels starting with
+ * `kici:` will be rejected at compile time and agent startup.
+ */
+export interface RunsOnSelector {
+    labels: string | string[];
+    exclude?: string | string[];
+}
+/**
+ * Polymorphic runsOn type: string shorthand, array shorthand, or full selector object.
+ * - `'linux'` — single label shorthand
+ * - `['linux', 'docker']` — multi-label shorthand
+ * - `{ labels: ['linux', 'docker'], exclude: ['gpu'] }` — full selector with exclusions
+ *
+ * **Reserved namespace:** Labels with the `kici:` prefix are reserved for internal use
+ * (e.g., `kici:role:builder`, `kici:role:init-runner`). User-supplied labels starting with
+ * `kici:` will be rejected at compile time and agent startup.
+ */
+export type RunsOn = string | string[] | RunsOnSelector;
+/** Job definition returned by job() factory */
+export interface Job {
+    readonly _tag: 'Job';
+    readonly name: string;
+    readonly runsOn: RunsOn;
+    readonly steps: readonly StepInput[];
+    readonly needs?: ReadonlyArray<Job | string | DynamicGroupRef | {
+        name: string;
+        ifFailed: 'skip' | 'run';
+    } | {
+        group: string;
+        ifFailed: 'skip' | 'run';
+    }>;
+    /** Rules for conditional execution */
+    readonly rules?: Rule[];
+    /** Optional description */
+    readonly description?: string;
+    /** Matrix configuration (unexpanded) */
+    readonly matrix?: Matrix;
+    /** Include combinations */
+    readonly include?: MatrixInclude[];
+    /** Exclude combinations */
+    readonly exclude?: MatrixExclude[];
+    /** When false, agent skips git clone (default: true). Useful for deploy/notify jobs. */
+    readonly checkout?: boolean;
+    /** Docker image for job execution. All steps run inside the container. */
+    readonly container?: string | ContainerConfig;
+    /** Deployment environment for this job. String for static, async function for dynamic (resolved at orchestrator two-phase eval). */
+    readonly environment?: string | ((event: Record<string, unknown>) => string | Promise<string>);
+    /** Environment variables. Static object or async function (resolved at orchestrator two-phase eval). */
+    readonly env?: Record<string, string> | ((event: Record<string, unknown>) => Record<string, string> | Promise<Record<string, string>>);
+    /** Concurrency group name. Defaults to environment name if not set. String or async function. */
+    readonly concurrencyGroup?: string | ((event: Record<string, unknown>) => string | Promise<string>);
+    /** Runs on cancellation. */
+    readonly onCancel?: HookInput;
+    /** Always runs after job (success, failure, or cancel). */
+    readonly cleanup?: HookInput;
+    /** Runs on job success. */
+    readonly onSuccess?: HookInput;
+    /** Runs on job failure. */
+    readonly onFailure?: HookInput;
+    /** Runs before each step in this job. */
+    readonly beforeStep?: HookInput;
+    /** Runs after each step in this job. */
+    readonly afterStep?: HookInput;
+    /** Seconds before SIGKILL after SIGTERM during cancellation. */
+    readonly gracePeriod?: number;
+    /**
+     * Resource request and limit for this job. Used by the scaler to enforce
+     * per-scaler / per-orchestrator / per-machine caps and the kernel-side limits
+     * on the spawned agent.
+     *
+     * `requests` drive scheduler accounting (cap aggregation).
+     * `limits` drive kernel enforcement (Docker memory + nanoCpus, FC memSizeMib + vcpuCount,
+     * optional bare-metal systemd-run scope).
+     *
+     * If only one side is set, the other inherits its values. If neither is set,
+     * the scaler default applies; if neither is set anywhere, the job counts only
+     * toward the agent-count cap.
+     */
+    readonly resources?: ResourceRequest;
+    /**
+     * Type-safe proxy for accessing this job's outputs.
+     * For multi-step jobs: jobRef.result.stepName.field
+     * For single-step (run shorthand) jobs: jobRef.result.field
+     * At runtime, resolves against the shared job outputs map populated by the workflow runner.
+     */
+    readonly result: OutputProxy<any>;
+}
+/** Options for job() factory */
+export interface JobOptions {
+    runsOn: RunsOn;
+    /**
+     * Steps to execute in this job. Accepts Step objects and bare async functions.
+     * Mutually exclusive with `run`.
+     */
+    steps?: StepInput[];
+    /**
+     * Single-step shorthand: an async function that becomes the job's only step.
+     * Mutually exclusive with `steps`.
+     */
+    run?: (ctx: StepContext) => Promise<any>;
+    needs?: Array<Job | string | DynamicGroupRef | {
+        name: string;
+        ifFailed: 'skip' | 'run';
+    } | {
+        group: string;
+        ifFailed: 'skip' | 'run';
+    }>;
+    /** Rules that must pass for job to execute */
+    rules?: Rule[];
+    /** Optional description for documentation */
+    description?: string;
+    /**
+     * Matrix configuration for job expansion.
+     * - Single dimension: string[] like ['linux', 'mac', 'windows']
+     * - Multi-dimensional: Record like {os: ['linux', 'mac'], node: ['18', '20']}
+     * - Dynamic: async function returning either form
+     */
+    matrix?: Matrix;
+    /**
+     * Additional matrix combinations to include.
+     * Applied after expansion, can add combinations not in original matrix.
+     */
+    include?: MatrixInclude[];
+    /**
+     * Matrix combinations to exclude.
+     * Applied before include, removes matching combinations.
+     */
+    exclude?: MatrixExclude[];
+    /** When false, agent skips git clone (default: true). Useful for deploy/notify jobs. */
+    checkout?: boolean;
+    /**
+     * Docker image for job execution.
+     * Simple string form for image name, object form for additional config.
+     * When set, all steps run inside the container.
+     */
+    container?: string | ContainerConfig;
+    /** Deployment environment for this job. String for static, async function for dynamic (resolved at orchestrator two-phase eval). */
+    environment?: string | ((event: Record<string, unknown>) => string | Promise<string>);
+    /** Environment variables. Static object or async function (resolved at orchestrator two-phase eval). */
+    env?: Record<string, string> | ((event: Record<string, unknown>) => Record<string, string> | Promise<Record<string, string>>);
+    /** Concurrency group name. Defaults to environment name if not set. String or async function. */
+    concurrencyGroup?: string | ((event: Record<string, unknown>) => string | Promise<string>);
+    /** Runs on cancellation. */
+    onCancel?: HookInput;
+    /** Always runs after job (success, failure, or cancel). */
+    cleanup?: HookInput;
+    /** Runs on job success. */
+    onSuccess?: HookInput;
+    /** Runs on job failure. */
+    onFailure?: HookInput;
+    /** Runs before each step in this job. */
+    beforeStep?: HookInput;
+    /** Runs after each step in this job. */
+    afterStep?: HookInput;
+    /** Seconds before SIGKILL after SIGTERM during cancellation. */
+    gracePeriod?: number;
+    /**
+     * Resource request and limit for this job. Used by the scaler to enforce
+     * per-scaler / per-orchestrator / per-machine caps and the kernel-side limits
+     * on the spawned agent.
+     *
+     * `requests` drive scheduler accounting (cap aggregation).
+     * `limits` drive kernel enforcement (Docker memory + nanoCpus, FC memSizeMib + vcpuCount,
+     * optional bare-metal systemd-run scope).
+     *
+     * If only one side is set, the other inherits its values. If neither is set,
+     * the scaler default applies; if neither is set anywhere, the job counts only
+     * toward the agent-count cap.
+     */
+    resources?: ResourceRequest;
+}
+/**
+ * Private npm registry declaration. Tells the agent to authenticate against
+ * a private package registry before running `npm install`.
+ *
+ * `tokenSecret` uses qualified `<environment>:<secret-name>` syntax — the
+ * orchestrator resolves the secret from the named environment's scoped secret
+ * store at dispatch time. Example: `tokenSecret: 'production:NPM_TOKEN'`.
+ */
+export interface Registry {
+    /** Registry URL (e.g. `https://npm.pkg.github.com`). */
+    readonly url: string;
+    /**
+     * Optional npm package scope this registry serves (e.g. `@my-org`).
+     * If omitted, the registry becomes the default (only one default per workflow).
+     */
+    readonly scope?: string;
+    /**
+     * Qualified secret reference of the form `<environment>:<secret-name>`.
+     * The orchestrator resolves it at dispatch via `secretResolver.resolveForJob(orgId, environment)`.
+     */
+    readonly tokenSecret: string;
+    /** Whether to require auth on every request (rendered as `always-auth=true` in `.npmrc`). Defaults to `true`. */
+    readonly alwaysAuth?: boolean;
+}
+/** Workflow definition returned by workflow() factory */
+export interface Workflow {
+    readonly _tag: 'Workflow';
+    readonly name: string;
+    /**
+     * Jobs array (may contain static jobs and dynamic job generators).
+     * Dynamic generators are expanded at agent runtime.
+     */
+    readonly jobs: JobOrFactory[];
+    /** Trigger configs (built from Trigger instances) */
+    readonly on?: TriggerConfig[];
+    /** Rules for conditional execution */
+    readonly rules?: Rule[];
+    /** Optional description */
+    readonly description?: string;
+    /**
+     * Optional paths or glob patterns (relative to repo root) to include in the workflow content hash.
+     * When any of these files change, the lock file content hash changes so cache is invalidated.
+     */
+    readonly hashFiles?: string[];
+    /**
+     * Private npm registries the agent should authenticate against before `npm install`.
+     * Each registry's `tokenSecret` uses qualified `<environment>:<secret-name>` syntax.
+     */
+    readonly registries?: readonly Registry[];
+    /**
+     * Extra secrets to project as environment variables on the install subprocess.
+     * Used together with a customer-committed `.kici/.npmrc` containing `${VAR}` placeholders.
+     * Each entry uses qualified `<environment>:<secret-name>` syntax; the resolved value is
+     * exposed to the install subprocess under the `<secret-name>` key (the environment
+     * prefix is stripped for the env-var name).
+     */
+    readonly installEnv?: readonly string[];
+    /** Runs on cancellation. */
+    readonly onCancel?: HookInput;
+    /** Always runs after workflow (success, failure, or cancel). */
+    readonly cleanup?: HookInput;
+    /** Runs on workflow success. */
+    readonly onSuccess?: HookInput;
+    /** Runs on workflow failure. */
+    readonly onFailure?: HookInput;
+    /** Concurrency configuration for this workflow. */
+    readonly concurrency?: {
+        readonly group: (ctx: {
+            branch: string;
+            event: Record<string, unknown>;
+        }) => string;
+        readonly cancelInProgress?: boolean;
+        readonly max?: number;
+    };
+}
+/** Options for workflow() factory */
+export interface WorkflowOptions {
+    /**
+     * Jobs in the workflow.
+     * Can be static Job objects or async functions that generate jobs.
+     * Dynamic job functions are evaluated at agent runtime.
+     */
+    jobs: JobOrFactory[];
+    /** Trigger conditions - when should this workflow run */
+    on?: Trigger | Trigger[];
+    /** Rules that must pass for workflow to execute */
+    rules?: Rule[];
+    /** Optional description for documentation */
+    description?: string;
+    /**
+     * Optional paths or glob patterns (relative to repo root) to include in the workflow content hash.
+     * When any of these files change, the lock file content hash changes so cache is invalidated.
+     */
+    hashFiles?: string[];
+    /**
+     * Private npm registries the agent should authenticate against before `npm install`.
+     * Each registry's `tokenSecret` uses qualified `<environment>:<secret-name>` syntax.
+     */
+    registries?: Registry[];
+    /**
+     * Extra secrets to project as environment variables on the install subprocess.
+     * Used together with a customer-committed `.kici/.npmrc` containing `${VAR}` placeholders.
+     * Each entry uses qualified `<environment>:<secret-name>` syntax; the resolved value is
+     * exposed to the install subprocess under the `<secret-name>` key.
+     */
+    installEnv?: string[];
+    /** Runs on cancellation. */
+    onCancel?: HookInput;
+    /** Always runs after workflow (success, failure, or cancel). */
+    cleanup?: HookInput;
+    /** Runs on workflow success. */
+    onSuccess?: HookInput;
+    /** Runs on workflow failure. */
+    onFailure?: HookInput;
+    /** Concurrency configuration for this workflow. */
+    concurrency?: {
+        group: (ctx: {
+            branch: string;
+            event: Record<string, unknown>;
+        }) => string;
+        cancelInProgress?: boolean;
+        max?: number;
+    };
+}
+export type { TriggerConfig, PrTriggerConfig, PushTriggerConfig } from './triggers/types.js';
+export type { Rule, RuleContext, RuleCheckFn, RuleResult } from './rules/types.js';
+export type { Matrix, MatrixInclude, MatrixExclude, MatrixValues } from './matrix/types.js';
+export type { HookInput, HookFn, HookConfig, HookContext, OutcomeMetadata } from './hooks/types.js';
+//# sourceMappingURL=types.d.ts.map

package/dist/types.js

@@ -0,0 +1,35 @@
+import "./chunk-gOLHoazu.js";
+//#region src/types.ts
+/**
+* Type guard to check if a JobOrFactory is a dynamic job generator.
+*/
+function isDynamicJobFn(item) {
+	return typeof item === "function";
+}
+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')]`.
+*
+* @param groupName - The group name (must match what static jobs reference)
+* @param fn - The dynamic job generator function
+*/
+function dynamicJob(groupName, fn) {
+	const tagged = fn;
+	Object.defineProperty(tagged, DYNAMIC_JOB_GROUP_TAG, {
+		value: groupName,
+		enumerable: false
+	});
+	return tagged;
+}
+/**
+* Get the group name from a DynamicJobFn, if it was tagged with dynamicJob().
+* Returns undefined for untagged functions.
+*/
+function getDynamicJobGroup(fn) {
+	return fn[DYNAMIC_JOB_GROUP_TAG];
+}
+//#endregion
+export { DYNAMIC_JOB_GROUP_TAG, dynamicJob, getDynamicJobGroup, isDynamicJobFn };
+
+//# sourceMappingURL=types.js.map

package/dist/validation/dag.d.ts

@@ -0,0 +1,42 @@
+/**
+ * Represents a node in a Directed Acyclic Graph.
+ * Used for validating job dependency graphs.
+ */
+export interface DagNode {
+    id: string;
+    needs: string[];
+}
+/**
+ * Result of DAG validation.
+ * Discriminated union for different validation outcomes.
+ */
+export type DagValidationResult = {
+    valid: true;
+    sortedOrder: string[];
+} | {
+    valid: false;
+    error: 'cycle';
+    nodesInCycle: string[];
+} | {
+    valid: false;
+    error: 'self-reference';
+    nodeId: string;
+} | {
+    valid: false;
+    error: 'missing-dependency';
+    nodeId: string;
+    missingDep: string;
+};
+/**
+ * Validate a DAG for common issues: self-references, missing dependencies, and cycles.
+ *
+ * Validation order:
+ * 1. Check for self-references (node depends on itself)
+ * 2. Check for missing dependencies (depends on non-existent node)
+ * 3. Check for cycles using Kahn's algorithm
+ *
+ * @param nodes - Array of DAG nodes to validate
+ * @returns Validation result with error details or sorted order
+ */
+export declare function validateDag(nodes: DagNode[]): DagValidationResult;
+//# sourceMappingURL=dag.d.ts.map