okengine 0.10.2 → 0.11.0

package/src/release/build-lib.ts

@@ -0,0 +1,58 @@
+#!/usr/bin/env bun
+/**
+ * Prebuild tree-shaken ESM library entries into `dist/` for non-Bun consumers.
+ *
+ * Bun itself resolves the `"bun"` export condition to TypeScript sources under
+ * `src/`. This build is what `"import"` / `"default"` conditions point at.
+ */
+
+import { mkdir, rm } from "node:fs/promises";
+import { dirname, join, relative, resolve } from "node:path";
+import { EXPORT_BUILD_EXTERNALS } from "./measure.ts";
+
+const ROOT = resolve(import.meta.dir, "../..");
+const DIST = join(ROOT, "dist");
+
+/** Library entry points mirrored into `dist/`. */
+const ENTRIES: readonly { readonly src: string; readonly out: string }[] = [
+  { src: "src/index.ts", out: "dist/index.js" },
+  { src: "src/http.ts", out: "dist/http.js" },
+  { src: "src/kernel-entry.ts", out: "dist/kernel-entry.js" },
+  { src: "src/full.ts", out: "dist/full.js" },
+  { src: "src/i18n-entry.ts", out: "dist/i18n-entry.js" },
+  { src: "src/compiler-entry.ts", out: "dist/compiler-entry.js" },
+  { src: "src/journal-entry.ts", out: "dist/journal-entry.js" },
+];
+
+/**
+ * Build every library entry into `dist/`.
+ */
+export async function buildLib(): Promise<void> {
+  await rm(DIST, { recursive: true, force: true });
+  await mkdir(DIST, { recursive: true });
+
+  for (const entry of ENTRIES) {
+    const absIn = join(ROOT, entry.src);
+    const absOut = join(ROOT, entry.out);
+    await mkdir(dirname(absOut), { recursive: true });
+    const result = await Bun.build({
+      entrypoints: [absIn],
+      outdir: dirname(absOut),
+      naming: relative(DIST, absOut).replace(/\\/g, "/"),
+      target: "bun",
+      format: "esm",
+      minify: false,
+      sourcemap: "external",
+      external: [...EXPORT_BUILD_EXTERNALS],
+      splitting: false,
+    });
+    if (!result.success) {
+      throw new Error(`build:lib failed for ${entry.src}:\n${result.logs.map(String).join("\n")}`);
+    }
+  }
+}
+
+if (import.meta.main) {
+  await buildLib();
+  console.log(`build:lib wrote ${ENTRIES.length} entries under dist/`);
+}

package/src/release/exports.test.ts

@@ -59,13 +59,15 @@ describe("export budget targets", () => {
 
   test("every non-glob package export and every driver module is covered", async () => {
     const pkg = (await Bun.file(join(ROOT, "package.json")).json()) as {
-      exports: Record<string, string>;
+      exports: Record<string, import("./exports.ts").PackageExportTarget>;
     };
+    const { resolveExportSourcePath } = await import("./exports.ts");
     const targets = await resolveExportBudgetTargets();
     const bySubpath = new Map(targets.map((t) => [t.subpath, t]));
 
-    for (const [subpath, entryRel] of Object.entries(pkg.exports)) {
+    for (const [subpath, entryTarget] of Object.entries(pkg.exports)) {
       if (subpath.endsWith("/*")) continue;
+      const entryRel = resolveExportSourcePath(entryTarget);
       const target = bySubpath.get(subpath);
       expect(target).toBeDefined();
       expect(target!.id).toBe(`export:${subpath}`);

package/src/release/exports.ts

@@ -77,8 +77,29 @@ export function exportBudgetGroup(subpath: string): BudgetGroup {
   return "exports";
 }
 
+/** One package.json exports target (string path or conditional map). */
+export type PackageExportTarget =
+  | string
+  | Readonly<Partial<Record<"types" | "bun" | "import" | "default" | "require", string>>>;
+
 interface PackageExports {
-  readonly exports?: Readonly<Record<string, string>>;
+  readonly exports?: Readonly<Record<string, PackageExportTarget>>;
+}
+
+/**
+ * Resolve a package export target to the TypeScript source path used for budgets.
+ *
+ * Prefers `bun` / `types` (src) over compiled `import`/`default` (dist).
+ *
+ * @param target - Export target from package.json
+ */
+export function resolveExportSourcePath(target: PackageExportTarget): string {
+  if (typeof target === "string") return target;
+  const path = target.bun ?? target.types ?? target.import ?? target.default;
+  if (!path || typeof path !== "string") {
+    throw new Error("export target has no resolvable string path");
+  }
+  return path;
 }
 
 /**
@@ -150,7 +171,7 @@ export async function resolveExportBudgetTargets(options?: {
 
   const targets: ExportBudgetTarget[] = [];
 
-  for (const [subpath, entryRel] of Object.entries(exportsMap)) {
+  for (const [subpath, entryTarget] of Object.entries(exportsMap)) {
     if (subpath.endsWith("/*")) {
       if (subpath !== "./drivers/*") {
         throw new Error(`unsupported export glob ${subpath}: only ./drivers/* is expanded`);
@@ -164,8 +185,13 @@ export async function resolveExportBudgetTargets(options?: {
       continue;
     }
 
-    if (typeof entryRel !== "string") {
-      throw new Error(`export ${subpath} must map to a string path`);
+    let entryRel: string;
+    try {
+      entryRel = resolveExportSourcePath(entryTarget);
+    } catch {
+      throw new Error(
+        `export ${subpath} must map to a string path or conditional bun/types target`,
+      );
     }
 
     targets.push(targetFor(subpath, resolve(root, entryRel)));

package/src/release/measure.ts

@@ -39,7 +39,7 @@ const BUILD_EXTERNALS = [
 ] as const;
 
 /** Heavy optional / peer packages — not counted in export:* gzip samples. */
-const EXPORT_BUILD_EXTERNALS = [
+export const EXPORT_BUILD_EXTERNALS = [
   ...BUILD_EXTERNALS,
   "sently",
   "sently/*",
@@ -48,8 +48,6 @@ const EXPORT_BUILD_EXTERNALS = [
   "ajv-formats",
   "oxc-parser",
   "zod",
-  "@libsql/client",
-  "@libsql/*",
   "@electric-sql/pglite",
   "@electric-sql/*",
 ] as const;
@@ -152,6 +150,80 @@ export async function measureEntryGzipBytes(
   return gzipBuildOutputs(result, label);
 }
 
+/**
+ * Raw (uncompressed) minified JS bytes for one entry.
+ *
+ * @param entry - Absolute path to the TypeScript entry
+ * @param label - Error context
+ * @param external - Packages left external (not inlined)
+ */
+export async function measureEntryRawBytes(
+  entry: string,
+  label = entry,
+  external: readonly string[] = BUILD_EXTERNALS,
+): Promise<number> {
+  const result = await Bun.build({
+    entrypoints: [entry],
+    minify: true,
+    target: "bun",
+    format: "esm",
+    external: [...external],
+  });
+  if (!result.success) {
+    throw new Error(`${label} build failed:\n${result.logs.map(String).join("\n")}`);
+  }
+  let total = 0;
+  for (const artifact of result.outputs) {
+    const path = artifact.path;
+    if (path && !/\.(m?js|cjs)$/.test(path) && artifact.kind === "asset") continue;
+    const raw = await artifact.arrayBuffer();
+    total += raw.byteLength;
+  }
+  if (total <= 0) throw new Error(`${label} build produced no JS output`);
+  return total;
+}
+
+/** HTTP-ping app budget sample (raw + gzip, with/without export externals). */
+export interface HttpPingBudgetSample {
+  readonly gzipWithExternals: number;
+  readonly rawWithExternals: number;
+  readonly gzipWithoutExternals: number;
+  readonly rawWithoutExternals: number;
+}
+
+/**
+ * Measure a minimal HTTP ping app via `okengine/http`.
+ */
+export async function measureHttpPingAppBytes(): Promise<HttpPingBudgetSample> {
+  const dir = await mkdtemp(join(tmpdir(), "oke-http-ping-budget-"));
+  const anchor = join(dir, "anchor.ts");
+  const httpEntry = resolve(ROOT, "src/http.ts");
+  await Bun.write(
+    anchor,
+    `import { on, flow, http, gate, oke, createBunRuntime } from ${JSON.stringify(httpEntry)};\n` +
+      `on(http.get("/").gate(gate.public), flow("ping", { do: () => "Hi" }));\n` +
+      `export const app = oke({ name: "ping" });\n` +
+      `export const rt = createBunRuntime;\n`,
+  );
+  try {
+    const [gzipWithExternals, rawWithExternals, gzipWithoutExternals, rawWithoutExternals] =
+      await Promise.all([
+        measureEntryGzipBytes(anchor, "http-ping", EXPORT_BUILD_EXTERNALS),
+        measureEntryRawBytes(anchor, "http-ping", EXPORT_BUILD_EXTERNALS),
+        measureEntryGzipBytes(anchor, "http-ping-deps", BUILD_EXTERNALS),
+        measureEntryRawBytes(anchor, "http-ping-deps", BUILD_EXTERNALS),
+      ]);
+    return {
+      gzipWithExternals,
+      rawWithExternals,
+      gzipWithoutExternals,
+      rawWithoutExternals,
+    };
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
 /**
  * Gzip size of the kernel edge profile bundle.
  */
@@ -287,22 +359,13 @@ export async function measureConsoleBundleBreakdown(
  * (FS / module-cache warmup), median of the remaining six.
  */
 async function measureColdStartMedianMsOnce(): Promise<number> {
-  const paths = {
-    bun: `${import.meta.dir}/../runtime/bun.ts`,
-    app: `${import.meta.dir}/../kernel/app.ts`,
-    flow: `${import.meta.dir}/../kernel/flow.ts`,
-    on: `${import.meta.dir}/../kernel/on.ts`,
-    http: `${import.meta.dir}/../kernel/triggers.ts`,
-  };
+  const httpEntry = `${import.meta.dir}/../http.ts`;
   const probe = `
 const t0 = performance.now();
-const { createBunRuntime } = await import(${JSON.stringify(paths.bun)});
-const { oke } = await import(${JSON.stringify(paths.app)});
-const { flow } = await import(${JSON.stringify(paths.flow)});
-const { on, resetBindings } = await import(${JSON.stringify(paths.on)});
-const { http } = await import(${JSON.stringify(paths.http)});
+const { createBunRuntime, oke, on, flow, http, gate } = await import(${JSON.stringify(httpEntry)});
+const { resetBindings } = await import(${JSON.stringify(`${import.meta.dir}/../kernel/on.ts`)});
 resetBindings();
-on(http.get("/ping"), flow("ping", { do: () => ({ ok: true }) }));
+on(http.get("/ping").gate(gate.public), flow("ping", { do: () => ({ ok: true }) }));
 const app = oke({ name: "cold-start" });
 const rt = createBunRuntime();
 const server = rt.serve(app, { port: 0, hostname: "127.0.0.1" });
@@ -429,11 +492,13 @@ export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
   // Cold start alone first — parallel gzip work contends for CPU on CI and
   // falsely inflates the wall-clock probe.
   const coldStartMedianMs = await measureColdStartMedianMs();
-  const [kernelEdgeGzipBytes, clientGzipBytes, consoleInitialGzipBytes] = await Promise.all([
-    measureKernelEdgeGzipBytes(),
-    measureClientGzipBytes(),
-    measureConsoleInitialGzipBytes(),
-  ]);
+  const [kernelEdgeGzipBytes, clientGzipBytes, consoleInitialGzipBytes, httpPing] =
+    await Promise.all([
+      measureKernelEdgeGzipBytes(),
+      measureClientGzipBytes(),
+      measureConsoleInitialGzipBytes(),
+      measureHttpPingAppBytes(),
+    ]);
   const routingP99Ms = measureRoutingP99Ms();
 
   const budgets: BudgetSample[] = [
@@ -482,6 +547,20 @@ export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
       "absolute",
       "core",
     ),
+    regressionSample(
+      "httpPingGzipBytes",
+      "HTTP ping app (gzip, externals)",
+      "core",
+      httpPing.gzipWithExternals,
+      previous,
+    ),
+    regressionSample(
+      "httpPingRawBytes",
+      "HTTP ping app (raw, externals)",
+      "core",
+      httpPing.rawWithExternals,
+      previous,
+    ),
   ];
 
   const exportTargets = await resolveExportBudgetTargets();
@@ -561,7 +640,7 @@ export function formatBudgetsMarkdown(snapshot: BudgetsSnapshot): string {
     "",
     `_okengine v${snapshot.version} · measured ${snapshot.measuredAt}_`,
     "",
-    "Core rows are absolute AGENTS caps. Exports, Plugins, and Drivers fail on regression vs the prior [`budgets.json`](budgets.json) (max +256 B or +2%). Export gzip excludes peers/optionals (`zod`, `sently`, `oxc-parser`, `ajv`).",
+    "Core rows are absolute AGENTS caps (plus HTTP-ping regression samples). Exports, Plugins, and Drivers fail on regression vs the prior [`budgets.json`](budgets.json) (max +256 B or +2%). Export gzip excludes peers/optionals (`zod`, `sently`, `oxc-parser`, `ajv`, DuckDB, FormatJS). The `okengine` export row is the **thin root** (gzip); use `okengine/full` for the legacy mega-barrel and `okengine/http` for HTTP-only apps.",
   ];
   const order: readonly BudgetGroup[] = ["core", "exports", "plugins", "drivers"];
   for (const group of order) {

package/src/runs/duckdb.ts

@@ -2,8 +2,9 @@
  * Thin DuckDB adapter — adopted via `@duckdb/node-api`, not reinvented.
  */
 
-import { DuckDBInstance, type DuckDBConnection } from "@duckdb/node-api";
+import type { DuckDBConnection, DuckDBInstance } from "@duckdb/node-api";
 
+import { importOptionalPeer } from "../shared/optional-peer.ts";
 import type { RunsRow } from "./types.ts";
 
 /** DuckDB session — instance kept alive with the connection. */
@@ -18,7 +19,11 @@ export interface DuckSession {
 
 /** Open an in-memory DuckDB session. */
 export async function openDuckDB(): Promise<DuckSession> {
-  const instance = await DuckDBInstance.create(":memory:");
+  const mod = await importOptionalPeer<typeof import("@duckdb/node-api")>(
+    "@duckdb/node-api",
+    "Runs DuckDB / Parquet queries",
+  );
+  const instance = await mod.DuckDBInstance.create(":memory:");
   const conn = await instance.connect();
   return {
     instance,

package/src/shared/optional-peer.ts

@@ -0,0 +1,41 @@
+/**
+ * Resolve optional peer dependencies with a clear install hint.
+ */
+
+import { createRequire } from "node:module";
+
+const require = createRequire(import.meta.url);
+
+/**
+ * Dynamically import an optional peer, or throw an actionable error.
+ *
+ * @param spec - Package name
+ * @param feature - Human feature label for the error
+ */
+export async function importOptionalPeer<T>(spec: string, feature: string): Promise<T> {
+  try {
+    return (await import(spec)) as T;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `${feature} requires optional peer \`${spec}\`. Install it with \`bun add ${spec}\`. (${detail})`,
+    );
+  }
+}
+
+/**
+ * Synchronously require an optional peer, or throw an actionable error.
+ *
+ * @param spec - Package name
+ * @param feature - Human feature label
+ */
+export function requireOptionalPeer<T>(spec: string, feature: string): T {
+  try {
+    return require(spec) as T;
+  } catch (err) {
+    const detail = err instanceof Error ? err.message : String(err);
+    throw new Error(
+      `${feature} requires optional peer \`${spec}\`. Install it with \`bun add ${spec}\`. (${detail})`,
+    );
+  }
+}

package/src/term.test.ts

@@ -16,9 +16,6 @@ import {
   formatRequestLine,
   formatStackSummary,
   countTermLines,
-  createAnchoredBoard,
-  createBootProgress,
-  createRewritableBlock,
   formatStatusDot,
   formatStatusLine,
   termStyle,
@@ -48,7 +45,7 @@ describe("term", () => {
         { element: "flow", detail: "", status: "ready" },
         { element: "store", detail: "sql postgres · kv redis", status: "ready" },
         { element: "signal", detail: "memory", status: "ready" },
-        { element: "ai", detail: "openai-compatible · smollm2", status: "pending" },
+        { element: "ai", detail: "openai-compatible · granite3.3:2b", status: "pending" },
       ],
     });
     expect(out).toContain("oke dev  v0.2.4");
@@ -77,47 +74,9 @@ describe("term", () => {
     expect(formatStatusDot("ready", false)).toBe("●");
   });
 
-  test("createRewritableBlock appends when disabled", () => {
-    let out = "";
-    const block = createRewritableBlock((t) => {
-      out += t;
-    }, false);
-    block.paint("a\nb\n");
-    block.paint("c\n");
-    expect(out).toBe("a\nb\nc\n");
+  test("countTermLines counts rows", () => {
     expect(countTermLines("a\nb\n")).toBe(2);
-  });
-
-  test("createBootProgress replaces keyed rows then clears", () => {
-    let out = "";
-    const progress = createBootProgress((t) => {
-      out += t;
-    }, false);
-    progress.set("compose", "compose…\n");
-    progress.set("compose", "compose ok\n");
-    progress.set("vault", "vault ok\n");
-    // Non-TTY appends each set (including replacements).
-    expect(out).toContain("compose ok\n");
-    expect(out).toContain("vault ok\n");
-    progress.clear();
-    // clear is a no-op on the stream when rewrite is disabled
-    expect(out).toContain("vault ok\n");
-  });
-
-  test("createAnchoredBoard wrapWrite tracks below output", () => {
-    let out = "";
-    const board = createAnchoredBoard((t) => {
-      out += t;
-    }, false);
-    board.paint("board\n");
-    const w = board.wrapWrite((t) => {
-      out += t;
-    });
-    w("below\n");
-    board.paint("board2\n"); // non-TTY: no rewrite append
-    expect(out).toContain("board\n");
-    expect(out).toContain("below\n");
-    board.stop();
+    expect(countTermLines("")).toBe(0);
   });
 
   test("formatServiceLine / formatAppReadyLine include URL", () => {

package/src/test/create-test-app.ts

@@ -14,6 +14,9 @@
  * ```
  */
 
+import { mkdtemp, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
 import {
   createMockAiDriver,
   createChannelInbox,
@@ -212,6 +215,12 @@ export async function createTestApp<App extends OkeApp>(
     return out;
   };
 
+  // Unique on-disk PGLite datadir per harness — `memory://` is not reliably
+  // isolated across boots in one worker (IF NOT EXISTS / row leaks).
+  const prevPgliteUrl = process.env.OKE_PGLITE_URL;
+  const pgliteDir = await mkdtemp(join(tmpdir(), "oke-pglite-"));
+  process.env.OKE_PGLITE_URL = pgliteDir;
+
   await app.boot({
     ...(options.boot ?? {}),
     env: "test",
@@ -322,6 +331,9 @@ export async function createTestApp<App extends OkeApp>(
     },
     async close() {
       await app.bootResult?.close();
+      if (prevPgliteUrl === undefined) delete process.env.OKE_PGLITE_URL;
+      else process.env.OKE_PGLITE_URL = prevPgliteUrl;
+      await rm(pgliteDir, { recursive: true, force: true }).catch(() => undefined);
     },
   };
 

package/src/test/provisions.integration.test.ts

@@ -54,7 +54,7 @@ describe("Provisions integration", () => {
       out: z.boolean(),
       effects: { secrets: ["STRIPE_KEY"], emits: ["order-news"] },
       do: async ({ orderId }, fx) => {
-        const key = fx.vault(stripeKey);
+        const key = await fx.vault.get(stripeKey);
         expect(key.reveal().startsWith("sk_")).toBe(true);
 
         await fx.step("create-intent", async () => ({ id: `pi_${orderId}` }));

package/src/test/reset-element-registries.ts

@@ -18,6 +18,7 @@
 import { afterEach } from "bun:test";
 import {
   channelTemplateRegistry,
+  requiredEnvRegistry,
   secretRegistry,
   signalRegistry,
   storeRegistry,
@@ -26,6 +27,7 @@ import {
 afterEach(() => {
   storeRegistry.length = 0;
   secretRegistry.length = 0;
+  requiredEnvRegistry.length = 0;
   signalRegistry.length = 0;
   channelTemplateRegistry.length = 0;
 });

package/src/upgrade/codemods.test.ts

@@ -5,8 +5,7 @@
 import { describe, expect, test } from "bun:test";
 import {
   CODEMODS,
-  rewriteConfigEnvKeys,
-  rewriteFromStackMarkers,
+  rewriteThinRootImports,
   runCodemods,
   validateCodemodRegistry,
   type Codemod,
@@ -54,24 +53,12 @@ describe("codemod registry", () => {
     expect(changes).toEqual([{ path: "src/x.ts", before: "old", after: "new" }]);
   });
 
-  test("rewriteConfigEnvKeys renames driver-map keys", () => {
-    const after = rewriteConfigEnvKeys(`sql: {
-  dev: "sqlite",
-  stack: "postgres",
-  prod: "postgres",
-}`);
-    expect(after).toContain('local: "sqlite"');
-    expect(after).toContain('docker: "postgres"');
-    expect(after).not.toMatch(/(^|[^\w.])dev\s*:/);
-    expect(after).not.toMatch(/(^|[^\w.])stack\s*:/);
-  });
-
-  test("rewriteFromStackMarkers renames vault helpers", () => {
-    const after = rewriteFromStackMarkers(
-      `dev: vault.fromStack("store.sql") // __oke_from_stack__`,
+  test("rewriteThinRootImports moves deep imports to subpaths", () => {
+    const after = rewriteThinRootImports(
+      `import { createFx, on } from "okengine";\nimport { flow } from "okengine";\n`,
     );
-    expect(after).toContain("fromDocker");
-    expect(after).toContain("__oke_from_docker__");
-    expect(after).not.toContain("fromStack");
+    expect(after).toContain('from "okengine/full"');
+    expect(after).toContain("createFx");
+    expect(after).toMatch(/from ["']okengine["']/);
   });
 });