@akanjs/devkit 3.0.0-beta.2 → 3.0.0-beta.20

package/integration/devStability.integration.test.ts

@@ -3,9 +3,7 @@ import { DevGeneratedIndexSync } from "../frontendBuild";
 import { DevStabilityHarness, type DevStabilityHmrProbe } from "./devStabilityHarness";
 
 const integrationEnabled = process.env.AKAN_DEV_STABILITY_INTEGRATION === "1";
-// Every test here boots a real dev server, and contention pushes a cold boot from ~3s to 21-55s
-// (`05-phase1-results.md`). At 120s a loaded machine ran out of budget mid-restart and reported it as a
-// product failure, which is the exact ambiguity this file exists to remove.
+// Contention pushes a cold dev-server boot from ~3s to nearly a minute; 120s ran out mid-restart.
 const INTEGRATION_TIMEOUT_MS = 180_000;
 const MB = 1024 * 1024;
 const harnesses: DevStabilityHarness[] = [];
@@ -38,15 +36,7 @@ const isBuildStatus =
     "status" in msg &&
     msg.status === status;
 
-/**
- * Assert an HMR message arrives — unless the socket dropped while waiting.
- *
- * The hub does not replay (`akanjs/server/hmr/wsHub.ts`): anything published while the probe was
- * reconnecting is simply gone, so a miss across a reconnect says nothing about the product. A real browser
- * covers the same gap by reloading when the `hello` buildId moved, not by expecting the message. Under
- * parallel load the socket flaps repeatedly, and this is what that looks like from the probe:
- * `socket=closed reconnects=5 since-mark=[build-status,hello,hello,rsc-refresh,…]`.
- */
+// The hub does not replay (`akanjs/server/hmr/wsHub.ts`), so a miss across a probe reconnect proves nothing.
 const expectHmrMessage = async (
   probe: DevStabilityHmrProbe,
   mark: number,
@@ -117,21 +107,12 @@ const waitForProcessesGone = async (pids: number[], timeoutMs = 15_000): Promise
   return false;
 };
 
-/**
- * `cleanup()` waits up to 3s for a SIGTERM'd dev host to exit and shells out to `ps` twice, and on a
- * loaded machine that overruns Bun's default 5s hook budget. A hook timeout fails the test that had
- * already passed, which reads exactly like a product failure — two of the five failures in a 3-way
- * parallel run were this and nothing else.
- */
+// `cleanup()` can overrun Bun's default 5s hook budget, and a hook timeout fails the already-passed test.
 const HOOK_TIMEOUT_MS = 60_000;
 
 beforeAll(async () => {
   if (!integrationEnabled) return;
-  // A run killed mid-test (a `-t` filter interrupted, an editor stopping the runner) leaves its fixture
-  // in `apps/` and its dev host running. Both interfere with every later run: the process holds ports
-  // and rebuilds a deleted app, and the directory shifts the app index every port prediction derives
-  // from. Only fixtures whose owning test pid is gone are swept, so this is safe with a suite running
-  // alongside.
+  // A killed run leaves its fixture and dev host behind, holding ports and shifting every app index.
   const swept = await DevStabilityHarness.sweepAbandonedFixtures(DevStabilityHarness.defaultWorkspaceRoot);
   if (swept.length) console.info(`[harness] swept ${swept.length} abandoned fixture(s): ${swept.join(", ")}`);
 }, HOOK_TIMEOUT_MS);
@@ -143,14 +124,8 @@ afterEach(async () => {
 afterAll(() => {
   if (!integrationEnabled) return;
   const { edits, retried } = DevStabilityHarness.editStats();
-  // Reported on purpose, every run. A retry means a real save produced no rebuild whatsoever — Bun's
-  // dropped `fs.watch` event (`local/optimize-resource/06-watcher-dropped-event.md`), which users hit too
-  // through format-on-save and save-all. A non-zero number here means this suite is passing *around* a
-  // product bug rather than because it is absent, and it is the signal for fixing that bug properly.
+  // A retry is a save Bun's `fs.watch` dropped — a product bug users hit too, which this suite passes around.
   console.info(`[harness] ${edits} observed edit(s), ${retried} needed a retry after a dropped watch event`);
-  // Every wait is individually bounded but their budgets sum past the per-test timeout, so a loaded round
-  // can kill a test without any single wait failing — and Bun then reports only "this test timed out". These
-  // are the numbers that say how close a green run came, and which step to look at when one dies.
   const slowest = DevStabilityHarness.waitStats();
   if (slowest.length)
     console.info(`[harness] slowest waits: ${slowest.map((wait) => `${wait.ms}ms ${wait.label}`).join(" | ")}`);
@@ -227,13 +202,7 @@ describe("dev stability integration harness", () => {
     );
     const generation = evidence[1];
     await host.waitForLogSince(mark, new RegExp(`\\[backend-reload\\].*generation=${generation}`));
-    // Asserted backend-side, not through the probe. A shared edit restarts the backend, which closes the
-    // socket the probe opened; the probe reconnects, but a reconnect does not replay what was published
-    // while it was down, and a real browser handles that by reloading when the `hello` buildId moved
-    // (`akanjs/server/hmr/clientScript.ts`) rather than by expecting the message. Requiring a probe
-    // message here only held while the client rebuild happened to finish before the restart killed the
-    // connection — a race this test lost the moment builds moved into a worker process and took ~240ms
-    // longer to start.
+    // Backend-side: the restart closes the probe's socket, and a reconnect does not replay what it missed.
     await host.waitForLogSince(mark, new RegExp(`\\[SSR\\] pages-updated.*generation=${generation}`));
     await harness.waitForHttpText("updated-shared-marker");
     hmr?.close();
@@ -265,8 +234,7 @@ export const dictionary = serviceDictionary(["en", "ko"])
   });
 `,
         ),
-      // As with the config edit: each attempt recycles the builder and the backend, so patience is cheaper
-      // than a retry.
+      // Each attempt recycles the builder and the backend, so patience is cheaper than a retry.
       { evidence: /\[dev-plan\].*actions=.*restart-builder/, attempts: 2, evidenceTimeoutMs: 30_000 },
     );
 
@@ -297,8 +265,7 @@ const config: AppConfig = { externalLibs: [] };
 export default config;
 `,
         ),
-      // Re-applying this edit is expensive — every attempt restarts the whole dev host — so wait longer
-      // before concluding the event was dropped rather than merely slow.
+      // Every attempt restarts the whole dev host, so wait longer before calling the event dropped.
       { evidence: /\[dev-plan\].*actions=.*restart-dev-host/, attempts: 2, evidenceTimeoutMs: 30_000 },
     );
 
@@ -338,8 +305,7 @@ export default config;
     await harness.waitForHttpText("initial-client-marker");
     const recoveryHmrMark = hmr?.mark() ?? 0;
 
-    // The edit that used to be dropped: it lands right after the failed build's write burst, and in a
-    // 3-way parallel run all three shards timed out here on 60s of completely empty log output.
+    // Lands right after the failed build's write burst, where Bun's watcher drops events.
     const { mark: recoveryMark } = await harness.editUntilSeen(host, (attempt) =>
       harness.writeFile(
         "ui/ClientMarker.tsx",
@@ -359,8 +325,7 @@ export default config;
   integrationTest("barrel add/delete includes generated indexes in watch generation", async () => {
     const harness = await createHarness();
     const sync = new DevGeneratedIndexSync({ workspaceRoot: harness.workspaceRoot });
-    // `common` barrels export camelCase names; `ui` barrels export PascalCase component names. Each facet's
-    // fixture file must follow its own casing convention or the barrel deliberately skips it.
+    // Each facet's barrel skips a file that breaks its casing convention (`common` camelCase, `ui` PascalCase).
     const facets = [
       { facet: "common", moduleName: "tmpExample", fileName: "tmpExample.ts", exportName: "commonTmpExample" },
       { facet: "ui", moduleName: "TmpExample", fileName: "TmpExample.tsx", exportName: "TmpExample" },
@@ -398,8 +363,7 @@ export default config;
   integrationTest("backend boot failure stops the crash loop, surfaces build-status, and recovers on fix", async () => {
     const harness = await createHarness();
     const host = await harness.startHost();
-    // The service file is part of the generated server graph (`akan start` regenerates server.ts
-    // from lib/), so a module-level throw here breaks every replica boot.
+    // `akan start` regenerates server.ts from lib/, so a module-level throw here breaks every replica boot.
     const { mark: failureMark } = await harness.editUntilSeen(host, (attempt) =>
       harness.writeFile(
         "lib/_fixture/fixture.service.ts",
@@ -412,9 +376,7 @@ throw new Error("intentional-backend-boot-crash-${attempt}");
       ),
     );
 
-    // The gateway abandons the replica after three failed boots instead of retrying forever...
     await host.waitForLogSince(failureMark, /\[child-crash-loop\].*failed 3 consecutive boots/);
-    // ...and the failure reaches the dev host's build-status pipeline (HMR overlay path).
     await host.waitForLogSince(failureMark, /\[build-status\].*phase=backend.*ok=false/);
     expect(host.proc.killed).toBe(false);
 
@@ -451,8 +413,7 @@ export class FixtureService extends serve("fixture" as const, { serverMode: "bat
 
     process.kill(gatewayPid, "SIGKILL");
 
-    // Children must notice the closed IPC channel and exit instead of orphaning (they would
-    // otherwise keep holding their ws ports and break every subsequent boot).
+    // An orphaned child would keep holding its ws port and break every later boot.
     expect(await waitForProcessesGone(childPids)).toBe(true);
 
     await host.waitForLogSince(mark, /backend ready pid=(\d+)|AkanApp gateway is running on port/);
@@ -467,8 +428,7 @@ export class FixtureService extends serve("fixture" as const, { serverMode: "bat
   integrationTest("occupied preferred ws port falls back to an ephemeral port and stays bootable", async () => {
     const harness = await createHarness();
     const port = await harness.resolvePort();
-    // The gateway assigns child 0 the deterministic ws port `port + 10_000`; occupy it up front
-    // the way an orphaned replica from a killed run would.
+    // Child 0's deterministic ws port, held the way an orphaned replica from a killed run would hold it.
     const blocker = Bun.serve({ port: port + 10_000, fetch: () => new Response("occupied") });
     try {
       const host = await harness.startHost();
@@ -491,34 +451,12 @@ export class FixtureService extends serve("fixture" as const, { serverMode: "bat
   });
 });
 
-/**
- * Resource budgets for `akan start`. A dev sandbox holds this process tree for a whole session, so
- * every regression here multiplies by the number of tenants. Budgets are deliberately loose (they
- * carry headroom over the measured values) — they exist to catch a *reintroduced* eager import or an
- * unbounded per-save ratchet, not to pin exact numbers. Raising one should be a visible diff.
- *
- * Deliberately two tests, not one per property: each boots a full dev server, and four boots after
- * the eleven tests above pushed cold boot from 3s to 21-55s through sheer machine contention, which
- * silently exhausted the waits and looked like product failures. Both tests therefore assert several
- * related properties against a single boot, with explicit generous waits. Run the block on its own
- * (`-t "dev resource budgets"`) when timing matters.
- *
- * **This block is not parallel-safe, and cannot be made so.** It asserts *absolute* resident memory, so
- * several dev servers competing for the machine changes what the number means rather than adding noise
- * around it — a 3-way parallel run reported 178MB against the 120MB budget. That is a property of the
- * measurement, not flakiness: run this block on an otherwise idle machine and parallelise the behavioural
- * block above. Loosening a budget to survive a parallel run would throw away the regression signal the
- * budget exists for.
- */
+// Loose budgets that catch a reintroduced eager import or a per-save ratchet, not exact numbers. Absolute RSS is
+// not parallel-safe: run this block alone on an idle machine (`-t "dev resource budgets"`), never loosen it.
 describe("dev resource budgets", () => {
   const BOOT_MS = 150_000;
   const WAIT_MS = 90_000;
-  /**
-   * Measured on this fixture at **260-516ms** per save. Set ~6× above that, like every budget here: it is
-   * looking for a path that got slower by a factor — a boot build that stopped being avoidable, a worker
-   * spawn that stopped being warm — not for jitter on a busy laptop. `apps/akan`, ~25× this fixture's
-   * pages bundle, took ~1.5s per save when the plan started.
-   */
+  // ~6x the measured 260-516ms per save: catches a path that got slower by a factor, not jitter.
   const SAVE_LATENCY_BUDGET_MS = 3_000;
   const budgetTest = (name: string, fn: () => Promise<void>): void => {
     if (integrationEnabled) test(name, fn, 300_000);
@@ -533,9 +471,7 @@ describe("dev resource budgets", () => {
     // A full minified browser-target build of every page, only reachable via `/__csr` and `?csr=true`.
     expect(host.logs.join("")).not.toMatch(/\[csr-build\] output ->/);
 
-    // Mobile local dev points a device WebView at this URL, so it must serve HTML, not a 404. Wait
-    // for the app to actually serve first: `backend ready` fires before the gateway routes to the
-    // replica, and a too-early request 503s without reaching the router that arms CSR.
+    // `backend ready` fires before the gateway routes to the replica; an earlier request 503s without arming CSR.
     await harness.waitForHttpText("initial-client-marker", WAIT_MS);
     const armMark = host.markLog();
     const res = await fetch(`http://127.0.0.1:${port}/?csr=true`);
@@ -543,11 +479,7 @@ describe("dev resource budgets", () => {
     expect(await res.text()).toContain("<html");
     expect(host.logs.join("").slice(armMark)).toMatch(/csr-build ok on demand/);
 
-    // Armed: from here on every save rebuilds CSR, which is what keeps a live mobile session working.
-    //
-    // `editUntilSeen` rather than a bare save, because the CSR build above emits a whole minified tree
-    // into `.akan/artifact/csr` and a save landing in that window is dropped by Bun 100% of the time
-    // (`local/optimize-resource/06-watcher-dropped-event.md`).
+    // `editUntilSeen`: Bun always drops a save landing in the CSR build's write burst.
     const { mark: resyncMark } = await harness.editUntilSeen(host, (attempt) =>
       harness.replaceText(
         "ui/ClientMarker.tsx",
@@ -561,8 +493,7 @@ describe("dev resource budgets", () => {
   budgetTest("bounds the rsc worker and the tree across repeated saves", async () => {
     const harness = await createHarness();
     const host = await harness.startHost({
-      // Recycle on the second reload so this needs a couple of saves rather than the ten a
-      // default-threshold run would take, and take the burst-coalescing floor out of the equation.
+      // Recycle on the second reload instead of the default tenth, with no burst-coalescing floor.
       timeoutMs: BOOT_MS,
       env: { AKAN_RSC_WORKER_MAX_RELOADS: "1", AKAN_RSC_WORKER_MIN_RECYCLE_INTERVAL_MS: "1" },
     });
@@ -571,22 +502,13 @@ describe("dev resource budgets", () => {
     const idleTotal = await DevStabilityHarness.processTreeRssBytes(host.proc.pid);
     const idleWithoutBuilder = await DevStabilityHarness.processTreeRssBytes(host.proc.pid, { excludeBuilder: true });
     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();
-    // 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.
+    // Split: the builder alone swings ~130-520MB with `Bun.build` arenas, so a tight total would flake.
     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.
+    // An eager import lands here, in the dev host or backend, not in the builder's arenas.
     expect(idleWithoutBuilder).toBeLessThan(600 * MB);
 
     const start = host.markLog();
@@ -599,53 +521,39 @@ describe("dev resource budgets", () => {
       const afterSave = host.logs.join("").slice(mark);
       expect(afterSave).toMatch(/csr-rebundle skipped/);
       expect(afterSave).not.toMatch(/csr-rebundle ok/);
-      // Waiting for the builder alone is not enough before the next iteration: the backend is still
-      // applying the reload after that, and it writes into the watched tree too. `editUntilSeen` handles
-      // the drop window itself, but these two waits are still what makes each iteration a whole
-      // generation, which is what the RSS deltas below are measured across.
+      // The backend applies the reload after the builder finishes; wait for both so each save is a whole generation.
       await host.waitForLogSince(mark, /css-rebuild checked/, WAIT_MS);
       await host.waitForLogSince(mark, /\[hmr\] backend apply/, WAIT_MS);
     }
 
-    // Each in-place reload re-imports the pages bundle under a fresh `?v=`, and Bun's ESM registry
-    // never evicts — so without a recycle the worker grows for the life of the process.
+    // Each reload re-imports the pages bundle under a fresh `?v=`, and Bun's ESM registry never evicts.
     await host.waitForLogSince(start, /rolling recycle worker reason=pages-reload-accumulation/, WAIT_MS);
 
-    // The dev host, gateway, replica and rsc worker must all stay flat across saves.
     const afterWithoutBuilder = await DevStabilityHarness.processTreeRssBytes(host.proc.pid, {
       excludeBuilder: true,
     });
     expect(afterWithoutBuilder - idleWithoutBuilder).toBeLessThan(120 * MB);
 
-    // And so must the builder. It used to be excluded from this budget because `Bun.build` retains
-    // native arenas no GC reclaims, which made it grow ~120MB per save on this fixture; every build
-    // that scales per save now runs in a process that exits, so its memory goes back to the OS.
+    // Every per-save build runs in a worker that exits, so the builder must stay flat too.
     const afterBuilder = await DevStabilityHarness.builderProcess(host.proc.pid);
     expect(afterBuilder?.pid).toBe(idleBuilder?.pid);
     expect((afterBuilder?.rssBytes ?? 0) - (idleBuilder?.rssBytes ?? 0)).toBeLessThan(30 * MB);
-    // The worker is transient: three generations built, and none of them is still around.
     expect(await DevStabilityHarness.buildWorkerProcess(host.proc.pid)).toBeNull();
   });
 
   budgetTest("recycles the builder at an unmeetable ceiling and keeps developing through it", async () => {
     const harness = await createHarness();
-    // Deliberately *below* this fixture's post-boot builder. Moving every per-save build into a
-    // disposable worker means the builder no longer grows into a ceiling, so a ceiling it is already
-    // over is the only way left to drive the recycle path end to end — and it is also the case the
-    // escape hatch exists for: an app whose boot floor simply does not fit under the limit.
+    // Deliberately below the post-boot builder: it no longer grows into a ceiling, so it must start over one.
     const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_BUILDER_MAX_RSS_MB: "200" } });
     const start = host.markLog();
     await harness.waitForHttpText("initial-client-marker", WAIT_MS);
 
-    // One save is enough: the builder reports its rss as soon as the batch drains, and the host arms
-    // the recycle from that report. The old pid comes from the log rather than from `ps`, so this does
-    // not race the swap it is about to observe.
+    // One save arms the recycle; the old pid comes from the log, not `ps`, so it cannot race the swap.
     const { mark: firstSave } = await harness.editUntilSeen(host, (attempt) =>
       harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-1-${attempt}`),
     );
     await host.waitForLogSince(firstSave, /pages-rebundle ok/, WAIT_MS);
 
-    // The host decides, the builder drains rather than being killed, and the replacement comes up.
     const recycleLog = await host.waitForLogSince(
       start,
       /recycling builder pid=(\d+) \((rss=\d+MiB>=200MiB after \d+ build\(s\))\)/,
@@ -654,19 +562,14 @@ describe("dev resource budgets", () => {
     await host.waitForLogSince(start, /exiting for recycle/, WAIT_MS);
     await host.waitForLogSince(start, /builder spawned pid=\d+ .*restart=1/, WAIT_MS);
     await host.waitForLogSince(start, /builder ready after restart/, WAIT_MS);
-    // The backend read `base-artifact.json` once at boot, so the replacement has to re-announce what
-    // it booted with or the backend keeps serving the artifact of the builder that just exited.
+    // The backend read `base-artifact.json` once at boot, so the replacement must re-announce its boot state.
     await host.waitForLogSince(start, /announced boot state after recycle/, WAIT_MS);
 
     const recycled = await DevStabilityHarness.builderProcess(host.proc.pid);
     expect(recycled).not.toBeNull();
     expect(String(recycled?.pid)).not.toBe(recycleLog[1]);
 
-    // And the dev server is still a dev server: the replacement watches, rebuilds and serves.
-    //
-    // Waiting for readiness above is load-bearing, not padding. The watcher is installed at the end of
-    // the boot build, so a save during the recycle is seen by neither builder — this test lost one
-    // exactly that way.
+    // The readiness waits above are load-bearing: a save during the recycle is seen by neither builder.
     const postRecycle = await harness.editUntilSeen(host, (attempt) =>
       harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-after-recycle-${attempt}`),
     );
@@ -676,9 +579,7 @@ describe("dev resource budgets", () => {
     );
     await harness.waitForHttpText("marker-after-recycle", WAIT_MS);
 
-    // This fixture's builder boots well under the ceiling and blows past it on its first build, which
-    // is the shape of every app the ceiling is derived for — a 1.2GB sandbox gives the builder ~420MB
-    // and a single route build costs ~247MB. So the host says the ceiling is tight...
+    // A tight ceiling is reported, and still enforced (recycles are throttled), never disabled for the session.
     for (let i = 1; i <= 3; i++) {
       const { mark } = await harness.editUntilSeen(host, (attempt) =>
         harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-settled-${i}-${attempt}`),
@@ -686,80 +587,53 @@ describe("dev resource budgets", () => {
       await host.waitForLogSince(mark, /pages-rebundle ok/, WAIT_MS).catch(() => undefined);
     }
     await host.waitForLogSince(start, /ceiling costs about one boot build per interval/, WAIT_MS);
-    // ...and goes on enforcing it. This used to disable the ceiling for the rest of the session on the
-    // same evidence, which on a small sandbox means nothing bounds the builder from the first page load
-    // onwards. Recycling is throttled to one per interval; that throttle is the answer to the cost, not
-    // dropping the bound.
     expect(host.logs.join("").slice(start)).not.toMatch(/no longer enforcing it this session/);
   });
 
-  // The guard the memory work did not have. Every budget above asserts RSS; none of them asserts that a
-  // page still renders while the machinery those budgets require is mid-swap — and that gap is where two
-  // shipped defects lived (`local/optimize-resource/19-shutdown-and-restart-races.md`).
   budgetTest("serves a page requested while the builder is being replaced", async () => {
     const harness = await createHarness();
-    // Same unmeetable ceiling as the guard above, for the same reason: a builder that no longer grows
-    // into a ceiling has to start under one for the recycle path to run end to end.
     const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_BUILDER_MAX_RSS_MB: "200" } });
     const port = await harness.resolvePort();
     await harness.waitForHttpText("initial-client-marker", WAIT_MS);
 
     const start = host.markLog();
-    // One save does both halves of the setup: it drops the route's client entries, so the next request
-    // has to ask the builder again rather than being served from cache, and it makes the builder report
-    // an rss over the ceiling, which is what arms the recycle.
+    // One save both evicts the route's cached client entries and arms the recycle.
     const { mark } = await harness.editUntilSeen(host, (attempt) =>
       harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-through-recycle-${attempt}`),
     );
     await host.waitForLogSince(mark, /pages-rebundle ok/, WAIT_MS);
 
-    // A builder that has been asked to drain is still alive and refuses everything new, so this request
-    // has to be held for the replacement exactly like one that arrives after the process is gone. Timing
-    // decides which of the two windows it actually lands in — the drain of an idle builder is short, and
-    // the log is polled — so what is asserted is the outcome both windows must produce. The drain itself
-    // is pinned deterministically one layer down, in `incrementalBuilder.host.test.ts`.
+    // Timing decides whether this lands in the drain or after the exit, so assert what both must produce.
     await host.waitForLogSince(start, /recycling builder pid=\d+/, WAIT_MS);
-    // Not awaited here: a held request only returns once the replacement is up, and waiting for it would
-    // put every assertion below on the far side of the window they are about.
+    // Not awaited: a held request returns only once the replacement is up.
     const drainRequest = fetch(`http://127.0.0.1:${port}/`, { signal: AbortSignal.timeout(WAIT_MS) }).then(
       async (response) => ({ status: response.status, html: await response.text() }),
     );
 
-    // Wait until the replacement exists but is still doing its boot build. From here it cannot answer
-    // anything for seconds — which is exactly the window a developer's reload lands in, and the point of
-    // anchoring on the spawn rather than on the exit: the gap after it is wide and known, not a race.
+    // Anchored on the spawn: the replacement's boot build leaves a wide, known window rather than a race.
     await host.waitForLogSince(start, /exiting for recycle/, WAIT_MS);
     await host.waitForLogSince(start, /builder spawned pid=\d+ .*restart=1/, WAIT_MS);
 
     const holdMark = host.markLog();
     const startedAtMono = performance.now();
-    // The second route, never requested before, so this one cannot be answered from the route cache the
-    // request above just populated — it has to reach a builder that is not there yet.
+    // Never requested before, so no route cache can answer it; it has to reach a builder that is not there yet.
     const res = await fetch(`http://127.0.0.1:${port}/second`, { signal: AbortSignal.timeout(WAIT_MS) });
     const html = await res.text();
     const heldMs = Math.round(performance.now() - startedAtMono);
 
-    // What the developer sees, asserted first because it is the whole point: with the hold removed this
-    // same request is answered **500** by the dev error page, and nothing retries on its own — the tab
-    // stays broken until it is reloaded by hand. Measured both ways before this guard was committed.
+    // Without the hold this is a 500 from the dev error page, which never retries on its own.
     expect(res.status).toBe(200);
     expect(html).toContain("marker-through-recycle");
     expect(html).not.toContain("reload after the builder is ready");
-    // And this is what stops the test passing having tested nothing: a request that arrives after the
-    // replacement is already ready never reaches the path under test, and everything above holds anyway.
+    // Proves the request reached the hold, rather than arriving after the replacement was already ready.
     expect(host.logs.join("").slice(holdMark)).toMatch(/holding build-route until the builder is ready/);
 
-    // The one fired at the drain, whichever side of the exit it landed on.
     const drained = await drainRequest;
     expect(drained.status).toBe(200);
     expect(drained.html).toContain("marker-through-recycle");
     console.info(`[restart-guard] page held ${heldMs}ms across the recycle, then rendered`);
   });
 
-  // The other half of a resource budget, and the half this plan spent: every megabyte above was bought
-  // with latency — a worker process spawned per save, a boot build per recycle and per wake, a hold
-  // window in front of requests that land in one. Nothing measured what that cost, so a change that
-  // traded another second per save for another 50MB would have passed every guard in this block.
   budgetTest("keeps a save's round trip inside its budget", async () => {
     const harness = await createHarness();
     const host = await harness.startHost({ timeoutMs: BOOT_MS });
@@ -768,45 +642,37 @@ describe("dev resource budgets", () => {
     const samples: number[] = [];
     for (let i = 1; i <= 3; i++) {
       let savedAtMono = 0;
-      // Timed from inside the mutate callback so a retried save — Bun drops watcher events, which is why
-      // `editUntilSeen` exists — is measured from the attempt that actually landed, not from the first.
+      // Timed inside the mutate callback, so a retried save is measured from the attempt that landed.
       const { mark } = await harness.editUntilSeen(host, async (attempt) => {
         await harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-latency-${i}-${attempt}`);
         savedAtMono = performance.now();
       });
-      // The moment the running dev server is serving the new code, which is everything the developer is
-      // waiting for. Deliberately not the browser's refresh message: that one is only published when a
-      // client is connected, so measuring it would measure a WebSocket probe's reconnects as well.
+      // Not the refresh message: that is published only while a client is connected.
       await host.waitForLogSince(mark, /\[hmr\] backend apply/, WAIT_MS);
       samples.push(performance.now() - savedAtMono);
     }
 
     const rounded = samples.map((ms) => Math.round(ms));
     console.info(`[latency-guard] save -> new code live ${rounded.join("ms, ")}ms`);
-    // Per save, not summed: the interesting regression is one save getting slower, and the median would
-    // hide a first save that pays for something the rest do not.
+    // The worst save, not a median, which would hide a first save that pays for something the rest do not.
     expect(Math.max(...rounded)).toBeLessThan(SAVE_LATENCY_BUDGET_MS);
   });
 
   budgetTest("suspends the builder when the dev server goes idle and wakes it on the next edit", async () => {
     const harness = await createHarness();
-    // 3s stands in for the 5min default: the machinery is the same, and the guard needs the dev server
-    // to actually reach idle inside a test.
+    // 3s stands in for the 5min default so the dev server reaches idle inside a test.
     const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_DEV_IDLE_SUSPEND_MS: "3000" } });
     const start = host.markLog();
     await harness.waitForHttpText("initial-client-marker", WAIT_MS);
 
-    // Nothing periodic may keep the dev server "busy": if the builder reported metrics on a timer, or
-    // the backend wrote a watched file, this would never fire.
+    // Never fires if anything periodic (timed metrics, a watched-file write) keeps the dev server busy.
     await host.waitForLogSince(start, /\[idle-suspend\] no build activity for \d+s; released the builder/, WAIT_MS);
     const suspendedBuilder = await DevStabilityHarness.builderProcess(host.proc.pid);
     expect(suspendedBuilder).toBeNull();
     // Only build capacity suspends — the backend keeps serving the preview URL.
     await harness.waitForHttpText("initial-client-marker", WAIT_MS);
 
-    // The edit that has to wake it. A suspended host has just installed a fresh watcher over a tree the
-    // suspend itself churned, so this is squarely inside Bun's drop window — it is what failed here in a
-    // 3-way parallel run, on 60s of empty log output.
+    // A fresh watcher over a tree the suspend just churned: squarely inside Bun's drop window.
     const { mark } = await harness.editUntilSeen(
       host,
       (attempt) => harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-after-wake-${attempt}`),
@@ -821,7 +687,6 @@ describe("dev resource budgets", () => {
     await harness.waitForHttpText("marker-after-wake", WAIT_MS);
     console.info(`[idle-suspend-guard] woke in ${awake[1]}ms; builder back at pid=${wokenBuilder?.pid}`);
 
-    // And it is a normal dev server again afterwards.
     const postWake = await harness.editUntilSeen(host, (attempt) =>
       harness.replaceText("ui/ClientMarker.tsx", /marker(-[\w-]+)?/, `marker-postwake-${attempt}`),
     );
@@ -838,8 +703,7 @@ describe("dev resource budgets", () => {
     await host.waitForLogSince(start, /\[idle-suspend\] .*released the builder/, WAIT_MS);
     expect(await DevStabilityHarness.builderProcess(host.proc.pid)).toBeNull();
 
-    // A browser asking for something the backend cannot serve on its own is the other wake trigger, and
-    // the request must not be answered with "builder is stopped" the way a dead builder's would be.
+    // A request only the builder can serve also wakes it, and must not be answered "builder is stopped".
     const mark = host.markLog();
     const port = await harness.resolvePort();
     const status = await fetch(`http://127.0.0.1:${port}/__csr`)
@@ -847,19 +711,13 @@ describe("dev resource budgets", () => {
       .catch(() => 0);
 
     await host.waitForLogSince(mark, /\[idle-suspend\] waking \(build-csr arrived while suspended\)/, WAIT_MS);
-    // `[builder]`, not `[idle-suspend]`: the same queue now also holds requests across a builder restart,
-    // so the replay says what it did rather than which of the two reasons put the request there. The wake
-    // line above is what distinguishes them, and it is asserted first for that reason.
+    // `[builder]`: the same queue holds requests across a restart too; the wake line above tells them apart.
     await host.waitForLogSince(mark, /\[builder\] replaying 1 request\(s\) held while the builder was away/, WAIT_MS);
     expect(status).toBe(200);
     expect(await DevStabilityHarness.builderProcess(host.proc.pid)).not.toBeNull();
   });
 
-  // The gap on the other side of the same window: requests held across it are answered, but for a while
-  // nothing was *watching* across it. The suspend stops its watcher before the replacement builder has
-  // primed its index, and the replacement primes from the disk it finds — so a save in between is
-  // baseline to it, reported by nobody, and the backend goes on running the code it replaced. Phase 2
-  // made this window routine by recycling the builder on every rss ceiling crossing.
+  // Nothing watches between the suspend stopping its watcher and the replacement priming its index from disk.
   budgetTest("restarts the backend for a save that lands while the builder is away", async () => {
     const harness = await createHarness();
     const host = await harness.startHost({ timeoutMs: BOOT_MS, env: { AKAN_DEV_IDLE_SUSPEND_MS: "3000" } });
@@ -869,13 +727,9 @@ describe("dev resource budgets", () => {
 
     const mark = host.markLog();
     const port = await harness.resolvePort();
-    // This request is the clock: it wakes the dev server and is answered only once the replacement
-    // builder is ready, so a write issued while it is in flight lands squarely inside the gap. Its own
-    // status is not asserted here — the write below restarts the backend, which drops the connection.
+    // The clock: in flight until the replacement is ready; its status is moot once the backend restarts.
     const request = fetch(`http://127.0.0.1:${port}/__csr`).catch(() => null);
-    // A service the backend imports, rather than this fixture's `srvkit/backendMarker.ts`: that marker is
-    // orphaned once `akan start` regenerates `server.ts`, so it is not in the backend graph at all and an
-    // edit to it restarts the backend by path role instead.
+    // Not `srvkit/backendMarker.ts`: the regenerated `server.ts` orphans it, so it restarts by path role only.
     await harness.writeFile(
       "lib/_fixture/fixture.service.ts",
       `import { serve } from "akanjs/service";
@@ -888,7 +742,6 @@ export class FixtureService extends serve("fixture" as const, { serverMode: "bat
 
     await host.waitForLogSince(mark, /\[builder-gap\] 1 backend file\(s\) changed while the builder was away/, WAIT_MS);
     await host.waitForLogSince(mark, /\[backend-reload\]/, WAIT_MS);
-    // And back to a working dev server, rather than one stuck restarting.
     await host.waitForLogSince(mark, /backend ready pid=(\d+)|AkanApp gateway is running on port/, WAIT_MS);
     await harness.waitForHttpText("initial-client-marker", WAIT_MS);
   });