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

package/src/describe/manifest-schema.ts

@@ -0,0 +1,179 @@
+// The manifest format, defined once in zod. `manifest.schema.json` is generated from this
+// (bun scripts/gen-manifest-schema.ts) and describe validates every manifest against it.
+import { z } from "zod";
+
+export const API_VERSION = "2.0";
+
+const stepName = z.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/).describe("Step name: lower-case kebab, 1-63 chars. The step's identity.");
+const modelName = z.string().regex(/^[A-Za-z][A-Za-z0-9_]*$/).describe("Model name (key of `models`).");
+const secretName = z.string().regex(/^[A-Z_][A-Z0-9_]*$/).describe("Secret name; also the env var name in the step container.");
+const configName = z.string().regex(/^[a-z][a-zA-Z0-9]*$/).describe("Config entry name; a key of the pipeline's config document.");
+const hash = z.string().regex(/^sha256:[0-9a-f]{64}$/);
+const Json = z.json().meta({ id: "Json", description: "Any JSON value." });
+const jsonSchema = z.record(z.string(), z.unknown()).describe("A JSON Schema (draft 2020-12) object, canonical (sorted keys, no $schema).");
+
+export const RefMapping = z
+  .strictObject({
+    ref: z
+      .string()
+      .regex(/^(?:input|failure|[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?)(?:\.[^.]+)*$/)
+      .describe("'<root>' or '<root>.<field>.<field>…'. Root: 'input' (pipeline input), a step name (that step's output) or 'failure' (FailureContext, failure handlers only)."),
+  })
+  .describe("Value taken from the run pool. A ref whose root step was skipped yields no value (only allowed for optional inputs).");
+export const ConstMapping = z.strictObject({ const: Json }).describe("A JSON constant.");
+
+export type Mapping = { ref: string } | { const: unknown } | { [field: string]: Mapping };
+export const Mapping: z.ZodType<Mapping> = z
+  .union([
+    RefMapping,
+    ConstMapping,
+    z.record(z.string(), z.lazy(() => Mapping)).describe(
+      "An object built field by field. Discrimination: an object whose only key is 'ref' (string value) is a ref, whose only key is 'const' is a constant, anything else is a nested object (describe never emits a nested object whose only key is 'ref' or 'const').",
+    ),
+  ])
+  .meta({ id: "Mapping" });
+
+export const ModelSchemas = z
+  .strictObject({
+    output: jsonSchema.describe("z.output view: validates step outputs, trigger results and the pool. Every object has additionalProperties: false."),
+    input: jsonSchema.optional().describe("z.input view (defaults make fields optional; `default` values are listed). Present only when it differs from `output`."),
+  })
+  .meta({ id: "ModelSchemas" });
+
+export const InputType = z
+  .union([
+    z.strictObject({ model: modelName, optional: z.boolean().describe("optional(Model): may be absent because its producer was skipped.") }),
+    z.strictObject({ schema: ModelSchemas.describe("A plain (unnamed) zod schema. Such inputs always have an explicit mapping.") }),
+  ])
+  .meta({ id: "InputType" });
+
+export const StepDescriptor = z
+  .strictObject({
+    name: stepName,
+    description: z.string().describe("What the step does, shown in the UI (may be empty)."),
+    kind: z.string().min(1).describe("'custom' = the handler is a handlers/*.ts file; any other kind is a step that carries its implementation (an SDK or package step). A label: the service accepts any kind."),
+    image: z.string().min(1).describe("Container image the step runs in."),
+    inputTypes: z.record(z.string(), InputType).describe("Declared input entries, keyed like input.json."),
+    input: z.record(z.string(), Mapping).describe("How the service assembles input.json: one mapping per input key (same keys as inputTypes)."),
+    output: modelName.nullable().describe("Output model, or null if the step produces no output."),
+    secrets: z.array(secretName).describe("Declared secrets (sorted). Mount exactly these, as env vars of the same name."),
+    handlerHash: hash.describe("Implementation identity: handler bundle (contract files excluded) + harness (bun + sdkHash); for a step that carries its implementation kind + config + harness + the hash of the code of its kind."),
+    timeoutSeconds: z.number().int().positive().optional(),
+    retries: z.number().int().nonnegative().optional(),
+    config: z
+      .record(z.string(), Json)
+      .optional()
+      .describe("The step's settings (display only; already covered by handlerHash). A config reference is recorded as {\"$config\": \"<entry>.<field>…\"}; the entry is in configEntries."),
+    configEntries: z
+      .array(configName)
+      .optional()
+      .describe("Config entries the step receives (sorted; omitted when none). The service delivers them in input.json under '$config'."),
+    clusterAccess: z
+      .literal(true)
+      .optional()
+      .describe("The step pod gets the instance's step ServiceAccount token (Kubernetes:StepServiceAccount), if the instance grants one. Omitted = no token."),
+  })
+  .meta({ id: "Step" });
+
+export type Stage =
+  | { steps: z.infer<typeof StepDescriptor>[] }
+  | { when: Record<string, (string | number | boolean)[]>; stages: Stage[] }
+  | { select: string; discriminator: string; cases: Record<string, Stage[]> };
+export const Stage: z.ZodType<Stage> = z
+  .union([
+    z.strictObject({ steps: z.array(StepDescriptor).min(1).describe("Steps run in parallel; the stage is a barrier.") }),
+    z.strictObject({
+      when: z.record(z.string(), z.array(z.union([z.string(), z.number(), z.boolean()])).min(1)).describe(
+        "Pipeline-input field → accepted values (all fields must match). Empty object = always.",
+      ),
+      stages: z.array(z.lazy(() => Stage)),
+    }),
+    z.strictObject({
+      select: z.string().min(1).describe("Config reference (`<entry>.<field>…`) to a discriminated union; the run's config snapshot picks the case."),
+      discriminator: z.string().min(1).describe("The union's literal field whose value names the case."),
+      cases: z
+        .record(z.string(), z.array(z.lazy(() => Stage)))
+        .describe("Discriminator value → stages. Exactly one case runs; a step name may repeat across cases, nowhere else."),
+    }),
+  ])
+  .meta({ id: "Stage" });
+
+export const Trigger = z
+  .discriminatedUnion("kind", [
+    z.strictObject({ kind: z.literal("push"), name: z.literal("push") }).describe("GitHub push. Event = the webhook payload."),
+    z
+      .strictObject({
+        kind: z.literal("poll"),
+        name: z.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/),
+        url: z.string(),
+        headers: z.record(z.string(), z.string()).describe("Values may contain '$SECRET:NAME' (NAME ∈ secrets)."),
+        secrets: z.array(secretName),
+        valuePath: z.string().describe("Dot path into the JSON response; a change triggers map-trigger with {\"value\": <string>}."),
+        intervalSeconds: z.number().int().positive(),
+      })
+      .describe("Background poller."),
+    z
+      .strictObject({
+        kind: z.literal("webhook"),
+        name: z.string().regex(/^[a-z0-9](?:[a-z0-9-]{0,61}[a-z0-9])?$/),
+        verify: z.discriminatedUnion("scheme", [
+          z.strictObject({
+            scheme: z.literal("hmac-sha256"),
+            secret: secretName,
+            header: z.string().min(1),
+            prefix: z.string().describe("Text before the hex digest in the header, e.g. 'sha256='."),
+          }),
+          z.strictObject({ scheme: z.literal("bearer"), secret: secretName }),
+        ]),
+      })
+      .describe("Inbound HTTP delivery to /api/hooks/<pipeline id>/<name>. Event = {headers, body}; a null mapping ignores it."),
+  ])
+  .meta({ id: "Trigger" });
+
+export const Manifest = z
+  .strictObject({
+    apiVersion: z.literal(API_VERSION),
+    name: z.string().min(1),
+    description: z.string().optional(),
+    input: modelName.describe("Pipeline input model."),
+    harness: z
+      .strictObject({
+        bun: z.string().describe("Bun runtime version compiled into the binary."),
+        sdk: z.string().describe("@olivervea/pipelines package version."),
+        sdkHash: hash.describe("Hash of the SDK runtime sources + zod version."),
+      })
+      .describe("Harness identity. Already folded into every handlerHash."),
+    models: z.record(modelName, ModelSchemas).describe("Every model referenced by the pipeline (input, step inputs/outputs)."),
+    secrets: z.array(z.strictObject({ name: secretName, description: z.string() })).describe("All declared secrets (steps + poll triggers), sorted by name."),
+    config: z
+      .array(
+        z.strictObject({
+          name: configName,
+          description: z.string(),
+          required: z.boolean().describe("False when the schema accepts a missing value (optional, or a default)."),
+          schema: jsonSchema.describe("z.input view: validates the config document's value for this entry (defaults listed)."),
+        }),
+      )
+      .optional()
+      .describe("Config entries used by steps, sorted by name (omitted when none). Fields of kind secretRef ({secret: NAME}) name a secret."),
+    triggers: z.array(Trigger),
+    stages: z.array(Stage),
+    failureHandlers: z.array(
+      z.strictObject({
+        step: StepDescriptor.describe("The handler step. Not part of any stage; its inputs are all FailureContext ({ref: 'failure'})."),
+        steps: z.array(stepName).nullable().describe("Steps whose failure triggers the handler (null = any step)."),
+      }),
+    ),
+  })
+  .meta({ id: "Manifest", title: "Olve.Pipelines v2 manifest" });
+
+export type ManifestT = z.infer<typeof Manifest>;
+export type StepDescriptorT = z.infer<typeof StepDescriptor>;
+export type TriggerT = z.infer<typeof Trigger>;
+export type ModelSchemasT = z.infer<typeof ModelSchemas>;
+
+/** The JSON Schema document written to manifest.schema.json. */
+export function manifestJsonSchema(): Record<string, unknown> {
+  const js = z.toJSONSchema(Manifest, { target: "draft-2020-12" }) as Record<string, unknown>;
+  return { ...js, $id: "https://olve.dev/schemas/pipelines/manifest-2.0.json" };
+}

package/src/describe/mapper-source.ts

@@ -0,0 +1,238 @@
+// Static analysis of mapper source (`fn.toString()`), an allowlist parser.
+//
+// Recording proxies cannot observe truthiness, `!`, `??`, `||`, `&&`, ternaries or `===` against a
+// value: they silently record a constant. So describe also checks the mapper's *source*: its body
+// must be an object literal whose values are member chains, literals, constant arrays or nested
+// object literals. Everything else is rejected with the offending construct named.
+//
+// Accepted shapes (after Bun's TypeScript transpilation):
+//   from => ({ a: from.input.sha, b: from["deploy-beta"].url, c: "lit", d: 1, e: { f: from.build } })
+//   (from) => { return { … }; }
+//   ({ input, "deploy-beta": beta }) => ({ sha: input.sha, url: beta.url })
+//   function (from) { return { … }; }
+// Free identifiers (`RELEASE`, `CONFIG.url`) are allowed: they are module constants, recorded as
+// `{const}` by the proxy. This requires the harness bundle not to be minified.
+import { MapperError } from "./record.ts";
+
+type Tok =
+  | { t: "ident"; v: string; pos: number }
+  | { t: "str"; v: string; pos: number }
+  | { t: "num"; v: string; pos: number }
+  | { t: "punc"; v: string; pos: number }
+  | { t: "op"; v: string; pos: number }
+  | { t: "eof"; v: ""; pos: number };
+
+const PUNCS = ["...", "=>", "?.", "(", ")", "{", "}", "[", "]", ",", ":", ".", ";"];
+const OPS = ["===", "!==", "**=", "??=", "&&=", "||=", "==", "!=", "<=", ">=", "&&", "||", "??", "++", "--", "**", "<<", ">>", "+=", "-=", "*=", "/=", "?", "!", "+", "-", "*", "/", "%", "<", ">", "=", "&", "|", "^", "~", "@", "#"];
+
+function describeOp(op: string): string {
+  if (op === "?") return "a ternary (`? :`)";
+  if (op === "??") return "nullish coalescing (`??`)";
+  if (op === "&&" || op === "||") return `a logical operator (\`${op}\`)`;
+  if (op === "!") return "negation (`!`)";
+  if (["===", "!==", "==", "!=", "<", ">", "<=", ">="].includes(op)) return `a comparison (\`${op}\`)`;
+  if (["+", "-", "*", "/", "%", "**"].includes(op)) return `arithmetic/concatenation (\`${op}\`)`;
+  if (op.endsWith("=") || op === "++" || op === "--") return `an assignment (\`${op}\`)`;
+  return `the operator \`${op}\``;
+}
+
+const KEYWORDS = new Set([
+  "typeof", "void", "delete", "new", "await", "yield", "this", "super", "class", "function", "async",
+  "if", "else", "for", "while", "do", "switch", "case", "try", "catch", "throw", "var", "let", "const",
+  "in", "instanceof", "import", "export", "return", "arguments", "eval",
+]);
+
+function tokenize(src: string): Tok[] {
+  const toks: Tok[] = [];
+  let i = 0;
+  while (i < src.length) {
+    const c = src[i]!;
+    if (/\s/.test(c)) { i++; continue; }
+    if (src.startsWith("//", i)) { const e = src.indexOf("\n", i); i = e < 0 ? src.length : e + 1; continue; }
+    if (src.startsWith("/*", i)) {
+      const e = src.indexOf("*/", i + 2);
+      if (e < 0) throw new MapperError("mapper source has an unterminated comment");
+      i = e + 2;
+      continue;
+    }
+    if (c === "`") throw new MapperError("mapper uses a template string");
+    if (c === '"' || c === "'") {
+      let j = i + 1;
+      let v = "";
+      for (;;) {
+        if (j >= src.length) throw new MapperError("mapper source has an unterminated string");
+        const d = src[j]!;
+        if (d === c) break;
+        if (d === "\\") { v += src.slice(j, j + 2); j += 2; continue; }
+        v += d;
+        j++;
+      }
+      toks.push({ t: "str", v, pos: i });
+      i = j + 1;
+      continue;
+    }
+    const num = /^(?:0[xXoObB][0-9a-fA-F_]+|(?:\d[\d_]*)?\.?\d[\d_]*(?:[eE][+-]?\d+)?)n?/.exec(src.slice(i));
+    if (num && /[\d.]/.test(c) && num[0] !== ".") {
+      toks.push({ t: "num", v: num[0], pos: i });
+      i += num[0].length;
+      continue;
+    }
+    const id = /^[\p{ID_Start}$_][\p{ID_Continue}$‌‍]*/u.exec(src.slice(i));
+    if (id) {
+      toks.push({ t: "ident", v: id[0], pos: i });
+      i += id[0].length;
+      continue;
+    }
+    const p = PUNCS.find((x) => src.startsWith(x, i));
+    if (p && !(p === "?." && /\d/.test(src[i + 2] ?? ""))) {
+      toks.push({ t: "punc", v: p, pos: i });
+      i += p.length;
+      continue;
+    }
+    const o = OPS.find((x) => src.startsWith(x, i));
+    if (o) {
+      toks.push({ t: "op", v: o, pos: i });
+      i += o.length;
+      continue;
+    }
+    throw new MapperError(`mapper source has an unexpected character '${c}'`);
+  }
+  toks.push({ t: "eof", v: "", pos: src.length });
+  return toks;
+}
+
+/** Throws MapperError unless `src` is an allowed mapper. */
+export function analyzeMapperSource(src: string): void {
+  const toks = tokenize(src);
+  let k = 0;
+  const peek = (o = 0) => toks[Math.min(k + o, toks.length - 1)]!;
+  const next = () => toks[k++]!;
+  const is = (t: Tok["t"], v?: string, o = 0) => peek(o).t === t && (v === undefined || peek(o).v === v);
+  const unexpected = (what = "here"): never => {
+    const tok = peek();
+    if (tok.t === "op") throw new MapperError(`mapper uses ${describeOp(tok.v)}; mappers may only contain property access and literals — move logic into the handler or a when block`);
+    if (tok.t === "punc" && tok.v === "?.") throw new MapperError("mapper uses optional chaining (`?.`); declare the input optional(...) and map the whole ref instead");
+    if (tok.t === "punc" && tok.v === "...") throw new MapperError("mapper uses spread (`...`); list the fields explicitly");
+    if (tok.t === "punc" && tok.v === "(") throw new MapperError("mapper calls a function or method; mappers may only contain property access and literals");
+    if (tok.t === "ident" && KEYWORDS.has(tok.v)) throw new MapperError(`mapper uses \`${tok.v}\`; mappers may only contain property access and literals`);
+    throw new MapperError(`mapper source is not an object literal of property accesses and literals (unexpected ${tok.t === "eof" ? "end" : `'${tok.v}'`} ${what})`);
+  };
+  const expect = (t: Tok["t"], v?: string) => (is(t, v) ? next() : unexpected(`(expected ${v ?? t})`));
+
+  const identifier = () => {
+    if (!is("ident") || KEYWORDS.has(peek().v)) unexpected("(expected an identifier)");
+    return next();
+  };
+
+  // ── parameters ──
+  const params = () => {
+    if (is("ident")) { identifier(); return; }
+    expect("punc", "(");
+    if (is("punc", ")")) { next(); return; }
+    if (is("punc", "{")) destructuring();
+    else identifier();
+    if (is("punc", ",")) next();
+    if (is("op", "=")) throw new MapperError("mapper parameter has a default value");
+    expect("punc", ")");
+  };
+  const destructuring = () => {
+    expect("punc", "{");
+    while (!is("punc", "}")) {
+      if (is("str")) { next(); expect("punc", ":"); identifier(); }
+      else {
+        identifier();
+        if (is("punc", ":")) { next(); identifier(); }
+      }
+      if (is("op", "=")) throw new MapperError("mapper parameter destructuring has a default value");
+      if (!is("punc", ",")) break;
+      next();
+    }
+    expect("punc", "}");
+  };
+
+  // ── values ──
+  const value = (): void => {
+    if (is("punc", "(")) { next(); value(); expect("punc", ")"); return; }
+    if (is("punc", "{")) return object();
+    if (is("punc", "[")) return array();
+    if (is("str") || is("num")) { next(); return; }
+    if (is("op", "-") && is("num", undefined, 1)) { next(); next(); return; }
+    if (is("ident", "true") || is("ident", "false") || is("ident", "null")) { next(); return; }
+    if (is("ident", "undefined")) throw new MapperError("mapper uses `undefined`; leave optional fields out instead");
+    chain();
+  };
+  const chain = () => {
+    identifier();
+    for (;;) {
+      if (is("punc", ".")) { next(); if (!is("ident")) unexpected("(expected a property name)"); next(); continue; }
+      if (is("punc", "[")) {
+        next();
+        if (!is("str") && !is("num")) throw new MapperError("mapper uses a computed property access; only literal keys (from[\"step-name\"]) are allowed");
+        next();
+        expect("punc", "]");
+        continue;
+      }
+      break;
+    }
+  };
+  const array = () => {
+    expect("punc", "[");
+    while (!is("punc", "]")) {
+      if (is("punc", ",")) unexpected("(array holes are not allowed)");
+      value();
+      if (!is("punc", ",")) break;
+      next();
+    }
+    expect("punc", "]");
+  };
+  const object = () => {
+    expect("punc", "{");
+    while (!is("punc", "}")) {
+      if (is("punc", "...")) unexpected();
+      if (is("punc", "[")) throw new MapperError("mapper uses a computed key; only literal keys are allowed");
+      if (is("ident") && (is("punc", ",", 1) || is("punc", "}", 1))) {
+        // shorthand `{ input }` — a destructured root or a module constant
+        identifier();
+      } else {
+        if (is("ident") || is("str") || is("num")) next();
+        else unexpected("(expected a property name)");
+        if (is("punc", "(")) throw new MapperError("mapper defines a method; mappers may only contain property access and literals");
+        expect("punc", ":");
+        value();
+      }
+      if (!is("punc", ",")) break;
+      next();
+    }
+    expect("punc", "}");
+  };
+  const returnBody = () => {
+    expect("punc", "{");
+    if (!is("ident", "return")) unexpected("(a block-bodied mapper must consist of a single `return { … }`)");
+    next();
+    object();
+    if (is("punc", ";")) next();
+    expect("punc", "}");
+  };
+
+  // ── function ──
+  if (is("ident", "async")) throw new MapperError("mapper must not be async");
+  if (is("ident", "function")) {
+    next();
+    if (is("op", "*")) throw new MapperError("mapper must not be a generator");
+    if (is("ident")) next();
+    params();
+    returnBody();
+  } else {
+    params();
+    expect("punc", "=>");
+    if (is("punc", "(")) {
+      next();
+      object();
+      expect("punc", ")");
+    } else if (is("punc", "{")) {
+      returnBody();
+    } else unexpected("(the mapper body must be an object literal: from => ({ … }))");
+  }
+  if (is("punc", ";")) next();
+  if (!is("eof")) unexpected("after the mapper body");
+}

package/src/describe/record.ts

@@ -0,0 +1,107 @@
+// Records a mapper as a tagged mapping by calling it with recording proxies.
+//
+// The proxy throws on coercion (template strings, `+`, String()), method calls, spreading,
+// `in`, assignment and JSON.stringify. It CANNOT see truthiness, `!`, `??`, `||`, ternaries or
+// `===` against a value — those are rejected by the static source analysis (mapper-source.ts),
+// and primarily by the `Ref<T>` types.
+import { REF_PATH } from "../core/brands.ts";
+
+export class MapperError extends Error {
+  override name = "MapperError";
+}
+
+/** Manifest mapping node: `{ref}` | `{const}` | a nested object of mappings. */
+export type Mapping = { ref: string } | { const: unknown } | { [key: string]: Mapping };
+
+function refProxy(path: string): unknown {
+  const fail = (what: string): never => {
+    throw new MapperError(
+      `mapper ${what} on reference '${path}'; mappers may only use property access and literals ` +
+        `(no template strings, arithmetic, method calls or logic) — move computation into the handler`,
+    );
+  };
+  const target = function () {}; // function target so calls hit the `apply` trap
+  return new Proxy(target, {
+    get(_t, prop) {
+      if (prop === REF_PATH) return path;
+      if (prop === "then") return undefined; // `await ref` must not recurse
+      if (prop === Symbol.toPrimitive || prop === "toString" || prop === "valueOf")
+        return fail("coerces a value (template string / concatenation / arithmetic / comparison)");
+      if (prop === "toJSON") return fail("serializes a reference (JSON.stringify)");
+      if (typeof prop === "symbol") return fail(`uses ${String(prop)} (iteration/spread/inspection)`);
+      if (prop.includes(".")) return fail(`accesses field '${prop}' (field names containing '.' cannot be mapped)`);
+      return refProxy(`${path}.${prop}`);
+    },
+    apply: () => fail("calls a function/method"),
+    construct: () => fail("constructs"),
+    set: () => fail("assigns"),
+    deleteProperty: () => fail("deletes"),
+    has: () => fail("uses the `in` operator"),
+    ownKeys: () => fail("enumerates/spreads"),
+    defineProperty: () => fail("defines a property"),
+    getPrototypeOf: () => fail("inspects the prototype (instanceof)"),
+  });
+}
+
+/** The `from` argument: `from.input`, `from.<step-name>`. */
+export function rootProxy(available: ReadonlySet<string>): unknown {
+  return new Proxy(
+    {},
+    {
+      get(_t, prop) {
+        if (typeof prop === "symbol" || prop === "then") return undefined;
+        if (!available.has(prop))
+          throw new MapperError(`mapper references '${prop}', which is not available at this stage (available: ${[...available].sort().join(", ") || "none"})`);
+        return refProxy(prop);
+      },
+      has: () => {
+        throw new MapperError("mapper uses the `in` operator on its argument");
+      },
+      ownKeys: () => {
+        throw new MapperError("mapper enumerates/spreads its argument");
+      },
+    },
+  );
+}
+
+export const refPathOf = (v: unknown): string | undefined =>
+  typeof v === "function" ? ((v as unknown as Record<symbol, unknown>)[REF_PATH] as string | undefined) : undefined;
+
+function toMapping(v: unknown, at: string): Mapping {
+  const path = refPathOf(v);
+  if (path !== undefined) return { ref: path };
+  if (typeof v === "function") throw new MapperError(`mapper returns a function at '${at}'`);
+  if (v === undefined) throw new MapperError(`mapper returns undefined at '${at}'`);
+  if (v === null || typeof v === "string" || typeof v === "boolean") return { const: v };
+  if (typeof v === "number") {
+    if (!Number.isFinite(v)) throw new MapperError(`mapper returns a non-finite number at '${at}'`);
+    return { const: v };
+  }
+  if (Array.isArray(v)) {
+    const items = v.map((x, i) => toMapping(x, `${at}[${i}]`));
+    if (items.every((e) => "const" in e && Object.keys(e).length === 1)) return { const: items.map((e) => (e as { const: unknown }).const) };
+    throw new MapperError(`mapper puts references inside an array at '${at}' (only constant arrays are supported)`);
+  }
+  if (typeof v === "object") {
+    if (Object.getPrototypeOf(v) !== Object.prototype && Object.getPrototypeOf(v) !== null)
+      throw new MapperError(`mapper returns a non-plain object at '${at}'`);
+    const keys = Object.keys(v);
+    if (keys.length === 1 && (keys[0] === "ref" || keys[0] === "const"))
+      throw new MapperError(`mapper builds an object whose only field is '${keys[0]}' at '${at}'; that is reserved by the manifest's mapping encoding — map the whole object with a ref instead`);
+    const out: Record<string, Mapping> = {};
+    for (const k of keys) out[k] = toMapping((v as Record<string, unknown>)[k], at ? `${at}.${k}` : k);
+    return out;
+  }
+  throw new MapperError(`mapper returns an unsupported value (${typeof v}) at '${at}'`);
+}
+
+/** Calls `fn` with recording proxies and returns `{ inputKey: Mapping }`. */
+export function recordMapper(fn: (from: unknown) => unknown, available: ReadonlySet<string>): Record<string, Mapping> {
+  const result = fn(rootProxy(available));
+  if (refPathOf(result) !== undefined || typeof result !== "object" || result === null || Array.isArray(result))
+    throw new MapperError("mapper must return an object literal");
+  if (result instanceof Promise) throw new MapperError("mapper must be synchronous");
+  const out: Record<string, Mapping> = {};
+  for (const k of Object.keys(result)) out[k] = toMapping((result as Record<string, unknown>)[k], k);
+  return out;
+}

package/src/dev/cli.ts

@@ -0,0 +1,87 @@
+#!/usr/bin/env bun
+// olve-dev — run a pipeline from source through the same harness path as the compiled binary.
+//   olve-dev describe <dir> [--sentinels]
+//   olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
+//   olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]
+// $OLVE_DIR defaults to <dir>/.olve; outputs land in <dir>/.olve/work/.
+import { copyFileSync, existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { join, resolve } from "node:path";
+import { parseArgs } from "node:util";
+import { runHarness, type HarnessConfig } from "../harness/main.ts";
+import { EXIT } from "../harness/exit.ts";
+import { handlerHashes, kindHashes } from "../build/hashes.ts";
+import { harnessInfo, loadPipeline, loadProject, ProjectError } from "../build/project.ts";
+
+const USAGE = `usage: olve-dev describe <dir> [--sentinels]
+       olve-dev run <dir> <step> [--input-file f] [--config-file f] [--olve-dir d] [--secret NAME=value]...
+       olve-dev map-trigger <dir> <trigger> --event-file f [--olve-dir d]`;
+
+export async function devConfig(dir: string, withHashes: boolean): Promise<HarnessConfig> {
+  const project = await loadProject(dir);
+  const pipeline = await loadPipeline(project);
+  const harness = harnessInfo();
+  const hashes = withHashes ? await handlerHashes(project, harness) : {};
+  return {
+    pipeline,
+    handlers: Object.fromEntries(project.handlers.map(([name, file]) => [name, () => import(file) as Promise<{ default: unknown }>])),
+    handlerHashes: Object.fromEntries(Object.entries(hashes).map(([k, v]) => [k, v.handlerHash])),
+    ...(withHashes ? { kindHashes: await kindHashes(project, pipeline) } : {}),
+    harness,
+  };
+}
+
+export async function devMain(argv: string[]): Promise<number> {
+  let parsed;
+  try {
+    parsed = parseArgs({
+      args: argv,
+      allowPositionals: true,
+      options: {
+        "input-file": { type: "string" },
+        "config-file": { type: "string" },
+        "event-file": { type: "string" },
+        "olve-dir": { type: "string" },
+        secret: { type: "string", multiple: true },
+        sentinels: { type: "boolean", default: false },
+        help: { type: "boolean", short: "h", default: false },
+      },
+    });
+  } catch (e) {
+    console.error(`${(e as Error).message}\n${USAGE}`);
+    return EXIT.usage;
+  }
+  const { values, positionals } = parsed;
+  if (values.help) return console.log(USAGE), 0;
+  const [mode, dir, name] = positionals;
+  if (!mode || !dir) return console.error(USAGE), EXIT.usage;
+  try {
+    if (mode === "describe") return await runHarness(await devConfig(dir, true), ["describe", ...(values.sentinels ? ["--sentinels"] : [])]);
+    if (mode !== "run" && mode !== "map-trigger") return console.error(USAGE), EXIT.usage;
+    if (!name) return console.error(USAGE), EXIT.usage;
+    const olveDir = resolve(values["olve-dir"] ?? join(dir, ".olve"));
+    mkdirSync(olveDir, { recursive: true });
+    process.env.OLVE_DIR = olveDir;
+    process.env.TMPDIR ??= join(olveDir, "tmp");
+    for (const s of values.secret ?? []) {
+      const i = s.indexOf("=");
+      if (i <= 0) return console.error(`--secret expects NAME=value, got '${s}'`), EXIT.usage;
+      process.env[s.slice(0, i)] = s.slice(i + 1);
+    }
+    const file = mode === "run" ? values["input-file"] : values["event-file"];
+    if (file) copyFileSync(resolve(file), join(olveDir, "input.json"));
+    if (mode === "run" && values["config-file"]) {
+      const inputFile = join(olveDir, "input.json");
+      const input = (existsSync(inputFile) ? JSON.parse(readFileSync(inputFile, "utf8")) : {}) as Record<string, unknown>;
+      input.$config = JSON.parse(readFileSync(resolve(values["config-file"]), "utf8"));
+      writeFileSync(inputFile, JSON.stringify(input));
+    }
+    else if (mode === "map-trigger") return console.error("--event-file is required"), EXIT.usage;
+    return await runHarness(await devConfig(dir, false), [mode, name]);
+  } catch (e) {
+    if (e instanceof ProjectError) return console.error(e.message), EXIT.configInvalid;
+    console.error((e as Error)?.stack ?? String(e));
+    return EXIT.configInvalid;
+  }
+}
+
+if (import.meta.main) process.exit(await devMain(process.argv.slice(2)));