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

package/src/build/build.ts

@@ -0,0 +1,125 @@
+// olve-build: pipeline dir → single executable + step.tar.gz + manifest.json.
+import { existsSync, mkdirSync, rmSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { canonicalJson } from "../util/canonical.ts";
+import { sha256File } from "../util/hash.ts";
+import type { HarnessInfo } from "../util/handler-hash.ts";
+import { writeTarGz } from "../util/tar.ts";
+import { MANIFEST_BEGIN, MANIFEST_END, uploadFile } from "../harness/result.ts";
+import { GLIBC_INTERP, MUSL_INTERP, readInterpreter } from "./elf.ts";
+import { handlerHashes, type HandlerHash } from "./hashes.ts";
+import { harnessInfo, loadProject, relPosix, type Project } from "./project.ts";
+
+export const BUILD_FLAGS = ["--no-compile-autoload-dotenv", "--no-compile-autoload-bunfig", "--bytecode", "--format=esm"] as const;
+export type Target = "bun-linux-x64" | "bun-linux-x64-musl";
+
+export class BuildError extends Error {
+  override name = "BuildError";
+  constructor(message: string, readonly exitCode = 1) {
+    super(message);
+  }
+}
+
+export interface BuildOptions {
+  out: string;
+  target?: Target;
+  /** Pre-signed PUT for step.tar.gz. */
+  uploadUrl?: string;
+  /** Print the manifest between sentinels on stdout (for the build Job's pod log). */
+  sentinels?: boolean;
+  log?: (line: string) => void;
+  stdout?: (text: string) => Promise<void>;
+}
+
+export interface BuildResult {
+  binary: string;
+  archive: string;
+  manifestFile: string;
+  manifest: string;
+  hashes: Record<string, HandlerHash>;
+  harness: HarnessInfo;
+}
+
+/** Writes `<dir>/.olve/gen/{handlers,entry}.ts`: the literal-import handler registry + binary entry. */
+export function generateEntry(project: Project, hashes: Record<string, string>, harness: HarnessInfo): string {
+  const gen = join(project.dir, ".olve", "gen");
+  mkdirSync(gen, { recursive: true });
+  const registry = project.handlers.map(([name, file]) => `  ${JSON.stringify(name)}: () => import(${JSON.stringify(relPosix(gen, file))}),`).join("\n");
+  writeFileSync(
+    join(gen, "handlers.ts"),
+    `// GENERATED by olve-build — do not edit.\n` +
+      `import type { HandlerRegistry, HarnessInfo } from "@olve/pipelines/harness";\n\n` +
+      `export const handlers: HandlerRegistry = {\n${registry}\n};\n\n` +
+      `export const handlerHashes: Record<string, string> = ${JSON.stringify(hashes, null, 2)};\n\n` +
+      `export const harness: HarnessInfo = ${JSON.stringify(harness, null, 2)};\n`,
+  );
+  const entry = join(gen, "entry.ts");
+  writeFileSync(
+    entry,
+    `// GENERATED by olve-build — do not edit. Entry point of the step binary.\n` +
+      `import pipeline from ${JSON.stringify(relPosix(gen, project.pipelineFile))};\n` +
+      `import { runHarness } from "@olve/pipelines/harness";\n` +
+      `import { handlers, handlerHashes, harness } from "./handlers.ts";\n\n` +
+      `process.exit(await runHarness({ pipeline, handlers, handlerHashes, harness }, process.argv.slice(2)));\n`,
+  );
+  return entry;
+}
+
+export async function build(dir: string, opts: BuildOptions): Promise<BuildResult> {
+  const log = opts.log ?? ((l: string) => process.stderr.write(l + "\n"));
+  const stdout = opts.stdout ?? (async (t: string) => void (await Bun.write(Bun.stdout, t)));
+  const target = opts.target ?? "bun-linux-x64";
+  const project = loadProject(dir);
+  const out = resolve(opts.out);
+  mkdirSync(out, { recursive: true });
+  const harness = harnessInfo();
+
+  const t0 = performance.now();
+  const hashes = await handlerHashes(project, harness);
+  const entry = generateEntry(project, Object.fromEntries(Object.entries(hashes).map(([k, v]) => [k, v.handlerHash])), harness);
+  log(`olve-build: ${project.handlers.length} handler(s) hashed in ${((performance.now() - t0) / 1000).toFixed(2)}s`);
+
+  // 1. compile
+  const binary = join(out, "step");
+  rmSync(binary, { force: true });
+  const t1 = performance.now();
+  const p = Bun.spawnSync([process.execPath, "build", "--compile", `--target=${target}`, ...BUILD_FLAGS, entry, `--outfile=${binary}`], {
+    cwd: project.dir,
+    stdout: "pipe",
+    stderr: "pipe",
+    env: { ...process.env, NO_COLOR: "1" },
+  });
+  if (p.exitCode !== 0 || !existsSync(binary))
+    throw new BuildError(`bun build --compile failed (exit ${p.exitCode}):\n${p.stdout.toString()}${p.stderr.toString()}`);
+  log(`olve-build: compiled ${target} in ${((performance.now() - t1) / 1000).toFixed(2)}s`);
+
+  // 2. loader check: the harness launches the binary through /olve/lib/<loader>; a musl binary
+  //    (e.g. compiled on alpine, where bun-linux-x64 silently yields musl) would not start.
+  const expected = target === "bun-linux-x64" ? GLIBC_INTERP : MUSL_INTERP;
+  const interp = readInterpreter(binary);
+  if (interp !== expected)
+    throw new BuildError(`compiled binary has PT_INTERP ${interp ?? "(none)"}, expected ${expected} — compile on a glibc Bun image (oven/bun:<version>-slim), not alpine`);
+
+  // 3. describe (runs the real binary: the manifest is exactly what the step pods will see)
+  const d = Bun.spawnSync([binary, "describe"], { cwd: out, stdout: "pipe", stderr: "pipe", env: { PATH: process.env.PATH ?? "/usr/bin:/bin" } });
+  if (d.exitCode !== 0) throw new BuildError(`describe failed (exit ${d.exitCode}):\n${d.stderr.toString()}`, d.exitCode ?? 1);
+  const manifest = d.stdout.toString();
+  const manifestFile = join(out, "manifest.json");
+  writeFileSync(manifestFile, manifest);
+
+  // 4. step.tar.gz (deterministic: `step` at the root, 0755, mtime 0)
+  const archive = join(out, "step.tar.gz");
+  await writeTarGz(archive, [{ path: "step", type: "file", mode: 0o755, source: binary }]);
+  writeFileSync(
+    join(out, "build.json"),
+    canonicalJson({ target, flags: BUILD_FLAGS, harness, handlers: hashes, binarySha256: sha256File(binary), archiveSha256: sha256File(archive) }),
+  );
+  log(`olve-build: wrote ${archive}`);
+
+  if (opts.uploadUrl) {
+    await uploadFile(opts.uploadUrl, archive, log);
+    log("olve-build: uploaded step.tar.gz");
+  }
+  if (opts.sentinels) await stdout(`${MANIFEST_BEGIN}\n${manifest}${MANIFEST_END}\n`);
+  return { binary, archive, manifestFile, manifest, hashes, harness };
+}

package/src/build/cli.ts

@@ -0,0 +1,52 @@
+#!/usr/bin/env bun
+// olve-build <pipelineDir> --out <dir> [--target bun-linux-x64|bun-linux-x64-musl] [--upload-url <url>] [--sentinels] [--hash-only]
+import { parseArgs } from "node:util";
+import { canonicalJson } from "../util/canonical.ts";
+import { build, BuildError, type Target } from "./build.ts";
+import { handlerHashes } from "./hashes.ts";
+import { harnessInfo, loadProject, ProjectError } from "./project.ts";
+
+const USAGE = "usage: olve-build <pipelineDir> --out <dir> [--target bun-linux-x64|bun-linux-x64-musl] [--upload-url <url>] [--sentinels]\n       olve-build <pipelineDir> --hash-only";
+
+async function main(): Promise<number> {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      allowPositionals: true,
+      options: {
+        out: { type: "string" },
+        target: { type: "string" },
+        "upload-url": { type: "string" },
+        sentinels: { type: "boolean", default: false },
+        "hash-only": { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+  } catch (e) {
+    console.error(`${(e as Error).message}\n${USAGE}`);
+    return 64;
+  }
+  const { values, positionals } = parsed;
+  if (values.help) return console.log(USAGE), 0;
+  if (positionals.length !== 1) return console.error(USAGE), 64;
+  const dir = positionals[0]!;
+  try {
+    if (values["hash-only"]) {
+      const h = await handlerHashes(loadProject(dir), harnessInfo());
+      await Bun.write(Bun.stdout, canonicalJson({ harness: harnessInfo(), handlers: h }));
+      return 0;
+    }
+    if (!values.out) return console.error(`--out is required\n${USAGE}`), 64;
+    const target = (values.target ?? "bun-linux-x64") as Target;
+    if (target !== "bun-linux-x64" && target !== "bun-linux-x64-musl") return console.error(`unsupported target ${target}`), 64;
+    await build(dir, { out: values.out, target, uploadUrl: values["upload-url"], sentinels: values.sentinels });
+    return 0;
+  } catch (e) {
+    if (e instanceof BuildError) return console.error(e.message), e.exitCode;
+    if (e instanceof ProjectError) return console.error(e.message), 78;
+    console.error((e as Error)?.stack ?? String(e));
+    return 1;
+  }
+}
+
+if (import.meta.main) process.exit(await main());

package/src/build/elf.ts

@@ -0,0 +1,35 @@
+import { closeSync, openSync, readSync } from "node:fs";
+
+export const GLIBC_INTERP = "/lib64/ld-linux-x86-64.so.2";
+export const MUSL_INTERP = "/lib/ld-musl-x86-64.so.1";
+
+function read(fd: number, pos: number, len: number): Buffer {
+  const b = Buffer.alloc(len);
+  const n = readSync(fd, b, 0, len, pos);
+  if (n !== len) throw new Error("truncated ELF file");
+  return b;
+}
+
+/** PT_INTERP of an x86-64 ELF executable, or null if it has none (static). */
+export function readInterpreter(path: string): string | null {
+  const fd = openSync(path, "r");
+  try {
+    const h = read(fd, 0, 64);
+    if (h.readUInt32BE(0) !== 0x7f454c46) throw new Error(`${path} is not an ELF file`);
+    if (h[4] !== 2 || h[5] !== 1) throw new Error(`${path} is not a 64-bit little-endian ELF file`);
+    const phoff = Number(h.readBigUInt64LE(0x20));
+    const phentsize = h.readUInt16LE(0x36);
+    const phnum = h.readUInt16LE(0x38);
+    for (let i = 0; i < phnum; i++) {
+      const ph = read(fd, phoff + i * phentsize, phentsize);
+      if (ph.readUInt32LE(0) === 3 /* PT_INTERP */) {
+        const off = Number(ph.readBigUInt64LE(0x08));
+        const size = Number(ph.readBigUInt64LE(0x20));
+        return read(fd, off, size).toString("latin1").replace(/\0+$/, "");
+      }
+    }
+    return null;
+  } finally {
+    closeSync(fd);
+  }
+}

package/src/build/hashes.ts

@@ -0,0 +1,67 @@
+// Per-handler hashes: bundle each handler on its own with the contract files and the SDK external
+// (tree-shaken → function-level granularity; embedded scripts are bundle outputs too), then hash the
+// outputs. Contract changes are versioned through the manifest's model/step entries, SDK changes
+// through `harness`; both are combined in composeHandlerHash.
+import { dirname, join, resolve } from "node:path";
+import type { BunPlugin } from "bun";
+import { composeHandlerHash, type HarnessInfo } from "../util/handler-hash.ts";
+import { sha256Hex } from "../util/hash.ts";
+import type { Project } from "./project.ts";
+
+export interface HandlerHash {
+  /** Hash of the bundle outputs alone. */
+  bundleHash: string;
+  /** composeHandlerHash(bundleHash, harness) — what the manifest carries. */
+  handlerHash: string;
+  /** Bundle output names (for diagnostics). */
+  outputs: string[];
+}
+
+function externals(project: Project): BunPlugin {
+  const contracts = new Set(project.contractFiles);
+  return {
+    name: "olve-handler-hash-externals",
+    setup(b) {
+      b.onResolve({ filter: /^@olve\/pipelines(\/.*)?$/ }, (args) => ({ path: args.path, external: true }));
+      b.onResolve({ filter: /^\.{1,2}\// }, (args) => {
+        const base = resolve(dirname(args.importer), args.path);
+        for (const cand of [base, `${base}.ts`, join(base, "index.ts")]) if (contracts.has(cand)) return { path: args.path, external: true };
+        return undefined;
+      });
+    },
+  };
+}
+
+export async function bundleHash(project: Project, entry: string): Promise<{ hash: string; outputs: string[] }> {
+  const r = await Bun.build({
+    entrypoints: [entry],
+    target: "bun",
+    format: "esm",
+    root: project.dir,
+    naming: { entry: "[dir]/[name].[ext]", chunk: "[dir]/[name].[ext]", asset: "[dir]/[name].[ext]" },
+    plugins: [externals(project)],
+    throw: false,
+  });
+  if (!r.success) throw new AggregateError(r.logs, `bundling ${entry} failed:\n${r.logs.map(String).join("\n")}`);
+  const parts: string[] = [];
+  const outputs: string[] = [];
+  for (const o of [...r.outputs].sort((a, b) => (a.path < b.path ? -1 : a.path > b.path ? 1 : 0))) {
+    const name = o.path.replace(/^\.\//, "");
+    outputs.push(name);
+    const bytes = new Uint8Array(await o.arrayBuffer());
+    // Bun prefixes each module with a `// <path>` comment relative to the *process cwd*; drop those
+    // so the hash depends only on code, not on where the repo or the build tool runs.
+    const content = name.endsWith(".js") ? new TextDecoder().decode(bytes).replace(/^\/\/ \S+\n/gm, "") : bytes;
+    parts.push(`${name}\0${sha256Hex(content)}`);
+  }
+  return { hash: "sha256:" + sha256Hex(parts.join("\n")), outputs };
+}
+
+export async function handlerHashes(project: Project, harness: HarnessInfo): Promise<Record<string, HandlerHash>> {
+  const out: Record<string, HandlerHash> = {};
+  for (const [name, file] of project.handlers) {
+    const b = await bundleHash(project, file);
+    out[name] = { bundleHash: b.hash, handlerHash: composeHandlerHash(b.hash, harness), outputs: b.outputs };
+  }
+  return out;
+}

package/src/build/project.ts

@@ -0,0 +1,79 @@
+// Layout of a pipeline directory and the identity of the SDK building it.
+import { existsSync, readdirSync, readFileSync, statSync } from "node:fs";
+import { dirname, join, relative, resolve } from "node:path";
+import { sha256Hex } from "../util/hash.ts";
+import type { HarnessInfo } from "../util/handler-hash.ts";
+
+export const SDK_ROOT = resolve(import.meta.dir, "../..");
+
+export interface Project {
+  dir: string;
+  pipelineFile: string;
+  /** Contract files (excluded from handler bundles): pipeline.ts, models.ts. */
+  contractFiles: string[];
+  /** step name → absolute handler file, sorted by name. */
+  handlers: [string, string][];
+}
+
+export class ProjectError extends Error {
+  override name = "ProjectError";
+}
+
+export function loadProject(dirArg: string): Project {
+  const dir = resolve(dirArg);
+  if (!existsSync(dir) || !statSync(dir).isDirectory()) throw new ProjectError(`${dirArg} is not a directory`);
+  const pipelineFile = join(dir, "pipeline.ts");
+  if (!existsSync(pipelineFile)) throw new ProjectError(`${join(dirArg, "pipeline.ts")} not found (it must default-export pipeline({...}))`);
+  const contractFiles = ["pipeline.ts", "models.ts"].map((f) => join(dir, f)).filter((f) => existsSync(f));
+  const hdir = join(dir, "handlers");
+  const handlers: [string, string][] = existsSync(hdir)
+    ? readdirSync(hdir)
+        .filter((f) => f.endsWith(".ts") && !f.endsWith(".test.ts") && !f.endsWith(".d.ts") && statSync(join(hdir, f)).isFile())
+        .sort()
+        .map((f) => [f.slice(0, -3), join(hdir, f)])
+    : [];
+  return { dir, pipelineFile, contractFiles, handlers };
+}
+
+function listFiles(dir: string): string[] {
+  const out: string[] = [];
+  for (const e of readdirSync(dir, { withFileTypes: true })) {
+    const p = join(dir, e.name);
+    if (e.isDirectory()) out.push(...listFiles(p));
+    else if (e.isFile()) out.push(p);
+  }
+  return out;
+}
+
+let cached: HarnessInfo | undefined;
+/**
+ * Harness identity: Bun version, SDK version, and a hash over the SDK's runtime sources (src/,
+ * without the build and dev tools) plus the zod version the SDK resolves.
+ */
+export function harnessInfo(): HarnessInfo {
+  if (cached) return cached;
+  const pkg = JSON.parse(readFileSync(join(SDK_ROOT, "package.json"), "utf8")) as { version: string };
+  const src = join(SDK_ROOT, "src");
+  const files = listFiles(src)
+    .map((f) => relative(src, f).split("\\").join("/"))
+    .filter((f) => !f.startsWith("build/") && !f.startsWith("dev/") && !f.startsWith("testing/") && f.endsWith(".ts"))
+    .sort();
+  const h = new Bun.CryptoHasher("sha256");
+  for (const f of files) h.update(`${f}\0${sha256Hex(readFileSync(join(src, f)))}\n`);
+  let zodVersion = "unknown";
+  try {
+    const zodPkg = Bun.resolveSync("zod/package.json", SDK_ROOT);
+    zodVersion = (JSON.parse(readFileSync(zodPkg, "utf8")) as { version: string }).version;
+  } catch {
+    /* keep unknown */
+  }
+  h.update(`zod@${zodVersion}\n`);
+  cached = { bun: Bun.version, sdk: pkg.version, sdkHash: "sha256:" + h.digest("hex") };
+  return cached;
+}
+
+export const relPosix = (from: string, to: string) => {
+  const r = relative(from, to).split("\\").join("/");
+  return r.startsWith(".") ? r : `./${r}`;
+};
+export { dirname };

package/src/builder/pipeline.ts

@@ -0,0 +1,291 @@
+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 { 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";
+
+// ─── 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 (see spikes/sdk-types):
+ *  - 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> };
+
+// ─── 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[] };
+
+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;
+    };
+
+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 ────────────────────────────────────────────────────────────────────────
+
+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 ?? [],
+    };
+  }
+
+  /** 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;
+  }
+
+  /**
+   * 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;
+  }
+
+  /**
+   * 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;
+  }
+
+  /** 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 (returned !== (inner as unknown)) 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;
+  }
+
+  /** 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>[] },
+  ): this {
+    this[PIPELINE].failureHandlers.push({ step: handler as AnyStep, steps: opts?.steps ? [...(opts.steps as readonly AnyStep[])] : null });
+    return this;
+  }
+}
+
+/** 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;
+}