okengine 0.17.2 → 0.18.4

package/src/bench/g16-live-query-fanout.bench.ts

@@ -0,0 +1,206 @@
+/**
+ * G16 — Live query fan-out (subscribers × stamped EXISTS).
+ *
+ * Characterizes the Realtime capability's honest cost model:
+ *   cost_per_event ≈ active_subscriptions × (stamp_prelude + point_lookup)
+ *
+ * Sweeps subscriber counts on one shared PGlite connection (serialized stamp
+ * queue — G1 physics). Each CDC event fans out a stamped EXISTS probe per
+ * subscriber; wall-clock and per-event p50/p99 are recorded.
+ *
+ * Run: bun test src/bench/g16-live-query-fanout.bench.ts --timeout 120000
+ * Env: OKE_BENCH=1 (PGlite). OKE_BENCH_CAL=1 shrinks N for a calibration pass.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { connectPglite } from "../drivers/pglite.ts";
+import { installOkeRlsHelpers, type RlsIdentity } from "../drivers/pg-rls.ts";
+import type { SqlConnection } from "../drivers/types.ts";
+import {
+  LiveQueryRuntime,
+  type LiveQueryEvent,
+  type LiveSubscription,
+} from "../elements/store/live-query-runtime.ts";
+import { liveQueryRuntimeFromConn } from "../elements/store/live-query-server.ts";
+import { DISCLAIMER, HARDWARE, percentile, writeArtifact } from "./lib/report.ts";
+
+const CAL = process.env.OKE_BENCH_CAL === "1";
+/** Subscriber counts per sweep point. */
+const SUBSCRIBERS = CAL ? [10, 50] : [10, 50, 100, 200];
+/** CDC events fired per point (each fans out to every subscriber). */
+const EVENTS = CAL ? 5 : 20;
+/** Settle wait after the last event (ms). */
+const SETTLE_MS = 2_000;
+
+const NOTES_DDL = `CREATE TABLE notes (
+  id text PRIMARY KEY,
+  owner text NOT NULL,
+  body text NOT NULL
+)`;
+
+const OWNER_POLICY = `CREATE POLICY owner_select ON notes
+  AS PERMISSIVE FOR SELECT TO public
+  USING (owner = oke.user())`;
+
+let conn: SqlConnection;
+let runtime: LiveQueryRuntime;
+
+beforeAll(async () => {
+  conn = await connectPglite({ url: "memory://bench-g16-live-fanout", role: "primary" });
+  await conn.exec(NOTES_DDL);
+  await conn.exec(`INSERT INTO notes VALUES ('n1', 'alice', 'hi'), ('n2', 'bob', 'yo')`);
+  await conn.exec(`ALTER TABLE notes ENABLE ROW LEVEL SECURITY`);
+  await installOkeRlsHelpers((sql) => conn.exec(sql));
+  await conn.exec(OWNER_POLICY);
+  runtime = liveQueryRuntimeFromConn(conn);
+}, 15_000);
+
+afterAll(async () => {
+  await conn.close();
+});
+
+interface PointResult {
+  readonly subscribers: number;
+  readonly events: number;
+  readonly delivered: number;
+  readonly wallMs: number;
+  readonly p50MsPerEvent: number;
+  readonly p99MsPerEvent: number;
+  readonly eventsPerSec: number;
+  readonly shed: number;
+}
+
+function aliceIdentity(_i: number): RlsIdentity {
+  return { gate: "member", userId: "alice", scopes: ["member"] };
+}
+
+function waitFor(pred: () => boolean, timeoutMs: number): Promise<boolean> {
+  const start = Date.now();
+  return new Promise((resolve) => {
+    const tick = (): void => {
+      if (pred()) {
+        resolve(true);
+        return;
+      }
+      if (Date.now() - start > timeoutMs) {
+        resolve(false);
+        return;
+      }
+      setTimeout(tick, 5);
+    };
+    tick();
+  });
+}
+
+describe("G16 live query fan-out", () => {
+  test("subscribers × stamped EXISTS scales without unbounded queue growth", async () => {
+    if (process.env.OKE_BENCH !== "1") {
+      console.log("skip: set OKE_BENCH=1 to run G16");
+      return;
+    }
+
+    const points: PointResult[] = [];
+    const issues: string[] = [];
+
+    for (const n of SUBSCRIBERS) {
+      const delivered: number[] = [];
+      const unsubs: Array<() => void> = [];
+      let totalDelivered = 0;
+
+      for (let i = 0; i < n; i += 1) {
+        delivered.push(0);
+        const idx = i;
+        const sub: LiveSubscription = {
+          id: `sub-${n}-${i}`,
+          ref: "sql:notes",
+          table: "notes",
+          pkColumn: "id",
+          identity: aliceIdentity(i),
+          deliver(_event: LiveQueryEvent) {
+            delivered[idx] = (delivered[idx] ?? 0) + 1;
+            totalDelivered += 1;
+          },
+        };
+        unsubs.push(runtime.subscribe(sub));
+      }
+
+      const shedBefore = runtime.metrics.eventsShed;
+      const eventLatencies: number[] = [];
+      const t0 = performance.now();
+      for (let e = 0; e < EVENTS; e += 1) {
+        const before = totalDelivered;
+        const te0 = performance.now();
+        runtime.onCdc({
+          tableName: "notes",
+          op: "update",
+          before: { id: "n1", owner: "alice", body: "hi" },
+          after: { id: "n1", owner: "alice", body: `hi-${e}` },
+          seq: e + 1,
+        });
+        // Wait until every subscriber got this event (or settle timeout).
+        const expected = before + n;
+        const ok = await waitFor(() => totalDelivered >= expected, SETTLE_MS);
+        eventLatencies.push(performance.now() - te0);
+        if (!ok) {
+          issues.push(
+            `N=${n} event ${e}: delivered ${totalDelivered}/${expected} within ${SETTLE_MS}ms`,
+          );
+          break;
+        }
+      }
+      const wallMs = performance.now() - t0;
+      const shed = runtime.metrics.eventsShed - shedBefore;
+
+      for (const u of unsubs) u();
+
+      const point: PointResult = {
+        subscribers: n,
+        events: eventLatencies.length,
+        delivered: totalDelivered,
+        wallMs: Number(wallMs.toFixed(1)),
+        p50MsPerEvent: Number(percentile(eventLatencies, 50).toFixed(2)),
+        p99MsPerEvent: Number(percentile(eventLatencies, 99).toFixed(2)),
+        eventsPerSec: Number(((eventLatencies.length / wallMs) * 1000).toFixed(1)),
+        shed,
+      };
+      points.push(point);
+
+      // Shed must stay at 0 under these N×EVENTS sizes — queue is 10k.
+      expect(shed).toBe(0);
+      // Rough linear growth: p50 at max N should not be > 20× p50 at min N
+      // (serialized PGlite is slow by design; collapse would be >>20×).
+    }
+
+    if (points.length >= 2) {
+      const first = points[0]!;
+      const last = points[points.length - 1]!;
+      const ratio = last.p50MsPerEvent / Math.max(0.001, first.p50MsPerEvent);
+      if (ratio > 40) {
+        issues.push(
+          `super-linear fan-out: p50 ${first.subscribers}→${last.subscribers} grew ${ratio.toFixed(1)}×`,
+        );
+      }
+    }
+
+    const path = await writeArtifact({
+      group: "g16-live-query-fanout",
+      hardware: HARDWARE,
+      disclaimer: DISCLAIMER,
+      command: "bun test src/bench/g16-live-query-fanout.bench.ts",
+      metrics: Object.fromEntries(
+        points.flatMap((p) => [
+          [`n${p.subscribers}_p50Ms`, p.p50MsPerEvent],
+          [`n${p.subscribers}_p99Ms`, p.p99MsPerEvent],
+          [`n${p.subscribers}_eventsPerSec`, p.eventsPerSec],
+          [`n${p.subscribers}_wallMs`, p.wallMs],
+        ]),
+      ),
+      issues,
+      fixes: [],
+      remeasured: null,
+    });
+    console.log(`G16 artifact → ${path}`);
+    console.table(points);
+    expect(points.length).toBe(SUBSCRIBERS.length);
+  }, 120_000);
+});

package/src/bench/lib/event-loop-lag.ts

@@ -0,0 +1,26 @@
+/**
+ * Event-loop lag probe — setInterval drift under load.
+ */
+
+/** Measure setInterval drift under load. Returns lag samples in ms. */
+export function measureEventLoopLag(expectedIntervalMs = 100): {
+  lags: () => number[];
+  stop: () => void;
+} {
+  const lags: number[] = [];
+  let last = performance.now();
+  let alive = true;
+  const id = setInterval(() => {
+    if (!alive) return;
+    const now = performance.now();
+    lags.push(Number((now - last - expectedIntervalMs).toFixed(2)));
+    last = now;
+  }, expectedIntervalMs);
+  return {
+    lags: () => lags,
+    stop: () => {
+      alive = false;
+      clearInterval(id);
+    },
+  };
+}

package/src/bench/lib/infra.ts

@@ -0,0 +1,60 @@
+/**
+ * Bench infra helpers — live-env resolution, file waits, jsonl loading.
+ *
+ * Env gating mirrors `src/kernel/horizontal.integration.test.ts`:
+ * OKE_TEST_POSTGRES_URL (or OKE_TEST_POSTGRES=1 + DATABASE_URL /
+ * OKE_STORE_SQL_URL) AND OKE_TEST_REDIS_URL (or REDIS_URL). Credentials are
+ * resolved at runtime from the environment only — never printed or logged.
+ */
+
+export const LIVE_PG =
+  process.env.OKE_TEST_POSTGRES_URL?.trim() ||
+  (process.env.OKE_TEST_POSTGRES === "1"
+    ? (process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL)?.trim()
+    : undefined);
+
+export const LIVE_REDIS =
+  process.env.OKE_TEST_REDIS_URL?.trim() || process.env.REDIS_URL?.trim() || undefined;
+
+export function resolveLivePg(): string | undefined {
+  return LIVE_PG;
+}
+
+export function resolveLiveRedis(): string | undefined {
+  return LIVE_REDIS;
+}
+
+/** Both live Postgres and Redis, or undefined — the bench gate. */
+export function liveInfra(): { pg: string; redis: string } | undefined {
+  return LIVE_PG && LIVE_REDIS ? { pg: LIVE_PG, redis: LIVE_REDIS } : undefined;
+}
+
+/** Poll until `path` exists (or timeout). Mirrors the horizontal test helper. */
+export async function waitForFile(path: string, timeoutMs = 20_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await Bun.file(path).exists()) return true;
+    await Bun.sleep(20);
+  }
+  return false;
+}
+
+/** Poll until `cond()` returns true (or timeout). */
+export async function waitFor(cond: () => Promise<boolean>, timeoutMs = 20_000): Promise<boolean> {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (await cond()) return true;
+    await Bun.sleep(20);
+  }
+  return false;
+}
+
+/** Read a JSONL file into parsed records; missing file → empty array. */
+export async function loadJsonl<T = Record<string, unknown>>(path: string): Promise<T[]> {
+  if (!(await Bun.file(path).exists())) return [];
+  return (await Bun.file(path).text())
+    .trim()
+    .split("\n")
+    .filter(Boolean)
+    .map((l) => JSON.parse(l) as T);
+}

package/src/bench/lib/report.ts

@@ -0,0 +1,52 @@
+/**
+ * Bench artifact writer — every benchmark emits a uniform, disclaimer-stamped
+ * JSON artifact into `src/bench/results/` (gitignored).
+ *
+ * These numbers are for regression trend analysis on this hardware — not
+ * production SLA targets. macOS/Bun/JSC behavior differs from Linux prod.
+ */
+
+export interface BenchArtifact {
+  readonly group: string;
+  readonly hardware: string;
+  readonly disclaimer: string;
+  readonly command: string;
+  readonly metrics: Record<string, number>;
+  readonly issues: string[];
+  readonly fixes: string[];
+  readonly remeasured: null | { metrics: Record<string, number>; rerunScope?: string };
+}
+
+export const HARDWARE = "Apple M4, 24GB";
+
+export const DISCLAIMER = "trend-analysis-only; not SLA; macOS M4 not Linux prod";
+
+/** Percentile of an array of samples (ms or ops). */
+export function percentile(samples: number[], p: number): number {
+  if (samples.length === 0) return NaN;
+  const sorted = [...samples].sort((a, b) => a - b);
+  const idx = Math.min(sorted.length - 1, Math.ceil((p / 100) * sorted.length) - 1);
+  return sorted[idx]!;
+}
+
+export function summarize(samples: number[]): {
+  p50Ms: number;
+  p99Ms: number;
+  opsPerSec: number;
+} {
+  const total = samples.reduce((a, b) => a + b, 0);
+  return {
+    p50Ms: Number(percentile(samples, 50).toFixed(3)),
+    p99Ms: Number(percentile(samples, 99).toFixed(3)),
+    opsPerSec: total > 0 ? Number((samples.length / (total / 1000)).toFixed(1)) : 0,
+  };
+}
+
+/** Write `src/bench/results/<group>-<timestamp>.json`. */
+export async function writeArtifact(a: BenchArtifact): Promise<string> {
+  const dir = new URL("../results/", import.meta.url).pathname;
+  await Bun.$`mkdir -p ${dir}`.quiet();
+  const path = `${dir}${a.group}-${Date.now()}.json`;
+  await Bun.write(path, `${JSON.stringify(a, null, 2)}\n`);
+  return path;
+}

package/src/bench/lib/rss-sampler.ts

@@ -0,0 +1,61 @@
+/**
+ * Background RSS / open-fd sampler for a foreign PID (the served app child).
+ *
+ * Samples via `ps` / `lsof` best-effort; lsof failure yields fds=0.
+ */
+
+export interface RssSample {
+  tMs: number;
+  rssMb: number;
+  fds: number;
+}
+
+/**
+ * Sample RSS every intervalMs until stopped. Open-fd count via
+ * `lsof -p <pid> -Fn | wc -l` best-effort (0 if lsof fails).
+ */
+export function startSampler(
+  pid: number,
+  intervalMs = 5000,
+): { samples: () => readonly RssSample[]; stop: () => Promise<void> } {
+  const samples: RssSample[] = [];
+  let alive = true;
+  const t0 = performance.now();
+  const tick = async () => {
+    while (alive) {
+      let rssMb = 0;
+      let fds = 0;
+      try {
+        const ps = Bun.spawnSync(["ps", "-o", "rss=", "-p", String(pid)]);
+        rssMb = Number(ps.stdout.toString().trim()) / 1024;
+        const lf = Bun.spawnSync(["sh", "-c", `lsof -p ${pid} -Fn 2>/dev/null | wc -l`]);
+        fds = Number(lf.stdout.toString().trim());
+      } catch {
+        /* best-effort */
+      }
+      samples.push({ tMs: Math.round(performance.now() - t0), rssMb, fds });
+      await Bun.sleep(intervalMs);
+    }
+  };
+  void tick();
+  return {
+    samples: () => samples,
+    stop: async () => {
+      alive = false;
+      await Bun.sleep(intervalMs);
+    },
+  };
+}
+
+/** Linear slope MB/min over samples (least squares on last N points). */
+export function rssSlopeMbPerMin(samples: readonly RssSample[], windowLast = 12): number {
+  const pts = samples.slice(-windowLast).filter((s) => s.rssMb > 0);
+  if (pts.length < 2) return 0;
+  const n = pts.length;
+  const sx = pts.reduce((a, s) => a + s.tMs, 0);
+  const sy = pts.reduce((a, s) => a + s.rssMb, 0);
+  const sxy = pts.reduce((a, s) => a + s.tMs * s.rssMb, 0);
+  const sxx = pts.reduce((a, s) => a + s.tMs * s.tMs, 0);
+  const slopePerMs = (n * sxy - sx * sy) / (n * sxx - sx * sx || 1);
+  return Number((slopePerMs * 60_000).toFixed(2));
+}

package/src/bench/lib/signal-pg.ts

@@ -0,0 +1,88 @@
+/**
+ * Live-Postgres SQL surface for `openPostgresSignal` (`src/drivers/signal-postgres.ts`).
+ *
+ * Bun.SQL has no LISTEN/NOTIFY API (see `src/drivers/bun-native-completeness.test.ts`),
+ * so this adapter:
+ *   - runs the real transactional outbox (INSERT + FOR UPDATE SKIP LOCKED claims)
+ *     against live Postgres via `Bun.SQL`;
+ *   - fans `notify()` out to in-process `listen()` callbacks so wakeups work
+ *     within one process, and additionally issues a best-effort real
+ *     `pg_notify` for cross-process visibility.
+ *
+ * Cross-process LISTEN delivery is NOT covered — bench artifacts using this
+ * adapter must say so.
+ */
+
+import { toPostgresParams, withPinnedPostgres } from "../../drivers/postgres.ts";
+import type { PostgresSignalSql } from "../../drivers/signal-postgres.ts";
+
+interface UnsafeClient {
+  unsafe(
+    sql: string,
+    values?: readonly unknown[],
+  ): PromiseLike<Record<string, unknown>[] | { length: number; changes?: number }>;
+}
+
+function wrap(
+  client: UnsafeClient,
+  listeners: Map<string, Set<(payload: string) => void>>,
+): PostgresSignalSql {
+  return {
+    async query(sql, params = []) {
+      const result = await client.unsafe(toPostgresParams(sql, params), [...params]);
+      if (Array.isArray(result)) return result as Record<string, unknown>[];
+      return Array.from(result as ArrayLike<Record<string, unknown>>);
+    },
+    async exec(sql, params = []) {
+      const result = await client.unsafe(toPostgresParams(sql, params), [...params]);
+      if (
+        result &&
+        typeof result === "object" &&
+        "changes" in result &&
+        typeof (result as { changes: unknown }).changes === "number"
+      ) {
+        return { changes: (result as { changes: number }).changes };
+      }
+      if (Array.isArray(result)) return { changes: result.length };
+      return { changes: 0 };
+    },
+    // withPinnedPostgres pins ONE pooled connection — required behind pgdog.
+    begin: (fn) =>
+      withPinnedPostgres(client as never, (tx) => fn(wrap(tx as UnsafeClient, listeners))),
+    async listen(channel, onNotify) {
+      const set = listeners.get(channel) ?? new Set<(payload: string) => void>();
+      set.add(onNotify);
+      listeners.set(channel, set);
+      return () => {
+        set.delete(onNotify);
+      };
+    },
+    async notify(channel, payload) {
+      // Real NOTIFY keeps cross-process semantics on the server; local fanout
+      // is what actually wakes this process's drain loop (no LISTEN API).
+      try {
+        await client.unsafe("SELECT pg_notify($1, $2)", [channel, payload]);
+      } catch {
+        /* best-effort */
+      }
+      for (const fn of listeners.get(channel) ?? []) fn(payload);
+    },
+    async close() {
+      /* per-transaction wrappers share the parent pool — nothing to close */
+    },
+  };
+}
+
+export function createBunSignalSql(url: string): PostgresSignalSql & { close(): Promise<void> } {
+  const client = new Bun.SQL(url, { max: 4 }) as unknown as UnsafeClient & {
+    close?: (options?: { timeout?: number }) => Promise<void>;
+  };
+  const listeners = new Map<string, Set<(payload: string) => void>>();
+  const api = wrap(client, listeners);
+  return {
+    ...api,
+    close: async () => {
+      await client.close?.();
+    },
+  };
+}