@olivervea/pipelines 2.0.0-beta.3 → 2.0.0-beta.6

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 by library steps 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,6 @@
 import { IMPLEMENTATION, SKIPPED, type SkippedBrand } from "./brands.ts";
 import type { Ctx } from "../ctx/types.ts";
-import type { AnyStep, LibraryStep, OutputValue, SecretsOf, StepInput } from "./steps.ts";
+import type { AnyStep, ConfigOf, LibraryStep, 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,7 +16,7 @@ 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> {
   readonly step: S;
@@ -34,7 +34,7 @@ type NoExtraFields<R, T> = R extends Skipped | void
  */
 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>>>,
+  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>;
 }

package/src/core/steps.ts

@@ -1,6 +1,8 @@
 import type { z } from "zod";
 import { STEP, type StepBrand } from "./brands.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";
 
@@ -17,13 +19,14 @@ export type InferEntry<E> =
 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";
+export type StepKind = "custom" | "script" | "gitHubSource" | "imageBuild" | "helmDeployOverSsh" | "helmDeployInCluster" | "composeDeploy";
 
 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,8 +36,12 @@ 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;
+  /** The step pod gets the instance's step ServiceAccount token (`Kubernetes:StepServiceAccount`). */
+  readonly clusterAccess?: boolean;
   /** Library steps carry their own implementation and config. */
   readonly builtin?: LibraryImplementation;
 }
@@ -47,10 +54,12 @@ export interface LibraryImplementation {
 }
 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 +70,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,12 +79,23 @@ 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;
 }
 
-export function makeStep(kind: StepKind, def: Record<string, unknown>, builtin?: LibraryImplementation): AnyStep {
+/** `configFrom`: a library step's definition; the config entries it references are added to the step's `config`. */
+export function makeStep(kind: StepKind, def: Record<string, unknown>, builtin?: LibraryImplementation, configFrom?: unknown): 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(configFrom, config);
   const s = {
     [STEP]: true,
     kind,
@@ -85,8 +105,10 @@ export function makeStep(kind: StepKind, def: Record<string, unknown>, builtin?:
     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 } : {}),
+    ...(def.clusterAccess === true ? { clusterAccess: true } : {}),
     ...(builtin ? { builtin } : {}),
   };
   return Object.freeze(s) as unknown as AnyStep;
@@ -102,6 +124,7 @@ export function step<
   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"]> {
+  const Cfg extends readonly AnyConfigEntry[] = [],
+>(def: StepDef<N, I, O, Sec, Cfg>): Step<N, I, O, Sec[number]["name"], Cfg[number]> {
   return makeStep("custom", def as never) as never;
 }

package/src/ctx/index.ts

@@ -12,6 +12,8 @@ export interface CtxOptions {
   secrets: readonly Secret[];
   /** Secret values that take precedence over the environment (tests). */
   secretValues?: Readonly<Record<string, string>>;
+  /** Parsed config entries of the step (`ctx.config`). */
+  config?: Readonly<Record<string, unknown>>;
   paths: { root: string; workFiles: string; tmp: string };
   signal: AbortSignal;
   /** Where log lines go (default stderr). */
@@ -102,6 +104,7 @@ export function createCtx(o: CtxOptions): Ctx {
   const filesDeps = { run: o.run, workFiles: o.paths.workFiles, tmpDir: o.paths.tmp, root: o.paths.root, signal: o.signal, log };
   return {
     secrets: createSecrets(o.secrets, o.secretValues) as Ctx["secrets"],
+    config: Object.freeze({ ...o.config }) as Ctx["config"],
     sh,
     exec,
     readText: async (p) => readFileSync(resolve(p), "utf8"),

package/src/ctx/types.ts

@@ -1,5 +1,6 @@
 import type { Skipped } from "../core/handlers.ts";
 import type { FileRef } from "../core/models.ts";
+import type { AnyConfigEntry, ConfigValues } from "../core/config.ts";
 import type { DeclaredSecrets } from "../core/secrets.ts";
 
 /** Facts about the current execution, from the service (see README "Environment"). */
@@ -79,9 +80,11 @@ export interface OutputFileOptions {
   name?: string;
 }
 
-export interface Ctx<Sec extends string = string> {
+export interface Ctx<Sec extends string = string, Cfg extends AnyConfigEntry = never> {
   /** Exactly the secrets the step declares, read from the environment. */
   readonly secrets: DeclaredSecrets<Sec>;
+  /** Exactly the config entries the step declares, from the run's config snapshot (defaults applied). */
+  readonly config: ConfigValues<Cfg>;
   readonly sh: Sh;
   /** Run a binary directly, without a shell (works in shell-less images). Rejects on non-zero exit. */
   exec(argv: readonly string[], opts?: ExecOptions): Promise<void>;

package/src/describe/describe.ts

@@ -1,6 +1,9 @@
 // `describe`: evaluates the contracts (models + pipeline, never handlers) into the manifest and runs
 // every describe-time check. All problems are collected and reported together.
 import { z } from "zod";
+import { CONFIG_NAME, isConfigEntry, SECRET_REF_KIND } from "../core/config.ts";
+import { CONFIG_CASE_KEY, CONFIG_REF_KEY } from "../core/config-refs.ts";
+import { configRefPath, configRefTarget, isConfigRef, unionAt } from "../core/config.ts";
 import { isModel, isOptional, MODEL_NAME, type AnyModel } from "../core/models.ts";
 import { SECRET_NAME, type Secret } from "../core/secrets.ts";
 import { RESERVED_STEP_NAMES, STEP_NAME, isStep, type AnyStep } from "../core/steps.ts";
@@ -127,14 +130,46 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     return s.name;
   };
 
+  // ── config entries ──
+  const configs = new Map<string, { description: string; required: boolean; schema: JsonSchema; key: string; secretRefs: string[] }>();
+  const useConfig = (e: unknown, at: string): string | undefined => {
+    if (!isConfigEntry(e)) return void problems.push(`${at}: config entries must be config("name", "description", schema)`);
+    if (!CONFIG_NAME.test(e.name)) problems.push(`${at}: config name '${e.name}' must match ${CONFIG_NAME}`);
+    let schema: JsonSchema;
+    try {
+      schema = z.toJSONSchema(e.schema, { io: "input", target: "draft-2020-12" }) as JsonSchema;
+      delete schema.$schema;
+      schema = canonicalize(schema) as JsonSchema;
+    } catch (err) {
+      problems.push(`${at}: config '${e.name}' is not representable as JSON Schema (${(err as Error).message})`);
+      return e.name;
+    }
+    const key = JSON.stringify([e.description, schema]);
+    const prev = configs.get(e.name);
+    if (!prev) configs.set(e.name, { description: e.description, required: !e.schema.safeParse(undefined).success, schema, key, secretRefs: secretRefsOf(schema) });
+    else if (prev.key !== key) problems.push(`two different config entries are named '${e.name}' (one description and schema per config name)`);
+    return e.name;
+  };
+
   // ── step identity ──
   const steps = new Map<string, AnyStep>();
-  const registerStep = (s: AnyStep, where: string) => {
+  const placements = new Map<string, { step: AnyStep; cases: readonly CaseOf[] }[]>();
+  // Two places are mutually exclusive when they sit in different cases of the same select.
+  const exclusive = (a: readonly CaseOf[], b: readonly CaseOf[]) => a.some((x) => b.some((y) => y.select === x.select && y.value !== x.value));
+  const registerStep = (s: AnyStep, where: string, cases: readonly CaseOf[] = []) => {
     if (typeof s.name !== "string" || !STEP_NAME.test(s.name))
       problems.push(`${where}: step name '${String(s.name)}' must be lower-case kebab (${STEP_NAME})`);
     if (RESERVED.has(s.name)) problems.push(`${where}: '${s.name}' is reserved and cannot be a step name`);
-    if (steps.has(s.name)) problems.push(`duplicate step name '${s.name}'`);
-    steps.set(s.name, s);
+    const prev = placements.get(s.name) ?? [];
+    if (prev.some((p) => !exclusive(p.cases, cases))) problems.push(`duplicate step name '${s.name}'`);
+    else if (prev.length) {
+      if (prev.some((p) => p.step !== s && p.step.kind === "custom" && s.kind === "custom"))
+        problems.push(`step '${s.name}': two different custom steps share the name across select cases; handlers pair by name, so use one step or different names`);
+      if (prev.some((p) => (p.step.output?.name ?? null) !== (s.output?.name ?? null)))
+        problems.push(`step '${s.name}': its select cases must give it the same output model`);
+    }
+    placements.set(s.name, [...prev, { step: s, cases }]);
+    if (!steps.has(s.name)) steps.set(s.name, s);
   };
 
   const inputModel = data.input;
@@ -144,7 +179,7 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
   const outputViewOf = (modelName: string | null): JsonSchema | undefined => (modelName ? models.get(modelName)?.schemas.output : undefined);
 
   // ── one step ──
-  const describeStep = (node: StageStepNode, avail: Map<string, Avail>, failureHandler: boolean): StepDescriptorT => {
+  const describeStep = (node: StageStepNode, avail: Map<string, Avail>, failureHandler: boolean, cases: readonly CaseOf[] = []): StepDescriptorT => {
     const s = node.step;
     const at = `step '${s.name}'`;
     if (typeof s.image !== "string" || s.image.trim() === "") problems.push(`${at}: image must be a non-empty string`);
@@ -194,7 +229,26 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
       }
     }
 
+    for (const key of Object.keys(s.input as Record<string, unknown>))
+      if (key.startsWith("$")) problems.push(`${at}: input '${key}': keys starting with '$' are reserved`);
     const secretNames = s.secrets.map((x) => useSecret(x, at)).sort();
+    const configNames = [...new Set((s.config ?? []).map((c) => useConfig(c, at)).filter((n): n is string => n !== undefined))].sort();
+    // A library step that references parts of an entry needs the secrets those parts name; any other
+    // step receiving an entry needs every secret the entry names.
+    let refs: { ref: string; case?: string }[] = [];
+    try {
+      refs = s.builtin ? recordedConfigRefs(s.builtin.manifestConfig()) : [];
+    } catch {
+      // reported with the library configuration below
+    }
+    for (const name of configNames) {
+      const into = refs.filter((r) => r.ref.split(".")[0] === name);
+      const needed = into.length === 0
+        ? configs.get(name)?.secretRefs ?? []
+        : [...new Set(into.flatMap((r) => secretRefsOf(subSchemas(configs.get(name)?.schema, r.ref.split(".").slice(1), r.case, name))))].sort();
+      for (const ref of needed)
+        if (!secretNames.includes(ref)) problems.push(`${at}: config '${name}' references secret '${ref}' (secretRef), so the step must declare it in secrets`);
+    }
     let handlerHash: string;
     let config: Record<string, unknown> | undefined;
     if (s.kind === "custom") {
@@ -208,6 +262,13 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
         problems.push(`${at}: invalid ${s.kind} configuration (${(e as Error).message})`);
         config = {};
       }
+      for (const { ref, case: kase } of recordedConfigRefs(config)) {
+        const [entry, ...path] = ref.split(".") as [string, ...string[]];
+        if (kase !== undefined && !cases.some((c) => c.cond === kase))
+          problems.push(`${at}: config reference '${ref}' is narrowed to the select case '${kase}' and can only be used inside it`);
+        if (!configNames.includes(entry)) problems.push(`${at}: config reference '${ref}': the step does not receive config entry '${entry}'`);
+        else if (!resolveField(configs.get(entry)?.schema, path)) problems.push(`${at}: config reference '${ref}': config '${entry}' has no field '${path.join(".")}'`);
+      }
       handlerHash = libraryHandlerHash(s.kind, config, opts.harness);
     } else {
       problems.push(`${at}: library step of kind '${s.kind}' has no implementation`);
@@ -230,7 +291,10 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
       ...(s.timeoutSeconds !== undefined ? { timeoutSeconds: s.timeoutSeconds } : {}),
       ...(s.retries !== undefined ? { retries: s.retries } : {}),
       ...(config !== undefined ? { config: config as Record<string, z.core.util.JSONType> } : {}),
+      ...(configNames.length ? { configEntries: configNames } : {}),
+      ...(s.clusterAccess === true ? { clusterAccess: true as const } : {}),
     };
+    if (s.clusterAccess !== undefined && typeof s.clusterAccess !== "boolean") problems.push(`${at}: clusterAccess must be a boolean`);
     if (s.output && !isModel(s.output)) problems.push(`${at}: output must be a model`);
     return out;
   };
@@ -275,17 +339,22 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
   };
 
   // ── stages ──
-  const walk = (nodes: readonly StageNode[], avail: Map<string, Avail>): Stage[] => {
+  let selects = 0;
+  const walk = (nodes: readonly StageNode[], avail: Map<string, Avail>, cases: readonly CaseOf[] = []): Stage[] => {
     const out: Stage[] = [];
     for (const n of nodes) {
+      if (n.kind === "select") {
+        out.push(describeSelect(n, avail, cases, ++selects));
+        continue;
+      }
       if (n.kind === "stage") {
         const descs = n.steps.map((ss) => {
           if (!isStep(ss.step)) {
             problems.push("a stage entry is not a step");
             return undefined;
           }
-          registerStep(ss.step, "stage");
-          return describeStep(ss, avail, false);
+          registerStep(ss.step, "stage", cases);
+          return describeStep(ss, avail, false, cases);
         }).filter((d): d is StepDescriptorT => d !== undefined);
         // Outputs become available only after the barrier (same-stage siblings can't see each other).
         for (const ss of n.steps) if (isStep(ss.step)) avail.set(ss.step.name, { model: ss.step.output?.name ?? null, maybe: false });
@@ -305,13 +374,43 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
           when[field] = values;
         }
         const inner = new Map(avail);
-        const stages = walk(n.nodes, inner);
+        const stages = walk(n.nodes, inner, cases);
         for (const [name, a] of inner) if (!avail.has(name)) avail.set(name, { model: a.model, maybe: true });
         out.push({ when, stages });
       }
     }
     return out;
   };
+  const describeSelect = (n: Extract<StageNode, { kind: "select" }>, avail: Map<string, Avail>, cases: readonly CaseOf[], id: number): Stage => {
+    if (!isConfigRef(n.on)) {
+      problems.push("select: the first argument must be a config reference");
+      return { select: "", discriminator: "", cases: {} };
+    }
+    const ref = configRefPath(n.on);
+    const { entry, case: kase } = configRefTarget(n.on);
+    useConfig(entry, `select '${ref}'`);
+    if (kase !== undefined && !cases.some((c) => c.cond === kase))
+      problems.push(`select '${ref}': the reference is narrowed to the case '${kase}' and can only be used inside it`);
+    const union = unionAt(n.on);
+    if (!union) problems.push(`select '${ref}': it must reference a z.discriminatedUnion in config '${entry.name}'`);
+    else {
+      for (const v of union.values) if (!Object.hasOwn(n.cases, v)) problems.push(`select '${ref}': no case for ${union.discriminator} '${v}'`);
+      for (const v of Object.keys(n.cases)) if (!union.values.includes(v)) problems.push(`select '${ref}': '${v}' is not a value of ${union.discriminator} (${union.values.join(", ")})`);
+    }
+    const discriminator = union?.discriminator ?? "";
+    const branches = Object.entries(n.cases).map(([value, nodes]) => {
+      const inner = new Map(avail);
+      const stages = walk(nodes, inner, [...cases, { select: id, value, cond: `${ref}.${discriminator}=${value}` }]);
+      return { value, inner, stages };
+    });
+    // A step every case has is as available as in its cases; one only some cases have is maybe-available.
+    const added = new Set(branches.flatMap((b) => [...b.inner.keys()].filter((k) => !avail.has(k))));
+    for (const name of added) {
+      const present = branches.map((b) => b.inner.get(name)).filter((a): a is Avail => a !== undefined);
+      avail.set(name, { model: present[0]!.model, maybe: present.length < branches.length || present.some((a) => a.maybe) });
+    }
+    return { select: ref, discriminator, cases: Object.fromEntries(branches.map((b) => [b.value, b.stages])) };
+  };
   const stages = walk(data.nodes, new Map([["input", { model: inputModel.name, maybe: false }]]));
 
   // ── failure handlers ──
@@ -369,6 +468,13 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
     harness: opts.harness,
     models: Object.fromEntries([...models].map(([k, v]) => [k, v.schemas])),
     secrets: [...secrets].sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0)).map(([name, description]) => ({ name, description })),
+    ...(configs.size
+      ? {
+          config: [...configs]
+            .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0))
+            .map(([name, c]) => ({ name, description: c.description, required: c.required, schema: c.schema })),
+        }
+      : {}),
     triggers,
     stages,
     failureHandlers,
@@ -381,6 +487,74 @@ export function describePipeline(pipeline: unknown, opts: DescribeOptions): Mani
 /** Canonical manifest text (what `describe` prints and the service hashes). */
 export const manifestText = (m: ManifestT): string => canonicalJson(m);
 
+/**
+ * The schemas at `path` inside an entry's schema: every union branch that has the field, except where
+ * `kase` (`<entry>.<path>.<discriminator>=<value>`) narrows a union to one branch.
+ */
+export function subSchemas(schema: unknown, path: readonly string[], kase: string | undefined, entry: string): unknown[] {
+  let narrow: { at: string; discriminator: string; value: string } | undefined;
+  if (kase) {
+    const eq = kase.lastIndexOf("=");
+    const left = kase.slice(0, eq);
+    const dot = left.lastIndexOf(".");
+    narrow = { at: left.slice(0, dot), discriminator: left.slice(dot + 1), value: kase.slice(eq + 1) };
+  }
+  const walk = (node: unknown, rest: readonly string[], here: string): unknown[] => {
+    if (node === null || typeof node !== "object") return [];
+    const o = node as JsonSchema;
+    const branches = (o.oneOf ?? o.anyOf) as JsonSchema[] | undefined;
+    if (Array.isArray(branches)) {
+      const chosen = narrow && narrow.at === here
+        ? branches.filter((b) => ((b.properties as Record<string, JsonSchema> | undefined)?.[narrow!.discriminator] as JsonSchema | undefined)?.const === narrow!.value)
+        : branches;
+      return chosen.flatMap((b) => walk(b, rest, here));
+    }
+    if (rest.length === 0) return [node];
+    const props = o.properties as Record<string, JsonSchema> | undefined;
+    if (props && Object.hasOwn(props, rest[0]!)) return walk(props[rest[0]!], rest.slice(1), `${here}.${rest[0]}`);
+    return [];
+  };
+  return walk(schema, path, entry);
+}
+
+/** Secret names of every secretRef inside a config entry's JSON Schema. */
+export function secretRefsOf(schema: unknown): string[] {
+  const out = new Set<string>();
+  const walk = (v: unknown) => {
+    if (Array.isArray(v)) return v.forEach(walk);
+    if (v === null || typeof v !== "object") return;
+    const o = v as JsonSchema;
+    if (o["x-olve-kind"] === SECRET_REF_KIND) {
+      const name = (o.properties as { secret?: { const?: unknown } } | undefined)?.secret?.const;
+      if (typeof name === "string") out.add(name);
+    }
+    Object.values(o).forEach(walk);
+  };
+  walk(schema);
+  return [...out].sort();
+}
+
+/** The `{"$config": "<entry>.<path>"[, "$case": …]}` references in a library step's recorded configuration. */
+export function recordedConfigRefs(v: unknown, out: { ref: string; case?: string }[] = []): { ref: string; case?: string }[] {
+  if (Array.isArray(v)) v.forEach((x) => recordedConfigRefs(x, out));
+  else if (v !== null && typeof v === "object") {
+    const o = v as Record<string, unknown>;
+    const keys = Object.keys(o).sort();
+    const isRef = typeof o[CONFIG_REF_KEY] === "string"
+      && (keys.length === 1 ? keys[0] === CONFIG_REF_KEY : keys.length === 2 && keys[0] === CONFIG_CASE_KEY && keys[1] === CONFIG_REF_KEY && typeof o[CONFIG_CASE_KEY] === "string");
+    if (isRef) out.push({ ref: o[CONFIG_REF_KEY] as string, ...(keys.length === 2 ? { case: o[CONFIG_CASE_KEY] as string } : {}) });
+    else Object.values(o).forEach((x) => recordedConfigRefs(x, out));
+  }
+  return out;
+}
+
+/** A select case a step sits in: which select (numbered in describe order), which value, and its condition text. */
+interface CaseOf {
+  select: number;
+  value: string;
+  cond: string;
+}
+
 function camel(name: string): string {
   return name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase());
 }