babavoss 0.12.4 → 0.12.5

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "babavoss",
-  "version": "0.12.4",
+  "version": "0.12.5",
   "license": "Apache-2.0",
   "repository": "github:alanremarc/babavoss",
   "homepage": "https://babavoss.org",
@@ -35,9 +35,9 @@
   "scripts": {
     "voss": "bun bin/voss.ts",
     "test": "bun test",
-    "check": "bunx tsc --noEmit -p ../..",
-    "prepack": "bun ../../tools/release/pack.ts prepack",
-    "postpack": "bun ../../tools/release/pack.ts postpack"
+    "test:kernel": "VOSS_KERNEL=1 bun test ./test/kernel.test.ts",
+    "test:all": "VOSS_KERNEL=1 bun test",
+    "check": "bunx tsc --noEmit -p ../.."
   },
   "devDependencies": {
     "@types/react-dom": "19"

package/src/ecs/runtime.ts

@@ -155,12 +155,16 @@ export class Runtime {
    * Runs an action now, as its system, over the state as it is: the round's and
    * the testbed's. `args` are already checked; an `s.entity(component)` field
    * is resolved from a key and checked to carry its component first. All or
-   * nothing: a throw or a bad result undoes every write it made.
+   * nothing: a throw or a bad result undoes every write it made. With an
+   * idempotency `key` the state remembers, the answer is the one remembered
+   * and the action does not run; a new key remembers the answer it gets.
    */
-  act(name: string, args: unknown): unknown {
+  act(name: string, args: unknown, key?: string): unknown {
     const d = this.baba.actions[name];
     if (!d) throw new ContractError("noaction", `no action ${name}; actions: ${Object.keys(this.baba.actions).join(", ")}`);
     const w = this.w;
+    const kept = key === undefined ? undefined : w.recall(key);
+    if (kept) return kept.value;
     args = this.entities(d.args.json, args);
     return w.transaction(() => {
       const was = w.writer;
@@ -171,7 +175,10 @@ export class Runtime {
         throw new ContractError("failed", `${name}: ${e instanceof Error ? e.message : String(e)}`);
       } finally { w.writer = was; }
       if (r === undefined) r = null;
-      try { return d.result.check(r); } catch (e) { throw new ContractError("result", `${name} returned a bad result: ${e instanceof SchemaError ? e.message : String(e)}`); }
+      let v: unknown;
+      try { v = d.result.check(r); } catch (e) { throw new ContractError("result", `${name} returned a bad result: ${e instanceof SchemaError ? e.message : String(e)}`); }
+      if (key !== undefined) w.remember(key, v);
+      return v;
     });
   }
 
@@ -369,13 +376,7 @@ export class Runtime {
     // The inbox: actions run as their system, raw writes happen, answers land.
     for (const i of this.inbox.splice(0)) {
       if (i.kind === "fire") {
-        const kept = i.key === undefined ? undefined : w.recall(i.key);
-        if (kept) { i.resolve(kept.value); continue; }
-        try {
-          const v = this.act(i.name, i.args);
-          if (i.key !== undefined) w.remember(i.key, v);
-          i.resolve(v);
-        } catch (err) { i.reject(err instanceof Error ? err : new Error(String(err))); }
+        try { i.resolve(this.act(i.name, i.args, i.key)); } catch (err) { i.reject(err instanceof Error ? err : new Error(String(err))); }
       } else if (i.kind === "raw") {
         try { i.resolve(w.transaction(() => this.apply(i.raw))); } catch (err) { i.reject(err instanceof Error ? err : new Error(String(err))); }
       } else if (i.kind === "batch") {
@@ -502,7 +503,13 @@ export class Runtime {
     }
   }
 
-  /** Runs a job against its adapter: a request's reply lands after its delay; a source's listing at once, its events at their moments, listed again every `relist`. */
+  /**
+   * Runs a job against its adapter: a request's reply lands after its delay; a
+   * source's listing at once, its events at their moments. As the driver has
+   * it: a poll (a list and no watch) is done with its listing, and `every`
+   * runs it again on the schedule; a watched source with a list lists again
+   * every `relist` of the adapter, or every `every` of the effect.
+   */
   private adapt(job: Job, adapter: Adapter, ctl: AbortController): void {
     const { effect, entity, args, instance } = job;
     const signal = ctl.signal;
@@ -518,9 +525,11 @@ export class Runtime {
       }
       if (effect.shape !== "source") { this.answer(effect, entity, instance, false, `${effect.name} is a request; its adapter is a source`); return; }
       job.phase = "list";
-      const list = () => { try { this.deliver(effect, entity, instance, { listed: adapter.listing(args, { ...ctx, now: this.sched.now() }) }); } catch (e) { this.answer(effect, entity, instance, false, e instanceof Error ? e.message : String(e)); } };
+      const list = (): boolean => { try { this.deliver(effect, entity, instance, { listed: adapter.listing(args, { ...ctx, now: this.sched.now() }) }); return true; } catch (e) { this.answer(effect, entity, instance, false, e instanceof Error ? e.message : String(e)); return false; } };
+      if (effect.list && !effect.watch) { at(0, () => { if (list()) this.answer(effect, entity, instance, true, undefined); }); return; }
       if (effect.list) { at(0, list); this.relisters.set(instance, () => at(0, list)); }
-      if (adapter.relist !== null && effect.list) { const again = () => at(adapter.relist!, () => { list(); again(); }); again(); }
+      const every = adapter.relist ?? effect.every;
+      if (every !== null && effect.list) { const again = () => at(every, () => { list(); again(); }); again(); }
       if (effect.watch) { job.phase = "watch"; for (const ev of adapter.events(args, ctx)) at(ev.at, () => { this.lastEvent.set(jobKey(effect, entity), ev.event); this.deliver(effect, entity, instance, { events: [ev.event] }); }); }
     } catch (e) { this.answer(effect, entity, instance, false, e instanceof Error ? e.message : String(e)); }
   }

package/src/ecs/testbed.ts

@@ -17,11 +17,14 @@ type ActOf<V> = IsAny<V> extends true ? Record<string, { args: any; result: any
 type ReadOf<V> = IsAny<V> extends true ? Record<string, { args: any; result: any }> : ContractReads<V>;
 type ArgsOf<D> = D extends { args: infer A } ? ({} extends A ? [args?: A] : [args: A]) : [];
 type ResultOf<D> = D extends { result: infer R } ? R : never;
+/** How a fire is made: with an idempotency `key`, the answer remembered under it is answered again and the action does not run. */
+export interface Fired { key?: string }
+type FireOf<D> = D extends { args: infer A } ? ({} extends A ? [args?: A, o?: Fired] : [args: A, o?: Fired]) : [args?: Record<string, never>, o?: Fired];
 
 export interface Testbed<V> {
   readonly w: State<V>;
-  /** Runs the action now, as its system, over the state as it is; what it returned. */
-  fire<K extends keyof ActOf<V> & string>(name: K, ...args: ArgsOf<ActOf<V>[K]>): ResultOf<ActOf<V>[K]>;
+  /** Runs the action now, as its system, over the state as it is; what it returned. With `{ key }`, as `--key` at the shell: the answer remembered under it, without running again. */
+  fire<K extends keyof ActOf<V> & string>(name: K, ...args: FireOf<ActOf<V>[K]>): ResultOf<ActOf<V>[K]>;
   /** The clock to `now` (the last time plus one by default), every round due on the way, then one round at `now`. */
   tick(at?: { now: number }): void;
   /** The clock to `to`: every round due on the way, and nothing more. What a live driver calls as real time passes. */
@@ -58,10 +61,10 @@ export function testbed<V extends Baba | System>(v: V, at: { now?: number; seed?
   });
   return {
     w: rt.w as State<V>,
-    fire: ((name: string, args?: unknown) => {
+    fire: ((name: string, args?: unknown, o?: Fired) => {
       const d = rt.baba.actions[name];
       if (!d) throw new Error(`no action ${name}`);
-      return rt.act(name, d.args.check(args ?? {}));
+      return rt.act(name, d.args.check(args ?? {}), o?.key);
     }) as never,
     // The clock to `to`, the round, then whatever the round's jobs answered at once: an adapter's reply with no delay lands before the hand looks.
     tick(t) { const to = t?.now ?? clock.now() + 1; clock.advance(to); rt.step(to); clock.flush(); },

package/src/generated/build.ts

@@ -1,4 +1,4 @@
 // The commit and the moment a package was built from, stamped by the pack
 // of a release (tools/release/pack.ts) and restored after it. From a
 // checkout both are empty: the tree is the build.
-export const build = {"sha":"f1afec7","at":"2026-10-08T21:00:04.416Z"};
+export const build = { sha: "", at: "" };

package/src/guide/spec-a-system.mdx

@@ -48,6 +48,7 @@ An adapter plays an effect, by the effect itself: `[pond.weather, after(300, ok(
 
 - Requests: `ok(value)`, `fail(error)`, `wait()`, `after(ms, a)`, `sequence([…])` (successive jobs in turn, the last for every job after), `match(where, a, otherwise)`, `model(initial, (state, args) => [state, answer])` for an outside with memory, `custom((args, ctx) => answer)`, `recorded(answer)`.
 - Sources: `listing(items)` (or a function of the args and the adapter's `ctx.state`) with optional `events` and `relist`, and `events([{ at, event }])` for a stream.
+- A played poll (a `list` with `every` and no `watch`) is done the round its listing lands and runs again on its `every`, as the real driver has it; a watched source with a `list` lists again on its `every` too. A listing a scenario changes by hand belongs to a quiet source: list it in the setup, then again when the scenario says.
 - An adapter's state is the spec's: seeded with it, reset with it, shown in the Maker. Keep state in `model` or `ctx.state`, never in a closure.
 - An effect the spec plays no adapter for is **quiet**: its job is never started, so it waits, pending, like an outside that has not answered yet. A script answers it by hand: `done(effect, result, where?)`, `failed(effect, error, where?)`, `list(source, items)`, `watch(source, events)`; `where` picks the jobs by their args, or `{ entity }`; every job of the effect without it. A quiet effect is nothing faked: a quiet mirror keeps what was listed by hand. Waiting jobs are in `t.jobs` (`t.pending` stays empty in a spec). A verdict names the quiet effects a scenario's jobs asked of: what an adapter would have to play.
 
@@ -56,10 +57,11 @@ An adapter plays an effect, by the effect itself: `[pond.weather, after(300, ok(
 A scenario is `{ name, intent, params?, script }`, run from the spec's setup. `script(words, params)` answers the lines, in the testbed's words:
 
 - `given(label, parts | (t) => …)`: a precondition the contract cannot express; parts by component name spawn one entity, `given("one fish", { fish: { x: 100, y: 100, hunger: 0 } })`.
-- `fire(action, args)`: an action, now; `answer(0, "entity")` is an earlier fire's answer in a later fire's args.
+- `fire(action, args, { key }?)`: an action, now; `answer(0, "entity")` is an earlier fire's answer in a later fire's args; `key` is the idempotency key, as `--key` at the shell.
 - `tick({ after | at })`, `ticks(count, every)`: rounds on the spec's clock.
 - `done`, `failed`, `list`, `watch`: the outside answering, landing at the next tick.
 - `check(label, (t) => read, want?)`: deep-equal to `want`, or true. A failed check records and the run goes on; a step that throws stops it.
+- `want` may be a function of the testbed, `(t) => value`: read when the check runs and recorded as the value it gave, so a check can want what a `given` captured. A fire that must be refused is a check whose read catches the throw: `check("refused", (t) => { try { t.fire(…); return false; } catch { return true; } })`.
 
 Everything runs on the spec's own clock: an adapter's delay, a retry, a schedule and the baba's tick are due moments on it. Headless the clock jumps; live it follows real time at the speed chosen. The state lands the same either way; `w.random()` is seeded, so a run repeats.
 

package/src/guide/write-promptware.mdx

@@ -79,11 +79,12 @@ export default [
 - Read the state in promptware: it is static, rendered from the manifest once per generation.
 - Explain why in a step; put reasons in the context if they are needed at all.
 - Write `simply`, `just`, `easily`, `should`, or a synonym for a term that has one name: system, app, spec, step, state, round, action, query, effect, source, mirror, context, skill, hook, baba, voss.
-- Edit `CLAUDE.md`, `AGENTS.md` or a `SKILL.md`: they are outputs.
+- Edit `CLAUDE.md`, `AGENTS.md`, a `SKILL.md` or `.claude/settings.local.json`: they are outputs. Git keeps none of them: voss writes its lines of the project's `.gitignore`, and a checkout makes its own with `voss baba promptware sync`.
+- Commit an output. A hand-written `.claude/settings.json` beside the made `settings.local.json` is the place for what the repository itself tells Claude Code, a `SessionStart` hook that runs the sync, say.
 
 ## Hooks
 
-A hook hands a harness moment to an action: `hook({ on, match?, action, strict? })` with `on` one of PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, PreCompact, Notification, and `match` a tool-name regex for the two tool events. The action takes `hookArgs(EVENT)` and answers `hookResult()`: `{ decision: "block", reason }` stops the tool call and the agent reads the reason; `{ context }` is told to the agent; `{}` lets it through. Voss compiles it into `.claude/settings.json` as `voss baba ACTION @- --hook EVENT`; a baba that is down lets through with a note, `strict: true` blocks. Prove a hook with a scenario: `fire` the action with an event, `check` the decision.
+A hook hands a harness moment to an action: `hook({ on, match?, action, strict? })` with `on` one of PreToolUse, PostToolUse, UserPromptSubmit, Stop, SubagentStop, SessionStart, PreCompact, Notification, and `match` a tool-name regex for the two tool events. The action takes `hookArgs(EVENT)` and answers `hookResult()`: `{ decision: "block", reason }` stops the tool call and the agent reads the reason; `{ context }` is told to the agent; `{}` lets it through. Voss compiles it into `.claude/settings.local.json` as `voss baba ACTION @- --hook EVENT`; a baba that is down lets through with a note, `strict: true` blocks. Prove a hook with a scenario: `fire` the action with an event, `check` the decision.
 
 ## Voice
 

package/src/promptware/compile.ts

@@ -2,7 +2,7 @@
 // context and skills rendered and its harness declaration, becomes what
 // each output path, relative to the project, should hold.
 //
-//   Claude Code   CLAUDE.md   .claude/skills/NAME/SKILL.md   .claude/settings.json
+//   Claude Code   CLAUDE.md   .claude/skills/NAME/SKILL.md   .claude/settings.local.json
 //   Codex         AGENTS.md   .agents/skills/NAME/SKILL.md
 //
 // Promptware is know-how; the contract teaches itself at the doors, the
@@ -48,7 +48,21 @@ export type Merge =
   | { kind: "json-key"; at: string[]; value: unknown }
   | { kind: "json-list"; at: string[]; values: unknown[] }
   | { kind: "json-lists"; lists: { at: string[]; values: unknown[] }[] }
-  | { kind: "toml-table"; table: string; body: string };
+  | { kind: "toml-table"; table: string; body: string }
+  | { kind: "lines"; lines: string[] };
+
+/** Voss's shared settings of Claude Code: the local file, which Claude Code keeps out of git, since what voss writes is made, not kept. */
+export const CLAUDE_SETTINGS = ".claude/settings.local.json";
+
+/**
+ * The outputs are made from the promptware: a checkout makes its own with `voss baba promptware sync` (a landing does),
+ * and git keeps none of them. Voss's lines of the project's .gitignore say so.
+ */
+export const ignoreLines = (): string[] => [
+  "# voss makes these from .baba/promptware: `voss baba promptware sync` writes them, git keeps none",
+  ...harnesses.flatMap((h) => [`/${files[h].instructions}`, `/${files[h].skills}/`]),
+  `/${CLAUDE_SETTINGS}`,
+];
 
 /** Output path to text, sorted by path. */
 export type Outputs = Record<string, string>;
@@ -101,10 +115,11 @@ export function compile(input: CompileInput): Compiled {
         byEvent.get(hk.on)!.push(entry);
       }
       for (const [on, values] of byEvent) lists.push({ at: ["hooks", on], values });
-      if (lists.length === 1 && lists[0]!.at[0] === "permissions") merges[".claude/settings.json"] = { kind: "json-list", at: lists[0]!.at, values: lists[0]!.values };
-      else if (lists.length) merges[".claude/settings.json"] = { kind: "json-lists", lists };
+      if (lists.length === 1 && lists[0]!.at[0] === "permissions") merges[CLAUDE_SETTINGS] = { kind: "json-list", at: lists[0]!.at, values: lists[0]!.values };
+      else if (lists.length) merges[CLAUDE_SETTINGS] = { kind: "json-lists", lists };
     }
   }
+  merges[".gitignore"] = { kind: "lines", lines: ignoreLines() };
   return { files: sorted(out), merges: sorted(merges) };
 }
 

package/src/promptware/sync.ts

@@ -9,9 +9,10 @@
 //   held      owned but edited by hand, or not a regular file: never touched
 //   foreign   present and never written by the compiler: never touched
 //
-// A shared file, .mcp.json or .claude/settings.json or .codex/config.toml,
-// is voss's only for its part: merged in, taken out when no longer wanted,
-// and the whole file held when the part was edited by hand.
+// A shared file, .mcp.json or .claude/settings.local.json or
+// .codex/config.toml, or the project's .gitignore, is voss's only for its
+// part: merged in, taken out when no longer wanted, and the whole file held
+// when the part was edited by hand.
 //
 // The files are reached through `Files`: Bun's on the shell's offline path
 // (disk.ts), the effect's ctx.fs inside a baba. plan() writes nothing;
@@ -183,6 +184,7 @@ export function partOf(m: Merge, text: string): string | null {
     const b = tomlBlock(lines, m.table);
     return b ? [`[${m.table}]`, ...lines.slice(b.start + 1, b.end)].join("\n").trim() : null;
   }
+  if (m.kind === "lines") { const have = new Set(text.split("\n").map((l) => l.trim())); const present = m.lines.filter((l) => have.has(l)); return present.length ? stable(present) : null; }
   const o = parseJson(text);
   if (m.kind === "json-key") { const v = getAt(o, m.at); return v === undefined ? null : stable(v); }
   const present = listsOf(m).map((l) => { const v = getAt(o, l.at); return l.values.filter((x) => Array.isArray(v) && v.some((y) => stable(y) === stable(x))); });
@@ -192,7 +194,7 @@ export function partOf(m: Merge, text: string): string | null {
 
 /** Voss's part whole, as partOf reads it once merged. */
 export function wholePart(m: Merge): string {
-  return m.kind === "toml-table" ? tomlText(m) : stable(m.kind === "json-key" ? m.value : m.kind === "json-list" ? m.values : listsOf(m).map((l) => l.values));
+  return m.kind === "toml-table" ? tomlText(m) : m.kind === "lines" ? stable(m.lines) : stable(m.kind === "json-key" ? m.value : m.kind === "json-list" ? m.values : listsOf(m).map((l) => l.values));
 }
 
 /** The lists a list merge holds: one for the older single-list kind. */
@@ -220,6 +222,22 @@ export function mergeText(text: string | null, want: Merge | undefined, was: Mer
     const out = lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
     return out ? out + "\n" : null;
   }
+  if (kind === "lines") {
+    // Lines: each of voss's, by content, taken out where no longer wanted and put in where missing, as a block at the end; others' lines stay.
+    const w = want as Extract<Merge, { kind: "lines" }> | undefined;
+    const old = was as Extract<Merge, { kind: "lines" }> | undefined;
+    const keep = new Set(w?.lines ?? []);
+    const gone = new Set((old?.lines ?? []).filter((l) => !keep.has(l)));
+    let lines = (text ?? "").replace(/\r\n/g, "\n").split("\n").filter((l) => !gone.has(l.trim()));
+    const have = new Set(lines.map((l) => l.trim()));
+    const missing = (w?.lines ?? []).filter((l) => !have.has(l));
+    if (missing.length) {
+      while (lines.length && !lines.at(-1)!.trim()) lines.pop();
+      lines = [...lines, ...(lines.length ? [""] : []), ...missing];
+    }
+    const out = lines.join("\n").replace(/\n{3,}/g, "\n\n").trim();
+    return out ? out + "\n" : null;
+  }
   const o = parseJson(text);
   if (kind === "json-key") {
     const w = want as Extract<Merge, { kind: "json-key" }> | undefined;
@@ -260,7 +278,7 @@ export function mergeText(text: string | null, want: Merge | undefined, was: Mer
 /** Whether two texts of a shared file say the same: equal JSON for JSON, equal text for TOML. */
 function same(m: Merge, a: string, b: string): boolean {
   if (a === b) return true;
-  if (m.kind === "toml-table") return a.trim() === b.trim();
+  if (m.kind === "toml-table" || m.kind === "lines") return a.trim() === b.trim();
   try { return stable(JSON.parse(a)) === stable(JSON.parse(b)); } catch { return false; }
 }
 
@@ -299,7 +317,7 @@ export async function plan(io: Files, wanted: Compiled, root = ""): Promise<Plan
             keep();
             continue;
           }
-          if (!owned && wm && wm.kind !== "json-list" && wm.kind !== "json-lists") {
+          if (!owned && wm && wm.kind !== "json-list" && wm.kind !== "json-lists" && wm.kind !== "lines") {
             const part = partOf(wm, text);
             if ((part !== null && part !== wholePart(wm)) || (wm.kind === "toml-table" && tomlElsewhere(text, wm.table))) {
               entries.push({ path, status: "held", action: null, before: now, reason: "an entry voss did not write" });

package/src/promptware/system.ts

@@ -36,7 +36,7 @@ const entries = async (fs: Fs, path: string) => ((await fs.stat(path).catch(() =
 
 /** Every place an output may be: the instruction files, the shared files (with those an older voss merged into, to take its part out), and the skill directories as they are now. */
 async function outputs(fs: Fs): Promise<{ path: string; hash: string }[]> {
-  const paths = ["AGENTS.md", "CLAUDE.md", ".mcp.json", ".claude/settings.json", ".codex/config.toml"];
+  const paths = ["AGENTS.md", "CLAUDE.md", ".mcp.json", ".claude/settings.local.json", ".claude/settings.json", ".codex/config.toml", ".gitignore"];
   for (const dir of [".claude/skills", ".agents/skills", ".codex/skills"]) for (const e of await entries(fs, dir)) if (e.dir) paths.push(`${dir}/${e.name}/SKILL.md`);
   const out: { path: string; hash: string }[] = [];
   for (const path of paths) {

package/src/spec/run.ts

@@ -46,9 +46,9 @@ export function* execute<T extends Testbed<any>>(steps: Line<T>[], t: T, o: { fr
         break;
       }
       case "fire": {
-        const rec: StepRecord = { kind: "fire", label: step.name, args: step.args };
+        const rec: StepRecord = { kind: "fire", label: step.name, args: step.args, ...(step.key !== undefined ? { key: step.key } : {}) };
         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; });
+        yield attempt(i, rec, () => { rec.args = resolveAnswers(step.args, answers.slice(0, at)); rec.result = (t.fire as unknown as (n: string, a: unknown, o?: { key?: string }) => unknown)(step.name, rec.args, step.key !== undefined ? { key: step.key } : undefined); 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; }
@@ -61,7 +61,9 @@ export function* execute<T extends Testbed<any>>(steps: Line<T>[], t: T, o: { fr
         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;
+          // A lazy want is read when the check runs, and recorded as the value it gave.
+          const want = typeof step.want === "function" ? (step.want as (t: T) => unknown)(t) : step.want;
+          if (step.compare) { c.got = got; c.want = want; c.ok = deepEqual(got, want); } else c.ok = got === true;
         } catch (e) { c.error = msg(e); }
         checks.push(c);
         yield { kind: "check", rec: c, index: i };

package/src/spec/take.ts

@@ -38,7 +38,7 @@ export function asProgram(o: { spec: string; name: string; intent: string; steps
     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)}),`);
+    if (rec.kind === "fire") lines.push(`    fire(${json(rec.label)}, ${json(rec.args)}${rec.key !== undefined ? `, { key: ${json(rec.key)} }` : ""}),`);
     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}),`);

package/src/test/index.ts

@@ -3,6 +3,6 @@
 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 { prove, proveAll, verdictsDir, type Registrar, 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

@@ -17,8 +17,11 @@ export interface Verdicts { spec: string; run: string; at: string; done: boolean
 /** 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 {
+/** What registers a scenario's test: bun's `test`, or the framework's own proof of the runner. */
+export type Registrar = (name: string, fn: () => Promise<void>) => void;
+
+/** Registers every scenario of `sp` with bun test (or `register`) 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(), register: Registrar = test): 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: "" }])) };
@@ -27,7 +30,7 @@ export function prove(sp: Spec, state = verdictsDir()): void {
   let left = sp.scenarios.length;
   if (left === 0) { void write(); return; }
   for (const sc of sp.scenarios) {
-    test(`${sp.name}: ${sc.name}`, async () => {
+    register(`${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));
@@ -45,11 +48,11 @@ export function prove(sp: Spec, state = verdictsDir()): void {
  * beside them. The one call in `.baba/spec.test.ts`:
  * `await proveAll(import.meta.dir)`.
  */
-export async function proveAll(baba: string): Promise<void> {
+export async function proveAll(baba: string, register: Registrar = test): 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"));
+  for (const sp of specs) prove(sp, join(baba, ".voss", "spec"), register);
 }
 
 const describe = (c: CheckRecord) => `${c.label}${c.error ? ` (${c.error})` : c.compare ? `: got ${JSON.stringify(c.got)}, want ${JSON.stringify(c.want)}` : ""}`;

package/src/test/records.ts

@@ -6,6 +6,8 @@ export interface StepRecord {
   kind: "given" | "fire" | "tick" | "done" | "failed" | "list" | "watch";
   label: string;
   args?: unknown;
+  /** A fire's idempotency key, when it had one. */
+  key?: string;
   result?: unknown;
   error?: string;
   /** False for a given done by a function: the page cannot replay it. */

package/src/test/steps.ts

@@ -7,20 +7,20 @@ 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: "fire"; name: string; args: unknown; key?: string }
   | { 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 };
+  | { kind: "check"; label: string; read: (t: T) => unknown; /** The value wanted, or a function of the testbed that gives it when the check runs. */ 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. */
+  /** 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. A third argument \`{ key }\` is the idempotency key, as \`--key\` at the shell. */
   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;
@@ -34,8 +34,12 @@ export interface Words<T extends Testbed<any>> {
   /** 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>;
+  /** A claim about the state now: without `want`, what `read` gives must be true. */
+  check(label: string, read: (t: T) => unknown): Line<T>;
+  /** With a `want` that is a function of the testbed: read when the check runs, so a check can want what a `given` captured; recorded as the value it gave. */
+  check(label: string, read: (t: T) => unknown, want: (t: T) => unknown): Line<T>;
+  /** With `want`, what `read` gives must deep-equal it. */
+  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>> {
@@ -53,14 +57,14 @@ export interface ScenarioDef<T extends Testbed<any>, P extends Record<string, un
 
 export const words: Words<any> = {
   given: (label, run) => ({ kind: "given", label, run }),
-  fire: (name: string, args?: unknown) => ({ kind: "fire", name, args: args ?? {} }),
+  fire: (name: string, args?: unknown, o?: { key?: string }) => ({ kind: "fire", name, args: args ?? {}, ...(o?.key !== undefined ? { key: o.key } : {}) }),
   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 }),
+  check: (label: string, read: (t: any) => unknown, ...want: [unknown?]) => ({ kind: "check", label, read, want: want[0], compare: want.length > 0 }),
   answer: (index: number, path?: string) => `$${index}${path ? `.${path}` : ""}`,
 };