@akanjs/devkit 2.4.1-rc.7 → 2.4.2-rc.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # @akanjs/devkit
 
+## 2.4.1
+
+### Patch Changes
+
+- Updated dependencies [473be34]
+- Updated dependencies [f5bfa27]
+- Updated dependencies [473be34]
+- Updated dependencies [068158b]
+- Updated dependencies [46a1a4a]
+- Updated dependencies [90c6597]
+- Updated dependencies [aca901d]
+- Updated dependencies [068158b]
+- Updated dependencies [cb895b7]
+- Updated dependencies [f8a9bc5]
+- Updated dependencies [d973712]
+- Updated dependencies [068158b]
+- Updated dependencies [cc3dd40]
+- Updated dependencies [8a2b795]
+- Updated dependencies [068158b]
+- Updated dependencies [473be34]
+- Updated dependencies [e5fde3b]
+- Updated dependencies [473be34]
+- Updated dependencies [f28466f]
+- Updated dependencies [51851fa]
+- Updated dependencies [1c3436f]
+- Updated dependencies [128e9a3]
+- Updated dependencies [a5d4a8a]
+- Updated dependencies [473be34]
+  - akanjs@2.4.1
+
 ## 2.4.0
 
 ### Minor Changes

package/DEV_RUNTIME_KNOBS.md

@@ -0,0 +1,97 @@
+# Dev runtime knobs
+
+Every environment variable that changes how much memory a dev server is allowed to use, and how it
+gives that memory back. Written for whoever sizes a sandbox: the defaults are tuned for a laptop, and a
+container smaller than one needs to know which numbers move.
+
+Nothing here is a secret — these are sizing knobs, set alongside the rest of a deployment's env.
+
+## The budget
+
+| variable | default | what it does |
+|---|---|---|
+| `AKAN_MEMORY_LIMIT` | the container's cgroup `memory.max`, if any | The total the dev server may use. Accepts a plain byte count or a suffix — `1200mb`, `2gib`. Every ceiling below is a fraction of this. |
+
+With neither an explicit value nor a cgroup limit, each process falls back to its own dev default, which
+assumes a developer laptop rather than a sandbox.
+
+## Per-process ceilings
+
+Each ceiling can be set outright, and otherwise takes a share of `AKAN_MEMORY_LIMIT`. A process that
+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) |
+| 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
+boot build simply does not fit under the derived share.
+
+### The shares do not add up to a budget, and that is worth knowing
+
+0.35 + 0.55 = **0.90 of the declared limit**, and only two processes are in that sum. A dev server also
+runs a dev host, a gateway, one or more backend replicas, and — during a build — a disposable build
+worker whose peak is the largest transient in the tree (measured: ~548MB on a mid-size app, ~1.1GB on
+this repo's own `apps/akan`). None of those has a ceiling, and none is subtracted from the two above.
+
+In practice this holds because the two ceilings are rarely at their limit simultaneously and the build
+worker exits. But if you are sizing a container to a hard number, size it against the *sum of observed
+peaks*, not against these fractions. Measured floors, for reference: builder 134-202MB at rest and
+~490MB after a route build, RSC worker ~142MB after boot, ~247MB per route build.
+
+## Recycling behaviour
+
+| variable | default | what it does |
+|---|---|---|
+| `AKAN_DEV_IDLE_SUSPEND_MS` | `300000` (5 min) | How long a dev server may sit unused before its builder is released entirely. The next edit or route request brings it back, at the cost of one boot build. `0` keeps the builder resident for the whole session. |
+| `AKAN_RSC_WORKER_MAX_RELOADS` | `10` in dev, off in production | Reloads tolerated before the worker is recycled instead of reloaded in place. Bun's ESM registry never evicts, so each in-place reload of the pages bundle is retained. |
+| `AKAN_RSC_WORKER_MIN_RECYCLE_INTERVAL_MS` | `1000` | Floor between worker recycles, so a burst of saves produces one. |
+| `AKAN_RSC_WORKER_RECYCLE_GRACE_MS` | `5000` | How long a recycled worker may take to finish what it is holding. |
+| `AKAN_RSC_WORKER_MAX_RENDER_COUNT` | unset | Recycle after this many renders. Off by default; a blunt instrument for chasing a leak. |
+| `AKAN_RSC_WORKER_MAX_ROUTE_MODULES` | unset | Recycle once this many route modules are loaded. Same. |
+
+The builder's own recycle timing is not configurable and is stated here because it is what a tight
+ceiling costs: it waits **750ms** of quiet so a recycle never lands mid-burst, then re-reads the
+process's RSS after **20s** (unless it is already 1.5× over) to see whether the allocator gave the
+memory back on its own, and never recycles twice inside **30s**. Requests that arrive while the builder
+is away are held — up to **64** of them — and replayed when it is back, rather than failed.
+
+If the builder crosses the ceiling again within that 30s window, the dev host says so once and keeps
+enforcing the ceiling. It stops enforcing only when a *freshly replaced* builder is already over it,
+which is the one case where replacing it again cannot help; it says that too, and names this knob.
+
+## Build behaviour
+
+| 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_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. |
+
+## Observability
+
+| variable | default | what it does |
+|---|---|---|
+| `AKAN_MEMORY_LOG` | off | `=1` logs a periodic memory report from each server role. |
+| `AKAN_MEMORY_LOG_INTERVAL_MS` | `60000` | How often that report is written. |
+| `AKAN_MEMORY_GC_ON_REPORT` | off | `=1` forces a GC before each report, so the number is retained memory rather than garbage. Costs a full GC per report. |
+
+## Sizing a small sandbox
+
+A worked example, for a 1.2GB container:
+
+```bash
+AKAN_MEMORY_LIMIT=1200mb          # builder gets ~420MB, rsc worker ~660MB
+AKAN_DEV_IDLE_SUSPEND_MS=300000   # release the builder after 5 idle minutes
+```
+
+Two things to expect at that size. The builder crosses 420MB during ordinary work — one route build
+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.
+
+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
+instead.

package/README.md

@@ -45,6 +45,12 @@ await runner.build();
 - AI prompt, guideline, and code-generation support utilities.
 - Capacitor and mobile release helpers.
 
+## Dev Server Sizing
+
+The dev server bounds its own memory by recycling the processes that grow, and every threshold it uses
+can be set from the environment. [`DEV_RUNTIME_KNOBS.md`](./DEV_RUNTIME_KNOBS.md) lists them with their
+defaults, the shares they derive from `AKAN_MEMORY_LIMIT`, and what a small container should expect.
+
 ## Package Boundary
 
 - Runtime code should import from `akanjs`, including shared config types such as `AppConfig`, `LibConfig`,

package/akanApp/akanApp.host.test.ts

@@ -14,15 +14,17 @@ import {
   decideBuilderRssRecycle,
   decideBuilderRssSettle,
   decideIdleSuspend,
+  filesChangedSince,
   hasAnyBuildFailure,
   hasBuildFailureForGeneration,
   isLegacyBackendFallbackFile,
+  isRssCeilingUnreachable,
   mergeBackendRestartReasons,
   mergeInvalidateMessages,
   normalizeBackendReportedGeneration,
   resolveIdleSuspendMs,
   shouldAbandonBackendRecovery,
-  shouldAbandonBuilderRssCeiling,
+  shouldHoldForReturningBuilder,
   shouldMarkBuildPhaseRecovered,
   shouldQueueBuildStatusReplay,
   shouldRefreshConfigOnIdleWake,
@@ -31,6 +33,7 @@ import {
   shouldRestartBackendByDevPlan,
   shouldRestartBuilderByDevPlan,
   shouldRestartDevHostByDevPlan,
+  shouldWarnBuilderRssCeilingTight,
 } from "./akanApp.host";
 
 const invalidateWithActions = (actions: DevChangeAction[]): Extract<BuilderMessage, { type: "invalidate" }> => ({
@@ -156,6 +159,28 @@ describe("last-good frontend helpers", () => {
   });
 });
 
+describe("holding requests for a returning builder", () => {
+  test("holds while the builder is on its way back", () => {
+    expect(shouldHoldForReturningBuilder({ status: "restarting", heldCount: 0 })).toBe(true);
+    expect(shouldHoldForReturningBuilder({ status: "starting", heldCount: 3 })).toBe(true);
+  });
+
+  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);
+  });
+
+  test("fails immediately when nothing is bringing the builder back", () => {
+    expect(shouldHoldForReturningBuilder({ status: "stopped", heldCount: 0 })).toBe(false);
+  });
+
+  test("stops holding once the queue is full", () => {
+    expect(shouldHoldForReturningBuilder({ status: "restarting", heldCount: 3, limit: 4 })).toBe(true);
+    expect(shouldHoldForReturningBuilder({ status: "restarting", heldCount: 4, limit: 4 })).toBe(false);
+  });
+});
+
 describe("builder rss recycle", () => {
   const ceiling = 1_200 * 1024 * 1024;
   const decide = (over: Partial<Parameters<typeof decideBuilderRssRecycle>[0]>) =>
@@ -191,11 +216,23 @@ describe("builder rss recycle", () => {
     expect(decide({ msSinceLastRecycle: 5_000, minIntervalMs: 1_000 })).toBe("recycle");
   });
 
-  // An app whose fresh boot is already over the ceiling would otherwise be recycled forever.
-  test("abandons the ceiling once recycling stops buying relief", () => {
-    expect(shouldAbandonBuilderRssCeiling(1)).toBe(false);
-    expect(shouldAbandonBuilderRssCeiling(2)).toBe(true);
-    expect(shouldAbandonBuilderRssCeiling(1, 1)).toBe(true);
+  // 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
@@ -465,6 +502,38 @@ describe("BackendImportGraph", () => {
     expect(graph.has(path.join(cwdPath, "lib/leaving.ts"))).toBe(false);
   });
 
+  test("reports which backend files moved while nobody was watching", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": 'import "./lib/handler";\nexport default 1;\n',
+      "lib/handler.ts": "export const handler = () => null;\n",
+    });
+    await graph.refresh();
+    const before = await graph.fingerprint();
+
+    // The builder is gone here, so no watcher event exists for this save — which is the whole reason
+    // the stamps are taken. `mtimeMs` has a coarse clock on Linux, so the size has to move too.
+    await writeFile(path.join(cwdPath, "lib/handler.ts"), "export const handler = () => 'changed';\n");
+
+    expect(filesChangedSince(before, await graph.fingerprint())).toEqual([path.join(cwdPath, "lib/handler.ts")]);
+  });
+
+  test("says nothing when the tree is untouched, and names a deleted file", async () => {
+    const { graph, cwdPath } = await makeGraph({
+      "main.ts": 'import "./server";\n',
+      "server.ts": 'import "./lib/handler";\nexport default 1;\n',
+      "lib/handler.ts": "export const handler = () => null;\n",
+    });
+    await graph.refresh();
+    const before = await graph.fingerprint();
+    // A recycle with no edit in it is the common case, and it must not cost a backend restart.
+    expect(filesChangedSince(before, await graph.fingerprint())).toEqual([]);
+
+    await rm(path.join(cwdPath, "lib/handler.ts"));
+    // Deleted counts as changed: the backend is still running what used to be there.
+    expect(filesChangedSince(before, await graph.fingerprint())).toEqual([path.join(cwdPath, "lib/handler.ts")]);
+  });
+
   test("keeps the previous graph when a refresh finds no entrypoints", async () => {
     const { graph, cwdPath } = await makeGraph({
       "main.ts": 'import "./lib/kept";\n',