@toist/spec 0.2.0

package/CHANGELOG.md

@@ -0,0 +1,24 @@
+# Changelog
+
+All notable changes to `@toist/spec` are recorded here.
+
+## 0.2.0 — 2026-05-05
+
+Rebrand: `@2121/platform-spec` → `@toist/spec`. Republished to **npmjs.com**
+(public scope) — the abandoned `@2121/*` v0.1.0 publishes lived on a private
+Gitea registry and required per-consumer auth tokens. See
+`session_summary_2026_05_05_phase_f_w3_publish_and_federated_design` in nalich
+for the rationale.
+
+No API or behaviour changes from 0.1.0; the rename is the only breaking change.
+
+## 0.1.0 — 2026-05-05 — abandoned (@2121/platform-spec on Gitea)
+
+Initial release. Extracted from the platform monorepo per Phase F W2.
+
+- Type definitions for kinds, pipelines, resources, run records, and
+  HITL specs — see kind-spec, pipeline-spec, resource-spec at
+  https://toist.in.
+- AJV-based validators for pipeline YAML and resource definitions.
+- JSON-schema generation utilities for editor tooling.
+- Babel-parser-based discriminator extraction for kind-id resolution.

package/package.json

@@ -0,0 +1,16 @@
+{
+  "name": "@toist/spec",
+  "version": "0.2.0",
+  "type": "module",
+  "main": "./src/index.ts",
+  "types": "./src/index.ts",
+  "exports": {
+    ".": "./src/index.ts"
+  },
+  "files": ["src/", "CHANGELOG.md"],
+  "dependencies": {
+    "@babel/parser": "^7.25.0",
+    "ajv": "^8.17.1",
+    "yaml": "^2.8.3"
+  }
+}

package/src/discriminator.ts

@@ -0,0 +1,148 @@
+// 2121
+// Discriminator parsing for pipeline-spec v1 §5.
+//
+// Every leaf inside a node's `params` and `input` is one of three forms:
+//
+//   1. Bare literal         — auto-static shorthand (any non-discriminator value)
+//   2. Explicit static      — { value: <literal> }
+//   3. TypeScript expression — { expr: "<ts-expression>" }
+//
+// Discriminator detection: an object with **exactly one key** equal to
+// `value` or `expr` is the discriminator form. Anything else is a literal.
+// To force a literal that is itself discriminator-shaped, wrap explicitly:
+// `{ value: { expr: "x" } }`.
+
+import { parseExpr, evalExpr, type ParsedExpr } from "./expr.ts"
+
+export type DiscNode =
+  | { kind: "literal"; value: unknown }
+  | { kind: "expr"; expr: ParsedExpr }
+  | { kind: "object"; entries: Record<string, DiscNode> }
+  | { kind: "array"; items: DiscNode[] }
+
+export interface ParseDiscResult {
+  tree: DiscNode
+  errors: string[]
+  /** Union of all `ctx.results.<id>` ids referenced anywhere in this subtree. */
+  refs: Set<string>
+}
+
+/**
+ * Walk a raw value and produce a parsed discriminator tree. Surfaces parse
+ * errors per leaf (caller decides whether to short-circuit). Validates §13
+ * item 9 (discriminator shape) and item 10 (expression syntactic
+ * well-formedness).
+ */
+export function parseDisc(value: unknown, path = ""): ParseDiscResult {
+  const errors: string[] = []
+  const refs = new Set<string>()
+  const tree = walk(value, path, errors, refs)
+  return { tree, errors, refs }
+}
+
+/**
+ * Parse a `params` or `input` container per pipeline-spec §1 (three layers
+ * of vocabulary): keys are kind-defined, values follow the discriminator.
+ * The container itself is **not** discriminator-detectable — a kind whose
+ * input has a single port named `value` would otherwise be misinterpreted
+ * as `{ value: <literal> }` explicit-static.
+ */
+export function parseDiscContainer(
+  obj: Record<string, unknown>,
+  path = "",
+): ParseDiscResult {
+  const errors: string[] = []
+  const refs = new Set<string>()
+  const entries: Record<string, DiscNode> = {}
+  for (const [k, v] of Object.entries(obj)) {
+    entries[k] = walk(v, path ? `${path}.${k}` : k, errors, refs)
+  }
+  return { tree: { kind: "object", entries }, errors, refs }
+}
+
+function walk(value: unknown, path: string, errors: string[], refs: Set<string>): DiscNode {
+  // Primitives — bare literal.
+  if (value === null || typeof value !== "object") {
+    return { kind: "literal", value }
+  }
+
+  // Arrays — recurse into elements.
+  if (Array.isArray(value)) {
+    return {
+      kind: "array",
+      items: value.map((v, i) => walk(v, `${path}[${i}]`, errors, refs)),
+    }
+  }
+
+  // Objects — discriminator detection.
+  const obj = value as Record<string, unknown>
+  const keys = Object.keys(obj)
+
+  if (keys.length === 1) {
+    if (keys[0] === "value") {
+      // Explicit static. The wrapped value is a literal — do NOT recurse
+      // into it for further discriminator parsing (per §5: { value } extracts
+      // the contained literal as-is, even if it is itself discriminator-shaped).
+      return { kind: "literal", value: obj.value }
+    }
+    if (keys[0] === "expr") {
+      const src = obj.expr
+      if (typeof src !== "string") {
+        errors.push(`${pathLabel(path)}: { expr: ... } must contain a string, got ${describeType(src)}`)
+        return { kind: "literal", value: null }
+      }
+      try {
+        const parsed = parseExpr(src)
+        for (const r of parsed.refs) refs.add(r)
+        return { kind: "expr", expr: parsed }
+      } catch (err) {
+        errors.push(`${pathLabel(path)}: ${(err as Error).message}`)
+        return { kind: "literal", value: null }
+      }
+    }
+  }
+
+  // §13 item 9: reject mixed discriminators like { value, expr }.
+  if (keys.length === 2 && keys.includes("value") && keys.includes("expr")) {
+    errors.push(`${pathLabel(path)}: object has both 'value' and 'expr' — discriminator must be exactly one of them`)
+    return { kind: "literal", value: null }
+  }
+
+  // Generic object — recurse into values.
+  const entries: Record<string, DiscNode> = {}
+  for (const [k, v] of Object.entries(obj)) {
+    entries[k] = walk(v, path ? `${path}.${k}` : k, errors, refs)
+  }
+  return { kind: "object", entries }
+}
+
+function pathLabel(path: string): string {
+  return path === "" ? "<root>" : path
+}
+
+function describeType(v: unknown): string {
+  if (v === null) return "null"
+  if (Array.isArray(v)) return "array"
+  return typeof v
+}
+
+/**
+ * Resolve a parsed discriminator tree against a runtime ctx. Bare literals
+ * pass through; `{ value }` already extracted; `{ expr }` evaluates lazily
+ * with `ctx` in scope.
+ */
+export function resolveDisc(tree: DiscNode, ctx: unknown): unknown {
+  switch (tree.kind) {
+    case "literal":
+      return tree.value
+    case "expr":
+      return evalExpr(tree.expr.source, ctx)
+    case "array":
+      return tree.items.map((n) => resolveDisc(n, ctx))
+    case "object": {
+      const out: Record<string, unknown> = {}
+      for (const [k, v] of Object.entries(tree.entries)) out[k] = resolveDisc(v, ctx)
+      return out
+    }
+  }
+}

package/src/expr.ts

@@ -0,0 +1,133 @@
+// 2121
+// TypeScript expression parsing and evaluation for pipeline-spec v1 §5.
+//
+// `{ expr: "<ts-expression>" }` discriminator values are parsed once at
+// spec-load (validation + ref extraction) and evaluated lazily per-node
+// at run time. The single bound identifier is `ctx`; see pipeline-spec.md
+// §5 for the contract.
+//
+// Static analysis extracts `ctx.results.<id>` references for DAG derivation.
+// Computed access (`ctx.results[someVar]`) is rejected — node references
+// must be statically determinable per §13 item 11.
+
+import { parse as babelParse } from "@babel/parser"
+import type { Node, MemberExpression } from "@babel/types"
+
+export interface ParsedExpr {
+  /** Original source string, kept for evaluation and diagnostics. */
+  source: string
+  /** Set of node ids referenced via ctx.results.<id>. */
+  refs: Set<string>
+}
+
+/**
+ * Parse a TypeScript expression string. Validates syntactic well-formedness
+ * and extracts the set of `ctx.results.<id>` references for DAG derivation.
+ * Throws on parse error or computed `ctx.results[...]` access.
+ */
+export function parseExpr(source: string): ParsedExpr {
+  let file
+  try {
+    // Wrap in parens to force expression-position parsing — without this,
+    // a leading `{` would be parsed as a block statement, and `function () {}`
+    // would be a function declaration rather than an expression.
+    file = babelParse(`(${source})`, {
+      sourceType: "script",
+      plugins: ["typescript"],
+      errorRecovery: false,
+    })
+  } catch (err) {
+    throw new Error(`expression parse error: ${(err as Error).message}`)
+  }
+
+  const stmt = file.program.body[0]
+  if (!stmt || stmt.type !== "ExpressionStatement") {
+    throw new Error("not a TypeScript expression")
+  }
+
+  const refs = new Set<string>()
+  collectCtxRefs(stmt.expression as Node, refs)
+  return { source, refs }
+}
+
+/**
+ * Recursively walk an AST collecting `ctx.results.<id>` member-access roots.
+ * Throws on computed access at the `ctx.results[...]` level.
+ */
+function collectCtxRefs(node: Node | null | undefined, refs: Set<string>): void {
+  if (!node || typeof node !== "object" || typeof (node as Node).type !== "string") return
+
+  if (node.type === "MemberExpression") {
+    const ref = matchCtxResultsRef(node)
+    if (ref) refs.add(ref)
+    // Fall through: still walk children to catch nested ctx.results.X inside
+    // member expressions (e.g. ctx.results.a[ctx.results.b ? 0 : 1] would be
+    // rejected at the inner level, but we still want to surface ctx.results.a).
+  }
+
+  for (const key of Object.keys(node)) {
+    if (key === "loc" || key === "range" || key === "leadingComments" || key === "trailingComments") continue
+    const value = (node as unknown as Record<string, unknown>)[key]
+    if (Array.isArray(value)) {
+      for (const item of value) collectCtxRefs(item as Node, refs)
+    } else if (value && typeof value === "object") {
+      collectCtxRefs(value as Node, refs)
+    }
+  }
+}
+
+/**
+ * If `node` is `ctx.results.<id>` (non-computed identifier access), return the
+ * id. If it is `ctx.results[<expr>]` (computed access), throw — the spec
+ * requires statically determinable references.
+ */
+function matchCtxResultsRef(node: MemberExpression): string | null {
+  if (!isCtxResults(node.object)) return null
+
+  if (node.computed) {
+    // Allow numeric/string-literal computed access (e.g. ctx.results["foo"])
+    // since those are statically determinable. Reject everything else.
+    if (node.property.type === "StringLiteral") return node.property.value
+    if (node.property.type === "NumericLiteral") return String(node.property.value)
+    throw new Error(
+      "computed access on ctx.results (e.g. ctx.results[someVar]) is not allowed; " +
+      "node references must be statically determinable",
+    )
+  }
+
+  if (node.property.type !== "Identifier") return null
+  return node.property.name
+}
+
+/** Returns true iff `node` is the member access `ctx.results`. */
+function isCtxResults(node: Node): boolean {
+  if (node.type !== "MemberExpression") return false
+  if (node.computed) return false
+  if (node.property.type !== "Identifier" || node.property.name !== "results") return false
+  if (node.object.type !== "Identifier" || node.object.name !== "ctx") return false
+  return true
+}
+
+// ─── Evaluation ──────────────────────────────────────────────────────────────
+
+const compileCache = new Map<string, (ctx: unknown) => unknown>()
+
+/**
+ * Evaluate a TS expression against `ctx`. Compiled functions are cached by
+ * source string so repeated runs of the same pipeline reuse the same closure.
+ *
+ * v1 evaluates with full Bun JS privileges (no sandbox); the trust boundary
+ * is pipeline write authority. See pipeline-spec.md §5 and §16.2.
+ */
+export function evalExpr(source: string, ctx: unknown): unknown {
+  let fn = compileCache.get(source)
+  if (!fn) {
+    try {
+      fn = new Function("ctx", `return (${source})`) as (ctx: unknown) => unknown
+    } catch (err) {
+      throw new Error(`expression compile error: ${(err as Error).message}`)
+    }
+    compileCache.set(source, fn)
+  }
+  return fn(ctx)
+}

package/src/index.ts

@@ -0,0 +1,54 @@
+// 2121
+// Platform-spec — the contract shared between the runner, the CLI, and any
+// future agents that need to reason about pipelines and kinds.
+//
+// Two concerns live together because they evolve together:
+//
+//   - **Pipeline format** (`pipeline-spec.md`) — yaml strict loader,
+//     `{ value | expr }` discriminator, TS expression parser/evaluator,
+//     and the v1 validator with closed-set + payloadSchema enforcement.
+//
+//   - **Kind contract** (`kind-spec.md`, forthcoming) — the runtime
+//     interface every NodeKind sees: ParamDef/PortDef shapes, the
+//     ExecContext exposed to `run`, and Cache/HitlSpec collateral types.
+//
+// Validation is offline-friendly: kind existence is pluggable via
+// `ValidateOptions.hasKind`, so the CLI can validate a pipeline without
+// booting a runner. Keep this package free of HTTP, DB, and registry
+// implementation — types and pure functions only.
+
+export { parse as parseYaml, YamlError } from "./yaml.ts"
+export { parseExpr, evalExpr, type ParsedExpr } from "./expr.ts"
+export { parseDisc, parseDiscContainer, resolveDisc, type DiscNode, type ParseDiscResult } from "./discriminator.ts"
+export {
+  validateSpec,
+  type ValidateOptions,
+  type ValidateResult,
+  type PipelineSpec,
+  type PipelineNode,
+  type ParsedNode,
+} from "./validate.ts"
+export {
+  type ResourceTypeDef,
+  type RunStore,
+  type SubRun,
+  type SubRunOutcome,
+  type OnErrorPolicy,
+  type ErrorReviewSpec,
+  type ParamDef,
+  type PortDef,
+  type Cache,
+  type HitlSpec,
+  type PlatformCtx,
+  type ExecContext,
+  type NodeKind,
+  type NodeKindManifest,
+} from "./kinds.ts"
+export {
+  paramDefToSchema,
+  portDefToSchema,
+  kindToNodeSchema,
+  pipelineSchema,
+  ctxDts,
+  type JsonSchema,
+} from "./jsonschema.ts"

package/src/jsonschema.ts

@@ -0,0 +1,296 @@
+// 2121
+// JSON Schema generation for the v1 pipeline format. Per pipeline-spec.md §15,
+// the generated schema covers §3 (pipeline-level) + §4 (node-level) with
+// per-kind params/input shapes inlined from the kind manifest.
+//
+// Pure spec logic — no fs, no fetch. The CLI's gen-pipeline-schema.ts script
+// fetches the live manifest and resource types, then calls these helpers to
+// produce the actual artifacts.
+
+import type { ParamDef, PortDef, NodeKindManifest, ResourceTypeDef } from "./kinds.ts"
+
+const API_VERSION = "2121.fi/v1"
+const SLUG_PATTERN = "^[A-Za-z][\\w-]*$"
+
+export type JsonSchema = Record<string, unknown>
+
+// ─── Discriminator wrapping ───────────────────────────────────────────────────
+// Per pipeline-spec.md §5: any value can be authored as a bare literal,
+// `{ value: <literal> }`, or `{ expr: "..." }`. The discriminator union below
+// is reused for every param and port leaf.
+
+function discriminatorUnion(literal: JsonSchema): JsonSchema {
+  // anyOf, not oneOf — for permissive types like `any`/`object`/`json` the
+  // literal branch overlaps with `{ value: ... }` and `{ expr: ... }` (an
+  // object literal IS an object). Authors don't care which branch matches;
+  // the runtime discriminator parser disambiguates exact shapes regardless.
+  return {
+    anyOf: [
+      literal,
+      {
+        type: "object",
+        required: ["value"],
+        properties: { value: literal },
+        additionalProperties: false,
+      },
+      {
+        type: "object",
+        required: ["expr"],
+        properties: { expr: { type: "string" } },
+        additionalProperties: false,
+      },
+    ],
+  }
+}
+
+// ─── ParamDef / PortDef → JSON Schema ────────────────────────────────────────
+
+/** Translate a ParamDef to its JSON Schema fragment, wrapped in the
+ *  discriminator union (bare | { value } | { expr }) per §5. */
+export function paramDefToSchema(def: ParamDef): JsonSchema {
+  let literal: JsonSchema
+  switch (def.type) {
+    case "string":
+      literal = { type: "string" }
+      break
+    case "number":
+      literal = { type: "number" }
+      break
+    case "boolean":
+      literal = { type: "boolean" }
+      break
+    case "select":
+      literal = { type: "string", enum: (def.options ?? []).map((o) => o.value) }
+      break
+    case "expression":
+      // An expression param expects a function value at runtime. The author
+      // writes { expr: "(item) => ..." } in YAML — bare-literal and { value }
+      // forms don't make sense here. Restrict to the expr branch.
+      return {
+        type: "object",
+        required: ["expr"],
+        properties: { expr: { type: "string" } },
+        additionalProperties: false,
+      }
+    case "json":
+    default:
+      literal = {}  // any JSON value
+      break
+  }
+  if (def.description) literal.description = def.description
+  return discriminatorUnion(literal)
+}
+
+/** Translate a PortDef to its JSON Schema fragment, wrapped in the
+ *  discriminator union. Unlike params, ports never carry a hardcoded
+ *  expression-only restriction — any port can be authored as a literal,
+ *  { value: ... }, or { expr: ... }. */
+export function portDefToSchema(def: PortDef): JsonSchema {
+  let literal: JsonSchema
+  switch (def.type) {
+    case "string":  literal = { type: "string" };  break
+    case "number":  literal = { type: "number" };  break
+    case "boolean": literal = { type: "boolean" }; break
+    case "object":  literal = { type: "object" };  break
+    case "array":   literal = { type: "array" };   break
+    case "any":
+    default:
+      literal = {}
+      break
+  }
+  if (def.description) literal.description = def.description
+  return discriminatorUnion(literal)
+}
+
+// ─── Per-kind node schema ────────────────────────────────────────────────────
+
+function paramsObjectSchema(decl: Record<string, ParamDef>): JsonSchema {
+  const props: Record<string, JsonSchema> = {}
+  const required: string[] = []
+  for (const [key, def] of Object.entries(decl)) {
+    props[key] = paramDefToSchema(def)
+    if (def.required) required.push(key)
+  }
+  const schema: JsonSchema = {
+    type: "object",
+    properties: props,
+    additionalProperties: false,
+  }
+  if (required.length > 0) schema.required = required
+  return schema
+}
+
+function inputsObjectSchema(decl: Record<string, PortDef>): JsonSchema {
+  const props: Record<string, JsonSchema> = {}
+  const required: string[] = []
+  for (const [key, def] of Object.entries(decl)) {
+    props[key] = portDefToSchema(def)
+    if (def.required) required.push(key)
+  }
+  const schema: JsonSchema = {
+    type: "object",
+    properties: props,
+    additionalProperties: false,
+  }
+  if (required.length > 0) schema.required = required
+  return schema
+}
+
+/** A discriminator branch — the schema for a node when `kind` matches a
+ *  specific id. The base node fields (id/label/dependsOn) are added by the
+ *  caller via `allOf` composition. params and input are themselves marked
+ *  required when the kind declares any required fields inside them, so
+ *  e.g. transform.sort (which requires params.by) rejects a node that
+ *  omits `params:` entirely. */
+export function kindToNodeSchema(kind: NodeKindManifest): JsonSchema {
+  const required: string[] = ["kind"]
+  if (Object.values(kind.params).some((d) => d.required)) required.push("params")
+  if (Object.values(kind.inputs).some((d) => d.required)) required.push("input")
+  return {
+    type: "object",
+    properties: {
+      kind:   { const: kind.id },
+      params: paramsObjectSchema(kind.params),
+      input:  inputsObjectSchema(kind.inputs),
+    },
+    required,
+  }
+}
+
+// ─── Top-level pipeline schema ───────────────────────────────────────────────
+
+const NODE_BASE: JsonSchema = {
+  type: "object",
+  properties: {
+    id:        { type: "string", pattern: SLUG_PATTERN },
+    kind:      { type: "string" },
+    label:     { type: "string" },
+    params:    { type: "object" },
+    input:     { type: "object" },
+    dependsOn: { type: "array", items: { type: "string" } },
+  },
+  required: ["id", "kind"],
+  additionalProperties: false,
+}
+
+/** Build the v1 pipeline JSON Schema from a snapshot of the kind manifest.
+ *  Editors (Monaco, VS Code, JetBrains) consume this for auto-complete
+ *  and per-kind shape validation on YAML files. */
+export function pipelineSchema(kinds: NodeKindManifest[]): JsonSchema {
+  const kindUnion: JsonSchema[] = kinds.map(kindToNodeSchema)
+
+  const nodeSchema: JsonSchema = kindUnion.length > 0
+    ? { allOf: [NODE_BASE, { oneOf: kindUnion }] }
+    : NODE_BASE
+
+  return {
+    $schema:     "https://json-schema.org/draft/2020-12/schema",
+    $id:         `https://2121.fi/pipeline-spec/v1/pipeline.schema.json`,
+    title:       "Pipeline (2121.fi/v1)",
+    description: "Generated from the live kind manifest. Regenerate when kinds are added or changed.",
+    type:        "object",
+    properties: {
+      apiVersion:    { const: API_VERSION },
+      id:            { type: "string", pattern: SLUG_PATTERN },
+      label:         { type: "string" },
+      description:   { type: "string" },
+      schedule:      { type: "string", description: "5-field cron expression (planned for §16.1; parsed but not active in v1)" },
+      payloadSchema: { type: "object", description: "JSON Schema 2020-12 for the pipeline's run payload" },
+      nodes:         { type: "array", minItems: 1, items: nodeSchema },
+    },
+    required: ["nodes"],
+    additionalProperties: false,
+  }
+}
+
+// ─── ctx.d.ts (TypeScript declarations) ───────────────────────────────────────
+// Per pipeline-spec.md §15, ctx.d.ts is generated from payloadSchema, the
+// kind manifest's output ports, and the resource registry. v1 ships a coarse
+// but correct version: per-Resource-Type interfaces, untyped ctx.results /
+// ctx.params (those depend on the specific pipeline being authored).
+
+/** Sanitize a Resource Type name into a valid TypeScript identifier suffix. */
+function tsIdent(name: string): string {
+  return name.replace(/[^A-Za-z0-9_]/g, "")
+}
+
+/** JSON Schema → TypeScript type expression. Coarse but correct for the
+ *  shapes Resource Type schemas use (object with primitive/optional fields).
+ *  Falls back to `unknown` for anything beyond that. */
+function jsonSchemaToTs(schema: unknown, indent = 0): string {
+  if (!schema || typeof schema !== "object") return "unknown"
+  const s = schema as Record<string, unknown>
+
+  if (s.enum && Array.isArray(s.enum)) {
+    return s.enum.map((v) => JSON.stringify(v)).join(" | ")
+  }
+
+  switch (s.type) {
+    case "string":  return "string"
+    case "number":  return "number"
+    case "integer": return "number"
+    case "boolean": return "boolean"
+    case "null":    return "null"
+    case "array": {
+      const items = jsonSchemaToTs(s.items, indent)
+      return `${items}[]`
+    }
+    case "object": {
+      const props = (s.properties as Record<string, unknown>) ?? {}
+      const required = new Set((s.required as string[]) ?? [])
+      const keys = Object.keys(props)
+      if (keys.length === 0) return "Record<string, unknown>"
+      const pad = "  ".repeat(indent + 1)
+      const closePad = "  ".repeat(indent)
+      const lines = keys.map((k) => {
+        const optional = required.has(k) ? "" : "?"
+        const valTs = jsonSchemaToTs(props[k], indent + 1)
+        return `${pad}${k}${optional}: ${valTs};`
+      })
+      return `{\n${lines.join("\n")}\n${closePad}}`
+    }
+  }
+  return "unknown"
+}
+
+/** Generate `ctx.d.ts` source from the resource type registry. The output is
+ *  a self-contained module that authors can reference for autocomplete on
+ *  `ctx.resource.<name>.<field>` once they have a concrete Resource Type. */
+export function ctxDts(resourceTypes: ResourceTypeDef[]): string {
+  const interfaces = resourceTypes.map((t) => {
+    const tsType = jsonSchemaToTs(t.schema)
+    const desc = t.description ? `/** ${t.description} */\n` : ""
+    return `${desc}export interface ${tsIdent(t.name)} ${tsType}`
+  }).join("\n\n")
+
+  const typeUnion = resourceTypes.length > 0
+    ? resourceTypes.map((t) => tsIdent(t.name)).join(" | ")
+    : "Record<string, unknown>"
+
+  return `// AUTO-GENERATED by packages/cli/scripts/gen-pipeline-schema.ts
+// Source: kind manifest + resource type registry. Regenerate after Resource
+// Type registration changes. Do not edit by hand.
+//
+// Resource Type interfaces give pipeline authors per-field type-checking on
+// \`ctx.resource.<name>\` once they assert which Type they're addressing:
+//   const api = ctx.resource.anthropic as AnthropicApi
+//   api.apiKey   // typed string
+//
+// v1 leaves \`ctx.params\` and \`ctx.results\` untyped because both depend on
+// the specific pipeline being authored. Per-pipeline narrowing is §16.2.
+
+${interfaces}
+
+export type AnyResource = ${typeUnion}
+
+export interface Ctx {
+  /** Run payload (validated against pipeline.payloadSchema if declared). */
+  params: Record<string, unknown>
+  /** Outputs of completed upstream nodes, keyed by node id. */
+  results: Record<string, unknown>
+  /** Configured resources (\`ctx.resource.<name>.<field>\`). Cast to a
+   *  specific Resource Type for field-level type-checking. */
+  resource: Record<string, AnyResource>
+}
+`
+}