@tonoid/agent-loop 1.0.0

package/src/kinds/reviewer.ts

@@ -0,0 +1,220 @@
+import type { Ctx, FilingConfig, Job, WorkItem } from "../types"
+import { type Kind, oneOf, unknownKey } from "./validate"
+import { issues, prs, unblocked } from "./shared"
+import { renderBrief } from "../brief"
+import { filingBudget } from "../filing"
+import { repoOf } from "../engine/item"
+
+interface Options {
+  identity: string
+  headRef: string
+  rounds: number
+  commentPrefix: string
+  mergeMode: string
+  passLabel: string
+  filing?: Record<string, unknown>
+  deleteRemote: boolean
+  copyIntoWorktree: string[]
+  journal: boolean
+  subagents: boolean
+  screenshots: boolean
+}
+
+const IDENTITIES = ["pr", "closing-issue", "head-ref-issue"]
+const MERGE_MODES = ["merge", "squash", "none"]
+const FILING_KEYS = ["queue", "maxOpen", "perRound", "dedupeBy"]
+
+// "build/b12" and "build/b12-a-title-slug" both name issue 12. Anchored on the
+// separator so "b4" cannot be read out of "b48".
+const HEAD_ISSUE = /(?:^|\/)b(\d+)(?:-|$)/
+
+export const reviewer: Kind = {
+  name: "reviewer",
+  workload: "reviewer",
+  fields: [
+    { name: "identity", type: "string", default: "pr", doc: "what a review is keyed on: pr, closing-issue, or head-ref-issue" },
+    { name: "headRef", type: "string", default: "", doc: "only pull requests whose head branch starts with this; empty for every one" },
+    { name: "rounds", type: "number", default: 0, doc: "advisory cap on review rounds, passed to the brief, 0 for none" },
+    { name: "commentPrefix", type: "string", default: "Review round", doc: "the prefix a round comment starts with" },
+    { name: "mergeMode", type: "string", default: "", doc: "merge, squash, none, or empty for the workspace's mergeMethod" },
+    { name: "passLabel", type: "string", default: "", doc: "a label that releases the slot while the pull request stays open" },
+    { name: "filing", type: "object", doc: "backpressure: queue, maxOpen, perRound, dedupeBy" },
+    { name: "deleteRemote", type: "boolean", default: false, doc: "delete the branch on sweep; a review branch is never pushed" },
+    { name: "copyIntoWorktree", type: "string[]", default: [], doc: "files copied from the repository into a fresh worktree" },
+    { name: "journal", type: "boolean", default: false, doc: "ask the worker to append one line to the journal" },
+    { name: "subagents", type: "boolean", default: false, doc: "allow parallel review subagents" },
+    { name: "screenshots", type: "boolean", default: false, doc: "allow screenshots on an orphan asset branch" },
+  ],
+
+  // Three reviewer variants in production differ in six substantive ways, and
+  // every one of them is a state-machine switch rather than a cosmetic. A typo
+  // in one of these parses clean and changes what the loop does with a merge,
+  // so none of them may be validated by shape alone.
+  check(spec) {
+    const o = spec.options as unknown as Options
+    const errs = [...oneOf("identity", String(o.identity ?? ""), IDENTITIES)]
+    if (o.mergeMode && !MERGE_MODES.includes(o.mergeMode)) {
+      errs.push("options.mergeMode must be one of merge, squash, none, or empty for the workspace default")
+    }
+    // Nothing merges and nothing releases the claim, so the item is claimed
+    // forever and the slot never comes back.
+    if (o.mergeMode === "none" && !o.passLabel) {
+      errs.push("options.mergeMode none requires a passLabel, which is the only thing left that releases the item")
+    }
+    if (o.filing) {
+      for (const key of Object.keys(o.filing)) {
+        if (!FILING_KEYS.includes(key)) errs.push(`options.filing: ${unknownKey(key, FILING_KEYS)}`)
+      }
+      if (typeof o.filing.queue !== "string" || !o.filing.queue) {
+        errs.push("options.filing.queue is required and must name the consumer job")
+      }
+      for (const key of ["maxOpen", "perRound"]) {
+        if (typeof o.filing[key] !== "number") errs.push(`options.filing.${key} is required and must be a number`)
+      }
+      if (o.filing.dedupeBy !== undefined && typeof o.filing.dedupeBy !== "string") {
+        errs.push("options.filing.dedupeBy must be a string")
+      }
+    }
+    return errs
+  },
+
+  build(spec) {
+    const o = spec.options as unknown as Options
+    const optional = [
+      o.journal ? "journal" : "",
+      o.subagents ? "subagents" : "",
+      o.screenshots ? "screenshots" : "",
+    ].filter(Boolean)
+    // The loader does not look inside an object option, so the one filing
+    // value with a default gets it here, beside the check that validates it.
+    const filing = o.filing
+      ? ({ dedupeBy: "path", ...o.filing } as unknown as FilingConfig)
+      : undefined
+
+    const numberOf = (rawKey: string): number => Number.parseInt(rawKey.replace(/^r/, ""), 10)
+
+    // A repository can hold work this job has no business reviewing, and a
+    // reviewer that claims one takes a human's pull request hostage behind its
+    // claim label. Two reviewers over one repository split it the same way.
+    const inScope = (items: WorkItem[]) =>
+      o.headRef ? items.filter((i) => (i.headRef ?? "").startsWith(o.headRef)) : items
+
+    const job: Job = {
+      name: spec.name,
+      dir: spec.dir,
+      repo: spec.repo,
+      workload: "reviewer",
+      deleteRemote: o.deleteRemote,
+      copyIntoWorktree: o.copyIntoWorktree,
+      filing,
+
+      async discover(ctx) {
+        const open = unblocked(ctx, inScope(await prs(ctx, job, "open")), o.passLabel ? [o.passLabel] : [])
+        // First in, first out. The engine takes the first eligible candidate and
+        // never re-sorts, so this ordering is an external contract.
+        return [...open].sort((a, b) => a.number - b.number)
+      },
+
+      async discoverClaimed(ctx) {
+        const claim = ctx.workspace.naming.labels.claim
+        return inScope(await prs(ctx, job, "all")).filter((i) => i.labels.includes(claim))
+      },
+
+      async key(ctx, item) {
+        if (o.identity === "pr") return `r${item.number}`
+        if (o.identity === "head-ref-issue") {
+          const m = item.headRef?.match(HEAD_ISSUE)
+          if (m) return `r${m[1]}`
+          ctx.log({ pass: "warn", job: job.name, reason: `no issue in head "${item.headRef ?? ""}" for ${item.id}, keying on the pull request` })
+          return `r${item.number}`
+        }
+        const view = await ctx.cache(`job:closing:${item.id}`, () =>
+          ctx.gh.prView(repoOf(item), String(item.number), ["closingIssuesReferences"]))
+        const closing = view?.closingIssuesReferences?.[0]?.number
+        if (typeof closing === "number") return `r${closing}`
+        ctx.log({ pass: "warn", job: job.name, reason: `${item.id} closes no issue, keying on the pull request` })
+        return `r${item.number}`
+      },
+
+      // Counted from the pull request's own comments, with startsWith and never
+      // includes: a transcript tail is posted in a fenced block and contains the
+      // prefix, which would make every failure look like another round.
+      async attempt(ctx, item) {
+        if (!o.rounds) return 1
+        const view = await ctx.cache(`job:comments:${item.id}`, () =>
+          ctx.gh.prView(repoOf(item), String(item.number), ["comments"]))
+        const rounds = (view?.comments ?? []).filter((c: any) =>
+          String(c?.body ?? "").startsWith(o.commentPrefix)).length
+        return rounds + 1
+      },
+
+      // The head branch itself is checked out in the builder's worktree and git
+      // forbids a second checkout, so a review works a throwaway local branch
+      // based on the remote head.
+      base: async (_ctx, item) => `origin/${item.headRef ?? ""}`,
+
+      // A pass label is a terminal state that releases the slot while the pull
+      // request is still open (continuous integration owns the merge). Merged
+      // and closed are handled by the monitor's own state check.
+      async done(_ctx, item) {
+        return o.passLabel ? item.labels.includes(o.passLabel) : false
+      },
+
+      // Frequently a different predicate from done(): done releases the slot,
+      // sweepOk tears the worktree down, and tearing it down at the pass label
+      // would destroy a run that is still reconciling.
+      //
+      // A lookup that finds nothing falls through to the pull request branch
+      // rather than answering false. key() falls back to the pull request's own
+      // number whenever the identity cannot be resolved, and sweepOk cannot know
+      // that happened: a key matching no issue is exactly what that fallback
+      // produces, so reading it as a pull request number is what the fallback
+      // means. Answering false instead leaks the worktree, the branch and the
+      // tab forever.
+      async sweepOk(ctx, rawKey) {
+        const number = numberOf(rawKey)
+        if (o.identity === "closing-issue") {
+          const issue = (await issues(ctx, job, "all")).find((i) => i.number === number)
+          if (issue) return issue.state !== "OPEN"
+        }
+        if (o.identity === "head-ref-issue") {
+          const all = await prs(ctx, job, "all")
+          const mine = all.filter((p) => p.headRef?.match(HEAD_ISSUE)?.[1] === String(number))
+          const newest = mine.length ? mine.reduce((a, b) => (b.number > a.number ? b : a)) : null
+          if (newest) return newest.state !== "OPEN"
+        }
+        const pr = (await prs(ctx, job, "all")).find((p) => p.number === number)
+        return pr !== undefined && pr.state !== "OPEN"
+      },
+
+      async brief(ctx, item) {
+        const budget = await filingBudget(ctx, job)
+        // The brief has no conditionals, so the kind writes the whole verdict
+        // step. Under "none" the merge is not the worker's to make, and a brief
+        // that said "merge with none" would hand an unattended worker the forge
+        // default: the merge the operator set this option to prevent.
+        const method = o.mergeMode === "none" ? "" : o.mergeMode || ctx.workspace.naming.mergeMethod
+        const mergeInstruction = method
+          ? `Merge with \`${method}\`, then poll the merge state until it is definitive. A state of UNKNOWN is not a merge; keep polling.`
+          : `The merge is not yours to make. Apply the \`${o.passLabel}\` label instead, and do not merge. Continuous integration owns the merge from there.`
+        return renderBrief(ctx, job, item, await job.key(ctx, item), {
+          extends: spec.brief?.extends ?? "default/review",
+          optional,
+          append: spec.brief?.append,
+        }, {
+          attemptCap: o.rounds,
+          filingBudget: budget.filingBudget,
+          openQueue: budget.openQueue,
+          mergeInstruction,
+          // Never the literal "none": that names an absence of a merge, not a
+          // method, and prose elsewhere reads this as a method.
+          mergeMethod: method || ctx.workspace.naming.mergeMethod,
+          commentPrefix: o.commentPrefix,
+          passLabel: o.passLabel,
+          dedupeBy: filing?.dedupeBy ?? "path",
+        })
+      },
+    }
+    return job
+  },
+}

package/src/kinds/routine.ts

@@ -0,0 +1,174 @@
+import { existsSync } from "node:fs"
+import { isAbsolute, resolve } from "node:path"
+import type { Ctx, Job, WorkItem } from "../types"
+import type { Kind } from "./validate"
+import { renderBrief } from "../brief"
+import { owns, keyOf } from "../engine/naming"
+import { expandHome } from "../paths"
+import { appendJournal } from "../journal"
+
+interface Options {
+  at: string[]
+  days: string[]
+  doneWhen: string
+  base: string
+  deleteRemote: boolean
+  copyIntoWorktree: string[]
+  journal: boolean
+}
+
+const TIME = /^([01]\d|2[0-3]):([0-5]\d)$/
+const DAYS = ["sun", "mon", "tue", "wed", "thu", "fri", "sat"]
+
+const pad = (n: number) => String(n).padStart(2, "0")
+const stamp = (d: Date) => `${d.getFullYear()}${pad(d.getMonth() + 1)}${pad(d.getDate())}`
+
+// Deliberately not a cron expression. A real routine is due across a window,
+// from its slot until the next one begins and then never, which is what makes a
+// slot missed to a reboot fire once on the first tick back inside its window and
+// never fire stale afterwards. A cron instant either misses slots after every
+// reboot or double-fires them.
+export function occurrenceKey(now: Date, at: string[]): string | null {
+  const slots = [...at].filter((t) => TIME.test(t)).sort()
+  if (!slots.length) return null
+  const minutes = now.getHours() * 60 + now.getMinutes()
+  const asMinutes = (t: string) => Number(t.slice(0, 2)) * 60 + Number(t.slice(3, 5))
+  const today = slots.filter((t) => asMinutes(t) <= minutes)
+  if (today.length) {
+    const slot = today[today.length - 1]!
+    return `${stamp(now)}-${slot.replace(":", "")}`
+  }
+  // Before the first slot of the day: the occurrence still running is
+  // yesterday's last one.
+  const yesterday = new Date(now)
+  yesterday.setDate(yesterday.getDate() - 1)
+  return `${stamp(yesterday)}-${slots[slots.length - 1]!.replace(":", "")}`
+}
+
+// The weekday of the occurrence, not of the clock: before the first slot of the
+// day the occurrence still running is yesterday's, and it is yesterday's
+// weekday that decides whether it was ever due.
+function onDay(key: string, days: string[]): boolean {
+  if (!days.length) return true
+  const [y, m, d] = [key.slice(0, 4), key.slice(4, 6), key.slice(6, 8)].map(Number)
+  return days.includes(DAYS[new Date(y!, m! - 1, d!).getDay()]!)
+}
+
+// The occurrence's own completion marker: the artifact the run exists to
+// produce. Without one the only signal a routine has is its worktree
+// disappearing, and that does not happen until the occurrence rolls, so a run
+// that finished at 09:38 would be nudged and then failed for hours.
+function donePath(spec: { dir: string }, pattern: string, key: string): string {
+  const filled = expandHome(pattern.replaceAll("{{key}}", key))
+  return isAbsolute(filled) ? filled : resolve(spec.dir, filled)
+}
+
+const itemFor = (key: string, name: string): WorkItem => ({
+  // No url, so nothing labels it and nothing comments on it: the loop's own
+  // mark and the worktree on disk are the whole record of this run.
+  id: `key:${key}`,
+  number: 0,
+  title: name,
+  state: "OPEN",
+  labels: [],
+})
+
+export const routine: Kind = {
+  name: "routine",
+  workload: "routine",
+  fields: [
+    { name: "at", type: "string[]", required: true, doc: "slot times, local, like 09:10; due from the slot until the next one" },
+    { name: "days", type: "string[]", default: [], doc: "weekdays the run is due, like mon tue; empty for every day" },
+    { name: "doneWhen", type: "string", default: "", doc: "a file, {{key}} substituted, whose existence ends the occurrence" },
+    { name: "base", type: "string", default: "origin/main", doc: "the ref the run branches from" },
+    { name: "deleteRemote", type: "boolean", default: false, doc: "delete the branch on sweep if the run pushed one" },
+    { name: "copyIntoWorktree", type: "string[]", default: [], doc: "files copied from the repository into a fresh worktree" },
+    { name: "journal", type: "boolean", default: true, doc: "ask the worker to append one line to the journal" },
+  ],
+
+  check(spec) {
+    const at = (spec.options.at ?? []) as string[]
+    const errs = at.filter((t) => !TIME.test(t)).map((t) => `options.at: "${t}" is not a time of day like 09:10`)
+    if (!errs.length && at.length === 0) errs.push("options.at must name at least one time of day")
+    for (const d of (spec.options.days ?? []) as string[]) {
+      if (!DAYS.includes(d)) errs.push(`options.days: "${d}" is not a weekday like mon`)
+    }
+    return errs
+  },
+
+  build(spec) {
+    const o = spec.options as unknown as Options
+    const optional = o.journal ? ["journal"] : []
+    const keyOfItem = (item: WorkItem) => item.id.replace(/^key:/, "")
+
+    const job: Job = {
+      name: spec.name,
+      dir: spec.dir,
+      repo: spec.repo,
+      workload: "routine",
+      deleteRemote: o.deleteRemote,
+      copyIntoWorktree: o.copyIntoWorktree,
+
+      // The spawned mark is authoritative local state here, not derived: there
+      // is no label and no pull request to read it back from (spec 7).
+      async discover(ctx) {
+        const key = occurrenceKey(ctx.now, o.at)
+        if (!key || !onDay(key, o.days)) return []
+        return ctx.marks.has(job.name, key, "spawned") ? [] : [itemFor(key, job.name)]
+      },
+
+      // Derived from the world after all: a worktree this job owns is a run in
+      // flight, whatever the marks say.
+      async discoverClaimed(ctx) {
+        const repo = ctx.workspace.repos[job.repo ?? ""]
+        if (!repo) return []
+        // The engine's own worktree cache, not a job: prefix - the sweep pass
+        // earlier in this same tick already reads this exact key, so sharing
+        // its snapshot is the point, not an accident.
+        const worktrees = await ctx.cache(`engine:worktrees:${repo}`, () => ctx.git(repo).worktrees())
+        return worktrees
+          .filter((wt) => owns(job.name, ctx.workspace.worktreeBase, wt))
+          .map((wt) => itemFor(keyOf(job.name, wt.branch)!, job.name))
+      },
+
+      key: async (ctx, item) => keyOfItem(item) || occurrenceKey(ctx.now, o.at) || "",
+      base: async () => o.base,
+
+      // Done when the worktree is gone, which is the only external record this
+      // job has. While it exists the monitor supervises the worker: busy,
+      // nudge, then fail, like every other item.
+      async done(ctx, item) {
+        if (o.doneWhen && existsSync(donePath(spec, o.doneWhen, keyOfItem(item)))) return true
+        const claimed = await job.discoverClaimed(ctx)
+        return !claimed.some((c) => c.id === item.id)
+      },
+
+      // A routine must sweep occurrences that are no longer due, which is a
+      // different question from done(): without a completion marker the current
+      // occurrence's worktree has to stay until its window closes, because
+      // nothing else says the run is over. A doneWhen does say so, and the run
+      // that wrote it has no more use for its checkout or its tab: a six-hourly
+      // routine that finished at 09:38 would otherwise hold both until 12:10.
+      // The sweep checks for a working agent before it asks this, so a marker
+      // written mid-run still cannot pull a worktree out from under one.
+      async sweepOk(ctx, rawKey) {
+        if (o.doneWhen && existsSync(donePath(spec, o.doneWhen, rawKey))) return true
+        return rawKey !== occurrenceKey(ctx.now, o.at)
+      },
+
+      // The default failure path labels and comments, and there is nothing here
+      // to label. The journal is the whole post-mortem, so it gets the tail.
+      async onFail(ctx, item, transcriptTail) {
+        appendJournal(ctx, `FAIL ${job.name} ${keyOfItem(item)}: ${transcriptTail.split("\n").slice(-5).join(" ").trim()}`)
+      },
+
+      brief: (ctx, item) =>
+        renderBrief(ctx, job, item, keyOfItem(item), {
+          extends: spec.brief?.extends ?? "default/routine",
+          optional,
+          append: spec.brief?.append,
+        }),
+    }
+    return job
+  },
+}

package/src/kinds/shared.ts

@@ -0,0 +1,49 @@
+import type { Ctx, Job, WorkItem } from "../types"
+
+// Every remote read a kind performs is memoized per tick under the job's own
+// namespace. Without this the natural implementation puts a list call inside a
+// guard and pays one network round trip per candidate: on a repository with 139
+// open issues that was roughly 175 seconds in the pick loop alone.
+export async function slugOf(ctx: Ctx, job: Job): Promise<string> {
+  const path = ctx.workspace.repos[job.repo ?? ""]
+  if (!path) throw new Error(`job "${job.name}" has no resolvable repo`)
+  return ctx.cache(`job:slug:${path}`, () => ctx.git(path).remoteSlug())
+}
+
+export async function issues(ctx: Ctx, job: Job, state: "open" | "all"): Promise<WorkItem[]> {
+  const slug = await slugOf(ctx, job)
+  return ctx.cache(`job:issues:${slug}:${state}`, () => ctx.gh.issueList({ repo: slug, state }))
+}
+
+export async function prs(ctx: Ctx, job: Job, state: "open" | "all"): Promise<WorkItem[]> {
+  const slug = await slugOf(ctx, job)
+  return ctx.cache(`job:prs:${slug}:${state}`, () => ctx.gh.prList({ repo: slug, state }))
+}
+
+// Claimed, failed, and parked items are not candidates: the claim belongs to a
+// live worker, the failure is waiting for a human, and the park is a question
+// nobody answered.
+export function unblocked(ctx: Ctx, items: WorkItem[], extra: string[] = []): WorkItem[] {
+  const l = ctx.workspace.naming.labels
+  const blocked = new Set([l.claim, l.failed, l.park, ...extra].filter(Boolean))
+  return items.filter((i) => !i.labels.some((name) => blocked.has(name)))
+}
+
+// Priority labels first, in the order the workspace lists them, then oldest
+// first. discover() returns candidates in priority order and the engine takes
+// the first eligible without re-sorting, so this ordering is the contract.
+export function byPriority(ctx: Ctx, items: WorkItem[]): WorkItem[] {
+  const priority = ctx.workspace.naming.labels.priority
+  const rank = (i: WorkItem) => {
+    const at = priority.findIndex((p) => i.labels.includes(p))
+    return at === -1 ? priority.length : at
+  }
+  return [...items].sort((a, b) => rank(a) - rank(b) || a.number - b.number)
+}
+
+// The newest match, so a retried issue's old closed pull request never decides
+// anything about the live one working the same key (spec 4.4).
+export function newestByHead(items: WorkItem[], head: string): WorkItem | null {
+  const mine = items.filter((i) => i.headRef === head)
+  return mine.length ? mine.reduce((a, b) => (b.number > a.number ? b : a)) : null
+}

package/src/kinds/validate.ts

@@ -0,0 +1,187 @@
+import type { Job } from "../types"
+
+// The field table, the kind contract, and the pure validation helpers around
+// it. Split out of index.ts because every kind needs these while index.ts
+// imports every kind to build the registry: entering the graph at a kind then
+// hit that cycle and threw before the kind's own module body ran, which made
+// its test file unrunnable on its own.
+export type FieldType = "string" | "number" | "boolean" | "string[]" | "object"
+
+export interface Field {
+  name: string
+  type: FieldType
+  required?: boolean
+  default?: unknown
+  doc: string
+}
+
+// What the loader hands a kind: everything it validated itself, plus the
+// options it did not look inside.
+export interface JobSpec {
+  name: string
+  dir: string
+  repo?: string
+  // Engine-level, so the loader resolves and checks it and the kind only
+  // renders it. `append` is already an absolute path by the time a kind sees it.
+  brief?: { extends?: string; append?: string }
+  options: Record<string, unknown>
+}
+
+export interface Kind {
+  name: string
+  workload: string
+  fields: Field[]
+  // Validation a field table cannot express: an enum, or the shape inside an
+  // object option. Returns messages in validateOptions' vocabulary, which the
+  // loader prefixes with the job file. A typo like "reserved" for "reserve"
+  // parses clean and silently disarms whatever it configures, so a kind with an
+  // enum or an object option owes the operator this.
+  check?(spec: JobSpec): string[]
+  build(spec: JobSpec): Job
+}
+
+function levenshtein(a: string, b: string): number {
+  const d: number[][] = Array.from({ length: a.length + 1 }, () => new Array(b.length + 1).fill(0))
+  for (let i = 0; i <= a.length; i++) d[i]![0] = i
+  for (let j = 0; j <= b.length; j++) d[0]![j] = j
+  for (let i = 1; i <= a.length; i++) {
+    for (let j = 1; j <= b.length; j++) {
+      d[i]![j] = Math.min(
+        d[i - 1]![j]! + 1,
+        d[i]![j - 1]! + 1,
+        d[i - 1]![j - 1]! + (a[i - 1] === b[j - 1] ? 0 : 1),
+      )
+    }
+  }
+  return d[a.length]![b.length]!
+}
+
+// A typo is worth a suggestion; a different word is not. The threshold keeps
+// "did you mean" from firing on names that merely start with the same letter.
+export function didYouMean(word: string, candidates: string[]): string {
+  let best = ""
+  let bestD = Infinity
+  for (const c of candidates) {
+    const d = levenshtein(word, c)
+    if (d < bestD) { bestD = d; best = c }
+  }
+  // Two edits, not one: a transposition costs two, and "wbe" for "web" is the
+  // most common typo there is. A floor of one makes the suggester blind to it
+  // for every short word, which is most repo keys and kind names.
+  return bestD <= Math.max(2, Math.floor(word.length * 0.4)) ? best : ""
+}
+
+// The unknown-key message, in the same shape validateOptions produces for an
+// unknown option. A typo is the whole reason these checks exist, so a message
+// that lists the known keys without pointing at the near miss is half a fix.
+export function unknownKey(key: string, known: string[]): string {
+  const near = didYouMean(key, known)
+  return near
+    ? `unknown key "${key}"; did you mean "${near}"?`
+    : `unknown key "${key}"; known: ${known.join(", ")}`
+}
+
+export function oneOf(field: string, value: string, allowed: string[]): string[] {
+  if (allowed.includes(value)) return []
+  const near = didYouMean(value, allowed)
+  return [
+    near
+      ? `options.${field} must be one of ${allowed.join(", ")}; did you mean "${near}"?`
+      : `options.${field} must be one of ${allowed.join(", ")}`,
+  ]
+}
+
+// Names the shape a value has, in the vocabulary the field table uses, so the
+// error an operator reads is in the same words as the documentation.
+function shapeOf(v: unknown): string {
+  if (Array.isArray(v)) return "list"
+  if (v === null) return "null"
+  return typeof v
+}
+
+function typeOk(v: unknown, t: FieldType): boolean {
+  switch (t) {
+    case "string": return typeof v === "string"
+    case "number": return typeof v === "number" && Number.isFinite(v)
+    case "boolean": return typeof v === "boolean"
+    case "string[]": return Array.isArray(v) && v.every((x) => typeof x === "string")
+    case "object": return typeof v === "object" && v !== null && !Array.isArray(v)
+  }
+}
+
+export function validateOptions(
+  kind: Kind,
+  options: Record<string, unknown>,
+): { errors: string[]; value: Record<string, unknown> } {
+  const errors: string[] = []
+  const known = kind.fields.map((f) => f.name)
+
+  for (const key of Object.keys(options)) {
+    if (known.includes(key)) continue
+    const near = didYouMean(key, known)
+    errors.push(
+      near
+        ? `unknown option "${key}"; did you mean "${near}"?`
+        : `unknown option "${key}"; known: ${known.join(", ")}`,
+    )
+  }
+
+  const value: Record<string, unknown> = {}
+  for (const f of kind.fields) {
+    const given = options[f.name]
+    if (given === undefined || given === null) {
+      if (f.required) errors.push(`options.${f.name} is required (${f.doc})`)
+      else if (f.default !== undefined) value[f.name] = f.default
+      continue
+    }
+    if (!typeOk(given, f.type)) {
+      errors.push(
+        f.type === "string[]"
+          ? `options.${f.name} must be a list of strings`
+          : `options.${f.name} must be a ${f.type}, found ${shapeOf(given)}`,
+      )
+      continue
+    }
+    value[f.name] = given
+  }
+  return { errors, value }
+}
+
+export function describeKind(k: Kind): string[] {
+  const notes = k.fields.map((f) => (f.required ? "required" : `= ${JSON.stringify(f.default)}`))
+  const width = Math.max(...k.fields.map((f) => f.name.length))
+  const typeWidth = Math.max(...k.fields.map((f) => f.type.length))
+  const noteWidth = Math.max(...notes.map((n) => n.length))
+  const lines = [`${k.name} (workload: ${k.workload})`]
+  k.fields.forEach((f, i) => {
+    lines.push(
+      `  ${f.name.padEnd(width)}  ${f.type.padEnd(typeWidth)}  ${notes[i]!.padEnd(noteWidth)}  ${f.doc}`,
+    )
+  })
+  return lines
+}
+
+const JSON_TYPE: Record<FieldType, object> = {
+  string: { type: "string" },
+  number: { type: "number" },
+  boolean: { type: "boolean" },
+  "string[]": { type: "array", items: { type: "string" } },
+  object: { type: "object" },
+}
+
+export function kindSchema(k: Kind): object {
+  const properties: Record<string, object> = {}
+  for (const f of k.fields) {
+    properties[f.name] = {
+      ...JSON_TYPE[f.type],
+      ...(f.default === undefined ? {} : { default: f.default }),
+      description: f.doc,
+    }
+  }
+  return {
+    type: "object",
+    properties,
+    required: k.fields.filter((f) => f.required).map((f) => f.name),
+    additionalProperties: false,
+  }
+}