okengine 0.17.2 → 0.18.3

package/src/bench/load-app.ts

@@ -0,0 +1,337 @@
+/**
+ * Bench load app — one real app process exposing every bench route needed
+ * by G1–G15. Modeled on `src/kernel/horizontal-child.ts`.
+ *
+ * Env (resolved at runtime, never printed):
+ *   DATABASE_URL / OKE_STORE_SQL_URL — live Postgres via pgdog
+ *   OKE_TEST_REDIS_URL or REDIS_URL  — live Redis
+ *   OKE_BENCH_MAILPIT_HOST / _PORT   — Mailpit for channel bulk (default 127.0.0.1:1025)
+ *
+ * Routes:
+ *   GET  /_/ready              { ok, pid }
+ *   GET  /_/stats              uptime, rss, counters
+ *   GET  /ping                 plain public flow
+ *   GET  /rate                 gate.rate-limited (keyBy ip)
+ *   POST /_/bench/rls          mixed-identity store writes through shared conn
+ *   POST /_/bench/rate         gate.rate-limited POST variant
+ *   POST /_/bench/emit         signal once emit
+ *   POST /_/bench/drain        signal bus drain
+ *   GET  /_oke/live/bench-live live SSE delivery (auto route via http.live)
+ *   POST /_/bench/durable      durable flow with fx.step
+ *   POST /_/bench/vault-read   vault runtime read
+ *   POST /_/bench/stream       fx.json.stream SSE response
+ *   POST /_/bench/channel-bulk channel RetryTransport bulk send → Mailpit
+ */
+
+import { openSmtpChannel } from "../drivers/channel-smtp.ts";
+import { createPostgresCronStore } from "../drivers/clock-postgres.ts";
+import { createPostgresJournalStore } from "../drivers/journal-postgres.ts";
+import { memorySignalDriver } from "../drivers/signal-memory.ts";
+import { postgresDriver } from "../drivers/postgres.ts";
+import { redisDriver } from "../drivers/redis.ts";
+import { channel } from "../elements/channel.ts";
+import { createChannelRuntime, type TemplateCatalog } from "../elements/channel/runtime.ts";
+import { clock } from "../elements/clock/declare.ts";
+import { createClockRuntime } from "../elements/clock/runtime.ts";
+import { gate } from "../elements/gate.ts";
+import { createGateRuntime } from "../elements/gate/runtime.ts";
+import { signal } from "../elements/signal/declare.ts";
+import { createSignalRuntime } from "../elements/signal/runtime.ts";
+import { sql } from "../elements/store/declare.ts";
+import { createStoreRuntime } from "../elements/store/runtime.ts";
+import { defineTable } from "../elements/store/table.ts";
+import { vault } from "../elements/vault/declare.ts";
+import { createVaultRuntime } from "../elements/vault/runtime.ts";
+import { GATE_KV_NAMESPACE } from "../kernel/boot-bind/gate.ts";
+import { oke } from "../kernel/app.ts";
+import { flow, type AnyFlowDef } from "../kernel/flow.ts";
+import type { Binding } from "../kernel/on.ts";
+import { http } from "../kernel/triggers.ts";
+import { installGracefulShutdown } from "../kernel/graceful-shutdown.ts";
+import { okid } from "../okid.ts";
+import { createBunRuntime } from "../runtime/bun.ts";
+
+const mode = process.argv[2];
+if (mode !== "serve") {
+  console.error("usage: load-app serve <instanceId> <port>");
+  process.exit(2);
+}
+
+const instanceId = process.argv[3] ?? "bench-a";
+const port = Number(process.argv[4] ?? "0");
+
+const pgUrl = process.env.DATABASE_URL?.trim() || process.env.OKE_STORE_SQL_URL?.trim() || "";
+const redisUrl = (process.env.OKE_TEST_REDIS_URL ?? process.env.REDIS_URL)?.trim() ?? "";
+if (!pgUrl || !redisUrl) {
+  console.error("load-app: DATABASE_URL and OKE_TEST_REDIS_URL (or REDIS_URL) are required");
+  process.exit(2);
+}
+
+const t0 = Date.now();
+const counters = { rls: 0, emits: 0, drains: 0, durable: 0, vaultReads: 0, streams: 0, mails: 0 };
+
+// --- Clock (perTenant cron declared for G2/G6) ------------------------------
+const cronStore = await createPostgresCronStore({ url: pgUrl });
+const CRON = "bench-cron";
+const benchClock = clock(CRON, { every: "1h", perTenant: true });
+const clockRt = createClockRuntime({ store: cronStore, instanceId, leaseMs: 300 });
+clockRt.register(benchClock);
+await clockRt.reconcile();
+clockRt.onCron(CRON, async () => {});
+
+// --- Signal (once + live physics) -------------------------------------------
+const signalPath = `/tmp/oke-bench-signal-${process.pid}.json`;
+const BENCH_JOB = signal("bench-job", {
+  delivery: "once",
+  retries: 3,
+  deadLetter: true,
+  optional: true,
+});
+const BENCH_LIVE = signal("bench-live", {
+  delivery: "live",
+  retention: { maxCount: 100 },
+});
+const signalRt = createSignalRuntime({
+  driver: memorySignalDriver,
+  durablePath: signalPath,
+  leaseMs: 300,
+});
+signalRt.register(BENCH_JOB as never);
+signalRt.register(BENCH_LIVE as never);
+const bus = await signalRt.start();
+await bus.subscribe(BENCH_JOB.name, `consumer-${instanceId}`, async () => {});
+
+// --- Gate --------------------------------------------------------------------
+const rateGate = gate.rate({ max: 1000, per: "1m", keyBy: "ip" });
+const kv = await redisDriver.open({
+  name: GATE_KV_NAMESPACE,
+  url: redisUrl,
+  nowMs: () => Date.now(),
+});
+const gateRt = createGateRuntime({
+  gates: [rateGate, gate.public],
+  kv,
+  now: () => Date.now(),
+});
+
+// --- Store -------------------------------------------------------------------
+const db = sql("db");
+const benchTable = defineTable("oke_bench_rows", {
+  id: true,
+  tenant_id: true,
+  instance_id: true,
+  at: true,
+});
+const journalStore = await createPostgresJournalStore({ url: pgUrl });
+await journalStore.sql.exec(`
+  CREATE TABLE IF NOT EXISTS oke_bench_rows (
+    id TEXT PRIMARY KEY,
+    tenant_id TEXT NOT NULL,
+    instance_id TEXT NOT NULL,
+    at BIGINT NOT NULL
+  )
+`);
+const storeRt = createStoreRuntime({
+  drivers: { sql: postgresDriver },
+  sql: { db: { name: "db", primary: { url: pgUrl } } },
+  now: () => Date.now(),
+});
+storeRt.register(db);
+
+// --- Vault -------------------------------------------------------------------
+const VAULT_SECRET = "OKE_BENCH_SECRET";
+const vaultRt = createVaultRuntime({
+  secrets: [vault.config(VAULT_SECRET, { dev: "bench-value" })],
+  allowDevFallbacks: true,
+});
+await vaultRt.boot();
+
+// --- Channel (Mailpit SMTP + RetryTransport) ----------------------------------
+const mailHost = process.env.OKE_BENCH_MAILPIT_HOST?.trim() || "127.0.0.1";
+const mailPort = Number(process.env.OKE_BENCH_MAILPIT_PORT ?? "1025");
+const WELCOME = channel.email().template("bench-welcome");
+const catalog: TemplateCatalog = {
+  "bench-welcome": { en: { subject: "Bench welcome", text: "Hello bench" } },
+};
+let channelRt: ReturnType<typeof createChannelRuntime> | undefined;
+try {
+  channelRt = createChannelRuntime({
+    templates: [WELCOME],
+    drivers: [openSmtpChannel({ host: mailHost, port: mailPort })],
+    catalog,
+    retry: true,
+    now: () => Date.now(),
+  });
+} catch (err) {
+  console.error("load-app: channel disabled", err);
+}
+
+// --- Flows ---------------------------------------------------------------------
+const ping = flow("bench.ping", { do: () => ({ ok: true as const }) });
+
+const statsFlow = flow("bench.stats", { do: () => benchStats() });
+
+const liveFirehose = flow("bench.live-firehose", {
+  do: (_input, fx) => fx.live(BENCH_LIVE),
+});
+
+const rlsWrite = flow("bench.rls", {
+  do: async (input, fx) => {
+    const body = input as { tenantId?: string; n?: number };
+    const n = Math.max(1, Math.min(64, Number(body.n ?? 1)));
+    for (let i = 0; i < n; i++) {
+      await fx
+        .store(db)
+        .insert(benchTable)
+        .values({
+          id: okid(),
+          tenant_id: body.tenantId ?? `tenant-${i}`,
+          instance_id: instanceId,
+          at: Date.now(),
+        })
+        .execute();
+    }
+    counters.rls += n;
+    return { written: n };
+  },
+});
+
+const rateFlow = flow("bench.rate", { do: () => ({ ok: true as const }) });
+
+const emit = flow("bench.emit", {
+  do: async (_input, fx) => {
+    await fx.emit(BENCH_JOB, { from: instanceId, at: Date.now() });
+    counters.emits++;
+    return { emitted: true as const };
+  },
+});
+
+const emitLive = flow("bench.emit-live", {
+  do: async (_input, fx) => {
+    await fx.emit(BENCH_LIVE, { from: instanceId, at: Date.now() });
+    counters.emits++;
+    return { emitted: true as const };
+  },
+});
+
+const drainFlow = flow("bench.drain", {
+  do: async () => {
+    await bus.drain();
+    counters.drains++;
+    return { drained: true as const };
+  },
+});
+
+const durableFlow = flow("bench.durable", {
+  durable: true,
+  do: async (_input, fx) => {
+    await fx.step("step-one", async () => ({ at: Date.now() }));
+    await fx.step("step-two", async () => "done");
+    counters.durable++;
+    return { ok: true as const };
+  },
+});
+
+const vaultRead = flow("bench.vault-read", {
+  do: async (_input, fx) => {
+    const value = await fx.vault.get(VAULT_SECRET);
+    counters.vaultReads++;
+    return { len: String(value).length };
+  },
+});
+
+const streamN = flow("bench.stream", {
+  do: async (input, fx) => {
+    const chunks = Number((input as { chunks?: number }).chunks ?? 16);
+    counters.streams++;
+    return fx.json.stream(
+      (async function* () {
+        for (let i = 0; i < chunks; i++) yield { i, at: Date.now() };
+      })(),
+    );
+  },
+});
+
+const channelBulk = flow("bench.channel-bulk", {
+  do: async (input) => {
+    if (!channelRt) throw new Error("channel runtime unavailable (Mailpit down?)");
+    const count = Math.max(1, Math.min(500, Number((input as { count?: number }).count ?? 10)));
+    let sent = 0;
+    for (let i = 0; i < count; i++) {
+      const r = await channelRt.send(WELCOME.name, {
+        to: `bench-${okid()}@example.test`,
+        data: { i },
+      });
+      if (r.ok) sent++;
+    }
+    counters.mails += sent;
+    return { sent };
+  },
+});
+
+const bindings: Binding[] = [
+  { trigger: http.get("/ping").public(), flow: ping as AnyFlowDef },
+  { trigger: http.get("/_/stats").public(), flow: statsFlow as AnyFlowDef },
+  { trigger: http.get("/rate").gate(rateGate), flow: rateFlow as AnyFlowDef },
+  { trigger: http.post("/_/bench/rate").gate(rateGate), flow: rateFlow as AnyFlowDef },
+  { trigger: http.post("/_/bench/rls").public(), flow: rlsWrite as AnyFlowDef },
+  { trigger: http.post("/_/bench/emit").public(), flow: emit as AnyFlowDef },
+  { trigger: http.post("/_/bench/emit-live").public(), flow: emitLive as AnyFlowDef },
+  { trigger: http.post("/_/bench/drain").public(), flow: drainFlow as AnyFlowDef },
+  { trigger: http.live(BENCH_LIVE).public(), flow: liveFirehose as AnyFlowDef },
+  { trigger: http.post("/_/bench/durable").public(), flow: durableFlow as AnyFlowDef },
+  { trigger: http.post("/_/bench/vault-read").public(), flow: vaultRead as AnyFlowDef },
+  { trigger: http.post("/_/bench/stream").public(), flow: streamN as AnyFlowDef },
+  { trigger: http.post("/_/bench/channel-bulk").public(), flow: channelBulk as AnyFlowDef },
+];
+
+const app = oke({
+  name: `bench-load-${instanceId}`,
+  env: "test",
+  startScheduler: false,
+  gate: { unguardedHttp: "allow", policies: [rateGate, gate.public] },
+  journalLeaseMs: 300,
+  bindings,
+  clocks: [benchClock],
+  signals: [BENCH_JOB as never, BENCH_LIVE as never],
+  stores: [db],
+  elements: {
+    clock: clockRt,
+    signal: signalRt,
+    gate: gateRt,
+    store: storeRt,
+    journal: { store: journalStore, instanceId, leaseMs: 300, driverId: "postgres" },
+  },
+});
+
+await app.boot();
+
+void (async () => {
+  for (;;) {
+    try {
+      await clockRt.tick();
+      await bus.drain();
+      await app.resumeDurable();
+    } catch (err) {
+      console.error("load-app tick error", err);
+    }
+    await Bun.sleep(20);
+  }
+})();
+
+const handle = createBunRuntime().serve(app, { port, hostname: "127.0.0.1" });
+installGracefulShutdown({ app, handle, exit: true });
+
+export function benchStats(): Record<string, unknown> {
+  return {
+    pid: process.pid,
+    uptimeS: Math.round((Date.now() - t0) / 1000),
+    rssMb: Math.round(process.memoryUsage.rss() / 1024 / 1024),
+    counters,
+  };
+}
+
+console.log(JSON.stringify({ ready: true, pid: process.pid, port: handle.port, instanceId }));
+
+// Keep alive
+await new Promise(() => {});

package/src/bench/load-child.ts

@@ -0,0 +1,108 @@
+/**
+ * Bench multi-mode entrypoint — argument/usage style of
+ * `src/kernel/horizontal-child.ts`.
+ *
+ * Modes:
+ *   serve <port>                       boot the bench load app on 127.0.0.1:<port>;
+ *                                      prints a ready line `{ready:true,pid,port}` to stdout.
+ *   flood-sse <url> <signal> <count>   open N SSE connections to the live route and hold them.
+ *   sustained <url> <concurrency> <durationS> [path]
+ *                                      closed-loop HTTP loop against <url><path>.
+ *   shutdown-test                      install graceful shutdown; drain on SIGTERM, exit 0.
+ *
+ * Env: DATABASE_URL + OKE_TEST_REDIS_URL (or REDIS_URL) required by serve.
+ */
+
+import { installGracefulShutdown } from "../kernel/graceful-shutdown.ts";
+
+const mode = process.argv[2];
+
+function usage(): never {
+  console.error(
+    [
+      "usage: load-child serve <port>",
+      "       load-child flood-sse <url> <signal> <count>",
+      "       load-child sustained <url> <concurrency> <durationS> [path]",
+      "       load-child shutdown-test",
+    ].join("\n"),
+  );
+  process.exit(2);
+}
+
+if (!mode) usage();
+
+if (mode === "serve") {
+  // Delegate entirely to load-app.ts so this file stays a thin dispatcher.
+  const portArg = Number(process.argv[3] ?? "0");
+  if (!Number.isFinite(portArg) || portArg < 0) usage();
+  process.argv = [process.argv[0]!, process.argv[1]!, "serve", "bench-a", String(portArg)];
+  await import("./load-app.ts");
+} else if (mode === "flood-sse") {
+  const url = process.argv[3];
+  const sig = process.argv[4] ?? "bench-live";
+  const count = Number(process.argv[5] ?? "100");
+  if (!url) usage();
+  const target = `${url}/_oke/live/${encodeURIComponent(sig)}`;
+  console.log(JSON.stringify({ mode, target, count }));
+  const controllers: AbortController[] = [];
+  const opened = new Set<number>();
+  await Promise.all(
+    Array.from({ length: count }, (_, i) =>
+      (async () => {
+        const ac = new AbortController();
+        controllers.push(ac);
+        try {
+          const res = await fetch(target, { signal: ac.signal });
+          if (res.body) {
+            opened.add(i);
+            const reader = res.body.getReader();
+            // Hold the connection open, discarding frames.
+            for (;;) {
+              const { done } = await reader.read();
+              if (done) break;
+            }
+          }
+        } catch {
+          /* aborted / conn reset — expected during teardown */
+        }
+      })(),
+    ),
+  );
+  // Only reachable if every connection closed on its own.
+  console.log(JSON.stringify({ floodDone: true, opened: opened.size }));
+} else if (mode === "sustained") {
+  const base = process.argv[3];
+  const concurrency = Number(process.argv[4] ?? "50");
+  const durationS = Number(process.argv[5] ?? "60");
+  const path = process.argv[6] ?? "/ping";
+  if (!base) usage();
+  const target = `${base}${path}`;
+  const deadline = Date.now() + durationS * 1000;
+  let requests = 0;
+  let errors = 0;
+  console.log(JSON.stringify({ mode, target, concurrency, durationS }));
+  await Promise.all(
+    Array.from({ length: concurrency }, async () => {
+      while (Date.now() < deadline) {
+        try {
+          const res = await fetch(target, { method: path.includes("ping") ? "GET" : "POST" });
+          await res.arrayBuffer();
+          if (!res.ok) errors++;
+        } catch {
+          errors++;
+        }
+        requests++;
+      }
+    }),
+  );
+  console.log(JSON.stringify({ sustainedDone: true, requests, errors }));
+} else if (mode === "shutdown-test") {
+  // Minimal app stub — shutdown-test measures signal handling + exit path,
+  // not lease release (no boot result exists in this mode).
+  installGracefulShutdown({ app: {} as never, exit: true });
+  console.log(JSON.stringify({ ready: true, pid: process.pid, mode: "shutdown-test" }));
+  // Hold until SIGTERM/SIGINT; the installed handler drains and exits 0.
+  await new Promise(() => {});
+} else {
+  usage();
+}

package/src/bench/smoke.bench.ts

@@ -0,0 +1,43 @@
+/**
+ * Bench harness smoke — validates the report/sampler/lag libs and gives
+ * `bun run bench:load` a runnable target before group benches land.
+ * Runs everywhere (no live infra required).
+ */
+
+import { describe, expect, test } from "bun:test";
+import { measureEventLoopLag } from "./lib/event-loop-lag.ts";
+import { percentile, summarize, DISCLAIMER, HARDWARE } from "./lib/report.ts";
+import { rssSlopeMbPerMin, type RssSample } from "./lib/rss-sampler.ts";
+
+describe("bench harness smoke", () => {
+  test("percentile + summarize", () => {
+    expect(percentile([1, 2, 3, 4, 5], 50)).toBe(3);
+    expect(percentile([], 50)).toBeNaN();
+    const s = summarize([10, 20, 30]);
+    expect(s.opsPerSec).toBeGreaterThan(0);
+    expect(s.p99Ms).toBeGreaterThanOrEqual(s.p50Ms);
+  });
+
+  test("rss slope on synthetic samples", () => {
+    const samples: RssSample[] = Array.from({ length: 6 }, (_, i) => ({
+      tMs: i * 5000,
+      rssMb: 100 + i * 10,
+      fds: 20,
+    }));
+    // 10 MB per 5 s = 120 MB/min.
+    expect(rssSlopeMbPerMin(samples)).toBeCloseTo(120, -1);
+    expect(rssSlopeMbPerMin([])).toBe(0);
+  });
+
+  test("event loop lag probe collects samples", async () => {
+    const probe = measureEventLoopLag(25);
+    await Bun.sleep(120);
+    probe.stop();
+    expect(probe.lags().length).toBeGreaterThan(1);
+  });
+
+  test("artifact constants", () => {
+    expect(HARDWARE).toContain("M4");
+    expect(DISCLAIMER).toContain("not SLA");
+  });
+});

package/src/cli/competitor-mention-removal.test.ts

@@ -27,10 +27,30 @@ const FORBIDDEN_III_DEV = ["iii", ".", "dev"].join("");
 const FORBIDDEN_COMPARISON_PATH = ["get-started/", "comparison"].join("");
 /** Word-boundary classic Node framework — `-F` false-positives on `CallExpression`. */
 const FORBIDDEN_EXPRESS = ["\\b", "Ex", "press", "\\b"].join("");
+/** Compact-ID peer library (okid design context stays first-principles). */
+const FORBIDDEN_NANOID = ["na", "no", "id"].join("");
+/** Collision-resistant-ID peer library (same rule). */
+const FORBIDDEN_CUID = ["cu", "id2"].join("");
 
 /** Decoy `X-Powered-By` fixture value in the headers plugin tests. */
 const EXPRESS_ALLOW = ["src/plugins/headers.test.ts:"];
 
+/**
+ * Allow-listed paths where peer-name strings are sanctioned: the okid design
+ * prompt, lockfile hashes, and the vendored Console dist bundle (Zod ships
+ * string-format validators whose registered format names collide with peer
+ * library names inside minified zod-core — vendor API identifiers, not
+ * authored comparisons).
+ */
+const OKID_PROMPT_ALLOW = [
+  "okid.md:",
+  "bun.lock:",
+  // Minified zod-core inside the vendored Console bundle registers string
+  // format validators whose names collide with peer library names — vendor
+  // identifiers, not authored comparisons. Hash changes on Console rebuilds.
+  "src/console/ui-next/dist/assets/index-DSEpMBPY.js:",
+];
+
 /**
  * Run `git grep -F` and assert zero matches after ignoring allow-listed paths.
  *
@@ -114,4 +134,12 @@ describe("named competitor mention removal gate", () => {
   test("tracked tree has zero classic Node framework peer mentions outside decoy fixture", () => {
     assertZeroGitGrepRegex(FORBIDDEN_EXPRESS, EXPRESS_ALLOW);
   });
+
+  test("tracked tree has zero compact-ID peer library mentions outside design prompt", () => {
+    assertZeroGitGrepFixed(FORBIDDEN_NANOID, OKID_PROMPT_ALLOW);
+  });
+
+  test("tracked tree has zero collision-resistant-ID peer library mentions outside design prompt", () => {
+    assertZeroGitGrepFixed(FORBIDDEN_CUID, OKID_PROMPT_ALLOW);
+  });
 });

package/src/cli/doctor-fd.ts

@@ -0,0 +1,117 @@
+/**
+ * `oke doctor` file-descriptor headroom probe.
+ *
+ * A live-SSE app holds one fd per open subscriber stream; a low `ulimit -n`
+ * soft limit collapses under load long before CPU or memory do. Doctor
+ * estimates peak concurrent fds from the manifest and compares against the
+ * process soft limit.
+ */
+
+import { spawnSync } from "node:child_process";
+import type { Manifest } from "../manifest/types.ts";
+
+/** Conservative fallback when the soft limit cannot be read. */
+const DEFAULT_SOFT_FD_LIMIT = 256;
+
+/** Baseline fds every runtime needs (stdin/out/err, event loop, listeners). */
+const BASE_FDS = 64;
+
+/** Expected concurrent subscribers per live signal / SSE route. */
+const EXPECTED_SUBSCRIBERS_PER_LIVE = 64;
+
+/**
+ * Measured server-side fd cost per open SSE subscriber.
+ *
+ * Calibrated by the G3b bench (`src/bench/g03-signal-sse-memory.bench.ts`):
+ * 1.53 fds/subscriber observed on macOS/Bun across a 100→500 subscriber
+ * scale-up. The original formula implicitly budgeted 64 fds/subscriber —
+ * off by >20% against this measurement. Remaining conservatism lives in
+ * `BASE_FDS` / `HTTP_CONCURRENCY`, not here.
+ */
+export const FD_COST_PER_SUBSCRIBER: number = 1.5;
+
+/** Pool connections per SQL driver. */
+const SQL_CONNECTIONS = 2;
+
+/** Connections held by Redis-style KV drivers. */
+const KV_CONNECTIONS = 2;
+
+/** Concurrent in-flight HTTP requests to budget for. */
+const HTTP_CONCURRENCY = 128;
+
+/**
+ * Read the current soft `NOFILE` limit for this process.
+ *
+ * Prefers `process.getrlimit` when Bun exposes it; falls back to spawning
+ * `sh -c 'ulimit -n'` (which reports the shell's own limit, a close proxy).
+ * Returns `null` when neither path works — callers treat that as the
+ * conservative {@link DEFAULT_SOFT_FD_LIMIT}.
+ */
+export function getSoftFdLimit(): number | null {
+  const proc = process as typeof process & {
+    getrlimit?: (name: string) => { readonly soft: number; readonly hard: number };
+  };
+  if (typeof proc.getrlimit === "function") {
+    try {
+      const rl = proc.getrlimit("NOFILE");
+      if (rl && Number.isFinite(rl.soft)) return rl.soft;
+    } catch {
+      // fall through to shell
+    }
+  }
+  try {
+    const out = spawnSync("sh", ["-c", "ulimit -n"], { encoding: "utf8" });
+    const parsed = Number.parseInt(out.stdout?.trim() ?? "", 10);
+    if (Number.isFinite(parsed) && parsed > 0) return parsed;
+  } catch {
+    // unreadable — caller falls back
+  }
+  return null;
+}
+
+/**
+ * Estimate peak concurrent file descriptors from a manifest.
+ *
+ * Budgets base runtime fds, expected live-signal subscribers (`signals`
+ * with `delivery === "live"` plus flows with an http trigger and `live`),
+ * pool connections, and HTTP concurrency. Without a manifest, returns a
+ * conservative baseline only.
+ *
+ * @param manifest - Loaded manifest, or `null` when none was found.
+ */
+export function estimatePeakFds(manifest: Manifest | null): number {
+  let need = BASE_FDS + SQL_CONNECTIONS + KV_CONNECTIONS + HTTP_CONCURRENCY;
+  if (!manifest) return need;
+  const liveSignals = Object.values(manifest.signals ?? {}).filter(
+    (signal) => signal.delivery === "live",
+  ).length;
+  const sseRoutes = Object.values(manifest.flows ?? {}).filter((flow) => {
+    if (!flow.live) return false;
+    const trigger = flow.trigger?.http;
+    return (
+      trigger !== undefined &&
+      (trigger.method === "GET" || trigger.method === "HEAD" || trigger.method === "QUERY")
+    );
+  }).length;
+  // Live subscribers are the dominant term; budget the busiest signal/route
+  // at the expected concurrency times the measured per-subscriber fd cost.
+  need += Math.max(liveSignals, sseRoutes) * EXPECTED_SUBSCRIBERS_PER_LIVE * FD_COST_PER_SUBSCRIBER;
+  return need;
+}
+
+/**
+ * Compare the estimated peak fd need against the soft limit.
+ *
+ * @param manifest - Loaded manifest, or `null` when none was found.
+ */
+export function checkFileDescriptorHeadroom(manifest: Manifest | null): {
+  ok: boolean;
+  softLimit: number;
+  estimatedNeed: number;
+  headroom: number;
+} {
+  const softLimit = getSoftFdLimit() ?? DEFAULT_SOFT_FD_LIMIT;
+  const estimatedNeed = estimatePeakFds(manifest);
+  const headroom = softLimit - estimatedNeed;
+  return { ok: headroom >= 0, softLimit, estimatedNeed, headroom };
+}