@akanjs/devkit 3.0.0-alpha.0 → 3.0.0-alpha.2

package/integration/devResourceProbe.ts

@@ -285,9 +285,14 @@ export class DevResourceProbe {
       "rscWorkerRecycleCount",
       "httpFullSsrCount",
     ];
-    const rssMb = (Number(child.rssBytes ?? 0) / 1024 / 1024).toFixed(0);
+    // `rssBytes` is the replica's own; the RSC worker is a separate process reporting under
+    // `rscWorker*`. These used to be the same field, because the worker's report shadowed the
+    // replica's — so this line printed the worker's RSS labelled as the child's.
+    const toMb = (bytes: unknown) => (Number(bytes ?? 0) / 1024 / 1024).toFixed(0);
     const parts = keys.map((key) => `${key}=${child[key] ?? "?"}`);
-    console.info(`[metrics ${label}] rsc rss=${rssMb}MB ${parts.join(" ")}`);
+    console.info(
+      `[metrics ${label}] replicaRss=${toMb(child.rssBytes)}MB rscWorkerRss=${toMb(child.rscWorkerRssBytes)}MB ${parts.join(" ")}`,
+    );
   }
 
   async #waitForLog(pattern: RegExp, timeoutMs: number): Promise<boolean> {

package/integration/ssrMemoryProbe.ts

@@ -0,0 +1,542 @@
+import fs from "node:fs";
+import os from "node:os";
+import path from "node:path";
+
+export type SsrProcRole = "gateway" | "replica" | "rsc" | "other";
+
+export interface SsrProc {
+  pid: number;
+  ppid: number;
+  rssMb: number;
+  cpuSec: number;
+  role: SsrProcRole;
+  command: string;
+}
+
+export interface SsrCgroupSample {
+  currentMb: number;
+  anonMb: number;
+  fileMb: number;
+}
+
+export interface SsrCacheSample {
+  replicaRssMb: number;
+  rscWorkerRssMb: number;
+  htmlEntries: number;
+  htmlBytes: number;
+  rscEntries: number;
+  rscBytes: number;
+  patchEntries: number;
+  patchBytes: number;
+  ssrChunkKeys: number;
+  loadedRouteModules: number;
+  fullSsr: number;
+  rscNavigation: number;
+  heap: SsrHeapSample;
+}
+
+/**
+ * RSS minus JS heap is what a module graph costs beyond its objects — compiled code, module
+ * records, native allocator retention — so the split is what separates "the app retains objects"
+ * from "the runtime retains code". `jscExtra` is JSC's off-heap attribution, which is where
+ * typed-array backing stores (cached Flight chunks) land.
+ */
+export interface SsrHeapSample {
+  replicaHeapUsedMb: number;
+  replicaJscHeapMb: number;
+  replicaJscExtraMb: number;
+  workerHeapUsedMb: number;
+  workerJscHeapMb: number;
+  workerJscExtraMb: number;
+}
+
+export interface SsrMemoryProbeOptions {
+  appName: string;
+  /** Built app directory — `dist/apps/<app>` unless the build was relocated. */
+  distDir: string;
+  port: number;
+  basePaths: string;
+  repoName: string;
+  serveDomain: string;
+  scenarios: number[];
+  /** Repeat count for scenario 1 (same route) and per-route passes in scenario 6. */
+  repeats: number;
+  concurrencies: number[];
+  idleSeconds: number;
+  /** Report cadence forced on the children; also bounds how long a sample waits for a fresh one. */
+  metricsIntervalMs: number;
+  /** Disables both result caches at boot — the second half of scenario 3. */
+  cacheOff: boolean;
+  /**
+   * Forces `Bun.gc(true)` before every metrics sample. Required for the s7 ratchet test: without
+   * it, growth across passes cannot be told apart from garbage that has not been collected yet.
+   */
+  gcOnReport: boolean;
+  /** s7: how many times to walk the whole route list. */
+  passes: number;
+  /** s8: cumulative distinct-route counts to sample the per-route slope at. */
+  sweep: number[];
+  logPath: string;
+}
+
+/**
+ * Production process-tree RSS and cache occupancy — probe §0.3 of
+ * `local/reduce-ssr-ram/01-measurement-harness.md`, and the source of the phase 0 results table.
+ *
+ *   bun pkgs/@akanjs/devkit/integration/ssrMemoryProbe.ts <app> [--scenarios=1,2,5] [--cache=off]
+ *
+ * The production tree is gateway → replica × N → rsc worker × N, with no builder; `DevResourceProbe`
+ * measures the dev tree instead and the two are not interchangeable.
+ *
+ * Two things this exists to get right:
+ *
+ * - **Replica and worker RSS are reported separately.** They are separate processes and the worker
+ *   holds a private copy of the pages bundle, so one summed number hides which of the two grows.
+ * - **On Linux it samples the cgroup's `anon` / `file` split, not just RSS.** Whether a cache is
+ *   anonymous heap (an OOM contributor) or page cache (evictable) is the entire question phase 2
+ *   asks; RSS cannot answer it, and neither can macOS, where the file half does not exist in the
+ *   same form. Read a macOS run as directional only.
+ */
+export class SsrMemoryProbe {
+  static readonly #columns: SsrProcRole[] = ["gateway", "replica", "rsc"];
+
+  static parseArgs(argv: string[]): SsrMemoryProbeOptions {
+    const args = new Map(
+      argv.slice(1).map((arg) => {
+        const [key, value] = arg.replace(/^--/, "").split("=");
+        return [key ?? "", value ?? "1"];
+      }),
+    );
+    const appName = argv[0] ?? "akan";
+    const num = (key: string, fallback: number) => Number(args.get(key) ?? fallback);
+    const list = (key: string, fallback: number[]) =>
+      args.has(key)
+        ? (args.get(key) ?? "")
+            .split(",")
+            .map(Number)
+            .filter((value) => Number.isFinite(value) && value > 0)
+        : fallback;
+    return {
+      appName,
+      distDir: args.get("dist") ?? path.join(process.cwd(), "dist", "apps", appName),
+      port: num("port", 8482),
+      basePaths: args.get("basePaths") ?? "",
+      repoName: args.get("repo") ?? path.basename(process.cwd()),
+      serveDomain: args.get("domain") ?? "localhost",
+      scenarios: list("scenarios", [1, 2, 5, 6]),
+      repeats: num("repeats", 200),
+      concurrencies: list("concurrency", [1, 8, 32]),
+      idleSeconds: num("idle", 300),
+      metricsIntervalMs: num("metricsInterval", 10_000),
+      cacheOff: args.get("cache") === "off",
+      gcOnReport: args.has("gc"),
+      passes: num("passes", 3),
+      sweep: list("sweep", [1, 10, 50, 169]),
+      logPath: args.get("log") ?? path.join(os.tmpdir(), `akan-ssr-memory-${appName}.log`),
+    };
+  }
+
+  readonly #options: SsrMemoryProbeOptions;
+  #gatewayPid = 0;
+
+  constructor(options: SsrMemoryProbeOptions) {
+    this.#options = options;
+  }
+
+  async run(): Promise<void> {
+    const { appName, distDir, port, basePaths, repoName, serveDomain, logPath, cacheOff } = this.#options;
+    if (!fs.existsSync(path.join(distDir, "main.js")))
+      throw new Error(`no built app at ${distDir} — run \`akan build ${appName}\` first`);
+    await Bun.write(logPath, "");
+    const gateway = Bun.spawn(["bun", "main.js"], {
+      cwd: distDir,
+      env: {
+        ...process.env,
+        NODE_ENV: "production",
+        USE_AKANJS_PKGS: "true",
+        AKAN_PUBLIC_APP_NAME: appName,
+        // `getEnv()` requires these one at a time, and a missing one fails the *replica* while the
+        // gateway stays up: the process tree still looks like a healthy three, and only the child's
+        // `ready` flag and the 503s give it away. Both are why `#waitForReady` checks child
+        // readiness rather than the gateway's own 200.
+        AKAN_PUBLIC_REPO_NAME: process.env.AKAN_PUBLIC_REPO_NAME ?? repoName,
+        AKAN_PUBLIC_SERVE_DOMAIN: process.env.AKAN_PUBLIC_SERVE_DOMAIN ?? serveDomain,
+        AKAN_PUBLIC_ENV: "local",
+        AKAN_PUBLIC_OPERATION_MODE: "local",
+        SERVER_MODE: "federation",
+        ...(basePaths ? { AKAN_PUBLIC_BASE_PATHS: basePaths } : {}),
+        PORT: String(port),
+        AKAN_MEMORY_LOG: "1",
+        AKAN_MEMORY_LOG_INTERVAL_MS: String(this.#options.metricsIntervalMs),
+        ...(cacheOff ? { AKAN_HTML_RESULT_CACHE: "0", AKAN_RSC_RESULT_CACHE: "0" } : {}),
+        ...(this.#options.gcOnReport ? { AKAN_MEMORY_GC_ON_REPORT: "1" } : {}),
+      },
+      stdout: Bun.file(logPath),
+      stderr: Bun.file(logPath),
+    });
+    this.#gatewayPid = gateway.pid;
+    console.info(
+      `[probe] app=${appName} pid=${gateway.pid} port=${port} cache=${cacheOff ? "off" : "on"} log=${logPath}`,
+    );
+    try {
+      await this.#measure();
+    } finally {
+      await this.#cleanup(gateway);
+    }
+  }
+
+  async #measure(): Promise<void> {
+    const { scenarios, repeats, concurrencies, idleSeconds } = this.#options;
+    if (!(await this.#waitForReady(180_000)))
+      throw new Error(`no replica became ready within 180s — see ${this.#options.logPath}`);
+    // Route modules are evaluated on first request, so nothing before this line is a floor.
+    await Bun.sleep(5_000);
+
+    console.info(`\n${"sample".padEnd(24)} ${["gway", "repl", "rsc"].map((h) => h.padStart(6)).join(" ")}`);
+    await this.#sample("boot");
+
+    const routes = await this.#staticRoutes();
+    console.info(`[probe] ${routes.length} static route(s) resolved`);
+
+    if (scenarios.includes(1)) {
+      const route = routes[0] ?? "/";
+      await this.#run(
+        `s1 same-route x${repeats}`,
+        Array.from({ length: repeats }, () => route),
+        1,
+      );
+    }
+
+    if (scenarios.includes(2)) await this.#run("s2 every-route x1", routes, 1);
+
+    if (scenarios.includes(4)) {
+      await this.#run(
+        "s4 rsc-only",
+        routes.map((route) => `/__rsc?url=${encodeURIComponent(route)}`),
+        1,
+      );
+    }
+
+    if (scenarios.includes(6)) {
+      for (const concurrency of concurrencies) await this.#run(`s6 concurrency=${concurrency}`, routes, concurrency);
+    }
+
+    // s7 — ratchet vs working set. Every pass renders the same routes, so pass 1 pays for module
+    // evaluation and later passes pay for nothing new. Flat later passes mean the memory is a
+    // working set and only a smaller bundle or fewer replicas reduces it; continued growth means
+    // per-render retention, which is a bug worth more than any ceiling. Run with `--cache=off --gc`
+    // or it measures cache hits and uncollected garbage instead.
+    if (scenarios.includes(7)) {
+      if (!this.#options.cacheOff)
+        console.info("[probe] WARNING s7 without --cache=off measures cache hits from pass 2 on");
+      if (!this.#options.gcOnReport)
+        console.info("[probe] WARNING s7 without --gc cannot separate retention from uncollected garbage");
+      for (let pass = 1; pass <= this.#options.passes; pass += 1)
+        await this.#run(`s7 pass ${pass}/${this.#options.passes}`, routes, 1);
+    }
+
+    // s8 — per-route slope vs fixed intercept. Cumulative: each step adds routes the process has
+    // not seen, so the RSS series against distinct-route count separates the two.
+    if (scenarios.includes(8)) {
+      for (const count of this.#options.sweep) {
+        const subset = routes.slice(0, Math.min(count, routes.length));
+        if (subset.length === 0) continue;
+        await this.#run(`s8 routes<=${subset.length}`, subset, 1);
+      }
+    }
+
+    if (scenarios.includes(5)) {
+      const started = Date.now();
+      while ((Date.now() - started) / 1_000 < idleSeconds) {
+        await Bun.sleep(30_000);
+        await this.#sample(`s5 idle+${Math.round((Date.now() - started) / 1_000)}s`);
+      }
+      console.info("[probe] idle reclamation is the delta from the last pre-idle row; expect none today");
+    }
+  }
+
+  /**
+   * A scenario is only a measurement if its requests succeeded. A gateway whose replica died still
+   * answers — with 503s, instantly — and the resulting RSS row looks like a legitimately cheap one.
+   * Fail loudly rather than publish that number.
+   */
+  async #run(label: string, urls: string[], concurrency: number): Promise<void> {
+    const started = Date.now();
+    const { ok, failed, statuses } = await this.#browse(urls, concurrency);
+    const elapsed = ((Date.now() - started) / 1_000).toFixed(1);
+    const breakdown = [...statuses.entries()].map(([status, count]) => `${status}×${count}`).join(" ");
+    console.info(`[probe] ${label}: ok=${ok} failed=${failed} in ${elapsed}s (${breakdown})`);
+    if (ok === 0) throw new Error(`${label}: every request failed (${breakdown}) — the sample would be meaningless`);
+    if (failed > 0) console.info(`[probe] WARNING ${label} has ${failed} failed request(s); the row below is partial`);
+    await this.#sample(label, Date.now());
+  }
+
+  async #sample(label: string, since = Date.now()): Promise<void> {
+    const procs = await this.#sampleTree();
+    const byRole = new Map<SsrProcRole, number>();
+    for (const proc of procs) byRole.set(proc.role, (byRole.get(proc.role) ?? 0) + proc.rssMb);
+    const total = procs.reduce((sum, proc) => sum + proc.rssMb, 0);
+    const mb = (value: number) => value.toFixed(0).padStart(6);
+    const cells = SsrMemoryProbe.#columns.map((role) => (byRole.has(role) ? mb(byRole.get(role) ?? 0) : "     —"));
+    const cgroup = SsrMemoryProbe.readCgroupSample();
+    console.info(
+      `${label.padEnd(24)} ${cells.join(" ")} | total ${mb(total)}MB n=${procs.length}` +
+        (cgroup
+          ? ` | cgroup ${cgroup.currentMb.toFixed(0)}MB anon=${cgroup.anonMb.toFixed(0)} file=${cgroup.fileMb.toFixed(0)}`
+          : ""),
+    );
+    const cache = await this.#sampleCaches(since);
+    if (!cache) return;
+    console.info(
+      `${"".padEnd(24)} caches: html=${cache.htmlEntries}/${SsrMemoryProbe.#mib(cache.htmlBytes)} ` +
+        `rsc=${cache.rscEntries}/${SsrMemoryProbe.#mib(cache.rscBytes)} ` +
+        `patch=${cache.patchEntries}/${SsrMemoryProbe.#mib(cache.patchBytes)} ` +
+        `ssrChunkKeys=${cache.ssrChunkKeys} routeModules=${cache.loadedRouteModules} ` +
+        `req=${cache.fullSsr}ssr/${cache.rscNavigation}rsc`,
+    );
+    const { heap } = cache;
+    const n = (value: number) => value.toFixed(0);
+    console.info(
+      `${"".padEnd(24)} heap:   repl heapUsed=${n(heap.replicaHeapUsedMb)} jsc=${n(heap.replicaJscHeapMb)} ` +
+        `jscExtra=${n(heap.replicaJscExtraMb)} | rsc heapUsed=${n(heap.workerHeapUsedMb)} ` +
+        `jsc=${n(heap.workerJscHeapMb)} jscExtra=${n(heap.workerJscExtraMb)} (MB)`,
+    );
+  }
+
+  static #mib(bytes: number): string {
+    return `${(bytes / 1024 / 1024).toFixed(1)}MiB`;
+  }
+
+  /**
+   * Reads the container's own accounting. `memory.current` counts page cache, so a disk-backed
+   * cache still shows up here — but under `file`, which the kernel reclaims under pressure instead
+   * of OOM-killing. That split is what phase 2 has to move. Returns null off cgroup v2.
+   */
+  static readCgroupSample(): SsrCgroupSample | null {
+    try {
+      const current = Number.parseInt(fs.readFileSync("/sys/fs/cgroup/memory.current", "utf8").trim(), 10);
+      if (!Number.isFinite(current)) return null;
+      const stat = fs.readFileSync("/sys/fs/cgroup/memory.stat", "utf8");
+      const field = (name: string) => {
+        const parsed = Number.parseInt(new RegExp(`^${name} (\\d+)$`, "m").exec(stat)?.[1] ?? "", 10);
+        return Number.isFinite(parsed) ? parsed : 0;
+      };
+      const toMb = (bytes: number) => bytes / 1024 / 1024;
+      return { currentMb: toMb(current), anonMb: toMb(field("anon")), fileMb: toMb(field("file")) };
+    } catch {
+      return null;
+    }
+  }
+
+  /**
+   * Waits for a metrics report sampled *after* `since` before reading the cache columns.
+   *
+   * The counters ride a periodic IPC report, so reading immediately after a browse returns the
+   * state from before it — and the two-hop path (worker → replica → gateway) means the `rsc*` and
+   * `rscWorker*` fields can be a further interval behind. Without this wait every row silently
+   * attributes one scenario's cache growth to the previous scenario.
+   */
+  async #sampleCaches(since: number): Promise<SsrCacheSample | null> {
+    const deadline = Date.now() + this.#options.metricsIntervalMs * 3 + 5_000;
+    let children: Array<Record<string, number>> = [];
+    let fresh = false;
+    while (Date.now() < deadline) {
+      children = await this.#fetchChildMetrics();
+      // Both hops must have re-reported: `reportedAt` is the replica's own sample time, and
+      // `rscWorkerReportedAt` the worker's as of the replica's last read of it.
+      fresh =
+        children.length > 0 &&
+        children.every(
+          (metrics) => Number(metrics.reportedAt ?? 0) >= since && Number(metrics.rscWorkerReportedAt ?? 0) >= since,
+        );
+      if (fresh) break;
+      await Bun.sleep(500);
+    }
+    if (children.length === 0) return null;
+    if (!fresh) console.info(`${"".padEnd(24)} WARNING cache columns are stale — no fresh report within the wait`);
+    {
+      const sum = (key: string) => children.reduce((total, metrics) => total + Number(metrics[key] ?? 0), 0);
+      const mb = (key: string) => sum(key) / 1024 / 1024;
+      return {
+        replicaRssMb: sum("rssBytes") / 1024 / 1024,
+        rscWorkerRssMb: sum("rscWorkerRssBytes") / 1024 / 1024,
+        htmlEntries: sum("httpHtmlCacheEntries"),
+        htmlBytes: sum("httpHtmlCacheBytes"),
+        rscEntries: sum("rscResultCacheEntries"),
+        rscBytes: sum("rscResultCacheBytes"),
+        patchEntries: sum("rscPatchResultCacheEntries"),
+        patchBytes: sum("rscPatchResultCacheBytes"),
+        ssrChunkKeys: sum("ssrChunkRegistrySize"),
+        loadedRouteModules: sum("rscLoadedRouteModuleCount"),
+        fullSsr: sum("httpFullSsrCount"),
+        rscNavigation: sum("httpRscNavigationCount"),
+        heap: {
+          replicaHeapUsedMb: mb("heapUsedBytes"),
+          replicaJscHeapMb: mb("jscHeapSizeBytes"),
+          replicaJscExtraMb: mb("jscExtraMemorySizeBytes"),
+          workerHeapUsedMb: mb("rscWorkerHeapUsedBytes"),
+          workerJscHeapMb: mb("rscWorkerJscHeapSizeBytes"),
+          workerJscExtraMb: mb("rscWorkerJscExtraMemorySizeBytes"),
+        },
+      };
+    }
+  }
+
+  async #fetchChildMetrics(): Promise<Array<Record<string, number>>> {
+    try {
+      const res = await fetch(`http://localhost:${this.#options.port}/_akan/app/metrics`, {
+        signal: AbortSignal.timeout(5_000),
+      });
+      if (!res.ok) return [];
+      const body = (await res.json()) as { children?: Array<{ metrics?: Record<string, number> }> };
+      return (body.children ?? []).map((child) => child.metrics ?? {});
+    } catch {
+      return [];
+    }
+  }
+
+  #roleOf(command: string): SsrProcRole {
+    if (/rscWorker\.js|react-server/.test(command)) return "rsc";
+    if (/\bmain\.js\b/.test(command)) return "gateway";
+    if (/server\.js|bun -e|import\(/.test(command)) return "replica";
+    return "other";
+  }
+
+  /** One `ps`, then walk from the gateway pid to a fixpoint. */
+  async #sampleTree(): Promise<SsrProc[]> {
+    const proc = Bun.spawn(["ps", "-eo", "pid=,ppid=,rss=,time=,command="], { stdout: "pipe" });
+    const text = await new Response(proc.stdout).text();
+    await proc.exited;
+    const all = text
+      .split("\n")
+      .map((line) => line.trim())
+      .filter(Boolean)
+      .map((line) => {
+        const match = /^(\d+)\s+(\d+)\s+(\d+)\s+([\d:.]+)\s+(.*)$/.exec(line);
+        if (!match) return null;
+        const [, pid, ppid, rss, time, command] = match;
+        const parts = (time ?? "0:0").split(":");
+        const cpuSec =
+          parts.length === 3
+            ? Number(parts[0]) * 3600 + Number(parts[1]) * 60 + Number(parts[2])
+            : Number(parts[0] ?? 0) * 60 + Number(parts[1] ?? 0);
+        return {
+          pid: Number(pid),
+          ppid: Number(ppid),
+          rssMb: Number(rss) / 1024,
+          cpuSec,
+          role: this.#roleOf(command ?? ""),
+          command: command ?? "",
+        } satisfies SsrProc;
+      })
+      .filter((proc): proc is SsrProc => proc !== null);
+    const kept = new Map<number, SsrProc>();
+    const root = all.find((proc) => proc.pid === this.#gatewayPid);
+    if (root) kept.set(this.#gatewayPid, root);
+    for (let pass = 0; pass < 12; pass++) {
+      const before = kept.size;
+      for (const proc of all) if (kept.has(proc.ppid) && !kept.has(proc.pid)) kept.set(proc.pid, proc);
+      if (kept.size === before) break;
+    }
+    return [...kept.values()].filter((proc) => proc.role !== "other" || proc.pid === this.#gatewayPid);
+  }
+
+  /**
+   * Concrete urls from the built route seed index. `:lang` takes the default locale; any route with
+   * another `:param` is skipped because it needs a real id to render.
+   */
+  async #staticRoutes(): Promise<string[]> {
+    const artifactDir = path.join(this.#options.distDir, ".akan", "artifact");
+    const seed = (await Bun.file(path.join(artifactDir, "route-seed-index.json")).json()) as {
+      entries: Array<{ routeId: string }>;
+    };
+    const artifact = (await Bun.file(path.join(artifactDir, "base-artifact.json")).json()) as {
+      i18n?: { defaultLocale?: string };
+    };
+    const locale = artifact.i18n?.defaultLocale ?? "en";
+    const urls = new Set<string>();
+    for (const entry of seed.entries) {
+      const url = entry.routeId.replace(/:lang\b/g, locale);
+      if (/[:[]/.test(url)) continue;
+      urls.add(url.startsWith("/") ? url : `/${url}`);
+    }
+    return [...urls].sort();
+  }
+
+  async #browse(
+    urls: string[],
+    concurrency: number,
+  ): Promise<{ ok: number; failed: number; statuses: Map<string, number> }> {
+    let ok = 0;
+    let failed = 0;
+    let cursor = 0;
+    const statuses = new Map<string, number>();
+    const record = (key: string) => statuses.set(key, (statuses.get(key) ?? 0) + 1);
+    const worker = async () => {
+      while (cursor < urls.length) {
+        const url = urls[cursor++];
+        if (url === undefined) return;
+        try {
+          const res = await fetch(`http://localhost:${this.#options.port}${url}`, {
+            signal: AbortSignal.timeout(60_000),
+          });
+          // Drain the body: SSR streams, so a response is not rendered until it is read.
+          await res.arrayBuffer();
+          record(String(res.status));
+          if (res.ok) ok++;
+          else failed++;
+        } catch (error) {
+          record(error instanceof Error ? error.name : "error");
+          failed++;
+        }
+      }
+    };
+    await Promise.all(Array.from({ length: Math.max(1, concurrency) }, worker));
+    return { ok, failed, statuses };
+  }
+
+  /**
+   * Waits for a **child** to report ready, not for the gateway to answer. The gateway binds and
+   * serves `/health` happily while every replica is in a crash-restart loop, so a 200 here proves
+   * nothing about whether anything can render.
+   */
+  async #waitForReady(timeoutMs: number): Promise<boolean> {
+    const deadline = Date.now() + timeoutMs;
+    let lastError = "";
+    while (Date.now() < deadline) {
+      try {
+        const res = await fetch(`http://localhost:${this.#options.port}/_akan/app/health`, {
+          signal: AbortSignal.timeout(2_000),
+        });
+        if (res.ok) {
+          const body = (await res.json()) as {
+            children?: Array<{ ready?: boolean; role?: string; lastErrorMessage?: string }>;
+          };
+          const children = body.children ?? [];
+          if (children.some((child) => child.ready && child.role !== "batch")) return true;
+          lastError = children.find((child) => child.lastErrorMessage)?.lastErrorMessage ?? lastError;
+        }
+      } catch {
+        // The gateway binds before the replicas are up; keep polling until one answers.
+      }
+      await Bun.sleep(1_000);
+    }
+    if (lastError) console.info(`[probe] no child became ready; last child error: ${lastError}`);
+    return false;
+  }
+
+  async #cleanup(gateway: { kill: (signal: NodeJS.Signals) => void }): Promise<void> {
+    for (const proc of (await this.#sampleTree()).reverse()) {
+      try {
+        process.kill(proc.pid, "SIGKILL");
+      } catch {}
+    }
+    try {
+      gateway.kill("SIGKILL");
+    } catch {}
+    await Bun.sleep(1_000);
+    console.info(`[probe] survivors after kill: ${(await this.#sampleTree()).length}`);
+  }
+}
+
+if (import.meta.main) await new SsrMemoryProbe(SsrMemoryProbe.parseArgs(process.argv.slice(2))).run();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@akanjs/devkit",
-  "version": "3.0.0-alpha.0",
+  "version": "3.0.0-alpha.2",
   "sourceType": "module",
   "type": "module",
   "publishConfig": {
@@ -44,7 +44,7 @@
     "@langchain/openai": "^1.4.6",
     "@tailwindcss/node": "^4.3.0",
     "@trapezedev/project": "^7.1.4",
-    "akanjs": "3.0.0-alpha.0",
+    "akanjs": "3.0.0-alpha.2",
     "chalk": "^5.6.2",
     "commander": "^14.0.3",
     "dayjs": "^1.11.20",

package/qualityScanner.test.ts

@@ -3,7 +3,7 @@ import { mkdir, mkdtemp, rm, writeFile } from "node:fs/promises";
 import os from "node:os";
 import path from "node:path";
 import { AbstractDoc } from "./abstractDoc";
-import { AkanQualityScanner } from "./qualityScanner";
+import { AkanQualityScanner, type QualityScanResult } from "./qualityScanner";
 
 const tempRoots: string[] = [];
 
@@ -44,3 +44,142 @@ describe("AkanQualityScanner abstract rule", () => {
     expect(warnings[0]?.fix).toContain("akan compact");
   });
 });
+
+const staticMarkup = (elementNum: number) =>
+  Array.from({ length: elementNum }, (_, idx) => `      <p className="text-sm">row ${idx}</p>`).join("\n");
+
+const rulesOf = (result: QualityScanResult, rule: string) => result.warnings.filter((warning) => warning.rule === rule);
+
+describe("AkanQualityScanner ssr rules", () => {
+  test("flags a client file that uses no client-only capability", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Plain.tsx": `"use client";\nexport const Plain = () => <div>plain</div>;\n`,
+      "apps/demo/ui/Interactive.tsx": `"use client";\nexport const Interactive = () => <button onClick={() => null}>go</button>;\n`,
+      "apps/demo/ui/Hooked.tsx": `"use client";\nimport { useState } from "react";\nexport const Hooked = () => {\n  const [open] = useState(false);\n  return <div>{open ? "y" : "n"}</div>;\n};\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.unnecessary-use-client");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.file).toBe("apps/demo/ui/Plain.tsx");
+  });
+
+  test("keeps the directive on a third-party wrapper and on an index_ boundary", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Chart.tsx": `"use client";\nimport { Bar } from "react-chartjs-2";\nexport const Chart = () => <Bar data={{}} />;\n`,
+      "apps/demo/ui/Lazy/index_.tsx": `"use client";\nexport { Inner } from "./Inner";\n`,
+    });
+
+    expect(rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.unnecessary-use-client")).toHaveLength(0);
+  });
+
+  test("flags a static component and a mostly-static component inside a client file", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Panels.tsx": [
+        `"use client";`,
+        `import { useState } from "react";`,
+        `export const StaticPanel = () => (`,
+        `  <section>`,
+        staticMarkup(5),
+        `  </section>`,
+        `);`,
+        `export const MixedPanel = () => {`,
+        `  const [open, setOpen] = useState(false);`,
+        `  return (`,
+        `    <section>`,
+        staticMarkup(12),
+        `      <span>{open ? "open" : "shut"}</span>`,
+        `    </section>`,
+        `  );`,
+        `};`,
+        "",
+      ].join("\n"),
+    });
+
+    const result = await new AkanQualityScanner().scan(root);
+    const staticWarnings = rulesOf(result, "akan.ssr.client-static-component");
+    const mixedWarnings = rulesOf(result, "akan.ssr.client-static-markup");
+
+    expect(staticWarnings).toHaveLength(1);
+    expect(staticWarnings[0]?.message).toContain("StaticPanel");
+    expect(staticWarnings[0]?.fix).toContain("server file");
+    expect(mixedWarnings).toHaveLength(1);
+    expect(mixedWarnings[0]?.message).toContain("MixedPanel");
+  });
+
+  test("flags a mount-only load but not a reactive one", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Zone.tsx": [
+        `"use client";`,
+        `import { useEffect } from "react";`,
+        `export const List = ({ tag }: { tag: string }) => {`,
+        `  useEffect(() => {`,
+        `    void st.do.initPostInPublic();`,
+        `  }, []);`,
+        `  useEffect(() => {`,
+        `    void st.do.getPostListInTag(tag);`,
+        `  }, [tag]);`,
+        `  return <div>{tag}</div>;`,
+        `};`,
+        "",
+      ].join("\n"),
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.client-mount-load");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("st.do.initPostInPublic");
+    expect(warnings[0]?.fix).toContain("init/view");
+  });
+
+  test("flags useState in a Template", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Template.tsx": `"use client";\nimport { useState } from "react";\nexport const General = () => {\n  const [draft, setDraft] = useState("");\n  return <input value={draft} onChange={(e) => setDraft(e.target.value)} />;\n};\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.template-client-state");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.fix).toContain("st.do.setFieldOnX");
+  });
+
+  test("flags a module that renders only from client files", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/lib/post/Post.Zone.tsx": [
+        `"use client";`,
+        `import { useState } from "react";`,
+        `export const Card = () => {`,
+        `  const [open] = useState(false);`,
+        `  return (`,
+        `    <section>`,
+        staticMarkup(14),
+        `      <span>{open ? "open" : "shut"}</span>`,
+        `    </section>`,
+        `  );`,
+        `};`,
+        "",
+      ].join("\n"),
+      "libs/shared/lib/user/User.Zone.tsx": `"use client";\nimport { st } from "@libs/shared/client";\nexport const Self = () => <User.View.General user={st.use.self()} />;\n`,
+      "libs/shared/lib/user/User.View.tsx": `export const General = ({ name }: { name: string }) => <div>{name}</div>;\n`,
+    });
+
+    const warnings = rulesOf(await new AkanQualityScanner().scan(root), "akan.ssr.module-missing-server-view");
+
+    expect(warnings).toHaveLength(1);
+    expect(warnings[0]?.message).toContain("apps/demo/lib/post");
+  });
+
+  test("measures the server render share per scope and for the workspace", async () => {
+    const root = await makeWorkspace({
+      "apps/demo/ui/Server.tsx": `export const Server = () => (\n  <section>\n    <p>a</p>\n    <p>b</p>\n  </section>\n);\n`,
+      "libs/shared/ui/Client.tsx": `"use client";\nexport const Client = () => <button onClick={() => null}>go</button>;\n`,
+    });
+
+    const { ssrBalance } = await new AkanQualityScanner().scan(root);
+
+    expect(ssrBalance.map((entry) => entry.scope)).toEqual(["apps/demo", "libs/shared", "workspace"]);
+    expect(ssrBalance[0]).toMatchObject({ serverMass: 3, clientMass: 0, serverShare: 1 });
+    expect(ssrBalance[1]).toMatchObject({ serverMass: 0, clientMass: 1 });
+    expect(ssrBalance[2]).toMatchObject({ scope: "workspace", serverMass: 3, clientMass: 1 });
+  });
+});

package/qualityScanner.ts

@@ -4,9 +4,10 @@ import path from "node:path";
 import ignore from "ignore";
 import ts from "typescript";
 import { AbstractDoc } from "./abstractDoc";
+import { formatSsrBalance, type SsrBalanceEntry, SsrScanner } from "./ssrScanner";
 
 type QualitySeverity = "warning";
-type QualityScope = "global" | "file" | "convention" | "layout";
+type QualityScope = "global" | "file" | "convention" | "layout" | "ssr";
 
 export interface QualityWarning {
   rule: string;
@@ -23,10 +24,11 @@ export interface QualityScanResult {
   workspaceRoot: string;
   scannedFiles: number;
   warnings: QualityWarning[];
+  ssrBalance: SsrBalanceEntry[];
   suggestedRules: string[];
 }
 
-interface SourceFileInfo {
+export interface SourceFileInfo {
   file: string;
   absolutePath: string;
   content: string;
@@ -169,6 +171,18 @@ const RULE_FIXES: Record<string, string> = {
     "Move the file into a domain module folder under lib/; keep lib root limited to generated support facets.",
   "akan.layout.module-ui-file":
     "Rename the file to an allowed module UI name, or move it to ui/ if it is not a module component.",
+  "akan.ssr.unnecessary-use-client":
+    'Delete the "use client" directive so the file renders on the server. If it exists only to wrap one client child, drop the wrapper and use the child directly.',
+  "akan.ssr.client-static-component":
+    "Move the component to a server file — a <Model>.Unit.tsx / <Model>.View.tsx for a module, or a ui/ file with no directive — and reference it from the client file.",
+  "akan.ssr.client-static-markup":
+    "Keep the interactive element in the client component and hoist the static subtree into a server component, then accept it as `children` or render it through a Unit/View reference.",
+  "akan.ssr.client-mount-load":
+    "Load the data in the route with `fetch.initX(...)` / `fetch.viewX(...)` and pass the init/view object down as a prop; the client store hydrates from it and the effect goes away.",
+  "akan.ssr.module-missing-server-view":
+    "Add a <Model>.Unit.tsx for list/card rendering and a <Model>.View.tsx for the detail surface, then have the Zone delegate to them.",
+  "akan.ssr.template-client-state":
+    "Bind the field to the store instead: `value={xForm.field}` with `onChange={st.do.setFieldOnX}`.",
 };
 
 function getRuleFix(rule: string): string | undefined {
@@ -190,6 +204,7 @@ export class AkanQualityScanner {
         .filter((file) => AbstractDoc.isAbstractPath(file))
         .map((file) => this.#readTextFile(workspaceRoot, file)),
     );
+    const ssr = new SsrScanner().scan(sourceFiles);
     const warnings = [
       ...this.#scanGlobalQuality(sourceFiles),
       ...sourceFiles.flatMap((sourceFile) => this.#scanSingleFileQuality(sourceFile)),
@@ -197,6 +212,7 @@ export class AkanQualityScanner {
       ...sourceFiles.flatMap((sourceFile) => this.#scanConventionQuality(sourceFile)),
       ...sourceFiles.flatMap((sourceFile) => this.#scanLayoutQuality(sourceFile)),
       ...abstractFiles.flatMap((abstractFile) => this.#scanAbstractQuality(abstractFile)),
+      ...ssr.warnings,
     ];
 
     return {
@@ -205,6 +221,7 @@ export class AkanQualityScanner {
       warnings: warnings
         .map((warning) => ({ ...warning, fix: warning.fix ?? getRuleFix(warning.rule) }))
         .sort(compareWarnings),
+      ssrBalance: ssr.balance,
       suggestedRules: SUGGESTED_RULES,
     };
   }
@@ -470,6 +487,10 @@ export function formatQualityScanResult(result: QualityScanResult) {
     "",
     ...formatQualityWarnings(result.warnings),
     "",
+    "SSR balance (component files, JSX elements rendered per side):",
+    "",
+    ...formatSsrBalance(result.ssrBalance),
+    "",
     "Suggested quality rules:",
     "",
     ...result.suggestedRules.map((rule) => `  - ${rule}`),
@@ -477,6 +498,24 @@ export function formatQualityScanResult(result: QualityScanResult) {
   return sections.join("\n");
 }
 
+export function formatSsrScanResult(result: QualityScanResult) {
+  const sections = [
+    "Akan SSR Balance Scan",
+    `workspace: ${result.workspaceRoot}`,
+    `scanned files: ${result.scannedFiles}`,
+    `ssr warnings: ${result.warnings.length}`,
+    "",
+    "Server render share (component files, JSX elements rendered per side):",
+    "",
+    ...formatSsrBalance(result.ssrBalance),
+    "",
+    "Warnings:",
+    "",
+    ...formatQualityWarnings(result.warnings),
+  ];
+  return sections.join("\n");
+}
+
 export function formatQualityWarnings(warnings: QualityWarning[]) {
   if (warnings.length === 0) return ["No warnings found."];
   return warnings.flatMap((warning) => {

package/spinner.test.ts

@@ -0,0 +1,81 @@
+import { describe, expect, test } from "bun:test";
+import { Spinner } from "./spinner";
+
+interface TtyStub {
+  restore: () => void;
+  rawModeCalls: boolean[];
+}
+
+/**
+ * ora only reaches for stdin when both streams look interactive, so the stub has to fake a tty on
+ * stderr (which decides `isEnabled`) as well as on stdin.
+ */
+const stubTty = (): TtyStub => {
+  const rawModeCalls: boolean[] = [];
+  const stdin = process.stdin as NodeJS.ReadStream & { setRawMode?: (mode: boolean) => unknown };
+  const previous = {
+    stdinIsTTY: stdin.isTTY,
+    stderrIsTTY: process.stderr.isTTY,
+    stderrColumns: process.stderr.columns,
+    setRawMode: stdin.setRawMode,
+    isPaused: stdin.isPaused,
+  };
+  stdin.isTTY = true;
+  process.stderr.isTTY = true;
+  process.stderr.columns = 120;
+  stdin.setRawMode = (mode: boolean) => {
+    rawModeCalls.push(mode);
+    return stdin;
+  };
+  stdin.isPaused = () => true;
+  return {
+    rawModeCalls,
+    restore: () => {
+      stdin.isTTY = previous.stdinIsTTY;
+      process.stderr.isTTY = previous.stderrIsTTY;
+      process.stderr.columns = previous.stderrColumns;
+      stdin.setRawMode = previous.setRawMode;
+      stdin.isPaused = previous.isPaused;
+    },
+  };
+};
+
+describe("Spinner", () => {
+  // A raw terminal at spawn time is what a Bun child snapshots and writes back when it exits, which is
+  // how `akan start` used to leave a terminal that no longer turns Ctrl+C into SIGINT.
+  test("never puts the terminal into raw mode while it spins", () => {
+    const tty = stubTty();
+    try {
+      const spinner = new Spinner("Preparing backend...").start();
+      expect(tty.rawModeCalls).toEqual([]);
+      spinner.succeed("prepared");
+      expect(tty.rawModeCalls).toEqual([]);
+    } finally {
+      tty.restore();
+    }
+  });
+
+  test("keeps ora's stdin discarder disabled", () => {
+    expect(Spinner.oraOptions.discardStdin).toBe(false);
+  });
+
+  // An unsized pty reports `isTTY: true` with `columns: 0`, which turns ora's clear loop into an
+  // infinite one — the process then writes cursor moves until it is SIGKILLed.
+  test("refuses to animate against a tty that reports no width", () => {
+    expect(Spinner.canAnimate({ isTTY: true, columns: 0 } as NodeJS.WriteStream)).toBe(false);
+    expect(Spinner.canAnimate({ isTTY: true, columns: 120 } as NodeJS.WriteStream)).toBe(true);
+    expect(Spinner.canAnimate({ isTTY: false, columns: 0 } as NodeJS.WriteStream)).toBe(true);
+  });
+
+  test("falls back to plain lines when the terminal has no width", () => {
+    const previous = { isTTY: process.stderr.isTTY, columns: process.stderr.columns };
+    process.stderr.isTTY = true;
+    process.stderr.columns = 0;
+    try {
+      expect(new Spinner("Preparing backend...").enableSpin).toBe(false);
+    } finally {
+      process.stderr.isTTY = previous.isTTY;
+      process.stderr.columns = previous.columns;
+    }
+  });
+});

package/spinner.ts

@@ -2,6 +2,26 @@ import ora, { type Ora } from "ora";
 
 export class Spinner {
   static padding = 12;
+  /**
+   * XXX: `discardStdin` must stay off. It makes ora put the terminal into raw mode for as long as the
+   * spinner runs, and a Bun child spawned in that window snapshots the raw termios and writes it back
+   * when it exits — long after the spinner restored the terminal. `akan start` spawns the builder and
+   * the backend under the "Preparing backend..." spinner, so the first builder recycle (a config or
+   * runtime-metadata change) SIGTERMs that child and silently turns the developer's terminal raw:
+   * `isig` goes off, Ctrl+C stops producing SIGINT at all, and the dev server looks unkillable.
+   */
+  static oraOptions = { discardStdin: false } as const;
+  /**
+   * ora sizes its clear loop as `ceil(lineWidth / stream.columns)`, so a tty that reports **0** columns
+   * makes it `Infinity` and `clear()` never returns. An unsized pty does exactly that (`isTTY: true`,
+   * `columns: 0`) — CI runners, `expect`/`script` harnesses, some detached panes. Measured: 750MB of
+   * cursor moves and 8.7GB RSS inside a minute, in a loop that no longer reaches the point where SIGINT
+   * or SIGTERM could be handled, so only SIGKILL ends it. A terminal with no width has nothing to
+   * animate anyway; fall back to plain lines.
+   */
+  static canAnimate(stream: NodeJS.WriteStream = process.stderr): boolean {
+    return !stream.isTTY || stream.columns > 0;
+  }
   spinner: Ora;
   stopWatch: NodeJS.Timeout | null = null;
   startAt: Date = new Date();
@@ -12,10 +32,10 @@ export class Spinner {
     Spinner.padding = Math.max(Spinner.padding, prefix.length);
     this.prefix = prefix;
     this.message = message;
-    this.spinner = ora(message);
+    this.spinner = ora({ ...Spinner.oraOptions, text: message });
     this.spinner.prefixText = prefix.padStart(Spinner.padding, " ");
     this.spinner.indent = indent;
-    this.enableSpin = enableSpin;
+    this.enableSpin = enableSpin && Spinner.canAnimate();
   }
   start() {
     this.startAt = new Date();

package/ssrScanner.ts

@@ -0,0 +1,409 @@
+import ts from "typescript";
+import type { QualityWarning, SourceFileInfo } from "./qualityScanner";
+
+/** Server/client render split for one app or lib, measured in JSX elements rather than files. */
+export interface SsrBalanceEntry {
+  scope: string;
+  serverMass: number;
+  clientMass: number;
+  serverShare: number;
+}
+
+export interface SsrScanResult {
+  warnings: QualityWarning[];
+  balance: SsrBalanceEntry[];
+}
+
+interface ComponentInfo {
+  name: string;
+  line: number;
+  mass: number;
+  touches: string[];
+  vendorTags: boolean;
+}
+
+// A component with no client-only touch at all never needed the client bundle, so even a small subtree is
+// worth moving. A mostly-static component keeps its interaction and hands the static part to the server, so
+// it only pays off once the static subtree is large enough to matter.
+const STATIC_COMPONENT_MIN_MASS = 4;
+const MIXED_COMPONENT_MIN_MASS = 10;
+const MIXED_COMPONENT_MAX_TOUCHES = 2;
+const MODULE_SERVER_VIEW_MIN_CLIENT_MASS = 12;
+
+export class SsrScanner {
+  // `usePage` and `getSelf` read request-scoped server context and are legal in server components, so they
+  // must not count as evidence that a file needs "use client".
+  static #serverSafeCalls = new Set(["usePage", "getSelf", "useServer"]);
+  static #clientGlobals = new Set([
+    "window",
+    "document",
+    "navigator",
+    "localStorage",
+    "sessionStorage",
+    "location",
+    "history",
+    "screen",
+    "matchMedia",
+    "IntersectionObserver",
+    "ResizeObserver",
+    "MutationObserver",
+    "requestAnimationFrame",
+    "WebSocket",
+  ]);
+  // Runtime singletons that only exist in the client bundle; importing either is what forces the directive.
+  static #clientRuntimeImports = new Set(["st", "fetch"]);
+
+  scan(sourceFiles: SourceFileInfo[]): SsrScanResult {
+    const componentFiles = sourceFiles.filter((sourceFile) => this.#isBalancedFile(sourceFile.file));
+    return {
+      warnings: [
+        ...componentFiles.flatMap((sourceFile) => this.#scanFile(sourceFile)),
+        ...this.#scanModules(componentFiles),
+      ],
+      balance: this.#measureBalance(componentFiles),
+    };
+  }
+
+  #scanFile(sourceFile: SourceFileInfo): QualityWarning[] {
+    if (!this.#hasUseClient(sourceFile.sourceFile)) return [];
+    const vendorNames = this.#getVendorNames(sourceFile.sourceFile);
+    const hasVendorImport = this.#hasVendorImport(sourceFile.sourceFile);
+    const importsClientRuntime = this.#importsClientRuntime(sourceFile.sourceFile);
+    const components = this.#getComponents(sourceFile, vendorNames);
+    const warnings: QualityWarning[] = [];
+
+    if (
+      !hasVendorImport &&
+      !importsClientRuntime &&
+      this.#getTouches(sourceFile.sourceFile, sourceFile.sourceFile).length === 0 &&
+      !this.#isConventionClientFile(sourceFile.file)
+    ) {
+      warnings.push({
+        rule: "akan.ssr.unnecessary-use-client",
+        scope: "ssr",
+        severity: "warning",
+        file: sourceFile.file,
+        line: 1,
+        message: `"use client" is declared but the file uses no client-only capability (hook, event handler, store, or browser API).`,
+      });
+    }
+
+    for (const component of components) {
+      if (component.vendorTags) continue;
+      if (component.touches.length === 0 && component.mass >= STATIC_COMPONENT_MIN_MASS) {
+        warnings.push({
+          rule: "akan.ssr.client-static-component",
+          scope: "ssr",
+          severity: "warning",
+          file: sourceFile.file,
+          line: component.line,
+          message: `Client component "${component.name}" renders ${component.mass} JSX elements with no client-only capability. It is server-renderable markup sitting in the client bundle.`,
+        });
+        continue;
+      }
+      if (
+        component.touches.length >= 1 &&
+        component.touches.length <= MIXED_COMPONENT_MAX_TOUCHES &&
+        component.mass >= MIXED_COMPONENT_MIN_MASS
+      ) {
+        warnings.push({
+          rule: "akan.ssr.client-static-markup",
+          scope: "ssr",
+          severity: "warning",
+          file: sourceFile.file,
+          line: component.line,
+          message: `Client component "${component.name}" renders ${component.mass} JSX elements around only ${component.touches.length} client-only touch (${[...new Set(component.touches)].join(", ")}). Most of this subtree does not need the client bundle.`,
+        });
+      }
+    }
+
+    warnings.push(...this.#getMountLoadWarnings(sourceFile));
+    warnings.push(...this.#getTemplateStateWarnings(sourceFile));
+    return warnings;
+  }
+
+  // A database module whose rendering happens entirely in Template/Zone/Util has no server-rendered surface at
+  // all, so every consumer pays for hydration even when it only needs to display the model.
+  #scanModules(sourceFiles: SourceFileInfo[]): QualityWarning[] {
+    const modules = new Map<string, { clientMass: number; serverFiles: number; line: string }>();
+    for (const sourceFile of sourceFiles) {
+      const moduleDir = this.#getModuleDir(sourceFile.file);
+      if (!moduleDir) continue;
+      const entry = modules.get(moduleDir) ?? { clientMass: 0, serverFiles: 0, line: sourceFile.file };
+      if (this.#hasUseClient(sourceFile.sourceFile)) entry.clientMass += this.#getMass(sourceFile.sourceFile);
+      else if (/\.(Unit|View)\.tsx$/.test(sourceFile.file)) entry.serverFiles += 1;
+      modules.set(moduleDir, entry);
+    }
+    return [...modules]
+      .filter(([, entry]) => entry.serverFiles === 0 && entry.clientMass >= MODULE_SERVER_VIEW_MIN_CLIENT_MASS)
+      .map(([moduleDir, entry]) => ({
+        rule: "akan.ssr.module-missing-server-view",
+        scope: "ssr" as const,
+        severity: "warning" as const,
+        file: entry.line,
+        message: `Module "${moduleDir}" renders ${entry.clientMass} JSX elements from client files only; it declares no Unit or View server component.`,
+      }));
+  }
+
+  // A load fired from a mount-only effect is data the route already could have fetched: the client renders an
+  // empty shell, hydrates, then fetches. A reactive effect (non-empty deps) responds to client state instead
+  // and has no server-side equivalent, so only the empty-dependency form is a finding.
+  #getMountLoadWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
+    const warnings: QualityWarning[] = [];
+    const visit = (node: ts.Node) => {
+      if (this.#isMountEffect(sourceFile.sourceFile, node)) {
+        for (const load of this.#getLoadCalls(sourceFile.sourceFile, node)) {
+          warnings.push({
+            rule: "akan.ssr.client-mount-load",
+            scope: "ssr",
+            severity: "warning",
+            file: sourceFile.file,
+            line: this.#getLine(sourceFile.sourceFile, load.node),
+            message: `Mount-only effect loads server data with ${load.callee}(). The route can fetch this before the first byte instead.`,
+          });
+        }
+      }
+      ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sourceFile.sourceFile, visit);
+    return warnings;
+  }
+
+  #isMountEffect(sourceFile: ts.SourceFile, node: ts.Node) {
+    if (!ts.isCallExpression(node)) return false;
+    const callee = node.expression.getText(sourceFile);
+    if (callee !== "useEffect" && callee !== "useLayoutEffect") return false;
+    const deps = node.arguments[1];
+    return !!deps && ts.isArrayLiteralExpression(deps) && deps.elements.length === 0;
+  }
+
+  #getLoadCalls(sourceFile: ts.SourceFile, node: ts.Node) {
+    const calls: Array<{ callee: string; node: ts.Node }> = [];
+    const visit = (child: ts.Node) => {
+      if (ts.isCallExpression(child)) {
+        const callee = child.expression.getText(sourceFile);
+        if (/^fetch\.[a-z]/.test(callee) || /^st\.do\.(init|get|view|load|list|count|insight)[A-Z]/.test(callee))
+          calls.push({ callee, node: child });
+      }
+      ts.forEachChild(child, visit);
+    };
+    ts.forEachChild(node, visit);
+    return calls;
+  }
+
+  #getTemplateStateWarnings(sourceFile: SourceFileInfo): QualityWarning[] {
+    if (!sourceFile.file.endsWith(".Template.tsx")) return [];
+    const warnings: QualityWarning[] = [];
+    const visit = (node: ts.Node) => {
+      if (ts.isCallExpression(node) && node.expression.getText(sourceFile.sourceFile) === "useState") {
+        warnings.push({
+          rule: "akan.ssr.template-client-state",
+          scope: "ssr",
+          severity: "warning",
+          file: sourceFile.file,
+          line: this.#getLine(sourceFile.sourceFile, node),
+          message: "Template holds form state in useState. Templates are store-driven and carry no local state.",
+        });
+      }
+      ts.forEachChild(node, visit);
+    };
+    ts.forEachChild(sourceFile.sourceFile, visit);
+    return warnings;
+  }
+
+  #measureBalance(sourceFiles: SourceFileInfo[]): SsrBalanceEntry[] {
+    const scopes = new Map<string, { serverMass: number; clientMass: number }>();
+    for (const sourceFile of sourceFiles) {
+      const segments = sourceFile.file.split("/");
+      const scope = `${segments[0]}/${segments[1]}`;
+      const entry = scopes.get(scope) ?? { serverMass: 0, clientMass: 0 };
+      const mass = this.#getMass(sourceFile.sourceFile);
+      if (this.#hasUseClient(sourceFile.sourceFile)) entry.clientMass += mass;
+      else entry.serverMass += mass;
+      scopes.set(scope, entry);
+    }
+    const entries = [...scopes]
+      .map(([scope, mass]) => ({ scope, ...mass, serverShare: getShare(mass.serverMass, mass.clientMass) }))
+      .sort((a, b) => a.scope.localeCompare(b.scope));
+    if (entries.length < 2) return entries;
+    const serverMass = entries.reduce((sum, entry) => sum + entry.serverMass, 0);
+    const clientMass = entries.reduce((sum, entry) => sum + entry.clientMass, 0);
+    return [...entries, { scope: "workspace", serverMass, clientMass, serverShare: getShare(serverMass, clientMass) }];
+  }
+
+  #getComponents(sourceFile: SourceFileInfo, vendorNames: Set<string>): ComponentInfo[] {
+    const components: ComponentInfo[] = [];
+    for (const statement of sourceFile.sourceFile.statements) {
+      for (const { name, node } of this.#getComponentNodes(statement)) {
+        if (!/^[A-Z]/.test(name)) continue;
+        components.push({
+          name,
+          line: this.#getLine(sourceFile.sourceFile, node),
+          mass: this.#getMass(node),
+          touches: this.#getTouches(sourceFile.sourceFile, node),
+          vendorTags: [...this.#getTagNames(sourceFile.sourceFile, node)].some((tag) => vendorNames.has(tag)),
+        });
+      }
+    }
+    return components;
+  }
+
+  #getComponentNodes(statement: ts.Statement): Array<{ name: string; node: ts.Node }> {
+    if (ts.isFunctionDeclaration(statement) && statement.body)
+      return [{ name: statement.name?.text ?? "default", node: statement.body }];
+    if (!ts.isVariableStatement(statement)) return [];
+    return statement.declarationList.declarations.flatMap((declaration) => {
+      if (!ts.isIdentifier(declaration.name) || !declaration.initializer) return [];
+      if (!ts.isArrowFunction(declaration.initializer) && !ts.isFunctionExpression(declaration.initializer)) return [];
+      return [{ name: declaration.name.text, node: declaration.initializer }];
+    });
+  }
+
+  #getTouches(sourceFile: ts.SourceFile, node: ts.Node): string[] {
+    const touches: string[] = [];
+    const visit = (child: ts.Node) => {
+      if (ts.isCallExpression(child)) {
+        const callee = child.expression.getText(sourceFile);
+        const bareName = callee.split(".").pop() ?? callee;
+        if (callee === "createContext" || callee === "lazy") touches.push(callee);
+        else if (/^use[A-Z]/.test(bareName) && !SsrScanner.#serverSafeCalls.has(bareName)) touches.push(bareName);
+      }
+      if (ts.isJsxAttribute(child) && /^on[A-Z]/.test(child.name.getText(sourceFile)))
+        touches.push(child.name.getText(sourceFile));
+      if (ts.isPropertyAccessExpression(child)) {
+        const root = getAccessRoot(child);
+        if (root === "st") touches.push("st");
+        else if (SsrScanner.#clientGlobals.has(root)) touches.push(root);
+      }
+      ts.forEachChild(child, visit);
+    };
+    ts.forEachChild(node, visit);
+    return touches;
+  }
+
+  #getTagNames(sourceFile: ts.SourceFile, node: ts.Node): Set<string> {
+    const tags = new Set<string>();
+    const visit = (child: ts.Node) => {
+      if (ts.isJsxOpeningElement(child) || ts.isJsxSelfClosingElement(child))
+        tags.add(child.tagName.getText(sourceFile).split(".")[0]);
+      ts.forEachChild(child, visit);
+    };
+    ts.forEachChild(node, visit);
+    return tags;
+  }
+
+  #getMass(node: ts.Node) {
+    let mass = 0;
+    const visit = (child: ts.Node) => {
+      if (ts.isJsxOpeningElement(child) || ts.isJsxSelfClosingElement(child)) mass += 1;
+      ts.forEachChild(child, visit);
+    };
+    ts.forEachChild(node, visit);
+    return mass;
+  }
+
+  #hasUseClient(sourceFile: ts.SourceFile) {
+    const first = sourceFile.statements[0];
+    if (!first || !ts.isExpressionStatement(first) || !ts.isStringLiteral(first.expression)) return false;
+    return first.expression.text === "use client";
+  }
+
+  // A bare specifier is a third-party package: it may be client-only, which is a legitimate reason for the
+  // directive that no amount of AST reading can rule out.
+  #hasVendorImport(sourceFile: ts.SourceFile) {
+    return sourceFile.statements.some(
+      (statement) => ts.isImportDeclaration(statement) && isVendorSpecifier(getSpecifier(statement)),
+    );
+  }
+
+  #getVendorNames(sourceFile: ts.SourceFile) {
+    const names = new Set<string>();
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement) || !isVendorSpecifier(getSpecifier(statement))) continue;
+      const clause = statement.importClause;
+      if (clause?.name) names.add(clause.name.text);
+      if (clause?.namedBindings && ts.isNamespaceImport(clause.namedBindings))
+        names.add(clause.namedBindings.name.text);
+      if (clause?.namedBindings && ts.isNamedImports(clause.namedBindings))
+        for (const element of clause.namedBindings.elements) names.add(element.name.text);
+    }
+    return names;
+  }
+
+  #importsClientRuntime(sourceFile: ts.SourceFile) {
+    for (const statement of sourceFile.statements) {
+      if (!ts.isImportDeclaration(statement)) continue;
+      const bindings = statement.importClause?.namedBindings;
+      if (!bindings || !ts.isNamedImports(bindings)) continue;
+      if (bindings.elements.some((element) => SsrScanner.#clientRuntimeImports.has(element.name.text))) return true;
+    }
+    return false;
+  }
+
+  // Zone/Template/Util carry the directive mechanically by file role, and `index_.tsx` is the declared
+  // "use client" + lazy() boundary. In neither case is the directive a stray — for module UI it means markup
+  // belongs in a Unit or View instead, which the component rules already cover.
+  #isConventionClientFile(file: string) {
+    if (file.endsWith("/index_.tsx")) return true;
+    return /\.(Zone|Template|Util)\.tsx$/.test(file) && this.#getModuleDir(file) !== null;
+  }
+
+  #isBalancedFile(file: string) {
+    if (!file.endsWith(".tsx") || file.endsWith(".test.tsx") || file.endsWith(".spec.tsx")) return false;
+    const segments = file.split("/");
+    if (segments[0] !== "apps" && segments[0] !== "libs") return false;
+    return segments[2] === "ui" || segments[2] === "lib";
+  }
+
+  #getModuleDir(file: string) {
+    const segments = file.split("/");
+    const libIndex = segments.indexOf("lib");
+    if (libIndex < 1 || segments.length <= libIndex + 2) return null;
+    const moduleName = segments[libIndex + 1];
+    if (moduleName.startsWith("_")) return null;
+    return segments.slice(0, libIndex + 2).join("/");
+  }
+
+  #getLine(sourceFile: ts.SourceFile, node: ts.Node) {
+    return sourceFile.getLineAndCharacterOfPosition(node.getStart(sourceFile)).line + 1;
+  }
+}
+
+/** Share of component rendering an app or lib should keep on the server before the split needs a reason. */
+export const SSR_SERVER_SHARE_TARGET = 0.5;
+
+export function formatSsrBalance(balance: SsrBalanceEntry[]) {
+  if (balance.length === 0) return ["No component files found."];
+  return balance.map((entry) => {
+    const total = entry.serverMass + entry.clientMass;
+    const share = `${Math.round(entry.serverShare * 100)}% server`;
+    const counts = `${entry.serverMass} of ${total} JSX elements, ${entry.clientMass} client`;
+    const flag =
+      entry.serverShare < SSR_SERVER_SHARE_TARGET
+        ? `  <- below the ${Math.round(SSR_SERVER_SHARE_TARGET * 100)}% target`
+        : "";
+    return `  ${entry.scope}: ${share} (${counts})${flag}`;
+  });
+}
+
+function getShare(serverMass: number, clientMass: number) {
+  const total = serverMass + clientMass;
+  return total === 0 ? 1 : serverMass / total;
+}
+
+function getSpecifier(statement: ts.ImportDeclaration) {
+  return ts.isStringLiteral(statement.moduleSpecifier) ? statement.moduleSpecifier.text : "";
+}
+
+function isVendorSpecifier(specifier: string) {
+  if (specifier === "" || specifier.startsWith(".") || specifier.startsWith("/")) return false;
+  if (specifier === "react" || specifier === "react-dom" || specifier.startsWith("react/")) return false;
+  if (specifier.startsWith("node:")) return false;
+  return !/^(akanjs|@akanjs|@libs|@apps|@contract)(\/|$)/.test(specifier);
+}
+
+function getAccessRoot(node: ts.PropertyAccessExpression) {
+  let current: ts.Expression = node;
+  while (ts.isPropertyAccessExpression(current)) current = current.expression;
+  return ts.isIdentifier(current) ? current.text : "";
+}