@akanjs/devkit 3.0.0-beta.8 → 3.0.0

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

@@ -1,5 +1,7 @@
 import { describe, expect, test } from "bun:test";
 import type { BuilderMessage, BuildPhase, DevBuildStatus, DevChangeAction } from "akanjs/server";
+//? The source itself, not the package: the published akanjs exports no such subpath, and tests are not bundled.
+import { DevBuildRecovery } from "../../../akanjs/server/artifact/devBuildRecovery";
 import {
   backendRestartReasonFromMessage,
   buildStatusReplaySequence,
@@ -17,6 +19,7 @@ import {
   resolveIdleSuspendMs,
   shouldAbandonBackendRecovery,
   shouldHoldForReturningBuilder,
+  shouldKeepBuildFailure,
   shouldMarkBuildPhaseRecovered,
   shouldQueueBuildStatusReplay,
   shouldRefreshConfigOnIdleWake,
@@ -28,6 +31,13 @@ import {
   shouldWarnBuilderRssCeilingTight,
 } from "./devHostPolicy";
 
+const status = (phase: BuildPhase, generation: number, ok: boolean): DevBuildStatus => ({
+  generation,
+  phase,
+  ok,
+  files: [],
+});
+
 const invalidateWithActions = (actions: DevChangeAction[]): Extract<BuilderMessage, { type: "invalidate" }> => ({
   type: "invalidate",
   kinds: ["code"],
@@ -158,8 +168,6 @@ describe("holding requests for a returning builder", () => {
   });
 
   test("holds through the drain too, not only after the process is gone", () => {
-    // The window this decision originally missed: the builder is still alive and refusing, which is
-    // the same gap as a restart from anyone waiting on a page.
     expect(shouldHoldForReturningBuilder({ status: "recycling", heldCount: 0 })).toBe(true);
   });
 
@@ -196,8 +204,6 @@ describe("builder rss recycle", () => {
     expect(decide({ ceilingBytes: null })).toBe("unbounded");
   });
 
-  // Rebooting on a generation whose build failed strands the dev server: the replacement hits the
-  // same compile error and exits before builder-ready.
   test("defers while the current generation has a failing build", () => {
     expect(decide({ buildFailed: true })).toBe("build-failed");
   });
@@ -208,34 +214,25 @@ describe("builder rss recycle", () => {
     expect(decide({ msSinceLastRecycle: 5_000, minIntervalMs: 1_000 })).toBe("recycle");
   });
 
-  // Says so, and keeps enforcing: a page load is two route builds, so an app whose builds sit over the
-  // ceiling reaches this on its first navigation — which is normal work, not a reason to drop the only
-  // bound the builder has.
   test("mentions a tight ceiling rather than acting on it", () => {
     expect(shouldWarnBuilderRssCeilingTight(1)).toBe(false);
     expect(shouldWarnBuilderRssCeilingTight(2)).toBe(true);
     expect(shouldWarnBuilderRssCeilingTight(1, 1)).toBe(true);
   });
 
-  // The one case recycling cannot fix, measured on the replacement before it has built anything: every
-  // future replacement lands on the same floor, so the loop would only ever cost boot builds.
   test("gives up only when a fresh builder is already over the ceiling", () => {
     expect(isRssCeilingUnreachable(ceiling + 1, ceiling)).toBe(true);
     expect(isRssCeilingUnreachable(ceiling - 1, ceiling)).toBe(false);
-    // An unreadable rss is no information, and no ceiling is nothing to be unreachable.
     expect(isRssCeilingUnreachable(null, ceiling)).toBe(false);
     expect(isRssCeilingUnreachable(ceiling + 1, null)).toBe(false);
   });
 
-  // Measured on Linux: the builder peaked at 522MiB and settled at 214MiB with no help, so a 400MiB
-  // ceiling recycled a process that was already back under it. The armed sample is always the peak.
   describe("settle check before committing", () => {
     test("waits when the builder is only modestly over the ceiling", () => {
       expect(decideBuilderRssSettle({ rssBytes: 522, ceilingBytes: 400 })).toBe("wait-and-recheck");
       expect(decideBuilderRssSettle({ rssBytes: 401, ceilingBytes: 400 })).toBe("wait-and-recheck");
     });
 
-    // No purge is going to rescue a builder this far over, so waiting only delays the inevitable.
     test("recycles immediately once far enough past the ceiling", () => {
       expect(decideBuilderRssSettle({ rssBytes: 600, ceilingBytes: 400 })).toBe("recycle-now");
       expect(decideBuilderRssSettle({ rssBytes: 900, ceilingBytes: 400 })).toBe("recycle-now");
@@ -268,7 +265,6 @@ describe("dev idle suspend", () => {
     expect(decide({ restartPending: true })).toBe("restart-pending");
   });
 
-  // A wake would boot straight back into the same compile error, and the developer is mid-fix anyway.
   test("never suspends on a red build", () => {
     expect(decide({ buildFailed: true })).toBe("build-failed");
   });
@@ -288,15 +284,15 @@ describe("dev idle suspend", () => {
     expect(resolveIdleSuspendMs("1500")).toBe(1_500);
   });
 
-  test("blocks a suspend on a failure in any phase, not just the newest generation", () => {
-    const status = (phase: BuildPhase, ok: boolean): DevBuildStatus => ({ generation: 1, phase, ok, files: [] });
+  test("blocks a suspend on a failure in any phase but a route's, not just the newest generation", () => {
     expect(hasAnyBuildFailure(new Map())).toBe(false);
-    expect(hasAnyBuildFailure(new Map([["scan", status("scan", true)]]))).toBe(false);
+    expect(hasAnyBuildFailure(new Map([["route", status("route", 1, false)]]))).toBe(false);
+    expect(hasAnyBuildFailure(new Map([["scan", status("scan", 1, true)]]))).toBe(false);
     expect(
       hasAnyBuildFailure(
         new Map([
-          ["scan", status("scan", true)],
-          ["pages", status("pages", false)],
+          ["scan", status("scan", 1, true)],
+          ["pages", status("pages", 1, false)],
         ]),
       ),
     ).toBe(true);
@@ -332,8 +328,6 @@ describe("recycled builder state announcements", () => {
     },
   });
 
-  // Both identities are content hashes, so a recycle with no concurrent edit reproduces them exactly
-  // and must not reload the backend — that would refresh every browser on a memory recycle.
   test("suppresses an unchanged pages announcement and relays a moved one", () => {
     expect(shouldRelayRecycledFrontendState(pages("/a/pages-abc.js"), pages("/a/pages-abc.js"))).toBe(false);
     expect(shouldRelayRecycledFrontendState(pages("/a/pages-abc.js"), pages("/a/pages-def.js"))).toBe(true);
@@ -355,13 +349,6 @@ describe("recycled builder state announcements", () => {
 });
 
 describe("build status helpers", () => {
-  const status = (phase: DevBuildStatus["phase"], generation: number, ok: boolean): DevBuildStatus => ({
-    generation,
-    phase,
-    ok,
-    files: [],
-  });
-
   test("tracks recovery by phase without unrelated phases masking failures", () => {
     const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([
       ["pages", status("pages", 10, false)],
@@ -372,6 +359,67 @@ 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("the same route built again recovers at the failure's generation or later, and another route's ok never does", () => {
+    const routeA = (ok: boolean, generation = 4) => ({ ...status("route", generation, ok), scope: "/:lang/a" });
+    const routeB = (ok: boolean, generation = 4) => ({ ...status("route", generation, ok), scope: "/:lang/b" });
+    const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["route", routeA(false)]]);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeA(true))).toBe(true);
+    expect(shouldKeepBuildFailure(previousByPhase, routeA(true))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeB(true))).toBe(false);
+    expect(shouldKeepBuildFailure(previousByPhase, routeB(true))).toBe(true);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeB(true, 5))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, routeA(true, 5))).toBe(true);
+    expect(shouldKeepBuildFailure(previousByPhase, routeA(true, 3))).toBe(true);
+  });
+
+  test("judges recovery as the backend does (akanjs DevBuildRecovery), case for case", () => {
+    const at = (phase: BuildPhase, generation: number, ok: boolean, scope?: string): DevBuildStatus => ({
+      ...status(phase, generation, ok),
+      ...(scope ? { scope } : {}),
+    });
+    const cases: [DevBuildStatus | undefined, DevBuildStatus][] = [];
+    for (const phase of ["backend", "route", "scan", "pages", "ssr"] as BuildPhase[])
+      for (const [previousOk, ok] of [
+        [false, true],
+        [true, true],
+        [false, false],
+      ])
+        for (const generation of [3, 4, 5])
+          for (const [previousScope, scope] of [
+            [undefined, undefined],
+            ["/a", "/a"],
+            ["/a", "/b"],
+          ])
+            cases.push([at(phase, 4, previousOk, previousScope), at(phase, generation, ok, scope)]);
+    cases.push([undefined, at("pages", 4, true)]);
+    for (const [previous, next] of cases) {
+      const previousByPhase = new Map<BuildPhase, DevBuildStatus>(previous ? [[previous.phase, previous]] : []);
+      expect([previous, next, shouldMarkBuildPhaseRecovered(previousByPhase, next)]).toEqual([
+        previous,
+        next,
+        DevBuildRecovery.recovers(previous, next),
+      ]);
+    }
+  });
+
+  test("a builder that came back clears no config change still on hold, or one that failed to apply", () => {
+    const previousByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["scan", status("scan", 42, false)]]);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("scan", 42, true))).toBe(false);
+    expect(shouldMarkBuildPhaseRecovered(previousByPhase, status("scan", 43, true))).toBe(true);
+  });
+
   test("creates backend build-status payloads for lifecycle test hooks", () => {
     expect(
       createBackendBuildStatus({
@@ -441,13 +489,6 @@ describe("backend recovery abandonment", () => {
 });
 
 describe("hasBuildFailureForGeneration", () => {
-  const status = (phase: DevBuildStatus["phase"], generation: number, ok: boolean): DevBuildStatus => ({
-    generation,
-    phase,
-    ok,
-    files: [],
-  });
-
   test("detects a failing phase recorded for the same generation", () => {
     const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([
       ["csr", status("csr", 3, false)],
@@ -464,6 +505,11 @@ describe("hasBuildFailureForGeneration", () => {
     expect(hasBuildFailureForGeneration(statusByPhase, 4)).toBe(false);
   });
 
+  test("leaves a route's failure out: nothing a replacement builder boots builds a route", () => {
+    const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["route", status("route", 42, false)]]);
+    expect(hasBuildFailureForGeneration(statusByPhase, 42)).toBe(false);
+  });
+
   test("treats unknown generations and green boards as healthy", () => {
     const statusByPhase = new Map<DevBuildStatus["phase"], DevBuildStatus>([["csr", status("csr", 3, false)]]);
     expect(hasBuildFailureForGeneration(statusByPhase, undefined)).toBe(false);

package/akanApp/devHostPolicy.ts

@@ -11,11 +11,7 @@ import type { IncrementalBuilderStatus } from "../incrementalBuilder";
 
 const BACKEND_RECOVERY_MAX_ATTEMPTS = 5;
 
-/**
- * How many requests may wait for a builder that is coming back. Generous — a page load asks for
- * several routes — but finite, so a builder that never returns cannot grow this without bound. Past
- * it, requests are failed as they were before, which is the behaviour this limit falls back to.
- */
+// A page load asks for several routes, but a builder that never returns must not grow the hold queue unbounded.
 const HELD_BUILDER_REQUEST_LIMIT = 64;
 
 export const BUILDER_MIN_RSS_RECYCLE_INTERVAL_MS = 30_000;
@@ -25,8 +21,6 @@ const BUILDER_TIGHT_RSS_REPORT_LIMIT = 2;
 // Far enough above the ceiling that no purge would rescue it; recycle without waiting.
 const BUILDER_RSS_HARD_MULTIPLE = 1.5;
 
-// A sandbox between user turns pays for a watcher that is watching nothing change. Suspending build
-// capacity after this long returns the builder's residency until the next edit or route request.
 const DEV_IDLE_SUSPEND_MS = 300_000;
 
 // A wake that immediately suspends again would flap around whatever woke it.
@@ -34,7 +28,6 @@ const DEV_IDLE_MIN_UPTIME_MS = 30_000;
 
 export const SOURCE_EXTS = new Set([".ts", ".tsx", ".js", ".jsx", ".mjs", ".cjs"]);
 
-/\.(css|scss|sass|less|json|svg|png|jpe?g|webp|gif|avif|ico|woff2?|ttf|otf|mp3|mp4|wav|html)$/i;
 const SERVER_SUFFIXES = [".service.ts", ".document.ts"];
 
 const SHARED_SUFFIXES = [".constant.ts", ".dictionary.ts", ".signal.ts"];
@@ -53,10 +46,6 @@ export const shouldRestartBackendByDevPlan = (
 export const shouldRestartBuilderByDevPlan = (message: Extract<BuilderMessage, { type: "invalidate" }>): boolean =>
   message.devPlan?.actions.includes("restart-builder") ?? false;
 
-/**
- * A backend that keeps dying isn't going to heal by retrying the same code; after this many
- * consecutive attempts the host idles and the next server-side edit triggers a fresh restart.
- */
 export const shouldAbandonBackendRecovery = (attempts: number, maxAttempts = BACKEND_RECOVERY_MAX_ATTEMPTS): boolean =>
   attempts >= maxAttempts;
 
@@ -69,19 +58,23 @@ export const shouldRestartDevHostByDevPlan = (message: Extract<BuilderMessage, {
 
 export type BackendLifecycleState = "starting" | "ready" | "restart-pending" | "stopping" | "recovering" | "stopped";
 
-/**
- * What a dev host tells a supervising process about itself. Reported rather than scraped: the parent
- * gets one pipe of interleaved child output, in which "this app is up" is indistinguishable from a line
- * that merely mentions it.
- */
+/** 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",
@@ -91,11 +84,7 @@ const devHostStateByBackendState = {
   stopped: "stopped",
 } as const satisfies { [key in BackendLifecycleState]: DevHostState };
 
-/**
- * The backend's own lifecycle collapsed to what a supervisor can act on. `stopped` is the one state
- * that is ambiguous on its own — a planned shutdown and a crash loop that ran out of retries both land
- * there — so the give-up flag is what separates "gone" from "broken".
- */
+/** `stopped` is both a planned shutdown and an exhausted crash loop; `gaveUp` maps the latter to `failed`. */
 export const devHostStateOf = (state: BackendLifecycleState, gaveUp: boolean): DevHostState =>
   state === "stopped" && gaveUp ? "failed" : devHostStateByBackendState[state];
 
@@ -131,14 +120,29 @@ export const isLegacyBackendFallbackFile = (file: string, workspaceRoot: string)
   );
 };
 
+//? The backend's rule (akanjs `DevBuildRecovery`), copied: no exported akanjs subpath reaches it from the CLI bundle.
 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 || previous.ok || !status.ok) return false;
+  const generation = generationValue(status.generation);
+  if (status.phase === "route" && status.scope !== undefined && previous.scope !== undefined)
+    return status.scope === previous.scope && generation >= previous.generation;
+  if (generation !== previous.generation) return generation > previous.generation;
+  return status.phase === "backend";
 };
 
+/** 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,
@@ -192,34 +196,22 @@ export const shouldReplaceLastGoodMessage = (
 export const shouldQueueBuildStatusReplay = (backendReady: boolean, pendingReplayCount: number): boolean =>
   !backendReady || pendingReplayCount > 0;
 
-/**
- * Recycling the builder/backend on a generation whose build already failed is guaranteed to strand
- * the dev server: the rebooted builder hits the same compile error and exits before builder-ready.
- * Failing phase statuses for a generation arrive over IPC before that generation's invalidate, so
- * the host can check them here and defer the recycle until a healthy batch lands.
- */
+/** Failing statuses arrive before their generation's invalidate; recycling on one strands the dev server. */
 export const hasBuildFailureForGeneration = (
   statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
   generation: number | undefined,
 ): boolean => {
   if (typeof generation !== "number") return false;
   for (const status of statusByPhase.values()) {
-    if (!status.ok && status.generation === generation) return true;
+    //? Not a route's: a replacement builder or a restarted dev host boots without building one, so it cannot hit it.
+    if (!status.ok && status.phase !== "route" && status.generation === generation) return true;
   }
   return false;
 };
 
 export type BuilderRssRecycleDecision = "unbounded" | "below-ceiling" | "build-failed" | "too-soon" | "recycle";
 
-/**
- * Whether an over-ceiling builder should be replaced now.
- *
- * `Bun.build` never returns its native arenas, so the builder's RSS only comes back when the process
- * exits. Recycling it is therefore the only bound available — but it costs a boot build, so the two
- * cases where a recycle cannot help are excluded: a generation whose build already failed (the
- * replacement would hit the same compile error), and a recycle so soon after the last one that the
- * ceiling is evidently unreachable for this app.
- */
+/** `Bun.build` never returns its native arenas, so recycling the builder is the only bound on its RSS. */
 export const decideBuilderRssRecycle = ({
   rssBytes,
   ceilingBytes,
@@ -242,11 +234,6 @@ export const decideBuilderRssRecycle = ({
 
 export type BuilderRssSettleDecision = "recycle-now" | "wait-and-recheck";
 
-/**
- * Whether an armed recycle should wait out the allocator's purge window before committing. A builder
- * far enough over the ceiling is not going to be rescued by a purge, so waiting there only delays a
- * recycle that has to happen.
- */
 export const decideBuilderRssSettle = ({
   rssBytes,
   ceilingBytes,
@@ -267,15 +254,7 @@ export type IdleSuspendDecision =
   | "too-soon"
   | "suspend";
 
-/**
- * Whether the dev host may drop its build capacity now. Every "no" here is a case where suspending
- * would either lose work or produce a wake that immediately re-suspends:
- *
- * - a red build means the developer is mid-fix and about to save again, and a wake would boot straight
- *   back into the same error via the degraded-boot path
- * - a pending restart/recovery already has its own plan for the builder
- * - `too-soon` keeps a wake from flapping around whatever triggered it
- */
+/** A red build means a save is imminent, and a wake would boot straight back into the same error. */
 export const decideIdleSuspend = ({
   enabled,
   suspended,
@@ -313,28 +292,14 @@ export const resolveIdleSuspendMs = (raw: string | undefined): number | null =>
   return Math.round(parsed);
 };
 
-/** Any red phase blocks a suspend, unlike the rss recycle which only cares about one generation. */
+//? Not a route's: a broken route builds again on its next request, which wakes a suspended builder anyway.
 export const hasAnyBuildFailure = (statusByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>): boolean =>
-  [...statusByPhase.values()].some((status) => !status.ok);
+  [...statusByPhase.values()].some((status) => !status.ok && status.phase !== "route");
 
-/**
- * A config change while suspended cannot be applied by restarting the builder alone — the dev host
- * itself has to re-read the config, which is the same path an ordinary config save takes.
- */
 export const shouldRefreshConfigOnIdleWake = (batch: ChangeBatch | null): boolean =>
   !!batch && batch.kinds.has("config");
 
-/**
- * Whether a request that arrived while the builder was away should wait for the one coming back.
- *
- * A recycle or a crash-restart is a gap, not a failure — the request that lands in it is the page a
- * developer is waiting on. A stopped builder is a different thing: nothing is bringing it back, so
- * waiting would only delay the error.
- *
- * `recycling` is in here for the same reason as `restarting`, and was the hole this decision shipped
- * with: a draining builder is still alive, so the request reached it and came back refused while the
- * host still thought there was nothing to wait for.
- */
+// `recycling` too: a draining builder is alive and refuses; nothing brings a `stopped` one back, so it fails fast.
 const RETURNING_BUILDER_STATUSES = new Set<IncrementalBuilderStatus>(["starting", "recycling", "restarting"]);
 export const shouldHoldForReturningBuilder = ({
   status,
@@ -346,37 +311,17 @@ export const shouldHoldForReturningBuilder = ({
   limit?: number;
 }): boolean => RETURNING_BUILDER_STATUSES.has(status) && heldCount < limit;
 
-/**
- * Whether a builder that is over the ceiling again this soon after being replaced is worth saying so
- * about, once. Not a reason to stop enforcing the ceiling: the minimum interval already bounds what
- * this costs at one recycle per interval, and dropping the bound is how a container gets OOM-killed.
- *
- * This used to disable the ceiling for the session, on a count that a single page load reaches — two
- * route builds, two reports, both inside the interval. That is normal work on any app whose builds sit
- * above the ceiling, which is the same app the ceiling was derived for.
- */
+/** Warn only, never stop enforcing: dropping the ceiling is how a container gets OOM-killed. */
 export const shouldWarnBuilderRssCeilingTight = (
   reportsSinceRecycle: number,
   limit = BUILDER_TIGHT_RSS_REPORT_LIMIT,
 ): boolean => reportsSinceRecycle >= limit;
 
-/**
- * Whether recycling can ever bring this builder under the ceiling.
- *
- * Measured on a replacement the moment it is ready, before it has built anything on demand: that is
- * the floor every future replacement lands on, so a floor already over the ceiling is the one case
- * where the recycle loop is pure cost. It is also the case the escape hatch was always described as
- * being for — the previous rule inferred it from report timing and caught ordinary work instead.
- */
+/** Takes a fresh replacement's RSS: the floor every future replacement lands on. */
 export const isRssCeilingUnreachable = (freshRssBytes: number | null, ceilingBytes: number | null): boolean =>
   freshRssBytes !== null && ceilingBytes !== null && freshRssBytes >= ceilingBytes;
 
-/**
- * Whether a recycled builder's re-announced boot artifact actually differs from what the backend
- * already has. Both payload identities are content hashes — `pages-[hash].js` and
- * `<name>-[hash].css` — so an unchanged recycle produces identical ones and needs no reload. Only a
- * save that raced the recycle moves them, and that is the case worth pushing.
- */
+/** Both identities are content hashes (`pages-[hash].js`, `<name>-[hash].css`), unchanged by a clean recycle. */
 export const shouldRelayRecycledFrontendState = (
   current:
     | Extract<BuilderMessage, { type: "pages-updated" }>
@@ -409,7 +354,6 @@ const mergeDevPlans = (current?: DevChangePlan, next?: DevChangePlan): DevChange
   };
 };
 
-/** A deferred recycle accumulates every batch it skipped so the eventual restart covers them all. */
 export const mergeInvalidateMessages = (
   current: Extract<BuilderMessage, { type: "invalidate" }>,
   next: Extract<BuilderMessage, { type: "invalidate" }>,
@@ -429,14 +373,9 @@ export const buildStatusReplaySequence = (
   latestByPhase: ReadonlyMap<BuildPhase, DevBuildStatus>,
 ): DevBuildStatus[] => [...pendingReplay, ...latestByPhase.values()];
 
-/** `(mtimeMs, size)` per file — what a save moves, and what a rebuild of identical content does not. */
+/** `mtimeMs:size` per file. */
 export type SourceFingerprints = ReadonlyMap<string, string>;
 
-/**
- * Which of the files in `before` are no longer stamped the way they were.
- *
- * Only files present in `before` are compared. The question this answers is which *running* code went
- * stale while nothing was watching, and a file that did not exist then is not running anywhere.
- */
+/** Only files in `before`: a file that did not exist then is not running anywhere. */
 export const filesChangedSince = (before: SourceFingerprints, after: SourceFingerprints): string[] =>
   [...before].filter(([file, stamp]) => after.get(file) !== stamp).map(([file]) => file);

package/akanConfig/akanBin.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, test } from "bun:test";
+import path from "node:path";
+import { AkanBin } from "./akanBin";
+
+const owner = "apps/portal/akan.config.ts";
+const sha256 = "A".repeat(64);
+
+describe("AkanBin.parse", () => {
+  test("takes a download checked by its hash, or a file relative to the declaring folder", () => {
+    expect(
+      AkanBin.parse(
+        {
+          ffmpeg: {
+            "linux-x64": { url: "https://files.test/ffmpeg-linux64-lgpl.tar.xz", sha256, file: "./ffmpeg\\bin/ffmpeg" },
+            "darwin-arm64": { path: "tools/ffmpeg" },
+          },
+        },
+        owner,
+        "/repo/apps/portal",
+      ),
+    ).toEqual({
+      ffmpeg: {
+        "linux-x64": {
+          url: "https://files.test/ffmpeg-linux64-lgpl.tar.xz",
+          sha256: "a".repeat(64),
+          file: "ffmpeg/bin/ffmpeg",
+        },
+        "darwin-arm64": { path: path.resolve("/repo/apps/portal/tools/ffmpeg") },
+      },
+    });
+    expect(AkanBin.parse(undefined, owner, "/repo/apps/portal")).toEqual({});
+  });
+
+  test("names the declaration that is wrong", () => {
+    const parse = (bin: unknown) => () => AkanBin.parse(bin, owner, "/repo/apps/portal");
+    expect(parse(["ffmpeg"])).toThrow(`${owner}: bin maps each executable's name`);
+    expect(parse({ "../ffmpeg": {} })).toThrow("bin.../ffmpeg is not a file name");
+    expect(parse({ ffmpeg: { "darwin-universal": { path: "x" } } })).toThrow(
+      "bin.ffmpeg.darwin-universal is not one of darwin-arm64",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { url: "https://x.test/ffmpeg", sha256, path: "x" } } })).toThrow(
+      "takes either url and sha256, or path",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { url: "ftp://x.test/ffmpeg", sha256 } } })).toThrow(
+      "url must be an http(s) address",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { url: "https://x.test/ffmpeg", sha256: "abc" } } })).toThrow(
+      "sha256 must be the downloaded file's 64-digit hex digest",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { path: "ffmpeg", sha256 } } })).toThrow("a path source downloads nothing");
+    expect(parse({ ffmpeg: { "linux-x64": { url: "https://x.test/ffmpeg.zip", sha256 } } })).toThrow(
+      "names an archive: file picks the executable inside it",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { path: "ffmpeg", file: "bin/ffmpeg" } } })).toThrow(
+      "file picks the executable out of an archive",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { path: "ffmpeg.tar.gz", file: "../ffmpeg" } } })).toThrow(
+      "file must be a path inside the archive",
+    );
+    expect(parse({ ffmpeg: { "linux-x64": { path: "ffmpeg", mode: 755 } } })).toThrow("unknown key mode");
+  });
+});