@olivervea/pipelines 2.0.0-beta.1 → 2.0.0-beta.10

package/src/builder/pipeline.ts

@@ -3,10 +3,12 @@ import type { AnyModel, Infer, InferInput, Plain } from "../core/models.ts";
 import type { Secret } from "../core/secrets.ts";
 import type { AnyStep, OutputValue, Step } from "../core/steps.ts";
 import { isStep } from "../core/steps.ts";
+import type { WebhookEvent, WebhookVerify } from "../core/webhooks.ts";
 import type { IsUnion, OrError, Simplify } from "../core/types.ts";
 import type { Optional } from "../core/models.ts";
 import type { FailureContext } from "../library/models.ts";
 import type { MapperResult, Ref } from "./refs.ts";
+import { isConfigRef, narrowConfigRef, unionAt, type ConfigNode, type ConfigRef, type DiscriminatorOf, type VariantOf } from "../core/config.ts";
 
 // ─── Availability (builder state, type level) ────────────────────────────────────────────────
 
@@ -70,7 +72,7 @@ type SiblingNames<E extends readonly unknown[], K> = {
 }[number];
 
 /**
- * Per-entry check. Inference constraints (see spikes/sdk-types):
+ * Per-entry check. Inference constraints:
  *  - the [step, mapper] branch must be exactly `readonly [S, (from) => …]` — wrapping S or the whole
  *    mapper type in a conditional/intersection breaks inference of E or contextual typing of `from`;
  *    so name errors of tuple entries are reported on the mapper's return type instead;
@@ -95,6 +97,29 @@ type OutputsOf<E extends readonly unknown[], Maybe extends boolean> = {
 };
 type MakeMaybe<X extends AvailMap> = { [K in keyof X]: Slot<X[K]["model"], X[K]["value"], true> };
 
+// ─── select (branching on config) ────────────────────────────────────────────────────────────
+
+type KeysOfUnion<T> = T extends unknown ? keyof T : never;
+type SlotIn<B, K extends PropertyKey> = B extends { [P in K]: infer X extends Slot } ? X : never;
+/** A case function: the pipeline so far, and the select's reference narrowed to the case's variant. */
+export type SelectCase<In extends AnyModel, A extends AvailMap, R> = (p: Pipeline<In, A>, ref: R) => Pipeline<In, AvailMap>;
+export type SelectCases<In extends AnyModel, A extends AvailMap, U, D extends string> = {
+  readonly [V in Extract<U[D & keyof U], string>]: SelectCase<In, A, ConfigNode<VariantOf<U, D, V>>>;
+};
+type CaseAvail<C> = { [K in keyof C]: C[K] extends (...args: never[]) => Pipeline<AnyModel, infer B> ? B : never }[keyof C];
+/**
+ * After a select: a step every case has is as available as in its cases (one case always runs);
+ * a step only some cases have is maybe-available.
+ */
+export type AfterSelect<A extends AvailMap, B> = Simplify<
+  A &
+    { [K in Exclude<keyof B, keyof A>]: Slot<SlotIn<B, K>["model"], SlotIn<B, K>["value"], SlotIn<B, K>["maybe"]> } &
+    { [K in Exclude<KeysOfUnion<B>, keyof B | keyof A>]: Slot<SlotIn<B, K>["model"], SlotIn<B, K>["value"], true> }
+>;
+type SelectOnError<U> = [DiscriminatorOf<U>] extends [never]
+  ? "❌ select needs a reference to a discriminated union in config (z.discriminatedUnion)"
+  : IsUnion<DiscriminatorOf<U>> extends true ? "❌ the union has more than one literal field; select can't tell which is the discriminator" : never;
+
 // ─── Conditions / triggers ───────────────────────────────────────────────────────────────────
 
 type IsLiteralLike<T> = [T] extends [string | number | boolean]
@@ -133,7 +158,8 @@ export interface StageStepNode {
 }
 export type StageNode =
   | { readonly kind: "stage"; readonly steps: readonly StageStepNode[] }
-  | { readonly kind: "when"; readonly cond: Readonly<Record<string, unknown>>; readonly nodes: readonly StageNode[] };
+  | { readonly kind: "when"; readonly cond: Readonly<Record<string, unknown>>; readonly nodes: readonly StageNode[] }
+  | { readonly kind: "select"; readonly on: ConfigRef; readonly cases: Readonly<Record<string, readonly StageNode[]>> };
 
 export type TriggerNode =
   | { readonly kind: "push"; readonly name: string; readonly map: (event: unknown) => unknown }
@@ -146,7 +172,8 @@ export type TriggerNode =
       readonly valuePath: string;
       readonly intervalSeconds: number;
       readonly map: (value: string) => unknown;
-    };
+    }
+  | { readonly kind: "webhook"; readonly name: string; readonly verify: WebhookVerify; readonly map: (event: WebhookEvent) => unknown };
 
 export interface FailureHandlerNode {
   readonly step: AnyStep;
@@ -176,6 +203,11 @@ export function isPipeline(p: unknown): boolean {
 
 // ─── Pipeline builder ────────────────────────────────────────────────────────────────────────
 
+// Builder calls record into shared data and hand back a fresh handle; a handle that was already
+// extended no longer matches its type (it would claim fewer stages than the data has), so reuse is a problem.
+const extended = new WeakSet<object>();
+const ReusedProblem = "a pipeline value was extended twice: chain the calls (pipeline({...}).stage(a).stage(b)) instead of reusing an earlier value";
+
 export interface PipelineDef<In extends AnyModel> {
   /** Display name. */
   name: string;
@@ -201,10 +233,19 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     };
   }
 
+  private next(): never {
+    const data = this[PIPELINE];
+    if (extended.has(this) && !data.problems.includes(ReusedProblem)) data.problems.push(ReusedProblem);
+    extended.add(this);
+    const handle = Object.create(Object.getPrototypeOf(this)) as Pipeline<In, A>;
+    (handle as { [PIPELINE]: PipelineData })[PIPELINE] = data;
+    return handle as never;
+  }
+
   /** Map a GitHub push to the pipeline input (`z.input` view). Runs as code in a `map-trigger` Job per event. */
   onPush<R extends InferInput<In>>(map: (event: PushEvent) => Exact<R, InferInput<In>>): this {
     this[PIPELINE].triggers.push({ kind: "push", name: "push", map: map as (event: unknown) => unknown });
-    return this;
+    return this.next();
   }
 
   /**
@@ -233,7 +274,19 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
       intervalSeconds: cfg.intervalSeconds,
       map: map as (value: string) => unknown,
     });
-    return this;
+    return this.next();
+  }
+
+  /**
+   * Start a run from a delivery to `/api/hooks/<pipeline id>/<name>`, authenticated by `verify`. Map it to the
+   * pipeline input (`z.input` view), or return `null` to ignore it. Runs as code in a `map-trigger` Job per delivery.
+   */
+  onWebhook<R extends InferInput<In>>(
+    cfg: { name: string; verify: WebhookVerify },
+    map: (event: WebhookEvent) => Exact<R, InferInput<In>> | null,
+  ): this {
+    this[PIPELINE].triggers.push({ kind: "webhook", name: cfg.name, verify: cfg.verify, map: map as (event: WebhookEvent) => unknown });
+    return this.next();
   }
 
   /**
@@ -258,7 +311,7 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     });
     if (entries.length === 0) data.problems.push("empty stage");
     data.nodes.push({ kind: "stage", steps });
-    return this;
+    return this.next();
   }
 
   /** Declarative condition on literal-like pipeline-input fields. Outputs produced inside become maybe-available after. */
@@ -266,9 +319,38 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
     const data = this[PIPELINE];
     const inner = new Pipeline<In, A>({ name: data.name, input: data.input as In }, data);
     const returned = block(inner);
-    if (returned !== (inner as unknown)) data.problems.push("a when block must return the pipeline it was given (p => p.stage(...))");
+    if (!isPipeline(returned) || pipelineData(returned) !== inner[PIPELINE])
+      data.problems.push("a when block must return the pipeline it was given (p => p.stage(...))");
     data.nodes.push({ kind: "when", cond: { ...(cond as object) }, nodes: inner[PIPELINE].nodes });
-    return this as never;
+    return this.next();
+  }
+
+  /**
+   * Branch on config: `on` references a discriminated union in a config entry, and each case gets the
+   * pipeline and `on` narrowed to its variant. Exactly one case runs, chosen by the run's config
+   * snapshot (not by run input; that is `when`). The same step name may appear in several cases.
+   */
+  select<U, const C extends SelectCases<In, A, U, DiscriminatorOf<U>>>(
+    on: ConfigRef<U> & ([SelectOnError<U>] extends [never] ? unknown : SelectOnError<U>),
+    cases: C & { readonly [K in Exclude<keyof C, keyof SelectCases<In, A, U, DiscriminatorOf<U>>>]: `❌ '${K & string}' is not a case of this select` },
+  ): Pipeline<In, AfterSelect<A, CaseAvail<C>>> {
+    const data = this[PIPELINE];
+    const recorded: Record<string, StageNode[]> = {};
+    const union = isConfigRef(on) ? unionAt(on) : undefined;
+    if (!union) data.problems.push("select: the first argument must reference a z.discriminatedUnion in a config entry");
+    for (const [value, fn] of Object.entries(cases as Record<string, unknown>)) {
+      if (typeof fn !== "function") {
+        data.problems.push(`select: case '${value}' is not a function`);
+        continue;
+      }
+      const inner = new Pipeline<In, A>({ name: data.name, input: data.input as In }, data);
+      const returned = (fn as (p: unknown, ref: unknown) => unknown)(inner, union ? narrowConfigRef(on, union.discriminator, value) : on);
+      if (!isPipeline(returned) || pipelineData(returned) !== inner[PIPELINE])
+        data.problems.push(`select: case '${value}' must return the pipeline it was given ((p, ref) => p.stage(...))`);
+      recorded[value] = inner[PIPELINE].nodes;
+    }
+    data.nodes.push({ kind: "select", on, cases: recorded });
+    return this.next();
   }
 
   /** Run `handler` (a step whose inputs are all FailureContext) when one of `steps` (default: any) fails. Untracked, best-effort. */
@@ -278,10 +360,10 @@ export class Pipeline<In extends AnyModel, A extends AvailMap> {
         ? unknown
         : "❌ a failure handler's inputs must all be FailureContext"),
     // eslint-disable-next-line @typescript-eslint/no-explicit-any
-    opts?: { steps?: readonly Step<StepNames<A>, any, any, any>[] },
+    opts?: { steps?: readonly Step<StepNames<A>, any, any, any, any>[] },
   ): this {
     this[PIPELINE].failureHandlers.push({ step: handler as AnyStep, steps: opts?.steps ? [...(opts.steps as readonly AnyStep[])] : null });
-    return this;
+    return this.next();
   }
 }
 

package/src/core/brands.ts

@@ -2,6 +2,7 @@
 // a dev runner and the user's installed package — still recognise each other's objects.
 export const STEP = Symbol.for("olve.pipelines.step");
 export const IMPLEMENTATION = Symbol.for("olve.pipelines.implementation");
+export const ORIGIN = Symbol.for("olve.pipelines.origin");
 export const SKIPPED = Symbol.for("olve.pipelines.skipped");
 export const PIPELINE = Symbol.for("olve.pipelines.pipeline");
 export const REF_PATH = Symbol.for("olve.pipelines.refPath");
@@ -11,3 +12,4 @@ export declare const ModelBrand: unique symbol;
 export declare const RefBrand: unique symbol;
 export declare const StepBrand: unique symbol;
 export declare const SkippedBrand: unique symbol;
+export declare const ImplementationBrand: unique symbol;

package/src/core/config-refs.ts

@@ -0,0 +1,77 @@
+// Config references inside library-step definitions: collected (the step receives their entries),
+// recorded in the manifest as `{"$config": "<entry>.<path>"}`, and resolved from ctx.config at run time.
+import { configRefPath, configRefTarget, isConfigRef, type AnyConfigEntry, type ConfigRef } from "./config.ts";
+
+/** `T` with every config reference replaced by the type of its value. */
+export type Resolved<T> = T extends ConfigRef<infer U>
+  ? U
+  : T extends readonly (infer E)[]
+    ? Resolved<E>[]
+    : T extends (...args: never[]) => unknown
+      ? T
+      : T extends object
+        ? { [K in keyof T]: Resolved<T[K]> }
+        : T;
+
+/** Manifest key of a recorded config reference. */
+export const CONFIG_REF_KEY = "$config";
+/** Beside it on a reference narrowed by a `select` case: the case's condition, `<ref>.<discriminator>=<value>`. */
+export const CONFIG_CASE_KEY = "$case";
+
+function isPlain(v: unknown): v is Record<string, unknown> {
+  if (typeof v !== "object" || v === null || Array.isArray(v)) return false;
+  const proto = Object.getPrototypeOf(v);
+  return proto === Object.prototype || proto === null;
+}
+
+/** Every config entry referenced anywhere in `v` (plain objects and arrays only), by name. */
+export function configRefsIn(v: unknown, into = new Map<string, AnyConfigEntry>()): AnyConfigEntry[] {
+  if (isConfigRef(v)) {
+    const { entry } = configRefTarget(v);
+    if (!into.has(entry.name)) into.set(entry.name, entry);
+  } else if (Array.isArray(v)) for (const x of v) configRefsIn(x, into);
+  else if (isPlain(v)) for (const x of Object.values(v)) configRefsIn(x, into);
+  return [...into.values()];
+}
+
+/** `v` as manifest JSON: references become `{"$config": "target.beta.host"}`; literal keys starting with `$` are reserved. */
+export function recordConfigRefs(v: unknown): unknown {
+  if (isConfigRef(v)) {
+    const { path, case: kase } = configRefTarget(v);
+    for (const seg of path) if (seg === "" || seg.includes(".")) throw new Error(`config reference '${configRefPath(v)}': field names must not be empty or contain '.'`);
+    return { [CONFIG_REF_KEY]: configRefPath(v), ...(kase ? { [CONFIG_CASE_KEY]: kase } : {}) };
+  }
+  if (Array.isArray(v)) return v.map(recordConfigRefs);
+  if (isPlain(v)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, x] of Object.entries(v)) {
+      if (k.startsWith("$")) throw new Error(`key '${k}': keys starting with '$' are reserved`);
+      out[k] = recordConfigRefs(x);
+    }
+    return out;
+  }
+  return v;
+}
+
+/** `v` with every reference replaced by its value in `config` (the step's parsed config entries). */
+export function resolveConfigRefs<T>(v: T, config: Readonly<Record<string, unknown>>): Resolved<T> {
+  if (isConfigRef(v)) {
+    const { entry, path } = configRefTarget(v);
+    if (!Object.hasOwn(config, entry.name)) throw new Error(`config entry '${entry.name}' was not delivered to the step`);
+    let cur: unknown = config[entry.name];
+    for (const seg of path) cur = cur !== null && typeof cur === "object" ? (cur as Record<string, unknown>)[seg] : undefined;
+    return cur as Resolved<T>;
+  }
+  if (Array.isArray(v)) return v.map((x) => resolveConfigRefs(x, config)) as Resolved<T>;
+  if (isPlain(v)) {
+    const out: Record<string, unknown> = {};
+    for (const [k, x] of Object.entries(v)) out[k] = resolveConfigRefs(x, config);
+    return out as Resolved<T>;
+  }
+  return v as Resolved<T>;
+}
+
+/** Literal `v` (no reference inside), so define-time checks can run on it. */
+export function isLiteral(v: unknown): boolean {
+  return configRefsIn(v).length === 0;
+}

package/src/core/config.ts

@@ -0,0 +1,147 @@
+import { z } from "zod";
+import type { Secret } from "./secrets.ts";
+
+const CONFIG_REF = Symbol.for("olve.configRef");
+declare const VALUE: unique symbol;
+
+interface RefTarget {
+  readonly entry: AnyConfigEntry;
+  readonly path: readonly string[];
+  /** Set on a reference narrowed by a `select` case: `<ref>.<discriminator>=<value>`. */
+  readonly case?: string;
+}
+
+/**
+ * A typed reference to a config value (`TARGET.beta.host`), accepted in a step's settings in place of a
+ * literal. It is recorded in the manifest as `{"$config": "target.beta.host"}` and resolved from the
+ * run's config when the step runs; the step receives the entry automatically.
+ */
+export interface ConfigRef<T = unknown> {
+  readonly [CONFIG_REF]: RefTarget;
+  readonly [VALUE]?: T;
+}
+
+/** A literal or a reference to a config value of the same type. */
+export type Configurable<T> = T | ConfigRef<T>;
+
+type Fields<T> = T extends readonly unknown[] ? never : T extends object ? T : never;
+type Children<T> = [Fields<NonNullable<T>>] extends [never]
+  ? {}
+  : { readonly [K in keyof Fields<NonNullable<T>> & string]-?: ConfigNode<Fields<NonNullable<T>>[K] | (undefined extends T ? undefined : never)> };
+/** A reference to a config value, and to each of its fields. */
+export type ConfigNode<T> = ConfigRef<T> & Children<T>;
+
+/** Fields of an entry that are its own properties; reach config fields with these names through `$`. */
+export type ReservedConfigField = "kind" | "name" | "description" | "schema" | "$";
+
+/** A named, typed value stored on the instance (one YAML document per pipeline), declared by the steps that use it. */
+export interface ConfigEntryBase<N extends string = string, S extends z.ZodType = z.ZodType> {
+  readonly kind: "config";
+  readonly name: N;
+  readonly description: string;
+  readonly schema: S;
+}
+export type ConfigEntry<N extends string = string, S extends z.ZodType = z.ZodType> = ConfigEntryBase<N, S> &
+  ConfigRef<z.output<S>> &
+  Omit<Children<z.output<S>>, ReservedConfigField> & { readonly $: ConfigNode<z.output<S>> };
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type AnyConfigEntry = ConfigEntryBase<string, any>;
+
+/** Config names are YAML keys: camelCase identifiers. */
+export const CONFIG_NAME = /^[a-z][a-zA-Z0-9]*$/;
+
+const NOT_REFS = new Set<PropertyKey>(["then", "toJSON", "constructor", "valueOf", "toString", "asymmetricMatch", "$$typeof", "nodeType"]);
+
+function node(entry: AnyConfigEntry, path: readonly string[], kase?: string): unknown {
+  const target = Object.freeze({ [CONFIG_REF]: Object.freeze({ entry, path, ...(kase ? { case: kase } : {}) }) });
+  return new Proxy(target, {
+    get(t, prop) {
+      if (prop === CONFIG_REF) return t[CONFIG_REF];
+      if (typeof prop === "symbol" || NOT_REFS.has(prop)) return undefined;
+      return node(entry, [...path, prop], kase);
+    },
+  });
+}
+
+/** `ref` narrowed to the union member whose `discriminator` is `value` (a `select` case). */
+export function narrowConfigRef(ref: ConfigRef, discriminator: string, value: string): unknown {
+  const { entry, path } = ref[CONFIG_REF];
+  return node(entry, path, `${[entry.name, ...path].join(".")}.${discriminator}=${value}`);
+}
+
+export function config<const N extends string, S extends z.ZodType>(name: N, description: string, schema: S): ConfigEntry<N, S> {
+  const ref = { entry: undefined as unknown as AnyConfigEntry, path: [] as readonly string[] };
+  const target = Object.freeze({ kind: "config" as const, name, description, schema, [CONFIG_REF]: ref });
+  const entry: unknown = new Proxy(target, {
+    get(t, prop) {
+      if (prop in t) return t[prop as keyof typeof t];
+      if (typeof prop === "symbol" || NOT_REFS.has(prop)) return undefined;
+      if (prop === "$") return node(entry as AnyConfigEntry, []);
+      return node(entry as AnyConfigEntry, [prop]);
+    },
+  });
+  ref.entry = entry as AnyConfigEntry;
+  Object.freeze(ref);
+  return entry as ConfigEntry<N, S>;
+}
+
+export function isConfigEntry(v: unknown): v is AnyConfigEntry {
+  return typeof v === "object" && v !== null && (v as { kind?: unknown }).kind === "config" && (v as { schema?: unknown }).schema instanceof z.ZodType;
+}
+
+export function isConfigRef(v: unknown): v is ConfigRef {
+  return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[CONFIG_REF] !== undefined;
+}
+
+/** The entry and field path a reference points at, and the `select` case it was narrowed by. */
+export function configRefTarget(ref: ConfigRef): { entry: AnyConfigEntry; path: readonly string[]; case?: string } {
+  return ref[CONFIG_REF];
+}
+
+/** `target.beta.host` */
+export function configRefPath(ref: ConfigRef): string {
+  const { entry, path } = configRefTarget(ref);
+  return [entry.name, ...path].join(".");
+}
+
+export const SECRET_REF_KIND = "secretRef";
+
+/** A config field that names a secret: `{ secret: NAME }` in YAML. The value never enters the config. */
+export function secretRef<const N extends string>(s: Secret<N>) {
+  return z.strictObject({ secret: z.literal(s.name) }).meta({ "x-olve-kind": SECRET_REF_KIND });
+}
+
+/** `ctx.config`: exactly the entries a step declares, after parsing (defaults applied). */
+export type ConfigValues<C extends AnyConfigEntry> = { readonly [E in C as E["name"]]: z.output<E["schema"]> };
+
+// ─── select: branching on a config union ────────────────────────────────────────────────────
+
+type IsLiteralString<T> = [T] extends [string] ? (string extends T ? false : true) : false;
+/** The fields of union `U` whose type is a string literal in every member: its discriminator(s). */
+export type DiscriminatorOf<U> = { [K in keyof U & string]-?: IsLiteralString<U[K]> extends true ? K : never }[keyof U & string];
+/** The member of `U` whose discriminator `D` is `V`. */
+export type VariantOf<U, D extends string, V> = Extract<U, { readonly [K in D]: V }>;
+
+function unwrap(schema: z.ZodType): z.ZodType {
+  let s = schema as unknown as { _zod: { def: { innerType?: z.ZodType } } };
+  for (let i = 0; i < 16 && s._zod.def.innerType; i++) s = s._zod.def.innerType as never;
+  return s as unknown as z.ZodType;
+}
+
+/**
+ * The discriminated union a reference points at: its discriminator and, per value, nothing else.
+ * Undefined when the referenced value is not a `z.discriminatedUnion`.
+ */
+export function unionAt(ref: ConfigRef): { discriminator: string; values: string[] } | undefined {
+  const { entry, path } = configRefTarget(ref);
+  let s = unwrap(entry.schema as z.ZodType) as unknown as { _zod: { def: Record<string, unknown> } };
+  for (const seg of path) {
+    const shape = s._zod.def.shape as Record<string, z.ZodType> | undefined;
+    if (!shape || !(seg in shape)) return undefined;
+    s = unwrap(shape[seg]!) as never;
+  }
+  const def = s._zod.def as { discriminator?: string; options?: { _zod: { propValues?: Record<string, Set<unknown>> } }[] };
+  if (typeof def.discriminator !== "string" || !Array.isArray(def.options)) return undefined;
+  const values = def.options.flatMap((o) => [...(o._zod.propValues?.[def.discriminator!] ?? [])]).filter((v): v is string => typeof v === "string");
+  return { discriminator: def.discriminator, values };
+}

package/src/core/handlers.ts

@@ -1,6 +1,7 @@
-import { IMPLEMENTATION, SKIPPED, type SkippedBrand } from "./brands.ts";
+import { IMPLEMENTATION, ORIGIN, SKIPPED, type ImplementationBrand, type SkippedBrand } from "./brands.ts";
 import type { Ctx } from "../ctx/types.ts";
-import type { AnyStep, LibraryStep, OutputValue, SecretsOf, StepInput } from "./steps.ts";
+import { callerFile, originsOf } from "./origin.ts";
+import type { AnyStep, ConfigOf, OutputValue, SecretsOf, StepInput } from "./steps.ts";
 import type { Awaitable } from "./types.ts";
 
 /** Returned by `ctx.skip(reason)`: the step produced no output on purpose. */
@@ -16,12 +17,15 @@ export function isSkipped(v: unknown): v is Skipped {
 }
 
 export type HandlerResult<S extends AnyStep> = OutputValue<S> | Skipped;
-export type Handler<S extends AnyStep> = (input: StepInput<S["input"]>, ctx: Ctx<SecretsOf<S>>) => Awaitable<HandlerResult<S>>;
+export type Handler<S extends AnyStep> = (input: StepInput<S["input"]>, ctx: Ctx<SecretsOf<S>, ConfigOf<S>>) => Awaitable<HandlerResult<S>>;
 
-export interface Implementation<S extends AnyStep = AnyStep> {
+/** A step with its handler. It is itself a step: stage it directly, or default-export it from `handlers/*.ts`. */
+export type Implementation<S extends AnyStep = AnyStep> = S & {
+  readonly [ImplementationBrand]: true;
+  /** The step as defined. */
   readonly step: S;
   readonly handler: Handler<S>;
-}
+};
 
 /** Block-bodied/async returns get no excess-property check; this restores it for handler outputs. */
 type NoExtraFields<R, T> = R extends Skipped | void
@@ -29,14 +33,16 @@ type NoExtraFields<R, T> = R extends Skipped | void
   : { [K in Exclude<keyof R, keyof T>]: `❌ '${K & string}' is not a field of the output model` };
 
 /**
- * Implement a custom step. Input, ctx and return types come from the step definition alone.
- * Default-export the result from `handlers/<step-name>.ts`.
+ * Implement a step. Input, ctx and return types come from the step definition alone. Default-export
+ * the result from a `handlers/*.ts` file, or stage it directly (a reusable step: give it a `kind`).
  */
 export function implement<S extends AnyStep, R extends HandlerResult<S>>(
-  step: S & (S extends LibraryStep ? "❌ library steps already carry their implementation" : unknown),
-  handler: (input: StepInput<S["input"]>, ctx: Ctx<SecretsOf<S>>) => Awaitable<R & NoExtraFields<R, OutputValue<S>>>,
+  step: S & (S extends { readonly [ImplementationBrand]: true } ? "❌ this step already carries its implementation" : unknown),
+  handler: (input: StepInput<S["input"]>, ctx: Ctx<SecretsOf<S>, ConfigOf<S>>) => Awaitable<R & NoExtraFields<R, OutputValue<S>>>,
 ): Implementation<S> {
-  return Object.freeze({ [IMPLEMENTATION]: true, step, handler: handler as unknown as Handler<S> }) as Implementation<S>;
+  if (isImplementation(step)) throw new TypeError(`step '${(step as AnyStep).name}' already carries its implementation`);
+  const origins = [...new Set([...originsOf(step), callerFile()].filter((f): f is string => f !== undefined))];
+  return Object.freeze({ ...step, [IMPLEMENTATION]: true, [ORIGIN]: origins, step, handler: handler as unknown as Handler<S> }) as unknown as Implementation<S>;
 }
 
 export function isImplementation(v: unknown): v is Implementation {

package/src/core/origin.ts

@@ -0,0 +1,20 @@
+import { ORIGIN } from "./brands.ts";
+
+/**
+ * The file that called the function calling this one, from the stack. A tail call drops its caller's
+ * frame, so this can name a module further up; the build only uses it to choose what to hash.
+ */
+export function callerFile(): string | undefined {
+  const files = (new Error().stack ?? "").split("\n").slice(1).map((f) => f.match(FRAME)?.[1]);
+  const own = files[0];
+  const callee = files[1];
+  const file = files.slice(2).find((f) => f && f !== own && f !== callee) ?? undefined;
+  return file?.startsWith("file://") ? new URL(file).pathname : file;
+}
+const FRAME = /\(?((?:file:\/\/)?\/[^()]*?):\d+(?::\d+)?\)?\s*$/;
+
+/** The modules that defined and implemented a step (where `step` and `implement` were called). */
+export function originsOf(v: unknown): string[] {
+  const o = (v as Record<symbol, unknown>)[ORIGIN];
+  return Array.isArray(o) ? o.filter((x): x is string => typeof x === "string") : [];
+}

package/src/core/steps.ts

@@ -1,6 +1,9 @@
 import type { z } from "zod";
-import { STEP, type StepBrand } from "./brands.ts";
+import { ORIGIN, STEP, type StepBrand } from "./brands.ts";
+import { callerFile } from "./origin.ts";
 import type { AnyModel, Infer, Optional } from "./models.ts";
+import type { AnyConfigEntry } from "./config.ts";
+import { configRefsIn } from "./config-refs.ts";
 import type { Secret } from "./secrets.ts";
 import type { Simplify } from "./types.ts";
 
@@ -16,14 +19,19 @@ export type InferEntry<E> =
 /** What a handler receives: the output view of every input entry. */
 export type StepInput<I> = Simplify<{ -readonly [K in keyof I]: InferEntry<I[K]> }>;
 
-/** `custom` steps have a handler file; the others are library steps implemented by the SDK. */
-export type StepKind = "custom" | "script" | "gitHubSource" | "imageBuild" | "helmDeployOverSsh";
+/**
+ * A label for what a step is, shown in the UI. `custom` (the default) is a step whose handler is in
+ * `handlers/`; a step that carries its implementation (`implement(step, …)` staged directly) names its
+ * kind, e.g. `gitHubSource`. Packages prefix theirs (`acme/deploy`).
+ */
+export type StepKind = string;
 
 export interface Step<
   N extends string = string,
   I extends InputSpec = InputSpec,
   O extends AnyModel | null = AnyModel | null,
   Sec extends string = string,
+  Cfg extends AnyConfigEntry = never,
 > {
   readonly [StepBrand]: true;
   readonly kind: StepKind;
@@ -33,24 +41,22 @@ export interface Step<
   readonly input: I;
   readonly output: O;
   readonly secrets: readonly Secret<Sec>[];
+  /** Config entries the step receives as `ctx.config`. */
+  readonly config: readonly Cfg[];
   readonly timeoutSeconds?: number;
   readonly retries?: number;
-  /** Library steps carry their own implementation and config. */
-  readonly builtin?: LibraryImplementation;
+  /** The step pod gets the instance's step ServiceAccount token (`Kubernetes:StepServiceAccount`). */
+  readonly clusterAccess?: boolean;
+  /** How the step is set up, as written in the definition (may hold config references). */
+  readonly settings?: Readonly<Record<string, unknown>>;
 }
-/** Runtime part of a library step (not part of the public contract). */
-export interface LibraryImplementation {
-  /** Config as emitted in the manifest (JSON only; must not contain paths). */
-  readonly manifestConfig: () => Record<string, unknown>;
-  // eslint-disable-next-line @typescript-eslint/no-explicit-any
-  readonly run: (input: any, ctx: any) => Promise<unknown>;
-}
-export type LibraryStep = { readonly builtin: LibraryImplementation };
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type AnyStep = Step<string, any, AnyModel | null, any>;
+export type AnyStep = Step<string, any, AnyModel | null, any, any>;
 
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
-export type SecretsOf<S> = S extends Step<any, any, any, infer Sec> ? Sec : never;
+export type SecretsOf<S> = S extends Step<any, any, any, infer Sec, any> ? Sec : never;
+// eslint-disable-next-line @typescript-eslint/no-explicit-any
+export type ConfigOf<S> = S extends Step<any, any, any, any, infer C> ? C : never;
 export type OutputValue<S extends AnyStep> = S["output"] extends AnyModel ? Infer<S["output"]> : void;
 
 /** Step names must be literals (identity, duplicate detection and mapper keys depend on it). */
@@ -61,7 +67,7 @@ export const STEP_NAME = /^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/;
 /** Names that cannot be steps: `input` is the pipeline input's root in mappings. */
 export const RESERVED_STEP_NAMES: readonly string[] = ["input"];
 
-export interface StepDef<N extends string, I extends InputSpec, O extends AnyModel | null, Sec extends readonly Secret[]> {
+export interface StepDef<N extends string, I extends InputSpec, O extends AnyModel | null, Sec extends readonly Secret[], Cfg extends readonly AnyConfigEntry[] = []> {
   name: LiteralName<N>;
   /** What the step does, shown in the UI. Required; may be empty. */
   description: string;
@@ -70,24 +76,45 @@ export interface StepDef<N extends string, I extends InputSpec, O extends AnyMod
   input?: I;
   output?: O;
   secrets?: Sec;
+  /** Config entries delivered as `ctx.config` (typed to exactly these). */
+  config?: Cfg;
   timeoutSeconds?: number;
   /** Automatic retries (an idempotency claim). Default 0. */
   retries?: number;
+  /**
+   * Ask for a Kubernetes API token in the step pod: the instance's step ServiceAccount
+   * (`Kubernetes:StepServiceAccount`), if it grants one. Default false (no token).
+   */
+  clusterAccess?: boolean;
+  /** A label for the step's kind (default `custom`). */
+  kind?: StepKind;
+  /**
+   * How the step is set up, shown in the manifest and part of the step's identity: the parameters of
+   * a reusable step. JSON values and config references (`target.prod.host`); every config entry it
+   * references is delivered to the step, and `resolveConfigRefs(value, ctx.config)` resolves them.
+   */
+  settings?: Readonly<Record<string, unknown>>;
 }
 
-export function makeStep(kind: StepKind, def: Record<string, unknown>, builtin?: LibraryImplementation): AnyStep {
+function makeStep(def: Record<string, unknown>, origin: string | undefined): AnyStep {
+  const config = new Map<string, AnyConfigEntry>();
+  for (const e of (def.config as readonly AnyConfigEntry[] | undefined) ?? []) if (!config.has(e.name)) config.set(e.name, e);
+  configRefsIn(def.settings, config);
   const s = {
     [STEP]: true,
-    kind,
+    kind: def.kind ?? "custom",
     name: def.name,
     description: def.description,
     image: def.image,
     input: Object.freeze({ ...((def.input as object | undefined) ?? {}) }),
     output: def.output ?? null,
     secrets: Object.freeze([...((def.secrets as readonly Secret[] | undefined) ?? [])]),
+    config: Object.freeze([...config.values()]),
     ...(def.timeoutSeconds !== undefined ? { timeoutSeconds: def.timeoutSeconds } : {}),
     ...(def.retries !== undefined ? { retries: def.retries } : {}),
-    ...(builtin ? { builtin } : {}),
+    ...(def.clusterAccess === true ? { clusterAccess: true } : {}),
+    ...(def.settings !== undefined ? { settings: def.settings } : {}),
+    [ORIGIN]: origin === undefined ? [] : [origin],
   };
   return Object.freeze(s) as unknown as AnyStep;
 }
@@ -96,12 +123,16 @@ export function isStep(v: unknown): v is AnyStep {
   return typeof v === "object" && v !== null && (v as Record<symbol, unknown>)[STEP] === true;
 }
 
-/** Define a custom step: a contract (name, image, inputs, output, secrets). Its handler lives in `handlers/<name>.ts`. */
+/**
+ * Define a step: a contract (name, image, inputs, output, secrets). Its handler is a `handlers/*.ts`
+ * default-exporting `implement(step, …)`, or, for a reusable step, `implement(step, …)` staged directly.
+ */
 export function step<
   const N extends string,
   const I extends InputSpec = {},
   O extends AnyModel | null = null,
   const Sec extends readonly Secret[] = [],
->(def: StepDef<N, I, O, Sec>): Step<N, I, O, Sec[number]["name"]> {
-  return makeStep("custom", def as never) as never;
+  const Cfg extends readonly AnyConfigEntry[] = [],
+>(def: StepDef<N, I, O, Sec, Cfg>): Step<N, I, O, Sec[number]["name"], Cfg[number]> {
+  return makeStep(def as never, callerFile()) as never;
 }