okengine 0.1.6 → 0.2.2

package/src/release/measure.ts

@@ -2,18 +2,55 @@
  * Budget measurement helpers — shared by gates and the budgets.json publisher.
  */
 
-import { readdir } from "node:fs/promises";
-import { join } from "node:path";
+import { mkdtemp, readdir, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
 import { createRouter } from "../kernel/router.ts";
+import {
+  type BudgetGroup,
+  resolveExportBudgetTargets,
+} from "./exports.ts";
 import {
   CLIENT_BUDGET_BYTES,
   COLD_START_BUDGET_MS,
   CONSOLE_BUDGET_BYTES,
+  EXPORT_REGRESSION_TOLERANCE_FLOOR_BYTES,
+  EXPORT_REGRESSION_TOLERANCE_RATIO,
   KERNEL_EDGE_BUDGET_BYTES,
   ROUTING_P99_BUDGET_MS,
 } from "./limits.ts";
 
 const ROOT = `${import.meta.dir}/../..`;
+const BUDGETS_JSON_PATH = resolve(ROOT, "budgets.json");
+
+/**
+ * Deps measured separately from OKE code in export samples.
+ * Edge/client absolute gates keep the historical smaller external list.
+ */
+const BUILD_EXTERNALS = ["@duckdb/node-api", "@duckdb/*"] as const;
+
+/** Heavy optional / peer packages — not counted in export:* gzip samples. */
+const EXPORT_BUILD_EXTERNALS = [
+  ...BUILD_EXTERNALS,
+  "age-encryption",
+  "sently",
+  "sently/*",
+  "ajv",
+  "ajv/*",
+  "ajv-formats",
+  "oxc-parser",
+  "zod",
+] as const;
+
+/** How a sample is gated. */
+export type BudgetGate = "absolute" | "regression";
+
+/** Report section headings. */
+const GROUP_HEADINGS: Readonly<Record<BudgetGroup, string>> = {
+  core: "Core",
+  exports: "Exports",
+  drivers: "Drivers",
+};
 
 /** One measured budget sample. */
 export interface BudgetSample {
@@ -23,11 +60,15 @@ export interface BudgetSample {
   readonly label: string;
   /** Measured value. */
   readonly value: number;
-  /** Hard limit (exclusive upper bound). */
+  /** Upper bound used for `ok` (absolute cap or regression ceiling). */
   readonly limit: number;
   /** Unit for display / snapshot. */
   readonly unit: "bytes" | "ms";
-  /** True when `value < limit`. */
+  /** Gate mode. */
+  readonly gate: BudgetGate;
+  /** Report section. */
+  readonly group: BudgetGroup;
+  /** True when under the gate's limit (or first baseline for regression). */
   readonly ok: boolean;
 }
 
@@ -41,18 +82,69 @@ export interface BudgetsSnapshot {
   readonly budgets: readonly BudgetSample[];
 }
 
+/**
+ * Gzip size of all JS artifacts from a Bun.build result.
+ *
+ * @param result - Successful build
+ * @param label - Error context
+ */
+async function gzipBuildOutputs(
+  result: Awaited<ReturnType<typeof Bun.build>>,
+  label: string,
+): Promise<number> {
+  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();
+    if (raw.byteLength === 0) continue;
+    total += Bun.gzipSync(new Uint8Array(raw)).byteLength;
+  }
+  if (total <= 0) throw new Error(`${label} build produced no JS output`);
+  return total;
+}
+
+/**
+ * Gzip size of a minified ESM bundle for one entry file.
+ *
+ * @param entry - Absolute path to the TypeScript entry
+ * @param label - Error context
+ * @param external - Packages left external (not inlined)
+ */
+export async function measureEntryGzipBytes(
+  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],
+  });
+  return gzipBuildOutputs(result, label);
+}
+
 /**
  * Gzip size of the kernel edge profile bundle.
  */
 export async function measureKernelEdgeGzipBytes(): Promise<number> {
   const entry = `${import.meta.dir}/../kernel/budget-entry.ts`;
+  // Browser target matches the historical edge-profile gate.
   const result = await Bun.build({
     entrypoints: [entry],
     minify: true,
     target: "browser",
     format: "esm",
-    // Optional native drivers stay out of the edge profile.
-    external: ["@duckdb/node-api", "@duckdb/*"],
+    external: [...BUILD_EXTERNALS],
   });
   if (!result.success) {
     throw new Error(
@@ -87,6 +179,33 @@ export async function measureClientGzipBytes(): Promise<number> {
   return Bun.gzipSync(new Uint8Array(raw)).byteLength;
 }
 
+/**
+ * Gzip size of one published package export entry.
+ *
+ * Bundles through a temporary `import *` anchor so minify cannot drop the
+ * re-export graph (direct entry bundles collapse barrels to ~empty stubs).
+ *
+ * @param entry - Absolute path to the export entry
+ */
+export async function measureExportGzipBytes(entry: string): Promise<number> {
+  const dir = await mkdtemp(join(tmpdir(), "oke-export-budget-"));
+  const anchor = join(dir, "anchor.ts");
+  await Bun.write(
+    anchor,
+    `import * as mod from ${JSON.stringify(entry)};\n` +
+      `export function __okeExportBudgetAnchor(){return mod;}\n`,
+  );
+  try {
+    return await measureEntryGzipBytes(
+      anchor,
+      `export ${entry}`,
+      EXPORT_BUILD_EXTERNALS,
+    );
+  } finally {
+    await rm(dir, { recursive: true, force: true });
+  }
+}
+
 /** One Console asset's gzip size. */
 export interface ConsoleAssetGzip {
   /** File name under `dist/` or `dist/assets/`. */
@@ -253,12 +372,49 @@ export function measureRoutingP99Ms(): number {
 }
 
 /**
- * Measure every published budget.
+ * Regression ceiling from a previous byte sample.
+ *
+ * @param previous - Last committed value
+ */
+export function exportRegressionLimitBytes(previous: number): number {
+  const allowed = Math.max(
+    EXPORT_REGRESSION_TOLERANCE_FLOOR_BYTES,
+    Math.ceil(previous * EXPORT_REGRESSION_TOLERANCE_RATIO),
+  );
+  return previous + allowed;
+}
+
+/**
+ * Load previous sample values from a budgets snapshot file (if present).
+ *
+ * @param path - Absolute path to budgets.json
+ */
+export async function loadPreviousBudgetValues(
+  path = BUDGETS_JSON_PATH,
+): Promise<ReadonlyMap<string, number>> {
+  const file = Bun.file(path);
+  if (!(await file.exists())) return new Map();
+  try {
+    const snap = (await file.json()) as BudgetsSnapshot;
+    const map = new Map<string, number>();
+    for (const b of snap.budgets ?? []) {
+      map.set(b.id, b.value);
+    }
+    return map;
+  } catch {
+    return new Map();
+  }
+}
+
+/**
+ * Measure every published budget (absolute AGENTS caps + export regressions).
  */
 export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
   const pkg = (await Bun.file(`${ROOT}/package.json`).json()) as {
     version: string;
   };
+  const previous = await loadPreviousBudgetValues();
+
   // Cold start alone first — parallel gzip work contends for CPU on CI and
   // falsely inflates the wall-clock probe.
   const coldStartMedianMs = await measureColdStartMedianMs();
@@ -277,6 +433,8 @@ export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
       kernelEdgeGzipBytes,
       KERNEL_EDGE_BUDGET_BYTES,
       "bytes",
+      "absolute",
+      "core",
     ),
     sample(
       "clientGzipBytes",
@@ -284,6 +442,8 @@ export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
       clientGzipBytes,
       CLIENT_BUDGET_BYTES,
       "bytes",
+      "absolute",
+      "core",
     ),
     sample(
       "consoleInitialGzipBytes",
@@ -291,6 +451,8 @@ export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
       consoleInitialGzipBytes,
       CONSOLE_BUDGET_BYTES,
       "bytes",
+      "absolute",
+      "core",
     ),
     sample(
       "coldStartMedianMs",
@@ -298,6 +460,8 @@ export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
       coldStartMedianMs,
       COLD_START_BUDGET_MS,
       "ms",
+      "absolute",
+      "core",
     ),
     sample(
       "routingP99Ms",
@@ -305,9 +469,30 @@ export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
       routingP99Ms,
       ROUTING_P99_BUDGET_MS,
       "ms",
+      "absolute",
+      "core",
     ),
   ];
 
+  const exportTargets = await resolveExportBudgetTargets();
+  const exportSizes = await Promise.all(
+    exportTargets.map(async (t) => ({
+      target: t,
+      bytes: await measureExportGzipBytes(t.entry),
+    })),
+  );
+  for (const { target, bytes } of exportSizes) {
+    budgets.push(
+      regressionSample(
+        target.id,
+        target.label,
+        target.group,
+        bytes,
+        previous,
+      ),
+    );
+  }
+
   return {
     measuredAt: new Date().toISOString(),
     version: pkg.version,
@@ -316,7 +501,7 @@ export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
 }
 
 /**
- * Format a snapshot for CI logs.
+ * Format a snapshot for CI logs (Core / Exports / Drivers sections).
  *
  * @param snapshot - Measured budgets
  */
@@ -324,11 +509,54 @@ export function formatBudgetsReport(snapshot: BudgetsSnapshot): string {
   const lines = [
     `okengine budgets v${snapshot.version} @ ${snapshot.measuredAt}`,
   ];
-  for (const b of snapshot.budgets) {
-    const flag = b.ok ? "ok" : "FAIL";
-    lines.push(
-      `  [${flag}] ${b.label}: ${formatValue(b.value, b.unit)} < ${formatValue(b.limit, b.unit)}`,
-    );
+  const order: readonly BudgetGroup[] = ["core", "exports", "drivers"];
+  for (const group of order) {
+    const rows = snapshot.budgets.filter((b) => b.group === group);
+    if (rows.length === 0) continue;
+    lines.push("");
+    lines.push(GROUP_HEADINGS[group]);
+    for (const b of rows) {
+      const flag = b.ok ? "ok" : "FAIL";
+      lines.push(
+        `  [${flag}] ${b.label}: ${formatValue(b.value, b.unit)} < ${formatValue(b.limit, b.unit)}`,
+      );
+    }
+  }
+  return `${lines.join("\n")}\n`;
+}
+
+/**
+ * Full markdown document for [`BUDGETS.md`](../../BUDGETS.md).
+ * Written by `bun run budgets` — do not edit the tables by hand.
+ *
+ * @param snapshot - Measured budgets
+ */
+export function formatBudgetsMarkdown(snapshot: BudgetsSnapshot): string {
+  const lines = [
+    "# Budgets",
+    "",
+    "Published numbers from [`budgets.json`](budgets.json). Refresh with `bun run budgets`.",
+    "",
+    `_okengine v${snapshot.version} · measured ${snapshot.measuredAt}_`,
+    "",
+    "Core rows are absolute AGENTS caps. Exports and Drivers fail on regression vs the prior [`budgets.json`](budgets.json) (max +256 B or +2%). Export gzip excludes peers/optionals (`zod`, `age-encryption`, `sently`, `oxc-parser`, `ajv`).",
+  ];
+  const order: readonly BudgetGroup[] = ["core", "exports", "drivers"];
+  for (const group of order) {
+    const rows = snapshot.budgets.filter((b) => b.group === group);
+    if (rows.length === 0) continue;
+    const limitCol = group === "core" ? "Limit" : "Ceiling";
+    lines.push("");
+    lines.push(`## ${GROUP_HEADINGS[group]}`);
+    lines.push("");
+    lines.push(`| | Measured | ${limitCol} |`);
+    lines.push("|---|---|---|");
+    for (const b of rows) {
+      const mark = b.ok ? "" : " **FAIL**";
+      lines.push(
+        `| ${b.label}${mark} | ${formatValue(b.value, b.unit)} | ${formatValue(b.limit, b.unit)} |`,
+      );
+    }
   }
   return `${lines.join("\n")}\n`;
 }
@@ -348,10 +576,65 @@ function sample(
   value: number,
   limit: number,
   unit: BudgetSample["unit"],
+  gate: BudgetGate,
+  group: BudgetGroup,
 ): BudgetSample {
   const rounded =
     unit === "bytes" ? Math.round(value) : Math.round(value * 1000) / 1000;
-  return { id, label, value: rounded, limit, unit, ok: rounded < limit };
+  return {
+    id,
+    label,
+    value: rounded,
+    limit,
+    unit,
+    gate,
+    group,
+    ok: rounded < limit,
+  };
+}
+
+/**
+ * Byte sample gated against the previous committed value (+ tolerance).
+ * First appearance records a baseline (`ok: true`, `limit` = value + floor).
+ *
+ * @param id - Sample id
+ * @param label - Human label
+ * @param group - Report section
+ * @param value - Measured gzip bytes
+ * @param previous - Prior snapshot values by id
+ */
+function regressionSample(
+  id: string,
+  label: string,
+  group: BudgetGroup,
+  value: number,
+  previous: ReadonlyMap<string, number>,
+): BudgetSample {
+  const rounded = Math.round(value);
+  const prior = previous.get(id);
+  if (prior === undefined) {
+    return {
+      id,
+      label,
+      value: rounded,
+      limit: rounded + EXPORT_REGRESSION_TOLERANCE_FLOOR_BYTES,
+      unit: "bytes",
+      gate: "regression",
+      group,
+      ok: true,
+    };
+  }
+  const limit = exportRegressionLimitBytes(prior);
+  return {
+    id,
+    label,
+    value: rounded,
+    limit,
+    unit: "bytes",
+    gate: "regression",
+    group,
+    ok: rounded < limit,
+  };
 }
 
 function formatValue(value: number, unit: BudgetSample["unit"]): string {

package/src/release/publish.ts

@@ -1,6 +1,7 @@
 #!/usr/bin/env bun
 /**
- * Measure every published budget, print the report, write `budgets.json`.
+ * Measure every published budget, print the report, write `budgets.json`
+ * and sync `BUDGETS.md`.
  *
  * Exit 1 on any regression. CI runs this as a gate; the snapshot is written
  * locally and committed with releases — not auto-pushed from Actions.
@@ -9,26 +10,32 @@
 import { resolve } from "node:path";
 import {
   budgetsPass,
+  formatBudgetsMarkdown,
   formatBudgetsReport,
   measureAllBudgets,
   type BudgetsSnapshot,
 } from "./measure.ts";
+import { BUDGETS_MD } from "./readme.ts";
 
 const ROOT = resolve(import.meta.dir, "../..");
 /** Snapshot path at the repository root. */
 export const BUDGETS_JSON = resolve(ROOT, "budgets.json");
+/** Generated markdown report (`BUDGETS.md`). */
+export const BUDGETS_MARKDOWN = BUDGETS_MD;
 
 /** Options for {@link publishBudgets}. */
 export interface PublishBudgetsOptions {
   /** Destination path (defaults to repo-root `budgets.json`). */
   readonly outPath?: string;
-  /** Skip writing the snapshot file. */
+  /** Markdown report path (defaults to repo-root `BUDGETS.md`). */
+  readonly markdownPath?: string;
+  /** Skip writing the snapshot and markdown report. */
   readonly dryRun?: boolean;
   readonly write?: (text: string) => void;
 }
 
 /**
- * Measure, print, and optionally persist the budgets snapshot.
+ * Measure, print, and optionally persist the budgets snapshot + markdown.
  *
  * @param options - Output / dry-run
  * @returns Exit code (1 when any budget fails)
@@ -44,6 +51,10 @@ export async function publishBudgets(
     const path = options.outPath ?? BUDGETS_JSON;
     await Bun.write(path, `${JSON.stringify(snapshot, null, 2)}\n`);
     write(`wrote ${path}\n`);
+
+    const markdownPath = options.markdownPath ?? BUDGETS_MARKDOWN;
+    await Bun.write(markdownPath, formatBudgetsMarkdown(snapshot));
+    write(`wrote ${markdownPath}\n`);
   }
 
   return { code: budgetsPass(snapshot) ? 0 : 1, snapshot };

package/src/release/readme.test.ts

@@ -0,0 +1,61 @@
+/**
+ * Generated budgets markdown document.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { formatBudgetsMarkdown, type BudgetsSnapshot } from "./measure.ts";
+import { BUDGETS_MD } from "./readme.ts";
+
+describe("budgets markdown", () => {
+  test("BUDGETS_MD points at root BUDGETS.md", () => {
+    expect(BUDGETS_MD.endsWith("/BUDGETS.md")).toBe(true);
+  });
+
+  test("formatBudgetsMarkdown is a standalone document with short names", () => {
+    const snapshot: BudgetsSnapshot = {
+      measuredAt: "2026-07-25T00:00:00.000Z",
+      version: "0.1.6",
+      budgets: [
+        {
+          id: "kernelEdgeGzipBytes",
+          label: "Kernel (edge profile)",
+          value: 8969,
+          limit: 15360,
+          unit: "bytes",
+          gate: "absolute",
+          group: "core",
+          ok: true,
+        },
+        {
+          id: "export:./channel",
+          label: "channel",
+          value: 6144,
+          limit: 6400,
+          unit: "bytes",
+          gate: "regression",
+          group: "exports",
+          ok: true,
+        },
+        {
+          id: "export:./drivers/postgres",
+          label: "postgres",
+          value: 1413,
+          limit: 1669,
+          unit: "bytes",
+          gate: "regression",
+          group: "drivers",
+          ok: true,
+        },
+      ],
+    };
+    const md = formatBudgetsMarkdown(snapshot);
+    expect(md.startsWith("# Budgets\n")).toBe(true);
+    expect(md).toContain("## Core");
+    expect(md).toContain("## Exports");
+    expect(md).toContain("## Drivers");
+    expect(md).toContain("| channel |");
+    expect(md).toContain("| postgres |");
+    expect(md).toContain("[`budgets.json`](budgets.json)");
+    expect(md).not.toContain("./channel");
+  });
+});

package/src/release/readme.ts

@@ -0,0 +1,13 @@
+/**
+ * Path helpers for the generated budgets markdown document.
+ *
+ * The tables live in `BUDGETS.md` at the repo root (rewritten by
+ * `bun run budgets`). README only links there.
+ */
+
+import { resolve } from "node:path";
+
+const ROOT = resolve(import.meta.dir, "../..");
+
+/** Generated budgets report (markdown tables). */
+export const BUDGETS_MD = resolve(ROOT, "BUDGETS.md");

package/src/runtime/index.ts

@@ -30,6 +30,7 @@ export {
 export {
   APP_PORT,
   CONSOLE_PORT,
+  DOCS_MCP_PORT,
   MCP_PORT,
   type FetchApp,
   type PasswordAlgorithm,

package/src/runtime/security.test.ts

@@ -123,7 +123,7 @@ describe("secureFetch", () => {
   });
 });
 
-describe("Host/Origin entry points (6530 / 6533 / 6535)", () => {
+describe("Host/Origin entry points (6530 / 6533 / 6535 / 6536)", () => {
   test("every HTTP surface routes through checkRequestSecurity", async () => {
     /**
      * Entry-point map (source of truth for §10.1):
@@ -132,6 +132,7 @@ describe("Host/Origin entry points (6530 / 6533 / 6535)", () => {
      *   and checkRequestSecurity before WebSocket upgrade on /console/live
      * - MCP :6535 → mcp/server.ts → checkRequestSecurity (same primitive;
      *   secureFetch is a thin wrapper around it)
+     * - Docs MCP :6536 → mcp/docs-server.ts → checkRequestSecurity
      */
     const surfaces: ReadonlyArray<{
       readonly file: string;
@@ -153,6 +154,10 @@ describe("Host/Origin entry points (6530 / 6533 / 6535)", () => {
         file: `${import.meta.dir}/../mcp/server.ts`,
         mustInclude: ["checkRequestSecurity", "forbiddenResponse"],
       },
+      {
+        file: `${import.meta.dir}/../mcp/docs-server.ts`,
+        mustInclude: ["checkRequestSecurity", "forbiddenResponse"],
+      },
     ];
 
     for (const surface of surfaces) {

package/src/runtime/types.ts

@@ -17,6 +17,12 @@ export const CONSOLE_PORT = 6533;
 /** Default MCP listen port (O·K·E mnemonic). */
 export const MCP_PORT = 6535;
 
+/**
+ * Default docs MCP listen port (read-only documentation search/fetch).
+ * Distinct from {@link MCP_PORT} — serves docs content, not a live Manifest.
+ */
+export const DOCS_MCP_PORT = 6536;
+
 /**
  * Minimal app surface a runtime can serve.
  * Satisfied by {@link import("../kernel/app.ts").OkeApp}.

package/src/term.test.ts

@@ -0,0 +1,51 @@
+/**
+ * Terminal chrome — color off stays plain; claim/banner keep structure.
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  formatAppReadyLine,
+  formatClaimNote,
+  formatDevBanner,
+  formatServiceLine,
+  formatStatusLine,
+  termStyle,
+} from "./term.ts";
+
+describe("term", () => {
+  test("termStyle(false) strips ANSI", () => {
+    const s = termStyle(false);
+    expect(s.cyan).toBe("");
+    expect(s.bold).toBe("");
+  });
+
+  test("formatDevBanner is readable without color", () => {
+    const out = formatDevBanner({ color: false });
+    expect(out).toContain("oke dev");
+    expect(out).toContain("Starting");
+    expect(out).toContain("watching");
+    expect(out).not.toMatch(/\u001b\[/);
+  });
+
+  test("formatServiceLine / formatAppReadyLine include URL", () => {
+    expect(formatServiceLine("Console", "http://127.0.0.1:6533", false)).toContain(
+      "http://127.0.0.1:6533",
+    );
+    expect(formatAppReadyLine("http://127.0.0.1:6530", false)).toContain(
+      "http://127.0.0.1:6530",
+    );
+  });
+
+  test("formatClaimNote embeds code and ownership line", () => {
+    const code = "aabbccddeeff00112233445566778899";
+    const out = formatClaimNote(code, false);
+    expect(out).toContain(code);
+    expect(out).toContain("Claim code");
+    expect(out).toContain("owns the server");
+    expect(out).not.toMatch(/\u001b\[/);
+  });
+
+  test("formatStatusLine keeps message", () => {
+    expect(formatStatusLine("stack up (sql)", false)).toContain("stack up");
+  });
+});