@akanjs/devkit 2.4.1-rc.4 → 2.4.1-rc.6

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;
+  }
+}

package/incrementalBuilder/incrementalBuilder.proc.ts

@@ -12,7 +12,6 @@ import {
   GraphClientEntryDiscovery,
   HmrWatcher,
   RouteClientBuilder,
-  SsrBaseArtifactBuilder,
   WatchRootResolver,
 } from "@akanjs/devkit/frontendBuild";
 import { Logger } from "akanjs/common";
@@ -27,7 +26,7 @@ import type {
 } from "akanjs/server";
 import type { BuildBatchNeed, BuildBatchRequest, BuildBatchResult, OptimizedFonts } from "./buildBatchProtocol";
 import { BuildBatchRunner } from "./buildBatchRunner";
-import { BuilderReply } from "./builderReply";
+import { BuilderChannel } from "./builderChannel";
 import { prepareDevWatchBatch } from "./devWatchBatch";
 
 interface IncrementalBuilderOptions {
@@ -89,7 +88,7 @@ class IncrementalBuilder {
    */
   async handleBuildRoute(msg: BuilderReq): Promise<void> {
     await this.#enqueueWork(`build-route:${msg.routeId}`, async () =>
-      BuilderReply.send(await this.#handleBuildRoute(msg)),
+      BuilderChannel.send(await this.#handleBuildRoute(msg)),
     );
   }
 
@@ -132,7 +131,7 @@ class IncrementalBuilder {
     { generation, ok, files, message }: { generation?: number; ok: boolean; files?: string[]; message?: string },
   ): void {
     if (typeof generation !== "number") return;
-    process.send?.({
+    BuilderChannel.emit({
       type: "build-status",
       data: {
         generation,
@@ -170,7 +169,7 @@ class IncrementalBuilder {
    */
   #reportMetrics(): void {
     if (!this.#idle || this.#shuttingDown) return;
-    process.send?.({
+    BuilderChannel.emit({
       type: "builder-metrics",
       data: { rssBytes: process.memoryUsage.rss(), generation: this.#generation, workCount: this.#workCount },
     });
@@ -195,7 +194,14 @@ class IncrementalBuilder {
     }
     await this.#workQueue.catch(() => undefined);
     await this.#cssRebuildQueue.catch(() => undefined);
-    this.#logger.info(`drained in ${Date.now() - started}ms; exiting for recycle`);
+    // Drained queues do not mean the host has the results. The events those work items produced are the
+    // largest messages this process sends, and `process.exit` discards an ipc write that has not
+    // flushed — a `css-updated` relayed milliseconds before this line would be dropped with no error
+    // anywhere, leaving the backend serving the previous bundle. See `BuilderChannel`.
+    const flushed = await BuilderChannel.drain();
+    this.#logger.info(
+      `drained in ${Date.now() - started}ms${flushed ? ` after flushing ${flushed} ipc write(s)` : ""}; exiting for recycle`,
+    );
     process.exit(0);
   }
 
@@ -311,7 +317,7 @@ class IncrementalBuilder {
 
     if (hasSyncErrors) {
       this.#sendBuildStatus("barrel", { generation, ok: false, files, message: indexSync.errors.join("\n") });
-      process.send?.(event);
+      BuilderChannel.emit(event);
       return;
     }
     if (indexSync.changedFiles.length > 0) this.#sendBuildStatus("barrel", { generation, ok: true, files });
@@ -347,7 +353,7 @@ class IncrementalBuilder {
       needs.push("css");
     }
 
-    process.send?.(event);
+    BuilderChannel.emit(event);
 
     if (needs.length > 0) await this.#runBatch({ generation, needs, changedFiles: files });
     // A css-only batch keeps its debounce: those arrive in bursts while a stylesheet is edited, and
@@ -374,15 +380,18 @@ class IncrementalBuilder {
   }): Promise<BuildBatchResult> {
     const started = Date.now();
     const result = await this.#batchRunner.run(await this.#batchRequest({ generation, needs, changedFiles }), (msg) =>
-      process.send?.(msg),
+      BuilderChannel.emit(msg),
     );
     if (result.optimizedFonts) this.#optimizedFonts = result.optimizedFonts;
     if (result.cssAssets) this.#artifact = { ...this.#artifact, cssAssets: result.cssAssets };
     // A worker that died before reporting streamed no build-status of its own, so report one per need
     // it was given: the generation must go red rather than look like it silently succeeded.
     if (result.crashed) {
+      // `base` is excluded because it is not a `BuildPhase`: a boot build has no phase board to fail, and
+      // it never travels through here — `#buildBootDeps` runs it and throws into the degraded-boot path.
       for (const need of needs)
-        this.#sendBuildStatus(need, { generation, ok: false, files: changedFiles, message: result.errors[need] });
+        if (need !== "base")
+          this.#sendBuildStatus(need, { generation, ok: false, files: changedFiles, message: result.errors[need] });
     }
     if (needs.includes("css")) this.#logger.verbose(`css-rebuild checked (${Date.now() - started}ms)`);
     return result;
@@ -413,7 +422,7 @@ class IncrementalBuilder {
 
   async boot(): Promise<void> {
     if (this.#watch) await this.installWatcher();
-    process.send?.({ type: "builder-ready" });
+    BuilderChannel.emit({ type: "builder-ready" });
     this.#logger.verbose(`ready (watch=${this.#watch})`);
   }
 
@@ -441,7 +450,9 @@ class IncrementalBuilder {
   async announceBootState(): Promise<void> {
     const generation = ++this.#generation;
     const reason = "builder-recycle" as const;
-    process.send?.({
+    // Awaited rather than emitted: this runs during a recycle, so the host may ask this builder to shut
+    // down at any moment, and "announced boot state" must mean the announcement left the process.
+    await BuilderChannel.send({
       type: "pages-updated",
       data: {
         bundlePath: this.#artifact.pagesBundlePath,
@@ -460,7 +471,7 @@ class IncrementalBuilder {
         ]),
       ),
     );
-    process.send?.({
+    await BuilderChannel.send({
       type: "css-updated",
       data: { cssAssets, cssBase64ByUrl, generation, changedFiles: [], reason },
     });
@@ -483,12 +494,12 @@ class IncrementalBuilder {
       const error = result.errors.csr;
       if (error) {
         this.#logger.error(`csr-build failed: ${error}`);
-        await BuilderReply.send({ type: "build-csr-res", id: msg.id, ok: false, error });
+        await BuilderChannel.send({ type: "build-csr-res", id: msg.id, ok: false, error });
         return;
       }
       this.#csrActive = true;
       this.#logger.info(`csr-build ok on demand (${Date.now() - started}ms); rebuilding CSR on every save now`);
-      await BuilderReply.send({ type: "build-csr-res", id: msg.id, ok: true });
+      await BuilderChannel.send({ type: "build-csr-res", id: msg.id, ok: true });
     });
   }
 
@@ -500,10 +511,40 @@ class IncrementalBuilder {
     return process.env.AKAN_DEV_CSR_REBUILD === "1";
   }
 
-  static async #buildBootDeps(app: App): Promise<IncrementalBuilderBootDeps> {
-    const { artifact, optimizedFonts } = await new SsrBaseArtifactBuilder(app).build();
+  /**
+   * Build the boot artifact in a process that exits afterwards, and keep only the serializable result.
+   *
+   * This runs in a worker for the same reason every other build does, and it was the largest single
+   * holdout: measured on `apps/akan`, `SsrBaseArtifactBuilder.build()` retains **+1143 MB** that
+   * `Bun.gc(true)` cannot touch, which is 65 % of the builder's post-boot RSS. Nothing was lost by
+   * moving it — the builder only ever kept `artifact` and `optimizedFonts`, both plain data, and the
+   * artifact is written to `base-artifact.json` regardless.
+   *
+   * `GraphClientEntryDiscovery.create` stays here because route builds need it live, and it costs
+   * nothing to keep: measured at **0 ms and 0 MB**, because it builds its graph lazily on first use.
+   */
+  static async #buildBootDeps(app: App, runner: BuildBatchRunner): Promise<IncrementalBuilderBootDeps> {
+    const result = await runner.run({
+      appName: app.name,
+      workspaceRoot: app.workspace.workspaceRoot,
+      repoName: app.workspace.repoName,
+      generation: 0,
+      needs: ["base"],
+      changedFiles: [],
+      // Discovered by the worker: at boot the watcher has no validated keys to seed, and the boot build
+      // globs them itself anyway.
+      pageKeys: null,
+      optimizedFonts: null,
+      cssAssets: null,
+      artifactDir: path.resolve(`${app.cwdPath}/.akan/artifact`),
+    });
+    // A failed boot build has to throw, not degrade quietly: `main` catches this to enter the degraded
+    // watch mode that keeps the dev server alive until the error is fixed.
+    if (result.errors.base) throw new Error(result.errors.base);
+    if (!result.artifact || !result.optimizedFonts)
+      throw new Error("boot build reported success without an artifact; the build worker likely died");
     const discovery = await GraphClientEntryDiscovery.create(app);
-    return { artifact, optimizedFonts, discovery };
+    return { artifact: result.artifact, optimizedFonts: result.optimizedFonts, discovery };
   }
 
   /**
@@ -535,18 +576,19 @@ class IncrementalBuilder {
     app: App,
     bootError: unknown,
     logger: Logger,
+    runner: BuildBatchRunner,
   ): Promise<{ builder: IncrementalBuilder; changedFiles: string[] }> {
     const firstMessage = bootError instanceof Error ? bootError.message : String(bootError);
     logger.error(`boot build failed; entering degraded watch mode until the error is fixed: ${firstMessage}`);
     let generation = 0;
     const sendFailure = (files: string[], message: string) => {
-      process.send?.({
+      BuilderChannel.emit({
         type: "build-status",
         data: { generation, phase: "pages", ok: false, files, message: `Boot build failed: ${message}` },
       });
     };
     sendFailure([], firstMessage);
-    process.send?.({ type: "builder-ready" });
+    BuilderChannel.emit({ type: "builder-ready" });
     return new Promise((resolve, reject) => {
       void (async () => {
         const roots = await new WatchRootResolver(app).resolve();
@@ -559,7 +601,7 @@ class IncrementalBuilder {
             try {
               // A broken akan.config.ts caches its import failure; re-import it before rebuilding.
               if (new Set(batch.kinds).has("config")) await app.getConfig({ refresh: true });
-              const deps = await IncrementalBuilder.#buildBootDeps(app);
+              const deps = await IncrementalBuilder.#buildBootDeps(app, runner);
               const builder = new IncrementalBuilder({ app, watch: true, initialGeneration: generation, ...deps });
               watcher.stop();
               logger.info(`boot build recovered generation=${generation}`);
@@ -602,7 +644,7 @@ class IncrementalBuilder {
       if (msg.type === "build-route") {
         const error = builder?.shuttingDown ? recyclingError : bootingError;
         if (!builder || builder.shuttingDown) {
-          process.send?.({ type: "build-route-res", id: msg.id, ok: false, error });
+          BuilderChannel.emit({ type: "build-route-res", id: msg.id, ok: false, error });
           return;
         }
         void builder.handleBuildRoute(msg);
@@ -611,24 +653,28 @@ class IncrementalBuilder {
       if (msg.type === "build-csr") {
         const error = builder?.shuttingDown ? recyclingError : bootingError;
         if (!builder || builder.shuttingDown) {
-          process.send?.({ type: "build-csr-res", id: msg.id, ok: false, error });
+          BuilderChannel.emit({ type: "build-csr-res", id: msg.id, ok: false, error });
           return;
         }
         void builder.handleBuildCsr(msg);
       }
     });
     // The IPC channel closes when the dev host dies (including SIGKILL); exit instead of running
-    // as an orphaned watcher that keeps rebuilding for nobody.
+    // as an orphaned watcher that keeps rebuilding for nobody. Nothing is drained here on purpose —
+    // there is no longer anyone on the other end to flush to.
     process.on("disconnect", () => {
       logger.warn("host IPC channel closed; exiting builder");
       process.exit(0);
     });
     let recoveredFiles: string[] | null = null;
+    // Owned by `main` rather than the instance: the boot build has to run before an instance exists, and
+    // a degraded boot re-runs it once per file change until it succeeds.
+    const bootRunner = new BuildBatchRunner({ workspaceRoot, cwd: app.cwdPath });
     try {
-      builder = new IncrementalBuilder({ app, watch, ...(await IncrementalBuilder.#buildBootDeps(app)) });
+      builder = new IncrementalBuilder({ app, watch, ...(await IncrementalBuilder.#buildBootDeps(app, bootRunner)) });
     } catch (err) {
       if (!watch) throw err;
-      const recovered = await IncrementalBuilder.#recoverBoot(app, err, logger);
+      const recovered = await IncrementalBuilder.#recoverBoot(app, err, logger, bootRunner);
       builder = recovered.builder;
       recoveredFiles = recovered.changedFiles;
     }

package/integration/devStability.integration.test.ts

@@ -566,9 +566,21 @@ describe("dev resource budgets", () => {
     const idleBuilder = await DevStabilityHarness.builderProcess(host.proc.pid);
     // Nothing should be building at idle, so the disposable worker must not be resident.
     expect(await DevStabilityHarness.buildWorkerProcess(host.proc.pid)).toBeNull();
-    // Measured ~670MB for this fixture; the headroom covers machine variance, not a reintroduced
-    // eager import (the cheapest of those is ~30MB, and the devkit barrel cycle was 236MB).
-    expect(idleTotal).toBeLessThan(1_000 * MB);
+    // Printed so a run that came close to its budget says so, instead of being indistinguishable from a
+    // comfortable one — the same reason the recycle and idle-suspend guards report their numbers.
+    console.info(
+      `[budget-guard] idle tree ${Math.round(idleTotal / MB)}MB (builder ${Math.round((idleBuilder?.rssBytes ?? 0) / MB)}MB, rest ${Math.round(idleWithoutBuilder / MB)}MB)`,
+    );
+    // Split in two because the two halves have very different variance. The builder legitimately swings
+    // from a ~130MB fresh floor to ~520MB once it has built a route (`Bun.build` arenas the RSS-ceiling
+    // recycle is what bounds), so a tight total would flake. Measured 929-959MB total / ~414MB without
+    // the builder; the old 1000MB total came from a phase-1 topology where the fixture measured ~670MB
+    // and is only ~4% above what the current topology legitimately uses.
+    expect(idleTotal).toBeLessThan(1_200 * MB);
+    // This is the half that catches what the budget exists for: an eager import lands in the dev host or
+    // the backend, not in the builder's arenas. The cheapest reintroduction is ~30MB and the devkit
+    // barrel cycle was 236MB, so this bound still fails on the latter.
+    expect(idleWithoutBuilder).toBeLessThan(600 * MB);
 
     const start = host.markLog();
     for (let i = 1; i <= 3; i++) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "2.4.1-rc.4",
+  "version": "2.4.1-rc.6",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,7 +44,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "2.4.1-rc.4",
+    "akanjs": "2.4.1-rc.6",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "daisyui": "5.5.23",

package/incrementalBuilder/builderReply.test.ts

@@ -1,73 +0,0 @@
-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 { BuilderReply } from "./builderReply";
-
-const tempDirs: string[] = [];
-
-afterEach(async () => {
-  for (const dir of tempDirs.splice(0)) await rm(dir, { recursive: true, force: true });
-});
-
-/**
- * Run a child that answers a build request and exits immediately — the shape of the recycle drain
- * finishing its last work item — and report whatever the parent actually received.
- */
-const replyThenExit = async (
-  bytes: number,
-  { awaitFlush }: { awaitFlush: boolean },
-): Promise<{ id?: number } | null> => {
-  const dir = await mkdtemp(path.join(os.tmpdir(), "builder-reply-"));
-  tempDirs.push(dir);
-  const entry = path.join(dir, "child.ts");
-  const modulePath = JSON.stringify(path.join(import.meta.dir, "builderReply"));
-  const reply = awaitFlush ? "await BuilderReply.send(res as never);" : "process.send?.(res);";
-  await Bun.write(
-    entry,
-    [
-      `import { BuilderReply } from ${modulePath};`,
-      'const chunk = "x".repeat(200);',
-      "const moduleMap: Record<string, string> = {};",
-      `for (let i = 0; i * 210 < ${bytes}; i++) moduleMap["chunk-" + i] = chunk;`,
-      'const res = { type: "build-route-res", id: 7, ok: true, data: { ssrManifestDelta: moduleMap } };',
-      reply,
-      "process.exit(0);",
-    ].join("\n"),
-  );
-  let received: { id?: number } | null = null;
-  const proc = Bun.spawn(["bun", entry], {
-    stdio: ["ignore", "inherit", "inherit"],
-    serialization: "advanced",
-    ipc: (message) => {
-      received = message as { id?: number };
-    },
-  });
-  await proc.exited;
-  // Replies land before the exit callback, never after, but leave room for a straggler to prove it.
-  await Bun.sleep(50);
-  return received;
-};
-
-describe("BuilderReply.send", () => {
-  test("delivers a reply too large for the pipe buffer before the process exits", async () => {
-    expect(await replyThenExit(1_000_000, { awaitFlush: true })).toMatchObject({ id: 7 });
-    // A manifest delta is usually well past the buffer, but the small case must keep working too.
-    expect(await replyThenExit(0, { awaitFlush: true })).toMatchObject({ id: 7 });
-  });
-
-  test("without the flush wait the same reply is lost, which is why this class exists", async () => {
-    // A control, not a requirement: if a future bun flushes ipc writes on exit, this fails and says so.
-    expect(await replyThenExit(1_000_000, { awaitFlush: false })).toBeNull();
-  });
-
-  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 BuilderReply.send({ type: "build-csr-res", id: 1, ok: true });
-    } finally {
-      (process as { send?: typeof process.send }).send = send;
-    }
-  });
-});

package/incrementalBuilder/builderReply.ts

@@ -1,30 +0,0 @@
-import type { BuilderCsrRes, BuilderRes } from "akanjs/server";
-
-/**
- * Sends a builder's answer to a backend request and reports when it has actually left the process.
- *
- * `process.exit` truncates an ipc write that has not flushed yet, and anything past the pipe buffer
- * (~64KiB) needs the sender to stay alive to drain it — a `build-route-res` carrying a manifest delta is
- * routinely larger than that. Measured on bun 1.3: a 100KB reply sent immediately before
- * `process.exit(0)` was lost 20/20 times, and arrived 20/20 times when the exit waited for the flush
- * callback. That made the recycle drain, which exists to release bundler memory, eat the answer of
- * whatever route build it happened to be draining.
- */
-export class BuilderReply {
-  /** Bound so a runtime that ever stops invoking the callback costs one late reply instead of wedging
-   * the shutdown drain until the host's kill watchdog fires. */
-  static readonly #flushTimeoutMs = 5_000;
-
-  static async send(res: BuilderRes | BuilderCsrRes): Promise<void> {
-    const send = process.send;
-    if (!send) return;
-    await new Promise<void>((resolve) => {
-      const timer = setTimeout(resolve, BuilderReply.#flushTimeoutMs);
-      // A failed send has nothing to retry — the host answers the id itself when this process exits.
-      send.call(process, res, undefined, undefined, () => {
-        clearTimeout(timer);
-        resolve();
-      });
-    });
-  }
-}