@tdk-landscape/tdk-cli-core 1.3.49 → 1.3.50

package/scripts/autoresearch/layer-eval.sh

@@ -0,0 +1,65 @@
+#!/usr/bin/env bash
+# Ground-truth evaluation for L1-L4 layer experiments. DO NOT EDIT during an autoresearch run.
+# Re-vendors this engine into the ERP project, regenerates Dockerfiles through Tilt, rebuilds the
+# golden layers and a fixed sample of 20 real ERP services, runs the container benchmark and the
+# feature tests, then prints one summary block.
+set -uo pipefail
+CORE="$(cd "$(dirname "$0")/../.." && pwd)"
+ERP="${TDK_BENCH_PROJECT:-$CORE/../tdk-erp-system}"
+SAMPLE="${LAYER_EVAL_SAMPLE:-20}"
+TDK_CLI="${TDK_CLI:-$CORE/cli/bin/tdk.js}"
+PREFIX="$(python3 -c "import json;print(json.load(open('$ERP/.tdk/project.json'))['project']['name'])")"
+t() { date +%s; }
+
+cd "$ERP"
+TDK_EXTENSION_SOURCE="$CORE" node "$TDK_CLI" project --yes >/dev/null 2>&1 || { echo "status: crash (tdk project)"; exit 1; }
+tilt alpha tiltfile-result -f .tdk/.tdk-out/Tiltfile >/dev/null 2>&1 || { echo "status: crash (Tiltfile evaluation)"; exit 1; }
+
+s=$(t)
+for target in l1_golden:l1 l2_golden:l2 l3_backend_golden:l3-backend l3_frontend_golden:l3-frontend l4_backend_bun:l4-backend l4_frontend_golden:l4-frontend; do
+  docker build -q -f .tdk/.tdk-out/golden-layers.Dockerfile --target "${target%%:*}" -t "$PREFIX-${target##*:}:latest" . >/dev/null 2>&1 \
+    || { echo "status: crash (golden ${target%%:*})"; exit 1; }
+done
+golden_build_s=$(( $(t) - s ))
+
+s=$(t)
+ls services/*/*/service.json | sort | head -n "$SAMPLE" | while read -r manifest; do
+  dir="$(dirname "$manifest")"; svc="$(basename "$dir")"; stack="$(basename "$(dirname "$dir")")"
+  echo "docker build -q -f $dir/.autogenerated/Dockerfile.app.autogenerated --target production -t ${stack}_${svc}:dev . >/dev/null 2>&1 || echo FAIL $svc"
+done | xargs -P 4 -I{} sh -c '{}' | tee /tmp/layer-eval-build.log
+grep -q FAIL /tmp/layer-eval-build.log && { echo "status: crash (service build: $(grep FAIL /tmp/layer-eval-build.log | head -3 | tr '\n' ' '))"; exit 1; }
+service_build_s=$(( $(t) - s ))
+
+cd "$CORE"
+bun scripts/benchmark/container-scale.ts --synthetic --tiers "$SAMPLE" --gate "$SAMPLE" --settle 15 > /tmp/layer-eval-bench.log 2>&1
+result="$(ls -t benchmarks/results/container-scale-*.json | head -1)"
+tests=pass
+python3 -m pytest tests/tilt-engine/test_runtime_container_footprint.py -q -p no:cacheprovider >/tmp/layer-eval-tests.log 2>&1 || tests=fail
+
+python3 - "$result" "$ERP" "$SAMPLE" "$PREFIX" "$golden_build_s" "$service_build_s" "$tests" <<'PY'
+import json, subprocess, sys, glob, os
+result, erp, sample, prefix, gb, sb, tests = sys.argv[1:]
+r = json.load(open(result))["results"][0]
+def size(img):
+    out = subprocess.run(["docker", "image", "inspect", img, "--format", "{{.Size}}"], capture_output=True, text=True).stdout.strip()
+    return int(out) / 1048576 if out else 0
+base = size(f"{prefix}-l4-backend:latest")
+svcs = sorted(glob.glob(f"{erp}/services/*/*/service.json"))[: int(sample)]
+backend = [f"{os.path.basename(os.path.dirname(os.path.dirname(p)))}_{os.path.basename(os.path.dirname(p))}:dev" for p in svcs
+           if json.load(open(p)).get("appType") != "frontend"]
+sizes = [size(i) for i in backend]
+ok = r["allHealthySeconds"] is not None and r["crashed"] == 0 and tests == "pass"
+print("---")
+print(f"mem_per_service_mib: {r['avgMemMiB']}")
+print(f"service_image_mib:   {sum(sizes)/len(sizes):.1f}")
+print(f"unique_per_service_mib: {sum(sizes)/len(sizes) - base:.1f}")
+print(f"l4_backend_mib:      {base:.1f}")
+print(f"all_healthy_s:       {r['allHealthySeconds']}")
+print(f"crashed:             {r['crashed']}")
+print(f"docker_ps_ms:        {r['dockerPsMs']}")
+print(f"cpu_total_pct:       {r['totalCpuPct']}")
+print(f"golden_build_s:      {gb}")
+print(f"service_build_s:     {sb}")
+print(f"tests:               {tests}")
+print(f"status:              {'ok' if ok else 'invalid'}")
+PY

package/scripts/benchmark/README.md

@@ -0,0 +1,25 @@
+# Container scale benchmark
+
+Release gate for the north star: **100 ERP services on a 16 GB machine without removing features**.
+
+```bash
+bun scripts/benchmark/container-scale.ts                       # tiers 5,10,20,50,80,100, gate on 100
+bun scripts/benchmark/container-scale.ts --tiers 5,10 --gate 10
+bun scripts/benchmark/container-scale.ts --legacy-healthcheck  # old 10s probes, for comparison
+```
+
+It uses the ERP images that `tdk up` already built in `../tdk-erp-system` (override with `--project` or `TDK_BENCH_PROJECT`). For each tier it starts N real service containers with the generated runtime settings (`--init`, 512 MiB / 0.5 CPU limits, healthchecks against `/health`). It then records:
+
+- launch time, first-healthy and all-healthy time
+- crashes and OOM kills, with each container's exit code and last log line
+- total and average memory, CPU
+- `docker ps` latency (`tdk doctor` fails above 10 s)
+- p50 `/health` latency and host load
+
+Containers are removed after each tier. Results are printed as a table and saved to `benchmarks/results/*.json`.
+
+**Gate:** at the gate tier, every container must be healthy within the timeout with no crashes. Total memory must fit `(Docker VM memory - 512 MiB) / 100` per service, and `docker ps` must answer in under 10 s. The exit code is 1 when the gate fails.
+
+**Git hook (opt-in):** call `scripts/benchmark/pre-release-gate.sh` from `pre-push` or `pre-commit`. It does nothing unless `TDK_BENCH_GATE=1`.
+
+Rebuild the ERP images after engine changes (`tdk project --yes && tdk up` in the ERP project) so the benchmark measures the current layers. The header line reports what share of images use a single-process `CMD`.

package/scripts/benchmark/container-scale.ts

@@ -0,0 +1,503 @@
+#!/usr/bin/env bun
+/**
+ * Container scale benchmark / release gate.
+ *
+ * Starts N real ERP service containers (images built by `tdk up` in the ERP
+ * project) for each tier, measures time-to-healthy, crashes, memory, CPU and
+ * Docker responsiveness, tears them down, and gates on the north star:
+ * 100 services on a 16 GB machine.
+ *
+ *   bun scripts/benchmark/container-scale.ts                    # 5,10,20,50,80,100
+ *   bun scripts/benchmark/container-scale.ts --tiers 5,10 --gate 10
+ *   bun scripts/benchmark/container-scale.ts --legacy-healthcheck   # 10s probes, for comparison
+ *
+ * Exit code 1 when the gate tier fails.
+ */
+import { execSync, spawnSync } from "node:child_process";
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from "node:fs";
+import { basename, dirname, join, relative, resolve } from "node:path";
+
+const REPO_ROOT = resolve(import.meta.dir, "..", "..");
+const PREFIX = "tdkbench-";
+
+interface Options {
+  mode: "compose" | "synthetic";
+  project: string;
+  tiers: number[];
+  gate: number;
+  timeoutSeconds: number;
+  interval: number;
+  startInterval: number;
+  settleSeconds: number;
+}
+
+function parseArgs(): Options {
+  const args = process.argv.slice(2);
+  const get = (flag: string, fallback: string): string => {
+    const i = args.indexOf(flag);
+    return i >= 0 && args[i + 1] ? args[i + 1] : fallback;
+  };
+  const legacy = args.includes("--legacy-healthcheck");
+  const tiers = get("--tiers", "5,10,20,50,80,100").split(",").map(Number).filter((n) => n > 0);
+  return {
+    mode: args.includes("--synthetic") ? "synthetic" : "compose",
+    project: resolve(get("--project", process.env.TDK_BENCH_PROJECT ?? join(REPO_ROOT, "..", "tdk-erp-system"))),
+    tiers,
+    gate: Number(get("--gate", String(Math.max(...tiers)))),
+    timeoutSeconds: Number(get("--timeout", "240")),
+    interval: legacy ? 10 : Number(get("--interval", "30")),
+    startInterval: legacy ? 0 : Number(get("--start-interval", "2")),
+    settleSeconds: Number(get("--settle", "15")),
+  };
+}
+
+function sh(command: string, timeoutMs = 120_000): string {
+  return execSync(command, { encoding: "utf-8", stdio: ["ignore", "pipe", "pipe"], timeout: timeoutMs }).trim();
+}
+
+function shOk(command: string, timeoutMs = 120_000): string {
+  try {
+    return sh(command, timeoutMs);
+  } catch {
+    return "";
+  }
+}
+
+interface Service {
+  name: string;
+  stack: string;
+  image: string;
+  port: number;
+  isFrontend: boolean;
+  singleProcess: boolean;
+  imageMiB: number;
+}
+
+function discoverServices(project: string): Service[] {
+  const images = new Set(shOk("docker images --format '{{.Repository}}:{{.Tag}}'").split("\n"));
+  const services: Service[] = [];
+  const manifests = [...new Bun.Glob("services/*/*/service.json").scanSync({ cwd: project })].sort();
+  for (const relative of manifests) {
+    const manifestPath = join(project, relative);
+    const manifest = JSON.parse(readFileSync(manifestPath, "utf-8"));
+    const name = basename(dirname(manifestPath));
+    const stack = manifest.stack ?? basename(dirname(dirname(manifestPath)));
+    const image = `${stack}_${name}:dev`;
+    if (!images.has(image)) continue;
+    const [cmd, bytes] = shOk(`docker image inspect ${image} --format '{{json .Config.Cmd}}|{{.Size}}'`).split("|");
+    services.push({
+      name,
+      stack,
+      image,
+      port: Number(manifest.port ?? 4000),
+      isFrontend: manifest.appType === "frontend",
+      singleProcess: !(cmd ?? "").includes('"run","start"'),
+      imageMiB: Math.round(Number(bytes ?? 0) / 1048576),
+    });
+  }
+  return services;
+}
+
+function dbPassword(project: string): string {
+  const envPath = join(project, ".env");
+  if (!existsSync(envPath)) return "";
+  const line = readFileSync(envPath, "utf-8").split("\n").find((l) => l.startsWith("DB_PASSWORD="));
+  return line ? line.slice("DB_PASSWORD=".length).trim() : "";
+}
+
+function projectName(project: string): string {
+  const pj = join(project, ".tdk", "project.json");
+  const name = existsSync(pj) ? JSON.parse(readFileSync(pj, "utf-8")).project?.name : basename(project);
+  return String(name).replace(/-/g, "_");
+}
+
+function toMiB(raw: string): number {
+  const n = Number.parseFloat(raw);
+  if (/GiB$/.test(raw)) return n * 1024;
+  if (/KiB$/.test(raw)) return n / 1024;
+  if (/MiB$/.test(raw)) return n;
+  if (/[0-9]B$/.test(raw)) return n / 1048576;
+  return n;
+}
+
+function timed<T>(fn: () => T): [T, number] {
+  const start = performance.now();
+  const value = fn();
+  return [value, Math.round(performance.now() - start)];
+}
+
+function hostLoad(): number {
+  return Number.parseFloat(shOk("sysctl -n vm.loadavg").replace(/[{}]/g, "").trim().split(/\s+/)[0] ?? "0");
+}
+
+function hostFreeMiB(): number {
+  const out = shOk("vm_stat");
+  const page = Number(out.match(/page size of (\d+)/)?.[1] ?? 16384);
+  const pages = (key: string) => Number(out.match(new RegExp(`${key}:\\s+(\\d+)`))?.[1] ?? 0);
+  return Math.round(((pages("Pages free") + pages("Pages speculative")) * page) / 1048576);
+}
+
+function removeBenchContainers(): void {
+  const ids = shOk(`docker ps -aq --filter name=${PREFIX}`).split("\n").filter(Boolean);
+  if (ids.length) shOk(`docker rm -f ${ids.join(" ")}`, 300_000);
+}
+
+interface TierResult {
+  tier: number;
+  launchSeconds: number;
+  firstHealthySeconds: number | null;
+  allHealthySeconds: number | null;
+  healthy: number;
+  unhealthy: number;
+  starting: number;
+  crashed: number;
+  oomKilled: number;
+  crashes: { name: string; exitCode: string; oom: boolean; lastLog: string }[];
+  totalMemMiB: number;
+  avgMemMiB: number;
+  totalCpuPct: number;
+  dockerPsMs: number;
+  requestMsP50: number | null;
+  loadAvg1m: number;
+  hostFreeMiB: number;
+  singleProcessShare: number;
+}
+
+function runTier(n: number, services: Service[], opts: Options, network: string, password: string, project: string): TierResult {
+  removeBenchContainers();
+  const picked = Array.from({ length: n }, (_, i) => ({ svc: services[i % services.length], name: `${PREFIX}${i}` }));
+  const healthFlags = (probe: string) =>
+    [
+      `--health-cmd '${probe}'`,
+      `--health-interval ${opts.interval}s`,
+      opts.startInterval > 0 ? `--health-start-interval ${opts.startInterval}s` : "",
+      "--health-timeout 5s --health-start-period 30s --health-retries 3",
+    ].join(" ");
+
+  const t0 = performance.now();
+  for (const { svc, name } of picked) {
+    const probe = svc.isFrontend ? "curl -fs http://localhost/ || exit 1" : `curl -fs http://localhost:${svc.port}/health || exit 1`;
+    const env = svc.isFrontend
+      ? ""
+      : `-e PORT=${svc.port} -e NODE_ENV=development -e DATABASE_URL=postgresql://${project}:${password}@${project}_postgres:5432/${project}_${svc.stack} -e TILT_DATABASE_URL=postgresql://${project}:${password}@${project}_postgres:5432/${project}_${svc.stack} -e AUTO_MIGRATE=false`;
+    const res = spawnSync(
+      "sh",
+      ["-c", `docker run -d --name ${name} --init --memory 512m --cpus 0.5 --network ${network} ${env} ${healthFlags(probe)} ${svc.image}`],
+      { encoding: "utf-8" },
+    );
+    if (res.status !== 0) console.error(`  ! ${name} (${svc.name}) failed to start: ${res.stderr.trim().split("\n").pop()}`);
+  }
+  const launchSeconds = (performance.now() - t0) / 1000;
+
+  let firstHealthy: number | null = null;
+  let allHealthy: number | null = null;
+  const deadline = t0 + opts.timeoutSeconds * 1000;
+  let states: string[] = [];
+  while (performance.now() < deadline) {
+    states = shOk(`docker ps -a --filter name=${PREFIX} --format '{{.Status}}'`, 60_000).split("\n").filter(Boolean);
+    const healthyCount = states.filter((s) => s.includes("(healthy)")).length;
+    const elapsed = (performance.now() - t0) / 1000;
+    if (healthyCount > 0 && firstHealthy === null) firstHealthy = elapsed;
+    if (healthyCount === n) {
+      allHealthy = elapsed;
+      break;
+    }
+    if (states.length === n && states.every((s) => !s.includes("health: starting") && !s.startsWith("Created"))) break;
+    Bun.sleepSync(1000);
+  }
+
+  Bun.sleepSync(opts.settleSeconds * 1000);
+  states = shOk(`docker ps -a --filter name=${PREFIX} --format '{{.Names}}\t{{.Status}}'`, 60_000).split("\n").filter(Boolean);
+  const exitedNames = states.filter((s) => /\tExited|\tRestarting|\tDead/.test(s)).map((s) => s.split("\t")[0]);
+  const crashes = exitedNames.map((name) => {
+    const inspect = shOk(`docker inspect ${name} --format '{{.State.ExitCode}}|{{.State.OOMKilled}}'`).split("|");
+    const lastLog = shOk(`docker logs --tail 3 ${name} 2>&1`).split("\n").filter(Boolean).pop() ?? "";
+    const svc = picked.find((p) => p.name === name)?.svc.name ?? name;
+    return { name: `${name} (${svc})`, exitCode: inspect[0] ?? "?", oom: inspect[1] === "true", lastLog: lastLog.slice(0, 160) };
+  });
+
+  const stats = shOk(`docker stats --no-stream --format '{{.Name}} {{.CPUPerc}} {{.MemUsage}}' $(docker ps -q --filter name=${PREFIX})`, 180_000)
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => l.split(/\s+/))
+    .map(([, cpu, mem]) => ({ cpu: Number.parseFloat(cpu ?? "0"), mem: toMiB(mem ?? "0") }));
+  const totalMem = stats.reduce((a, s) => a + s.mem, 0);
+  const [, dockerPsMs] = timed(() => shOk("docker ps -q", 60_000));
+
+  const running = picked.filter((p) => !exitedNames.includes(p.name)).slice(0, 10);
+  const latencies = running
+    .map(({ svc, name }) => {
+      const url = svc.isFrontend ? "http://localhost/" : `http://localhost:${svc.port}/health`;
+      const out = shOk(`docker exec ${name} curl -s -o /dev/null -w '%{http_code} %{time_total}' ${url}`, 30_000).split(" ");
+      return out[0] === "200" ? Number.parseFloat(out[1] ?? "0") * 1000 : null;
+    })
+    .filter((v): v is number => v !== null)
+    .sort((a, b) => a - b);
+
+  const result: TierResult = {
+    tier: n,
+    launchSeconds: round(launchSeconds),
+    firstHealthySeconds: firstHealthy === null ? null : round(firstHealthy),
+    allHealthySeconds: allHealthy === null ? null : round(allHealthy),
+    healthy: states.filter((s) => s.includes("(healthy)")).length,
+    unhealthy: states.filter((s) => s.includes("(unhealthy)")).length,
+    starting: states.filter((s) => s.includes("health: starting")).length,
+    crashed: crashes.length,
+    oomKilled: crashes.filter((c) => c.oom).length,
+    crashes,
+    totalMemMiB: Math.round(totalMem),
+    avgMemMiB: stats.length ? round(totalMem / stats.length) : 0,
+    totalCpuPct: round(stats.reduce((a, s) => a + s.cpu, 0)),
+    dockerPsMs,
+    requestMsP50: latencies.length ? round(latencies[Math.floor(latencies.length / 2)]) : null,
+    loadAvg1m: hostLoad(),
+    hostFreeMiB: hostFreeMiB(),
+    singleProcessShare: round(picked.filter((p) => p.svc.singleProcess).length / n),
+  };
+  removeBenchContainers();
+  return result;
+}
+
+// ---- compose mode: start services exactly like Tilt (generated compose, real infra, Traefik) ----
+
+function ensureExternalNetworks(composeArgs: string): void {
+  const config = shOk(`docker compose ${composeArgs} config --format json`, 120_000);
+  if (!config) return;
+  for (const net of Object.values(JSON.parse(config).networks ?? {}) as { name?: string; external?: boolean }[]) {
+    if (net.external && net.name && !shOk(`docker network inspect ${net.name} --format '{{.Name}}'`)) shOk(`docker network create ${net.name}`);
+  }
+}
+
+function startInfra(project: string, root: string): string[] {
+  const started: string[] = [];
+  const envFile = join(root, ".env");
+  const infra = [
+    { container: `${project}_postgres`, file: join(root, "services", "platform", "database-management", "docker-compose.yml") },
+    { container: `${project}_traefik`, file: join(root, ".tdk", ".tdk-out", "docker-compose.traefik.yml") },
+  ];
+  for (const { container, file } of infra) {
+    if (shOk(`docker ps -q --filter name=^${container}$`)) continue;
+    if (shOk(`docker ps -aq --filter name=^${container}$`)) shOk(`docker start ${container}`);
+    else {
+      const args = `-f ${file} --env-file ${envFile}`;
+      ensureExternalNetworks(args);
+      shOk(`docker compose ${args} up -d`, 300_000);
+    }
+    started.push(container);
+  }
+  for (let i = 0; i < 60 && !shOk(`docker exec ${project}_postgres pg_isready -U ${project}`); i++) Bun.sleepSync(1000);
+  return started;
+}
+
+function composeArgs(root: string, stack: string): string {
+  return `-p ${stack}-autogenerated -f ${join(root, "services", stack, ".autogenerated", "docker-compose.app.autogenerated.yml")} --env-file ${join(root, ".env")}`;
+}
+
+function routeRequest(container: string): { code: string; ms: number } | null {
+  const labels = JSON.parse(shOk(`docker inspect ${container} --format '{{json .Config.Labels}}'`) || "{}") as Record<string, string>;
+  const ruleKey = Object.keys(labels).find((k) => /^traefik\.http\.routers\.[^.]+\.rule$/.test(k));
+  if (!ruleKey) return null;
+  const rule = labels[ruleKey] ?? "";
+  const host = rule.match(/Host\(`([^`]+)`\)/)?.[1];
+  const prefix = rule.match(/PathPrefix\(`([^`]+)`\)/)?.[1] ?? "";
+  const healthKey = Object.keys(labels).find((k) => k.endsWith(".loadbalancer.healthcheck.path"));
+  const path = `${prefix.replace(/\/$/, "")}${healthKey ? labels[healthKey] : "/"}`;
+  if (!host) return null;
+  const out = shOk(`curl -s -o /dev/null -m 10 -w '%{http_code} %{time_total}' -H 'Host: ${host}' 'http://127.0.0.1:80${path}'`, 20_000).split(" ");
+  return { code: out[0] ?? "000", ms: round(Number.parseFloat(out[1] ?? "0") * 1000) };
+}
+
+function runTierCompose(n: number, services: Service[], opts: Options, project: string): TierResult & { routed: Record<string, number>; restarts: number } {
+  const picked = services.slice(0, Math.min(n, services.length));
+  const byStack = new Map<string, string[]>();
+  for (const svc of picked) byStack.set(svc.stack, [...(byStack.get(svc.stack) ?? []), svc.name]);
+  for (const stack of byStack.keys()) {
+    shOk(`docker exec ${project}_postgres createdb -U ${project} -O ${project} ${project}_${stack}`);
+    ensureExternalNetworks(composeArgs(opts.project, stack));
+  }
+  const names = picked.map((svc) => `${svc.stack}-autogenerated-${svc.name}-1`);
+
+  // Launch every stack's `compose up` in parallel, same as Tilt does across resources.
+  // NOTE: do not use Bun.spawn() + a Bun.sleepSync() poll loop here - sleepSync blocks
+  // Bun's event loop, so a spawned child's exit is never observed and the poll spins
+  // forever even after the real process has finished. Shelling out one blocking
+  // spawnSync (with the stack commands backgrounded and `wait`ed inside the shell)
+  // avoids that: the parent shell, not our JS, is what waits for real completion.
+  const launchScript = [...byStack]
+    .map(([stack, svcs]) => `docker compose ${composeArgs(opts.project, stack)} up -d --no-build ${svcs.join(" ")} &`)
+    .join("\n") + "\nwait\n";
+  const t0 = performance.now();
+  const launch = spawnSync("sh", ["-c", launchScript], { encoding: "utf-8", timeout: opts.timeoutSeconds * 1000 });
+  const launchSeconds = (performance.now() - t0) / 1000;
+  if (launch.status !== 0) console.error(`  ! compose up failed (exit ${launch.status}): ${(launch.stderr ?? "").slice(0, 500)}`);
+
+  const status = () => {
+    const rows = shOk(`docker ps -a --format '{{.Names}}\t{{.Status}}'`, 60_000).split("\n").map((l) => l.split("\t"));
+    return new Map(rows.filter(([name]) => names.includes(name ?? "")).map(([name, st]) => [name ?? "", st ?? ""]));
+  };
+  let firstHealthy: number | null = null;
+  let allHealthy: number | null = null;
+  const deadline = t0 + opts.timeoutSeconds * 1000;
+  while (performance.now() < deadline) {
+    const st = [...status().values()];
+    const healthyCount = st.filter((s) => s.includes("(healthy)") || (s.startsWith("Up") && !s.includes("health"))).length;
+    const elapsed = (performance.now() - t0) / 1000;
+    if (healthyCount > 0 && firstHealthy === null) firstHealthy = elapsed;
+    if (healthyCount === picked.length) {
+      allHealthy = elapsed;
+      break;
+    }
+    Bun.sleepSync(1000);
+  }
+  Bun.sleepSync(opts.settleSeconds * 1000);
+
+  const final = status();
+  const states = [...final.values()];
+  const crashes = [...final]
+    .filter(([name, st]) => /^(Exited|Restarting|Dead)/.test(st) || Number(shOk(`docker inspect ${name} --format '{{.RestartCount}}'`)) > 0)
+    .map(([name]) => {
+      const [exitCode, oom, restarts] = shOk(`docker inspect ${name} --format '{{.State.ExitCode}}|{{.State.OOMKilled}}|{{.RestartCount}}'`).split("|");
+      const lastLog = shOk(`docker logs --tail 3 ${name} 2>&1`).split("\n").filter(Boolean).pop() ?? "";
+      return { name: `${name} restarts=${restarts}`, exitCode: exitCode ?? "?", oom: oom === "true", lastLog: lastLog.slice(0, 160) };
+    });
+  const running = [...final].filter(([, st]) => st.startsWith("Up")).map(([name]) => name);
+  const stats = shOk(`docker stats --no-stream --format '{{.CPUPerc}} {{.MemUsage}}' ${running.join(" ")}`, 180_000)
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => l.split(/\s+/))
+    .map(([cpu, mem]) => ({ cpu: Number.parseFloat(cpu ?? "0"), mem: toMiB(mem ?? "0") }));
+  const totalMem = stats.reduce((a, x) => a + x.mem, 0);
+  const [, dockerPsMs] = timed(() => shOk("docker ps -q", 60_000));
+
+  const routed: Record<string, number> = {};
+  const latencies: number[] = [];
+  for (const name of running) {
+    const r = routeRequest(name);
+    const code = r?.code ?? "no-route";
+    routed[code] = (routed[code] ?? 0) + 1;
+    if (r && r.code === "200") latencies.push(r.ms);
+  }
+  latencies.sort((a, b) => a - b);
+
+  const result = {
+    tier: n,
+    launchSeconds: round(launchSeconds),
+    firstHealthySeconds: firstHealthy === null ? null : round(firstHealthy),
+    allHealthySeconds: allHealthy === null ? null : round(allHealthy),
+    healthy: states.filter((st) => st.includes("(healthy)")).length,
+    unhealthy: states.filter((st) => st.includes("(unhealthy)")).length,
+    starting: states.filter((st) => st.includes("health: starting")).length,
+    crashed: crashes.length,
+    oomKilled: crashes.filter((c) => c.oom).length,
+    crashes,
+    totalMemMiB: Math.round(totalMem),
+    avgMemMiB: stats.length ? round(totalMem / stats.length) : 0,
+    totalCpuPct: round(stats.reduce((a, x) => a + x.cpu, 0)),
+    dockerPsMs,
+    requestMsP50: latencies.length ? latencies[Math.floor(latencies.length / 2)] ?? null : null,
+    loadAvg1m: hostLoad(),
+    hostFreeMiB: hostFreeMiB(),
+    singleProcessShare: round(picked.filter((svc) => svc.singleProcess).length / picked.length),
+    routed,
+    restarts: crashes.length,
+  };
+  for (const [stack, svcs] of byStack) shOk(`docker compose ${composeArgs(opts.project, stack)} rm -sf ${svcs.join(" ")}`, 300_000);
+  return result;
+}
+
+function round(v: number): number {
+  return Math.round(v * 10) / 10;
+}
+
+function main(): void {
+  const opts = parseArgs();
+  const project = projectName(opts.project);
+  const network = `${project}_database`;
+  const dockerMemMiB = Math.round(Number(shOk("docker info --format '{{.MemTotal}}'")) / 1048576);
+  const hostMemGiB = Math.round(Number(shOk("sysctl -n hw.memsize")) / 1073741824);
+
+  if (shOk("pgrep -f 'tilt up'")) console.warn("⚠ Tilt is running - builds in the background will skew results.");
+  shOk(`docker network inspect ${network} || docker network create ${network}`);
+  const startedInfra = opts.mode === "compose" ? startInfra(project, opts.project) : [];
+  if (opts.mode === "synthetic") shOk(`docker start ${project}_postgres`);
+  const services = discoverServices(opts.project);
+  if (services.length === 0) {
+    console.error(`No built ERP images found for ${opts.project}. Run \`tdk up\` there once to build them.`);
+    process.exit(2);
+  }
+  const baselineContainers = shOk("docker ps -q").split("\n").filter(Boolean).length;
+  const singleShare = services.filter((s) => s.singleProcess).length / services.length;
+
+  // North star math: 100 services must fit in the Docker VM with ~512 MiB left for infra.
+  const imageSizes = (list: Service[]) => {
+    const sizes = list.map((s) => s.imageMiB).sort((a, b) => a - b);
+    return sizes.length ? { count: sizes.length, min: sizes[0], avg: Math.round(sizes.reduce((a, b) => a + b, 0) / sizes.length), max: sizes[sizes.length - 1] } : null;
+  };
+  const imageStats = {
+    backend: imageSizes(services.filter((s) => !s.isFrontend)),
+    frontend: imageSizes(services.filter((s) => s.isFrontend)),
+    backendSingleProcess: imageSizes(services.filter((s) => !s.isFrontend && s.singleProcess)),
+    backendWrapper: imageSizes(services.filter((s) => !s.isFrontend && !s.singleProcess)),
+  };
+  const diskUsage = shOk("docker system df --format '{{.Type}} {{.Size}}'").split("\n")[0] ?? "";
+  const perServiceBudgetMiB = Math.floor((dockerMemMiB - 512) / 100);
+  console.log(`Host ${hostMemGiB} GB, Docker VM ${dockerMemMiB} MiB, ${services.length} distinct ERP images (${Math.round(singleShare * 100)}% single-process CMD), ${baselineContainers} other containers running`);
+  console.log(`North star budget: (${dockerMemMiB} - 512 infra) / 100 = ${perServiceBudgetMiB} MiB per service`);
+  const fmt = (x: ReturnType<typeof imageSizes>) => (x ? `${x.count} × ${x.min}/${x.avg}/${x.max} MiB (min/avg/max)` : "none");
+  console.log(`Images - backend new layers: ${fmt(imageStats.backendSingleProcess)}, backend old layers: ${fmt(imageStats.backendWrapper)}, frontend: ${fmt(imageStats.frontend)}; Docker disk: ${diskUsage}`);
+  console.log(`Mode: ${opts.mode === "compose" ? "compose (generated compose files, real Postgres + Traefik, requests routed through Traefik)" : "synthetic (docker run, /health only)"}`);
+  console.log(`Healthcheck: interval ${opts.interval}s, start-interval ${opts.startInterval || "off"}\n`);
+
+  const results: TierResult[] = [];
+  for (const tier of opts.tiers) {
+    process.stdout.write(`▶ tier ${tier}... `);
+    const r = opts.mode === "compose" ? runTierCompose(tier, services, opts, project) : runTier(tier, services, opts, network, dbPassword(opts.project), project);
+    results.push(r);
+    const routed = "routed" in r ? ` | via Traefik: ${JSON.stringify(r.routed)}` : "";
+    console.log(`all healthy: ${r.allHealthySeconds ?? "NO"}s, crashed ${r.crashed}, mem ${r.totalMemMiB} MiB, docker ps ${r.dockerPsMs} ms${routed}`);
+  }
+
+  const header = "| tier | launch s | 1st healthy s | all healthy s | healthy | unhealthy | starting | crashed | OOM | mem MiB | avg MiB | CPU % | docker ps ms | req p50 ms | load 1m | host free MiB |";
+  const rows = results.map(
+    (r) =>
+      `| ${r.tier} | ${r.launchSeconds} | ${r.firstHealthySeconds ?? "-"} | ${r.allHealthySeconds ?? "TIMEOUT"} | ${r.healthy} | ${r.unhealthy} | ${r.starting} | ${r.crashed} | ${r.oomKilled} | ${r.totalMemMiB} | ${r.avgMemMiB} | ${r.totalCpuPct} | ${r.dockerPsMs} | ${r.requestMsP50 ?? "-"} | ${r.loadAvg1m} | ${r.hostFreeMiB} |`,
+  );
+  console.log(`\n${header}\n|${"---|".repeat(16)}\n${rows.join("\n")}`);
+  for (const r of results.filter((x) => x.crashes.length)) {
+    console.log(`\nCrashes at tier ${r.tier}:`);
+    for (const c of r.crashes.slice(0, 15)) console.log(`  - ${c.name} exit=${c.exitCode}${c.oom ? " OOMKilled" : ""} :: ${c.lastLog}`);
+  }
+
+  const gate = results.find((r) => r.tier === opts.gate);
+  const checks = gate
+    ? [
+        [`all ${gate.tier} healthy within ${opts.timeoutSeconds}s`, gate.allHealthySeconds !== null],
+        ["no crashes / OOM kills", gate.crashed === 0],
+        [`memory ${gate.totalMemMiB} MiB <= ${perServiceBudgetMiB * gate.tier} MiB budget`, gate.totalMemMiB <= perServiceBudgetMiB * gate.tier],
+        [`docker ps ${gate.dockerPsMs} ms < 10000 ms (tdk doctor timeout)`, gate.dockerPsMs < 10_000],
+      ]
+    : [];
+  if (gate && "routed" in gate) {
+    const routed = gate.routed as Record<string, number>;
+    const total = Object.values(routed).reduce((a, b) => a + b, 0);
+    checks.push([`requests through Traefik: ${routed["200"] ?? 0}/${total} returned 200`, (routed["200"] ?? 0) === total]);
+  }
+  const smallest = results[0];
+  console.log(`\nWebsite promise "full boot in under 5 seconds": tier ${smallest?.tier} all healthy in ${smallest?.allHealthySeconds ?? "TIMEOUT"}s (info only)`);
+  console.log(`Gate (tier ${opts.gate}):`);
+  for (const [label, ok] of checks) console.log(`  ${ok ? "✓" : "✗"} ${label}`);
+  const passed = checks.length > 0 && checks.every(([, ok]) => ok);
+  for (const container of startedInfra) shOk(`docker stop ${container}`);
+
+  const outDir = join(REPO_ROOT, "benchmarks", "results");
+  mkdirSync(outDir, { recursive: true });
+  const outFile = join(outDir, `container-scale-${new Date().toISOString().replace(/[:.]/g, "-")}.json`);
+  writeFileSync(
+    outFile,
+    JSON.stringify({ date: new Date().toISOString(), hostMemGiB, dockerMemMiB, perServiceBudgetMiB, options: { ...opts, project: relative(REPO_ROOT, opts.project) }, images: services.length, imageStats, diskUsage, singleProcessImageShare: singleShare, results, gate: { tier: opts.gate, passed } }, null, 2),
+  );
+  console.log(`\n${passed ? "PASS" : "FAIL"} - results saved to ${outFile}`);
+  process.exit(passed ? 0 : 1);
+}
+
+main();

package/scripts/benchmark/pre-release-gate.sh

@@ -0,0 +1,9 @@
+#!/usr/bin/env bash
+# Opt-in container scale gate for git hooks. No-op unless TDK_BENCH_GATE=1.
+#   TDK_BENCH_GATE=1 git push            # run full gate (tiers up to 100)
+#   TDK_BENCH_GATE=1 TDK_BENCH_TIERS=5,10,20 git commit ...
+set -euo pipefail
+[ "${TDK_BENCH_GATE:-0}" = "1" ] || exit 0
+cd "$(dirname "$0")/../.."
+tiers="${TDK_BENCH_TIERS:-5,10,20,50,80,100}"
+exec bun scripts/benchmark/container-scale.ts --tiers "$tiers" --gate "${tiers##*,}"

package/scripts/measure-idle-footprint.sh

@@ -0,0 +1,58 @@
+#!/usr/bin/env bash
+# Checks an idle generated backend container against the runtime footprint budget
+# (openspec: runtime-container-footprint): one Bun process, <= 64 MiB, < 2% CPU.
+#
+# Usage: scripts/measure-idle-footprint.sh <container> [sample_seconds]
+set -euo pipefail
+
+container="${1:?usage: $0 <container> [sample_seconds]}"
+sample_seconds="${2:-60}"
+max_mem_mib="${MAX_MEM_MIB:-64}"
+max_cpu_pct="${MAX_CPU_PCT:-2}"
+
+echo "Waiting for ${container} to be healthy..."
+for _ in $(seq 1 90); do
+  health="$(docker inspect --format '{{if .State.Health}}{{.State.Health.Status}}{{else}}none{{end}}' "$container")"
+  [ "$health" = "healthy" ] || [ "$health" = "none" ] && break
+  sleep 2
+done
+if [ "$health" != "healthy" ] && [ "$health" != "none" ]; then
+  echo "FAIL: ${container} is ${health}, not healthy" >&2
+  exit 1
+fi
+
+bun_processes="$(docker top "$container" -o args | tail -n +2 | grep -c '^bun ' || true)"
+echo "Bun processes: ${bun_processes}"
+docker top "$container" -o pid,rss,args | sed 's/^/  /'
+
+to_mib() {
+  awk -v v="$1" 'BEGIN {
+    n = v + 0
+    if (v ~ /GiB$/) n *= 1024
+    else if (v ~ /KiB$/) n /= 1024
+    else if (v ~ /[0-9]B$/) n /= 1048576
+    printf "%.2f", n
+  }'
+}
+
+samples=0 cpu_total=0 mem_peak=0
+end=$((SECONDS + sample_seconds))
+while [ "$SECONDS" -lt "$end" ]; do
+  line="$(docker stats --no-stream --format '{{.CPUPerc}} {{.MemUsage}}' "$container")"
+  cpu="${line%%\%*}"
+  mem="$(to_mib "$(echo "$line" | awk '{print $2}')")"
+  cpu_total="$(awk -v a="$cpu_total" -v b="$cpu" 'BEGIN { printf "%.4f", a + b }')"
+  mem_peak="$(awk -v a="$mem_peak" -v b="$mem" 'BEGIN { print (b > a ? b : a) }')"
+  samples=$((samples + 1))
+  sleep 5
+done
+cpu_avg="$(awk -v t="$cpu_total" -v n="$samples" 'BEGIN { printf "%.2f", t / n }')"
+
+echo "Samples: ${samples} over ${sample_seconds}s | peak memory: ${mem_peak} MiB (max ${max_mem_mib}) | avg CPU: ${cpu_avg}% (max <${max_cpu_pct}%)"
+
+failed=0
+[ "$bun_processes" -eq 1 ] || { echo "FAIL: expected 1 Bun process, found ${bun_processes}" >&2; failed=1; }
+awk -v m="$mem_peak" -v max="$max_mem_mib" 'BEGIN { exit !(m <= max) }' || { echo "FAIL: memory over budget" >&2; failed=1; }
+awk -v c="$cpu_avg" -v max="$max_cpu_pct" 'BEGIN { exit !(c < max) }' || { echo "FAIL: CPU over budget" >&2; failed=1; }
+[ "$failed" -eq 0 ] && echo "PASS: ${container} is within the idle footprint budget"
+exit "$failed"