@olivervea/pipelines 0.0.0-stage → 2.0.0-beta.10

package/src/builder/pipeline.ts

@@ -0,0 +1,373 @@
+import { PIPELINE } from "../core/brands.ts";
+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) ────────────────────────────────────────────────
+
+interface Slot<M extends string | null = string | null, V = unknown, Maybe extends boolean = boolean> {
+  model: M;
+  value: V;
+  maybe: Maybe;
+}
+type AvailMap = { [step: string]: Slot };
+export type InitialAvail<In extends AnyModel> = { input: Slot<In["name"], Infer<In>, false> };
+
+/** The mapper argument: keyed by step name + `input`; maybe-available outputs are `Ref<T | undefined>`. */
+export type InRefs<A extends AvailMap> = {
+  readonly [K in keyof A as A[K]["model"] extends null ? never : K]: Ref<
+    A[K]["maybe"] extends true ? A[K]["value"] | undefined : A[K]["value"]
+  >;
+};
+
+type ProducersOf<A extends AvailMap, MN> = { [K in keyof A]: A[K]["model"] extends MN ? K : never }[keyof A];
+type DefiniteProducersOf<A extends AvailMap, MN> = {
+  [K in keyof A]: A[K]["model"] extends MN ? (A[K]["maybe"] extends false ? K : never) : never;
+}[keyof A];
+
+type EntryError<SN extends string, Key extends string, E, A extends AvailMap> =
+  E extends Optional<infer M>
+    ? [ProducersOf<A, M["name"]>] extends [never]
+      ? `❌ ${M["name"]} (input '${Key}' of step '${SN}') is not available at this stage`
+      : IsUnion<ProducersOf<A, M["name"]>> extends true
+        ? `❌ ${M["name"]} (input '${Key}' of step '${SN}') has several producers; use a mapper to pick one`
+        : never
+    : E extends AnyModel
+      ? [ProducersOf<A, E["name"]>] extends [never]
+        ? `❌ ${E["name"]} (input '${Key}' of step '${SN}') is not available at this stage`
+        : [DefiniteProducersOf<A, E["name"]>] extends [never]
+          ? `❌ ${E["name"]} (input '${Key}' of step '${SN}') is only maybe-available (produced inside a when block); declare it optional(${E["name"]})`
+          : IsUnion<ProducersOf<A, E["name"]>> extends true
+            ? `❌ ${E["name"]} (input '${Key}' of step '${SN}') has several producers; use a mapper to pick one`
+            : never
+      : `❌ input '${Key}' of step '${SN}' is a plain schema, not a model, so it cannot be matched by model; add a mapper`;
+
+type DefaultMatchError<S extends AnyStep, A extends AvailMap> = {
+  [K in keyof S["input"] & string]: EntryError<S["name"], K, S["input"][K], A>;
+}[keyof S["input"] & string] extends infer X extends string ? X : never; // `infer` forces display of the literal
+
+type NameError<S extends AnyStep, A extends AvailMap, SiblingNames> =
+  // NB: no `string extends S["name"]` test here — it poisons inference of mixed stages;
+  // non-literal names are rejected in step() instead.
+  S["name"] extends "input" ? "❌ 'input' is reserved for the pipeline input and cannot be a step name"
+  : S["name"] extends keyof A ? `❌ duplicate step name '${S["name"]}' (already used in an earlier stage)`
+  : S["name"] extends SiblingNames ? `❌ duplicate step name '${S["name"]}' (used twice in this stage)`
+  : never;
+
+// ─── Stage entries ───────────────────────────────────────────────────────────────────────────
+
+export type MapperFn<S extends AnyStep, A extends AvailMap> = (from: InRefs<A>) => MapperResult<S>;
+export type StageEntry<A extends AvailMap> = AnyStep | readonly [AnyStep, (from: InRefs<A>) => unknown];
+
+type StepOfEntry<X> = X extends readonly [infer S extends AnyStep, unknown] ? S : X extends AnyStep ? X : never;
+type SiblingNames<E extends readonly unknown[], K> = {
+  [J in keyof E]: J extends K ? never : StepOfEntry<E[J]>["name"];
+}[number];
+
+/**
+ * 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;
+ *  - nothing may look at *neighbouring* entries through E except via NoInfer (sibling names only).
+ */
+export type CheckEntry<E extends readonly unknown[], K, X, A extends AvailMap> =
+  X extends readonly [infer S extends AnyStep, unknown]
+    ? readonly [S, (from: InRefs<A>) => OrError<NameError<S, A, SiblingNames<E, K>>, MapperResult<S>>]
+    : X extends AnyStep
+      ? string extends X["name"] ? X : OrError<NameError<X, A, SiblingNames<E, K>> | DefaultMatchError<X, A>, X>
+      : "❌ a stage entry must be a step or a [step, mapper] pair";
+
+// NB: the template must mention `E[K]` literally, or reverse-mapped inference of E fails.
+export type CheckStage<E extends readonly unknown[], A extends AvailMap> = { [K in keyof E]: CheckEntry<NoInfer<E>, K, E[K], A> };
+
+type OutputsOf<E extends readonly unknown[], Maybe extends boolean> = {
+  [S in StepOfEntry<E[number]> as S["name"]]: Slot<
+    S["output"] extends AnyModel ? S["output"]["name"] : null,
+    OutputValue<S>,
+    Maybe
+  >;
+};
+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]
+  ? string extends T ? false : number extends T ? false : true
+  : false;
+export type WhenCond<In extends AnyModel> = {
+  [K in keyof Plain<In> & string]?: Exclude<Plain<In>[K], undefined> extends infer L
+    ? IsLiteralLike<L> extends true
+      ? L | readonly L[]
+      : `❌ '${K}' is not a literal-like field (enum, boolean or literal); when cannot match on it`
+    : never;
+};
+
+/** The push event the service sends a push trigger mapper: exactly these fields, nothing more. */
+export interface PushEvent {
+  readonly ref: string;
+  readonly after: string;
+  readonly repository: { readonly full_name: string };
+}
+
+type CheckHeader<V, Allowed extends string> = V extends `$SECRET:${infer X}`
+  ? X extends Allowed ? V : `❌ secret '${X}' is not declared in this poll trigger's secrets`
+  : V;
+
+/** Rejects extra fields in a trigger mapping (arrow-function returns get no excess-property check). */
+type Exact<R, T> = R & { [K in Exclude<keyof R, keyof T>]: `❌ '${K & string}' is not a field of the pipeline input` };
+
+type StepNames<A extends AvailMap> = Exclude<keyof A, "input"> & string;
+
+// ─── Runtime records (read by describe/harness) ──────────────────────────────────────────────
+
+export type MapperFunction = (from: unknown) => unknown;
+export interface StageStepNode {
+  readonly step: AnyStep;
+  readonly mapper?: MapperFunction;
+}
+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: "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 }
+  | {
+      readonly kind: "poll";
+      readonly name: string;
+      readonly url: string;
+      readonly headers: Readonly<Record<string, string>>;
+      readonly secrets: readonly Secret[];
+      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;
+  /** null = every step. */
+  readonly steps: readonly AnyStep[] | null;
+}
+
+export interface PipelineData {
+  readonly name: string;
+  readonly description: string | undefined;
+  readonly input: AnyModel;
+  readonly nodes: StageNode[];
+  readonly triggers: TriggerNode[];
+  readonly failureHandlers: FailureHandlerNode[];
+  /** Structural problems found while building (reported by describe). */
+  readonly problems: string[];
+}
+
+export function pipelineData(p: unknown): PipelineData {
+  const d = typeof p === "object" && p !== null ? (p as Record<symbol, unknown>)[PIPELINE] : undefined;
+  if (!d) throw new TypeError("not a pipeline (pipeline.ts must default-export pipeline({...})...)");
+  return d as PipelineData;
+}
+export function isPipeline(p: unknown): boolean {
+  return typeof p === "object" && p !== null && PIPELINE in p;
+}
+
+// ─── 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;
+  description?: string;
+  /** The pipeline input model (what triggers produce, what `when` matches on). */
+  input: In;
+}
+
+export class Pipeline<In extends AnyModel, A extends AvailMap> {
+  /** Phantom: the availability map accumulated so far. */
+  declare readonly __avail: A;
+  readonly [PIPELINE]: PipelineData;
+
+  constructor(def: PipelineDef<In>, shared?: { triggers: TriggerNode[]; failureHandlers: FailureHandlerNode[]; problems: string[] }) {
+    this[PIPELINE] = {
+      name: def.name,
+      description: def.description,
+      input: def.input,
+      nodes: [],
+      triggers: shared?.triggers ?? [],
+      failureHandlers: shared?.failureHandlers ?? [],
+      problems: shared?.problems ?? [],
+    };
+  }
+
+  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.next();
+  }
+
+  /**
+   * Poll a URL; when the JSON value at `valuePath` changes, map it to the pipeline input.
+   * Header values may reference the poll's own declared secrets as `$SECRET:NAME`.
+   */
+  onPoll<R extends InferInput<In>, const Sec extends readonly Secret[] = [], const H extends Record<string, string> = {}>(
+    cfg: {
+      /** Trigger id, unique per pipeline (default "poll"). Used by `map-trigger <name>`. */
+      name?: string;
+      url: string;
+      secrets?: Sec;
+      headers?: { [K in keyof H]: CheckHeader<H[K], Sec[number]["name"]> };
+      valuePath: string;
+      intervalSeconds: number;
+    },
+    map: (value: string) => Exact<R, InferInput<In>>,
+  ): this {
+    this[PIPELINE].triggers.push({
+      kind: "poll",
+      name: cfg.name ?? "poll",
+      url: cfg.url,
+      headers: { ...((cfg.headers ?? {}) as Record<string, string>) },
+      secrets: [...(cfg.secrets ?? [])],
+      valuePath: cfg.valuePath,
+      intervalSeconds: cfg.intervalSeconds,
+      map: map as (value: string) => unknown,
+    });
+    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();
+  }
+
+  /**
+   * Add a stage (its steps run in parallel). Entries: `step` (inputs matched by model) or
+   * `[step, from => ({ … })]` (explicit mapping). Every entry sees only what was available
+   * *before* this stage.
+   */
+  stage<const E extends readonly StageEntry<A>[]>(...entries: CheckStage<E, A>): Pipeline<In, Simplify<A & OutputsOf<E, false>>>;
+  stage(...entries: readonly unknown[]): unknown {
+    const data = this[PIPELINE];
+    const steps: StageStepNode[] = [];
+    entries.forEach((e, i) => {
+      if (Array.isArray(e) && e.length === 2 && isStep(e[0]) && typeof e[1] === "function") {
+        steps.push({ step: e[0], mapper: e[1] as MapperFunction });
+      } else if (isStep(e)) {
+        steps.push({ step: e });
+      } else if (typeof e === "function") {
+        data.problems.push(`stage entry ${i + 1} is a bare function; mappers are given as [step, from => ({ ... })] tuples`);
+      } else {
+        data.problems.push(`stage entry ${i + 1} is neither a step nor a [step, mapper] pair`);
+      }
+    });
+    if (entries.length === 0) data.problems.push("empty stage");
+    data.nodes.push({ kind: "stage", steps });
+    return this.next();
+  }
+
+  /** Declarative condition on literal-like pipeline-input fields. Outputs produced inside become maybe-available after. */
+  when<B extends AvailMap>(cond: WhenCond<In>, block: (p: Pipeline<In, A>) => Pipeline<In, B>): Pipeline<In, Simplify<A & MakeMaybe<Omit<B, keyof A>>>> {
+    const data = this[PIPELINE];
+    const inner = new Pipeline<In, A>({ name: data.name, input: data.input as In }, data);
+    const returned = block(inner);
+    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.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. */
+  onFailure<S extends AnyStep>(
+    handler: S &
+      ([Exclude<S["input"][keyof S["input"]], typeof FailureContext>] extends [never]
+        ? 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, any>[] },
+  ): this {
+    this[PIPELINE].failureHandlers.push({ step: handler as AnyStep, steps: opts?.steps ? [...(opts.steps as readonly AnyStep[])] : null });
+    return this.next();
+  }
+}
+
+/** Start a pipeline definition. `pipeline.ts` must default-export the result. */
+export function pipeline<In extends AnyModel>(def: PipelineDef<In>): Pipeline<In, InitialAvail<In>> {
+  return new Pipeline(def) as never;
+}

package/src/builder/refs.ts

@@ -0,0 +1,26 @@
+import type { RefBrand } from "../core/brands.ts";
+import type { AnyStep, InferEntry } from "../core/steps.ts";
+import type { Primitive } from "../core/types.ts";
+
+/**
+ * A typed reference into the run pool — what mappers see. `symbol &` makes template strings, `+`
+ * and `===` against values compile errors (TS2731 / TS2469 / TS2367); only property access and
+ * literals remain. Fields of a maybe-undefined ref are themselves maybe-undefined.
+ */
+export type Ref<T> = symbol & { readonly [RefBrand]: T } & RefFields<T>;
+type RefFields<T> = [NonNullable<T>] extends [Primitive]
+  ? {}
+  : NonNullable<T> extends readonly unknown[]
+    ? {}
+    : { readonly [K in keyof NonNullable<T> & string]-?: Ref<NonNullable<T>[K] | (undefined extends T ? undefined : never)> };
+
+/** What a mapper may put where a T is expected: a Ref<T>, a literal, or an object of those. */
+export type Mappable<T> =
+  | Ref<T>
+  | (T extends Primitive
+      ? T
+      : T extends readonly unknown[]
+        ? never
+        : { [K in keyof T]: Mappable<T[K]> } & { readonly [RefBrand]?: never }); // a Ref of another model can't sneak in structurally
+
+export type MapperResult<S extends AnyStep> = { [K in keyof S["input"]]: Mappable<InferEntry<S["input"][K]>> };

package/src/core/brands.ts

@@ -0,0 +1,15 @@
+// Runtime markers. `Symbol.for` (not `Symbol()`) so that two copies of the SDK in one process — e.g.
+// 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");
+
+// Type-only brands (never exist at runtime).
+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 };
+}