babavoss 0.0.1 → 0.0.2

package/src/spec/run.ts

@@ -0,0 +1,97 @@
+// One executor for both runners. A program (a seed, a scenario) is a list of
+// steps; `execute` walks them against a testbed as a generator: every step
+// that needs no time runs at once and is reported; every step that moves
+// the clock is yielded, so the driver decides how: the headless runner ticks
+// at once, the live runner waits the scaled real time first. The state lands
+// the same either way, because the testbed's clock is the only clock.
+import type { Testbed } from "../ecs/testbed.ts";
+import type { Effect } from "../ecs/state.ts";
+import { resolveAnswers, spawnParts, words, type Line, type Words } from "../test/steps.ts";
+import type { StepRecord, CheckRecord } from "../test/records.ts";
+
+const TICK = 200;
+
+/** What a run reports as it goes: a step done (with its error, if it threw), a check made, or a moment to reach before going on. */
+export type Progress =
+  | { kind: "step"; rec: StepRecord; index: number }
+  | { kind: "check"; rec: CheckRecord; index: number }
+  | { kind: "tick"; to: number; index: number };
+
+export interface RunResult { verdict: "passed" | "failed"; steps: StepRecord[]; checks: CheckRecord[]; /** The first step that threw, or null: the run stopped there. */ broke: number | null }
+
+/** A program's steps, from its `steps` function, with `params`. */
+export function linesOf<T extends Testbed<any>, P extends Record<string, unknown>>(program: (s: Words<T>, params: P) => Line<T>[], params: P): Line<T>[] {
+  return program(words as Words<T>, params);
+}
+
+/**
+ * Executes `steps` against `t`. Yields a tick to the driver, which must
+ * `t.tick({ now: to })` (after waiting, if it waits) before resuming; a
+ * failed check is reported and the run goes on; a step that throws is
+ * reported and the run stops. Returns the result.
+ */
+export function* execute<T extends Testbed<any>>(steps: Line<T>[], t: T, o: { from?: number; answers?: unknown[] } = {}): Generator<Progress, RunResult, void> {
+  let now = o.from ?? t.now;
+  const answers: unknown[] = o.answers ?? [];
+  const done: StepRecord[] = [];
+  const checks: CheckRecord[] = [];
+  let broke: number | null = null;
+  const attempt = (i: number, rec: StepRecord, f: () => void): Progress => { try { f(); } catch (e) { rec.error = msg(e); broke = i; } done.push(rec); return { kind: "step", rec, index: i }; };
+  for (let i = 0; i < steps.length; i++) {
+    const step = steps[i]!;
+    switch (step.kind) {
+      case "given": {
+        const rec: StepRecord = { kind: "given", label: step.label, ...(typeof step.run === "function" ? { replay: false } : { args: step.run }) };
+        yield attempt(i, rec, () => { if (typeof step.run === "function") step.run(t); else spawnParts(t, step.run); });
+        break;
+      }
+      case "fire": {
+        const rec: StepRecord = { kind: "fire", label: step.name, args: step.args };
+        const at = answers.push(undefined) - 1;
+        yield attempt(i, rec, () => { rec.args = resolveAnswers(step.args, answers.slice(0, at)); rec.result = (t.fire as unknown as (n: string, a: unknown) => unknown)(step.name, rec.args); answers[at] = rec.result; });
+        break;
+      }
+      case "tick": { now = step.at ?? now + (step.after ?? TICK); yield { kind: "tick", to: now, index: i }; done.push({ kind: "tick", label: `+${fmt(now)}` }); break; }
+      case "ticks": { for (let k = 0; k < step.count; k++) { now += step.every; yield { kind: "tick", to: now, index: i }; done.push({ kind: "tick", label: `+${fmt(now)}` }); } break; }
+      case "done": yield attempt(i, { kind: "done", label: step.effect.name, args: step.where, result: step.result }, () => (t.done as (e: Effect, r: unknown, w?: unknown) => void)(step.effect, step.result, step.where)); break;
+      case "failed": yield attempt(i, { kind: "failed", label: step.effect.name, args: step.where, result: { error: step.error } }, () => (t.failed as (e: Effect, r: string, w?: unknown) => void)(step.effect, step.error, step.where)); break;
+      case "list": yield attempt(i, { kind: "list", label: step.effect.name, args: step.where, result: step.items }, () => (t.list as (e: Effect, i: unknown[], w?: unknown) => void)(step.effect, step.items, step.where)); break;
+      case "watch": yield attempt(i, { kind: "watch", label: step.effect.name, args: step.where, result: step.events }, () => (t.watch as (e: Effect, i: unknown[], w?: unknown) => void)(step.effect, step.events, step.where)); break;
+      case "check": {
+        const c: CheckRecord = { label: step.label, ok: false, compare: step.compare };
+        try {
+          const got = step.read(t);
+          if (step.compare) { c.got = got; c.want = step.want; c.ok = deepEqual(got, step.want); } else c.ok = got === true;
+        } catch (e) { c.error = msg(e); }
+        checks.push(c);
+        yield { kind: "check", rec: c, index: i };
+        break;
+      }
+    }
+    if (broke !== null) break;
+  }
+  return { verdict: broke !== null || checks.some((c) => !c.ok) ? "failed" : "passed", steps: done, checks, broke };
+}
+
+/** Runs a program to its end at once: the headless driver. */
+export function runNow<T extends Testbed<any>>(steps: Line<T>[], t: T, each?: (p: Progress) => void): RunResult {
+  const g = execute(steps, t);
+  for (;;) {
+    const r = g.next();
+    if (r.done) return r.value;
+    if (r.value.kind === "tick") t.tick({ now: r.value.to });
+    each?.(r.value);
+  }
+}
+
+const msg = (e: unknown) => (e instanceof Error ? e.message : String(e));
+const fmt = (ms: number) => (ms >= 1000 ? `${(ms / 1000).toFixed(ms % 1000 ? 1 : 0)} s` : `${ms} ms`);
+/** Deep equality by structure, browser-safe. */
+export function deepEqual(a: unknown, b: unknown): boolean {
+  if (a === b) return true;
+  if (typeof a !== typeof b || a === null || b === null || typeof a !== "object") return false;
+  if (Array.isArray(a) !== Array.isArray(b)) return false;
+  const ka = Object.keys(a as object), kb = Object.keys(b as object);
+  if (ka.length !== kb.length) return false;
+  return ka.every((k) => deepEqual((a as Record<string, unknown>)[k], (b as Record<string, unknown>)[k]));
+}

package/src/spec/take.ts

@@ -0,0 +1,54 @@
+// A take: what a person did in the Maker, as a scenario file of the spec.
+// The steps as played, in the program's words; the expectations they added
+// by pointing at an object, as checks on that entity's parts; the effects
+// they answered by hand, imported from their systems. Runs as written.
+import type { StepRecord } from "../test/records.ts";
+
+/** One step of a take: the record, and for an answered job the effect's system, so the file can import it. */
+export interface TakeStep { rec: StepRecord; owner?: string }
+/** An expectation added in play: the entity as it was, by its parts, at this point of the take. */
+export interface Expectation { at: number; label: string; entity: number; parts: Record<string, unknown> }
+/** A note added in play: the person's words on an entity, or on the spec, at this point of the take. */
+export interface Note { at: number; entity: number | null; text: string }
+
+const json = (v: unknown) => JSON.stringify(v);
+
+/** A step in plain words, for a person reading the take. */
+export function wordsOf(rec: StepRecord): string {
+  switch (rec.kind) {
+    case "fire": return `${rec.label} ${Object.keys((rec.args as object) ?? {}).length ? json(rec.args) : ""}${rec.error ? ` → failed: ${rec.error}` : ""}`.trim();
+    case "tick": return rec.label === "a round" ? "a round" : `time passes ${rec.label}`;
+    case "done": return `${rec.label} answered ${json(rec.result)}`;
+    case "failed": return `${rec.label} failed: ${json((rec.result as { error?: unknown })?.error ?? "")}`;
+    case "given": return `given ${rec.label}`;
+    case "list": return `${rec.label} listed ${json(rec.result)}`;
+    case "watch": return `${rec.label} sent ${json(rec.result)}`;
+  }
+}
+
+/** The take as a scenario file for `spec`, saved in its scenarios directory beside its spec, with `systems` the import path of each system by name, relative to that directory. */
+export function asProgram(o: { spec: string; name: string; intent: string; steps: TakeStep[]; expectations: Expectation[]; notes?: Note[]; systems: Record<string, string> }): string {
+  const owners = new Set<string>();
+  const lines: string[] = [];
+  const expectAt = (i: number) => {
+    for (const n of (o.notes ?? []).filter((n) => n.at === i)) lines.push(`    // ${n.entity !== null ? `on #${n.entity}: ` : ""}${n.text.replace(/\n/g, " ")}`);
+    for (const e of o.expectations.filter((e) => e.at === i)) lines.push(`    check(${json(e.label)}, (t) => t.w.of(${e.entity}), ${json(e.parts)}),`);
+  };
+  o.steps.forEach(({ rec, owner }, i) => {
+    expectAt(i);
+    const where = rec.args && typeof rec.args === "object" && "entity" in (rec.args as object) ? `, { entity: ${json((rec.args as { entity: unknown }).entity)} }` : "";
+    const ref = owner ? (owners.add(owner), `${ident(owner)}.${rec.label}`) : `/* ${rec.label} */ undefined as never`;
+    if (rec.kind === "fire") lines.push(`    fire(${json(rec.label)}, ${json(rec.args)}),`);
+    else if (rec.kind === "tick") lines.push(`    tick(${rec.args !== undefined ? json(rec.args) : ""}),`);
+    else if (rec.kind === "done") lines.push(`    done(${ref}, ${json(rec.result)}${where}),`);
+    else if (rec.kind === "failed") lines.push(`    failed(${ref}, ${json((rec.result as { error?: unknown })?.error ?? "")}${where}),`);
+    else if (rec.kind === "list") lines.push(`    list(${ref}, ${json(rec.result)}${where}),`);
+    else if (rec.kind === "watch") lines.push(`    watch(${ref}, ${json(rec.result)}${where}),`);
+    else if (rec.kind === "given" && rec.args !== undefined) lines.push(`    given(${json(rec.label)}, ${json(rec.args)}),`);
+  });
+  expectAt(o.steps.length);
+  const imports = [...owners].map((n) => `import ${ident(n)} from ${json(o.systems[n] ?? `../../${n}/index.ts`)};`);
+  return [`import { scenario } from "babavoss/spec";`, ...imports, "", `// A take from the Maker on the spec ${o.spec}: the steps as played, the expectations as pointed at.`, "export default scenario({", `  name: ${json(o.name)},`, `  intent: ${json(o.intent)},`, "  script: ({ fire, tick, done, failed, list, watch, given, check }) => [", ...lines, "  ],", "});", ""].join("\n");
+}
+
+const ident = (name: string) => name.replace(/-([a-z0-9])/g, (_, c: string) => c.toUpperCase()).replace(/^[^a-zA-Z_$]/, "_");

package/src/test/index.ts

@@ -0,0 +1,8 @@
+// babavoss/test: the testbed, and the runner that proves a baba's specs
+// under bun test. `.baba/spec.test.ts` is one call: `await proveAll(import.meta.dir)`.
+export { testbed, type Testbed } from "../ecs/testbed.ts";
+export { spawnParts, answer, resolveAnswers, type Line, type Words, type ScenarioDef } from "./steps.ts";
+export { vossDir } from "./voss-dir.ts";
+export { prove, proveAll, verdictsDir, type Verdicts, type ScenarioVerdict } from "./prove.ts";
+export { specFiles, specsIn, type SpecFiles } from "./specs.ts";
+export type { StepRecord, CheckRecord } from "./records.ts";

package/src/test/prove.ts

@@ -0,0 +1,56 @@
+// The headless runner of specs: under bun test, every scenario of a
+// spec runs from its setup, and the verdicts land under
+// .baba/.voss/spec/SPEC/verdicts.json, where the maker system shows them. A
+// run writes its record first, so a scenario missing from a finished run is
+// unknown, never green; one file per spec, written whole.
+import { test } from "bun:test";
+import { mkdir } from "node:fs/promises";
+import { dirname, join } from "node:path";
+import { vossDir } from "./voss-dir.ts";
+import { runScenario, type Spec } from "../spec/index.ts";
+import type { CheckRecord, StepRecord } from "./records.ts";
+import { specsIn } from "./specs.ts";
+
+export interface ScenarioVerdict { verdict: "passed" | "failed" | "unknown"; intent: string; /** The step that threw, by index, or null. */ broke: number | null; steps: number; checks: number; failed: string[]; /** The effects the spec left quiet that jobs asked of: what an adapter would have to play. */ quiet: string[]; at: string }
+export interface Verdicts { spec: string; run: string; at: string; done: boolean; scenarios: Record<string, ScenarioVerdict> }
+
+/** Where a spec's verdicts go: under the project's .baba/.voss. */
+export const verdictsDir = (from?: string) => join(vossDir(from), "spec");
+
+/** Registers every scenario of `sp` with bun test and keeps the spec's verdicts current as they run, under `state` (the project's .baba/.voss/spec by default). */
+export function prove(sp: Spec, state = verdictsDir()): void {
+  const file = join(state, sp.name, "verdicts.json");
+  const run = `${Date.now().toString(36)}-${Math.random().toString(36).slice(2, 6)}`;
+  const kept: Verdicts = { spec: sp.name, run, at: new Date().toISOString(), done: false, scenarios: Object.fromEntries(sp.scenarios.map((sc) => [sc.name, { verdict: "unknown", intent: sc.intent, broke: null, steps: 0, checks: 0, failed: [], quiet: [], at: "" }])) };
+  let wrote: Promise<void> = Promise.resolve();
+  const write = () => { wrote = wrote.then(async () => { await mkdir(dirname(file), { recursive: true }); await Bun.write(file, JSON.stringify(kept, null, 2)); }); return wrote; };
+  let left = sp.scenarios.length;
+  if (left === 0) { void write(); return; }
+  for (const sc of sp.scenarios) {
+    test(`${sp.name}: ${sc.name}`, async () => {
+      if (!kept.at) kept.at = new Date().toISOString();
+      const r = runScenario(sp, sc);
+      const failed = [...r.setup.steps, ...r.steps].filter((s) => s.error).map((s) => `${s.kind} ${s.label}: ${s.error}`).concat(r.checks.filter((c) => !c.ok).map(describe));
+      kept.scenarios[sc.name] = { verdict: r.verdict, intent: sc.intent, broke: r.broke, steps: r.steps.length, checks: r.checks.length, failed, quiet: r.quiet, at: new Date().toISOString() };
+      if (--left === 0) kept.done = true;
+      await write();
+      if (r.verdict === "failed") throw new Error(`${sc.intent}\n  ${failed.join("\n  ")}${r.quiet.length ? `\n  quiet: ${r.quiet.join(", ")} (no adapter plays them)` : ""}`);
+    });
+  }
+}
+
+/**
+ * Every spec of the baba at `baba`, its .baba directory: each system's
+ * `systems/NAME/spec.ts`, the whole baba's `spec.ts`, and the scenarios saved
+ * beside them. The one call in `.baba/spec.test.ts`:
+ * `await proveAll(import.meta.dir)`.
+ */
+export async function proveAll(baba: string): Promise<void> {
+  const specs = await specsIn(baba);
+  const names = new Set<string>();
+  for (const sp of specs) { if (names.has(sp.name)) throw new Error(`two specs are named ${sp.name}`); names.add(sp.name); }
+  for (const sp of specs) prove(sp, join(baba, ".voss", "spec"));
+}
+
+const describe = (c: CheckRecord) => `${c.label}${c.error ? ` (${c.error})` : c.compare ? `: got ${JSON.stringify(c.got)}, want ${JSON.stringify(c.want)}` : ""}`;
+export type { StepRecord };

package/src/test/records.ts

@@ -0,0 +1,23 @@
+// What a run of a script records, line by line: each line done (with its
+// error, if it threw) and each check made. Pure types, browser-safe: the
+// headless runner keeps them for the verdicts, the Maker shows them live.
+
+export interface StepRecord {
+  kind: "given" | "fire" | "tick" | "done" | "failed" | "list" | "watch";
+  label: string;
+  args?: unknown;
+  result?: unknown;
+  error?: string;
+  /** False for a given done by a function: the page cannot replay it. */
+  replay?: false;
+}
+
+export interface CheckRecord {
+  label: string;
+  ok: boolean;
+  /** Whether `got` was compared to `want`, or taken as a truth. */
+  compare?: boolean;
+  got?: unknown;
+  want?: unknown;
+  error?: string;
+}

package/src/test/specs.ts

@@ -0,0 +1,56 @@
+// The specs of a baba, found where they live: beside each system,
+// `systems/NAME/spec.ts`, and for the whole baba `spec.ts` beside the entry.
+// A scenario saved in a file of its own, `systems/NAME/scenarios/*.ts` (or
+// `scenarios/*.ts` for the whole baba), joins the spec of the spec beside
+// it. The views bundler lists the same files for the Maker's page, as the
+// module "babavoss:specs".
+import { existsSync, readdirSync, statSync } from "node:fs";
+import { join } from "node:path";
+import { assembleSpec, type SpecFiles } from "../spec/files.ts";
+import type { Spec } from "../spec/index.ts";
+
+export type { SpecFiles } from "../spec/files.ts";
+
+const isDir = (p: string) => { try { return statSync(p).isDirectory(); } catch { return false; } };
+const scenarioFiles = (baba: string, dir: string) => {
+  const d = join(baba, dir, "scenarios");
+  return isDir(d) ? readdirSync(d).filter((f) => /\.tsx?$/.test(f) && !/\.test\.tsx?$/.test(f)).sort().map((f) => join(dir, "scenarios", f)) : [];
+};
+
+/** The files of every spec of the baba at `baba` (its .baba directory): the systems' in name order, then the whole baba's. */
+export function specFiles(baba: string): SpecFiles[] {
+  const out: SpecFiles[] = [];
+  const systems = join(baba, "systems");
+  if (isDir(systems)) {
+    for (const name of readdirSync(systems).sort()) {
+      const dir = join("systems", name);
+      if (existsSync(join(baba, dir, "spec.ts"))) out.push({ dir, spec: join(dir, "spec.ts"), scenarios: scenarioFiles(baba, dir) });
+    }
+  }
+  if (existsSync(join(baba, "spec.ts"))) out.push({ dir: "", spec: "spec.ts", scenarios: scenarioFiles(baba, "") });
+  return out;
+}
+
+/** Every spec of the baba at `baba`, imported. */
+export async function specsIn(baba: string): Promise<Spec<any, any>[]> {
+  const out: Spec<any, any>[] = [];
+  for (const f of specFiles(baba)) {
+    const spec = (await import(join(baba, f.spec))).default;
+    const scenarios = await Promise.all(f.scenarios.map(async (s) => (await import(join(baba, s))).default));
+    out.push(assembleSpec(f, spec, scenarios));
+  }
+  return out;
+}
+
+/** The source of "babavoss:specs" for the baba at `baba`: every spec, imported and assembled, as the default export. */
+export function specsModule(baba: string): string {
+  const files = specFiles(baba);
+  const imports: string[] = [`import { assembleSpec } from "babavoss/spec";`];
+  const specs: string[] = [];
+  files.forEach((f, i) => {
+    imports.push(`import w${i} from ${JSON.stringify(join(baba, f.spec))};`);
+    f.scenarios.forEach((s, j) => imports.push(`import w${i}s${j} from ${JSON.stringify(join(baba, s))};`));
+    specs.push(`assembleSpec(${JSON.stringify(f)}, w${i}, [${f.scenarios.map((_, j) => `w${i}s${j}`).join(", ")}])`);
+  });
+  return `${imports.join("\n")}\nexport default [${specs.join(", ")}];\n`;
+}

package/src/test/steps.ts

@@ -0,0 +1,100 @@
+// The words of a program, browser-safe: the step types, the words that make
+// them, the answer references, and a given from parts. A scenario file and
+// the page's live runner both speak them; the bun runner is elsewhere.
+import type { Testbed } from "../ecs/testbed.ts";
+import type { Effect } from "../ecs/state.ts";
+
+/** One line of a script: a given, a fire, a tick, an answer from the outside, or a check. */
+export type Line<T> =
+  | { kind: "given"; label: string; run: ((t: T) => void) | Record<string, unknown> }
+  | { kind: "fire"; name: string; args: unknown }
+  | { kind: "tick"; after?: number; at?: number }
+  | { kind: "ticks"; count: number; every: number }
+  | { kind: "done"; effect: Effect; result: unknown; where?: unknown }
+  | { kind: "failed"; effect: Effect; error: string; where?: unknown }
+  | { kind: "list"; effect: Effect; items: unknown[]; where?: unknown }
+  | { kind: "watch"; effect: Effect; events: unknown[]; where?: unknown }
+  | { kind: "check"; label: string; read: (t: T) => unknown; want?: unknown; compare: boolean };
+
+/** The words of a scenario, typed by the system under test. */
+export interface Words<T extends Testbed<any>> {
+  /** A precondition the contract cannot express. Parts by component name spawn one entity carrying them: the form the page can replay. A function does anything, and cannot be replayed. */
+  given(label: string, run: ((t: T) => void) | Record<string, unknown>): Line<T>;
+  /** An action, run now as its system. Its args may name an earlier fire's answer: \`answer(0, "entity")\`, or the string \`"$0.entity"\`, the first fire's entity. */
+  fire(...a: Parameters<T["fire"]>): Line<T>;
+  /** An earlier fire's answer, or a field of it by a dotted path, to put in a later fire's args: \`fire("note-remove", { note: answer(0, "entity") })\`. Fires count from 0, in the order they are listed. */
+  answer(index: number, path?: string): any;
+  /** One round, `after` ms later (200 by default), or `at` a time. */
+  tick(o?: { after?: number; at?: number }): Line<T>;
+  /** `count` rounds, `every` ms apart. */
+  ticks(count: number, every: number): Line<T>;
+  /** An effect's job answered, landing at the next tick. */
+  done(...a: Parameters<T["done"]>): Line<T>;
+  failed(...a: Parameters<T["failed"]>): Line<T>;
+  /** A source's listing, or the events its watch yields, landing at the next tick. */
+  list(...a: Parameters<T["list"]>): Line<T>;
+  watch(...a: Parameters<T["watch"]>): Line<T>;
+  /** A claim about the state now: with `want`, what `read` gives must deep-equal it; without, it must be true. */
+  check(label: string, read: (t: T) => unknown, ...want: [unknown?]): Line<T>;
+}
+
+export interface ScenarioDef<T extends Testbed<any>, P extends Record<string, unknown> = Record<string, never>> {
+  name: string;
+  /** What should hold, as a person would say it: the title of the proof. */
+  intent: string;
+  /** The time of the first round. */
+  now?: number;
+  /** The seed of `w.random()`; 1 by default, so the run is the same every time. */
+  seed?: number;
+  /** Knobs with their defaults: the test runs at the defaults, the page lets a person nudge them. */
+  params?: P;
+  script: (s: Words<T>, params: P) => Line<T>[];
+}
+
+export const words: Words<any> = {
+  given: (label, run) => ({ kind: "given", label, run }),
+  fire: (name: string, args?: unknown) => ({ kind: "fire", name, args: args ?? {} }),
+  tick: (o = {}) => ({ kind: "tick", ...o }),
+  ticks: (count, every) => ({ kind: "ticks", count, every }),
+  done: (effect: Effect, result: unknown, where?: unknown) => ({ kind: "done", effect, result, where }),
+  failed: (effect: Effect, error: string, where?: unknown) => ({ kind: "failed", effect, error, where }),
+  list: (effect: Effect, items: unknown[], where?: unknown) => ({ kind: "list", effect, items, where }),
+  watch: (effect: Effect, events: unknown[], where?: unknown) => ({ kind: "watch", effect, events, where }),
+  check: (label, read, ...want) => ({ kind: "check", label, read, want: want[0], compare: want.length > 0 }),
+  answer: (index: number, path?: string) => `$${index}${path ? `.${path}` : ""}`,
+};
+
+/** An earlier fire's answer, for a later fire's args, outside a step list: the same as the \`answer\` a step list destructures. */
+export const answer = (index: number, path?: string): any => words.answer(index, path);
+
+const REF = /^\$(\d+)((?:\.[A-Za-z0-9_]+)*)$/;
+/** Args with every "$N.path" string replaced by the Nth fire's answer at that path; an answer that is not there is an error, as the CLI's run says. */
+export function resolveAnswers(args: unknown, answers: readonly unknown[]): unknown {
+  if (typeof args === "string") {
+    const m = REF.exec(args);
+    if (!m) return args;
+    const i = Number(m[1]);
+    if (i >= answers.length) throw new Error(`${args}: fire ${i} has not run yet; ${answers.length} fire${answers.length === 1 ? " has" : "s have"}`);
+    let v: unknown = answers[i];
+    for (const key of m[2]!.split(".").filter(Boolean)) {
+      if (v === null || typeof v !== "object" || !(key in (v as object))) throw new Error(`${args}: fire ${i}'s answer has no ${key}`);
+      v = (v as Record<string, unknown>)[key];
+    }
+    return v;
+  }
+  if (Array.isArray(args)) return args.map((a) => resolveAnswers(a, answers));
+  if (args && typeof args === "object") return Object.fromEntries(Object.entries(args).map(([k, v]) => [k, resolveAnswers(v, answers)]));
+  return args;
+}
+
+
+/** A `given` from parts by component name: one entity with those parts, checked; `true` for a tag. */
+export function spawnParts(t: Testbed<any>, parts: Record<string, unknown>): number {
+  const e = t.w.spawn();
+  for (const [name, value] of Object.entries(parts)) {
+    const d = t.w.declaration(name);
+    if (!d || d.kind !== "component") throw new Error(`no component ${name}`);
+    if (value === true) t.w.add(e, d as never); else t.w.add(e, d as never, value as never);
+  }
+  return e;
+}

package/src/test/voss-dir.ts

@@ -0,0 +1,17 @@
+// Where a project's spec verdicts are kept: its .baba/.voss, found from the
+// working directory.
+import { existsSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
+
+/** The project's .baba/.voss, found from the working directory; VOSS_DIR overrides. Where spec verdicts go. */
+export function vossDir(from = process.cwd()): string {
+  if (process.env.VOSS_DIR) return resolve(process.env.VOSS_DIR);
+  let dir = resolve(from);
+  for (;;) {
+    if (dir.endsWith(`${"/"}.baba`) || existsSync(join(dir, "package.json")) && existsSync(join(dir, "systems"))) return join(dir, ".voss");
+    if (existsSync(join(dir, ".baba"))) return join(dir, ".baba", ".voss");
+    const up = dirname(dir);
+    if (up === dir) return join(resolve(from), ".baba", ".voss");
+    dir = up;
+  }
+}

package/src/transport/messages.ts

@@ -0,0 +1,110 @@
+// The message schema: what crosses between the kernel and a runtime, and
+// between the kernel and a builder, in either direction, over any
+// transport. One version, said in `hello`. Every transport carries these
+// objects as they are (structured clone).
+import type { Manifest } from "../ecs/baba.ts";
+import type { Snapshot } from "../ecs/state.ts";
+import type { StateAnswer } from "../ecs/snapshot.ts";
+import type { Raw } from "../ecs/runtime.ts";
+import type { Project } from "../baba/project.ts";
+import type { Interest } from "../server/protocol.ts";
+import type { BuildOutput, ViewSpec } from "../build/builder.ts";
+import type { ViewFailure } from "../build/failure.ts";
+
+export const PROTOCOL = 6;
+
+/** The first message each side sends. A side that cannot serve the other's version answers `failed`. */
+export interface Hello { type: "hello"; protocol: number; role: "kernel" | "runtime" | "server" | "builder" }
+
+// ---- kernel → runtime --------------------------------------------------
+
+/** A baba to run: its code as one bundle of text, its environment, and the state to continue from. */
+export interface Load {
+  type: "load";
+  project: { name: string; dir: string; baba: string };
+  /** The bundle: the baba's entry, the framework and the harness, one module that serves itself. */
+  code: string;
+  /** The environment effects may read: composed by the kernel from .env and .env.local. */
+  env: Record<string, string>;
+  snapshot: Snapshot | null;
+  prepare?: boolean;
+}
+
+/** Fire an action: it runs at the start of the next round, as its system; the answer is what it returned. A `key` the state remembers answers the same again, without running. */
+export interface Fire { type: "fire"; id: number; name: string; args: unknown; coerce?: boolean; key?: string }
+/** Read a query, between rounds. */
+export interface Read { type: "read"; id: number; name: string; args: unknown; coerce?: boolean }
+/** The state since round `since`, once a round past it has run or a wait is over: a delta, or the whole; its secrets redacted. With `frame`, as bytes laid out by the model. */
+export interface StateAsk { type: "state"; id: number; since: number; frame?: true; /** false: answer the state as it is, without waiting for a round past `since`. */ wait?: boolean; /** With `frame`: only these parts of the state, as they are now, for a window that began to ask for them. */ parts?: Interest }
+/** A write at layer zero, applied at the next round. */
+export interface RawOp { type: "raw"; id: number; raw: Raw }
+/** The generation is done: cancel every job, answer `retired` with the state. The sender closes after. */
+export interface Retire { type: "retire"; /** Reload may stop only between nonrepeatable jobs. */ unlessBusy?: boolean }
+
+/**
+ * The answer to a service request the runtime made. A streaming operation
+ * answers many times: `more` with a batch of `values`, then one last answer
+ * without `more` that ends it, ok or not.
+ */
+export interface Serviced { type: "serviced"; id: number; ok: boolean; value?: unknown; code?: string; error?: string; more?: true; values?: unknown[] }
+
+export interface Activate { type: "activate"; snapshot: Snapshot | null }
+export interface Credit { type: "credit"; id: number }
+export type ToRuntime = Activate | Hello | Load | Fire | Read | StateAsk | RawOp | Retire | Serviced;
+
+// ---- runtime → kernel --------------------------------------------------
+
+/** The baba loaded: its contract, and the state it starts from. */
+export interface Loaded { type: "loaded"; manifest: Manifest; snapshot: Snapshot }
+/** The baba did not load; the last generation, if any, keeps serving. */
+export interface Failed { type: "failed"; error: string }
+
+export type ResultCode = "noaction" | "noquery" | "args" | "result" | "failed" | "entity" | "name" | "owner" | "down";
+/** The end of a fire, read, state or raw: a value, or a failure with a code the shell and the API understand. */
+export type Result =
+  | { type: "result"; id: number; ok: true; value: unknown; /** The round the call ran in, for a fire or a raw write. */ round?: number }
+  | { type: "result"; id: number; ok: false; code: ResultCode; error: string };
+
+/** A round ended: what it changed since the one before, or the whole, for the kernel to keep; and the same redacted, as the frame every window gets. */
+export interface Round { type: "round"; state: StateAnswer; frame: Uint8Array }
+/** Every job cancelled; `errors` says what went wrong; the state as it was. */
+export interface Retired { type: "retired"; errors: string[]; snapshot: Snapshot; /** The generation remains active; retry retirement later. */ busy?: boolean }
+
+/** A request for something outside the runtime, made by a job: the kernel serves it and answers `serviced`. */
+export interface ServiceRequest {
+  type: "service";
+  id: number;
+  system: string;
+  effect: string;
+  job: number;
+  entity?: number | null;
+  service: ServiceName;
+  op: string;
+  args: unknown;
+}
+
+export type ServiceName = "fs" | "http" | "exec" | "secrets";
+
+/** The operations that answer many times: known to both sides, so the bridge hands back an iterator and the kernel pumps. */
+export const STREAMS: Record<ServiceName, readonly string[]> = { fs: ["watch"], http: [], exec: ["stream"], secrets: [] };
+export const isStream = (service: ServiceName, op: string) => STREAMS[service]?.includes(op) ?? false;
+
+/** The runtime no longer wants a request's answer: the job was cancelled. The kernel ends what it holds for it. */
+export interface Cancel { type: "cancel"; id: number }
+
+export type FromRuntime = Hello | Loaded | Failed | Result | Round | Retired | ServiceRequest | Cancel | Credit;
+
+export type Message = ToRuntime | FromRuntime;
+
+// ---- kernel ↔ builder --------------------------------------------------
+
+/** Bundle the baba's backend: the Project as the kernel opened it. */
+export interface BuildProject { type: "build-project"; id: number; project: Project }
+/** Bundle the view for the browser; URLs inside the bundle start with `publicPath`. */
+export interface BuildView { type: "build-view"; id: number; spec: ViewSpec }
+export type Built =
+  | { type: "built"; id: number; ok: true; outputs: BuildOutput[] }
+  | { type: "built"; id: number; ok: false; failure: ViewFailure };
+
+export type ToBuilder = Hello | BuildProject | BuildView;
+export type FromBuilder = Hello | Built;

package/src/transport/transport.ts

@@ -0,0 +1,62 @@
+// A transport carries messages to one peer and delivers its messages back.
+// The kernel talks to a runtime, or to the GUI server, only through one.
+import type { Message } from "./messages.ts";
+
+export interface Transport<Out extends { type: string } = Message, In extends { type: string } = Message> {
+  send(m: Out): void;
+  /** At most one handler; the last one set wins. */
+  onMessage(handler: (m: In) => void): void;
+  /** Called when the peer goes away, with why. */
+  onClose(handler: (reason: string) => void): void;
+  /** Ends the peer: a worker is terminated, a process is killed. */
+  close(): void;
+}
+
+/** A transport over a Bun Worker: the peer runs in a thread of this process. */
+export class WorkerTransport<Out extends { type: string } = Message, In extends { type: string } = Message> implements Transport<Out, In> {
+  private handler: ((m: In) => void) | null = null;
+  private closed: ((reason: string) => void) | null = null;
+  constructor(private worker: Worker) {
+    worker.onmessage = (e: MessageEvent<In>) => this.handler?.(e.data);
+    worker.onerror = (e) => this.closed?.(e.message);
+  }
+  send(m: Out) { this.worker.postMessage(m); }
+  onMessage(h: (m: In) => void) { this.handler = h; }
+  onClose(h: (reason: string) => void) { this.closed = h; }
+  close() { this.worker.terminate(); }
+}
+
+/** A transport over Bun's process IPC: the peer is a child process the kernel spawned. */
+export class ProcessTransport<Out extends { type: string } = Message, In extends { type: string } = Message> implements Transport<Out, In> {
+  private handler: ((m: In) => void) | null = null;
+  private closed: ((reason: string) => void) | null = null;
+  private proc: import("bun").Subprocess | null = null;
+
+  /** Spawns `cmd` with IPC; the caller sets cwd, env and stdio through `options`. */
+  constructor(cmd: string[], options: { cwd?: string; env?: Record<string, string>; stdout?: "inherit" | "pipe" | "ignore"; stderr?: "inherit" | "pipe" | "ignore" } = {}) {
+    this.proc = Bun.spawn(cmd, {
+      ...options,
+      ipc: (m: In) => this.handler?.(m),
+      onExit: (_p, code, signal) => this.closed?.(`exited: code ${code}${signal ? `, signal ${signal}` : ""}`),
+    });
+  }
+  get pid() { return this.proc?.pid ?? -1; }
+  send(m: Out) { this.proc?.send(m); }
+  onMessage(h: (m: In) => void) { this.handler = h; }
+  onClose(h: (reason: string) => void) { this.closed = h; }
+  close() { this.proc?.kill(); this.proc = null; }
+}
+
+/** The child's end of a ProcessTransport: `process.send` and `message` events. */
+export class ParentTransport<Out extends { type: string } = Message, In extends { type: string } = Message> implements Transport<Out, In> {
+  private handler: ((m: In) => void) | null = null;
+  constructor() {
+    if (typeof process.send !== "function") throw new Error("not spawned with IPC");
+    process.on("message", (m) => this.handler?.(m as In));
+    process.on("disconnect", () => process.exit(0));
+  }
+  send(m: Out) { process.send!(m); }
+  onMessage(h: (m: In) => void) { this.handler = h; }
+  onClose(h: (reason: string) => void) { process.on("disconnect", () => h("parent gone")); }
+  close() { process.disconnect?.(); }
+}