@kici-dev/sdk 0.4.0 → 0.6.0

package/dist/git-types.js

@@ -0,0 +1,32 @@
+import "./rolldown-runtime-ClRpJifh.js";
+//#region src/git-types.ts
+/**
+* Resolve a call site's credential.
+*
+* Order: an explicit per-call value wins; otherwise `default` from the job map;
+* otherwise undefined, which means the source credential — all a read needs.
+*
+* An unknown name THROWS rather than falling back to `default`: silently using
+* a different credential than the author named is precisely the confusion this
+* map exists to remove.
+*/
+function resolveCredential(perCall, map) {
+	if (perCall && typeof perCall === "object") return perCall;
+	if (typeof perCall === "string") {
+		const found = map?.[perCall];
+		if (!found) throw new Error(`Unknown git credential '${perCall}'. Declare it in the job's gitCredentials map. Known: ${Object.keys(map ?? {}).join(", ") || "(none)"}`);
+		return found;
+	}
+	return map?.default;
+}
+/**
+* Every credential field names a secret. Catch the easy, silent mistake of
+* pasting the credential itself — which would commit it to a git repository.
+*/
+function assertSecretName(value, field, subject = "git credential") {
+	if (value.startsWith("-----BEGIN") || /^gh[pousr]_/.test(value) || value.startsWith("github_pat_")) throw new Error(`${subject} '${field}' looks like the credential itself, not the name of a secret holding it. Store it with \`kici-admin secret set\` and name it here.`);
+}
+//#endregion
+export { assertSecretName, resolveCredential };
+
+//# sourceMappingURL=git-types.js.map

package/dist/idempotent.js

@@ -83,7 +83,7 @@ function idempotentStep(name, opts) {
 * lockfile change.
 */
 function checkStep(name, options) {
-	return step(name, {
+	const checkOptions = {
 		check: options.check,
 		summarize: options.summarize,
 		run: (ctx, drift) => options.apply(ctx, drift),
@@ -94,7 +94,8 @@ function checkStep(name, options) {
 		...options.retry !== void 0 && { retry: options.retry },
 		...options.cache !== void 0 && { cache: options.cache },
 		...options.rules !== void 0 && { rules: options.rules }
-	});
+	};
+	return step(name, checkOptions);
 }
 //#endregion
 export { checkStep, idempotent, idempotentStep };

package/dist/index.d.ts

@@ -3,6 +3,8 @@ export { job } from './job.js';
 export { workflow } from './workflow.js';
 export { parallel, isParallelGroup, flattenStepInputs } from './parallel.js';
 export type { ParallelGroup, ParallelOptions } from './parallel.js';
+export { invokeSource } from './invoke.js';
+export type { InvokeConfig } from './invoke.js';
 export { normalizeApproval } from './approval.js';
 export type { ApprovalConfig, ApprovalWhen, ApproverClause, NormalizedApproval, } from './approval.js';
 export { pr, push, tag, comment, review, reviewComment, release, dispatch, create, delete as delete, status, workflowRun, fork, star, watch, webhook, kiciEvent, workflowComplete, workflowsFailedBatch, jobComplete, genericWebhook, schedule, lifecycle, defineDispatchInputs, } from './triggers/index.js';
@@ -21,7 +23,7 @@ export type { SourceLocation, OutputProxy, Step, StepOptions, StepOptionsBase, S
 export { isDynamicJobFn, dynamicJob, getDynamicJobGroup, getDynamicJobNeeds, DYNAMIC_JOB_GROUP_TAG, DYNAMIC_JOB_NEEDS_TAG, } from './types.js';
 export type { TaggedDynamicJobFn, ResultAwareDynamicJobConfig, ResultAwareDynamicJobFn, DynamicJobNeed, NeedsWhen, NeedsWhenInput, } from './types.js';
 export { buildNeedsContext } from './needs-context.js';
-export type { UpstreamSnapshot, NeedsContext, NeedEntry, GroupNeedEntry } from './needs-context.js';
+export type { UpstreamSnapshot, NeedsContext, NeedEntry, GroupNeedEntry, InvokeNeedEntry, InvokeResult, } 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';
@@ -33,6 +35,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';
@@ -58,4 +63,9 @@ export type { WaitForHostAliveOptions, RestartHostOptions } from './host-restart
 export { agentVersionConverge } from './fleet/agent-version-converge.js';
 export type { AgentVersionConvergeOptions, AgentVersionDrift, } from './fleet/agent-version-converge.js';
 export { z } from 'zod';
+export { SCALER_EVENT_NAMES, ScaleDownReason, ScalerScaleUpPayload, ScalerScaleDownPayload, } from '@kici-dev/engine';
+export { buildAgentCloudInit } from './agent-cloud-init.js';
+export type { CloudInitCredentials, ClaimCodeCredentials, AgentCloudInitCredentials, AgentDeliveryMode, UserDataEncoding, CloudInitWriteFile, AgentCloudInitOptions, } from './agent-cloud-init.js';
+export { assertSecretName } from './git-types.js';
+export type { ForgeName, GitHubPermissions, WriteOptions, GitGrant, Sourced, ContainerRegistryAuth, GitCredentialRef, GitCredentialMap, RepoHandle, GitTokenResult, GitHubApi, GitApi, } from './git-types.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,4 +1,5 @@
 import "./rolldown-runtime-ClRpJifh.js";
+import { buildAgentCloudInit } from "./agent-cloud-init.js";
 import { buildKiciApi } from "./api-types.js";
 import { normalizeApproval } from "./approval.js";
 import { ARTIFACT_NAME_MAX_LENGTH, ArtifactNameSchema } from "./artifacts-types.js";
@@ -6,15 +7,19 @@ import { CacheSpecSchema, normalizeCacheSpecs } from "./cache-types.js";
 import { isHostJobOutputs, isMatrixJobOutputs } from "./context.js";
 import { DYNAMIC_GROUP_TAG, dynamicGroup, isDynamicGroupRef } from "./dynamic-group.js";
 import { SecretNotFoundError } from "./errors.js";
-import { fixture } from "./fixture.js";
+import { ChangedFilesUnavailableError } from "./rules/changed-files.js";
+import { createFilterContext } from "./filter-context.js";
+import { workflow } from "./workflow.js";
 import { createJobOutputProxy, createSnapshotOutputProxy, createStepOutputProxy, getJobOutputsMap, getStepOutputsMap, getStepRefMap, resolveJobOutputs, resolveStepOutputs, setJobOutputsMap, setStepOutputsMap, setStepRefMap } from "./outputs.js";
+import { assertSecretName } from "./git-types.js";
+import { job } from "./job.js";
 import { step } from "./step.js";
+import { fixture } from "./fixture.js";
 import { WaitForTimeoutError, waitFor, waitForStep } from "./wait-for.js";
 import { restartHost, waitForHostAlive } from "./host-restart.js";
 import { checkStep, idempotent, idempotentStep } from "./idempotent.js";
-import { job } from "./job.js";
-import { workflow } from "./workflow.js";
 import { flattenStepInputs, isParallelGroup, parallel } from "./parallel.js";
+import { invokeSource } from "./invoke.js";
 import { pr } from "./triggers/pr.js";
 import { push } from "./triggers/push.js";
 import { tag } from "./triggers/tag.js";
@@ -42,7 +47,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";
@@ -58,5 +63,6 @@ import "./matrix/index.js";
 import { defineEvent, isEventDefinition } from "./events/define-event.js";
 import "./events/index.js";
 import { agentVersionConverge } from "./fleet/agent-version-converge.js";
+import { SCALER_EVENT_NAMES, ScaleDownReason, ScalerScaleDownPayload, ScalerScaleUpPayload } from "@kici-dev/engine";
 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, SCALER_EVENT_NAMES, ScaleDownReason, ScalerScaleDownPayload, ScalerScaleUpPayload, SecretNotFoundError, WaitForTimeoutError, afterStep, agentVersionConverge, applyIncludeExclude, assertSecretName, beforeStep, buildAgentCloudInit, 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, invokeSource, 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/invoke.d.ts

@@ -0,0 +1,29 @@
+/** Config produced by {@link invokeSource}: emit a kici event at the source repo and gate on the runs it triggers. */
+export interface InvokeConfig {
+    readonly _tag: 'InvokeSource';
+    /** The kici event name to emit. Subscribers opt in with `kiciEvent({ name })`. */
+    readonly event: string;
+    /** Target scope. `'source'` targets exactly `ctx.sourceRepo` (the only v1 scope). */
+    readonly scope: 'source';
+    /** Optional event payload delivered to subscribers. */
+    readonly payload?: Readonly<Record<string, unknown>>;
+    /**
+     * When true, a zero-subscriber emit succeeds immediately (the repo may opt out).
+     * When false/unset (the default), a zero-subscriber emit FAILS the gate — a repo
+     * that never wired up its tests must not silently pass the org gate.
+     */
+    readonly optional?: boolean;
+}
+/**
+ * Invoke the source repo's opt-in workflows and gate on them.
+ *
+ * Targets exactly `ctx.sourceRepo`, so a global workflow can hand control back to
+ * the repo whose event triggered it without any org-wide fan-out. Subscribers opt
+ * in with `kiciEvent({ name })`. Required by default: if no workflow subscribes,
+ * the gate fails unless `optional: true` is set.
+ */
+export declare function invokeSource(event: string, opts?: {
+    payload?: Record<string, unknown>;
+    optional?: boolean;
+}): InvokeConfig;
+//# sourceMappingURL=invoke.d.ts.map

package/dist/invoke.js

@@ -0,0 +1,27 @@
+import "./rolldown-runtime-ClRpJifh.js";
+import { reservedEventNamePrefix } from "@kici-dev/engine";
+//#region src/invoke.ts
+/**
+* Invoke the source repo's opt-in workflows and gate on them.
+*
+* Targets exactly `ctx.sourceRepo`, so a global workflow can hand control back to
+* the repo whose event triggered it without any org-wide fan-out. Subscribers opt
+* in with `kiciEvent({ name })`. Required by default: if no workflow subscribes,
+* the gate fails unless `optional: true` is set.
+*/
+function invokeSource(event, opts) {
+	if (typeof event !== "string" || event.trim().length === 0) throw new Error("invokeSource: event name must be a non-empty string");
+	const reservedPrefix = reservedEventNamePrefix(event);
+	if (reservedPrefix) throw new Error(`invokeSource: event name prefix "${reservedPrefix}" is reserved for KiCI internal events (got "${event}")`);
+	return Object.freeze({
+		_tag: "InvokeSource",
+		event,
+		scope: "source",
+		...opts?.payload !== void 0 && { payload: Object.freeze({ ...opts.payload }) },
+		...opts?.optional === true && { optional: true }
+	});
+}
+//#endregion
+export { invokeSource };
+
+//# sourceMappingURL=invoke.js.map

package/dist/job-outputs.test-d.js

@@ -1,30 +1,34 @@
 import "./rolldown-runtime-ClRpJifh.js";
 import { isHostJobOutputs, isMatrixJobOutputs } from "./context.js";
 import { dynamicGroup } from "./dynamic-group.js";
-import { step } from "./step.js";
-import { job } from "./job.js";
 import { workflow } from "./workflow.js";
+import { job } from "./job.js";
+import { step } from "./step.js";
 import { describe, expectTypeOf, it } from "vitest";
 //#region src/job-outputs.test-d.ts
 describe("Job<TOutputs> — merged-steps inference", () => {
 	it("infers a nested output map keyed by step name for a multi-step job", () => {
+		const build = step("build", { run: async () => ({ version: "1.0" }) });
+		const test_ = step("test", { run: async () => ({ passed: true }) });
 		const j = job("ci", {
 			runsOn: "kici:os:linux",
-			steps: [step("build", { run: async () => ({ version: "1.0" }) }), step("test", { run: async () => ({ passed: true }) })]
+			steps: [build, test_]
 		});
 		expectTypeOf(j.result.build.version).toEqualTypeOf();
 		expectTypeOf(j.result.test.passed).toEqualTypeOf();
 	});
 	it("rejects reading an unknown output field of a declared step", () => {
+		const build = step("build", { run: async () => ({ version: "1.0" }) });
 		job("ci", {
 			runsOn: "kici:os:linux",
-			steps: [step("build", { run: async () => ({ version: "1.0" }) })]
+			steps: [build]
 		}).result.build.nope;
 	});
 	it("rejects reading an undeclared step name", () => {
+		const build = step("build", { run: async () => ({ version: "1.0" }) });
 		job("ci", {
 			runsOn: "kici:os:linux",
-			steps: [step("build", { run: async () => ({ version: "1.0" }) })]
+			steps: [build]
 		}).result.other;
 	});
 	it("infers a flat output shape for the run: shorthand", () => {
@@ -36,22 +40,26 @@ describe("Job<TOutputs> — merged-steps inference", () => {
 		flat.result.nope;
 	});
 	it("honours an explicit output-type override for a dynamically-shaped job", () => {
-		expectTypeOf(job("dyn", {
+		const dyn = job("dyn", {
 			runsOn: "kici:os:linux",
 			steps: [step(async () => ({}))]
-		}).result.n).toEqualTypeOf();
+		});
+		expectTypeOf(dyn.result.n).toEqualTypeOf();
 	});
 	it("omits id-less steps and falls back to the loose shape", () => {
-		expectTypeOf(job("idless", {
+		const j = job("idless", {
 			runsOn: "kici:os:linux",
 			steps: [step(async () => ({ x: 1 }))]
-		}).result.anything).toEqualTypeOf();
+		});
+		expectTypeOf(j.result.anything).toEqualTypeOf();
 	});
 	it("keeps a typed job assignable to the bare Job type", () => {
-		expectTypeOf(job("ci", {
+		const build = step("build", { run: async () => ({ version: "1.0" }) });
+		const anyJob = job("ci", {
 			runsOn: "kici:os:linux",
-			steps: [step("build", { run: async () => ({ version: "1.0" }) })]
-		})).toEqualTypeOf();
+			steps: [build]
+		});
+		expectTypeOf(anyJob).toEqualTypeOf();
 	});
 });
 describe("Job<void> — void run-shorthand assignability", () => {
@@ -75,10 +83,11 @@ describe("Job<void> — void run-shorthand assignability", () => {
 		workflow("wf", { jobs: [setup] });
 	});
 	it("resolves result to never for a void run-shorthand job", () => {
-		expectTypeOf(job("setup", {
+		const setup = job("setup", {
 			runsOn: "kici:os:linux",
 			run: async () => {}
-		}).result).toEqualTypeOf();
+		});
+		expectTypeOf(setup.result).toEqualTypeOf();
 	});
 	it("leaves a value-returning run job untouched (regression guard)", () => {
 		const flat = job("flat", {
@@ -90,9 +99,11 @@ describe("Job<void> — void run-shorthand assignability", () => {
 	});
 });
 describe("typed ctx.needs from job references", () => {
+	const build = step("build", { run: async () => ({ version: "1.0" }) });
+	const test_ = step("test", { run: async () => ({ passed: true }) });
 	const ci = job("ci", {
 		runsOn: "kici:os:linux",
-		steps: [step("build", { run: async () => ({ version: "1.0" }) }), step("test", { run: async () => ({ passed: true }) })]
+		steps: [build, test_]
 	});
 	it("threads a referenced job’s inferred outputs into ctx.needs", () => {
 		job("deploy", {
@@ -135,13 +146,15 @@ describe("typed ctx.needs from job references", () => {
 	});
 });
 describe("envelope-generic jobOutputs for typed refs", () => {
+	const build = step("build", { run: async () => ({ version: "1.0" }) });
 	const ci = job("ci", {
 		runsOn: "kici:os:linux",
-		steps: [step("build", { run: async () => ({ version: "1.0" }) })]
+		steps: [build]
 	});
 	const ctx = null;
 	it("types a job-ref jobOutputs as the plain | matrix | host union of the inferred shape", () => {
-		expectTypeOf(ctx.jobOutputs(ci)).toEqualTypeOf();
+		const out = ctx.jobOutputs(ci);
+		expectTypeOf(out).toEqualTypeOf();
 	});
 	it("narrows to the typed matrix envelope via isMatrixJobOutputs", () => {
 		const out = ctx.jobOutputs(ci);
@@ -155,7 +168,8 @@ describe("envelope-generic jobOutputs for typed refs", () => {
 		if (isHostJobOutputs(out)) expectTypeOf(out.byHost).toEqualTypeOf();
 	});
 	it("keeps a string-name ref on the loose union", () => {
-		expectTypeOf(ctx.jobOutputs({ name: "ci" })).toEqualTypeOf();
+		const out = ctx.jobOutputs({ name: "ci" });
+		expectTypeOf(out).toEqualTypeOf();
 	});
 });
 //#endregion

package/dist/job.js

@@ -1,5 +1,6 @@
 import "./rolldown-runtime-ClRpJifh.js";
 import { createJobOutputProxy } from "./outputs.js";
+import { assertSecretName } from "./git-types.js";
 import { isKnownCapability } from "@kici-dev/engine";
 import { randomUUID } from "node:crypto";
 //#region src/job.ts
@@ -38,6 +39,7 @@ function validateSandbox(sandbox, jobName) {
 function job(nameOrOptions, maybeOptions) {
 	const name = typeof nameOrOptions === "string" ? nameOrOptions : randomUUID();
 	const options = typeof nameOrOptions === "string" ? maybeOptions : nameOrOptions;
+	if (options.invoke && ((options.steps?.length ?? 0) > 0 || "run" in options)) throw new Error(`job('${name}'): 'invoke' is mutually exclusive with 'steps'/'run'`);
 	let steps = options.steps ?? [];
 	if (options.run) {
 		if (options.steps && options.steps.length > 0) throw new Error("job() cannot have both \"run\" and \"steps\" -- use one or the other");
@@ -49,7 +51,10 @@ function job(nameOrOptions, maybeOptions) {
 	const concurrencyGroup = options.concurrencyGroup ?? (typeof firstContext === "string" ? firstContext : void 0);
 	if (options.context !== void 0 && options.contexts !== void 0) throw new Error(`job('${name}'): context and contexts are mutually exclusive — use one`);
 	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.container !== void 0) validateContainerImageSource(name, options.container);
+	if (options.container && typeof options.container === "object" && options.container.auth) validateContainerAuth(name, options.container.auth);
+	if (options.gitCredentials) validateGitCredentials(name, options.gitCredentials);
+	if (options.invoke === void 0 && 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`);
 	if (options.includeUninitialized !== void 0 && options.runsOnAll === void 0) console.warn(`[kici] job('${name}'): includeUninitialized is ignored without runsOnAll`);
 	return {
@@ -61,6 +66,7 @@ function job(nameOrOptions, maybeOptions) {
 		...options.includeUninitialized !== void 0 && { includeUninitialized: options.includeUninitialized },
 		...options.maxParallel !== void 0 && { maxParallel: options.maxParallel },
 		...options.failFast !== void 0 && { failFast: options.failFast },
+		...options.invoke !== void 0 && { invoke: options.invoke },
 		steps,
 		needs: options.needs,
 		rules: options.rules,
@@ -69,6 +75,7 @@ function job(nameOrOptions, maybeOptions) {
 		include: options.include,
 		exclude: options.exclude,
 		checkout: options.checkout,
+		...options.gitCredentials && { gitCredentials: options.gitCredentials },
 		container: options.container,
 		...options.sandbox !== void 0 && { sandbox: options.sandbox },
 		context: options.context,
@@ -90,6 +97,91 @@ function job(nameOrOptions, maybeOptions) {
 		result: createJobOutputProxy(name)
 	};
 }
+/**
+* Validate a job's named git credentials at definition time.
+*
+* Every `*Secret` field is a qualified `<context>:<secret-name>` reference into
+* the secrets backend — the same form `workflow()` enforces for
+* `registries[].tokenSecret`. Catching a pasted credential here matters because
+* the alternative is committing it to a git repository and discovering it later
+* as a confusing auth failure.
+*/
+/**
+* Validate a job's container registry auth at definition time.
+*
+* Same contract as `gitCredentials`: every `*Secret` field is a qualified
+* `<context>:<secret-name>` reference, and a pasted credential is refused
+* rather than committed to a git repository. The `*Value` half is material
+* supplied at run time and is deliberately not checked for shape.
+*/
+/**
+* Is `p` a repo-relative path that stays inside the repository?
+*
+* Rejects an absolute path and any path whose `..` segments walk out of the
+* tree. Deliberately string-only: the workflow is authored on one machine and
+* the path is resolved on another, so there is no filesystem here to consult.
+*/
+function isInsideRepo(p) {
+	if (p.startsWith("/") || /^[A-Za-z]:[\\/]/.test(p)) return false;
+	let depth = 0;
+	for (const part of p.split(/[\\/]+/)) {
+		if (part === "" || part === ".") continue;
+		if (part === "..") {
+			depth -= 1;
+			if (depth < 0) return false;
+			continue;
+		}
+		depth += 1;
+	}
+	return true;
+}
+/**
+* A container names exactly one image source: a finalized `image`, or a
+* `dockerfile` the agent builds before the job runs.
+*
+* Refused at definition time rather than at dispatch, because the author is the
+* only one who can fix it and the workflow file is where they are looking. The
+* agent re-checks the paths against the real workdir — a lock file is repo
+* content and is not trusted — but that failure reaches a run log, not an
+* editor.
+*/
+function validateContainerImageSource(name, container) {
+	if (typeof container === "string") return;
+	const hasImage = typeof container.image === "string" && container.image.length > 0;
+	const hasDockerfile = typeof container.dockerfile === "string" && container.dockerfile.length > 0;
+	if (hasImage === hasDockerfile) throw new Error(`job('${name}'): exactly one of container.image or container.dockerfile is required`);
+	if (!hasDockerfile) {
+		for (const field of [
+			"context",
+			"target",
+			"args"
+		]) if (container[field] !== void 0) throw new Error(`job('${name}'): container.${field} applies only to container.dockerfile`);
+		return;
+	}
+	if (!isInsideRepo(container.dockerfile)) throw new Error(`job('${name}'): container.dockerfile must stay inside the repository (got: ${container.dockerfile})`);
+	if (container.context !== void 0 && !isInsideRepo(container.context)) throw new Error(`job('${name}'): container.context must stay inside the repository (got: ${container.context})`);
+	if (container.auth && typeof container.auth.registry !== "string") throw new Error(`job('${name}'): container.auth.registry is required with container.dockerfile — the base image is named inside the Dockerfile, so the registry cannot be derived`);
+}
+function validateContainerAuth(name, auth) {
+	const bag = auth;
+	for (const [field, value] of Object.entries(bag)) {
+		if (!field.endsWith("Secret") || typeof value !== "string") continue;
+		assertSecretName(value, field, "container registry credential");
+		const idx = value.indexOf(":");
+		if (idx <= 0 || idx >= value.length - 1 || value.slice(idx + 1).includes(":")) throw new Error(`job('${name}'): container.auth.${field} must use qualified <context>:<secret-name> syntax (got: ${value})`);
+	}
+}
+function validateGitCredentials(name, credentials) {
+	for (const [alias, ref] of Object.entries(credentials)) {
+		const bag = ref;
+		for (const [field, value] of Object.entries(bag)) {
+			if (!field.endsWith("Secret") || typeof value !== "string") continue;
+			assertSecretName(value, `${alias}.${field}`);
+			const idx = value.indexOf(":");
+			if (idx <= 0 || idx >= value.length - 1 || value.slice(idx + 1).includes(":")) throw new Error(`job('${name}'): gitCredentials.${alias}.${field} must use qualified <context>:<secret-name> syntax (got: ${value})`);
+		}
+	}
+}
 //#endregion
 export { job };
 

package/dist/needs-context.d.ts

@@ -14,6 +14,23 @@ export interface UpstreamSnapshot {
     jobs: Record<string, Record<string, unknown>>;
     groups: Record<string, string[]>;
     statuses?: Record<string, ExecutionJobStatus>;
+    /**
+     * Maps an invoke-gate job name to its ordered per-run results, one entry per
+     * run the gate triggered. Present only when the upstream is an invoke gate.
+     */
+    invokeResults?: Record<string, InvokeResult[]>;
+}
+/**
+ * One invoked-run result exposed on an invoke-gate upstream's
+ * `ctx.needs[gate].result` array — one entry per run the gate triggered.
+ * `outputs` carries the invoked run's non-secret declared outputs.
+ */
+export interface InvokeResult {
+    readonly repo: string;
+    readonly workflow: string;
+    readonly runId: string;
+    readonly status: string;
+    readonly outputs: Readonly<Record<string, unknown>>;
 }
 /**
  * A single-job need entry: the upstream's outputs proxy plus its terminal
@@ -31,8 +48,20 @@ export interface GroupNeedEntry<T = Record<string, unknown>> {
     result: OutputProxy<T>;
     status: ExecutionJobStatus;
 }
-/** A single-job need exposes `{ result, status }`; a group need exposes an ordered array. */
-export type NeedEntry<T = Record<string, unknown>> = SingleNeedEntry<T> | GroupNeedEntry[];
+/**
+ * An invoke-gate need entry: `ctx.needs['<gate>'].result` is an ordered array of
+ * {@link InvokeResult}, one per run the gate triggered.
+ */
+export interface InvokeNeedEntry {
+    result: readonly InvokeResult[];
+}
+/**
+ * A single-job need exposes `{ result, status }`; a group need exposes an
+ * ordered array of `{ name, result, status }`; an invoke-gate need exposes
+ * `{ result }` — an ordered array of {@link InvokeResult} on `.result`, one per
+ * triggered run.
+ */
+export type NeedEntry<T = Record<string, unknown>> = SingleNeedEntry<T> | GroupNeedEntry[] | InvokeNeedEntry;
 /** The resolved `ctx.needs` map keyed by job name or group name. */
 export type NeedsContext = Record<string, NeedEntry>;
 /**

package/dist/needs-context.js

@@ -34,7 +34,9 @@ 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) => ({
+		const invokeResults = snapshot.invokeResults?.[key];
+		if (kind === "job" && invokeResults !== void 0) out[key] = { result: invokeResults };
+		else if (kind === "group") out[key] = (snapshot.groups[key] ?? []).map((name) => ({
 			name,
 			result: createSnapshotOutputProxy(name, snapshot.jobs[name]),
 			status: statusFor(snapshot, name)

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