babavoss 0.0.0-stage → 0.0.2

package/src/shell/service.ts

@@ -0,0 +1,167 @@
+// The GUI kept running by the user service, at its configured address.
+import { join } from "node:path";
+import { homedir } from "node:os";
+import { browserUrl } from "./address.ts";
+import { mkdir, writeFile, unlink, stat } from "node:fs/promises";
+
+export const label = "org.babavoss.voss";
+
+/** How the service reaches the system: replaced in tests. */
+export interface Sys {
+  platform: NodeJS.Platform;
+  home: string;
+  uid: number;
+  /** Runs a program and answers its exit code and output. */
+  run(cmd: string[], opts?: { inherit?: boolean }): Promise<{ code: number; out: string }>;
+}
+
+export const realSys: Sys = {
+  platform: process.platform,
+  // Read when asked: a walled child has no home and never asks.
+  get home() { return process.env.HOME || homedir(); },
+  uid: process.getuid?.() ?? 0,
+  async run(cmd, opts = {}) {
+    const p = Bun.spawn(cmd, { stdout: opts.inherit ? "inherit" : "pipe", stderr: opts.inherit ? "inherit" : "pipe", stdin: opts.inherit ? "inherit" : "ignore" });
+    const out = opts.inherit ? "" : (await new Response(p.stdout).text()) + (await new Response(p.stderr).text());
+    return { code: await p.exited, out };
+  },
+};
+
+/** The command the service runs: Bun on the framework's entry. */
+export function program(): string[] {
+  return [process.execPath, join(import.meta.dir, "..", "..", "bin", "voss.ts")];
+}
+
+export const agentPath = (home: string) => join(home, "Library", "LaunchAgents", `${label}.plist`);
+export const unitPath = (home: string) => join(home, ".config", "systemd", "user", "voss.service");
+export const logPath = (home: string) => join(home, ".voss", "service.log");
+
+const xml = (s: string) => s.replace(/&/g, "&amp;").replace(/</g, "&lt;");
+
+/** The launchd agent: runs at login, restarts when it stops, logs under ~/.voss. */
+export function plist(o: { program: string[]; address: string; home: string }): string {
+  const args = [...o.program, "gui", o.address].map((a) => `    <string>${xml(a)}</string>`).join("\n");
+  return `<?xml version="1.0" encoding="UTF-8"?>
+<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
+<plist version="1.0"><dict>
+  <key>Label</key><string>${label}</string>
+  <key>ProgramArguments</key><array>
+${args}
+  </array>
+  <key>RunAtLoad</key><true/>
+  <key>KeepAlive</key><true/>
+  <key>WorkingDirectory</key><string>${xml(o.home)}</string>
+  <key>StandardOutPath</key><string>${xml(logPath(o.home))}</string>
+  <key>StandardErrorPath</key><string>${xml(logPath(o.home))}</string>
+  <key>EnvironmentVariables</key><dict>
+    <key>HOME</key><string>${xml(o.home)}</string>
+    <key>PATH</key><string>/usr/bin:/bin:/usr/sbin:/sbin</string>
+  </dict>
+</dict></plist>
+`;
+}
+
+/** The systemd user unit, the same three promises. */
+export function unit(o: { program: string[]; address: string; home: string }): string {
+  const exec = [...o.program, "gui", o.address].map((a) => (/[\s"]/.test(a) ? JSON.stringify(a) : a)).join(" ");
+  return `[Unit]
+Description=voss gui
+
+[Service]
+ExecStart=${exec}
+Restart=always
+RestartSec=2
+WorkingDirectory=${o.home}
+Environment=HOME=${o.home}
+Environment=PATH=/usr/bin:/bin
+
+[Install]
+WantedBy=default.target
+`;
+}
+
+export interface Status {
+  installed: boolean;
+  running: boolean;
+  pid: number | null;
+  address: string | null;
+  url: string | null;
+  file: string;
+  log: string;
+  program: string[];
+}
+
+async function exists(p: string) { try { await stat(p); return true; } catch { return false; } }
+
+/** Reads the address the installed agent or unit runs on. */
+async function installedAddress(sys: Sys): Promise<string | null> {
+  const file = sys.platform === "darwin" ? agentPath(sys.home) : unitPath(sys.home);
+  if (!(await exists(file))) return null;
+  const text = await Bun.file(file).text();
+  const m = text.match(/gui(?:<\/string>\s*<string>| )([^<\s]+)/);
+  return m?.[1] ?? null;
+}
+
+export async function status(sys: Sys = realSys): Promise<Status> {
+  const file = sys.platform === "darwin" ? agentPath(sys.home) : unitPath(sys.home);
+  const installed = await exists(file);
+  let running = false, pid: number | null = null;
+  if (installed && sys.platform === "darwin") {
+    const r = await sys.run(["launchctl", "print", `gui/${sys.uid}/${label}`]);
+    running = r.code === 0 && /state = running/.test(r.out);
+    pid = Number(r.out.match(/\bpid = (\d+)/)?.[1]) || null;
+  } else if (installed) {
+    const r = await sys.run(["systemctl", "--user", "show", "-p", "ActiveState,MainPID", "voss"]);
+    running = /ActiveState=active/.test(r.out);
+    pid = Number(r.out.match(/MainPID=(\d+)/)?.[1]) || null;
+  }
+  const address = await installedAddress(sys);
+  return { installed, running, pid, address, url: address ? browserUrl(address) : null, file, log: logPath(sys.home), program: program() };
+}
+
+export async function install(address: string, sys: Sys = realSys): Promise<Status> {
+  const prog = program();
+  if (sys.platform === "darwin") {
+    const file = agentPath(sys.home);
+    await mkdir(join(sys.home, "Library", "LaunchAgents"), { recursive: true });
+    await mkdir(join(sys.home, ".voss"), { recursive: true });
+    await writeFile(file, plist({ program: prog, address, home: sys.home }), { mode: 0o644 });
+    await sys.run(["launchctl", "bootout", `gui/${sys.uid}/${label}`]);
+    const r = await sys.run(["launchctl", "bootstrap", `gui/${sys.uid}`, file]);
+    if (r.code !== 0) throw new Error(`launchctl bootstrap failed: ${r.out.trim()}`);
+  } else if (sys.platform === "linux") {
+    const file = unitPath(sys.home);
+    await mkdir(join(sys.home, ".config", "systemd", "user"), { recursive: true });
+    await writeFile(file, unit({ program: prog, address, home: sys.home }));
+    await sys.run(["systemctl", "--user", "daemon-reload"]);
+    const r = await sys.run(["systemctl", "--user", "enable", "--now", "voss"]);
+    if (r.code !== 0) throw new Error(`systemctl enable failed: ${r.out.trim()}`);
+    // enable --now leaves an already-running unit on its old address.
+    const restarted = await sys.run(["systemctl", "--user", "restart", "voss"]);
+    if (restarted.code !== 0) throw new Error(`systemctl restart failed: ${restarted.out.trim()}`);
+  } else throw new Error(`no service on ${sys.platform}`);
+  return status(sys);
+}
+
+export async function remove(sys: Sys = realSys): Promise<Status> {
+  if (sys.platform === "darwin") {
+    await sys.run(["launchctl", "bootout", `gui/${sys.uid}/${label}`]);
+    await unlink(agentPath(sys.home)).catch(() => {});
+  } else if (sys.platform === "linux") {
+    await sys.run(["systemctl", "--user", "disable", "--now", "voss"]);
+    await unlink(unitPath(sys.home)).catch(() => {});
+    await sys.run(["systemctl", "--user", "daemon-reload"]);
+  }
+  return status(sys);
+}
+
+export async function restart(sys: Sys = realSys): Promise<Status> {
+  if (sys.platform === "darwin") {
+    const r = await sys.run(["launchctl", "kickstart", "-k", `gui/${sys.uid}/${label}`]);
+    if (r.code !== 0) throw new Error(`launchctl kickstart failed: ${r.out.trim()}`);
+  } else if (sys.platform === "linux") {
+    const r = await sys.run(["systemctl", "--user", "restart", "voss"]);
+    if (r.code !== 0) throw new Error(`systemctl restart failed: ${r.out.trim()}`);
+  }
+  return status(sys);
+}

package/src/shell/state.ts

@@ -0,0 +1,204 @@
+// The state at the shell: state, follow, run and raw, each over the client.
+// Each answers its exit status and prints through `out`; an error is thrown
+// for the shell to answer on stderr.
+import { readFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { callArgs, duration, words, UsageError } from "./args.ts";
+import { ShellError, errorLine } from "./codes.ts";
+import { stateOf, followEntity, watchQuery, untilOf, byKey, FOLLOW_MS, type Api, type Until } from "../door/core.ts";
+import type { Client } from "./client.ts";
+import { follow as whole } from "../ecs/snapshot.ts";
+import type { Manifest } from "../ecs/baba.ts";
+
+type O = Record<string, unknown>;
+
+export interface Io {
+  /** One answer, one line, within the budget; `name` names its file when it is over. */
+  out: (v: unknown, name?: string) => void;
+  /** A value within the budget, or its marker: for a value inside a line. */
+  fit: (v: unknown, name: string) => unknown;
+  /** Where answers over the budget go. */
+  outDir: string;
+  cwd: string;
+  stdin?: () => Promise<string>;
+  stdinTTY?: boolean;
+  /** Ctrl-C: calls the handler until the returned function unsubscribes. */
+  interrupt?: (handler: () => void) => () => void;
+}
+
+/** The shell's client as the core's Api: a fire coerces shell strings by the schema. */
+export const apiOf = (c: Client): Api => ({
+  describe: () => c.describe(),
+  fire: (n, args, key) => c.fire(n, args, { key, coerce: true }),
+  read: (n, args) => c.read(n, args),
+  state: (since, signal) => c.state(since, signal),
+});
+
+/** The exit status of a wait's outcome: 0 held, 3 time ran out (130 when interrupted), 4 gone. */
+const exitOfOutcome = (outcome: string, stopped = false) => outcome === "held" ? 0 : outcome === "gone" ? 4 : stopped ? 130 : 3;
+
+/** state [ENTITY | COMPONENT [VALUE] | RESOURCE] [--where k=v]… [--deep] [--limit N] [--all] */
+export async function state(c: Client, m: Manifest, args: string[], io: Io): Promise<number> {
+  const w = words(args, { positional: ["what", "value"], booleans: ["deep", "all"] });
+  for (const k of Object.keys(w)) if (!["what", "value", "deep", "all", "where", "limit"].includes(k)) throw new UsageError(`state takes --where, --deep, --limit and --all, not --${k}`);
+  const what = typeof w.what === "string" ? w.what : undefined;
+  const deep = w.deep === "true";
+  const api = apiOf(c);
+  if (what === undefined) {
+    const all = w.all === "true";
+    io.out((await stateOf(api, m, { all })).value, all ? "state" : undefined);
+    return 0;
+  }
+  if (/^\d+$/.test(what)) {
+    if (w.value !== undefined) throw new UsageError("state ENTITY takes nothing after it");
+    const r = await stateOf(api, m, { entity: Number(what), deep });
+    io.out(r.value, r.outcome === "gone" ? undefined : "state");
+    return exitOfOutcome(r.outcome);
+  }
+  if (typeof w.value === "string") { io.out((await stateOf(api, m, { component: what, key: w.value, deep })).value, "state"); return 0; }
+  const wheres = w.where === undefined ? [] : Array.isArray(w.where) ? w.where : [w.where];
+  const where = wheres.map((cond) => {
+    const eq = cond.indexOf("=");
+    if (eq < 0) throw new UsageError(`--where takes field=value, got ${cond}`);
+    return [cond.slice(0, eq), cond.slice(eq + 1)] as const;
+  });
+  const limit = w.limit === undefined ? 100 : Number(w.limit);
+  if (!Number.isInteger(limit) || limit < 0) throw new UsageError(`--limit takes a whole number, got ${String(w.limit)}`);
+  const r = await stateOf(api, m, { component: what, where, limit, deep, dir: io.outDir });
+  io.out(r.value, Array.isArray(r.value) ? `state-${what}` : "state");
+  return 0;
+}
+
+/**
+ * follow ENTITY | COMPONENT VALUE [--until COMPONENT | COMPONENT.field=value] [--for 30s] [--changes]
+ * follow QUERY [args…] --changed [--for 30s]
+ */
+export async function follow(c: Client, m: Manifest, args: string[], io: Io): Promise<number> {
+  const first = args.find((a) => !a.startsWith("--"));
+  if (first === undefined) throw new UsageError("follow takes an ENTITY, a COMPONENT and its key, or a QUERY with --changed");
+  const changed = args.includes("--changed");
+  if (!/^\d+$/.test(first) && (changed || (first in m.queries && !(first in m.components)))) return await watch(c, m, args, io);
+  const w = words(args, { positional: ["what", "value"], booleans: ["changes"] });
+  for (const k of Object.keys(w)) if (!["what", "value", "until", "for", "changes"].includes(k)) throw new UsageError(`follow takes --until, --for and --changes, not --${k}`);
+  if (Array.isArray(w.until) || Array.isArray(w.for)) throw new UsageError("--until and --for are given once");
+  const forMs = typeof w.for === "string" ? duration(w.for) : FOLLOW_MS;
+  const until: Until | null = typeof w.until === "string" ? untilOf(m, w.until) : null;
+  const api = apiOf(c);
+  let e: number;
+  if (/^\d+$/.test(String(w.what))) {
+    if (w.value !== undefined) throw new UsageError("follow ENTITY takes nothing after it but flags");
+    e = Number(w.what);
+  } else if (typeof w.value === "string") e = byKey(whole(null, await api.state(-1)), m, String(w.what), w.value);
+  else throw new UsageError(`follow takes an ENTITY, a COMPONENT and its key, or a QUERY with --changed; got ${String(w.what)}`);
+
+  let stopped = false;
+  const off = io.interrupt?.(() => { stopped = true; });
+  let printed: string | null = null;
+  const show = (row: unknown) => { io.out(row, "follow"); printed = JSON.stringify(row); };
+  try {
+    const r = await followEntity(api, e, { until, for: forMs, changes: w.changes === "true", onChange: show, stop: () => stopped });
+    if (r.outcome === "gone") io.out(r.value);
+    else if (JSON.stringify(r.value) !== printed) show(r.value);
+    return exitOfOutcome(r.outcome, stopped);
+  } finally { off?.(); }
+}
+
+/** follow QUERY [args…] --changed [--for]: the query's answer the first time it differs from the first read. */
+async function watch(c: Client, m: Manifest, args: string[], io: Io): Promise<number> {
+  let forMs = FOLLOW_MS;
+  const rest: string[] = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i]!;
+    if (a === "--changed") continue;
+    if (a === "--for") { const v = args[++i]; if (v === undefined || v.startsWith("--")) throw new UsageError("--for needs a value: 30, 30s or 2m"); forMs = duration(v); continue; }
+    if (a.startsWith("--for=")) { forMs = duration(a.slice(6)); continue; }
+    rest.push(a);
+  }
+  const [name, ...words] = rest;
+  const q = name === undefined ? undefined : m.queries[name];
+  if (!q || name === undefined) throw new ShellError("noquery", `no query ${name ?? ""}; queries: ${Object.keys(m.queries).join(", ")}`);
+  const { args: a } = await callArgs(words, q, io.stdin);
+  const r = await watchQuery(apiOf(c), name, a, { for: forMs });
+  io.out(r.value, name);
+  return exitOfOutcome(r.outcome);
+}
+
+/** "$N" or "$N.a.b" in a line's args: an earlier line's answer, or a field of it. */
+const REF = /^\$(\d+)((?:\.[^.]+)*)$/;
+
+/**
+ * run [FILE | LINE …]: lines of {"NAME": args, "key"?: K}, actions and
+ * queries, from stdin, a file, or the arguments; each sent in order, its
+ * answer on its own line as {"i":n,"ok":value} or {"i":n,"error":{…}}.
+ */
+export async function batch(c: Client, m: Manifest, args: string[], io: Io): Promise<number> {
+  let text: string;
+  if (args.length === 1 && !args[0]!.trimStart().startsWith("{")) {
+    try { text = await readFile(resolve(io.cwd, args[0]!), "utf8"); } catch { throw new UsageError(`run reads lines from ${args[0]}, and there is no such file`); }
+  } else if (args.length) text = args.join("\n");
+  else if (!io.stdin || io.stdinTTY) throw new UsageError("run takes lines of {\"NAME\": args}: from stdin, from a FILE, or as arguments");
+  else text = await io.stdin();
+  const lines = text.split("\n").map((l) => l.trim()).filter(Boolean);
+  const answers: ({ ok: true; value: unknown } | { ok: false })[] = [];
+  const refer = (v: unknown, i: number): unknown => {
+    if (typeof v === "string") {
+      const r = REF.exec(v);
+      if (!r) return v;
+      const n = Number(r[1]);
+      if (n >= i) throw new ShellError("args", `${v} refers to line ${n}, not an earlier one`);
+      const a = answers[n]!;
+      if (!a.ok) throw new ShellError("args", `${v} refers to line ${n}, which failed`);
+      let x: unknown = a.value;
+      for (const k of r[2] ? r[2].slice(1).split(".") : []) {
+        if (typeof x !== "object" || x === null || !(k in x)) throw new ShellError("args", `${v}: line ${n}'s answer has no ${k}`);
+        x = (x as O)[k];
+      }
+      return x;
+    }
+    if (Array.isArray(v)) return v.map((x) => refer(x, i));
+    if (typeof v === "object" && v !== null) return Object.fromEntries(Object.entries(v).map(([k, x]) => [k, refer(x, i)]));
+    return v;
+  };
+  let failed = false;
+  for (const [i, l] of lines.entries()) {
+    try {
+      let o: unknown;
+      try { o = JSON.parse(l); } catch { throw new ShellError("args", `line ${i} is not JSON`); }
+      if (typeof o !== "object" || o === null || Array.isArray(o)) throw new ShellError("args", `line ${i} is not {"NAME": args}`);
+      const { key, ...call } = o as O;
+      const names = Object.keys(call);
+      if (names.length !== 1) throw new ShellError("args", `line ${i}: one action or query by name, and "key" if any`);
+      if (key !== undefined && typeof key !== "string") throw new ShellError("args", `line ${i}: the key is a string`);
+      const name = names[0]!;
+      const a = refer(call[name] ?? {}, i);
+      let value: unknown;
+      if (name in m.actions) value = await c.fire(name, a, { key: key as string | undefined });
+      else if (name in m.queries) {
+        if (key !== undefined) throw new ShellError("args", `line ${i}: ${name} is a query, and a key is an action's`);
+        value = await c.read(name, a, {});
+      } else throw new ShellError("noaction", `line ${i}: no action or query ${name}`);
+      answers.push({ ok: true, value });
+      io.out({ i, ok: io.fit(value, `run-${i}`) });
+    } catch (err) {
+      failed = true;
+      answers.push({ ok: false });
+      await io.out({ i, error: errorLine(err) });
+    }
+  }
+  return failed ? 1 : 0;
+}
+
+/** raw spawn JSON | add E C [JSON] | remove E C … | despawn E | set R JSON */
+export async function rawOp(c: Client, args: string[], io: Io): Promise<number> {
+  const [op, ...rest] = args;
+  const parse = (s: string | undefined, what: string) => { if (s === undefined) return true; try { return JSON.parse(s); } catch { throw new UsageError(`${what} is not JSON: ${s}`); } };
+  const entity = (s: string | undefined) => { if (!s || !/^\d+$/.test(s)) throw new UsageError(`raw ${op} takes an ENTITY`); return Number(s); };
+  switch (op) {
+    case "spawn": { if (!rest[0]) throw new UsageError("raw spawn takes JSON: {\"component\": value, …}"); await io.out(await c.raw({ op: "spawn", parts: parse(rest[0], "the parts") as O })); return 0; }
+    case "add": { if (!rest[1]) throw new UsageError("raw add takes ENTITY COMPONENT [JSON]"); await io.out(await c.raw({ op: "add", entity: entity(rest[0]), component: rest[1], value: parse(rest[2], "the value") })); return 0; }
+    case "remove": { if (!rest[1]) throw new UsageError("raw remove takes ENTITY COMPONENT …"); await io.out(await c.raw({ op: "remove", entity: entity(rest[0]), components: rest.slice(1) })); return 0; }
+    case "despawn": { const e = entity(rest[0]); await c.raw({ op: "despawn", entity: e }); await io.out({ entity: e, despawned: true }); return 0; }
+    case "set": { if (!rest[1]) throw new UsageError("raw set takes RESOURCE JSON"); await io.out(await c.raw({ op: "set", resource: rest[0]!, value: parse(rest[1], "the value") })); return 0; }
+  }
+  throw new UsageError("raw: spawn, add, remove, despawn or set");
+}

package/src/spec/adapters.ts

@@ -0,0 +1,72 @@
+// Adapters: programs that play the outside for a simulated state. An effect
+// asks for a job; instead of the port, an adapter answers it, on the spec's
+// virtual clock, from a model that is part of the spec: seeded with it,
+// reset with it. Composed from primitives; synchronous by design, so a
+// headless run and a live one answer at the same moments.
+import type { Effect, Entity } from "../ecs/state.ts";
+
+/** What a request's job gets back. */
+export type Answer = { ok: true; value: unknown } | { ok: false; error: string };
+/** A request's answer, after a delay on the virtual clock. */
+export interface Reply { answer: Answer | null; after: number }
+
+/** What an adapter sees of the spec when it answers: the moment, the job's entity, and the adapter's own state, kept per spec. */
+export interface AdapterContext {
+  now: number;
+  entity: Entity | null;
+  /** This adapter's state in this spec: anything serializable; `model` keeps its state here. */
+  state: Map<string, unknown>;
+}
+
+/** An adapter for a request effect: the answer, and when. */
+export interface RequestAdapter { kind: "request"; reply(args: unknown, ctx: AdapterContext): Reply }
+/** An adapter for a source: its listing, and the events it yields, each at a moment after the job starts; `relist` lists again every so often. */
+export interface SourceAdapter { kind: "source"; listing(args: unknown, ctx: AdapterContext): unknown[]; events(args: unknown, ctx: AdapterContext): { at: number; event: unknown }[]; relist: number | null }
+export type Adapter = RequestAdapter | SourceAdapter;
+
+const request = (reply: RequestAdapter["reply"]): RequestAdapter => ({ kind: "request", reply });
+
+/** The job succeeds with `value`. */
+export const ok = (value: unknown = null): RequestAdapter => request(() => ({ answer: { ok: true, value }, after: 0 }));
+/** The job fails with `error`. */
+export const fail = (error: string): RequestAdapter => request(() => ({ answer: { ok: false, error }, after: 0 }));
+/** The job never answers: pending work, visible in the shell. */
+export const wait = (): RequestAdapter => request(() => ({ answer: null, after: 0 }));
+/** `inner`'s answer, `ms` later on the virtual clock. */
+export const after = (ms: number, inner: RequestAdapter): RequestAdapter => request((a, c) => { const r = inner.reply(a, c); return { ...r, after: r.after + ms }; });
+/** Successive jobs answer in turn; the last answers every job after. */
+export const sequence = (inner: RequestAdapter[]): RequestAdapter => {
+  if (!inner.length) throw new Error("sequence: at least one adapter");
+  return request((a, c) => { const n = (c.state.get("sequence") as number | undefined) ?? 0; c.state.set("sequence", n + 1); return inner[Math.min(n, inner.length - 1)]!.reply(a, c); });
+};
+/** `inner` when the args match `where` (every field deep-equal), else `otherwise`, else the default answer of nothing: wait. */
+export const match = (where: Record<string, unknown> | ((args: unknown) => boolean), inner: RequestAdapter, otherwise: RequestAdapter = wait()): RequestAdapter =>
+  request((a, c) => (typeof where === "function" ? where(a) : Object.entries(where).every(([k, v]) => JSON.stringify((a as Record<string, unknown>)?.[k]) === JSON.stringify(v))) ? inner.reply(a, c) : otherwise.reply(a, c));
+/** A stateful outside: `step` sees the state so far and the args, answers the next state and the reply. The state is the spec's: seeded, reset, shown. */
+export const model = <S>(initial: S, step: (state: S, args: unknown, ctx: AdapterContext) => [S, Answer | Reply]): RequestAdapter =>
+  request((a, c) => { const s = (c.state.has("model") ? c.state.get("model") : initial) as S; const [next, r] = step(s, a, c); c.state.set("model", next); return "answer" in (r as Reply) && "after" in (r as Reply) ? (r as Reply) : { answer: r as Answer, after: 0 }; });
+/** A custom reply. */
+export const custom = (reply: (args: unknown, ctx: AdapterContext) => Answer | Reply): RequestAdapter => request((a, c) => { const r = reply(a, c); return "after" in r ? r : { answer: r, after: 0 }; });
+/** A real job's answer, kept: the data was recorded from the running baba; the caller loaded it. */
+export const recorded = (answer: Answer): RequestAdapter => request(() => ({ answer, after: 0 }));
+
+/** A source's listing: the items as its `list` would answer, or a function of the args and the adapter's state. */
+export const listing = (items: unknown[] | ((args: unknown, ctx: AdapterContext) => unknown[]), o: { events?: { at: number; event: unknown }[]; relist?: number } = {}): SourceAdapter =>
+  ({ kind: "source", listing: typeof items === "function" ? items : () => items, events: () => o.events ?? [], relist: o.relist ?? null });
+/** A stream's events, each `at` ms after its job starts. */
+export const events = (evs: { at: number; event: unknown }[]): SourceAdapter => ({ kind: "source", listing: () => [], events: () => evs, relist: null });
+
+/**
+ * How a runtime finds an effect's adapter: by the effect itself. An effect
+ * the spec names no adapter for is quiet: its job is never started, so it
+ * waits, pending, like an outside that has not answered yet, which is what it
+ * is; a scenario may answer it by hand (`done`, `failed`, `list`, `watch`).
+ * Nothing is faked: a quiet mirror keeps what was listed by hand.
+ */
+export function adaptersOf(pairs: readonly (readonly [Effect, Adapter])[]): (effect: Effect) => Adapter | undefined {
+  const map = new Map<Effect, Adapter>(pairs.map(([e, a]) => [e, a] as const));
+  return (effect) => map.get(effect);
+}
+
+/** Whether a spec plays an effect, or leaves it quiet. */
+export const isPlayed = (pairs: readonly (readonly [Effect, Adapter])[], effect: Effect): boolean => pairs.some(([e]) => e === effect);

package/src/spec/diff.ts

@@ -0,0 +1,26 @@
+// What changed between two states, in object terms: an entity that appeared
+// with its parts, one that went, one whose parts moved; a resource that
+// moved. What a person reads after a step of a story.
+import type { Snapshot } from "../ecs/state.ts";
+
+export interface Change { kind: "added" | "removed" | "changed"; entity: number; /** The parts after; a part removed is null. */ parts: Record<string, unknown> }
+export interface ResourceChange { name: string; value: unknown }
+
+const same = (a: unknown, b: unknown) => JSON.stringify(a) === JSON.stringify(b);
+
+export function diffStates(before: Snapshot, after: Snapshot): { entities: Change[]; resources: ResourceChange[] } {
+  const entities: Change[] = [];
+  const b = before.entities as Record<string, Record<string, unknown> | null>, a = after.entities as Record<string, Record<string, unknown> | null>;
+  for (const [id, parts] of Object.entries(a)) {
+    const was = b[id];
+    if (!was) { entities.push({ kind: "added", entity: Number(id), parts: parts ?? {} }); continue; }
+    const moved: Record<string, unknown> = {};
+    for (const [n, v] of Object.entries(parts ?? {})) if (!(n in was) || !same(was[n], v)) moved[n] = v;
+    for (const n of Object.keys(was)) if (!(n in (parts ?? {}))) moved[n] = null;
+    if (Object.keys(moved).length) entities.push({ kind: "changed", entity: Number(id), parts: moved });
+  }
+  for (const id of Object.keys(b)) if (!(id in a)) entities.push({ kind: "removed", entity: Number(id), parts: {} });
+  const resources: ResourceChange[] = [];
+  for (const [n, v] of Object.entries(after.resources)) if (!same(before.resources[n], v)) resources.push({ name: n, value: v });
+  return { entities, resources };
+}

package/src/spec/files.ts

@@ -0,0 +1,17 @@
+// A spec from where it lives, browser-safe: the spec module beside a system
+// (or beside the entry, for the whole baba) and the scenarios saved in files
+// of their own beside it. The headless runner and the Maker's page both
+// assemble specs with it; how each finds the files is its own.
+import { isSpec, withScenarios, type Spec, type SpecScenario } from "./index.ts";
+
+/** One spec's files, relative to the baba's .baba directory: its spec, and its scenarios in files of their own. */
+export interface SpecFiles { dir: string; spec: string; scenarios: string[] }
+
+/** A spec from its spec module's default export and its scenario modules' default exports: checked, and named for where it lives. */
+export function assembleSpec(files: SpecFiles, spec: unknown, scenarios: readonly unknown[]): Spec<any, any> {
+  if (!isSpec(spec)) throw new Error(`${files.spec}: its default export is not a spec; export default spec(system, { … })`);
+  const expected = files.dir === "" ? null : files.dir.split("/").pop()!;
+  if (expected !== null && spec.name !== expected) throw new Error(`${files.spec}: the spec is named ${spec.name}; a system's spec is named like its directory, ${expected}`);
+  scenarios.forEach((sc, i) => { if (typeof sc !== "object" || sc === null || typeof (sc as SpecScenario).script !== "function") throw new Error(`${files.scenarios[i]}: its default export is not a scenario; export default scenario({ name, intent, script })`); });
+  return withScenarios(spec, scenarios as SpecScenario[]);
+}

package/src/spec/index.ts

@@ -0,0 +1,155 @@
+// babavoss/spec: a spec as a program. A spec is of a system (the system
+// and every system it reads) or of the whole baba; it has a setup that brings
+// an empty spec to its initial state, the adapters that play its outside,
+// and its scenarios. One program runs
+// in two places: headless under bun test, which writes the verdicts, and
+// live in the Maker, which draws every round and lets a person act.
+import { baba, isBaba, isSystem, nameOf, closureOf, SYSTEM, type System, type Baba } from "../ecs/baba.ts";
+import { testbed, type Testbed } from "../ecs/testbed.ts";
+import type { Effect } from "../ecs/state.ts";
+import type { Line, Words } from "../test/steps.ts";
+import { adaptersOf, isPlayed, type Adapter } from "./adapters.ts";
+import { execute, runNow, linesOf, type Progress, type RunResult } from "./run.ts";
+
+export { ok, fail, wait, after, sequence, match, model, custom, recorded, listing, events, adaptersOf, isPlayed, type Adapter, type Answer, type Reply, type AdapterContext, type RequestAdapter, type SourceAdapter } from "./adapters.ts";
+export { execute, runNow, linesOf, deepEqual, type Progress, type RunResult } from "./run.ts";
+export { asProgram, wordsOf, type Expectation, type Note, type TakeStep } from "./take.ts";
+export { diffStates, type Change, type ResourceChange } from "./diff.ts";
+export type { Line, Words } from "../test/steps.ts";
+export { assembleSpec, type SpecFiles } from "./files.ts";
+
+export type Params = Record<string, unknown>;
+
+/** A scenario of a spec: what must hold, as a script of steps and checks, from the spec's setup. */
+export interface SpecScenario<V = any, P extends Params = Params> {
+  name: string;
+  /** What should hold, as a person would say it. */
+  intent: string;
+  /** Knobs with defaults, on top of the spec's. */
+  params?: P;
+  script: (s: Words<Testbed<V>>, params: P) => Line<Testbed<V>>[];
+}
+
+/** How a spec is made, beside the system (or the baba) it is the spec of. */
+export interface SpecDef<V extends Baba = Baba, P extends Params = Params> {
+  /** The spec's name: the system's own, or "baba" for the whole baba, by default. */
+  name?: string;
+  /** What the spec says it is for. */
+  summary?: string;
+  /** Specs of the systems it reads: their adapters, setup and params come along, so their outside is played here too. */
+  also?: readonly Spec<any, any>[];
+  /** Rounds on their own, every so often, so a spec moves while a person watches; the baba's own tick by default. */
+  tick?: number | null;
+  /** The spec's first time and random seed. */
+  now?: number;
+  seed?: number;
+  /** Knobs with defaults: given to the setup and every scenario; the Maker lets a person nudge them. */
+  params?: P;
+  /** The script from an empty spec to the spec's initial state, after the setups of `also`. */
+  setup?: (s: Words<Testbed<V>>, params: P) => Line<Testbed<V>>[];
+  /** The outside: an adapter per effect, over those of `also`. An effect with none is quiet: a mirror lists nothing, a stream sends nothing, a request stays pending. */
+  adapters?: readonly (readonly [Effect, Adapter])[];
+  scenarios?: SpecScenario<V, P>[];
+}
+
+export interface Spec<V extends Baba = Baba, P extends Params = Params> {
+  kind: "spec";
+  name: string;
+  summary: string;
+  baba: V;
+  params: P;
+  tick: number | null;
+  now: number;
+  seed: number;
+  setup: (s: Words<Testbed<V>>, params: P) => Line<Testbed<V>>[];
+  adapters: readonly (readonly [Effect, Adapter])[];
+  scenarios: SpecScenario<V, P>[];
+}
+
+const NAME = /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/;
+
+type ReadsOf<S> = S extends { readonly [SYSTEM]: { readonly $types?: { readonly reads: infer R extends readonly System[] } } } ? R : readonly [];
+/** The spec of a system, as a baba: the system and the systems it reads. */
+export type SpecBaba<S extends System> = Baba<Closure<S>>;
+/** A system and what it reads, and what those read: the spec's systems, as types. Reads form no cycle, so this ends. */
+type Closure<S> = readonly [S extends System ? S : never, ...ClosureOf<ReadsOf<S>>];
+type ClosureOf<R> = R extends readonly [infer H, ...infer T] ? readonly [...Closure<H>, ...ClosureOf<T>] : readonly [];
+
+/**
+ * A spec: a definition, not a run. Of a system, beside it in its
+ * directory, `systems/pond/spec.ts`: the spec is the system and every system
+ * it reads; or of a whole baba, `.baba/spec.ts`. Pure: `.baba/spec.test.ts`
+ * proves it under bun test, the Maker runs it live.
+ */
+// The baba first: a system typed loosely is any, and would take a baba for itself.
+export function spec<V extends Baba, P extends Params = Params>(baba: V, def?: SpecDef<V, P>): Spec<V, P>;
+export function spec<const S extends System, P extends Params = Params>(system: S, def?: SpecDef<SpecBaba<S>, P>): Spec<SpecBaba<S>, P>;
+export function spec(target: System | Baba, def: SpecDef<any, any> = {}): Spec<any, any> {
+  const whole = isBaba(target);
+  if (!whole && !isSystem(target)) throw new Error("spec: the first argument is the system the spec is of, or the baba");
+  const name = def.name ?? (whole ? "baba" : nameOf(target));
+  if (!NAME.test(name)) throw new Error(`spec ${JSON.stringify(name)}: lowercase words joined by single dashes`);
+  const base = whole ? (target as Baba) : baba({ systems: closureOf([target as System]) });
+  const tick = def.tick === undefined ? base.tick : def.tick;
+  const v = tick === base.tick ? base : baba({ systems: base.systems, ...(tick !== null ? { tick } : {}), promptware: base.promptware, apps: base.apps });
+  const names = new Set<string>();
+  for (const sc of def.scenarios ?? []) { if (names.has(sc.name)) throw new Error(`spec ${name}: two scenarios are named ${JSON.stringify(sc.name)}`); names.add(sc.name); }
+  const also = def.also ?? [];
+  for (const o of also) if (!isSpec(o)) throw new Error(`spec ${name}: also takes specs`);
+  // The outside: also's adapters first, so the spec's own, for the same effect, win.
+  const adapters = [...also.flatMap((o) => o.adapters), ...(def.adapters ?? [])];
+  const setup = (w: Words<any>, params: Params) => [...also.flatMap((o) => o.setup(w, params)), ...(def.setup?.(w, params) ?? [])];
+  const params = Object.assign({}, ...also.map((o) => o.params), def.params ?? {});
+  return { kind: "spec", name, summary: def.summary ?? "", baba: v, params, tick, now: def.now ?? 0, seed: def.seed ?? 1, setup, adapters, scenarios: def.scenarios ?? [] };
+}
+
+/** A scenario in a file of its own, `systems/pond/scenarios/NAME.ts`: the spec of the system whose directory it is in takes it. Its testbed is untyped; a scenario written in the spec is typed by its spec. */
+export function scenario<P extends Params = Params>(def: SpecScenario<any, P>): SpecScenario<any, P> {
+  if (!def.name.trim()) throw new Error("scenario: a name");
+  return def;
+}
+
+/** The spec with scenarios added: those saved in files of their own beside the spec. */
+export function withScenarios<V extends Baba, P extends Params>(sp: Spec<V, P>, more: readonly SpecScenario<any, any>[]): Spec<V, P> {
+  const names = new Set(sp.scenarios.map((x) => x.name));
+  for (const sc of more) { if (names.has(sc.name)) throw new Error(`spec ${sp.name}: two scenarios are named ${JSON.stringify(sc.name)}`); names.add(sc.name); }
+  return { ...sp, scenarios: [...sp.scenarios, ...more] };
+}
+
+export const isSpec = (x: unknown): x is Spec => typeof x === "object" && x !== null && (x as { kind?: unknown }).kind === "spec";
+
+/** A fresh spec of the spec: its baba on a virtual clock, its adapters, seeded by its setup with `params` over the defaults. */
+export function seeded<V extends Baba, P extends Params>(sp: Spec<V, P>, o: { params?: Partial<P>; log?: (line: string) => void; each?: (p: Progress) => void } = {}): { t: Testbed<V>; params: P; setup: RunResult } {
+  const params = { ...sp.params, ...(o.params ?? {}) } as P;
+  const t = testbed(sp.baba, { now: sp.now, seed: sp.seed, adapters: adaptersOf(sp.adapters), ...(o.log ? { log: o.log } : {}) });
+  const setup = runNow(linesOf(sp.setup, params), t, o.each);
+  return { t, params, setup };
+}
+
+/** A scenario's steps for a seeded spec. */
+export function scenarioLines<V extends Baba, P extends Params>(sp: Spec<V, P>, sc: SpecScenario<V, P>, params: P): Line<Testbed<V>>[] {
+  return linesOf(sc.script, { ...params, ...(sc.params ?? {}) } as P);
+}
+
+/** The effects the spec left quiet that a job asked of during a run: what an adapter would have to play. For the agent. */
+export function quietOf<V extends Baba>(sp: Spec<V, any>, t: Testbed<V>): string[] {
+  const names = new Set<string>();
+  for (const j of t.jobs) if (!isPlayed(sp.adapters, j.effect)) names.add(j.effect.name);
+  return [...names].sort();
+}
+
+/** One scenario, headless, from the seed: the canonical run, with the quiet effects its jobs touched. */
+export function runScenario<V extends Baba, P extends Params>(sp: Spec<V, P>, sc: SpecScenario<V, P>, o: { params?: Partial<P>; each?: (p: Progress) => void } = {}): RunResult & { setup: RunResult; quiet: string[] } {
+  const { t, params, setup } = seeded(sp, o);
+  if (setup.verdict === "failed") return { ...setup, setup, verdict: "failed", quiet: quietOf(sp, t) };
+  const r = runNow(scenarioLines(sp, sc, params), t, o.each);
+  return { ...r, setup, quiet: quietOf(sp, t) };
+}
+
+/** A live run's driver: a generator the caller advances, ticking the testbed itself when told to. */
+export function liveRun<V extends Baba, P extends Params>(sp: Spec<V, P>, sc: SpecScenario<V, P>, t: Testbed<V>, params: P): Generator<Progress, RunResult, void> {
+  return execute(scenarioLines(sp, sc, params), t);
+}
+
+/** A baba's name for the verdict files: its own, or "baba". */
+export const babaOf = (x: unknown): x is Baba => isBaba(x);