okengine 0.20.0 → 0.21.1

package/src/kernel/app.ts

@@ -17,7 +17,6 @@ import {
   type RoutesFromNamespace,
   type RuntimeRouteMap,
 } from "./adopt-routes.ts";
-import { buildClientDescriptor } from "./client-descriptor.ts";
 import { liveExposureKey, liveGatesKey, liveMatchKeyFromPath } from "./live-http.ts";
 // `./boot.ts` pulls in every element + driver module (vault, store, signal,
 // clock, gate, channel, ai, runs) — a type-only import here keeps that whole
@@ -61,7 +60,7 @@ import type {
 } from "./fx.ts";
 import {
   currentDevSurface,
-  failureDetailFromResponse,
+  failureEnvelopeFromResponse,
   logDevRequest,
   shouldLogDevRequests,
 } from "../runtime/dev-request-log.ts";
@@ -203,6 +202,14 @@ function loadJsonCodeBlock(): typeof import("../runtime/json-code-block.ts") {
   return lazyRequire(`${import.meta.dir}/../runtime`, ["json", "code", "block"].join("-"));
 }
 
+/**
+ * Route descriptor for `GET /_oke/client.json`.
+ * A static import evaluates Zod on every HTTP cold start; load it on first fetch.
+ */
+function loadClientDescriptor(): typeof import("./client-descriptor.ts") {
+  return lazyRequire(import.meta.dir, ["client", "descriptor"].join("-"));
+}
+
 /** Options for {@link oke}. */
 export interface OkeOptions {
   /** Application name (Manifest `app`). */
@@ -351,6 +358,11 @@ export interface ExecuteResult {
   readonly failure: PipelineResult["failure"];
   readonly response: Response | undefined;
   readonly ctx: InvocationContext;
+  /**
+   * Derived projection of {@link InvocationContext.error} — never a separate
+   * store. Always `=== ctx.error` by reference.
+   */
+  readonly error: unknown;
   readonly fx: Fx;
   /** Wide-event cache dimension from this invocation's telemetry. */
   readonly cache: "hit" | "miss" | "none";
@@ -1915,6 +1927,7 @@ export function oke(options: OkeOptions): OkeApp {
           },
         );
         if (inner.failure) return inner.failure;
+        if (inner.ctx.error !== undefined) throw inner.ctx.error;
         return inner.output;
       },
     });
@@ -2144,6 +2157,9 @@ export function oke(options: OkeOptions): OkeApp {
       failure: result.failure,
       response: result.response,
       ctx: result.ctx,
+      get error() {
+        return result.ctx.error;
+      },
       fx,
       cache: cacheDimensionOf(telemetry),
       durationMs,
@@ -2328,6 +2344,7 @@ export function oke(options: OkeOptions): OkeApp {
           response.headers.set("accept-query", '"application/json"');
         }
         if (shouldLogDevRequests()) {
+          const envelope = await failureEnvelopeFromResponse(response);
           logDevRequest({
             surface: currentDevSurface(),
             method,
@@ -2336,7 +2353,8 @@ export function oke(options: OkeOptions): OkeApp {
             runId: runLabel,
             status: response.status,
             ms: Math.round(performance.now() - started),
-            detail: await failureDetailFromResponse(response),
+            detail: envelope.detail,
+            errorCode: envelope.code,
           });
         }
         const jcb = loadJsonCodeBlock();
@@ -2370,7 +2388,7 @@ export function oke(options: OkeOptions): OkeApp {
       }
 
       if (method === "GET" && url.pathname === "/_oke/client.json") {
-        const descriptor = buildClientDescriptor(routes, flowsByName);
+        const descriptor = loadClientDescriptor().buildClientDescriptor(routes, flowsByName);
         return respond(
           new Response(JSON.stringify(descriptor), {
             headers: { "content-type": "application/json" },
@@ -2552,6 +2570,7 @@ export function oke(options: OkeOptions): OkeApp {
         flowDef.triggers[0] ?? ({ kind: "internal" } satisfies InternalTrigger);
       const result = await execute(flowDef, input, trigger);
       if (result.failure) return result.failure;
+      if (result.ctx.error !== undefined) throw result.ctx.error;
       return result.output;
     },
     resolveMcpTool(name) {

package/src/kernel/builtin-errors.test.ts

@@ -0,0 +1,117 @@
+/**
+ * Built-in failure HTTP status map.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { fail } from "./errors.ts";
+import { httpStatusForFailure, statusForBuiltinError } from "./builtin-errors.ts";
+import { encodeExecuteResult, statusForFailure } from "../compiler/response.ts";
+
+describe("statusForBuiltinError", () => {
+  test("maps REST codes", () => {
+    expect(statusForBuiltinError("NotFound")).toBe(404);
+    expect(statusForBuiltinError("Conflict")).toBe(409);
+    expect(statusForBuiltinError("ForeignKey")).toBe(409);
+    expect(statusForBuiltinError("Unauthorized")).toBe(401);
+    expect(statusForBuiltinError("Forbidden")).toBe(403);
+    expect(statusForBuiltinError("RateLimited")).toBe(429);
+    expect(statusForBuiltinError("AuthRateLimited")).toBe(429);
+    expect(statusForBuiltinError("ValidationError")).toBe(422);
+    expect(statusForBuiltinError("UnsupportedMediaType")).toBe(415);
+    expect(statusForBuiltinError("ServiceUnavailable")).toBe(503);
+    expect(statusForBuiltinError("InternalError")).toBe(500);
+    expect(statusForBuiltinError("AuthFailed")).toBe(400);
+    expect(statusForBuiltinError("InvalidQuery")).toBe(400);
+  });
+
+  test("DatabaseError status follows data.reason", () => {
+    expect(statusForBuiltinError("DatabaseError", { reason: "not_null" })).toBe(422);
+    expect(statusForBuiltinError("DatabaseError", { reason: "check" })).toBe(422);
+    expect(statusForBuiltinError("DatabaseError", { reason: "invalid" })).toBe(422);
+    expect(statusForBuiltinError("DatabaseError", { reason: "too_long" })).toBe(422);
+    expect(statusForBuiltinError("DatabaseError", { reason: "out_of_range" })).toBe(422);
+    expect(statusForBuiltinError("DatabaseError", { reason: "retryable" })).toBe(503);
+    expect(statusForBuiltinError("DatabaseError", { reason: "unknown" })).toBe(500);
+    expect(statusForBuiltinError("DatabaseError", {})).toBe(500);
+  });
+
+  test("domain codes are undefined so HTTP defaults to 400", () => {
+    expect(statusForBuiltinError("OutOfStock")).toBeUndefined();
+    expect(httpStatusForFailure("OutOfStock")).toBe(400);
+    expect(httpStatusForFailure("OKE1110")).toBe(500);
+  });
+});
+
+describe("statusForFailure", () => {
+  test("reads DatabaseError reason from the envelope", () => {
+    expect(statusForFailure(fail("DatabaseError", { reason: "not_null" }))).toBe(422);
+    expect(statusForFailure(fail("NotFound", { id: "n1" }))).toBe(404);
+    expect(statusForFailure(fail("FlightFull", { seatsLeft: 0 }))).toBe(400);
+  });
+});
+
+describe("encodeExecuteResult InternalError", () => {
+  test("never copies the thrown Error.message", async () => {
+    const res = await encodeExecuteResult({ error: new Error("secret leak") });
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as {
+      data: null;
+      error: { code: string; message?: string; data?: unknown };
+    };
+    expect(body.error.code).toBe("InternalError");
+    expect(JSON.stringify(body)).not.toContain("secret leak");
+  });
+
+  test("maps leftover unique SQLSTATE to Conflict", async () => {
+    const res = await encodeExecuteResult({
+      error: {
+        code: "23505",
+        message: "duplicate key value violates unique constraint",
+        detail: "Key (email)=(a@b.c) already exists.",
+      },
+    });
+    expect(res.status).toBe(409);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("Conflict");
+    expect(JSON.stringify(body)).not.toContain("a@b.c");
+  });
+
+  test("maps leftover Redis connection failure to ServiceUnavailable", async () => {
+    const res = await encodeExecuteResult({
+      error: Object.assign(new Error("Connection closed"), { code: "ECONNREFUSED" }),
+    });
+    expect(res.status).toBe(503);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("ServiceUnavailable");
+    expect(JSON.stringify(body)).not.toContain("Connection closed");
+  });
+
+  test("maps leftover S3 AccessDenied to Forbidden", async () => {
+    const res = await encodeExecuteResult({
+      error: Object.assign(new Error("Access Denied"), { code: "AccessDenied", status: 403 }),
+    });
+    expect(res.status).toBe(403);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("Forbidden");
+    expect(JSON.stringify(body)).not.toContain("Access Denied");
+  });
+
+  test("leaves WRONGTYPE as InternalError", async () => {
+    const res = await encodeExecuteResult({
+      error: new Error("WRONGTYPE Operation against a key holding the wrong kind of value"),
+    });
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("InternalError");
+    expect(JSON.stringify(body)).not.toContain("WRONGTYPE");
+  });
+
+  test("maps exhausted serialization failure to ServiceUnavailable", async () => {
+    const res = await encodeExecuteResult({
+      error: { code: "40001", message: "could not serialize access" },
+    });
+    expect(res.status).toBe(503);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("ServiceUnavailable");
+  });
+});

package/src/kernel/builtin-errors.ts

@@ -0,0 +1,129 @@
+/**
+ * Built-in flow-boundary error codes — HTTP status + payload types.
+ *
+ * Always-on for `fx.fail` helpers and the typed client. Domain codes
+ * (`OutOfStock`, `FlightFull`) stay on the exposure `errors:` bag.
+ * No Zod — this module sits on the kernel edge graph.
+ */
+
+/** Built-in codes with a fixed HTTP status (not `DatabaseError`). */
+export const BUILTIN_ERROR_STATUS = {
+  ValidationError: 422,
+  Unauthorized: 401,
+  Forbidden: 403,
+  NotFound: 404,
+  Conflict: 409,
+  ForeignKey: 409,
+  UnsupportedMediaType: 415,
+  RateLimited: 429,
+  AuthRateLimited: 429,
+  InvalidQuery: 400,
+  AuthFailed: 400,
+  InternalError: 500,
+  ServiceUnavailable: 503,
+} as const;
+
+/** Built-in error code (including `DatabaseError`). */
+export type BuiltinErrorCode = keyof typeof BUILTIN_ERROR_STATUS | "DatabaseError";
+
+/** `DatabaseError.data.reason` — encoder maps these to HTTP status. */
+export type DatabaseErrorReason =
+  | "not_null"
+  | "check"
+  | "invalid"
+  | "too_long"
+  | "out_of_range"
+  | "retryable"
+  | "unknown";
+
+/**
+ * One `ValidationError` issue — same shape as the validation layer,
+ * inlined so this module stays off that graph.
+ */
+export type BuiltinValidationIssue = {
+  readonly message: string;
+  readonly path: ReadonlyArray<string | number>;
+};
+
+/** Loose identity / constraint bag used by several built-in codes. */
+export type BuiltinErrorBag = {
+  readonly id?: string;
+  readonly key?: string;
+  readonly code?: string;
+  readonly reason?: string;
+  readonly gate?: string;
+  readonly constraint?: string;
+  readonly table?: string;
+  readonly column?: string;
+  readonly sqlstate?: string;
+  readonly retryAfterMs?: number;
+  readonly retryAfter?: number;
+  readonly contentType?: string;
+  readonly [key: string]: unknown;
+};
+
+/**
+ * Built-in error code → payload. Client unions this with declared `errors:`.
+ */
+export type BuiltinErrorMap = {
+  readonly ValidationError: { readonly issues: readonly BuiltinValidationIssue[] };
+  readonly Unauthorized: BuiltinErrorBag;
+  readonly Forbidden: BuiltinErrorBag;
+  readonly NotFound: BuiltinErrorBag;
+  readonly Conflict: BuiltinErrorBag;
+  readonly ForeignKey: BuiltinErrorBag;
+  readonly UnsupportedMediaType: BuiltinErrorBag;
+  readonly RateLimited: { readonly retryAfterMs?: number };
+  readonly AuthRateLimited: BuiltinErrorBag;
+  readonly InvalidQuery: BuiltinErrorBag;
+  readonly AuthFailed: BuiltinErrorBag;
+  readonly DatabaseError: {
+    readonly reason: DatabaseErrorReason;
+    readonly sqlstate?: string;
+    readonly constraint?: string;
+    readonly table?: string;
+    readonly column?: string;
+  };
+  readonly InternalError: Record<string, never>;
+  readonly ServiceUnavailable: { readonly retryAfter?: number };
+};
+
+/**
+ * HTTP status for a built-in failure code, or `undefined` for domain codes.
+ *
+ * `DatabaseError` uses `data.reason`: `retryable` → 503, `unknown` / missing
+ * → 500, any other reason (`not_null`, `check`, `invalid`, …) → 422.
+ *
+ * @param code - Failure `error.code`
+ * @param data - Failure `error.data` (reason for `DatabaseError`)
+ */
+export function statusForBuiltinError(code: string, data?: unknown): number | undefined {
+  if (code === "DatabaseError") {
+    const reason = databaseErrorReason(data);
+    if (reason === "retryable") return 503;
+    if (reason !== undefined && reason !== "unknown") return 422;
+    return 500;
+  }
+  if (Object.prototype.hasOwnProperty.call(BUILTIN_ERROR_STATUS, code)) {
+    return BUILTIN_ERROR_STATUS[code as keyof typeof BUILTIN_ERROR_STATUS];
+  }
+  return undefined;
+}
+
+/**
+ * HTTP status for a typed flow failure. Domain codes default to 400.
+ *
+ * @param code - Failure code
+ * @param data - Failure payload
+ */
+export function httpStatusForFailure(code: string, data?: unknown): number {
+  const mapped = statusForBuiltinError(code, data);
+  if (mapped !== undefined) return mapped;
+  return code.startsWith("OKE") ? 500 : 400;
+}
+
+function databaseErrorReason(data: unknown): string | undefined {
+  if (data === null || typeof data !== "object") return undefined;
+  const reason = (data as { reason?: unknown }).reason;
+  return typeof reason === "string" ? reason : undefined;
+}

package/src/kernel/call.test.ts

@@ -1,6 +1,8 @@
 import { describe, expect, test, beforeEach } from "bun:test";
 import { oke } from "./app.ts";
+import { fail } from "./fail-helpers.ts";
 import { flow, resetFlowSeq } from "./flow.ts";
+import { isFlowFailure } from "./hooks.ts";
 import { on, resetBindings } from "./on.ts";
 import { http } from "./triggers.ts";
 
@@ -120,3 +122,183 @@ describe("fx.call — untriggered flows", () => {
     expect(runs).toBe(2);
   });
 });
+
+describe("error pipeline — RPC / call propagation", () => {
+  test("regression: unhandled RPC exception must never become 204 No Content", async () => {
+    const boom = flow("math.boom", {
+      do: () => {
+        throw new Error("sensitive leak");
+      },
+    });
+    const app = oke({ autoBoot: false, name: "rpc-boom" }).adopt(boom);
+
+    const res = await app.fetch(
+      new Request("http://localhost/_oke/math/boom", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+
+    expect(res.status).toBe(500);
+    expect(res.status).not.toBe(204);
+    const body = (await res.json()) as {
+      data: unknown;
+      error: { code: string; data: unknown; message?: string };
+    };
+    expect(body.data).toBeNull();
+    expect(body.error.code).toBe("InternalError");
+    expect(body.error.data).toEqual({});
+    expect(body.error.message).toBe("Something went wrong. Try again.");
+    expect(JSON.stringify(body)).not.toContain("sensitive leak");
+  });
+
+  test("RPC store auto-map unique violation is Conflict 409", async () => {
+    const clash = flow("math.clash", {
+      do: () => {
+        throw Object.assign(new Error("duplicate key"), {
+          code: "23505",
+          constraint: "users_email_key",
+        });
+      },
+    });
+    const app = oke({ autoBoot: false, name: "rpc-clash" }).adopt(clash);
+
+    const res = await app.fetch(
+      new Request("http://localhost/_oke/math/clash", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+
+    expect(res.status).toBe(409);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("Conflict");
+  });
+
+  test("ExecuteResult.error is a derived projection of ctx.error", async () => {
+    const boom = flow("math.boom", {
+      do: () => {
+        throw new Error("disk failed");
+      },
+    });
+    const app = oke({ autoBoot: false, name: "exec-err" }).adopt(boom);
+    const result = await app.execute(boom, {}, { kind: "internal" });
+
+    expect(result.failure).toBeUndefined();
+    expect(result.ctx.error).toBeDefined();
+    expect(result.error).toBe(result.ctx.error);
+  });
+
+  test("app.call returns FlowFailure value for controlled fail", async () => {
+    const missing = flow("notes.missing", {
+      do: () => fail.notFound({ id: "1" }),
+    });
+    const app = oke({ autoBoot: false, name: "call-fail" }).adopt(missing);
+    const out = await app.call(missing, {});
+    expect(isFlowFailure(out)).toBe(true);
+    if (isFlowFailure(out)) {
+      expect(out.error.code).toBe("NotFound");
+    }
+  });
+
+  test("app.call rethrows unhandled exception (never undefined)", async () => {
+    const boom = flow("notes.boom", {
+      do: () => {
+        throw new Error("disk failed");
+      },
+    });
+    const app = oke({ autoBoot: false, name: "call-throw" }).adopt(boom);
+    await expect(app.call(boom, {})).rejects.toThrow("disk failed");
+  });
+
+  test("fx.call returns FlowFailure value for controlled fail", async () => {
+    const child = flow("child.fail", {
+      do: () => fail.notFound({ id: "x" }),
+    });
+    on(
+      http.post("/run"),
+      flow("parent.run", {
+        effects: { calls: ["child.fail"] },
+        do: async (_input: Record<string, never>, fx) => {
+          const out = await fx.call("child.fail", {});
+          expect(isFlowFailure(out)).toBe(true);
+          return isFlowFailure(out) ? out : { unexpected: true };
+        },
+      }),
+    );
+    const app = oke({ autoBoot: false, name: "fx-fail" }).adopt(child);
+    const res = await app.fetch(
+      new Request("http://localhost/run", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(404);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("NotFound");
+  });
+
+  test("fx.call rethrows when child throws", async () => {
+    const child = flow("child.boom", {
+      do: () => {
+        throw new Error("worker crash");
+      },
+    });
+    on(
+      http.post("/run"),
+      flow("parent.run", {
+        effects: { calls: ["child.boom"] },
+        do: async (_input: Record<string, never>, fx) => {
+          return fx.call("child.boom", {});
+        },
+      }),
+    );
+    const app = oke({ autoBoot: false, name: "fx-throw" }).adopt(child);
+    const res = await app.fetch(
+      new Request("http://localhost/run", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { data: unknown; error: { code: string; message?: string } };
+    expect(body.data).toBeNull();
+    expect(body.error.code).toBe("InternalError");
+    expect(JSON.stringify(body)).not.toContain("worker crash");
+  });
+
+  test("nested fx.call chain propagates throw to outer boundary", async () => {
+    const deep = flow("deep.boom", {
+      do: () => {
+        throw new Error("deep crash");
+      },
+    });
+    const mid = flow("mid.call", {
+      effects: { calls: ["deep.boom"] },
+      do: async (_input: Record<string, never>, fx) => fx.call("deep.boom", {}),
+    });
+    on(
+      http.post("/run"),
+      flow("outer.run", {
+        effects: { calls: ["mid.call"] },
+        do: async (_input: Record<string, never>, fx) => fx.call("mid.call", {}),
+      }),
+    );
+    const app = oke({ autoBoot: false, name: "nested-throw" }).adopt(deep).adopt(mid);
+    const res = await app.fetch(
+      new Request("http://localhost/run", {
+        method: "POST",
+        headers: { "content-type": "application/json" },
+        body: "{}",
+      }),
+    );
+    expect(res.status).toBe(500);
+    const body = (await res.json()) as { error: { code: string } };
+    expect(body.error.code).toBe("InternalError");
+    expect(JSON.stringify(body)).not.toContain("deep crash");
+  });
+});

package/src/kernel/client-descriptor.test.ts

@@ -0,0 +1,78 @@
+/**
+ * Client descriptor printing — schema type strings are cached per object.
+ */
+
+import { describe, expect, test } from "bun:test";
+import { z } from "zod";
+import type { AnyFlowDef } from "./flow.ts";
+import type { RuntimeRouteMap } from "./adopt-routes.ts";
+import { buildClientDescriptor } from "./client-descriptor.ts";
+
+const FLOW_COUNT = 64;
+
+function fieldSchema() {
+  return z.object({
+    id: z.string().uuid(),
+    title: z.string().min(1).max(120),
+    tags: z.array(z.string()),
+    count: z.number().int().nonnegative(),
+  });
+}
+
+function fixture(): {
+  routes: RuntimeRouteMap;
+  flows: Map<string, AnyFlowDef>;
+} {
+  const routes: RuntimeRouteMap = { app: {} };
+  const flows = new Map<string, AnyFlowDef>();
+  for (let i = 0; i < FLOW_COUNT; i++) {
+    const name = `flow${i}`;
+    routes.app![name] = { method: "GET", path: `/${name}` };
+    flows.set(`app.${name}`, {
+      in: fieldSchema(),
+      out: z.object({
+        id: z.string(),
+        title: z.string(),
+        createdAt: z.iso.datetime(),
+      }),
+    } as AnyFlowDef);
+  }
+  return { routes, flows };
+}
+
+describe("schemaToTsString cache", () => {
+  test("a second pass over the same schema objects skips reprinting them", () => {
+    const { routes, flows } = fixture();
+
+    const coldStart = performance.now();
+    const cold = buildClientDescriptor(routes, flows);
+    const coldMs = performance.now() - coldStart;
+
+    const warmStart = performance.now();
+    const warm = buildClientDescriptor(routes, flows);
+    const warmMs = performance.now() - warmStart;
+
+    expect(warm).toEqual(cold);
+    expect(cold.routes.app?.flow0?.in).toContain("title");
+    // Uncached toJSONSchema is the whole map. A cache hit is the map lookup.
+    expect(warmMs).toBeLessThan(coldMs / 4);
+    console.log(
+      `client descriptor ${FLOW_COUNT} flows cold=${coldMs.toFixed(1)}ms warm=${warmMs.toFixed(1)}ms`,
+    );
+
+    const previous = flows.get("app.flow0");
+    flows.set("app.flow0", {
+      in: z.object({ id: z.string(), extra: z.boolean() }),
+      out: previous?.out,
+    } as AnyFlowDef);
+
+    const touchedStart = performance.now();
+    const touched = buildClientDescriptor(routes, flows);
+    const touchedMs = performance.now() - touchedStart;
+
+    expect(touched.routes.app?.flow0?.in).toContain("extra");
+    expect(touched.routes.app?.flow1?.in).toBe(warm.routes.app?.flow1?.in);
+    expect(touchedMs).toBeLessThan(coldMs / 4);
+    console.log(`client descriptor one schema replaced=${touchedMs.toFixed(1)}ms`);
+  });
+});

package/src/kernel/client-descriptor.ts

@@ -9,6 +9,15 @@ import type { AnyFlowDef } from "./flow.ts";
 import type { RuntimeRouteMap } from "./adopt-routes.ts";
 import { z } from "zod";
 
+/**
+ * Printed type string per schema object.
+ *
+ * A flows-tree reload replaces the schema objects of the modules that
+ * actually changed. Every other flow keeps the same reference and hits
+ * this map instead of running `toJSONSchema` again.
+ */
+const schemaTsCache = new WeakMap<object, string>();
+
 /**
  * Build a client descriptor from runtime routes + flow defs (type strings + stamps).
  *
@@ -62,6 +71,20 @@ export function buildClientDescriptor(
  */
 export function schemaToTsString(schema: unknown): string {
   if (schema === undefined || schema === null) return "unknown";
+  if (typeof schema !== "object" && typeof schema !== "function") return "unknown";
+  const cached = schemaTsCache.get(schema);
+  if (cached !== undefined) return cached;
+  const printed = printSchemaToTs(schema);
+  schemaTsCache.set(schema, printed);
+  return printed;
+}
+
+/**
+ * Convert one schema object to a TypeScript type string. Uncached.
+ *
+ * @param schema - Object or function schema
+ */
+function printSchemaToTs(schema: object): string {
   try {
     if (hasToJSONSchema(schema)) {
       return jsonSchemaToTs(schema.toJSONSchema());