babavoss 0.0.1 → 0.12.0

package/src/baba/node.ts

@@ -0,0 +1,483 @@
+// A project as a running node: its one state in a runtime, fire, read, state
+// and raw over it, reload on change with the state carried across, and its
+// view bundled and cached per generation. The state lives for the run:
+// carried across reloads, gone at stop. Nothing of it is kept on disk;
+// what a baba wants to keep is the baba's own concern.
+import { watch, type FSWatcher } from "node:fs";
+import { join, sep } from "node:path";
+import { mkdir } from "node:fs/promises";
+import type { Manifest } from "../ecs/baba.ts";
+import type { Snapshot } from "../ecs/state.ts";
+import { isDelta, patchSnapshot, type StateAnswer } from "../ecs/snapshot.ts";
+import type { Interest } from "../server/protocol.ts";
+import type { Raw } from "../ecs/runtime.ts";
+import type { Project } from "./project.ts";
+import type { ToWorker, FromWorker } from "./worker.ts";
+import type { Services, Who } from "../kernel/context.ts";
+import { KernelServices, describe, serveRequest } from "../services/index.ts";
+import type { ServiceRequest, Result } from "../transport/messages.ts";
+import { WorkerTransport, type Transport } from "../transport/transport.ts";
+import { InProcessBuilder, type Builder, type BuildOutput, type ViewSpec } from "../build/builder.ts";
+import { ViewFailed, formatFailure, type ViewFailure } from "../build/failure.ts";
+import { moveOldDir, writeEditorConfig } from "./config.ts";
+import { takeLock, LockError, type Lock } from "../kernel/lock.ts";
+
+/** What describe answers: the contract, the generation, the view's state. */
+export interface Described { name: string; title: string; gen: number; manifest: Manifest | null; view: { v: number; error: ViewFailure | null } | null; error: string | null }
+
+/** PROJECT/.baba/.voss/lock: the pid of the one process running this state. */
+export const lockPath = (p: Project) => join(p.baba, ".voss", "lock");
+/** PROJECT/.baba/.voss/manifest.json: the contract as the last successful load left it. */
+export const manifestPath = (p: Project) => join(p.baba, ".voss", "manifest.json");
+
+/** The manifest the last load wrote, or null when there is none or it does not read. */
+export async function readManifest(p: Project): Promise<Manifest | null> {
+  try { return (await Bun.file(manifestPath(p)).json()) as Manifest; } catch { return null; }
+}
+
+export class NodeError extends Error {
+  constructor(readonly code: string, msg: string) { super(msg); }
+}
+
+interface Live {
+  transport: Transport<ToWorker, FromWorker>;
+  manifest: Manifest;
+  inflight: number;
+  /** The service requests this generation has open, by its ids: each aborted on cancel, and all when the generation goes. */
+  open: Map<number, { ctl: AbortController; done: Promise<void>; grant(): void; request: ServiceRequest }>;
+  generation: string;
+  active: boolean;
+  destruction?: Promise<void>;
+  activated?: { resolve(m: { manifest: Manifest; snapshot: Snapshot }): void; reject(e: Error): void };
+  closed?: Error;
+  /** This generation's state as its last round left it: the whole it loaded with, moved by each round's delta. */
+  last: Snapshot | null;
+  onRetired: ((r: { errors: string[]; snapshot: Snapshot | null; busy?: boolean }) => void) | null;
+}
+
+const RETIRE_MS = 3000;
+const ACTIVATE_MS = 10_000;
+const QUIET_MS = 300;
+/** How often a reload that waits for a job asks again. */
+const WAIT_MS = 500;
+// What changes under .baba without changing the code: voss's own files and the dependencies. Promptware is code: a change there reloads.
+const IGNORED = [".voss", "node_modules"];
+
+/** Makes the transport a Node loads a project over. The worker is the first; a runtime process is next. */
+export type Connect = () => Transport<ToWorker, FromWorker>;
+export const workerConnect: Connect = () => new WorkerTransport(new Worker(new URL("./worker.ts", import.meta.url).href, { preload: [new URL("../build/mdx-register.ts", import.meta.url).pathname] }));
+
+interface Bundle { gen: number; outputs: BuildOutput[] }
+
+const failureOf = (err: unknown): ViewFailure => err instanceof ViewFailed ? err.failure : { stage: "build", message: err instanceof Error ? err.message : String(err) };
+
+interface Pending { from: Live; resolve: (v: { value: unknown; round: number | undefined }) => void; reject: (e: Error) => void }
+type Unnumbered<T> = T extends unknown ? Omit<T, "id"> : never;
+
+export class Node {
+  private live: Live | null = null;
+  private loading: Promise<void> | null = null;
+  private stopping = false;
+  private cancelLoad: ((e: Error) => void) | null = null;
+  private switching: Promise<void> | null = null;
+  private cleanupFailure: Error | null = null;
+  private pending = new Map<number, Pending>();
+  private nextId = 1;
+  private watcher: FSWatcher | null = null;
+  private timer: ReturnType<typeof setTimeout> | null = null;
+  /** The last load error, when the running generation is older than the files. */
+  error: string | null = null;
+  /** Why changes on disk are not loaded for now: a newer voss is installed, and this one serves what it has until the restart. */
+  frozen: string | null = null;
+  /** Whether a change arrived while frozen: the restart will load it. */
+  held = false;
+  /** Whether a reload is waiting for a job that cannot run twice to finish. */
+  private waiting = false;
+  /** The state as the last round left it: what a reload continues from. */
+  private last: Snapshot | null = null;
+  /** Hears each of the live generation's rounds as the frame every window gets: the GUI server fans it out. */
+  onRound: ((frame: Uint8Array, round: number) => void) | null = null;
+  /** Hears the generation advance: windows re-read the contract and resync. */
+  onGeneration: ((gen: number) => void) | null = null;
+  /** The state is one process's: .baba/.voss/lock, taken on the first start and held until stop. */
+  private lock: Lock | null = null;
+
+  // Generations: seeded so a restart never repeats a URL, advanced once per settled change.
+  private gen = Date.now();
+  private viewGen: number;
+  private bundle_: Bundle | null = null;
+  private bundleError: ViewFailure | null = null;
+  private building: Promise<Bundle> | null = null;
+  private waiters: (() => void)[] = [];
+
+  constructor(
+    readonly project: Project,
+    private log: (line: string) => void = () => {},
+    private connect: Connect = workerConnect,
+    /** What answers the jobs' service requests: the kernel's services, every reach beyond the project in the log. */
+    private services: Services = new KernelServices((e) => { const line = describe(e); if (line) log(`${project.name}: ${line}`); }),
+    /** What bundles the view: in-process by default; the kernel gives the project's walled builder. */
+    private builder: Builder = new InProcessBuilder(),
+  ) { this.viewGen = this.gen; }
+
+  get name() { return this.project.name; }
+  get generation() { return this.gen; }
+
+  /** Where the view's outputs are served from, at a generation. */
+  publicPath(gen: number): string { return `/view/${encodeURIComponent(this.name)}/${gen}/`; }
+
+  private spec(gen: number): ViewSpec {
+    return { entry: this.project.view!, root: this.project.baba, publicPath: this.publicPath(gen), dir: this.project.baba, plugins: this.project.build.plugins, assets: this.project.build.assets };
+  }
+
+  describe(): Described {
+    return {
+      name: this.name, title: this.project.title, gen: this.gen,
+      manifest: this.live?.manifest ?? null,
+      view: this.project.view ? { v: this.viewGen, error: this.bundleError } : null,
+      error: this.error,
+    };
+  }
+
+  /** Loads the project into a fresh runtime over the state it has, and, when that works, makes it the live one. */
+  start(): Promise<void> {
+    if (this.stopping) return Promise.reject(new NodeError("closed", "node is stopping"));
+    return this.loading ??= this.load().finally(() => { this.loading = null; this.cancelLoad = null; });
+  }
+
+  private async load(): Promise<void> {
+    // A first load that fails gives the lock back: nothing runs, so nothing holds the state, and the next start is not refused as busy.
+    const took = !this.lock;
+    if (!this.lock) {
+      // Before .voss is made for the lock: a project from before the rename still has its files in state/, and they move first.
+      await moveOldDir(this.project).catch((err) => this.log(`${this.name}: .baba/state was not moved: ${err instanceof Error ? err.message : String(err)}`));
+      await mkdir(join(this.project.baba, ".voss"), { recursive: true });
+      try { this.lock = takeLock(lockPath(this.project), { name: this.name }, (h) => `${this.name} is already run by pid ${h.pid}`); }
+      catch (err) { if (err instanceof LockError) throw new NodeError("busy", err.message); throw err; }
+    }
+    await writeEditorConfig(this.project).catch((err) => this.log(`${this.name}: editor config: ${err instanceof Error ? err.message : String(err)}`));
+    if (this.stopping) throw new NodeError("closed", "node is stopping");
+    const snapshot = this.last;
+    const transport = this.connect();
+    const fresh: Live = { transport, manifest: null as never, inflight: 0, open: new Map(), last: null, onRetired: null, generation: crypto.randomUUID(), active: false };
+    const loaded = await new Promise<{ manifest: Manifest; snapshot: Snapshot }>((resolve, reject) => {
+      const failed = (error: Error) => {
+        this.closed(fresh, error);
+        reject(error);
+      };
+      this.cancelLoad = failed;
+      transport.onMessage((m) => {
+        if (m.type === "loaded") { fresh.last = m.snapshot; resolve(m); fresh.activated?.resolve(m); }
+        else if (m.type === "failed") failed(new NodeError("load", m.error));
+        else if (m.type === "result") this.settle(m);
+        else if (m.type === "round") {
+          // Each generation follows its own rounds, in place; the live one's state is the node's, and its frames go to the windows.
+          try { fresh.last = isDelta(m.state) ? patchSnapshot(fresh.last!, m.state) : m.state; } catch (err) { this.log(`${this.name}: a round was lost: ${err instanceof Error ? err.message : String(err)}`); }
+          if (fresh === this.live || !this.live) { this.last = fresh.last; if (fresh === this.live) this.onRound?.(m.frame, m.state.round); }
+        }
+        else if (m.type === "service") void this.serve(m, fresh).catch((e) => { this.cleanupFailure = e; this.log(`${this.name}: execution cleanup failed: ${e}`); });
+        else if (m.type === "cancel") { fresh.open.get(m.id)?.ctl.abort(); }
+        else if (m.type === "credit") fresh.open.get(m.id)?.grant();
+        else if (m.type === "retired") fresh.onRetired?.(m);
+      });
+      transport.onClose((reason) => failed(new NodeError("down", reason)));
+      transport.send({ type: "load-dir", dir: this.project.dir, snapshot, prepare: true });
+    }).catch((err) => {
+      transport.close();
+      if (took && !this.live && !this.cleanupFailure) { this.lock?.release(); this.lock = null; }
+      throw err;
+    });
+    fresh.manifest = loaded.manifest;
+    // The contract outlives the run: discovery and promptware read it with the baba down.
+    await mkdir(join(this.project.baba, ".voss"), { recursive: true })
+      .then(() => Bun.write(manifestPath(this.project), JSON.stringify(loaded.manifest, null, 2) + "\n"))
+      .catch((err) => this.log(`${this.name}: the manifest was not written: ${err instanceof Error ? err.message : String(err)}`));
+    // Preparation did no IO. Hold new calls while the old state reaches its
+    // final snapshot and all owned execution groups are drained.
+    let resume!: () => void;
+    this.switching = new Promise<void>((r) => { resume = r; });
+    try {
+      const old = this.live;
+      if (old) {
+        while (old.inflight && !this.stopping) await new Promise((r) => setTimeout(r, 5));
+        if (this.stopping) throw new NodeError("closed", "node is stopping");
+        await this.destruct(old, true);
+      }
+      // A crashed generation may already have left `live`, while its OS
+      // cleanup still runs. It holds the same activation barrier.
+      await Promise.all([...this.retiring].map((retiring) => this.destruct(retiring)));
+      if (this.stopping) throw new NodeError("closed", "node is stopping");
+      if (fresh.closed) throw fresh.closed;
+      if (this.cleanupFailure) throw this.cleanupFailure;
+      fresh.active = true;
+      this.live = fresh;
+      const activated = await new Promise<{ manifest: Manifest; snapshot: Snapshot }>((resolve, reject) => {
+        const timer = setTimeout(() => reject(new NodeError("load", "runtime did not activate within 10s")), ACTIVATE_MS);
+        fresh.activated = { resolve: (m) => { clearTimeout(timer); resolve(m); }, reject: (e) => { clearTimeout(timer); reject(e); } };
+        try { fresh.transport.send({ type: "activate", snapshot: old?.last ?? this.last ?? snapshot }); }
+        catch (e) { fresh.activated.reject(e instanceof Error ? e : new Error(String(e))); }
+      }).finally(() => { fresh.activated = undefined; });
+      this.last = activated.snapshot;
+      this.error = null;
+      this.watch();
+    } catch (e) {
+      this.closed(fresh, e instanceof Error ? e : new Error(String(e)));
+      await this.destruct(fresh);
+      if (took && !this.live && !this.cleanupFailure) { this.lock?.release(); this.lock = null; }
+      throw e;
+    } finally { this.switching = null; resume(); }
+  }
+
+  private ask(m: Unnumbered<Extract<ToWorker, { id: number }>>): Promise<unknown> { return this.askFull(m).then((r) => r.value); }
+
+  private async askFull(m: Unnumbered<Extract<ToWorker, { id: number }>>): Promise<{ value: unknown; round: number | undefined }> {
+    await this.switching;
+    const live = this.live;
+    if (this.stopping || !live || live.closed) return Promise.reject(new NodeError("down", `${this.name} is not running${this.error ? `: ${this.error}` : ""}`));
+    const id = this.nextId++;
+    live.inflight++;
+    return new Promise<{ value: unknown; round: number | undefined }>((resolve, reject) => {
+      this.pending.set(id, { from: live, resolve, reject });
+      live.transport.send({ ...m, id } as ToWorker);
+    }).finally(() => {
+      live.inflight--;
+      if (live !== this.live) this.retire(live);
+    });
+  }
+
+  /** Fires an action; answers what it returned. `coerce` reads shell strings; a `key` makes a retry answer the same. */
+  fire(name: string, args: unknown, coerce = false, key?: string): Promise<unknown> { return this.ask({ type: "fire", name, args, coerce, ...(key !== undefined ? { key } : {}) }); }
+  /** Reads a query. */
+  read(name: string, args: unknown, coerce = false): Promise<unknown> { return this.ask({ type: "read", name, args, coerce }); }
+  /** The state once a round past `since` has run, or after a wait; its secrets redacted. */
+  state(since = 0): Promise<StateAnswer> { return this.ask({ type: "state", since }) as Promise<StateAnswer>; }
+  /** The same as a frame: bytes laid out by the model, for a window. */
+  frame(since = 0, wait = true): Promise<Uint8Array> { return this.ask({ type: "state", since, frame: true, ...(wait ? {} : { wait: false }) }) as Promise<Uint8Array>; }
+  /** The parts a window began to ask for, as a frame since the round just ended. */
+  parts(interest: Interest): Promise<Uint8Array> { return this.ask({ type: "state", since: 0, frame: true, wait: false, parts: interest }) as Promise<Uint8Array>; }
+  /** Fires an action and says which round it ran in. */
+  fireIn(name: string, args: unknown, coerce = false, key?: string): Promise<{ value: unknown; round: number | undefined }> { return this.askFull({ type: "fire", name, args, coerce, ...(key !== undefined ? { key } : {}) }); }
+  /** A raw write and the round it ran in. */
+  rawIn(raw: Raw): Promise<{ value: unknown; round: number | undefined }> { return this.askFull({ type: "raw", raw }); }
+  /** A write at layer zero. */
+  raw(raw: Raw): Promise<unknown> { return this.ask({ type: "raw", raw }); }
+  /** Fire or read by the contract's kind of `name`. */
+  async call(name: string, args: unknown, coerce = false): Promise<unknown> {
+    const m = this.live?.manifest;
+    if (m && name in m.queries) return this.read(name, args, coerce);
+    return this.fire(name, args, coerce);
+  }
+
+  /** A job asked for something outside its runtime: the kernel's services answer the generation that asked, once or, for a stream, many times. */
+  private async serve(m: ServiceRequest, from: Live): Promise<void> {
+    if (!from.active || this.cleanupFailure) {
+      from.transport.send({ type: "serviced", id: m.id, ok: false, code: "failed", error: this.cleanupFailure?.message ?? "generation is not active" }); return;
+    }
+    const who: Who = { project: this.project.dir, system: m.system, effect: m.effect, job: m.job, entity: m.entity, generation: from.generation };
+    const ctl = new AbortController();
+    let available = true, wake: (() => void) | undefined;
+    const grant = () => { available = true; wake?.(); };
+    ctl.signal.addEventListener("abort", grant, { once: true });
+    const credit = async () => {
+      if (!available && !ctl.signal.aborted) await new Promise<void>((r) => { wake = r; });
+      available = false; wake = undefined;
+    };
+    // Replacement of a logical job waits for its cancelled predecessor.
+    const predecessors = [...from.open.values()].filter((r) => r.request.service === "exec" && r.request.job !== m.job && r.request.system === m.system && r.request.effect === m.effect && r.request.entity === m.entity).map((r) => r.done);
+    const done = Promise.resolve().then(async () => {
+      if (m.service === "exec" && m.op !== "write") await Promise.all(predecessors);
+      if (!ctl.signal.aborted) await serveRequest(this.services, who, m, (a) => { if (!ctl.signal.aborted) from.transport.send(a); }, ctl.signal, credit);
+    }).finally(() => { from.open.delete(m.id); });
+    from.open.set(m.id, { ctl, done, grant, request: m });
+    await done;
+  }
+  private retiring = new Set<Live>();
+
+  /** The view's bundle: what the last change built, or, for a view nobody asked for since the node started, built now. */
+  async bundle(): Promise<Bundle> {
+    if (!this.project.view) throw new NodeError("noview", `${this.name} has no view`);
+    if (this.bundle_) return this.bundle_;
+    if (!this.building) {
+      const gen = this.viewGen;
+      this.building = this.builder.view(this.spec(gen)).then(
+        (outputs) => { const b = { gen, outputs }; this.bundle_ = b; this.bundleError = null; return b; },
+        (err) => { this.bundleError = failureOf(err); this.wake(); throw new NodeError("bundle", formatFailure(this.bundleError)); },
+      ).finally(() => { this.building = null; });
+    }
+    return this.building;
+  }
+
+  private wake(): void {
+    const waiters = this.waiters;
+    this.waiters = [];
+    for (const w of waiters) w();
+  }
+
+  /** Resolves once the generation passes `since`, or after `ms`. */
+  waitFor(since: number, ms: number): Promise<void> {
+    if (this.gen > since) return Promise.resolve();
+    return new Promise((resolve) => {
+      const t = setTimeout(() => { this.waiters = this.waiters.filter((w) => w !== done); resolve(); }, ms);
+      const done = () => { clearTimeout(t); resolve(); };
+      this.waiters.push(done);
+    });
+  }
+
+  /**
+   * The settled change: the new code over the current state, the view
+   * rebuilt, the generation advanced once. A view that fails to build keeps
+   * its old bundle and records the error; the old generation serves
+   * throughout, and stays if the new code fails to load.
+   */
+  async reload(): Promise<void> {
+    // Retiring the generation would cut its jobs, and one of an effect that cannot run twice would land as interrupted
+    // instead of done: so the reload waits for those, asking again until none runs.
+    const busy = this.unrepeatable();
+    if (busy.length) {
+      if (!this.waiting) this.log(`${this.name}: changed on disk; the reload waits for ${busy.join(", ")} to finish`);
+      this.waiting = true;
+      this.waitReload();
+      return;
+    }
+    this.waiting = false;
+    try {
+      await this.start();
+      this.log(`${this.name}: reloaded`);
+    } catch (err) {
+      if (err instanceof NodeError && err.code === "reload-busy") { this.waitReload(); return; }
+      this.error = err instanceof Error ? err.message : String(err);
+      this.log(`${this.name}: reload failed${this.live ? ", still serving the last generation" : ""}: ${this.error}`);
+    }
+    if (this.stopping) return;
+    const next = this.gen + 1;
+    if (this.project.view) {
+      try {
+        const outputs = await this.builder.view(this.spec(next));
+        this.bundle_ = { gen: next, outputs };
+        this.bundleError = null;
+        this.viewGen = next;
+      } catch (err) {
+        this.bundleError = failureOf(err);
+        this.log(`${this.name}: keeping the last view. ${formatFailure(this.bundleError)}`);
+      }
+    } else { this.bundle_ = null; this.bundleError = null; }
+    this.gen = next;
+    this.wake();
+    this.onGeneration?.(next);
+  }
+
+  /** Stops everything; the state is written once more. */
+  async stop(): Promise<void> {
+    this.stopping = true;
+    this.cancelLoad?.(new NodeError("closed", "node is stopping"));
+    this.builder.stop();
+    this.watcher?.close(); this.watcher = null;
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; }
+    let cleaned = false;
+    try {
+      // A rejected load must not prevent cleanup of the old generation.
+      await this.loading?.catch(() => {});
+      const live = this.live;
+      this.live = null;
+      if (live) await this.destruct(live);
+      await Promise.all([...this.retiring].map((old) => this.destruct(old)));
+      if (this.cleanupFailure) throw this.cleanupFailure;
+      cleaned = true;
+    } finally {
+      for (const p of this.pending.values()) p.reject(new NodeError("closed", "node stopped"));
+      this.pending.clear();
+      if (cleaned) { this.last = null; this.lock?.release(); this.lock = null; }
+      this.stopping = false;
+      this.wake();
+    }
+  }
+
+  /** A file under .baba changed: arm the reload. */
+  changed(relative: string): void {
+    const top = relative.split(sep)[0] ?? "";
+    if (IGNORED.includes(top)) return;
+    if (this.frozen) { if (!this.held) this.log(`${this.name}: changed on disk; kept for the restart, since ${this.frozen}`); this.held = true; return; }
+    if (this.timer) clearTimeout(this.timer);
+    this.timer = setTimeout(() => void this.reload(), QUIET_MS);
+  }
+
+  /** The jobs running now of effects not safe to repeat, named: what a reload must not cut. */
+  private unrepeatable(): string[] {
+    const m = this.live?.manifest;
+    if (!m) return [];
+    return (this.last?.jobs ?? []).filter((j) => j.status === "running" && m.effects[j.effect]?.repeat === false).map((j) => `${j.effect}${j.entity === null ? "" : ` on ${j.entity}`}`);
+  }
+
+  /** Stops loading changes: the generation that runs keeps running, and a change on disk waits for the restart. */
+  freeze(why: string): void {
+    this.frozen = why;
+    if (this.timer) { clearTimeout(this.timer); this.timer = null; this.held = true; }
+  }
+
+  private settle(m: Result) {
+    const p = this.pending.get(m.id);
+    if (!p) return;
+    this.pending.delete(m.id);
+    if (m.ok) p.resolve({ value: m.value, round: m.round }); else p.reject(new NodeError(m.code, m.error));
+  }
+
+  private waitReload(): void {
+    this.waiting = true;
+    if (this.timer) clearTimeout(this.timer);
+    if (!this.stopping) this.timer = setTimeout(() => void this.reload(), WAIT_MS);
+  }
+
+  /** A dead generation rejects its callers and drains its owned services. */
+  private closed(from: Live, error: Error): void {
+    if (from.closed) return;
+    from.closed = error;
+    from.active = false;
+    from.activated?.reject(error);
+    from.onRetired?.({ errors: [], snapshot: from.last });
+    for (const r of from.open.values()) r.ctl.abort();
+    for (const [id, p] of this.pending) if (p.from === from) { this.pending.delete(id); p.reject(error); }
+    if (this.live === from) { this.live = null; this.error = error.message; }
+    from.transport.close();
+    this.retire(from);
+  }
+
+  private retire(old: Live) {
+    if (old.inflight === 0) void this.destruct(old).catch((e) => { this.cleanupFailure = e; this.log(`${this.name}: cleanup failed: ${e}`); });
+  }
+
+  /** Conditional retirement checks live jobs atomically inside the runtime. */
+  private destruct(old: Live, unlessBusy = false): Promise<void> {
+    if (old.destruction) return old.destruction;
+    this.retiring.add(old);
+    old.destruction = (async () => {
+      const retired = old.closed ? { errors: [], snapshot: old.last } : await new Promise<{ errors: string[]; snapshot: Snapshot | null; busy?: boolean }>((resolve) => {
+        const timer = setTimeout(() => resolve({ errors: ["the baba did not retire within 3s"], snapshot: null }), RETIRE_MS);
+        old.onRetired = (r) => { clearTimeout(timer); resolve(r); };
+        try { old.transport.send({ type: "retire", ...(unlessBusy ? { unlessBusy: true } : {}) }); }
+        catch (e) { clearTimeout(timer); resolve({ errors: [String(e)], snapshot: null }); }
+      });
+      old.onRetired = null;
+      if (retired.snapshot) { old.last = retired.snapshot; if (!this.live || this.live === old) this.last = retired.snapshot; }
+      if (retired.busy) throw new NodeError("reload-busy", "reload waits for nonrepeatable jobs");
+      old.active = false;
+      if (this.live === old) this.live = null;
+      for (const e of retired.errors) this.log(`${this.name}: ${e}`);
+      for (const r of old.open.values()) r.ctl.abort();
+      try { await Promise.all([...old.open.values()].map((r) => r.done)); }
+      finally { old.transport.close(); }
+    })().finally(() => { this.retiring.delete(old); });
+    // A busy response leaves the generation live and allows explicit stop.
+    void old.destruction.catch((e) => { if (e instanceof NodeError && e.code === "reload-busy") old.destruction = undefined; });
+    return old.destruction;
+  }
+
+  private watch() {
+    if (this.watcher) return;
+    try {
+      this.watcher = watch(this.project.baba, { recursive: true }, (_, file) => { if (file) this.changed(String(file)); });
+      this.watcher.unref();
+    } catch (err) {
+      this.log(`${this.name}: not watching: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}

package/src/baba/project.ts

@@ -0,0 +1,63 @@
+// A project as the kernel sees it: a directory with a .baba that holds the
+// baba's package.json, its entry index.ts and, when present, its interface.tsx (or the older view.tsx).
+import { resolve, join } from "node:path";
+import { stat } from "node:fs/promises";
+import type { BabaConfig } from "../kernel/context.ts";
+
+export interface Project {
+  /** `baba.name`, else the package's name: lowercase letters, digits and dashes. */
+  name: string;
+  title: string;
+  harnesses: string[];
+  /** The project directory. */
+  dir: string;
+  /** PROJECT/.baba */
+  baba: string;
+  /** The entry, .baba/index.ts: its default export is the baba. */
+  entry: string;
+  /** The interface, .baba/interface.tsx (or the older view.tsx), when the project has one. */
+  view: string | null;
+  build: { plugins: string[]; assets: string[] };
+}
+
+const NAME = /^[a-z][a-z0-9-]*$/;
+/** The page's own first segments: a baba's address is `/NAME/…`, so no baba is named one of them. */
+export const PAGE_WORDS = new Set(["api", "assets", "view", "ws"]);
+
+interface Pkg { name?: unknown; baba?: unknown; dependencies?: unknown; devDependencies?: unknown }
+
+async function readPkg(path: string): Promise<Pkg | null> {
+  const f = Bun.file(path);
+  if (!(await f.exists())) return null;
+  try { return (await f.json()) as Pkg; } catch (err) { throw new Error(`${path}: ${err instanceof Error ? err.message : String(err)}`); }
+}
+
+/** Reads PROJECT/.baba/package.json: `name` and the `baba` field; finds the entry and the view. */
+export async function openProject(dir: string): Promise<Project> {
+  dir = resolve(dir);
+  const baba = join(dir, ".baba");
+  const pkg = await readPkg(join(baba, "package.json"));
+  if (!pkg) throw new Error(`${dir} has no .baba/package.json`);
+  const v = (typeof pkg.baba === "object" && pkg.baba ? pkg.baba : {}) as BabaConfig;
+  const name = v.name ?? pkg.name;
+  if (typeof name !== "string" || !NAME.test(name)) throw new Error(`${baba}/package.json: "${v.name === undefined ? "name" : "baba.name"}" must be lowercase letters, digits and dashes`);
+  if (PAGE_WORDS.has(name)) throw new Error(`${baba}/package.json: a baba cannot be named ${name}, its address /${name}/ is the page's own (${[...PAGE_WORDS].join(", ")})`);
+  const title = v.title === undefined ? name : v.title;
+  if (typeof title !== "string") throw new Error(`${baba}/package.json: "baba.title" must be a string`);
+  const harnesses = v.harnesses === undefined ? ["claude", "codex"] : v.harnesses;
+  if (!Array.isArray(harnesses) || !harnesses.every((h) => typeof h === "string")) throw new Error(`${baba}/package.json: "baba.harnesses" must be a list of names`);
+  const b = v.build ?? {};
+  const strings = (x: unknown, what: string) => { if (x === undefined) return [] as string[]; if (!Array.isArray(x) || !x.every((s) => typeof s === "string")) throw new Error(`${baba}/package.json: "baba.build.${what}" must be a list of strings`); return x as string[]; };
+  const entry = join(baba, "index.ts");
+  if (!(await exists(entry))) throw new Error(`${baba} has no index.ts; the entry exports default baba({ systems: [...] })`);
+  const view = (await exists(join(baba, "interface.tsx"))) ? join(baba, "interface.tsx") : join(baba, "view.tsx");
+  // A baba that depends on bun-plugin-tailwind means it: the plugin runs without being declared again.
+  const plugins = strings(b.plugins, "plugins");
+  const deps = { ...(pkg.devDependencies as Record<string, unknown> | undefined), ...(pkg.dependencies as Record<string, unknown> | undefined) };
+  if ("bun-plugin-tailwind" in deps && !plugins.includes("bun-plugin-tailwind")) plugins.push("bun-plugin-tailwind");
+  return { name, title, harnesses, dir, baba, entry, view: (await exists(view)) ? view : null, build: { plugins, assets: strings(b.assets, "assets") } };
+}
+
+export async function exists(path: string): Promise<boolean> {
+  try { await stat(path); return true; } catch { return false; }
+}

package/src/baba/registry.ts

@@ -0,0 +1,35 @@
+// The root's registry of projects: DIR/projects.json, a list of directories.
+// Names are read from each project's package.json when it is opened.
+import { join, resolve } from "node:path";
+import { mkdir } from "node:fs/promises";
+
+export class Registry {
+  constructor(readonly dir: string) {}
+  private get path() { return join(this.dir, "projects.json"); }
+
+  async list(): Promise<string[]> {
+    const f = Bun.file(this.path);
+    if (!(await f.exists())) return [];
+    const j = (await f.json()) as { projects?: unknown };
+    return Array.isArray(j.projects) ? j.projects.filter((p): p is string => typeof p === "string") : [];
+  }
+
+  async add(dir: string): Promise<void> {
+    dir = resolve(dir);
+    const all = await this.list();
+    if (!all.includes(dir)) await this.write([...all, dir].sort());
+  }
+
+  async remove(dir: string): Promise<boolean> {
+    dir = resolve(dir);
+    const all = await this.list();
+    if (!all.includes(dir)) return false;
+    await this.write(all.filter((d) => d !== dir));
+    return true;
+  }
+
+  private async write(projects: string[]): Promise<void> {
+    await mkdir(this.dir, { recursive: true });
+    await Bun.write(this.path, JSON.stringify({ projects }, null, 2) + "\n");
+  }
+}

package/src/baba/worker.ts

@@ -0,0 +1,55 @@
+// The worker a baba runs in without the wall: the entry imported from disk.
+// For tests and the in-process path; the walled runtime gets a bundle.
+// Messages in: load-dir {dir, snapshot}, then the kernel's. Out: the runtime's.
+import { plugin as bunPlugin } from "bun";
+import { dirname, join } from "node:path";
+import type { ToRuntime, FromRuntime } from "../transport/messages.ts";
+import type { Snapshot } from "../ecs/state.ts";
+import { isBaba } from "../ecs/baba.ts";
+import { openProject } from "./project.ts";
+import { readEnv } from "../runtime/env.ts";
+import { Harness } from "../runtime/harness.ts";
+import { PROTOCOL } from "../transport/messages.ts";
+
+declare const self: Worker;
+
+// The running voss is the framework: "babavoss" in a baba resolves to it,
+// never to a second copy under the project's node_modules.
+const root = dirname(dirname(dirname(Bun.fileURLToPath(import.meta.url))));
+const names: Record<string, string> = {
+  "babavoss": join(root, "index.ts"),
+  "babavoss/desktop": join(root, "src/desktop/index.ts"),
+  "babavoss/kit": join(root, "src/kit/index.ts"),
+  "babavoss/prompt": join(root, "src/prompt/index.ts"),
+  "babavoss/prompt/jsx-runtime": join(root, "src/prompt/jsx-runtime.ts"),
+  "babavoss/prompt/jsx-dev-runtime": join(root, "src/prompt/jsx-dev-runtime.ts"),
+  "babavoss/test": join(root, "src/test/index.ts"),
+  "babavoss/bench": join(root, "src/bench/index.ts"),
+};
+bunPlugin({
+  name: "babavoss",
+  setup(b) { for (const [name, path] of Object.entries(names)) b.module(name, async () => ({ exports: await import(path), loader: "object" })); },
+});
+
+export type ToWorker = Exclude<ToRuntime, { type: "load" }> | { type: "load-dir"; dir: string; snapshot: Snapshot | null; prepare?: boolean };
+export type FromWorker = FromRuntime;
+
+const post = (m: FromWorker) => self.postMessage(m);
+const h = new Harness(post);
+post({ type: "hello", protocol: PROTOCOL, role: "runtime" });
+
+self.onmessage = async (e: MessageEvent<ToWorker>) => {
+  const m = e.data;
+  if (m.type === "load-dir") {
+    try {
+      const project = await openProject(m.dir);
+      const mod = (await import(`${project.entry}?t=${Date.now()}`)) as { default?: unknown };
+      if (!isBaba(mod.default)) throw new Error(`${project.entry}: the default export is not a baba(); export default baba({ systems: [...] })`);
+      h.load(mod.default, { name: project.name, dir: project.dir, baba: project.baba }, await readEnv(project.baba), m.snapshot, m.prepare);
+    } catch (err) {
+      post({ type: "failed", error: err instanceof Error ? err.message : String(err) });
+    }
+    return;
+  }
+  await h.handle(m);
+};

package/src/bench/index.ts

@@ -0,0 +1,6 @@
+// babavoss/bench: the framework's own measuring kit. A scenario is a baba
+// seeded to a size; a measurement runs it for rounds with knobs set and
+// answers the round times, the bytes each round shipped, the heap. The lab
+// baba (babavoss/lab) shows measurements; the Lab’s `bench-start` capability runs them.
+export { measure, type Knobs, type Measurement, type Summary, type Sample } from "./measure.ts";
+export { scenarios, rng, type Scenario } from "./scenarios.ts";