okengine 0.6.0 → 0.6.1

package/src/kernel/boot-bind/channel.test.ts

@@ -1,15 +1,34 @@
 /**
- * Channel binder — profile selection + SMTP env parsing.
+ * Channel binder — profile selection + env parsing.
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
-import { resolveEmailDriverId, smtpOptionsFromEnv } from "./channel.ts";
+import {
+  msegatOptionsFromEnv,
+  resendOptionsFromEnv,
+  resolveEmailDriverId,
+  resolveSmsDriverId,
+  smtpOptionsFromEnv,
+  sndrOptionsFromEnv,
+  taqnyatOptionsFromEnv,
+  unifonicOptionsFromEnv,
+} from "./channel.ts";
 
 const previous = {
   url: process.env.SMTP_URL,
   user: process.env.SMTP_USER,
   password: process.env.SMTP_PASSWORD,
   okeUrl: process.env.OKE_CHANNEL_EMAIL_URL,
+  resend: process.env.RESEND_API_KEY,
+  sndr: process.env.SNDR_API_KEY,
+  sndrBase: process.env.SNDR_BASE_URL,
+  taqBearer: process.env.TAQNYAT_BEARER_TOKEN,
+  taqSender: process.env.TAQNYAT_SENDER,
+  msegatUser: process.env.MSEGAT_USERNAME,
+  msegatKey: process.env.MSEGAT_API_KEY,
+  msegatSender: process.env.MSEGAT_SENDER,
+  unifonicSid: process.env.UNIFONIC_APPSID,
+  unifonicSender: process.env.UNIFONIC_SENDER,
 };
 
 afterEach(() => {
@@ -17,6 +36,16 @@ afterEach(() => {
   restoreEnv("SMTP_USER", previous.user);
   restoreEnv("SMTP_PASSWORD", previous.password);
   restoreEnv("OKE_CHANNEL_EMAIL_URL", previous.okeUrl);
+  restoreEnv("RESEND_API_KEY", previous.resend);
+  restoreEnv("SNDR_API_KEY", previous.sndr);
+  restoreEnv("SNDR_BASE_URL", previous.sndrBase);
+  restoreEnv("TAQNYAT_BEARER_TOKEN", previous.taqBearer);
+  restoreEnv("TAQNYAT_SENDER", previous.taqSender);
+  restoreEnv("MSEGAT_USERNAME", previous.msegatUser);
+  restoreEnv("MSEGAT_API_KEY", previous.msegatKey);
+  restoreEnv("MSEGAT_SENDER", previous.msegatSender);
+  restoreEnv("UNIFONIC_APPSID", previous.unifonicSid);
+  restoreEnv("UNIFONIC_SENDER", previous.unifonicSender);
 });
 
 describe("bindChannel driver resolution", () => {
@@ -24,7 +53,8 @@ describe("bindChannel driver resolution", () => {
     config: {
       drivers: {
         channel: {
-          email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+          email: { local: "console", docker: "smtp", test: "console", prod: "sndr" },
+          sms: { local: "console", docker: "taqnyat", test: "msegat", prod: "taqnyat" },
         },
       },
     },
@@ -33,6 +63,13 @@ describe("bindChannel driver resolution", () => {
   test("uses console locally and smtp in docker", () => {
     expect(resolveEmailDriverId(options, "local", false)).toBe("console");
     expect(resolveEmailDriverId(options, "docker", true)).toBe("smtp");
+    expect(resolveEmailDriverId(options, "prod", false)).toBe("sndr");
+  });
+
+  test("resolves sms driver ids", () => {
+    expect(resolveSmsDriverId(options, "local")).toBe("console");
+    expect(resolveSmsDriverId(options, "docker")).toBe("taqnyat");
+    expect(resolveSmsDriverId(options, "test")).toBe("msegat");
   });
 
   test("parses SMTP_URL and optional auth overrides", () => {
@@ -52,6 +89,34 @@ describe("bindChannel driver resolution", () => {
     delete process.env.OKE_CHANNEL_EMAIL_URL;
     expect(() => smtpOptionsFromEnv(true)).toThrow("docker/.env.docker");
   });
+
+  test("resend and sndr env helpers", () => {
+    process.env.RESEND_API_KEY = "re_x";
+    expect(resendOptionsFromEnv()).toEqual({ apiKey: "re_x" });
+    process.env.SNDR_API_KEY = "sndr_test_x";
+    process.env.SNDR_BASE_URL = "https://api.example.test";
+    expect(sndrOptionsFromEnv()).toEqual({
+      apiKey: "sndr_test_x",
+      url: "https://api.example.test",
+    });
+  });
+
+  test("taqnyat, msegat, and unifonic env helpers", () => {
+    process.env.TAQNYAT_BEARER_TOKEN = "bearer";
+    process.env.TAQNYAT_SENDER = "Brand";
+    expect(taqnyatOptionsFromEnv()).toEqual({ bearerToken: "bearer", sender: "Brand" });
+    process.env.MSEGAT_USERNAME = "user";
+    process.env.MSEGAT_API_KEY = "key";
+    process.env.MSEGAT_SENDER = "Brand";
+    expect(msegatOptionsFromEnv()).toEqual({
+      userName: "user",
+      apiKey: "key",
+      sender: "Brand",
+    });
+    process.env.UNIFONIC_APPSID = "sid";
+    process.env.UNIFONIC_SENDER = "Brand";
+    expect(unifonicOptionsFromEnv()).toEqual({ appSid: "sid", sender: "Brand" });
+  });
 });
 
 function restoreEnv(key: string, value: string | undefined): void {

package/src/kernel/boot-bind/channel.ts

@@ -4,7 +4,12 @@
 
 import { resolveDriverId, type ConfigEnv } from "../../config/index.ts";
 import { openConsoleChannel } from "../../drivers/channel-console.ts";
+import { openMsegatChannel } from "../../drivers/channel-msegat.ts";
+import { openResendChannel } from "../../drivers/channel-resend.ts";
 import { openSmtpChannel } from "../../drivers/channel-smtp.ts";
+import { openSndrChannel } from "../../drivers/channel-sndr.ts";
+import { openTaqnyatChannel } from "../../drivers/channel-taqnyat.ts";
+import { openUnifonicChannel } from "../../drivers/channel-unifonic.ts";
 import type { ChannelDriver, ChannelOpenOptions } from "../../drivers/channel-types.ts";
 import { createChannelRuntime, type ChannelRuntime } from "../../elements/channel.ts";
 import type { BootOptions } from "../boot.ts";
@@ -12,6 +17,9 @@ import type { BootOptions } from "../boot.ts";
 /**
  * Construct a Channel runtime (console inbox default).
  *
+ * When `options.channel.drivers` is omitted, opens the configured email driver
+ * and, if `drivers.channel.sms` resolves, appends that SMS driver to the chain.
+ *
  * @param options - Boot options
  * @param env - Active environment
  * @param now - Clock
@@ -25,18 +33,36 @@ export function bindChannel(
 ): ChannelRuntime {
   return createChannelRuntime({
     ...(options.channel ?? {}),
-    drivers: options.channel?.drivers ?? [channelDriverFor(options, env, docker)],
+    drivers: options.channel?.drivers ?? defaultDrivers(options, env, docker),
     now,
   });
 }
 
-function channelDriverFor(options: BootOptions, env: ConfigEnv, docker: boolean): ChannelDriver {
+function defaultDrivers(options: BootOptions, env: ConfigEnv, docker: boolean): ChannelDriver[] {
+  const drivers: ChannelDriver[] = [emailDriverFor(options, env, docker)];
+  const sms = smsDriverFor(options, env);
+  if (sms) drivers.push(sms);
+  return drivers;
+}
+
+function emailDriverFor(options: BootOptions, env: ConfigEnv, docker: boolean): ChannelDriver {
   const id = resolveEmailDriverId(options, env, docker);
   if (id === "console") return openConsoleChannel();
   if (id === "smtp") return openSmtpChannel(smtpOptionsFromEnv(docker));
+  if (id === "resend") return openResendChannel(resendOptionsFromEnv());
+  if (id === "sndr") return openSndrChannel(sndrOptionsFromEnv());
   throw new Error(`oke boot: unknown email channel driver "${id}"`);
 }
 
+function smsDriverFor(options: BootOptions, env: ConfigEnv): ChannelDriver | undefined {
+  const id = resolveSmsDriverId(options, env);
+  if (!id || id === "console") return undefined;
+  if (id === "taqnyat") return openTaqnyatChannel(taqnyatOptionsFromEnv());
+  if (id === "msegat") return openMsegatChannel(msegatOptionsFromEnv());
+  if (id === "unifonic") return openUnifonicChannel(unifonicOptionsFromEnv());
+  throw new Error(`oke boot: unknown sms channel driver "${id}"`);
+}
+
 /**
  * Resolve the configured email driver for one environment.
  *
@@ -54,6 +80,16 @@ export function resolveEmailDriverId(
   );
 }
 
+/**
+ * Resolve the configured SMS driver for one environment.
+ *
+ * @param options - Boot options
+ * @param env - Active environment
+ */
+export function resolveSmsDriverId(options: BootOptions, env: ConfigEnv): string | undefined {
+  return resolveDriverId(options.config?.drivers?.channel?.sms, env);
+}
+
 /**
  * Resolve SMTP connection options from `SMTP_URL` plus optional auth overrides.
  *
@@ -81,3 +117,58 @@ export function smtpOptionsFromEnv(docker = false): ChannelOpenOptions {
     ...(pass ? { pass } : {}),
   };
 }
+
+/**
+ * Resolve Resend options from env.
+ */
+export function resendOptionsFromEnv(): ChannelOpenOptions {
+  const apiKey = process.env.RESEND_API_KEY?.trim();
+  if (!apiKey) throw new Error("oke boot: resend channel needs RESEND_API_KEY");
+  return { apiKey };
+}
+
+/**
+ * Resolve SNDR options from env.
+ */
+export function sndrOptionsFromEnv(): ChannelOpenOptions {
+  const apiKey = process.env.SNDR_API_KEY?.trim();
+  if (!apiKey) throw new Error("oke boot: sndr channel needs SNDR_API_KEY");
+  const url = process.env.SNDR_BASE_URL?.trim();
+  return { apiKey, ...(url ? { url } : {}) };
+}
+
+/**
+ * Resolve Taqnyat SMS options from env.
+ */
+export function taqnyatOptionsFromEnv(): ChannelOpenOptions {
+  const bearerToken = process.env.TAQNYAT_BEARER_TOKEN?.trim() ?? process.env.TAQNYAT_TOKEN?.trim();
+  const sender = process.env.TAQNYAT_SENDER?.trim();
+  if (!bearerToken) {
+    throw new Error("oke boot: taqnyat channel needs TAQNYAT_BEARER_TOKEN");
+  }
+  if (!sender) throw new Error("oke boot: taqnyat channel needs TAQNYAT_SENDER");
+  return { bearerToken, sender };
+}
+
+/**
+ * Resolve Msegat SMS options from env.
+ */
+export function msegatOptionsFromEnv(): ChannelOpenOptions {
+  const userName = process.env.MSEGAT_USERNAME?.trim();
+  const apiKey = process.env.MSEGAT_API_KEY?.trim();
+  const sender = process.env.MSEGAT_SENDER?.trim();
+  if (!userName) throw new Error("oke boot: msegat channel needs MSEGAT_USERNAME");
+  if (!apiKey) throw new Error("oke boot: msegat channel needs MSEGAT_API_KEY");
+  if (!sender) throw new Error("oke boot: msegat channel needs MSEGAT_SENDER");
+  return { userName, apiKey, sender };
+}
+
+/**
+ * Resolve Unifonic SMS options from env.
+ */
+export function unifonicOptionsFromEnv(): ChannelOpenOptions {
+  const appSid = process.env.UNIFONIC_APPSID?.trim() ?? process.env.UNIFONIC_APP_SID?.trim();
+  const sender = process.env.UNIFONIC_SENDER?.trim();
+  if (!appSid) throw new Error("oke boot: unifonic channel needs UNIFONIC_APPSID");
+  return { appSid, ...(sender ? { sender } : {}) };
+}

package/src/plugins/auth-delivery.mailpit.integration.test.ts

@@ -1,8 +1,9 @@
 /**
  * Real Mailpit end-to-end: magic-link / email-otp request → SMTP → Mailpit API.
  *
- * Gated on a live Docker daemon — same real-skip pattern as pgvector /
- * Meilisearch (`const live = … ? test : test.skip`). Never an empty pass.
+ * Opt-in via `OKE_TEST_DOCKER=1` plus a live Docker daemon — same real-skip
+ * pattern as pgvector / Meilisearch (`const live = … ? test : test.skip`).
+ * Never an empty pass.
  */
 
 import { afterEach, describe, expect, test } from "bun:test";
@@ -36,9 +37,14 @@ function dockerAvailable(): boolean {
   }
 }
 
-const DOCKER = dockerAvailable();
+const WANT = process.env.OKE_TEST_DOCKER === "1";
+const DOCKER = WANT && dockerAvailable();
 if (!DOCKER) {
-  console.log("skip: mailpit e2e (docker daemon not available)");
+  console.log(
+    WANT
+      ? "skip: mailpit e2e (docker daemon not available)"
+      : "skip: mailpit e2e (OKE_TEST_DOCKER≠1)",
+  );
 }
 const live = DOCKER ? test : test.skip;
 

package/src/release/exports.test.ts

@@ -9,7 +9,9 @@ import {
   exportBudgetLabel,
   isMeasurableDriverFile,
   listDriverModules,
+  OFFICIAL_PLUGIN_BUDGETS,
   resolveExportBudgetTargets,
+  resolvePluginBudgetTargets,
 } from "./exports.ts";
 
 const ROOT = resolve(import.meta.dir, "../..");
@@ -29,12 +31,32 @@ describe("export budget targets", () => {
     expect(exportBudgetLabel(".")).toBe("okengine");
     expect(exportBudgetLabel("./channel")).toBe("channel");
     expect(exportBudgetLabel("./drivers/postgres")).toBe("postgres");
+    expect(exportBudgetLabel("./plugins/cors")).toBe("cors");
     expect(exportBudgetGroup(".")).toBe("exports");
     expect(exportBudgetGroup("./channel")).toBe("exports");
+    expect(exportBudgetGroup("./plugins")).toBe("exports");
+    expect(exportBudgetGroup("./plugins/cors")).toBe("plugins");
     expect(exportBudgetGroup("./drivers")).toBe("drivers");
     expect(exportBudgetGroup("./drivers/postgres")).toBe("drivers");
   });
 
+  test("official plugin catalogue files exist and resolve uniquely", async () => {
+    const plugins = resolvePluginBudgetTargets();
+    expect(plugins.length).toBe(OFFICIAL_PLUGIN_BUDGETS.length);
+    expect(new Set(plugins.map((t) => t.id)).size).toBe(plugins.length);
+
+    for (const plugin of OFFICIAL_PLUGIN_BUDGETS) {
+      const path = join(ROOT, "src/plugins", plugin.file);
+      expect(await Bun.file(path).exists()).toBe(true);
+      const target = plugins.find((t) => t.label === plugin.name);
+      expect(target).toBeDefined();
+      expect(target!.id).toBe(`export:./plugins/${plugin.name}`);
+      expect(target!.group).toBe("plugins");
+      expect(target!.category).toBe(plugin.category);
+      expect(target!.entry).toBe(path);
+    }
+  });
+
   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>;
@@ -65,6 +87,10 @@ describe("export budget targets", () => {
       expect(target!.entry).toBe(join(ROOT, "src/drivers", file));
     }
 
+    for (const plugin of OFFICIAL_PLUGIN_BUDGETS) {
+      expect(bySubpath.get(`./plugins/${plugin.name}`)).toBeDefined();
+    }
+
     // No duplicates.
     expect(new Set(targets.map((t) => t.id)).size).toBe(targets.length);
   });

package/src/release/exports.ts

@@ -2,22 +2,37 @@
  * Resolve published `package.json` exports into measurable bundle entries.
  *
  * Expands `./drivers/*` to concrete driver modules (tree-shaken subpaths).
+ * Official `okengine/plugins` named modules are sampled separately (not published
+ * as `./plugins/*` subpaths).
  */
 
 import { readdir } from "node:fs/promises";
 import { basename, join, resolve } from "node:path";
+import {
+  OFFICIAL_PLUGIN_BUDGETS,
+  type OfficialPluginBudget,
+  type PluginBudgetCategory,
+} from "./official-plugins.ts";
+
+export {
+  OFFICIAL_PLUGIN_BUDGETS,
+  PLUGIN_BUDGET_CATEGORIES,
+  type OfficialPluginBudget,
+  type PluginBudgetCategory,
+} from "./official-plugins.ts";
 
 const ROOT = resolve(import.meta.dir, "../..");
 const DRIVERS_DIR = join(ROOT, "src/drivers");
+const PLUGINS_DIR = join(ROOT, "src/plugins");
 
 /** Report / snapshot group for a budget sample. */
-export type BudgetGroup = "core" | "exports" | "drivers";
+export type BudgetGroup = "core" | "exports" | "plugins" | "drivers";
 
 /** One published subpath ready for gzip measurement. */
 export interface ExportBudgetTarget {
   /** Sample id — `export:<subpath>`. */
   readonly id: string;
-  /** Package subpath (`.` or `./store`, `./drivers/postgres`, …). */
+  /** Package subpath (`.` or `./store`, `./drivers/postgres`, `./plugins/cors`, …). */
   readonly subpath: string;
   /** Short human label (`channel`, `postgres`, `okengine`, …). */
   readonly label: string;
@@ -25,18 +40,23 @@ export interface ExportBudgetTarget {
   readonly group: BudgetGroup;
   /** Absolute path to the TypeScript entry. */
   readonly entry: string;
+  /** Docs category when `group` is `plugins`. */
+  readonly category?: PluginBudgetCategory;
 }
 
 /**
  * Short display name for a package subpath.
  *
- * @param subpath - `.` / `./channel` / `./drivers/postgres`
+ * @param subpath - `.` / `./channel` / `./drivers/postgres` / `./plugins/cors`
  */
 export function exportBudgetLabel(subpath: string): string {
   if (subpath === ".") return "okengine";
   if (subpath.startsWith("./drivers/")) {
     return subpath.slice("./drivers/".length);
   }
+  if (subpath.startsWith("./plugins/")) {
+    return subpath.slice("./plugins/".length);
+  }
   if (subpath.startsWith("./")) return subpath.slice(2);
   return subpath;
 }
@@ -50,6 +70,10 @@ export function exportBudgetGroup(subpath: string): BudgetGroup {
   if (subpath === "./drivers" || subpath.startsWith("./drivers/")) {
     return "drivers";
   }
+  // Named plugin modules (not the `./plugins` barrel — that stays in exports).
+  if (subpath.startsWith("./plugins/")) {
+    return "plugins";
+  }
   return "exports";
 }
 
@@ -82,6 +106,30 @@ export async function listDriverModules(driversDir = DRIVERS_DIR): Promise<reado
   return entries.filter(isMeasurableDriverFile).sort((a, b) => a.localeCompare(b));
 }
 
+/**
+ * Resolve official plugin modules into measurement targets.
+ *
+ * @param options - Override plugins dir (tests)
+ */
+export function resolvePluginBudgetTargets(options?: {
+  readonly pluginsDir?: string;
+  readonly catalogue?: readonly OfficialPluginBudget[];
+}): readonly ExportBudgetTarget[] {
+  const pluginsDir = options?.pluginsDir ?? PLUGINS_DIR;
+  const catalogue = options?.catalogue ?? OFFICIAL_PLUGIN_BUDGETS;
+  return catalogue.map((plugin) => {
+    const subpath = `./plugins/${plugin.name}`;
+    return {
+      id: `export:${subpath}`,
+      subpath,
+      label: plugin.name,
+      group: "plugins" as const,
+      entry: join(pluginsDir, plugin.file),
+      category: plugin.category,
+    };
+  });
+}
+
 /**
  * Resolve every published export into a stable, sorted measurement target list.
  *
@@ -91,12 +139,14 @@ export async function resolveExportBudgetTargets(options?: {
   readonly root?: string;
   readonly pkg?: PackageExports;
   readonly driversDir?: string;
+  readonly pluginsDir?: string;
 }): Promise<readonly ExportBudgetTarget[]> {
   const root = options?.root ?? ROOT;
   const pkg =
     options?.pkg ?? ((await Bun.file(join(root, "package.json")).json()) as PackageExports);
   const exportsMap = pkg.exports ?? {};
   const driversDir = options?.driversDir ?? join(root, "src/drivers");
+  const pluginsDir = options?.pluginsDir ?? join(root, "src/plugins");
 
   const targets: ExportBudgetTarget[] = [];
 
@@ -121,6 +171,8 @@ export async function resolveExportBudgetTargets(options?: {
     targets.push(targetFor(subpath, resolve(root, entryRel)));
   }
 
+  targets.push(...resolvePluginBudgetTargets({ pluginsDir }));
+
   targets.sort((a, b) => {
     const g = groupOrder(a.group) - groupOrder(b.group);
     if (g !== 0) return g;
@@ -129,6 +181,12 @@ export async function resolveExportBudgetTargets(options?: {
     if (b.subpath === "./drivers") return 1;
     if (a.subpath === ".") return -1;
     if (b.subpath === ".") return 1;
+    // Catalogue order for plugins (docs category order).
+    if (a.group === "plugins" && b.group === "plugins") {
+      const ai = OFFICIAL_PLUGIN_BUDGETS.findIndex((p) => p.name === a.label);
+      const bi = OFFICIAL_PLUGIN_BUDGETS.findIndex((p) => p.name === b.label);
+      if (ai !== -1 && bi !== -1) return ai - bi;
+    }
     return a.label.localeCompare(b.label);
   });
   return targets;
@@ -146,6 +204,7 @@ function targetFor(subpath: string, entry: string): ExportBudgetTarget {
 
 function groupOrder(group: BudgetGroup): number {
   if (group === "exports") return 0;
-  if (group === "drivers") return 1;
-  return 2;
+  if (group === "plugins") return 1;
+  if (group === "drivers") return 2;
+  return 3;
 }

package/src/release/index.ts

@@ -7,9 +7,14 @@ export {
   exportBudgetLabel,
   isMeasurableDriverFile,
   listDriverModules,
+  OFFICIAL_PLUGIN_BUDGETS,
+  PLUGIN_BUDGET_CATEGORIES,
   resolveExportBudgetTargets,
+  resolvePluginBudgetTargets,
   type BudgetGroup,
   type ExportBudgetTarget,
+  type OfficialPluginBudget,
+  type PluginBudgetCategory,
 } from "./exports.ts";
 
 export {

package/src/release/measure.exports.test.ts

@@ -31,7 +31,7 @@ describe("export gzip budgets", () => {
     );
   });
 
-  test("formatBudgetsReport groups Core / Exports / Drivers with short names", () => {
+  test("formatBudgetsReport groups Core / Exports / Plugins / Drivers with short names", () => {
     const snapshot: BudgetsSnapshot = {
       measuredAt: "2026-07-25T00:00:00.000Z",
       version: "0.0.0",
@@ -56,6 +56,16 @@ describe("export gzip budgets", () => {
           group: "exports",
           ok: true,
         },
+        {
+          id: "export:./plugins/cors",
+          label: "cors",
+          value: 100,
+          limit: 200,
+          unit: "bytes",
+          gate: "regression",
+          group: "plugins",
+          ok: true,
+        },
         {
           id: "export:./drivers/postgres",
           label: "postgres",
@@ -71,8 +81,10 @@ describe("export gzip budgets", () => {
     const report = formatBudgetsReport(snapshot);
     expect(report).toContain("\nCore\n");
     expect(report).toContain("\nExports\n");
+    expect(report).toContain("\nPlugins\n");
     expect(report).toContain("\nDrivers\n");
     expect(report).toContain("[ok] channel:");
+    expect(report).toContain("[ok] cors:");
     expect(report).toContain("[ok] postgres:");
     expect(report).not.toContain("regression Export");
     expect(report).not.toContain("./channel");

package/src/release/measure.ts

@@ -6,7 +6,12 @@ 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 {
+  type BudgetGroup,
+  OFFICIAL_PLUGIN_BUDGETS,
+  PLUGIN_BUDGET_CATEGORIES,
+  resolveExportBudgetTargets,
+} from "./exports.ts";
 import {
   CLIENT_BUDGET_BYTES,
   COLD_START_BUDGET_MS,
@@ -56,9 +61,18 @@ export type BudgetGate = "absolute" | "regression";
 const GROUP_HEADINGS: Readonly<Record<BudgetGroup, string>> = {
   core: "Core",
   exports: "Exports",
+  plugins: "Plugins",
   drivers: "Drivers",
 };
 
+/** Docs category → markdown subheading under Plugins. */
+const PLUGIN_CATEGORY_HEADINGS: Readonly<Record<string, string>> = {
+  auth: "Auth",
+  security: "Security",
+  ops: "Ops",
+  perf: "Perf",
+};
+
 /** One measured budget sample. */
 export interface BudgetSample {
   /** Stable metric id. */
@@ -489,13 +503,13 @@ export async function measureAllBudgets(): Promise<BudgetsSnapshot> {
 }
 
 /**
- * Format a snapshot for CI logs (Core / Exports / Drivers sections).
+ * Format a snapshot for CI logs (Core / Exports / Plugins / Drivers).
  *
  * @param snapshot - Measured budgets
  */
 export function formatBudgetsReport(snapshot: BudgetsSnapshot): string {
   const lines = [`okengine budgets v${snapshot.version} @ ${snapshot.measuredAt}`];
-  const order: readonly BudgetGroup[] = ["core", "exports", "drivers"];
+  const order: readonly BudgetGroup[] = ["core", "exports", "plugins", "drivers"];
   for (const group of order) {
     const rows = snapshot.budgets.filter((b) => b.group === group);
     if (rows.length === 0) continue;
@@ -511,6 +525,28 @@ export function formatBudgetsReport(snapshot: BudgetsSnapshot): string {
   return `${lines.join("\n")}\n`;
 }
 
+/**
+ * Markdown table with column widths padded so `oxfmt` is a no-op.
+ * Compact `|---|` tables get realigned by oxfmt and make Format fail after
+ * every `bun run budgets` refresh.
+ *
+ * @param headers - Column headers (use `""` for an unnamed first column)
+ * @param rows - Body cells
+ */
+export function formatMarkdownTable(
+  headers: readonly string[],
+  rows: readonly (readonly string[])[],
+): string[] {
+  const widths = headers.map((header, i) =>
+    Math.max(header.length, ...rows.map((row) => (row[i] ?? "").length)),
+  );
+  const cell = (value: string, i: number): string => value.padEnd(widths[i]!);
+  const line = (cells: readonly string[]): string =>
+    `| ${cells.map((value, i) => cell(value, i)).join(" | ")} |`;
+  const sep = `| ${widths.map((w) => "-".repeat(w)).join(" | ")} |`;
+  return [line(headers), sep, ...rows.map((row) => line(row))];
+}
+
 /**
  * Full markdown document for [`BUDGETS.md`](../../BUDGETS.md).
  * Written by `bun run budgets` — do not edit the tables by hand.
@@ -525,24 +561,51 @@ export function formatBudgetsMarkdown(snapshot: BudgetsSnapshot): string {
     "",
     `_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`, `sently`, `oxc-parser`, `ajv`).",
+    "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`).",
   ];
-  const order: readonly BudgetGroup[] = ["core", "exports", "drivers"];
+  const order: readonly BudgetGroup[] = ["core", "exports", "plugins", "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)} |`,
-      );
+    if (group === "plugins") {
+      for (const category of PLUGIN_BUDGET_CATEGORIES) {
+        const names = new Set(
+          OFFICIAL_PLUGIN_BUDGETS.filter((p) => p.category === category).map((p) => p.name),
+        );
+        const catRows = rows.filter((b) => names.has(b.label));
+        if (catRows.length === 0) continue;
+        lines.push("");
+        lines.push(`### ${PLUGIN_CATEGORY_HEADINGS[category] ?? category}`);
+        lines.push("");
+        lines.push(
+          ...formatMarkdownTable(
+            ["", "Measured", limitCol],
+            catRows.map((b) => {
+              const mark = b.ok ? "" : " **FAIL**";
+              return [
+                `${b.label}${mark}`,
+                formatValue(b.value, b.unit),
+                formatValue(b.limit, b.unit),
+              ];
+            }),
+          ),
+        );
+      }
+      continue;
     }
+    lines.push("");
+    lines.push(
+      ...formatMarkdownTable(
+        ["", "Measured", limitCol],
+        rows.map((b) => {
+          const mark = b.ok ? "" : " **FAIL**";
+          return [`${b.label}${mark}`, formatValue(b.value, b.unit), formatValue(b.limit, b.unit)];
+        }),
+      ),
+    );
   }
   return `${lines.join("\n")}\n`;
 }