okengine 0.21.0 → 0.22.0

package/site/content/docs/understand/try-it.mdx

@@ -405,7 +405,7 @@ test("creates a user", async () => {
 bun test # [!code focus]
 ```
 
-`createTestApp` swaps every driver behind `fx` for a deterministic one.
+`createTestApp` swaps every driver behind `fx` for a deterministic one. It stamps Manifest tokens. Inline flows that are not an app pass `capability: "open"`.
 
 </Step>
 
@@ -762,7 +762,7 @@ return await fx.ask(triage, { message }); // [!code focus]
 
 ## Learn more
 
-- [Routing](/docs/elements/flow/routing) — when to omit the path, `list` / `create` / `get` filenames
+- [Routing](/docs/understand/routing) — when to omit the path, `list` / `create` / `get` filenames
 - [Flow](/docs/elements/flow) — one species; `fx` is the door
 - [Signal](/docs/elements/signal) — `once` / `broadcast` / `live`
 - [Store](/docs/elements/store) — SQL, KV, files, search
@@ -775,7 +775,7 @@ return await fx.ask(triage, { message }); // [!code focus]
   <Card
     title="Routing"
     description="File-tree stamps, many-routes files, and reserved leaves."
-    href="/docs/elements/flow/routing"
+    href="/docs/understand/routing"
   />
   <Card title="Flow" description="on(trigger) → do through fx." href="/docs/elements/flow" />
   <Card title="Signal" description="Move work off the request." href="/docs/elements/signal" />

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

@@ -11,8 +11,8 @@ import { join } from "node:path";
 
 const ROOT = join(import.meta.dir, "../..");
 
-/** Forbidden peer name — split so this file does not match itself. */
-const FORBIDDEN_HONO = ["Ho", "no"].join("");
+/** Word-boundary router peer — `-F` false-positives on `Honored` / `canHonor`. */
+const FORBIDDEN_HONO = ["\\b", "Ho", "no", "\\b"].join("");
 /** Forbidden peer name. */
 const FORBIDDEN_ELYSIA = ["Ely", "sia"].join("");
 /** Forbidden peer name (covers Enc + ore.ts). */
@@ -104,7 +104,7 @@ function assertZeroGitGrepRegex(pattern: string, ignorePrefixes: readonly string
 
 describe("named competitor mention removal gate", () => {
   test("tracked tree has zero mentions of the thin multi-runtime router peer", () => {
-    assertZeroGitGrepFixed(FORBIDDEN_HONO);
+    assertZeroGitGrepRegex(FORBIDDEN_HONO);
   });
 
   test("tracked tree has zero mentions of the Bun-first peer framework", () => {

package/src/cli/dev.test.ts

@@ -6,7 +6,7 @@
  * context and exercises `oke.manifest.get` over HTTP on :6535.
  */
 
-import { afterEach, describe, expect, test } from "bun:test";
+import { afterEach, describe, expect, mock, test } from "bun:test";
 import { mkdir, mkdtemp, readdir } from "node:fs/promises";
 import { tmpdir } from "node:os";
 import { join, resolve } from "node:path";
@@ -17,9 +17,19 @@ import {
 } from "../compiler/generate-adopt.ts";
 import type { Manifest } from "../manifest/types.ts";
 import type { WideEvent } from "../runs/types.ts";
+import type { ConsoleAppHandle } from "../console/server/app.ts";
+import { createConsoleState } from "../console/server/state.ts";
 import { isDataEnvelope, MCP_DATA_KIND } from "../mcp/data.ts";
 import { mintMcpSession } from "../mcp/session.ts";
-import { isFlowsTreeWatchPath, runDev, type DevOptions, type DevSession } from "./dev.ts";
+import {
+  CLIENT_REGEN_DEBOUNCE_MS,
+  isClientRegenWatchPath,
+  isFlowsTreeWatchPath,
+  runDev,
+  type DevOptions,
+  type DevSession,
+  type DevWatchFn,
+} from "./dev.ts";
 import { mcpContextFromConsole } from "./mcp-from-console.ts";
 
 /** Repo public entry — absolute import so temp apps need no install. */
@@ -803,6 +813,99 @@ describe("isFlowsTreeWatchPath", () => {
   });
 });
 
+describe("isClientRegenWatchPath", () => {
+  test("flow files and schema declares regenerate the client; unrelated files do not", () => {
+    expect(isClientRegenWatchPath("flows/notes/get.ts")).toBe(true);
+    expect(isClientRegenWatchPath("schema.ts")).toBe(true);
+    expect(isClientRegenWatchPath("db/schema/links.ts")).toBe(true);
+    expect(isClientRegenWatchPath("lib/util.ts")).toBe(false);
+    expect(isClientRegenWatchPath("flows/index.ts")).toBe(false);
+    expect(isClientRegenWatchPath("flows/notes/get.ts.tmp")).toBe(false);
+    expect(isClientRegenWatchPath("db/drizzle/schema.ts")).toBe(false);
+  });
+});
+
+describe("oke dev client regen watch", () => {
+  let session: DevSession | undefined;
+
+  afterEach(() => {
+    session?.stop();
+    session = undefined;
+    mock.restore();
+  });
+
+  test("three flow saves within 50ms regenerate the client once", async () => {
+    const dir = await mkdtemp(join(tmpdir(), "oke-dev-regen-"));
+    await mkdir(join(dir, "src"), { recursive: true });
+    await Bun.write(join(dir, "src/app.ts"), "export {};\n");
+
+    const extractMod = await import("../compiler/extract.ts");
+    const originalExtract = extractMod.extractManifest;
+    let extracts = 0;
+    mock.module(resolve(import.meta.dir, "../compiler/extract.ts"), () => ({
+      ...extractMod,
+      extractManifest: (opts: Parameters<typeof originalExtract>[0]) => {
+        extracts++;
+        return originalExtract(opts);
+      },
+    }));
+
+    let regens = 0;
+    let listener: Parameters<DevWatchFn>[2] | undefined;
+    const result = await runDev({
+      cwd: dir,
+      stdinIsTTY: false,
+      appPort: 0,
+      consolePort: 0,
+      mcpPort: 0,
+      ...stubSurfaces(),
+      serveConsole: async () => ({
+        port: 0,
+        stop() {},
+        console: {
+          state: createConsoleState({ cwd: dir, secret: SECRET }),
+        } as ConsoleAppHandle,
+      }),
+      startApp: async () => ({
+        port: 0,
+        url: new URL("http://127.0.0.1:9"),
+        stop() {},
+      }),
+      syncAdoptBarrel: async () => [],
+      regenClient: async () => {
+        regens++;
+      },
+      watchFs: (_path, _options, next) => {
+        listener = next;
+        return { close() {} };
+      },
+    });
+
+    expect(result.code).toBe(0);
+    session = result.session;
+    const boot = regens;
+    expect(boot).toBe(1);
+    const extractsAfterBoot = extracts;
+    expect(extractsAfterBoot).toBeGreaterThan(0);
+    if (!listener) throw new Error("watcher not started");
+
+    listener("change", "flows/notes/get.ts");
+    listener("change", "flows/notes/list.ts");
+    listener("change", "flows/notes/[id]/delete.ts");
+    await Bun.sleep(50);
+    expect(regens).toBe(boot);
+    expect(extracts).toBe(extractsAfterBoot);
+
+    await Bun.sleep(CLIENT_REGEN_DEBOUNCE_MS + 80);
+    expect(regens).toBe(boot + 1);
+    expect(extracts).toBe(extractsAfterBoot + 1);
+
+    listener("change", "lib/util.ts");
+    await Bun.sleep(CLIENT_REGEN_DEBOUNCE_MS + 80);
+    expect(regens).toBe(boot + 1);
+  });
+});
+
 describe("oke dev Docker-first", () => {
   test("dryRun always plans compose (no mode ask)", async () => {
     const dir = await mkdtemp(join(tmpdir(), "oke-dev-always-compose-"));

package/src/cli/dev.ts

@@ -1417,15 +1417,26 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
 
   const watchFs: DevWatchFn =
     options.watchFs ?? ((path, watchOptions, listener) => watch(path, watchOptions, listener));
+  // Trailing timer, always re-armed. A burst resets the window and still
+  // fires once after it goes quiet — a timestamp check that only `return`s
+  // drops the save and never regenerates.
+  const clientRegen = createDebouncedRunner(() => {
+    void regen(appUrl);
+  }, CLIENT_REGEN_DEBOUNCE_MS);
+  const manifestRefresh = createDebouncedRunner(() => {
+    void refreshManifestInto(consoleState);
+  }, CLIENT_REGEN_DEBOUNCE_MS);
   const watcher = watchFs(resolve(cwd, "src"), { recursive: true }, (_event, filename) => {
     const rel = (filename?.toString() ?? "").replace(/\\/g, "/");
     if (isFlowsTreeWatchPath(rel)) {
       void syncAdoptBarrel(cwd);
     }
-    void regen(appUrl);
+    if (isClientRegenWatchPath(rel)) {
+      clientRegen.trigger();
+    }
     // Only live-extract when the host did not pin a Manifest (tests).
     if (options.manifest === undefined) {
-      void refreshManifestInto(consoleState);
+      manifestRefresh.trigger();
     }
     if (autoPushEnabled && isDomainSchemaWatchPath(filename?.toString())) {
       lastSchemaFilename = filename?.toString() ?? "schema.ts";
@@ -1444,6 +1455,8 @@ export async function runDev(options: DevOptions = {}): Promise<DevResult> {
     stopComposeHealthWatch = null;
     bootBoard.stop();
     autoPushRunner.cancel();
+    clientRegen.cancel();
+    manifestRefresh.cancel();
     watcher.close();
     const host = attachedHost;
     attachedHost = null;
@@ -1613,6 +1626,28 @@ export function isFlowsTreeWatchPath(rel: string): boolean {
   return true;
 }
 
+/** Quiet window before one `oke-client.d.ts` regen after a burst of saves. */
+export const CLIENT_REGEN_DEBOUNCE_MS = 200;
+
+/**
+ * True when a `src/` watcher event can change the typed client
+ * (flow files, or a schema declare module those flows import).
+ *
+ * Editor temp files and the adopt barrel are excluded so a regen cannot
+ * retrigger itself.
+ *
+ * @param rel - Watcher filename (POSIX or Windows)
+ */
+export function isClientRegenWatchPath(rel: string): boolean {
+  const posix = rel.replace(/\\/g, "/");
+  if (posix.endsWith(".tmp")) return false;
+  if (isFlowsTreeWatchPath(posix)) return true;
+  if (/(^|\/)drizzle\//.test(posix)) return false;
+  if (/(^|\/)schema(\.decl)?\.tsx?$/.test(posix)) return true;
+  if (/(^|\/)schema\/.+\.tsx?$/.test(posix)) return true;
+  return false;
+}
+
 /**
  * Frame a schema-sync failure for the `oke dev` loop: warn loud for developer
  * bugs, soft-skip only known environmental gaps. Never crashes the session.

package/src/cli/docker-cli.test.ts

@@ -72,7 +72,7 @@ describe("oke stack", () => {
     const code = await runStackPreview({
       cwd: dir,
       images: {
-        "channel.email": "axllent/mailpit:v1.31.1",
+        "channel.email": "axllent/mailpit:v1.31.2",
       },
       write: (t) => {
         out += t;

package/src/cli/index.ts

@@ -5,6 +5,7 @@
  * Bare `oke` (TTY) → interactive Ink TUI. `oke <command>` runs directly.
  */
 
+import type { VaultAuditConfig } from "../elements/vault/types.ts";
 import { aiCli } from "./ai.ts";
 import { branchCli } from "./branch.ts";
 import { buildCli } from "./build.ts";
@@ -28,6 +29,7 @@ import { stackCli } from "./stack.ts";
 import { startCli } from "./start.ts";
 import { testCli } from "./test.ts";
 import { upgradeCli } from "./upgrade.ts";
+import { loadOkeConfig } from "./load-config.ts";
 import { vaultCli } from "./vault-cmd.ts";
 
 const rawArgv = process.argv.slice(2);
@@ -90,7 +92,13 @@ if (cmd === "client" && sub === "add") {
 }
 
 if (cmd === "vault") {
-  process.exit(await vaultCli(sub ? [sub, ...rest] : rest));
+  let audit: VaultAuditConfig | undefined;
+  try {
+    audit = (await loadOkeConfig()).config.vault?.audit;
+  } catch {
+    audit = undefined;
+  }
+  process.exit(await vaultCli(sub ? [sub, ...rest] : rest, audit === undefined ? {} : { audit }));
 }
 
 if (cmd === "docker") {

package/src/cli/load-config.images.test.ts

@@ -18,19 +18,19 @@ describe("flattenImagesConfig", () => {
           sql: "postgres:18-alpine",
           kv: "redis:8-alpine",
           files: "rustfs/rustfs:1.0.0",
-          index: "getmeili/meilisearch:v1.53",
+          index: "getmeili/meilisearch:v1.54",
         },
-        channel: { email: "axllent/mailpit:v1.31.1" },
-        pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
+        channel: { email: "axllent/mailpit:v1.31.2" },
+        pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.59",
         proxy: "caddy:2-alpine",
       }),
     ).toEqual({
       "store.sql": "postgres:18-alpine",
       "store.kv": "redis:8-alpine",
       "store.files": "rustfs/rustfs:1.0.0",
-      "store.index": "getmeili/meilisearch:v1.53",
-      "channel.email": "axllent/mailpit:v1.31.1",
-      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
+      "store.index": "getmeili/meilisearch:v1.54",
+      "channel.email": "axllent/mailpit:v1.31.2",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.59",
       proxy: "caddy:2-alpine",
     });
   });
@@ -53,7 +53,7 @@ describe("defaultImagesFromConfig", () => {
     });
     expect(images).toEqual({
       "store.sql": "postgres:18-alpine",
-      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.59",
       "store.kv": "redis:8-alpine",
     });
   });
@@ -68,7 +68,7 @@ describe("defaultImagesFromConfig", () => {
       },
     });
     expect(images["store.sql"]).toBe("pgvector/pgvector:pg17");
-    expect(images.pgdog).toBe("ghcr.io/pgdogdev/pgdog:v0.1.57");
+    expect(images.pgdog).toBe("ghcr.io/pgdogdev/pgdog:v0.1.59");
   });
 
   test("clock postgres alone pulls store.sql image", () => {
@@ -79,7 +79,7 @@ describe("defaultImagesFromConfig", () => {
     });
     expect(images).toEqual({
       "store.sql": "postgres:18-alpine",
-      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.59",
     });
   });
 
@@ -91,7 +91,7 @@ describe("defaultImagesFromConfig", () => {
     });
     expect(images).toEqual({
       "store.sql": "postgres:18-alpine",
-      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.57",
+      pgdog: "ghcr.io/pgdogdev/pgdog:v0.1.59",
     });
   });
 

package/src/cli/load-config.ts

@@ -15,7 +15,7 @@ import type { Manifest } from "../manifest/types.ts";
 /** Default image pins when `images` is omitted but prod drivers need containers. */
 const DEFAULT_SQL_IMAGE = "postgres:18-alpine";
 const DEFAULT_PGVECTOR_IMAGE = "pgvector/pgvector:pg17";
-const DEFAULT_PGDOG_IMAGE = "ghcr.io/pgdogdev/pgdog:v0.1.57";
+const DEFAULT_PGDOG_IMAGE = "ghcr.io/pgdogdev/pgdog:v0.1.59";
 const DEFAULT_KV_IMAGE = "redis:8-alpine";
 
 /**

package/src/cli/vault-cmd.test.ts

@@ -282,6 +282,29 @@ describe("oke vault audit", () => {
       await h.close();
     }
   });
+
+  test("audit verify refuses a webhook sink", async () => {
+    const sql = createMemoryVaultSql();
+    const errors: string[] = [];
+    const original = console.error;
+    console.error = (...args: unknown[]) => {
+      errors.push(args.map((part) => String(part)).join(" "));
+    };
+    try {
+      const code = await vaultCli(["audit", "verify"], {
+        sql,
+        env: {},
+        stdinIsTTY: false,
+        audit: { sink: "webhook", webhookUrl: "https://audit.example/hook" },
+        write: () => undefined,
+      });
+      expect(code).toBe(1);
+      expect(errors.join("\n")).toContain('audit.sink "db"');
+    } finally {
+      console.error = original;
+      await sql.close();
+    }
+  });
 });
 
 describe("oke vault backup / restore", () => {

package/src/cli/vault-cmd.ts

@@ -24,6 +24,7 @@ import type { SqlConnection } from "../drivers/types.ts";
 import { openBuiltinVaultAdapter, VAULT_MASTER_KEY_ENV } from "../drivers/vault-builtin.ts";
 import { parseDotenv, formatDotenv } from "../drivers/vault-dotenv-parse.ts";
 import type { BuiltinVaultAdapter } from "../elements/vault/builtin-adapter.ts";
+import type { VaultAuditConfig } from "../elements/vault/types.ts";
 import { promptHidden, readStdinSecure } from "./vault-secure-input.ts";
 
 /** Env var for the *new* master key when resuming an interrupted `rotate-master`. */
@@ -70,6 +71,11 @@ export interface VaultCmdOptions {
    * closes a connection it did not open.
    */
   readonly sql?: SqlConnection;
+  /**
+   * `vault.audit` from `oke.config.ts`. The `oke` binary loads this; tests
+   * pass it directly. Omitted means the SQL hash chain.
+   */
+  readonly audit?: VaultAuditConfig;
 }
 
 /**
@@ -332,6 +338,7 @@ async function withVault<T>(
     masterKey,
     ...(flags.url === undefined ? {} : { url: flags.url }),
     ...(options.sql === undefined ? {} : { connection: options.sql }),
+    ...(options.audit === undefined ? {} : { audit: options.audit }),
   });
   try {
     return await run(opened.adapter);

package/src/client/create.ts

@@ -12,7 +12,7 @@
  * Untriggered flows fall back to `POST /_oke/{unit}/{flow}` RPC.
  */
 
-import { createTransport, type Transport } from "./transport.ts";
+import { createTransport, transportEnvelope, type Transport } from "./transport.ts";
 import { asThenableIterable, attachPager } from "./pager.ts";
 import {
   flattenLiveRoutes,
@@ -33,6 +33,7 @@ import type {
   LiveHandlers,
   ResolveApp,
 } from "./types.ts";
+import { methodAndPath, walkContracts } from "./wire.ts";
 
 /** App-shaped value that carries a runtime `$routes` table from typed adopt. */
 export interface AppWithRoutes {
@@ -169,19 +170,11 @@ function mergeHeaders(base: ClientHeaders | undefined, over: ClientHeaders): Cli
 export function flattenRoutes(
   $routes: ClientRouteMap | undefined,
 ): ClientOptions["routes"] | undefined {
-  if (!$routes) return undefined;
   const out: Record<string, { readonly method: string; readonly path: string }> = {};
-  for (const [unit, flows] of Object.entries($routes)) {
-    if (!flows || typeof flows !== "object") continue;
-    for (const [flow, contract] of Object.entries(flows)) {
-      if (!contract || typeof contract !== "object") continue;
-      const method = "method" in contract ? contract.method : undefined;
-      const path = "path" in contract ? contract.path : undefined;
-      if (typeof method === "string" && typeof path === "string") {
-        out[`${unit}.${flow}`] = { method, path };
-      }
-    }
-  }
+  walkContracts($routes, (unit, flow, contract) => {
+    const route = methodAndPath(contract);
+    if (route) out[`${unit}.${flow}`] = route;
+  });
   return Object.keys(out).length > 0 ? out : undefined;
 }
 
@@ -196,25 +189,19 @@ function proxy(transport: Transport, path: readonly string[], ctx: ProxyCtx): un
     if (path.length < 2) {
       const message = `Incomplete path: api.${path.join(".") || "?"}(…)`;
       return attachPager(
-        {
-          data: null,
-          error: {
-            code: "TransportError" as const,
-            message,
-            data: { message },
-          },
-        },
+        transportEnvelope(message),
         (nextInput) => invoke(nextInput, callOpts),
         input,
       );
     }
     const unit = path[0]!;
     const flow = path.slice(1).join(".");
-    const result = await transport.call(`${unit}/${flow}`, input, {
-      headers: ctx.perCallHeaders.read(),
-      ...(callOpts?.response !== undefined ? { response: callOpts.response } : {}),
-      ...(callOpts?.signal !== undefined ? { signal: callOpts.signal } : {}),
-    });
+    const headers = ctx.perCallHeaders.read();
+    const result = await transport.call(
+      `${unit}/${flow}`,
+      input,
+      callOpts ? { headers, ...callOpts } : headers,
+    );
     return attachPager(result, (nextInput) => invoke(nextInput, callOpts), input);
   };
   const call = (a?: unknown, b?: unknown): unknown => {
@@ -351,11 +338,28 @@ function isCallOpts(value: unknown): value is CallOpts {
   if ("signal" in v) {
     return v.signal === undefined || v.signal instanceof AbortSignal;
   }
+  const keyOk =
+    "idempotencyKey" in v && (typeof v.idempotencyKey === "string" || v.idempotencyKey === false);
+  if (("retry" in v && typeof v.retry === "boolean") || keyOk) {
+    return Object.keys(v).every(
+      (k) => k === "response" || k === "signal" || k === "retry" || k === "idempotencyKey",
+    );
+  }
   return false;
 }
 
-/** Per-call options on a Flow invoke (binary decode / abort). */
+/** Per-call options on a Flow invoke (binary decode, abort, retry opt-in). */
 export interface CallOpts {
   readonly response?: "json" | "blob" | "arrayBuffer";
   readonly signal?: AbortSignal;
+  /**
+   * Repeat this call under the client `retry` policy even when it sends
+   * no idempotency key.
+   */
+  readonly retry?: boolean;
+  /**
+   * Stable `Idempotency-Key`, or `false` to send none.
+   * See {@link ClientCallOpts.idempotencyKey}.
+   */
+  readonly idempotencyKey?: string | false;
 }