babavoss 0.0.1 → 0.12.0

package/src/kernel/lock.ts

@@ -0,0 +1,46 @@
+// A lock on a directory: one process at a time. A file created exclusively,
+// holding the holder's pid and what it is; a second taker reads it, and
+// yields to a live holder or takes over from a dead one. Released on stop
+// and at exit, only if the file is still the holder's own.
+import { openSync, closeSync, writeSync, readFileSync, unlinkSync, constants } from "node:fs";
+
+export interface Holder { pid: number; [k: string]: unknown }
+
+export class LockError extends Error {
+  constructor(readonly path: string, readonly holder: Holder, msg: string) { super(msg); }
+  readonly code = "busy";
+}
+
+export interface Lock { readonly path: string; release(): void }
+
+const alive = (pid: number): boolean => {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try { process.kill(pid, 0); return true; } catch (err) { return (err as { code?: string }).code === "EPERM"; }
+};
+
+/** Takes the lock at `path` for this process, with `what` beside the pid; throws LockError while another live process holds it. */
+export function takeLock(path: string, what: Record<string, unknown> = {}, describe = (h: Holder) => `held by pid ${h.pid}`): Lock {
+  const text = JSON.stringify({ pid: process.pid, ...what }) + "\n";
+  for (let attempt = 0; attempt < 2; attempt++) {
+    try {
+      const fd = openSync(path, constants.O_WRONLY | constants.O_CREAT | constants.O_EXCL, 0o600);
+      try { writeSync(fd, text); } finally { closeSync(fd); }
+      break;
+    } catch (err) {
+      if ((err as { code?: string }).code !== "EEXIST") throw err;
+      let holder: Holder | null = null;
+      try { holder = JSON.parse(readFileSync(path, "utf8")) as Holder; } catch { /* unreadable: a dead or half-written lock */ }
+      // A live holder holds, this process included: a second opener here is a bug the lock is meant to catch.
+      if (holder && alive(holder.pid)) throw new LockError(path, holder, `${path}: ${describe(holder)}`);
+      // The holder is gone: take over.
+      try { unlinkSync(path); } catch { /* raced away */ }
+      if (attempt === 1) throw new LockError(path, holder ?? { pid: 0 }, `${path}: could not take the lock`);
+    }
+  }
+  const release = () => {
+    process.off("exit", release);
+    try { if (readFileSync(path, "utf8") === text) unlinkSync(path); } catch { /* already gone */ }
+  };
+  process.once("exit", release);
+  return { path, release };
+}

package/src/kernel/names.ts

@@ -0,0 +1,14 @@
+// How a build is named for people: its version, or "source" from a checkout;
+// and two builds told apart when they share a name, by the moment each was built.
+export interface Named { version?: string; sha?: string; at?: string; dev?: boolean }
+
+/** One word for a build: its version, or "source" when run from a checkout. */
+export const buildName = (b: Named) => b.dev ? "source" : (b.version || b.sha || "unstamped");
+
+/** Two builds, each named so a reader can tell them apart: by name, or by the moment when the name is the same. */
+export function tellApart(a: Named, b: Named): [string, string] {
+  const na = buildName(a), nb = buildName(b);
+  if (na !== nb) return [na, nb];
+  const when = (x: Named) => x.at ? `${buildName(x)} built ${x.at.slice(11, 19)}Z` : buildName(x);
+  return [when(a), when(b)];
+}

package/src/kernel/schema.ts

@@ -0,0 +1,130 @@
+// A small schema language: one declaration gives the TypeScript type, the
+// JSON Schema the edges read, and the check at the edges. No dependency.
+
+export type Json = { [k: string]: unknown };
+
+export interface Schema<T> {
+  readonly json: Json;
+  /** Returns the value as T, or throws SchemaError. `coerce` turns shell strings into numbers and booleans. */
+  check(value: unknown, path?: string, coerce?: boolean): T;
+  describe(text: string): Schema<T>;
+}
+
+export type Infer<S> = S extends Schema<infer T> ? T : never;
+
+export class SchemaError extends Error {
+  constructor(readonly path: string, msg: string) { super(`${path || "value"}: ${msg}`); }
+}
+
+function make<T>(json: Json, check: (v: unknown, path: string, coerce: boolean) => T): Schema<T> {
+  const s: Schema<T> = {
+    json,
+    check: (v, path = "", coerce = false) => check(v, path, coerce),
+    describe: (text) => make({ ...json, description: text }, check),
+  };
+  return s;
+}
+
+// Exported, and annotated, so a declaration file can name what a contract's optional args carry.
+export const OPTIONAL: unique symbol = Symbol("optional");
+export type Optional<T> = Schema<T | undefined> & { [OPTIONAL]: true };
+
+export const s = {
+  string: () => make<string>({ type: "string" }, (v, p) => {
+    if (typeof v !== "string") throw new SchemaError(p, "expected a string");
+    return v;
+  }),
+  number: () => make<number>({ type: "number" }, (v, p, c) => {
+    if (c && typeof v === "string" && v !== "" && !isNaN(Number(v))) v = Number(v);
+    if (typeof v !== "number" || !isFinite(v)) throw new SchemaError(p, "expected a number");
+    return v;
+  }),
+  integer: () => make<number>({ type: "integer" }, (v, p, c) => {
+    if (c && typeof v === "string" && /^-?\d+$/.test(v)) v = Number(v);
+    if (typeof v !== "number" || !Number.isInteger(v)) throw new SchemaError(p, "expected an integer");
+    return v;
+  }),
+  boolean: () => make<boolean>({ type: "boolean" }, (v, p, c) => {
+    if (c && (v === "true" || v === "")) v = true;
+    if (c && v === "false") v = false;
+    if (typeof v !== "boolean") throw new SchemaError(p, "expected a boolean");
+    return v;
+  }),
+  literal: <const L extends string | number | boolean>(value: L) => make<L>({ const: value }, (v, p) => {
+    if (v !== value) throw new SchemaError(p, `expected ${JSON.stringify(value)}`);
+    return v as L;
+  }),
+  enum: <const E extends readonly string[]>(...values: E) => make<E[number]>({ type: "string", enum: [...values] }, (v, p) => {
+    if (typeof v !== "string" || !values.includes(v)) throw new SchemaError(p, `expected one of ${values.join(", ")}`);
+    return v as E[number];
+  }),
+  /** A tag: a component that is present or not; its only value is true. */
+  tag: () => make<true>({ const: true, description: "a tag" }, (v, p) => {
+    if (v !== true) throw new SchemaError(p, "expected true");
+    return true as const;
+  }),
+  /**
+   * An entity id of the baba's state: an integer from 1. Naming a component
+   * (`s.entity("task")`) records it as `x-entity`: in an action's args the
+   * runtime checks the entity carries it, and, when the component has a key
+   * field, takes that key as a string in place of the id.
+   */
+  entity: (component?: string) => make<number>({ type: "integer", minimum: 1, description: "an entity", ...(component ? { "x-entity": component } : {}) }, (v, p, c) => {
+    if (c && typeof v === "string" && /^\d+$/.test(v)) v = Number(v);
+    if (component && typeof v === "string" && v !== "") return v as unknown as number;   // a key, resolved by the runtime
+    if (typeof v !== "number" || !Number.isInteger(v) || v < 1) throw new SchemaError(p, component ? `expected an entity id or a ${component} key` : "expected an entity id");
+    return v;
+  }),
+  /** A component's key field: a string or integer by which `w.find` and an action's `s.entity(component)` args find the entity. */
+  key: <T extends string | number>(inner: Schema<T>) => {
+    if (inner.json.type !== "string" && inner.json.type !== "integer") throw new Error("s.key: a string or an integer schema");
+    return make<T>({ ...inner.json, "x-key": true }, (v, p, c) => inner.check(v, p, c));
+  },
+  /** A secret: a string that the runtime redacts from every snapshot that leaves it. */
+  secret: () => make<string>({ type: "string", format: "secret" }, (v, p) => {
+    if (typeof v !== "string") throw new SchemaError(p, "expected a string");
+    return v;
+  }),
+  unknown: () => make<unknown>({}, (v) => v),
+  void: () => make<void>({ type: "null" }, (v, p) => {
+    if (v != null) throw new SchemaError(p, "expected nothing");
+  }),
+  array: <T>(item: Schema<T>) => make<T[]>({ type: "array", items: item.json }, (v, p, c) => {
+    if (c && typeof v === "string") v = [v];
+    if (!Array.isArray(v)) throw new SchemaError(p, "expected an array");
+    return v.map((x, i) => item.check(x, `${p}[${i}]`, c));
+  }),
+  nullable: <T>(inner: Schema<T>) => make<T | null>({ ...inner.json, type: [inner.json.type, "null"] }, (v, p, c) =>
+    v === null ? null : inner.check(v, p, c)),
+  optional: <T>(inner: Schema<T>): Optional<T> => {
+    const o = make<T | undefined>(inner.json, (v, p, c) => (v === undefined ? undefined : inner.check(v, p, c))) as Optional<T>;
+    o[OPTIONAL] = true;
+    return o;
+  },
+  /** An object of these fields; `open` lets fields the schema does not name through, as the outside sends them. */
+  object: <P extends Record<string, Schema<any>>>(props: P, o: { open?: boolean } = {}) => {
+    const required = Object.keys(props).filter((k) => !(OPTIONAL in props[k]!));
+    const json: Json = {
+      type: "object",
+      properties: Object.fromEntries(Object.entries(props).map(([k, v]) => [k, v.json])),
+      ...(required.length ? { required } : {}),
+      additionalProperties: o.open === true,
+    };
+    return make<ObjectOf<P> & (typeof o extends { open: true } ? Record<string, unknown> : {})>(json, (v, p, c) => {
+      if (typeof v !== "object" || v === null || Array.isArray(v)) throw new SchemaError(p, "expected an object");
+      const out: Record<string, unknown> = {};
+      for (const k of Object.keys(v)) { if (!(k in props)) { if (o.open) out[k] = (v as Record<string, unknown>)[k]; else throw new SchemaError(p ? `${p}.${k}` : k, "unknown field"); } }
+      for (const [k, sch] of Object.entries(props)) {
+        const r = sch.check((v as Record<string, unknown>)[k], p ? `${p}.${k}` : k, c);
+        if (r !== undefined) out[k] = r;
+      }
+      return out as ObjectOf<P>;
+    });
+  },
+};
+
+type OptionalKeys<P> = { [K in keyof P]: P[K] extends { [OPTIONAL]: true } ? K : never }[keyof P];
+export type ObjectOf<P extends Record<string, Schema<any>>> = Flat<
+  { [K in Exclude<keyof P, OptionalKeys<P>>]: Infer<P[K]> } & { [K in OptionalKeys<P>]?: Infer<P[K]> }
+>;
+type Flat<T> = { [K in keyof T]: T[K] } & {};

package/src/kernel/where.ts

@@ -0,0 +1,12 @@
+// Where this voss runs from. The framework is this package's directory,
+// `packages/babavoss` in the repository, `node_modules/babavoss` installed.
+// A developer checkout keeps voss's state beside the source and links new
+// babas to the tree; an installed package keeps it under ~/.voss and pins
+// new babas to its version. A path under node_modules tells them apart.
+import { basename, dirname } from "node:path";
+
+/** The framework's directory: the package, wherever it is. */
+export const framework = dirname(dirname(dirname(Bun.fileURLToPath(import.meta.url))));
+
+/** True in a developer checkout of the repository; false installed as a package. */
+export const dev = basename(dirname(framework)) !== "node_modules";

package/src/kit/index.ts

@@ -0,0 +1,232 @@
+// The kit: a baba's components, shadcn's way. The baba owns them as copies
+// under .baba/ui, added by shadcn's CLI and styled by Tailwind over voss's
+// theme tokens; babavoss ships no component and takes no dependency. This
+// module carries what a baba needs to have a kit, the files init writes and
+// the packages it installs, and the kit system, which keeps the kit as objects
+// in the state and adds to it through the port.
+import { effect, source } from "../ecs/baba.ts";
+import { system } from "../ecs/system.ts";
+import { not } from "../ecs/state.ts";
+import { s } from "../kernel/schema.ts";
+import type { Context } from "../kernel/context.ts";
+
+/** The packages a kit stands on, written into the baba's package.json. */
+export const kitDependencies: Record<string, string> = {
+  "tailwindcss": "^4.3.3",
+  "bun-plugin-tailwind": "^0.1.2",
+  "cn": "^0.4.0",
+  "class-variance-authority": "^0.7.1",
+  "radix-ui": "^1.6.7",
+  "lucide-react": "^1.52.0",
+};
+
+/** The files a kit needs under .baba: shadcn's config, the bridge from shadcn's token names to voss's theme, the class helper. */
+export const kitFiles: Record<string, string> = {
+  "components.json": `{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "new-york",
+  "rsc": false,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "ui.css",
+    "baseColor": "neutral",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "aliases": {
+    "components": "@/ui",
+    "utils": "@/lib/utils",
+    "ui": "@/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  }
+}
+`,
+  "ui.css": `@import "tailwindcss";
+@source "./systems";
+@source "./ui";
+@source "./apps";
+@source "./interface.tsx";
+
+/* shadcn's names over voss's theme tokens: the theme stays the one source of color, type and space. */
+@theme inline {
+  /* The theme's measures, not rem: a 4px unit whatever the root font, and its two sizes of type, 13/20 and 11/16. */
+  --spacing: 4px;
+  --text-xs: 11px;
+  --text-xs--line-height: 16px;
+  --text-sm: 13px;
+  --text-sm--line-height: 20px;
+  --text-base: 13px;
+  --text-base--line-height: 20px;
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--surface);
+  --color-card-foreground: var(--foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--muted);
+  --color-secondary-foreground: var(--foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--foreground);
+  --color-destructive: var(--destructive);
+  --color-destructive-foreground: var(--primary-foreground);
+  --color-success: var(--success);
+  --color-warning: var(--warning);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--primary);
+  --color-chrome: var(--chrome);
+  --color-desk: var(--desk);
+  --radius-sm: var(--radius);
+  --radius-md: var(--radius);
+  --radius-lg: var(--radius);
+  --radius-xl: var(--radius);
+  --font-sans: var(--font-sans);
+  --font-mono: var(--font-mono);
+}
+
+/* Markdown, as GitHub flavours it, at the theme's density: 13/20 body, headings the same size and weight 600, code at 12. */
+@layer components {
+  .md { font-size: 13px; line-height: 20px; overflow-wrap: anywhere; }
+  .md > * + * { margin-top: 8px; }
+  .md h1, .md h2, .md h3, .md h4, .md h5, .md h6 { font-size: 13px; line-height: 20px; font-weight: 600; margin-top: 16px; }
+  .md h1 { font-size: 15px; }
+  .md > :first-child { margin-top: 0; }
+  .md ul, .md ol { padding-left: 20px; }
+  .md ul { list-style: disc; }
+  .md ol { list-style: decimal; }
+  .md li + li { margin-top: 2px; }
+  .md li > ul, .md li > ol { margin-top: 2px; }
+  .md li.task-list-item, .md li:has(> input[type="checkbox"]) { list-style: none; margin-left: -20px; }
+  .md code { font-family: var(--font-mono); font-size: 12px; padding: 0 4px; border-radius: var(--radius); background: var(--muted); }
+  .md pre { padding: 8px 10px; border-radius: var(--radius); background: var(--muted); overflow: auto; }
+  .md pre code { padding: 0; background: transparent; }
+  .md blockquote { padding-left: 10px; border-left: 2px solid var(--border); color: var(--muted-foreground); }
+  .md a { color: var(--primary); text-decoration: none; }
+  .md a:hover { text-decoration: underline; }
+  .md hr { border: 0; border-top: 1px solid var(--border); }
+  .md img { max-width: 100%; }
+  .md table { border-collapse: collapse; font-variant-numeric: tabular-nums; }
+  .md th, .md td { border: 1px solid var(--border); padding: 2px 8px; text-align: left; }
+  .md th { font-weight: 600; background: var(--chrome); }
+  .md del { color: var(--muted-foreground); }
+  .md strong { font-weight: 600; }
+}
+`,
+  "lib/utils.ts": `export { cn } from "cn";\n`,
+};
+
+/** The names a component file exports: what an app imports from \`@/ui/NAME\`. */
+export function exportsOf(text: string): string[] {
+  const out = new Set<string>();
+  for (const m of text.matchAll(/export\s+(?:function|const|class)\s+([A-Za-z0-9_]+)/g)) out.add(m[1]!);
+  for (const m of text.matchAll(/export\s*\{([^}]*)\}/g)) for (const part of m[1]!.split(",")) { const name = part.trim().split(/\s+as\s+/).pop()!.trim(); if (/^[A-Za-z0-9_]+$/.test(name)) out.add(name); }
+  return [...out].sort();
+}
+
+const UI = ".baba/ui";
+const works = ["add", "remove"] as const;
+
+async function listPieces(ctx: Context) {
+  const entries = await ctx.fs.list(UI).catch(() => []);
+  const files = entries.filter((e) => !e.dir && e.name.endsWith(".tsx"));
+  return Promise.all(files.map(async (e) => ({ name: e.name.replace(/\.tsx$/, ""), exports: exportsOf(await ctx.fs.read(`${UI}/${e.name}`)), bytes: e.size, updated: e.updated })));
+}
+
+/** One change to the kit, by shadcn's CLI for an addition, by the port's fs for a removal. */
+async function runKit(a: { kind: (typeof works)[number]; names: string[] }, ctx: Context) {
+  if (a.kind === "remove") {
+    for (const n of a.names) await ctx.fs.remove(`${UI}/${n}.tsx`);
+    return { output: `removed ${a.names.join(", ")}` };
+  }
+  const r = await ctx.exec.run("bun", ["x", "shadcn@latest", "add", ...a.names, "-y", "-c", ".baba"], { cwd: ctx.project });
+  if (r.code !== 0) throw new Error(`shadcn add: ${(r.stderr || r.stdout).trim().split("\n").slice(-4).join("; ")}`);
+  // One path to the class helper whatever the registry wrote: the baba's lib/utils re-exports shadcn's own.
+  for (const e of await ctx.fs.list(UI).catch(() => [])) {
+    if (e.dir || !e.name.endsWith(".tsx")) continue;
+    const text = await ctx.fs.read(`${UI}/${e.name}`);
+    if (text.includes('from "cn"')) await ctx.fs.write(`${UI}/${e.name}`, text.replaceAll('from "cn"', 'from "@/lib/utils"'));
+  }
+  return { output: (r.stdout || "").trim().split("\n").filter((l) => /ui\//.test(l)).join("; ") || `added ${a.names.join(", ")}` };
+}
+
+/**
+ * The kit system: the baba's components as objects, one per file under .baba/ui, with what each exports; additions through
+ * shadcn's CLI, removals through the port, each a job whose failure stays visible until forgotten.
+ */
+export const kit = system({
+  name: "kit",
+  model: {
+    /** A component of the kit, mirrored from .baba/ui/NAME.tsx: never written by the system. */
+    uiPiece: { name: s.key(s.string()), exports: s.array(s.string()), bytes: s.integer(), updated: s.string() },
+    /** A change asked of the kit and not yet done. */
+    kitWork: { kind: s.enum(...works), names: s.array(s.string()), asked: s.integer() },
+    kitTrouble: { error: s.string(), at: s.integer() },
+  },
+  effects: {
+    kitList: source({
+      summary: "the kit's components as the files under .baba/ui have them, with what each exports",
+      mirror: "uiPiece",
+      every: 60_000,
+      retry: 10_000,
+      list: (_, ctx) => listPieces(ctx),
+      watch: async function* (_, ctx) { for await (const _c of ctx.fs.watch(UI)) yield { changed: true as const }; },
+    }),
+    kitRun: effect({
+      summary: "one change to the kit: components added by shadcn's CLI, or removed",
+      args: s.object({ kind: s.enum(...works), names: s.array(s.string()) }),
+      result: s.object({ output: s.string() }),
+      run: (a, ctx) => runKit(a, ctx),
+    }),
+  },
+}, (kit, p) => [
+  p.on(kit.kitRun, {
+    for: (w) => w.query(kit.kitWork, not(kit.kitTrouble)).map((r) => [r.entity, { kind: r.kitWork.kind, names: r.kitWork.names }] as const),
+    done: (w, e) => { w.despawn(e!); w.cancel(kit.kitList); w.run(kit.kitList, {}); },
+    failed: (w, e, error) => { w.add(e!, kit.kitTrouble, { error, at: w.now }); },
+  }),
+
+  p.action("ui-add", {
+    summary: "add components to the kit from shadcn's registry, by name: button, dialog, command…; they land under .baba/ui, for an app to import from @/ui/NAME",
+    args: { names: s.array(s.string()) },
+    result: s.object({ entity: s.entity("kitWork") }),
+    run: (w, a) => {
+      const names = [...new Set(a.names.map((n) => n.trim()).filter(Boolean))];
+      if (!names.length) throw new Error("name at least one component, such as button");
+      for (const n of names) if (!/^[a-z0-9@/._-]+$/i.test(n) || n.includes("..")) throw new Error(`${n} is not a component name`);
+      return { entity: w.spawn(kit.kitWork, { kind: "add", names, asked: w.now }) };
+    },
+  }),
+
+  p.action("ui-remove", {
+    summary: "take a component out of the kit: its file under .baba/ui goes",
+    args: { name: s.entity("uiPiece") },
+    result: s.object({ entity: s.entity("kitWork") }),
+    run: (w, a) => ({ entity: w.spawn(kit.kitWork, { kind: "remove", names: [w.get(a.name, kit.uiPiece)!.name], asked: w.now }) }),
+  }),
+
+  p.action("ui-forget", {
+    summary: "let a failed change to the kit go",
+    args: { entity: s.entity("kitWork") },
+    result: s.void(),
+    run: (w, a) => { w.despawn(a.entity); },
+  }),
+
+  p.query("ui", {
+    summary: "the kit: every component under .baba/ui with what it exports, and the changes on their way or failed",
+    result: s.object({
+      pieces: s.array(s.object({ name: s.string(), exports: s.array(s.string()) })),
+      work: s.array(s.object({ kind: s.string(), names: s.array(s.string()), error: s.nullable(s.string()) })),
+    }),
+    read: (w) => ({
+      pieces: w.query(kit.uiPiece).map((r) => ({ name: r.uiPiece.name, exports: r.uiPiece.exports })).sort((a, b) => a.name.localeCompare(b.name)),
+      work: w.query(kit.kitWork).map((r) => ({ kind: r.kitWork.kind, names: r.kitWork.names, error: w.get(r.entity, kit.kitTrouble)?.error ?? null })),
+    }),
+  }),
+]);

package/src/maker/system.ts

@@ -0,0 +1,213 @@
+// maker: voss's system behind the Baba Maker. It mirrors the specs, each
+// system's `.baba/systems/NAME/spec.ts` and the whole baba's `.baba/spec.ts`,
+// and their verdicts under .baba/.voss/spec/, as the disk has them; `spec-run` runs a spec's
+// scenarios headless through bun test so the verdicts are remade; `spec-save`
+// writes a scenario file a person made by playing. The live simulation is
+// the page's; this system holds what the page and an agent share: files, and
+// asks. An ask (`spec-step`, `spec-read`) is an entity the page with that
+// spec open answers against its own spec, so an agent acts in and reads
+// the very spec the person is looking at.
+import { effect, resource, source } from "../ecs/baba.ts";
+import { system } from "../ecs/system.ts";
+import { changed, not, removed } from "../ecs/state.ts";
+import { s } from "../kernel/schema.ts";
+
+export const SYSTEMS_DIR = ".baba/systems";
+/** The directory of a spec's files: a system's own, or .baba for the whole baba's. */
+export const specDir = (spec: string) => spec === "baba" ? ".baba" : `${SYSTEMS_DIR}/${spec}`;
+export const SPEC_DIR = ".baba/.voss/spec";
+/** How long an ask waits for a page before it fails, and how long an answered one is kept. */
+const ASK_PATIENCE = 15_000, ASK_KEPT = 10 * 60_000;
+
+const verdictFields = { run: s.string(), at: s.string(), done: s.boolean(), scenarios: s.array(s.object({ name: s.string(), verdict: s.enum("passed", "failed", "unknown"), intent: s.string(), broke: s.nullable(s.integer()), steps: s.integer(), checks: s.integer(), failed: s.array(s.string()), quiet: s.array(s.string()), at: s.string() })) };
+
+/** The newest change under a directory, recursively, as an ISO time; "" when empty. */
+async function newest(fs: { list(path: string): Promise<{ path: string; dir: boolean; updated: string; name: string }[]> }, dir: string): Promise<string> {
+  let latest = "";
+  const walk = async (d: string) => {
+    for (const e of await fs.list(d).catch(() => [])) {
+      if (e.name === "node_modules" || e.name.startsWith(".")) continue;
+      if (e.dir) await walk(e.path); else if (e.updated > latest) latest = e.updated;
+    }
+  };
+  await walk(dir);
+  return latest;
+}
+
+export default system({
+  name: "maker",
+  model: {
+    /** A spec as the disk has it: a system's spec.ts (or the whole baba's), when it or its saved scenarios last changed, and when the systems' code did. */
+    specFile: { name: s.key(s.string()), updated: s.string(), code: s.string() },
+    /** The verdicts of a spec's last headless run, as the file under .baba/.voss/spec says; `stale` when code or spec changed since. */
+    specVerdicts: verdictFields,
+    specVerdictsBroken: { error: s.string() },
+    /** An agent's ask of a page's spec: steps to run or a query to read, what the page answered, or why not. */
+    specAsk: { spec: s.string(), kind: s.enum("step", "read"), program: s.string(), status: s.enum("asked", "answered", "failed"), answer: s.string(), error: s.string(), at: s.integer() },
+    /** The last headless run asked for: when, which spec, how it ended. */
+    specRun: resource(s.object({ at: s.integer(), spec: s.nullable(s.string()), code: s.nullable(s.integer()), output: s.string() }), { at: 0, spec: null, code: null, output: "" }),
+  },
+  effects: {
+    specs: source({
+      summary: "the specs as the disk has them: every system directory with a spec.ts, and .baba/spec.ts, with the newest change to each and under the systems",
+      mirror: "specFile",
+      every: 5_000,
+      retry: 2_000,
+      list: async (_, ctx) => {
+        await ctx.fs.mkdir(SYSTEMS_DIR);
+        const code = await newest(ctx.fs, SYSTEMS_DIR);
+        const out: { name: string; updated: string; code: string }[] = [];
+        // When a spec file or its saved scenarios last changed.
+        const updated = async (dir: string, files: { name: string; updated: string }[]) => {
+          const spec = files.find((f) => f.name === "spec.ts")!.updated;
+          const saved = files.some((f) => f.name === "scenarios") ? await newest(ctx.fs, `${dir}/scenarios`) : "";
+          return saved > spec ? saved : spec;
+        };
+        for (const d of await ctx.fs.list(SYSTEMS_DIR)) {
+          if (!d.dir) continue;
+          const files = await ctx.fs.list(d.path);
+          if (files.some((f) => f.name === "spec.ts")) out.push({ name: d.name, updated: await updated(d.path, files), code });
+        }
+        const root = await ctx.fs.list(".baba");
+        if (root.some((f) => f.name === "spec.ts")) out.push({ name: "baba", updated: await updated(".baba", root), code });
+        return out;
+      },
+      // Any change under .baba but voss.s own files and its packages: a spec, a saved scenario, a system appearing or going.
+      watch: async function* (_, ctx) { for await (const c of ctx.fs.watch(".baba")) if (!("path" in c) || !/^\.baba\/(\.voss|node_modules)\//.test(c.path)) yield { changed: true }; },
+    }),
+    specVerdictFile: source({
+      summary: "a spec's verdict file as the disk has it; the run writes it whole",
+      event: s.object({ spec: s.string(), text: s.nullable(s.string()) }),
+      args: s.object({ spec: s.string() }),
+      retry: 2_000,
+      list: async ({ spec }, ctx) => [{ spec, text: await ctx.fs.read(`${SPEC_DIR}/${spec}/verdicts.json`).catch(() => null) }],
+      watch: async function* ({ spec }, ctx) {
+        await ctx.fs.mkdir(`${SPEC_DIR}/${spec}`);
+        for await (const _c of ctx.fs.watch(`${SPEC_DIR}/${spec}`)) yield { spec, text: await ctx.fs.read(`${SPEC_DIR}/${spec}/verdicts.json`).catch(() => null) };
+      },
+    }),
+    specTest: effect({
+      summary: "a spec's scenarios, or every spec's, run headless under bun test in .baba: the verdicts are remade",
+      args: s.object({ spec: s.nullable(s.string()) }),
+      result: s.object({ code: s.integer(), output: s.string() }),
+      run: async ({ spec }, ctx) => {
+        const r = await ctx.exec.run("bun", ["test", "./spec.test.ts", ...(spec ? ["-t", `^${spec}: `] : [])], { cwd: ".baba" });
+        return { code: r.code, output: (r.stderr + r.stdout).trim().slice(-4_000) };
+      },
+    }),
+    specWrite: effect({
+      summary: "a scenario file written under a spec's scenarios directory",
+      args: s.object({ spec: s.string(), file: s.string(), source: s.string() }),
+      result: s.object({ path: s.string() }),
+      run: async ({ spec, file, source }, ctx) => { const dir = `${specDir(spec)}/scenarios`; const path = `${dir}/${file}`; await ctx.fs.mkdir(dir); await ctx.fs.write(path, source); return { path }; },
+    }),
+  },
+}, (maker, p) => [
+  // A spec the disk took away takes its verdicts with it.
+  p.step("sweep", (w) => { for (const r of w.query(removed(maker.specFile))) if (w.alive(r.entity)) w.despawn(r.entity); }),
+
+  // An ask no page answered in time fails, saying so; an answered one goes after a while.
+  p.step("expire", (w) => {
+    for (const r of w.query(maker.specAsk)) {
+      if (r.specAsk.status === "asked" && w.now - r.specAsk.at > ASK_PATIENCE) w.add(r.entity, maker.specAsk, { ...r.specAsk, status: "failed", error: `no page has the spec ${r.specAsk.spec} open in the Maker` });
+      else if (r.specAsk.status !== "asked" && w.now - r.specAsk.at > ASK_KEPT) w.despawn(r.entity);
+    }
+  }),
+
+  // The verdict file as it arrived, by spec: parsed onto the spec's entity.
+  p.step("land", (w) => {
+    for (const { event } of w.events(maker.specVerdictFile)) {
+      const e = w.find(maker.specFile, event.spec);
+      if (e === undefined) continue;
+      w.remove(e, maker.specVerdicts, maker.specVerdictsBroken);
+      if (event.text === null) continue;
+      try {
+        const d = JSON.parse(event.text) as { run?: string; at?: string; done?: boolean; scenarios?: Record<string, Record<string, unknown>> };
+        w.add(e, maker.specVerdicts, { run: String(d.run ?? ""), at: String(d.at ?? ""), done: !!d.done, scenarios: Object.entries(d.scenarios ?? {}).map(([name, v]) => ({ name, verdict: v.verdict, intent: v.intent, broke: v.broke, steps: v.steps, checks: v.checks, failed: v.failed, quiet: Array.isArray(v.quiet) ? v.quiet : [], at: v.at })) } as never);
+      } catch (err) { w.add(e, maker.specVerdictsBroken, { error: err instanceof Error ? err.message : String(err) }); }
+    }
+  }),
+
+  p.on(maker.specVerdictFile, { for: (w) => w.query(maker.specFile).map((r) => [r.entity, { spec: r.specFile.name }] as const) }),
+
+  p.on(maker.specTest, {
+    done: (w, _, r) => w.update(maker.specRun, (x) => ({ ...x, code: r.code, output: r.output })),
+    failed: (w, _, error) => w.update(maker.specRun, (x) => ({ ...x, code: -1, output: error })),
+  }),
+
+  p.on(maker.specWrite, { done: () => {}, failed: (w, _, error) => w.update(maker.specRun, (x) => ({ ...x, output: `save failed: ${error}` })) }),
+
+  p.action("spec-run", {
+    summary: "run a spec's scenarios headless, or every spec's when no spec is named; the verdicts land as the run writes them",
+    args: { spec: s.optional(s.string()) }, positional: ["spec"], result: s.void(),
+    run: (w, { spec }) => { w.set(maker.specRun, { at: w.now, spec: spec ?? null, code: null, output: "" }); w.run(maker.specTest, { spec: spec ?? null }); },
+  }),
+
+  p.action("spec-save", {
+    summary: "keep a scenario a person played, as a file under the spec's scenarios directory: `file` its name (NAME.ts), `source` the program",
+    args: { spec: s.string(), file: s.string(), source: s.string() }, result: s.void(),
+    run: (w, a) => {
+      if (w.find(maker.specFile, a.spec) === undefined) throw new Error(`no spec is named ${a.spec}`);
+      if (!/^[a-z][a-z0-9-]*\.ts$/.test(a.file)) throw new Error("a file is lowercase words joined by dashes, ending in .ts");
+      w.run(maker.specWrite, a);
+    },
+  }),
+
+  p.action("spec-step", {
+    summary: "act in the spec a person has open in the Maker: steps as `{fire, args}`, `{tick: ms}` or `{read, args}`, run in order by the page; follow the entity for what each answered and what changed",
+    args: { spec: s.string(), steps: s.array(s.unknown()) }, result: s.object({ entity: s.entity("specAsk") }),
+    run: (w, { spec, steps }) => {
+      if (w.find(maker.specFile, spec) === undefined) throw new Error(`no spec is named ${spec}`);
+      return { entity: w.spawn(maker.specAsk, { spec, kind: "step", program: JSON.stringify(steps), status: "asked", answer: "", error: "", at: w.now }) };
+    },
+  }),
+
+  p.action("spec-read", {
+    summary: "read the spec a person has open in the Maker: a query by name with its args, or `take` for what the person did, noted and expected; follow the entity for the answer",
+    args: { spec: s.string(), query: s.string(), args: s.optional(s.unknown()) }, result: s.object({ entity: s.entity("specAsk") }),
+    run: (w, a) => {
+      if (w.find(maker.specFile, a.spec) === undefined) throw new Error(`no spec is named ${a.spec}`);
+      return { entity: w.spawn(maker.specAsk, { spec: a.spec, kind: "read", program: JSON.stringify({ query: a.query, args: a.args ?? {} }), status: "asked", answer: "", error: "", at: w.now }) };
+    },
+  }),
+
+  p.action("spec-answer", {
+    summary: "the page's answer to an ask, from the spec it has open: what the page fires, not an agent",
+    args: { entity: s.entity("specAsk"), ok: s.boolean(), answer: s.unknown() }, result: s.void(),
+    run: (w, { entity, ok, answer }) => {
+      const a = w.get(entity, maker.specAsk);
+      if (!a) throw new Error(`no ask is #${entity}`);
+      if (a.status !== "asked") throw new Error(`ask #${entity} is already ${a.status}`);
+      w.add(entity, maker.specAsk, { ...a, status: ok ? "answered" : "failed", answer: ok ? JSON.stringify(answer) : "", error: ok ? "" : String(answer) });
+    },
+  }),
+
+  p.query("spec-asks", {
+    summary: "the asks a page with this spec open must answer, oldest first",
+    args: { spec: s.string() },
+    result: s.array(s.object({ entity: s.entity("specAsk"), kind: s.enum("step", "read"), program: s.string() })),
+    read: (w, { spec }) => w.query(maker.specAsk).filter((r) => r.specAsk.spec === spec && r.specAsk.status === "asked").sort((a, b) => a.specAsk.at - b.specAsk.at).map((r) => ({ entity: r.entity, kind: r.specAsk.kind, program: r.specAsk.program })),
+  }),
+
+  p.query("spec", {
+    summary: "every spec with its last verdicts: passed, failed, unknown per scenario, and whether the code or the spec changed since the run",
+    result: s.array(s.object({ name: s.string(), updated: s.string(), stale: s.boolean(), run: s.nullable(s.object({ at: s.string(), done: s.boolean(), passed: s.integer(), failed: s.integer(), unknown: s.integer() })), error: s.nullable(s.string()) })),
+    read: (w) => w.query(maker.specFile).map((r) => {
+      const v = w.get(r.entity, maker.specVerdicts), broken = w.get(r.entity, maker.specVerdictsBroken);
+      const count = (k: string) => v?.scenarios.filter((x) => x.verdict === k).length ?? 0;
+      return { name: r.specFile.name, updated: r.specFile.updated, stale: !!v && (v.at < r.specFile.updated || v.at < r.specFile.code), run: v ? { at: v.at, done: v.done, passed: count("passed"), failed: count("failed"), unknown: count("unknown") } : null, error: broken?.error ?? null };
+    }),
+  }),
+
+  p.query("spec-verdicts", {
+    summary: "one spec's verdicts in full: each scenario's verdict, where it broke, what failed, and the quiet effects its jobs asked of (what an adapter would have to play)",
+    args: { spec: s.string() },
+    result: s.object({ name: s.string(), stale: s.boolean(), verdicts: s.nullable(s.object(verdictFields)) }),
+    read: (w, { spec }) => {
+      const e = w.find(maker.specFile, spec);
+      if (e === undefined) throw new Error(`no spec is named ${spec}`);
+      const r = w.get(e, maker.specFile)!, v = w.get(e, maker.specVerdicts) ?? null;
+      return { name: spec, stale: !!v && (v.at < r.updated || v.at < r.code), verdicts: v };
+    },
+  }),
+]);