@olivervea/pipelines 2.0.0-beta.17 → 2.0.0-beta.19

package/src/builder/refs.ts

@@ -1,7 +1,7 @@
-import type { RefBrand } from "../core/brands.ts";
-import type { AnyStep, InferEntry } from "../core/steps.ts";
-import type { External } from "../core/external.ts";
-import type { Primitive } from "../core/types.ts";
+import type { RefBrand } from '../core/brands.ts';
+import type { AnyStep, InferEntry } from '../core/steps.ts';
+import type { External } from '../core/external.ts';
+import type { Primitive } from '../core/types.ts';
 
 /**
  * A typed reference into the run pool — what mappers see. `symbol &` makes template strings, `+`
@@ -13,7 +13,11 @@ 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)> };
+    : {
+        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> =
@@ -26,5 +30,7 @@ export type Mappable<T> =
 
 /** What a mapper provides: every input except the external ones, which come from outside the run. */
 export type MapperResult<S extends AnyStep> = {
-  [K in keyof S["input"] as S["input"][K] extends External ? never : K]: Mappable<InferEntry<S["input"][K]>>;
+  [K in keyof S['input'] as S['input'][K] extends External ? never : K]: Mappable<
+    InferEntry<S['input'][K]>
+  >;
 };

package/src/core/brands.ts

@@ -1,11 +1,11 @@
 // 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");
+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;

package/src/core/config-refs.ts

@@ -1,31 +1,41 @@
 // 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";
+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;
+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";
+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";
+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;
+  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[] {
+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);
@@ -38,14 +48,22 @@ export function configRefsIn(v: unknown, into = new Map<string, AnyConfigEntry>(
 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 } : {}) };
+    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`);
+      if (k.startsWith('$'))
+        throw new Error(`key '${k}': keys starting with '$' are reserved`);
       out[k] = recordConfigRefs(x);
     }
     return out;
@@ -54,12 +72,20 @@ export function recordConfigRefs(v: unknown): unknown {
 }
 
 /** `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> {
+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`);
+    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;
+    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>;

package/src/core/config.ts

@@ -1,7 +1,7 @@
-import { z } from "zod";
-import type { Secret } from "./secrets.ts";
+import { z } from 'zod';
+import type { Secret } from './secrets.ts';
 
-const CONFIG_REF = Symbol.for("olve.configRef");
+const CONFIG_REF = Symbol.for('olve.configRef');
 declare const VALUE: unique symbol;
 
 interface RefTarget {
@@ -27,56 +27,100 @@ 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)> };
+  : {
+      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" | "$";
+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";
+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> &
+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>> };
+  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"]);
+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 } : {}) }) });
+  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;
+      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 {
+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}`);
+  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 });
+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, []);
+      if (typeof prop === 'symbol' || NOT_REFS.has(prop)) return undefined;
+      if (prop === '$') return node(entry as AnyConfigEntry, []);
       return node(entry as AnyConfigEntry, [prop]);
     },
   });
@@ -86,39 +130,62 @@ export function config<const N extends string, S extends z.ZodType>(name: N, des
 }
 
 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;
+  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;
+  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 } {
+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(".");
+  return [entry.name, ...path].join('.');
 }
 
-export const SECRET_REF_KIND = "secretRef";
+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 });
+  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"]> };
+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;
+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];
+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 }>;
 
@@ -132,16 +199,26 @@ function unwrap(schema: z.ZodType): 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 {
+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> } };
+  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");
+  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/external.ts

@@ -1,14 +1,19 @@
-import { isModel, type AnyModel } from "./models.ts";
+import { isModel, type AnyModel } from './models.ts';
 
 /** Who or what may supply an external input's value. */
 export type ExternalSource =
-  | { readonly kind: "person" }
-  | { readonly kind: "callback" }
-  | { readonly kind: "poll"; readonly url: string; readonly valuePath: string; readonly intervalSeconds: number };
+  | { readonly kind: 'person' }
+  | { readonly kind: 'callback' }
+  | {
+      readonly kind: 'poll';
+      readonly url: string;
+      readonly valuePath: string;
+      readonly intervalSeconds: number;
+    };
 
 /** A signed-in user answers, in the UI or with `pl input`. */
 export function person(): ExternalSource {
-  return Object.freeze({ kind: "person" as const });
+  return Object.freeze({ kind: 'person' as const });
 }
 
 /**
@@ -16,7 +21,7 @@ export function person(): ExternalSource {
  * with `ctx.inputUrl(step, input)`. The body is the value as JSON, or `{"$decline": "reason"}`.
  */
 export function callback(): ExternalSource {
-  return Object.freeze({ kind: "callback" as const });
+  return Object.freeze({ kind: 'callback' as const });
 }
 
 export interface PollOptions {
@@ -30,7 +35,12 @@ export interface PollOptions {
 
 /** The service polls `url` while the step waits and answers with the value at `valuePath` once it validates. */
 export function poll(options: PollOptions): ExternalSource {
-  return Object.freeze({ kind: "poll" as const, url: options.url, valuePath: options.valuePath, intervalSeconds: options.intervalSeconds ?? 30 });
+  return Object.freeze({
+    kind: 'poll' as const,
+    url: options.url,
+    valuePath: options.valuePath,
+    intervalSeconds: options.intervalSeconds ?? 30,
+  });
 }
 
 /**
@@ -38,7 +48,7 @@ export function poll(options: PollOptions): ExternalSource {
  * validated against `model`), then runs with the value in its input like any other.
  */
 export interface External<M extends AnyModel = AnyModel> {
-  readonly kind: "external";
+  readonly kind: 'external';
   readonly model: M;
   readonly title: string;
   readonly description: string;
@@ -53,16 +63,24 @@ export interface ExternalOptions {
   from?: readonly ExternalSource[];
 }
 
-export function external<M extends AnyModel>(model: M, options: ExternalOptions): External<M> {
+export function external<M extends AnyModel>(
+  model: M,
+  options: ExternalOptions,
+): External<M> {
   return Object.freeze({
-    kind: "external" as const,
+    kind: 'external' as const,
     model,
     title: options.title,
-    description: options.description ?? "",
+    description: options.description ?? '',
     from: Object.freeze([...(options.from ?? [person()])]),
   });
 }
 
 export function isExternal(v: unknown): v is External {
-  return typeof v === "object" && v !== null && (v as { kind?: unknown }).kind === "external" && isModel((v as { model?: unknown }).model);
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as { kind?: unknown }).kind === 'external' &&
+    isModel((v as { model?: unknown }).model)
+  );
 }

package/src/core/handlers.ts

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

package/src/core/models.ts

@@ -1,30 +1,40 @@
-import { z } from "zod";
-import type { ModelBrand } from "./brands.ts";
+import { z } from 'zod';
+import type { ModelBrand } from './brands.ts';
 
 /** A named, nominal zod schema. The name is its identity in the manifest (one schema per name). */
 export interface Model<N extends string = string, S extends z.ZodType = z.ZodType> {
-  readonly kind: "model";
+  readonly kind: 'model';
   readonly name: N;
   readonly schema: S;
 }
 export type AnyModel = Model<string, z.ZodType>;
 
 /** Output view of a model (`z.output`), nominally branded with the model name. The brand is optional, so plain literals still assign. */
-export type Infer<M extends AnyModel> = z.output<M["schema"]> & { readonly [ModelBrand]?: M["name"] };
+export type Infer<M extends AnyModel> = z.output<M['schema']> & {
+  readonly [ModelBrand]?: M['name'];
+};
 /** Input view of a model (`z.input`: fields with defaults are optional). What trigger mappers produce. */
-export type InferInput<M extends AnyModel> = z.input<M["schema"]>;
+export type InferInput<M extends AnyModel> = z.input<M['schema']>;
 /** Output view without the nominal brand. */
-export type Plain<M extends AnyModel> = z.output<M["schema"]>;
+export type Plain<M extends AnyModel> = z.output<M['schema']>;
 
 /** Model names: identifier-like, so they are safe as JSON keys, C# names and URL segments. */
 export const MODEL_NAME = /^[A-Za-z][A-Za-z0-9_]*$/;
 
-export function model<const N extends string, S extends z.ZodType>(name: N, schema: S): Model<N, S> {
-  return Object.freeze({ kind: "model" as const, name, schema });
+export function model<const N extends string, S extends z.ZodType>(
+  name: N,
+  schema: S,
+): Model<N, S> {
+  return Object.freeze({ kind: 'model' as const, name, schema });
 }
 
 export function isModel(v: unknown): v is AnyModel {
-  return typeof v === "object" && v !== null && (v as { kind?: unknown }).kind === "model" && (v as { schema?: unknown }).schema instanceof z.ZodType;
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as { kind?: unknown }).kind === 'model' &&
+    (v as { schema?: unknown }).schema instanceof z.ZodType
+  );
 }
 
 // ─── File references ─────────────────────────────────────────────────────────────────────────
@@ -47,8 +57,8 @@ const FileRefSchema = z
     path: z.string().regex(FILE_PATH),
     sha256: z.string().regex(/^[0-9a-f]{64}$/),
   })
-  .brand<"FileRef">()
-  .meta({ "x-olve-kind": "fileRef" });
+  .brand<'FileRef'>()
+  .meta({ 'x-olve-kind': 'fileRef' });
 
 /** A file or directory in some step attempt's output (`runs/<p>/<run>/<step>/<attempt>/files/<path>`). Branded: only `ctx.output.*` or a mapper ref produce one. */
 export type FileRef = z.output<typeof FileRefSchema>;
@@ -60,12 +70,17 @@ export const fileRefSchema = FileRefSchema;
 
 /** A step input that may be missing because its producer was *maybe skipped* (inside a `when`). There must still be a producer. */
 export interface Optional<M extends AnyModel = AnyModel> {
-  readonly kind: "optional";
+  readonly kind: 'optional';
   readonly model: M;
 }
 export function optional<M extends AnyModel>(model: M): Optional<M> {
-  return Object.freeze({ kind: "optional" as const, model });
+  return Object.freeze({ kind: 'optional' as const, model });
 }
 export function isOptional(v: unknown): v is Optional {
-  return typeof v === "object" && v !== null && (v as { kind?: unknown }).kind === "optional" && isModel((v as { model?: unknown }).model);
+  return (
+    typeof v === 'object' &&
+    v !== null &&
+    (v as { kind?: unknown }).kind === 'optional' &&
+    isModel((v as { model?: unknown }).model)
+  );
 }