babavoss 0.0.1 → 0.0.2

package/src/bench/measure.ts

@@ -0,0 +1,132 @@
+// One controlled measurement: a scenario at a size, run for a number of
+// rounds with the knobs set, timed round by round, and followed the way a
+// view follows: each round's answer made by the runtime, shipped as a frame
+// of bytes (or as JSON, by a knob), applied to a replica and read as the
+// view would read it. The same seed
+// gives the same state, so two measurements differ only in what the lab
+// changed: the knobs, or the framework underneath.
+import { Runtime } from "../ecs/runtime.ts";
+import { Replica } from "../ecs/replica.ts";
+import { decodeFrame, encodeFrame } from "../ecs/codec.ts";
+import type { StateAnswer } from "../ecs/snapshot.ts";
+import { scenarios, rng } from "./scenarios.ts";
+
+/** What a measurement may vary without changing the code. */
+export interface Knobs {
+  /** Every write checked against its schema, as a testbed does; off is how the runtime runs. */
+  checking?: boolean;
+  /** Ship each follower the whole state after each round instead of its delta: what every round cost before deltas. */
+  whole?: boolean;
+  /** How many followers take each round's answer, each with its own replica; 1 by default. The follower costs are summed over them. */
+  followers?: number;
+  /** Ship each round as JSON text, as the long poll did, instead of as a frame of bytes. */
+  json?: boolean;
+  /** The audit of what changed, at each round's end; on by default, as the runtime runs. */
+  audit?: boolean;
+  /** The round's virtual time step, ms; 200 by default. */
+  tick?: number;
+  seed?: number;
+}
+
+/**
+ * One round: what it cost the runtime (`ms`), and what following it cost:
+ * the answer made and serialized (`stateMs`, `bytes`), parsed and applied
+ * to the replica (`applyMs`), read by the view's query (`readMs`).
+ */
+export interface Sample { round: number; ms: number; bytes: number; heap: number; stateMs: number; applyMs: number; readMs: number }
+
+export interface Summary {
+  rounds: number; entities: number;
+  avgMs: number; p50Ms: number; p95Ms: number; maxMs: number; totalMs: number;
+  avgBytes: number; totalBytes: number;
+  /** Following, per round: the answer made, applied, read; and their sum. */
+  avgStateMs: number; avgApplyMs: number; avgReadMs: number; avgFollowMs: number; p95FollowMs: number;
+  /** Heap in use after a collection before the rounds, after them, and the highest seen between. */
+  heapStart: number; heapEnd: number; heapPeak: number;
+  /** How much the rounds left behind: heapEnd - heapStart. */
+  retained: number;
+  seedMs: number;
+}
+
+export interface Measurement { scenario: string; size: number; knobs: Knobs; summary: Summary; series: Sample[]; at: number; runtime: string }
+
+// The host, when there is one: a baba bundle may not name process or Bun, and a browser has neither.
+const host = globalThis as unknown as { process?: { memoryUsage?: () => { heapUsed: number } }; Bun?: { gc?: (sync: boolean) => void; version?: string } };
+const heapNow = () => host.process?.memoryUsage?.().heapUsed ?? 0;
+const gc = () => { host.Bun?.gc?.(true); };
+const quantile = (xs: number[], q: number) => { const a = [...xs].sort((x, y) => x - y); return a.length ? a[Math.min(a.length - 1, Math.floor(q * a.length))]! : 0; };
+const mean = (xs: number[]) => xs.reduce((a, b) => a + b, 0) / Math.max(1, xs.length);
+
+/** Runs the scenario and answers what it cost; `points` bounds the series kept. */
+export function measure(scenario: string, size: number, rounds: number, knobs: Knobs = {}, points = 200): Measurement {
+  const sc = scenarios[scenario];
+  if (!sc) throw new Error(`no scenario ${scenario}; scenarios: ${Object.keys(scenarios).join(", ")}`);
+  const tick = knobs.tick ?? 200, followers = Math.max(1, knobs.followers ?? 1);
+  let now = 1_000;
+  const rt = new Runtime(sc.baba, { auto: false, now: () => now, audit: knobs.audit !== false });
+  rt.w.checking = knobs.checking === true;
+  const seeded = performance.now();
+  sc.seed(rt, size, rng(knobs.seed ?? 1));
+  const seedMs = performance.now() - seeded;
+  rt.step(now);   // the first round seeds the scenario's own random and settles the arrivals
+  // The followers: each holds a replica and takes every round's answer, as a view does: the whole on first contact, then deltas.
+  const views = Array.from({ length: followers }, () => ({ since: 0, replica: new Replica() }));
+  const follow = () => {
+    let bytes = 0, stateMs = 0, applyMs = 0, readMs = 0;
+    for (const v of views) {
+      const t0 = performance.now();
+      let shipped: number, t1: number, parsed: StateAnswer;
+      if (knobs.json) {
+        const answer: StateAnswer = knobs.whole ? rt.snapshot({ redacted: true }) : rt.state(v.since, { redacted: true });
+        const text = JSON.stringify(answer);
+        shipped = text.length; t1 = performance.now();
+        parsed = JSON.parse(text) as StateAnswer;
+      } else {
+        const frame = knobs.whole ? encodeFrame(rt.codec, rt.snapshot({ redacted: true })) : rt.frame(v.since);
+        shipped = frame.byteLength; t1 = performance.now();
+        parsed = decodeFrame(rt.codec, frame);
+      }
+      v.replica = v.replica.apply(parsed);
+      v.since = rt.round;
+      const t2 = performance.now();
+      sc.view(v.replica);
+      const t3 = performance.now();
+      bytes += shipped; stateMs += t1 - t0; applyMs += t2 - t1; readMs += t3 - t2;
+    }
+    return { bytes, stateMs, applyMs, readMs };
+  };
+  follow();
+  gc();
+  const heapStart = heapNow();
+  let heapPeak = heapStart;
+  const series: Sample[] = [];
+  const ms: number[] = [], stateMs: number[] = [], applyMs: number[] = [], readMs: number[] = [];
+  let totalBytes = 0;
+  const every = Math.max(1, Math.floor(rounds / points));
+  for (let r = 1; r <= rounds; r++) {
+    now += tick;
+    const t0 = performance.now();
+    rt.step(now);
+    const dt = performance.now() - t0;
+    const f = follow();
+    ms.push(dt); stateMs.push(f.stateMs); applyMs.push(f.applyMs); readMs.push(f.readMs);
+    totalBytes += f.bytes;
+    if (r % every === 0 || r === rounds) {
+      const heap = heapNow();
+      if (heap > heapPeak) heapPeak = heap;
+      series.push({ round: rt.round, ms: dt, bytes: f.bytes, heap, stateMs: f.stateMs, applyMs: f.applyMs, readMs: f.readMs });
+    }
+  }
+  gc();
+  const heapEnd = heapNow();
+  const followMs = ms.map((_, i) => stateMs[i]! + applyMs[i]! + readMs[i]!);
+  const summary: Summary = {
+    rounds, entities: rt.w.all().length,
+    avgMs: mean(ms), p50Ms: quantile(ms, 0.5), p95Ms: quantile(ms, 0.95), maxMs: Math.max(0, ...ms), totalMs: ms.reduce((a, b) => a + b, 0),
+    avgBytes: totalBytes / Math.max(1, rounds), totalBytes,
+    avgStateMs: mean(stateMs), avgApplyMs: mean(applyMs), avgReadMs: mean(readMs), avgFollowMs: mean(followMs), p95FollowMs: quantile(followMs, 0.95),
+    heapStart, heapEnd, heapPeak: Math.max(heapPeak, heapEnd), retained: heapEnd - heapStart, seedMs,
+  };
+  rt.stop();
+  return { scenario, size, knobs, summary, series, at: Date.now(), runtime: host.Bun?.version ? `bun ${host.Bun.version}` : "js" };
+}

package/src/bench/scenarios.ts

@@ -0,0 +1,136 @@
+// The workloads the lab measures: each a baba and a way to seed it to a
+// size, deterministic from a seed so two runs differ only in what the lab
+// changed. Pure ECS: no port, no view.
+import { baba, resource } from "../ecs/baba.ts";
+import { system } from "../ecs/system.ts";
+import { s } from "../kernel/schema.ts";
+import { not, added, removed, changed, select } from "../ecs/state.ts";
+import type { Baba } from "../ecs/baba.ts";
+import type { Runtime } from "../ecs/runtime.ts";
+import type { Replica } from "../ecs/replica.ts";
+export { not, added, removed, changed, select };
+
+/** A deterministic random: the same seed, the same state. */
+export function rng(seed: number): () => number {
+  let x = seed >>> 0 || 1;
+  return () => { x ^= x << 13; x >>>= 0; x ^= x >>> 17; x ^= x << 5; x >>>= 0; return x / 4294967296; };
+}
+
+export interface Scenario {
+  name: string;
+  summary: string;
+  baba: Baba;
+  /** Fills the state to `size` entities, with `random` for the positions and the like. */
+  seed(rt: Runtime, size: number, random: () => number): void;
+  /** What a view of it reads each round: the rows it would draw. */
+  view(r: Replica): void;
+}
+
+const W = 600, H = 400;
+const dist = (a: { x: number; y: number }, b: { x: number; y: number }) => Math.hypot(a.x - b.x, a.y - b.y);
+
+/** The pond: every fish moves every round; a tenth as much food; fish seek, eat, food rots. The demo's system, made deterministic. */
+let pondRandom = rng(1);
+const pond = system({
+  name: "pond",
+  model: {
+    fish: { x: s.number(), y: s.number(), vx: s.number(), vy: s.number(), hunger: s.number() },
+    food: { x: s.number(), y: s.number(), at: s.integer() },
+    target: { food: s.entity("food") },
+    fed: resource(s.integer(), 0), seed: resource(s.integer(), 1),
+  },
+}, (pond, p) => {
+  const idle = select(pond.fish, not(pond.target));
+  const chasing = select(pond.fish, pond.target);
+  return [
+    p.step("seek", (w) => {
+      let freed = false;
+      w.each([removed(pond.food)], (gone) => { w.each(chasing, (e, _, t) => { if (t.food === gone) { w.remove(e, pond.target); freed = true; } }); });
+      if (!freed && w.query(added(pond.food)).length === 0 && w.query(removed(pond.target)).length === 0) return;
+      const foods = w.query(pond.food);
+      if (foods.length === 0) return;
+      w.each(idle, (e, f) => {
+        let best = foods[0]!, bestD = Infinity;
+        for (const c of foods) { const d = dist(f, c.food); if (d < bestD) { best = c; bestD = d; } }
+        w.add(e, pond.target, { food: best.entity });
+      });
+    }),
+
+    p.step("swim", (w) => {
+      if (w.round === 1) pondRandom = rng(w.get(pond.seed));   // before the first round's early return: the sequence starts over for every measurement
+      const dt = Math.min(w.elapsed / 1000, 0.5);
+      if (dt <= 0) return;
+      w.each([pond.fish], (e, r) => {
+        let { x, y, vx, vy, hunger } = r;
+        const t = w.get(e, pond.target);
+        const goal = t && w.get(t.food, pond.food);
+        if (goal) { const d = dist(r, goal) || 1; vx = (goal.x - x) / d * 140; vy = (goal.y - y) / d * 140; }
+        else { const a = Math.atan2(vy, vx) + (pondRandom() - 0.5) * 1.2; vx = Math.cos(a) * 60; vy = Math.sin(a) * 60; }
+        x += vx * dt; y += vy * dt;
+        if (x < 0) { x = 0; vx = Math.abs(vx); } else if (x > W) { x = W; vx = -Math.abs(vx); }
+        if (y < 0) { y = 0; vy = Math.abs(vy); } else if (y > H) { y = H; vy = -Math.abs(vy); }
+        w.add(e, pond.fish, { x, y, vx, vy, hunger: hunger + dt });
+      });
+    }),
+
+    p.step("eat", (w) => {
+      w.each([changed(pond.fish), pond.target], (e, r, t) => {
+        const f = w.get(t.food, pond.food);
+        if (!f || dist(r, f) > 12) return;
+        w.despawn(t.food);
+        w.remove(e, pond.target);
+        w.update(e, pond.fish, (x) => ({ ...x, hunger: 0 }));
+        w.update(pond.fed, (n) => n + 1);
+      });
+    }),
+
+    p.step("rot", (w) => { w.each([pond.food], (e, f) => { if (w.now - f.at > 30_000) w.despawn(e); }); }),
+  ];
+});
+
+/** Churn: a tenth of the items change a value each round, a twentieth gain or lose a tag: what a reconciling system does. */
+let churnRandom = rng(1);
+const churn = system({
+  name: "churn",
+  model: { item: { n: s.integer(), text: s.string() }, hot: s.tag(), seed: resource(s.integer(), 1) },
+}, (churn, p) => [
+  p.step("move", (w) => {
+    if (w.round === 1) churnRandom = rng(w.get(churn.seed));
+    w.each([churn.item], (e, v) => {
+      const r = churnRandom();
+      if (r < 0.1) w.add(e, churn.item, { n: v.n + 1, text: v.text });
+      else if (r < 0.15) { if (w.has(e, churn.hot)) w.remove(e, churn.hot); else w.add(e, churn.hot); }
+    });
+  }),
+  p.step("count", (w) => { let n = 0; w.each([churn.hot], () => { n++; }); void n; }),
+]);
+
+/** Quiet: items that never change; a step that reads them all: the floor of a round, and what a delta costs when nothing moved. */
+const quiet = system({ name: "quiet", model: { item: { n: s.integer() } } }, (quiet, p) => [
+  p.step("read", (w) => { let n = 0; w.each([quiet.item], (_, v) => { n += v.n; }); void n; }),
+]);
+
+export const scenarios: Record<string, Scenario> = {
+  pond: {
+    name: "pond", summary: "fish that all move every round, food a tenth as many; seek, eat, rot",
+    baba: baba({ systems: [pond] }),
+    seed(rt, size, random) {
+      const w = rt.w;
+      for (let i = 0; i < size; i++) { const a = random() * Math.PI * 2; w.spawn(pond.fish, { x: random() * W, y: random() * H, vx: Math.cos(a) * 60, vy: Math.sin(a) * 60, hunger: 0 }); }
+      for (let i = 0; i < Math.max(1, size / 10); i++) w.spawn(pond.food, { x: random() * W, y: random() * H, at: 0 });
+    },
+    view(r) { r.query(pond.fish); r.query(pond.food); },
+  },
+  churn: {
+    name: "churn", summary: "a tenth of the items rewritten and a twentieth tagged or untagged each round",
+    baba: baba({ systems: [churn] }),
+    seed(rt, size, random) { for (let i = 0; i < size; i++) rt.w.spawn(churn.item, { n: Math.floor(random() * 100), text: `item ${i}` }); },
+    view(r) { r.query(churn.item); r.query(churn.hot); },
+  },
+  quiet: {
+    name: "quiet", summary: "items that never change, read by one step: the floor",
+    baba: baba({ systems: [quiet] }),
+    seed(rt, size, random) { for (let i = 0; i < size; i++) rt.w.spawn(quiet.item, { n: Math.floor(random() * 100) }); },
+    view(r) { r.query(quiet.item); },
+  },
+};

package/src/build/builder.ts

@@ -0,0 +1,74 @@
+// What a build is, wherever it runs: the Builder a Node asks, the outputs
+// a build answers with, and the checks the kernel makes on them before
+// trusting a path. The in-process builder here is for tests and the worker
+// transport; the kernel's own runs a walled process (src/kernel/builder.ts).
+import { posix } from "node:path";
+import type { Project } from "../baba/project.ts";
+import { bundleProject } from "./project.ts";
+import { bundleView } from "./views.ts";
+
+/** One file a build produced, as bytes: its path under the view's URL, and its kind. */
+export interface BuildOutput {
+  path: string;
+  kind: "entry-point" | "chunk" | "asset" | "sourcemap" | "bytecode";
+  /** The media type to serve it with. */
+  type: string;
+  bytes: Uint8Array;
+}
+
+/** The view to build: where it is, where its outputs will be served, and what the project declared for the build. */
+export interface ViewSpec {
+  entry: string;
+  /** The project's .baba: paths in failures are relative to it; build plugins resolve from it; asset directories are under it. */
+  root: string;
+  publicPath: string;
+  dir: string;
+  plugins: string[];
+  assets: string[];
+}
+
+export interface Builder {
+  /** The baba's backend bundle: one module that serves itself in a Worker. */
+  project(p: Project): Promise<string>;
+  /** A view's bundle for the browser, every output; URLs inside it start with `publicPath`. */
+  view(spec: ViewSpec): Promise<BuildOutput[]>;
+  stop(): void;
+}
+
+export class InProcessBuilder implements Builder {
+  project(p: Project) { return bundleProject(p); }
+  async view(spec: ViewSpec) { return validateOutputs(await bundleView(spec)); }
+  stop() {}
+}
+
+export const limits = { count: 512, bytes: 256 * 1024 * 1024 };
+
+/**
+ * Outputs come from a process that ran the project's code: a path is
+ * trusted only when it is a plain relative one, once, and the whole fits.
+ */
+export function validateOutputs(outputs: BuildOutput[]): BuildOutput[] {
+  if (!Array.isArray(outputs) || outputs.length === 0) throw new Error("the build produced no outputs");
+  if (outputs.length > limits.count) throw new Error(`the build produced ${outputs.length} outputs; at most ${limits.count} are served`);
+  const seen = new Set<string>();
+  let total = 0;
+  let entries = 0;
+  for (const o of outputs) {
+    if (typeof o.path !== "string" || o.path === "" || o.path.startsWith("/") || posix.normalize(o.path) !== o.path || o.path.split("/").some((s) => s === "" || s === "." || s === "..")) {
+      throw new Error(`the build named an output ${JSON.stringify(o.path)}; outputs are plain relative paths`);
+    }
+    if (seen.has(o.path)) throw new Error(`the build named ${o.path} twice`);
+    seen.add(o.path);
+    if (!(o.bytes instanceof Uint8Array)) throw new Error(`the output ${o.path} is not bytes`);
+    total += o.bytes.byteLength;
+    if (o.kind === "entry-point") entries++;
+  }
+  if (total > limits.bytes) throw new Error(`the build produced ${(total / 1048576).toFixed(0)} MB; at most ${limits.bytes / 1048576} MB are served`);
+  if (entries !== 1) throw new Error(`the build produced ${entries} entry points; a view has one`);
+  return outputs;
+}
+
+/** The entry point's text. */
+export function entryOf(outputs: BuildOutput[]): string {
+  return new TextDecoder().decode(outputs.find((o) => o.kind === "entry-point")!.bytes);
+}

package/src/build/failure.ts

@@ -0,0 +1,78 @@
+// What went wrong with a view, in one shape from the bundler to the window:
+// where it failed, one line saying what, the place in the source when
+// there is one, and the rest for whoever wants it. Pure, so the GUI
+// and the kernel share it.
+
+export type Stage = "build" | "load" | "render";
+
+export interface ViewFailure {
+  stage: Stage;
+  /** One line, for a person. */
+  message: string;
+  /** The source file, relative to the project's `.baba` when it is inside. */
+  file?: string;
+  line?: number;
+  column?: number;
+  /** The source line, when the bundler had it. */
+  excerpt?: string;
+  /** Further messages, a stack, a component stack. */
+  detail?: string;
+}
+
+/** The bundler's message as Bun.build logs it. */
+interface Logged {
+  level?: string;
+  message: string;
+  position?: { file?: string; line?: number; column?: number; lineText?: string } | null;
+}
+
+/** A path under `root` as `root` sees it; anything else as it is. */
+export function within(root: string, file: string): string {
+  const base = root.endsWith("/") ? root : root + "/";
+  return file.startsWith(base) ? file.slice(base.length) : file;
+}
+
+/**
+ * A failed build as one failure: the first error is the headline, the
+ * others go to the detail, and paths inside the project lose their prefix.
+ */
+export function buildFailure(logs: readonly Logged[], root: string): ViewFailure {
+  const errors = logs.filter((l) => l.level === undefined || l.level === "error");
+  const [first, ...rest] = errors.length > 0 ? errors : logs;
+  const shorten = (s: string) => s.split(root.endsWith("/") ? root : root + "/").join("");
+  if (!first) return { stage: "build", message: "the bundler failed without a message" };
+  const f: ViewFailure = { stage: "build", message: shorten(first.message.replace(/^BuildMessage: /, "")) };
+  const p = first.position;
+  if (p?.file) {
+    f.file = within(root, p.file);
+    if (p.line) { f.line = p.line; if (p.column) f.column = p.column; }
+    if (p.lineText) f.excerpt = p.lineText;
+  }
+  if (rest.length > 0) f.detail = rest.map((l) => shorten(l.message) + (l.position?.file ? ` (${within(root, l.position.file)}${l.position.line ? `:${l.position.line}` : ""})` : "")).join("\n");
+  return f;
+}
+
+/** Where a failure points: `file:line:column`, as much as is known. */
+export function placeOf(f: ViewFailure): string | undefined {
+  if (!f.file) return undefined;
+  return f.file + (f.line ? `:${f.line}` + (f.column ? `:${f.column}` : "") : "");
+}
+
+/** The failure as text: for a log line, the shell, or a clipboard. */
+export function formatFailure(f: ViewFailure): string {
+  const head = { build: "The view did not build", load: "The view did not load", render: "The view crashed while rendering" }[f.stage];
+  const lines = [`${head}: ${f.message}`];
+  const place = placeOf(f);
+  if (place) lines.push(`  at ${place}`);
+  if (f.excerpt) {
+    lines.push(`  ${f.excerpt}`);
+    if (f.column) lines.push(`  ${" ".repeat(f.column - 1)}^`);
+  }
+  if (f.detail) lines.push("", f.detail);
+  return lines.join("\n");
+}
+
+/** A thrown failure, so a caller can tell one from any other error. */
+export class ViewFailed extends Error {
+  constructor(readonly failure: ViewFailure) { super(formatFailure(failure)); }
+}

package/src/build/guard.ts

@@ -0,0 +1,85 @@
+// The guard: what a baba may not reach for, and what it uses instead.
+// One list serves the generated declarations (.voss/guard.d.ts, where a
+// forbidden name has a type that says the alternative), the checker's
+// hints, and the bundler plugin that refuses the imports. It is the
+// experience, not the guarantee: the wall underneath holds either way.
+import { relative } from "node:path";
+
+/** A refusal: what to use instead, and the type name that says so in the checker's errors. */
+export interface Refusal {
+  /** What the baba uses instead, as written in the message. */
+  use: string;
+  /** The type the declaration carries, so the error names the alternative. */
+  type: string;
+}
+
+const context = "an effect's context (ctx.fs, ctx.http, ctx.exec, ctx.secrets)";
+const fs: Refusal = { use: "ctx.fs", type: "UseCtxFsInstead" };
+const exec: Refusal = { use: "ctx.exec", type: "UseCtxExecInstead" };
+const http: Refusal = { use: "ctx.http", type: "UseCtxHttpInstead" };
+const whole: Refusal = { use: context, type: "UseTheContextInstead" };
+
+/** Module specifiers a baba may not import, each with its alternative. */
+export const forbiddenModules: Record<string, Refusal> = {
+  "node:fs": fs, "fs": fs, "node:fs/promises": fs, "fs/promises": fs,
+  "node:child_process": exec, "child_process": exec, "bun:ffi": exec,
+  "bun:sqlite": whole,
+  "node:net": http, "net": http, "node:http": http, "http": http, "node:https": http, "https": http,
+  "node:os": whole, "os": whole, "node:process": whole, "process": whole,
+  "node:worker_threads": whole, "worker_threads": whole, "bun": whole, "bun:jsc": whole,
+};
+
+/** Global names a baba's backend does not have, each with its alternative. */
+export const forbiddenGlobals: Record<string, Refusal> = {
+  Bun: { use: context, type: "UseTheContextInsteadOfBun" },
+  fetch: { use: "ctx.http.fetch", type: "UseCtxHttpFetchInstead" },
+  process: { use: "ctx.env for the environment, ctx.exec for programs", type: "UseCtxEnvOrCtxExecInsteadOfProcess" },
+  require: { use: "import", type: "UseImportInsteadOfRequire" },
+  Worker: { use: "an effect, which the runtime runs outside the round", type: "UseAnEffectInsteadOfWorker" },
+  WebSocket: { use: "ctx.http", type: "UseCtxHttpInsteadOfWebSocket" },
+  Buffer: { use: "Uint8Array, TextEncoder and TextDecoder", type: "UseUint8ArrayInsteadOfBuffer" },
+  __dirname: { use: "ctx.project", type: "UseCtxProjectInsteadOfDirname" },
+  __filename: { use: "ctx.project", type: "UseCtxProjectInsteadOfFilename" },
+};
+
+/** The sentence every refusal ends with. */
+export function advice(r: Refusal): string {
+  return `a baba has no OS: use ${r.use} instead (see README.md)`;
+}
+
+const escape = (s: string) => s.replace(/[.*+?^${}()|[\]\\/]/g, "\\$&");
+const filter = new RegExp(`^(${Object.keys(forbiddenModules).map(escape).join("|")})$`);
+
+const where = (file: string) => {
+  const rel = relative(process.cwd(), file);
+  return rel && !rel.startsWith("..") ? rel : file;
+};
+/** An import attribute asking for a macro, in either spelling. */
+const macro = /\b(?:with|assert)\s*\{\s*type\s*:\s*["']macro["']\s*\}/;
+const refuse = (file: string, specifier: string) => new Error(`${where(file)} imports ${specifier}; ${advice(forbiddenModules[specifier]!)}`);
+
+/**
+ * The bundler's refusal: a Bun.build plugin that fails the build on a
+ * forbidden import with `<file> imports <specifier>; a baba has no OS: ...`.
+ * For the browser and node targets resolution reaches the import; for the
+ * bun target a builtin never does, so each source is also scanned on load.
+ */
+export const guardImports: import("bun").BunPlugin = {
+  name: "babavoss-guard",
+  setup(b) {
+    b.onResolve({ filter }, (a) => { throw refuse(a.importer || a.path, a.path); });
+    b.onLoad({ filter: /\.[cm]?[jt]sx?$/ }, async (a) => {
+      const ext = a.path.slice(a.path.lastIndexOf(".") + 1);
+      const loader = ext === "tsx" || ext === "jsx" ? ext : ext.endsWith("ts") ? "ts" : "js";
+      const text = await Bun.file(a.path).text();
+      // A macro import runs at build time, in the builder: a baba has no build-time OS either.
+      if (macro.test(text)) throw new Error(`${where(a.path)} imports a macro (with { type: "macro" }); a baba has no build step of its own: compute at run time, in an effect (see README.md)`);
+      // A file that does not parse is the bundler's to report, with its position.
+      let imports: { path: string }[];
+      try { imports = new Bun.Transpiler({ loader }).scanImports(text); } catch { return undefined; }
+      const bad = imports.find((i) => filter.test(i.path));
+      if (bad) throw refuse(a.path, bad.path);
+      return undefined;
+    });
+  },
+};

package/src/build/mdx-register.ts

@@ -0,0 +1,3 @@
+import { plugin } from "bun";
+import { promptMdx } from "./mdx.ts";
+plugin(promptMdx());

package/src/build/mdx.ts

@@ -0,0 +1,38 @@
+// MDX is compiled in the builder. Only the resulting prompt tree reaches the runtime.
+import { compile } from "@mdx-js/mdx";
+import gfm from "remark-gfm";
+import { forbiddenModules, advice } from "./guard.ts";
+
+function promptExport() {
+  return (tree: any) => {
+    const metadata = tree.body.some((n: any) => n.type === "ExportNamedDeclaration" && n.declaration?.type === "VariableDeclaration" && n.declaration.declarations.some((d: any) => d.id.name === "prompt"));
+    if (!metadata) throw new Error('MDX promptware needs an exported prompt metadata object');
+    const exported = tree.body.find((n: any) => n.type === "ExportDefaultDeclaration");
+    if (!exported || exported.declaration.type !== "FunctionDeclaration") throw new Error("MDX must export a document component");
+    const component = exported.declaration;
+    const id = (name: string) => ({ type: "Identifier", name });
+    const literal = (value: string) => ({ type: "Literal", value });
+    tree.body[tree.body.indexOf(exported)] = component;
+    tree.body.push({ type: "ImportDeclaration", source: literal("babavoss/prompt"), specifiers: [{ type: "ImportSpecifier", imported: id("mdxDocument"), local: id("$promptDocument") }] });
+    tree.body.push({ type: "ExportDefaultDeclaration", declaration: { type: "CallExpression", callee: id("$promptDocument"), arguments: [id("prompt"), id(component.id.name)], optional: false } });
+  };
+}
+
+export async function compilePromptMdx(value: string, path: string): Promise<string> {
+  const result = String(await compile({ value, path }, {
+    jsxImportSource: "babavoss/prompt", format: "mdx", development: false,
+    remarkPlugins: [gfm], recmaPlugins: [promptExport],
+  }));
+  // Bun's bun-target builtin imports can bypass onResolve: apply the same guard after MDX compilation.
+  for (const item of new Bun.Transpiler({ loader: "js" }).scanImports(result)) {
+    if (forbiddenModules[item.path]) throw new Error(`${path} imports ${item.path}; ${advice(forbiddenModules[item.path]!)}`);
+  }
+  if (/\b(?:with|assert)\s*\{\s*type\s*:\s*["']macro["']\s*\}/.test(result)) throw new Error(`${path}: macros are not allowed in promptware`);
+  return result;
+}
+
+export function promptMdx(files: Record<string, string> = {}): import("bun").BunPlugin {
+  return { name: "babavoss-prompt-mdx", setup(b) {
+    b.onLoad({ filter: /\.mdx$/ }, async ({ path }) => ({ contents: await compilePromptMdx(files[path] ?? await Bun.file(path).text(), path), loader: "js" }));
+  } };
+}

package/src/build/project.ts

@@ -0,0 +1,38 @@
+import { promptMdx } from "./mdx.ts";
+// A baba's backend as one text: its entry, the framework it imports and the
+// worker harness, bundled for the runtime, which has no file access. The
+// entry is virtual: it imports the baba and hands it to the harness, so the
+// text runs as a Worker.
+import { join } from "node:path";
+import type { Project } from "../baba/project.ts";
+import { aliasOf, loadBuildPlugins, resolver } from "./views.ts";
+import { framework } from "../kernel/where.ts";
+
+const harness = join(framework, "src/runtime/worker.ts");
+const ENTRY = "/babavoss/entry.ts";
+
+export async function bundleProject(project: Project): Promise<string> {
+  const text = [
+    `import v from ${JSON.stringify(project.entry)};`,
+    `import { serve } from ${JSON.stringify(harness)};`,
+    `export default v;`,
+    `serve(v);`,
+  ].join("\n") + "\n";
+  const extra = project.build.plugins.length ? await loadBuildPlugins(project.build.plugins, project.baba, project.baba) : [];
+  const r = await Bun.build({
+    entrypoints: [ENTRY],
+    files: { [ENTRY]: text },
+    target: "bun", format: "esm",
+    plugins: [promptMdx(), resolver, aliasOf(project.baba), ...extra],
+    define: { "process.env.NODE_ENV": '"production"' },
+    throw: false,
+  });
+  if (!r.success) throw new Error(r.logs.filter((l) => l.level === "error").map(explain).join("\n"));
+  return await r.outputs[0]!.text();
+}
+
+/** One build error as the editor would show it: where, then what. */
+function explain(l: Awaited<ReturnType<typeof Bun.build>>["logs"][number]): string {
+  const at = l.position ? `${l.position.file}:${l.position.line}:${l.position.column}: ` : "";
+  return `${at}${l.message}`;
+}