@akanjs/devkit 3.0.0-beta.23 → 3.0.0-beta.25

package/DEV_RUNTIME_KNOBS.md

@@ -22,7 +22,7 @@ crosses its ceiling is replaced when it is next idle — never mid-work.
 
 | process | explicit (MiB) | explicit (bytes) | share of the limit | fallback with no limit |
 |---|---|---|---|---|
-| incremental builder | `AKAN_BUILDER_MAX_RSS_MB` | `AKAN_BUILDER_MAX_RSS` | **0.35** | 1200MB (dev) |
+| incremental builder | `AKAN_BUILDER_MAX_RSS_MB` | `AKAN_BUILDER_MAX_RSS` | **0.35** | 2048MB (dev) |
 | RSC worker | `AKAN_RSC_WORKER_MAX_RSS_MB` | `AKAN_RSC_WORKER_MAX_RSS` | **0.55** | 768MB (dev), unbounded (production) |
 
 `AKAN_BUILDER_MAX_RSS_MB=0` leaves the builder unbounded, which is the escape hatch for an app whose
@@ -65,10 +65,17 @@ which is the one case where replacing it again cannot help; it says that too, an
 
 | variable | default | what it does |
 |---|---|---|
-| `AKAN_DEV_CSR_REBUILD` | off | Rebuild the CSR artifact on every save. Armed automatically by the first `/__csr` or `?csr=true` request, which is what a mobile WebView session does — set it explicitly only to have it from boot. |
+| `AKAN_DEV_CSR_REBUILD` | off | Rebuild the CSR artifact on every save. Armed automatically by the first `/__csr` or `?csr=true` request, which is what a mobile WebView session does — set it explicitly only to have it from boot. Set at boot, its CSR build runs beside the SSR registry's: on apps/akan the builder and its workers peak at about 2.7GB instead of 1.3GB, and the next boot wave waits for both builds. |
+| `AKAN_DEV_CSR` | `registry` | How the dev CSR page is built. `registry` serves it as a module registry that patches the modules a save changed; `artifact` brings back the single-file bundle, which reloads on every save. |
+| `AKAN_DEV_CSR_PATCHER` | on | `off` sends every save of a dev module registry — the CSR page's, and the one SSR pages load their client code from (`.akan/artifact/ssr-dev`) — to a disposable build worker instead of patching it in the resident builder. The patcher keeps each registry in memory (on minimal the CSR one adds about 170MB to the builder's median RSS and 210MB to its peak, flat across saves) and hands whole-app builds to a worker: a first build, a new npm module, a bare import no file of its package resolved before, a config change, a signal or dictionary save (their metadata is inlined at build time), and a registry whose last whole build was cut short. A misspelled import fails in the builder, like a missing file. A builder that dies mid-patch turns it off until the dev server next replaces its builder and backend together (a config, signal or dictionary change). |
+| `AKAN_DEV_WATCH_DEBOUNCE_MS` | `30` | How long the file watcher collects changes before it hands a batch over. Every save waits this long before anything builds. A second write inside the window joins the same batch; one after it starts another batch, which reads the file's latest content, so a format-on-save costs a second build rather than a wrong one. |
 | `AKAN_BUILDER_RPC_TIMEOUT_MS` | `120000` | How long the backend waits for a builder answer. Generous on purpose: a cold CSR build of every page legitimately takes tens of seconds. |
 | `AKAN_SERVER_PAGES_SPLITTING` | off | Emit the server pages bundle as chunks instead of one file. Experimental — the memory/latency trade has not been measured on a real app. |
 
+Two more are read by the dev server for its end-to-end tests only; never set them. `AKAN_DEV_SSR_ARM_DELAY_MS`
+holds the SSR registry's boot build back, and `AKAN_CSR_DEV_APP_WRITE_DELAY_MS` holds a registry's `app.js`
+back after a patch is announced.
+
 ## Observability
 
 | variable | default | what it does |
@@ -80,31 +87,36 @@ which is the one case where replacing it again cannot help; it says that too, an
 ## Several apps at once
 
 `akan start a,b` runs one dev host per app under a supervisor, so **every number above multiplies by the number
-of apps** — there is no shared builder and no shared RSC worker. Measured on this repo, right after both apps
+of apps** — there is no shared builder and no shared RSC worker. Measured on this repo 8 seconds after both apps
 finished booting:
 
 | process | akan | minimal |
 |---|---|---|
-| dev host | 101MB | 94MB |
-| incremental builder | 596MB | 532MB |
-| backend | 35MB | 38MB |
-| RSC worker | 190MB | 81MB |
-
-Plus ~51MB for the supervisor itself: **~1.7GB for two apps at their peak.** The builders are almost all of
-that, and they are also the part that goes away — `AKAN_DEV_IDLE_SUSPEND_MS` releases each one independently, so
-a session where you are editing one app settles to roughly one builder plus ~190MB per idle app. **Multi-app is
-sized against idle suspend being on**; setting it to `0` keeps every builder resident for the whole session.
+| dev host | 279MB | 196MB |
+| incremental builder | 182MB | 114MB |
+| backend (gateway and replica) | 123MB | 130MB |
+| RSC worker | 162MB | 75MB |
+
+Plus ~75MB for the supervisor itself: **~1.3GB for two apps at rest.** The peak is the boot, not the rest: the
+build workers — the base build, then the SSR registry's — take a whole akan dev host to ~1.9GB and minimal's to
+~1.4GB, and booted one after the other the two peaked at 2.2GB. The builders are also the part that goes away —
+`AKAN_DEV_IDLE_SUSPEND_MS` releases each one independently, so a session where you are editing one app keeps one
+builder, and every idle app keeps only its dev host, backend and RSC worker. **Multi-app is sized against idle
+suspend being on**; setting it to `0` keeps every builder resident for the whole session.
 
 Two things bound the peak rather than the floor:
 
-- **`--concurrency` (default: what the machine allows).** Apps boot in waves, and the next wave starts only
-  once the previous one reports ready. A cold boot build is the builder's peak, so booting `n` apps at once
-  means `n` overlapping peaks — which is what OOM-kills a container that would have been fine with them
-  staggered. Unset, the wave is `min(apps, half the memory budget / 900MB per app, cores / 4)`, never below
-  one, and the session prints which — so a laptop boots its apps together and a 1.2GB container still
-  staggers them. The memory budget is the smaller of the host's RAM and `AKAN_MEMORY_LIMIT` / the cgroup
-  limit; `os.freemem()` is not consulted, because it counts free pages rather than reclaimable ones and
-  reports ~0.3GB on an idle 48GB laptop.
+- **`--concurrency` (default: what the machine allows).** Apps boot in waves. The next wave starts once each
+  app of the previous one serves and its builder's boot builds have settled — the SSR registry's, and CSR's when
+  `AKAN_DEV_CSR_REBUILD=1` arms it — since those workers are the largest processes of a boot. An app that never
+  reports them starts the next wave 30 seconds after it serves. It shows as ready, and `--open` opens it, as
+  soon as it serves. Booting `n` apps at once means `n` overlapping peaks — which is what OOM-kills a container
+  that would have been fine with them staggered. Unset, the wave is
+  `min(apps, half the memory budget / 1.8GB per app, cores / 4)`, never below one, and the session prints
+  which — so a laptop boots its apps together and a small container boots them one at a time. The 1.8GB is
+  apps/akan's boot peak across all its processes (measured 1.73–1.9GB). The memory budget is the smaller of
+  the host's RAM and `AKAN_MEMORY_LIMIT` / the cgroup limit; `os.freemem()` is not consulted, because it counts
+  free pages rather than reclaimable ones and reports ~0.3GB on an idle 48GB laptop.
 - **`AKAN_MEMORY_LIMIT` is per process, not per session.** Each dev host derives its builder and RSC-worker
   ceilings from it independently, so a limit sized for one app does not become a budget for four. Divide it
   yourself, or leave it unset on a laptop. The one place it is read as a session ceiling is the boot wave
@@ -113,7 +125,8 @@ Two things bound the peak rather than the floor:
 
 ## Sizing a small sandbox
 
-A worked example, for a 1.2GB container:
+A worked example, for a 1.2GB container running an app the size of `apps/minimal` (apps/akan's boot alone
+peaks near 1.8GB):
 
 ```bash
 AKAN_MEMORY_LIMIT=1200mb          # builder gets ~420MB, rsc worker ~660MB
@@ -124,7 +137,9 @@ Two things to expect at that size. The builder crosses 420MB during ordinary wor
 costs ~247MB on top of its floor — so it is replaced roughly once per 30s while you keep building, each
 replacement costing a boot build that requests wait through rather than fail. And the build worker's
 peak is not covered by any of these ceilings; if the kernel OOM-kills it, the dev server survives with a
-red build for that generation and the log names the signal.
+red build for that generation and the log names the signal. On a boot whose `.akan` was cleared, the SSR
+registry's first build is such a worker: a killed one leaves no registry, and every later save retries that
+same whole build, so a container that cannot fit it once cannot fit it at all.
 
 Raising `AKAN_BUILDER_MAX_RSS_MB` above the derived share trades memory for fewer boot builds. Setting
 it to `0` trades the bound away entirely, which on a container this size means the kernel decides

package/akanApp/akanApp.host.ts

@@ -9,6 +9,7 @@ import { WatchRootResolver } from "../frontendBuild/watchRootResolver";
 import { type DevStdioMode, IncrementalBuilderHost } from "../incrementalBuilder";
 import { BuilderRequestRouter } from "../incrementalBuilder/builderRequestRouter";
 import { BackendImportGraph } from "./BackendImportGraph";
+import { DevBootLatch } from "./devBootLatch";
 import {
   type BackendLifecycleState,
   type BackendRestartReason,
@@ -34,6 +35,7 @@ import {
   type SourceFingerprints,
   shouldAbandonBackendRecovery,
   shouldHoldForReturningBuilder,
+  shouldKeepBuildFailure,
   shouldMarkBuildPhaseRecovered,
   shouldQueueBuildStatusReplay,
   shouldRefreshConfigOnIdleWake,
@@ -88,6 +90,7 @@ export class AkanAppHost {
   readonly env: Record<string, string>;
   readonly #onDevEvent: ((event: DevHostEvent) => void) | null;
   #lastDevState: DevHostState | null = null;
+  readonly #bootLatch = new DevBootLatch(() => this.#onDevEvent?.({ app: this.app.name, booted: true }));
   #backend: Bun.Subprocess<"ignore", "inherit" | "pipe", "inherit" | "pipe"> | null = null;
   #builder: IncrementalBuilderHost | null = null;
   #backendReady = false;
@@ -126,6 +129,7 @@ export class AkanAppHost {
   #builderGapStamp: Promise<SourceFingerprints | null> | null = null;
   #pendingBuilderMessages: BuilderMessage[] = [];
   readonly #builderRequests = new BuilderRequestRouter();
+  #builderGeneration = 0;
   constructor(
     private readonly app: App,
     {
@@ -143,6 +147,7 @@ export class AkanAppHost {
     if (!this.#onDevEvent || state === this.#lastDevState) return;
     this.#lastDevState = state;
     this.#onDevEvent({ app: this.app.name, state, ...(detail ? { detail } : {}) });
+    if (state === "ready") this.#bootLatch.ready();
   }
   async start() {
     if (this.#backend) await this.#stopBackend();
@@ -202,6 +207,7 @@ export class AkanAppHost {
           this.#setBackendLifecycleState("ready", `pid=${msg.pid}`);
           this.#recordBackendReadyStatus();
           this.logger.verbose(`backend ready pid=${msg.pid}`);
+          this.#forgetRouteBuildStatus();
           this.#replayBuilderState();
           return;
         }
@@ -425,6 +431,7 @@ export class AkanAppHost {
   }
   async #handleBuilderMessage(message: BuilderMessage) {
     this.#markDevActivity();
+    this.#trackBuilderGeneration(message);
     if (message.type === "build-status") {
       this.#recordBuildStatus(message.data);
       this.#sendOrQueueBuildStatus(message.data);
@@ -435,6 +442,11 @@ export class AkanAppHost {
       this.#handleBuilderMetrics(message.data);
       return;
     }
+    if (message.type === "boot-armed") {
+      this.logger.verbose("[builder] boot builds settled");
+      this.#bootLatch.armed();
+      return;
+    }
     if (message.type === "pages-updated" || message.type === "css-updated") {
       const recycled = message.data.reason === "builder-recycle";
       if (recycled && !this.#shouldRelayRecycledState(message)) return;
@@ -455,6 +467,20 @@ export class AkanAppHost {
     }
     this.#sendToBackend(message);
   }
+  // In `env`, which every builder spawn re-reads: a replacement (recycled, crashed, restarted) continues from here.
+  #trackBuilderGeneration(message: BuilderMessage): void {
+    const generation = AkanAppHost.#builderGenerationOf(message);
+    if (generation === undefined || generation <= this.#builderGeneration) return;
+    this.#builderGeneration = generation;
+    Object.assign(this.env, { AKAN_BUILDER_INITIAL_GENERATION: String(generation) });
+  }
+  // Not `csr-updated` / `ssr-updated`: their generation is the registry's.
+  static #builderGenerationOf(message: BuilderMessage): number | undefined {
+    if (message.type === "invalidate") return message.generation;
+    if (message.type === "build-status" || message.type === "builder-metrics") return message.data.generation;
+    if (message.type === "pages-updated" || message.type === "css-updated") return message.data.generation;
+    return undefined;
+  }
   // The backend reads `base-artifact.json` once, so a recycled builder re-announces it; unchanged hashes are dropped.
   #shouldRelayRecycledState(
     message: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
@@ -995,7 +1021,7 @@ export class AkanAppHost {
     await this.#startBuilder();
     this.#startBackend({ generation, files: message.files });
   }
-  // `supersede`: a replacement builder's generation restarts at 0, so its announcement would look stale.
+  // `supersede`: a recycled builder's re-announcement is what is on disk now, whatever generation it carries.
   #recordLastGood(
     message: Extract<BuilderMessage, { type: "pages-updated" }> | Extract<BuilderMessage, { type: "css-updated" }>,
     { supersede = false }: { supersede?: boolean } = {},
@@ -1034,6 +1060,7 @@ export class AkanAppHost {
   }
   #recordBuildStatus(status: DevBuildStatus): void {
     const recovered = shouldMarkBuildPhaseRecovered(this.#buildStatusByPhase, status);
+    if (shouldKeepBuildFailure(this.#buildStatusByPhase, status)) return;
     this.#buildStatusByPhase.set(status.phase, status);
     const label = `[build-status] generation=${status.generation} phase=${status.phase} ok=${status.ok} files=${status.files.length}`;
     if (status.ok) this.logger.verbose(`${label}${recovered ? " recovered=1" : ""}`);
@@ -1049,6 +1076,12 @@ export class AkanAppHost {
     }
     this.#sendToBackend({ type: "build-status", data: status });
   }
+  //? A route status belongs to the route cache of the backend that asked for the build: a new backend builds its routes
+  //? again, and reports each one itself.
+  #forgetRouteBuildStatus(): void {
+    this.#buildStatusByPhase.delete("route");
+    this.#pendingBuildStatusReplay = this.#pendingBuildStatusReplay.filter((status) => status.phase !== "route");
+  }
   #replayBuilderState(): void {
     if (!this.#backendReady) return;
     if (this.#lastGoodFrontend.css) this.#sendToBackend(this.#lastGoodFrontend.css);

package/akanApp/devBootLatch.test.ts

@@ -0,0 +1,39 @@
+import { describe, expect, test } from "bun:test";
+import { DevBootLatch } from "./devBootLatch";
+
+const latch = (waitMs = 60_000) => {
+  const booted: number[] = [];
+  return { booted, latch: new DevBootLatch(() => booted.push(Date.now()), { waitMs }) };
+};
+
+describe("DevBootLatch", () => {
+  test("opens once the app serves and its boot builds have settled, in either order", () => {
+    const readyFirst = latch();
+    readyFirst.latch.ready();
+    expect(readyFirst.booted).toHaveLength(0);
+    readyFirst.latch.armed();
+    expect(readyFirst.booted).toHaveLength(1);
+
+    const armedFirst = latch();
+    armedFirst.latch.armed();
+    expect(armedFirst.booted).toHaveLength(0);
+    armedFirst.latch.ready();
+    expect(armedFirst.booted).toHaveLength(1);
+  });
+
+  test("opens once per session, however often the app restarts or the builder re-arms", () => {
+    const { booted, latch: boot } = latch();
+    boot.armed();
+    boot.ready();
+    boot.ready();
+    boot.armed();
+    expect(booted).toHaveLength(1);
+  });
+
+  test("opens after its wait past ready when the builder never reports", async () => {
+    const { booted, latch: boot } = latch(20);
+    boot.ready();
+    await Bun.sleep(60);
+    expect(booted).toHaveLength(1);
+  });
+});

package/akanApp/devBootLatch.ts

@@ -0,0 +1,39 @@
+//* An app's boot is over for the supervisor once it serves and its builder's boot builds have settled (the SSR
+//* registry's, and CSR's when the env arms it): those workers are a boot's largest processes, so the next boot wave
+//* starts here, while the browser opens on the ready that comes first.
+export class DevBootLatch {
+  readonly #onBooted: () => void;
+  readonly #waitMs: number;
+  #ready = false;
+  #armed = false;
+  #booted = false;
+  #timer: ReturnType<typeof setTimeout> | null = null;
+
+  /** `waitMs` bounds the wait past ready: a builder that never reports (killed mid-boot) must not stall the waves. */
+  constructor(onBooted: () => void, { waitMs = 30_000 }: { waitMs?: number } = {}) {
+    this.#onBooted = onBooted;
+    this.#waitMs = waitMs;
+  }
+
+  ready(): void {
+    this.#ready = true;
+    if (!this.#armed && !this.#timer) {
+      this.#timer = setTimeout(() => this.armed(), this.#waitMs);
+      this.#timer.unref?.();
+    }
+    this.#release();
+  }
+
+  armed(): void {
+    this.#armed = true;
+    this.#release();
+  }
+
+  #release(): void {
+    if (this.#booted || !this.#ready || !this.#armed) return;
+    this.#booted = true;
+    if (this.#timer) clearTimeout(this.#timer);
+    this.#timer = null;
+    this.#onBooted();
+  }
+}

package/akanApp/devHostPolicy.test.ts

@@ -17,6 +17,7 @@ import {
   resolveIdleSuspendMs,
   shouldAbandonBackendRecovery,
   shouldHoldForReturningBuilder,
+  shouldKeepBuildFailure,
   shouldMarkBuildPhaseRecovered,
   shouldQueueBuildStatusReplay,
   shouldRefreshConfigOnIdleWake,
@@ -355,6 +356,30 @@ describe("build status helpers", () => {
     expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("pages", 12, true))).toBe(true);
   });
 
+  test("an ok of the failure's own generation neither recovers nor replaces it, except a backend's", () => {
+    const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([
+      ["ssr", status("ssr", 7, false)],
+      ["backend", status("backend", 7, false)],
+    ]);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("ssr", 7, true))).toBe(false);
+    expect(shouldKeepBuildFailure(previousByPhase, status("ssr", 7, true))).toBe(true);
+    expect(shouldKeepBuildFailure(previousByPhase, status("ssr", 8, true))).toBe(false);
+    expect(shouldKeepBuildFailure(previousByPhase, status("ssr", 7, false))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("backend", 7, true))).toBe(true);
+  });
+
+  test("a route built again and a builder that came back recover on the failure's own generation", () => {
+    const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([
+      ["route", status("route", 4, false)],
+      ["scan", status("scan", 42, false)],
+    ]);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("route", 4, true))).toBe(true);
+    expect(shouldKeepBuildFailure(previousByPhase, status("route", 4, true))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("scan", 42, true))).toBe(true);
+    expect(shouldKeepBuildFailure(previousByPhase, status("scan", 42, true))).toBe(false);
+    expect(shouldKeepBuildFailure(previousByPhase, status("route", 3, true))).toBe(true);
+  });
+
   test("creates backend build-status payloads for lifecycle test hooks", () => {
     expect(
       createBackendBuildStatus({

package/akanApp/devHostPolicy.ts

@@ -61,12 +61,20 @@ export type BackendLifecycleState = "starting" | "ready" | "restart-pending" | "
 /** Reported, not scraped: in interleaved child output "this app is up" reads like any line mentioning it. */
 export type DevHostState = "starting" | "ready" | "restarting" | "recovering" | "suspended" | "failed" | "stopped";
 
-export interface DevHostEvent {
+export interface DevHostStateEvent {
   app: string;
   state: DevHostState;
   detail?: string;
 }
 
+/** Sent once: the app serves and its boot builds have settled, which is what the next boot wave waits for. */
+export interface DevHostBootEvent {
+  app: string;
+  booted: true;
+}
+
+export type DevHostEvent = DevHostStateEvent | DevHostBootEvent;
+
 const devHostStateByBackendState = {
   starting: "starting",
   ready: "ready",
@@ -112,14 +120,31 @@ export const isLegacyBackendFallbackFile = (file: string, workspaceRoot: string)
   );
 };
 
+const recoversOnSameGeneration = (phase: BuildPhase): boolean =>
+  phase === "backend" || phase === "scan" || phase === "route";
+
+//? A newer generation, as the backend and the tabs judge it: an ok of the failure's own generation (a route build's
+//? registry check that had nothing to add) says nothing about the failure. The phases whose retry reports the
+//? failure's generation again (a backend or builder that came back, a route built again) recover on it.
 export const shouldMarkBuildPhaseRecovered = (
   previousByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
   status: DevBuildStatus,
 ): boolean => {
   const previous = previousByPhase.get(status.phase);
-  return Boolean(previous && status.ok && !previous.ok && generationValue(status.generation) >= previous.generation);
+  if (!previous || !status.ok || previous.ok) return false;
+  const generation = generationValue(status.generation);
+  return recoversOnSameGeneration(status.phase) ? generation >= previous.generation : generation > previous.generation;
 };
 
+/** An ok that recovers nothing leaves the failure standing, for hello and for whatever waits on a clean build. */
+export const shouldKeepBuildFailure = (
+  previousByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
+  status: DevBuildStatus,
+): boolean =>
+  status.ok &&
+  previousByPhase.get(status.phase)?.ok === false &&
+  !shouldMarkBuildPhaseRecovered(previousByPhase, status);
+
 export const createBackendBuildStatus = ({
   generation,
   ok,

package/cloud/globalConfig.ts

@@ -1,4 +1,4 @@
-import { mkdir, rename, rm, writeFile } from "node:fs/promises";
+import { mkdir, rm, writeFile } from "node:fs/promises";
 import dayjs from "dayjs";
 import { FileSys } from "../fileSys";
 import { ConfigLock } from "./configLock";
@@ -39,7 +39,8 @@ export class GlobalConfig {
     const temp = `${configPath}.${process.pid}.${crypto.randomUUID()}.tmp`;
     try {
       await writeFile(temp, JSON.stringify(akanConfig, null, 2), { mode: 0o600 });
-      await rename(temp, configPath);
+      // Every CLI reads this file outside the lock, which on Windows makes the rename wait for the reader.
+      await FileSys.replace(temp, configPath);
     } catch (error) {
       await rm(temp, { force: true });
       throw error;