@akanjs/devkit 2.4.1-rc.3 → 2.4.1-rc.5

package/frontendBuild/sourceMtimeIndex.ts

@@ -0,0 +1,326 @@
+import type { Dirent, Stats } from "node:fs";
+import { readdir, stat } from "node:fs/promises";
+import path from "node:path";
+import { HmrChangeClassifier } from "./hmrChangeClassifier";
+
+interface TrackedFile {
+  mtimeMs: number;
+  size: number;
+}
+
+/**
+ * A directory the index could not read, held with this mtime so every subsequent scan sees a mismatch
+ * and retries it. `NaN !== NaN`, which is exactly the "always stale" semantics wanted here.
+ */
+const UNREADABLE = Number.NaN;
+
+export interface SourceMtimeIndexOptions {
+  roots: string[];
+  classifier?: HmrChangeClassifier;
+}
+
+/**
+ * A snapshot of every interesting source file's mtime under the watch roots, so the watcher can answer
+ * "what actually changed" without trusting `fs.watch` event payloads.
+ *
+ * Bun 1.3.14's recursive `fs.watch` on macOS reports roughly **one path per ~200ms coalescing window**
+ * and discards every other path changed in that window. Measured on this repo: saving 5 files together
+ * reports 1; saving 20 reports 2; a single unrelated write landing first in the window hides a
+ * concurrent save entirely. Node 22 reports all 20 on the same tree, so this is a Bun defect rather
+ * than an FSEvents limitation (`local/optimize-resource/06-watcher-dropped-event.md`).
+ *
+ * Re-stating the tracked set costs ~15ms against ~1300 source files here, where a fresh walk costs
+ * ~70ms — the walk has to visit ~40k entries (`ios/`, `android/`, `public/`) to find those 1300. So
+ * changes are found by re-stating known files plus re-reading only the directories whose own mtime
+ * moved, which is what adding or removing an entry bumps.
+ */
+export class SourceMtimeIndex {
+  readonly #roots: string[];
+  readonly #classifier: HmrChangeClassifier;
+  readonly #files = new Map<string, TrackedFile>();
+  readonly #dirs = new Map<string, number>();
+  readonly #unreadable = new Map<string, string>();
+  #primed = false;
+  #queue: Promise<unknown> = Promise.resolve();
+
+  constructor({ roots, classifier }: SourceMtimeIndexOptions) {
+    this.#roots = SourceMtimeIndex.#pruneNestedRoots(roots);
+    this.#classifier = classifier ?? new HmrChangeClassifier();
+  }
+
+  get primed(): boolean {
+    return this.#primed;
+  }
+
+  get trackedFileCount(): number {
+    return this.#files.size;
+  }
+
+  /**
+   * Paths the index currently cannot read, as `{ path, code }`. Non-empty means change detection has a
+   * blind spot right now: anything edited underneath one of these is not reported until it recovers.
+   *
+   * Worth surfacing rather than swallowing, because the failure is silent by nature — a walk cannot tell
+   * how much it did not see. Each entry is retried on every scan and clears itself on success.
+   */
+  get coverageGaps(): { path: string; code: string }[] {
+    return [...this.#unreadable].map(([file, code]) => ({ path: file, code }));
+  }
+
+  /** Record the current state as the baseline. Reports nothing; call before the first `collectChanges`. */
+  async prime(): Promise<void> {
+    await this.#serialize(async () => {
+      this.#files.clear();
+      this.#dirs.clear();
+      this.#unreadable.clear();
+      await Promise.all(this.#roots.map((root) => this.#walk(root, null)));
+      this.#primed = true;
+    });
+  }
+
+  /**
+   * Absolute paths whose content changed (or which disappeared) since the last call, with the baseline
+   * advanced to match. Returns an empty list until primed, so a failed prime degrades to watcher events
+   * rather than reporting the entire tree as changed.
+   */
+  async collectChanges(): Promise<string[]> {
+    return this.#serialize(async () => {
+      if (!this.#primed) return [];
+      const changed = new Set<string>();
+      await this.#collectFileChanges(changed);
+      await this.#collectDirChanges(changed);
+      return [...changed];
+    });
+  }
+
+  /**
+   * Every scan runs to completion before the next begins.
+   *
+   * Overlapping scans corrupt each other rather than merely racing: one advances the baseline and prunes
+   * entries while the other is midway through a key snapshot it took earlier, so a path the first has
+   * already accounted for reads back as missing and is reported as a change that never happened. Observed
+   * directly — a file nothing had written was reported, which downstream is a wasted rebuild.
+   */
+  async #serialize<T>(work: () => Promise<T>): Promise<T> {
+    const run = this.#queue.then(work, work);
+    // Swallowed on the chain only; the caller still sees the rejection through `run`.
+    this.#queue = run.catch(() => undefined);
+    return run;
+  }
+
+  /**
+   * Adopt writes the caller made itself — regenerated barrels, inserted imports — into the baseline so
+   * the next `collectChanges` does not report them as a user edit.
+   *
+   * Narrow race worth knowing: a user save of the same path landing between the caller's write and this
+   * call is baselined too, and therefore lost. It is sub-millisecond and no wider than the window the
+   * event-based watcher already had.
+   */
+  async absorb(paths: string[]): Promise<void> {
+    await this.#serialize(async () => {
+      if (!this.#primed) return;
+      await Promise.all(
+        paths.map(async (file) => {
+          const abs = path.resolve(file);
+          const stats = await stat(abs).catch(() => null);
+          if (!stats?.isFile()) {
+            this.#files.delete(abs);
+            return;
+          }
+          this.#files.set(abs, { mtimeMs: stats.mtimeMs, size: stats.size });
+        }),
+      );
+    });
+  }
+
+  async #collectFileChanges(changed: Set<string>): Promise<void> {
+    await Promise.all(
+      [...this.#files.keys()].map(async (abs) => {
+        const { stats, err } = await SourceMtimeIndex.#statPath(abs);
+        if (!stats) {
+          // Unreadable is not deleted. Dropping it here would both invent a change nobody made and stop
+          // tracking the file, so a later real edit would go unreported.
+          if (err && !SourceMtimeIndex.#isMissing(err)) {
+            this.#unreadable.set(abs, err.code ?? "EUNKNOWN");
+            return;
+          }
+          this.#files.delete(abs);
+          this.#unreadable.delete(abs);
+          changed.add(abs);
+          return;
+        }
+        this.#unreadable.delete(abs);
+        if (!stats.isFile()) {
+          this.#files.delete(abs);
+          changed.add(abs);
+          return;
+        }
+        const known = this.#files.get(abs);
+        if (known && known.mtimeMs === stats.mtimeMs && known.size === stats.size) return;
+        this.#files.set(abs, { mtimeMs: stats.mtimeMs, size: stats.size });
+        changed.add(abs);
+      }),
+    );
+  }
+
+  /**
+   * A directory's own mtime moves when an entry is added or removed but not when a tracked file's
+   * content changes, so this finds creations and deletions the file pass cannot see.
+   */
+  async #collectDirChanges(changed: Set<string>): Promise<void> {
+    const moved: string[] = [];
+    const gone: string[] = [];
+    await Promise.all(
+      [...this.#dirs.entries()].map(async ([dir, mtimeMs]) => {
+        const { stats, err } = await SourceMtimeIndex.#statPath(dir);
+        if (!stats?.isDirectory()) {
+          if (err && !SourceMtimeIndex.#isMissing(err)) {
+            this.#markUnreadable(dir, err);
+            return;
+          }
+          gone.push(dir);
+          return;
+        }
+        // `UNREADABLE` is NaN, so a directory retained from a failed read always mismatches and is
+        // rewalked here — that retry is what lets a transient failure recover on its own.
+        if (stats.mtimeMs !== mtimeMs) moved.push(dir);
+      }),
+    );
+    for (const dir of gone) this.#forget(dir);
+    // Sequential: a moved directory can reveal a new subtree, and walking those in order keeps the
+    // number of concurrent `readdir` calls proportional to the change rather than to the tree.
+    for (const dir of moved) await this.#walk(dir, changed);
+  }
+
+  /**
+   * Re-read one directory, tracking entries that are new or changed. Recurses only into subdirectories
+   * that are new to the index; known ones are covered by their own mtime check in `#collectDirChanges`.
+   */
+  async #walk(dir: string, changed: Set<string> | null): Promise<void> {
+    const [listing, dirStat] = await Promise.all([SourceMtimeIndex.#readdirPath(dir), SourceMtimeIndex.#statPath(dir)]);
+    const entries = listing.entries;
+    const dirStats = dirStat.stats;
+    if (!entries || !dirStats?.isDirectory()) {
+      // A directory that cannot be read is not a directory that is gone. Forgetting it here is
+      // unrecoverable: nothing re-stats a dir the index has dropped, and the parent's own mtime does not
+      // move when a child merely becomes unreadable, so the whole subtree stays invisible for the life of
+      // the process. Measured: one `EACCES` at prime silently hid 2 of 3 files, permanently.
+      const err = listing.err ?? dirStat.err;
+      if (err && !SourceMtimeIndex.#isMissing(err)) {
+        this.#markUnreadable(dir, err);
+        return;
+      }
+      this.#forget(dir);
+      return;
+    }
+    const known = this.#dirs.has(dir);
+    this.#dirs.set(dir, dirStats.mtimeMs);
+    this.#unreadable.delete(dir);
+    const descend: string[] = [];
+    const present = new Set<string>();
+    let blind = false;
+    for (const entry of entries) {
+      if (SourceMtimeIndex.#skipDirent(entry.name)) continue;
+      const abs = path.join(dir, entry.name);
+      if (entry.isDirectory()) {
+        descend.push(abs);
+        continue;
+      }
+      if (!entry.isFile()) continue;
+      if (this.#classifier.classify(abs) === "ignore") continue;
+      present.add(abs);
+      const { stats, err } = await SourceMtimeIndex.#statPath(abs);
+      if (!stats?.isFile()) {
+        // A file listed but not stat-able has no baseline, so an edit to it would compare against nothing.
+        // Leaving the directory stale is what brings it back; the file pass cannot, since it only revisits
+        // paths already tracked.
+        if (err && !SourceMtimeIndex.#isMissing(err)) {
+          this.#unreadable.set(abs, err.code ?? "EUNKNOWN");
+          blind = true;
+        }
+        continue;
+      }
+      this.#unreadable.delete(abs);
+      const previous = this.#files.get(abs);
+      if (previous && previous.mtimeMs === stats.mtimeMs && previous.size === stats.size) continue;
+      this.#files.set(abs, { mtimeMs: stats.mtimeMs, size: stats.size });
+      changed?.add(abs);
+    }
+    // Entries this directory used to hold and no longer does. Only worth scanning for a directory the
+    // index already knew, which during `prime` is none of them.
+    if (known) {
+      for (const abs of [...this.#files.keys()]) {
+        if (present.has(abs) || path.dirname(abs) !== dir) continue;
+        this.#files.delete(abs);
+        changed?.add(abs);
+      }
+    }
+    if (blind) this.#dirs.set(dir, UNREADABLE);
+    // Known subdirectories carry their own mtime check, so only unseen ones need walking. Concurrent
+    // because `prime` reaches every directory through here.
+    await Promise.all(descend.filter((sub) => !this.#dirs.has(sub)).map((sub) => this.#walk(sub, changed)));
+  }
+
+  /**
+   * Keep a directory the index could not read, flagged for retry on every scan, and keep whatever it
+   * already knows underneath it — those files stay tracked so a real edit is still caught the moment
+   * access returns.
+   */
+  #markUnreadable(dir: string, err: NodeJS.ErrnoException): void {
+    this.#dirs.set(dir, UNREADABLE);
+    this.#unreadable.set(dir, err.code ?? "EUNKNOWN");
+  }
+
+  /** Drop a directory and everything the index holds beneath it. */
+  #forget(dir: string): void {
+    const prefix = `${dir}${path.sep}`;
+    this.#dirs.delete(dir);
+    this.#unreadable.delete(dir);
+    for (const known of [...this.#dirs.keys()]) if (known.startsWith(prefix)) this.#dirs.delete(known);
+    // Otherwise a gap under a deleted directory is reported forever, since nothing revisits it to clear.
+    for (const known of [...this.#unreadable.keys()]) if (known.startsWith(prefix)) this.#unreadable.delete(known);
+  }
+
+  /** `null` stats with the errno kept, so callers can tell "not there" from "could not look". */
+  static async #statPath(abs: string): Promise<{ stats: Stats | null; err: NodeJS.ErrnoException | null }> {
+    try {
+      return { stats: await stat(abs), err: null };
+    } catch (err) {
+      return { stats: null, err: err as NodeJS.ErrnoException };
+    }
+  }
+
+  static async #readdirPath(dir: string): Promise<{ entries: Dirent[] | null; err: NodeJS.ErrnoException | null }> {
+    try {
+      return { entries: await readdir(dir, { withFileTypes: true }), err: null };
+    } catch (err) {
+      return { entries: null, err: err as NodeJS.ErrnoException };
+    }
+  }
+
+  /**
+   * Whether an errno means the path genuinely is not there, which is the only case where dropping it from
+   * the baseline is right. Everything else — `EACCES`, `EIO`, `EMFILE`, a stalled network mount — means the
+   * index failed to look, and treating that as a deletion both invents a change and blinds it to real ones.
+   */
+  static #isMissing(err: NodeJS.ErrnoException): boolean {
+    return err.code === "ENOENT" || err.code === "ENOTDIR";
+  }
+
+  /**
+   * Mirrors `HmrChangeClassifier`'s path rules for directory names — dotted names cover `.git` and
+   * `.akan`, which is where every build artifact lands. Symlinked entries are neither `isFile` nor
+   * `isDirectory` and so are skipped, matching `fs.watch`, which does not follow them either.
+   */
+  static #skipDirent(name: string): boolean {
+    return !name || name.startsWith(".") || name === "node_modules";
+  }
+
+  /** `WatchRootResolver` can return `apps/<app>/page` alongside `apps/`; walking both doubles the work. */
+  static #pruneNestedRoots(roots: string[]): string[] {
+    const resolved = [...new Set(roots.map((root) => path.resolve(root)))].sort();
+    return resolved.filter(
+      (root) => !resolved.some((other) => other !== root && root.startsWith(`${other}${path.sep}`)),
+    );
+  }
+}

package/incrementalBuilder/buildBatch.proc.ts

@@ -4,7 +4,13 @@ import type { App } from "@akanjs/devkit/commandDecorators";
 // eager import is paid on every save. Measured on a 177-route app: `executors` 24ms, `frontendBuild`
 // ~110ms, app config 5ms.
 import { AppExecutor, WorkspaceExecutor } from "@akanjs/devkit/executors";
-import { CsrArtifactBuilder, CssCompiler, FontOptimizer, PagesBundleBuilder } from "@akanjs/devkit/frontendBuild";
+import {
+  CsrArtifactBuilder,
+  CssCompiler,
+  FontOptimizer,
+  PagesBundleBuilder,
+  SsrBaseArtifactBuilder,
+} from "@akanjs/devkit/frontendBuild";
 import { Logger } from "akanjs/common";
 import type { BuilderMessage, BuildPhase } from "akanjs/server";
 import type { BuildBatchRequest, BuildBatchResult, OptimizedFonts, PagesBatchCssAssets } from "./buildBatchProtocol";
@@ -34,6 +40,8 @@ class BuildBatch {
   }
 
   async run(): Promise<BuildBatchResult> {
+    // `base` arrives alone, from a builder that cannot serve anything until it finishes.
+    if (this.#request.needs.includes("base")) await this.#buildBase();
     // Ordered the way the watcher used to run them: csr before pages so a csr failure cannot delay the
     // pages bundle the browser is waiting on, and css last because it depends on the rebuilt client.
     if (this.#request.needs.includes("csr")) await this.#buildCsr();
@@ -48,6 +56,12 @@ class BuildBatch {
    * never had, and it would move every artifact write into the window right before the watcher reports
    * the generation complete — which is where a save issued immediately afterwards gets dropped by Bun's
    * recursive `fs.watch` (`local/optimize-resource/06-watcher-dropped-event.md`).
+   *
+   * A bare `process.send` is safe here, unlike in the watcher, for one reason: this process ends by
+   * returning from `main`, and a natural exit flushes a pending ipc write (measured: 1MB delivered
+   * 20/20). It is `process.exit` that discards one — so adding an explicit exit to this file, at the end
+   * of `main` or anywhere after an emit, would silently start dropping `css-updated` payloads. Route
+   * sends through `BuilderChannel` if that ever becomes necessary.
    */
   #emit(message: BuilderMessage): void {
     process.send?.(message);
@@ -66,6 +80,25 @@ class BuildBatch {
     });
   }
 
+  /**
+   * The boot build. Streams nothing: a builder is not serving yet, so there is no phase board to update
+   * and no browser to reload — the watcher learns the outcome from the batch result, and a failure there
+   * is what puts it into degraded watch mode.
+   */
+  async #buildBase(): Promise<void> {
+    const started = Date.now();
+    try {
+      const { artifact, optimizedFonts } = await new SsrBaseArtifactBuilder(this.#app).build();
+      this.#result.artifact = artifact;
+      this.#result.optimizedFonts = optimizedFonts;
+      this.#logger.verbose(`base-artifact ok buildId=${artifact.pagesBundleBuildId} (${Date.now() - started}ms)`);
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err);
+      this.#logger.error(`base-artifact failed: ${message}`);
+      this.#result.errors.base = message;
+    }
+  }
+
   async #buildCsr(): Promise<void> {
     const started = Date.now();
     try {

package/incrementalBuilder/buildBatchProtocol.ts

@@ -1,9 +1,15 @@
 import type { FontOptimizer } from "@akanjs/devkit/frontendBuild";
-import type { CssPayload, PagesBundlePayload } from "akanjs/server";
+import type { BaseBuildArtifact, CssPayload, PagesBundlePayload } from "akanjs/server";
 
 export type OptimizedFonts = Awaited<ReturnType<FontOptimizer["optimize"]>>;
 
-export type BuildBatchNeed = "pages" | "css" | "csr";
+/**
+ * `base` is the boot build (`SsrBaseArtifactBuilder`) and is never batched with the others: it is what a
+ * builder runs before it can serve anything, where the rest are per-save work. It earns its place here
+ * for the same reason as the others — measured on `apps/akan`, it retains **+1143 MB** of bundler arena
+ * that only a process exit returns, which was 65 % of the builder's whole idle footprint.
+ */
+export type BuildBatchNeed = "base" | "pages" | "css" | "csr";
 
 /**
  * One generation of build work, handed to a process that exits when it is done.
@@ -44,6 +50,11 @@ export interface BuildBatchResult {
   generation: number;
   cssAssets?: PagesBatchCssAssets;
   optimizedFonts?: OptimizedFonts;
+  /**
+   * Present only for a `base` batch. The same object the worker wrote to `base-artifact.json`, returned
+   * here so the watcher does not have to read its own boot build back off disk.
+   */
+  artifact?: BaseBuildArtifact;
   errors: Partial<Record<BuildBatchNeed, string>>;
   /** The worker died before reporting, so it streamed no `build-status` of its own for these needs. */
   crashed?: boolean;

package/incrementalBuilder/builderChannel.test.ts

@@ -0,0 +1,144 @@
+import { afterEach, describe, expect, test } from "bun:test";
+import { mkdtemp, rm } from "node:fs/promises";
+import os from "node:os";
+import path from "node:path";
+import { BuilderChannel } from "./builderChannel";
+
+const tempDirs: string[] = [];
+
+afterEach(async () => {
+  for (const dir of tempDirs.splice(0)) await rm(dir, { recursive: true, force: true });
+});
+
+type SendMode = "drain" | "await" | "bare";
+
+/**
+ * Run a child that sends what the builder sends and then exits the way the recycle drain does, and
+ * report what the parent actually received.
+ *
+ * `payload` picks the message shape, because shape decides whether a bare send survives: `manifest` is a
+ * map of many short strings (a `build-route-res` delta), `css` is one long string (a base64 stylesheet).
+ */
+const sendThenExit = async (
+  bytes: number,
+  { mode, payload }: { mode: SendMode; payload: "manifest" | "css" },
+): Promise<Array<{ type?: string }>> => {
+  const dir = await mkdtemp(path.join(os.tmpdir(), "builder-channel-"));
+  tempDirs.push(dir);
+  const entry = path.join(dir, "child.ts");
+  const modulePath = JSON.stringify(path.join(import.meta.dir, "builderChannel"));
+  const build =
+    payload === "manifest"
+      ? [
+          'const chunk = "x".repeat(200);',
+          "const moduleMap: Record<string, string> = {};",
+          `for (let i = 0; i * 210 < ${bytes}; i++) moduleMap["chunk-" + i] = chunk;`,
+          'const msg = { type: "build-route-res", id: 7, ok: true, data: { ssrManifestDelta: moduleMap } };',
+        ]
+      : [
+          `const css = "y".repeat(${bytes});`,
+          'const msg = { type: "css-updated", data: { cssAssets: {}, cssBase64ByUrl: { "/a.css": css } } };',
+        ];
+  const sendLine = {
+    drain: "BuilderChannel.emit(msg as never);\nawait BuilderChannel.drain();",
+    await: "await BuilderChannel.send(msg as never);",
+    bare: "process.send?.(msg);",
+  }[mode];
+  await Bun.write(
+    entry,
+    [`import { BuilderChannel } from ${modulePath};`, ...build, sendLine, "process.exit(0);"].join("\n"),
+  );
+  const received: Array<{ type?: string }> = [];
+  const proc = Bun.spawn(["bun", entry], {
+    stdio: ["ignore", "inherit", "inherit"],
+    // The mode the dev host actually spawns the builder with; it changes where the loss cliff sits.
+    serialization: "advanced",
+    ipc: (message) => {
+      received.push(message as { type?: string });
+    },
+  });
+  await proc.exited;
+  // Messages land before the exit callback, never after, but leave room for a straggler to prove it.
+  await Bun.sleep(50);
+  return received;
+};
+
+describe("BuilderChannel", () => {
+  test("delivers a reply too large for the pipe buffer before the process exits", async () => {
+    expect(await sendThenExit(1_000_000, { mode: "await", payload: "manifest" })).toMatchObject([{ id: 7 }]);
+    // A manifest delta is usually well past the buffer, but the small case must keep working too.
+    expect(await sendThenExit(0, { mode: "await", payload: "manifest" })).toMatchObject([{ id: 7 }]);
+  });
+
+  test("a drained event survives the exit even though nobody awaited it", async () => {
+    // The event path: `css-updated` is relayed with no caller to await it, and the recycle drain exits
+    // milliseconds later. Only `drain()` stands between the two.
+    expect(await sendThenExit(200_000, { mode: "drain", payload: "css" })).toMatchObject([{ type: "css-updated" }]);
+  });
+
+  test("without the flush wait the same messages are lost, which is why this class exists", async () => {
+    // Controls, not requirements: if a future bun flushes ipc writes on exit, these fail and say so.
+    expect(await sendThenExit(1_000_000, { mode: "bare", payload: "manifest" })).toEqual([]);
+    // 20KB of css, far below the 64KB the manifest shape survives — one long string dies much earlier,
+    // so no size threshold would have been safe to special-case.
+    expect(await sendThenExit(20_000, { mode: "bare", payload: "css" })).toEqual([]);
+  });
+
+  test("drain resolves only once every tracked send has flushed", async () => {
+    const send = process.send;
+    const flushes: Array<() => void> = [];
+    try {
+      (process as { send?: unknown }).send = (_msg: unknown, _h: unknown, _o: unknown, cb: () => void) => {
+        flushes.push(cb);
+        return true;
+      };
+      BuilderChannel.emit({ type: "builder-ready" });
+      BuilderChannel.emit({ type: "builder-ready" });
+      let drained = false;
+      const draining = BuilderChannel.drain().then((count) => {
+        drained = true;
+        return count;
+      });
+      flushes[0]?.();
+      await Bun.sleep(1);
+      expect(drained).toBe(false);
+      flushes[1]?.();
+      expect(await draining).toBe(2);
+    } finally {
+      (process as { send?: unknown }).send = send;
+    }
+  });
+
+  test("a send started while draining is drained too", async () => {
+    const send = process.send;
+    const flushes: Array<() => void> = [];
+    try {
+      (process as { send?: unknown }).send = (_msg: unknown, _h: unknown, _o: unknown, cb: () => void) => {
+        flushes.push(cb);
+        return true;
+      };
+      BuilderChannel.emit({ type: "builder-ready" });
+      const draining = BuilderChannel.drain();
+      // What `#reportMetrics` does from a work item's `finally`, after the drain has begun.
+      BuilderChannel.emit({ type: "builder-metrics", data: { rssBytes: 1, generation: 1, workCount: 1 } });
+      for (let i = 0; i < 4 && flushes.length; i++) {
+        flushes.shift()?.();
+        await Bun.sleep(1);
+      }
+      expect(await draining).toBe(2);
+    } finally {
+      (process as { send?: unknown }).send = send;
+    }
+  });
+
+  test("resolves instead of hanging when there is no ipc channel", async () => {
+    const send = process.send;
+    try {
+      (process as { send?: typeof process.send }).send = undefined;
+      await BuilderChannel.send({ type: "build-csr-res", id: 1, ok: true });
+      expect(await BuilderChannel.drain()).toBe(0);
+    } finally {
+      (process as { send?: typeof process.send }).send = send;
+    }
+  });
+});

package/incrementalBuilder/builderChannel.ts

@@ -0,0 +1,72 @@
+import type { BuilderMessage } from "akanjs/server";
+
+/**
+ * Every message the builder sends its host, and the record of which of those writes have actually left
+ * the process.
+ *
+ * `process.exit` discards an ipc write that has not flushed, and this process exits routinely — the
+ * recycle that keeps its RSS under the ceiling ends in `process.exit(0)`. Whether a given message
+ * survives that depends on its *shape*, not only its size. Measured on bun 1.3.14 (darwin,
+ * `serialization: "advanced"`), send-then-exit-immediately, 20 rounds each:
+ *
+ * - one long string: 8KB delivered 20/20, 16KB delivered **0/20**
+ * - many short strings: 60KB delivered 20/20, 100KB delivered **0/20**
+ *
+ * `css-updated` is the first shape (a base64 stylesheet per url) and `build-route-res` the second (a
+ * manifest delta), so neither sits safely under a threshold worth relying on. Nothing here assumes one:
+ * every send reports when it flushed, and `drain` is what `shutdown` awaits before exiting.
+ *
+ * A natural exit does *not* have this problem — a process that simply returns from `main` flushes 1MB
+ * 20/20 — which is why the disposable build worker needs none of this. Only an explicit `process.exit`
+ * cuts a write short.
+ */
+export class BuilderChannel {
+  /**
+   * Bound so a runtime that ever stops invoking the flush callback costs one late message instead of
+   * wedging the shutdown drain until the host's kill watchdog fires.
+   */
+  static readonly #flushTimeoutMs = 5_000;
+  /** Sends that have not flushed yet; `drain` only ever needs to await them all. */
+  static readonly #flushing = new Set<Promise<void>>();
+
+  /** Send, and resolve once the write has left this process. */
+  static send(message: BuilderMessage): Promise<void> {
+    const send = process.send;
+    if (!send) return Promise.resolve();
+    const flushed = new Promise<void>((resolve) => {
+      const timer = setTimeout(resolve, BuilderChannel.#flushTimeoutMs);
+      // A failed send has nothing to retry: the host answers an unanswered request id itself when this
+      // process exits, and a lost event is superseded by the next generation's.
+      send.call(process, message, undefined, undefined, () => {
+        clearTimeout(timer);
+        resolve();
+      });
+    });
+    BuilderChannel.#flushing.add(flushed);
+    void flushed.then(() => BuilderChannel.#flushing.delete(flushed));
+    return flushed;
+  }
+
+  /**
+   * Send an event no caller awaits. Tracked exactly like `send`, which is the whole point: a relayed
+   * `css-updated` has nobody to await it, so `drain` is the only thing standing between it and the exit.
+   */
+  static emit(message: BuilderMessage): void {
+    void BuilderChannel.send(message);
+  }
+
+  /**
+   * Resolve once every send handed over so far has flushed, and report how many were still in flight.
+   * Sends started *while* draining are covered too — `#reportMetrics` can fire from a work item's
+   * `finally`, after the drain has already begun.
+   */
+  static async drain(): Promise<number> {
+    let flushed = 0;
+    while (BuilderChannel.#flushing.size) {
+      const pending = [...BuilderChannel.#flushing];
+      flushed += pending.length;
+      await Promise.all(pending);
+    }
+    return flushed;
+  }
+}