okengine 0.20.0 → 0.21.1

package/src/okid-extended.ts

@@ -0,0 +1,175 @@
+/**
+ * `okid({ … })` options path — sortable, prefix, and alphabet toggles.
+ *
+ * Kept off the kernel edge profile. `okid()` and `okid(length)` never load it.
+ */
+
+import {
+  assertLength,
+  OKID_ALPHABET,
+  OKID_DEFAULT_LENGTH,
+  OKID_LOOKALIKE_CHARS,
+  OKID_MAX_PREFIX_LENGTH,
+  OKID_MIN_LENGTH,
+  OKID_SORTABLE_ALPHABET,
+  OKID_SORTABLE_MIN_LENGTH,
+  type OkidOptions,
+} from "./okid-shared.ts";
+
+/** Character groups addressable through {@link OkidOptions} toggles. */
+const GROUPS = {
+  numbers: "0123456789",
+  lowercase: "abcdefghijklmnopqrstuvwxyz",
+  uppercase: "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
+  symbols: "-_",
+} as const;
+
+/** Resolved alphabet + encoding metadata for one options combination. */
+interface ResolvedAlphabet {
+  readonly chars: string;
+  readonly size: number;
+  /** Bitmask covering `size` values (`size` is always a power of two here). */
+  readonly mask: number;
+}
+
+/** Memoized resolutions keyed by the toggle bitmask (32 combinations max). */
+const ALPHABET_CACHE = new Map<number, ResolvedAlphabet>();
+
+/**
+ * Resolve a toggle combination to an alphabet and rejection-sampling mask.
+ *
+ * @param numbers - Include `0-9`
+ * @param lowercase - Include `a-z`
+ * @param uppercase - Include `A-Z`
+ * @param symbols - Include `-` and `_`
+ * @param lookAlikes - Include visually confusable characters
+ */
+function resolveAlphabet(
+  numbers: boolean,
+  lowercase: boolean,
+  uppercase: boolean,
+  symbols: boolean,
+  lookAlikes: boolean,
+): ResolvedAlphabet {
+  const key =
+    (numbers ? 1 : 0) |
+    (lowercase ? 2 : 0) |
+    (uppercase ? 4 : 0) |
+    (symbols ? 8 : 0) |
+    (lookAlikes ? 0 : 16);
+  const cached = ALPHABET_CACHE.get(key);
+  if (cached) return cached;
+
+  let chars = "";
+  if (numbers) chars += GROUPS.numbers;
+  if (lowercase) chars += GROUPS.lowercase;
+  if (uppercase) chars += GROUPS.uppercase;
+  if (symbols) chars += GROUPS.symbols;
+  if (!chars) {
+    throw new RangeError("okid: alphabet is empty — enable at least one character group");
+  }
+  if (!lookAlikes) {
+    chars = [...chars].filter((c) => !OKID_LOOKALIKE_CHARS.includes(c)).join("");
+  }
+
+  // Round up to a power of two for mask-based rejection sampling: bytes below
+  // `size` map uniformly, bytes above are discarded and re-drawn — unbiased at
+  // every alphabet size, unlike naive modulo.
+  const rawSize = chars.length;
+  const size = 1 << Math.ceil(Math.log2(rawSize));
+  const resolved: ResolvedAlphabet = { chars, size: rawSize, mask: size - 1 };
+  ALPHABET_CACHE.set(key, resolved);
+  return resolved;
+}
+
+/**
+ * Encode one random byte stream into `length` characters of `alphabet`.
+ *
+ * @param alphabet - Resolved charset
+ * @param length - Output length
+ */
+function encodeAlphabet(alphabet: ResolvedAlphabet, length: number): string {
+  const { chars, size, mask } = alphabet;
+  const bytes = new Uint8Array(length + Math.ceil(length >> 2));
+  crypto.getRandomValues(bytes.subarray(0, length));
+  let out = "";
+  let i = 0;
+  while (out.length < length && i < bytes.length) {
+    const byte = bytes[i++]!;
+    if ((byte & mask) < size) out += chars[byte & mask];
+  }
+  return out;
+}
+
+/**
+ * Pack epoch-ms into exactly 8 codepoint-ordered characters (48 bits).
+ *
+ * @param nowMs - Epoch milliseconds
+ */
+function encodeTimestamp(nowMs: number): string {
+  let t = nowMs % 2 ** 48;
+  let out = "";
+  for (let i = 0; i < 8; i++) {
+    out = OKID_SORTABLE_ALPHABET[t & 63]! + out;
+    t = Math.floor(t / 64);
+  }
+  return out;
+}
+
+/**
+ * Assert a semantic prefix is within bounds and stays on the URL-safe alphabet.
+ *
+ * @param prefix - Caller-supplied label
+ */
+function assertPrefix(prefix: string): void {
+  if (prefix.length > OKID_MAX_PREFIX_LENGTH) {
+    throw new RangeError(
+      `okid: prefix length ${prefix.length} exceeds max ${OKID_MAX_PREFIX_LENGTH}`,
+    );
+  }
+  for (const char of prefix) {
+    if (!OKID_ALPHABET.includes(char)) {
+      throw new RangeError(
+        `okid: prefix contains invalid character ${JSON.stringify(char)} — use characters from OKID_ALPHABET`,
+      );
+    }
+  }
+}
+
+/**
+ * Generate an id from an options object.
+ *
+ * @param options - Length, prefix, sortable, and alphabet toggles
+ */
+export function okidWithOptions(options: OkidOptions): string {
+  const {
+    length = OKID_DEFAULT_LENGTH,
+    prefix = "",
+    sortable = false,
+    lowercase = true,
+    uppercase = true,
+    numbers = true,
+    symbols = true,
+    lookAlikes = true,
+  } = options;
+
+  if (prefix) assertPrefix(prefix);
+
+  let body: string;
+  if (sortable) {
+    assertLength(length, OKID_SORTABLE_MIN_LENGTH, "length");
+    // Time ordering requires lexicographic encoding, which requires the full
+    // codepoint-ordered alphabet — partial subsets cannot preserve both the
+    // caller's charset choice AND cross-ms ordering, so toggles are ignored.
+    const alphabet = resolveAlphabet(true, true, true, true, true);
+    body = encodeTimestamp(Date.now()) + encodeAlphabet(alphabet, length - 8);
+  } else {
+    assertLength(length, OKID_MIN_LENGTH, "length");
+    body = encodeAlphabet(
+      resolveAlphabet(numbers, lowercase, uppercase, symbols, lookAlikes),
+      length,
+    );
+  }
+
+  return prefix ? prefix + body : body;
+}

package/src/okid-shared.ts

@@ -0,0 +1,103 @@
+/**
+ * OKID constants and the options-path encoder.
+ *
+ * The default `okid()` / `okid(length)` hot path does not import the
+ * alphabet resolver — only these constants and {@link assertLength}.
+ */
+
+/**
+ * Default `okid()` / `okid(length)` alphabet.
+ *
+ * Same 64-character set and order as
+ * `resolveAlphabet(true, true, true, true, true)` (numbers, lowercase,
+ * uppercase, symbols). Power-of-two size, so a bitmask is unbiased.
+ */
+export const OKID_DEFAULT_CHARS =
+  "0123456789abcdefghijklmnopqrstuvwxyzABCDEFGHIJKLMNOPQRSTUVWXYZ-_";
+
+/**
+ * Characters removed when `lookAlikes` is disabled (human transcription).
+ */
+export const OKID_LOOKALIKE_CHARS = "1lI0Oouv5Ss";
+
+/** Default URL-safe alphabet: Base64URL charset in its conventional order. */
+export const OKID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
+
+/**
+ * Codepoint-ordered variant of {@link OKID_ALPHABET}: identical characters,
+ * sorted by code unit so plain string comparison equals value comparison.
+ * The default Base64URL order is NOT lexicographic (`_` sorts between `Z`
+ * and `a`), which would silently break time ordering — so the sortable
+ * encoder always uses this order.
+ *
+ * Kept as a literal (not `[...OKID_ALPHABET].sort().join("")`) so the public
+ * JSR API stays fast-type / explicitly typed.
+ */
+export const OKID_SORTABLE_ALPHABET: string =
+  "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz";
+
+/** Default id length — 21 chars × 6 bits = 126 bits of entropy. */
+export const OKID_DEFAULT_LENGTH = 21;
+
+/** Shortest permitted id length (8 chars ≈ 48 bits entropy floor). */
+export const OKID_MIN_LENGTH = 8;
+
+/** Longest permitted id length. */
+export const OKID_MAX_LENGTH = 128;
+
+/** Sortable ids need ≥ 16: 8 timestamp chars alone would leave no randomness. */
+export const OKID_SORTABLE_MIN_LENGTH = 16;
+
+/** Longest permitted semantic {@link OkidOptions.prefix}. */
+export const OKID_MAX_PREFIX_LENGTH = 32;
+
+/** Options for {@link okid}. All alphabet toggles default to included. */
+export interface OkidOptions {
+  /**
+   * Generated body length (default {@link OKID_DEFAULT_LENGTH}). Does not
+   * include {@link prefix} — the returned string is `prefix + body`.
+   */
+  readonly length?: number;
+  /**
+   * Fixed semantic label prepended to the body (e.g. `"usr_"`, `"evt_"`).
+   * Characters must belong to {@link OKID_ALPHABET}; max
+   * {@link OKID_MAX_PREFIX_LENGTH}. Empty / omitted means no label.
+   */
+  readonly prefix?: string;
+  /**
+   * Prefix the body with a 48-bit epoch-ms timestamp (exactly 8 chars) so
+   * lexicographic order tracks creation time across milliseconds. Alphabet
+   * toggles are ignored under this mode — see {@link OKID_SORTABLE_ALPHABET}.
+   * Combines with {@link prefix}: `prefix + timestamp + random`.
+   */
+  readonly sortable?: boolean;
+  /** Include `a-z` (default true). */
+  readonly lowercase?: boolean;
+  /** Include `A-Z` (default true). */
+  readonly uppercase?: boolean;
+  /** Include `0-9` (default true). */
+  readonly numbers?: boolean;
+  /** Include `-` and `_` (default true). */
+  readonly symbols?: boolean;
+  /**
+   * Include visually confusable characters (`1lI0Oouv5Ss`, default true).
+   * Set `false` to drop them for human transcription.
+   */
+  readonly lookAlikes?: boolean;
+}
+
+/**
+ * Assert `length` is a valid integer within bounds for the requested mode.
+ *
+ * @param length - Requested length
+ * @param min - Mode-specific minimum
+ * @param label - Option name used in the error message
+ */
+export function assertLength(length: number, min: number, label: string): void {
+  if (!Number.isInteger(length)) {
+    throw new RangeError(`okid: ${label} must be an integer, got ${length}`);
+  }
+  if (length < min || length > OKID_MAX_LENGTH) {
+    throw new RangeError(`okid: ${label} ${length} is out of range [${min}, ${OKID_MAX_LENGTH}]`);
+  }
+}

package/src/okid.ts

@@ -52,193 +52,33 @@
  * @module
  */
 
-/** Character groups addressable through {@link OkidOptions} toggles. */
-const GROUPS = {
-  numbers: "0123456789",
-  lowercase: "abcdefghijklmnopqrstuvwxyz",
-  uppercase: "ABCDEFGHIJKLMNOPQRSTUVWXYZ",
-  symbols: "-_",
-} as const;
+import { lazyRequire } from "./kernel/lazy-require.ts";
+import {
+  assertLength,
+  OKID_DEFAULT_CHARS,
+  OKID_DEFAULT_LENGTH,
+  OKID_MIN_LENGTH,
+  type OkidOptions,
+} from "./okid-shared.ts";
+
+export type { OkidOptions } from "./okid-shared.ts";
+export {
+  OKID_ALPHABET,
+  OKID_DEFAULT_LENGTH,
+  OKID_LOOKALIKE_CHARS,
+  OKID_MAX_LENGTH,
+  OKID_MAX_PREFIX_LENGTH,
+  OKID_MIN_LENGTH,
+  OKID_SORTABLE_ALPHABET,
+  OKID_SORTABLE_MIN_LENGTH,
+} from "./okid-shared.ts";
 
 /**
- * Characters removed when `lookAlikes` is disabled (human transcription).
+ * Load sortable / prefix / alphabet-toggle encoding.
+ * Computed stem so the edge profile does not inline it.
  */
-export const OKID_LOOKALIKE_CHARS = "1lI0Oouv5Ss";
-
-/** Default URL-safe alphabet: Base64URL charset in its conventional order. */
-export const OKID_ALPHABET = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-_";
-
-/**
- * Codepoint-ordered variant of {@link OKID_ALPHABET}: identical characters,
- * sorted by code unit so plain string comparison equals value comparison.
- * The default Base64URL order is NOT lexicographic (`_` sorts between `Z`
- * and `a`), which would silently break time ordering — so the sortable
- * encoder always uses this order.
- *
- * Kept as a literal (not `[...OKID_ALPHABET].sort().join("")`) so the public
- * JSR API stays fast-type / explicitly typed.
- */
-export const OKID_SORTABLE_ALPHABET: string =
-  "-0123456789ABCDEFGHIJKLMNOPQRSTUVWXYZ_abcdefghijklmnopqrstuvwxyz";
-
-/** Default id length — 21 chars × 6 bits = 126 bits of entropy. */
-export const OKID_DEFAULT_LENGTH = 21;
-
-/** Shortest permitted id length (8 chars ≈ 48 bits entropy floor). */
-export const OKID_MIN_LENGTH = 8;
-
-/** Longest permitted id length. */
-export const OKID_MAX_LENGTH = 128;
-
-/** Sortable ids need ≥ 16: 8 timestamp chars alone would leave no randomness. */
-export const OKID_SORTABLE_MIN_LENGTH = 16;
-
-/** Longest permitted semantic {@link OkidOptions.prefix}. */
-export const OKID_MAX_PREFIX_LENGTH = 32;
-
-/** Options for {@link okid}. All alphabet toggles default to included. */
-export interface OkidOptions {
-  /**
-   * Generated body length (default {@link OKID_DEFAULT_LENGTH}). Does not
-   * include {@link prefix} — the returned string is `prefix + body`.
-   */
-  readonly length?: number;
-  /**
-   * Fixed semantic label prepended to the body (e.g. `"usr_"`, `"evt_"`).
-   * Characters must belong to {@link OKID_ALPHABET}; max
-   * {@link OKID_MAX_PREFIX_LENGTH}. Empty / omitted means no label.
-   */
-  readonly prefix?: string;
-  /**
-   * Prefix the body with a 48-bit epoch-ms timestamp (exactly 8 chars) so
-   * lexicographic order tracks creation time across milliseconds. Alphabet
-   * toggles are ignored under this mode — see {@link OKID_SORTABLE_ALPHABET}.
-   * Combines with {@link prefix}: `prefix + timestamp + random`.
-   */
-  readonly sortable?: boolean;
-  /** Include `a-z` (default true). */
-  readonly lowercase?: boolean;
-  /** Include `A-Z` (default true). */
-  readonly uppercase?: boolean;
-  /** Include `0-9` (default true). */
-  readonly numbers?: boolean;
-  /** Include `-` and `_` (default true). */
-  readonly symbols?: boolean;
-  /**
-   * Include visually confusable characters (`1lI0Oouv5Ss`, default true).
-   * Set `false` to drop them for human transcription.
-   */
-  readonly lookAlikes?: boolean;
-}
-
-/** Resolved alphabet + encoding metadata for one options combination. */
-interface ResolvedAlphabet {
-  readonly chars: string;
-  readonly size: number;
-  /** Bitmask covering `size` values (`size` is always a power of two here). */
-  readonly mask: number;
-}
-
-/** Memoized resolutions keyed by the toggle bitmask (32 combinations max). */
-const ALPHABET_CACHE = new Map<number, ResolvedAlphabet>();
-
-function resolveAlphabet(
-  numbers: boolean,
-  lowercase: boolean,
-  uppercase: boolean,
-  symbols: boolean,
-  lookAlikes: boolean,
-): ResolvedAlphabet {
-  const key =
-    (numbers ? 1 : 0) |
-    (lowercase ? 2 : 0) |
-    (uppercase ? 4 : 0) |
-    (symbols ? 8 : 0) |
-    (lookAlikes ? 0 : 16);
-  const cached = ALPHABET_CACHE.get(key);
-  if (cached) return cached;
-
-  let chars = "";
-  if (numbers) chars += GROUPS.numbers;
-  if (lowercase) chars += GROUPS.lowercase;
-  if (uppercase) chars += GROUPS.uppercase;
-  if (symbols) chars += GROUPS.symbols;
-  if (!chars) {
-    throw new RangeError("okid: alphabet is empty — enable at least one character group");
-  }
-  if (!lookAlikes) {
-    chars = [...chars].filter((c) => !OKID_LOOKALIKE_CHARS.includes(c)).join("");
-  }
-
-  // Round up to a power of two for mask-based rejection sampling: bytes below
-  // `size` map uniformly, bytes above are discarded and re-drawn — unbiased at
-  // every alphabet size, unlike naive modulo.
-  const rawSize = chars.length;
-  const size = 1 << Math.ceil(Math.log2(rawSize));
-  const resolved: ResolvedAlphabet = { chars, size: rawSize, mask: size - 1 };
-  ALPHABET_CACHE.set(key, resolved);
-  return resolved;
-}
-
-/** Encode one random byte stream into `length` characters of `alphabet`. */
-function encode(alphabet: ResolvedAlphabet, length: number): string {
-  const { chars, size, mask } = alphabet;
-  const bytes = new Uint8Array(length + Math.ceil(length >> 2));
-  crypto.getRandomValues(bytes.subarray(0, length));
-  let out = "";
-  let i = 0;
-  while (out.length < length && i < bytes.length) {
-    const byte = bytes[i++]!;
-    if ((byte & mask) < size) out += chars[byte & mask];
-  }
-  return out;
-}
-
-/** Pack epoch-ms into exactly 8 codepoint-ordered characters (48 bits). */
-function encodeTimestamp(nowMs: number): string {
-  let t = nowMs % 2 ** 48;
-  let out = "";
-  for (let i = 0; i < 8; i++) {
-    out = OKID_SORTABLE_ALPHABET[t & 63]! + out;
-    t = Math.floor(t / 64);
-  }
-  return out;
-}
-
-/**
- * Assert `length` is a valid integer within bounds for the requested mode.
- *
- * @param length - Requested length
- * @param min - Mode-specific minimum
- * @param label - Option name used in the error message
- */
-function assertLength(length: number, min: number, label: string): void {
-  if (!Number.isInteger(length)) {
-    throw new RangeError(`okid: ${label} must be an integer, got ${length}`);
-  }
-  if (length < min || length > OKID_MAX_LENGTH) {
-    throw new RangeError(`okid: ${label} ${length} is out of range [${min}, ${OKID_MAX_LENGTH}]`);
-  }
-}
-
-/**
- * Assert a semantic prefix is within bounds and stays on the URL-safe alphabet.
- *
- * @param prefix - Caller-supplied label
- */
-function assertPrefix(prefix: string): void {
-  if (prefix.length > OKID_MAX_PREFIX_LENGTH) {
-    throw new RangeError(
-      `okid: prefix length ${prefix.length} exceeds max ${OKID_MAX_PREFIX_LENGTH}`,
-    );
-  }
-  for (const char of prefix) {
-    if (!OKID_ALPHABET.includes(char)) {
-      throw new RangeError(
-        `okid: prefix contains invalid character ${JSON.stringify(char)} — use characters from OKID_ALPHABET`,
-      );
-    }
-  }
+function loadOkidExtended(): typeof import("./okid-extended.ts") {
+  return lazyRequire(import.meta.dir, ["okid", "extended"].join("-"));
 }
 
 /**
@@ -256,34 +96,11 @@ function assertPrefix(prefix: string): void {
 export function okid(options: number | OkidOptions = OKID_DEFAULT_LENGTH): string {
   if (typeof options === "number") {
     assertLength(options, OKID_MIN_LENGTH, "length");
-    return encode(resolveAlphabet(true, true, true, true, true), options);
+    const bytes = new Uint8Array(options);
+    crypto.getRandomValues(bytes);
+    let out = "";
+    for (let i = 0; i < options; i++) out += OKID_DEFAULT_CHARS[bytes[i]! & 63]!;
+    return out;
   }
-
-  const {
-    length = OKID_DEFAULT_LENGTH,
-    prefix = "",
-    sortable = false,
-    lowercase = true,
-    uppercase = true,
-    numbers = true,
-    symbols = true,
-    lookAlikes = true,
-  } = options;
-
-  if (prefix) assertPrefix(prefix);
-
-  let body: string;
-  if (sortable) {
-    assertLength(length, OKID_SORTABLE_MIN_LENGTH, "length");
-    // Time ordering requires lexicographic encoding, which requires the full
-    // codepoint-ordered alphabet — partial subsets cannot preserve both the
-    // caller's charset choice AND cross-ms ordering, so toggles are ignored.
-    const alphabet = resolveAlphabet(true, true, true, true, true);
-    body = encodeTimestamp(Date.now()) + encode(alphabet, length - 8);
-  } else {
-    assertLength(length, OKID_MIN_LENGTH, "length");
-    body = encode(resolveAlphabet(numbers, lowercase, uppercase, symbols, lookAlikes), length);
-  }
-
-  return prefix ? prefix + body : body;
+  return loadOkidExtended().okidWithOptions(options);
 }

package/src/release/build-lib.ts

@@ -26,6 +26,7 @@ const ENTRIES: readonly { readonly src: string; readonly out: string }[] = [
   // Lazy sync chunks — loaded via requirePackageModule / computed require
   // when the feature actually runs (auth, list page, auto-cache).
   { src: "src/kernel/fx-runtime.ts", out: "dist/fx-runtime.js" },
+  { src: "src/kernel/client-descriptor.ts", out: "dist/client-descriptor.js" },
   { src: "src/auth/config.ts", out: "dist/auth-config.js" },
   { src: "src/kernel/fx-auth-keys.ts", out: "dist/fx-auth-keys.js" },
   { src: "src/kernel/fx-auth-tenants.ts", out: "dist/fx-auth-tenants.js" },
@@ -37,6 +38,12 @@ const ENTRIES: readonly { readonly src: string; readonly out: string }[] = [
   { src: "src/kernel/errors-live-resume.ts", out: "dist/errors-live-resume.js" },
   { src: "src/kernel/errors-channel.ts", out: "dist/errors-channel.js" },
   { src: "src/kernel/errors-tenant.ts", out: "dist/errors-tenant.js" },
+  { src: "src/kernel/errors-text.ts", out: "dist/errors-text.js" },
+  { src: "src/kernel/fx-sql-handle.ts", out: "dist/fx-sql-handle.js" },
+  { src: "src/kernel/concurrency.ts", out: "dist/concurrency.js" },
+  { src: "src/compiler/aot.ts", out: "dist/aot.js" },
+  { src: "src/runs/window.ts", out: "dist/window.js" },
+  { src: "src/okid-extended.ts", out: "dist/okid-extended.js" },
   { src: "src/kernel/clock-durable.ts", out: "dist/clock-durable.js" },
   { src: "src/kernel/clock-reconcile.ts", out: "dist/clock-reconcile.js" },
   { src: "src/kernel/clock-per-tenant-name.ts", out: "dist/clock-per-tenant-name.js" },
@@ -44,6 +51,8 @@ const ENTRIES: readonly { readonly src: string; readonly out: string }[] = [
   { src: "src/kernel/list-page.ts", out: "dist/list-page.js" },
   { src: "src/kernel/http-resource.ts", out: "dist/http-resource.js" },
   { src: "src/elements/store/cache.ts", out: "dist/store-cache.js" },
+  { src: "src/elements/store/search-runtime.ts", out: "dist/search-runtime.js" },
+  { src: "src/elements/store/schema-decl.ts", out: "dist/schema-decl.js" },
   { src: "src/i18n/messages.ts", out: "dist/messages.js" },
   { src: "src/i18n/failure-message.ts", out: "dist/failure-message.js" },
   { src: "src/okid.ts", out: "dist/okid.js" },

package/src/runtime/dev-request-log.ts

@@ -56,6 +56,8 @@ export type DevRequestLogInput = {
   readonly ms: number;
   /** Human failure detail (error.message / code) for 4xx/5xx. */
   readonly detail?: string;
+  /** Failure `error.code` for the title chip. */
+  readonly errorCode?: string;
 };
 
 /**
@@ -85,16 +87,19 @@ export function isSilentDevRequest(method: string, path: string, surface?: DevLo
  *
  * @param response - HTTP response (cloned; original body stays readable)
  */
-export async function failureDetailFromResponse(response: Response): Promise<string | undefined> {
-  if (response.status < 400) return undefined;
+export async function failureEnvelopeFromResponse(
+  response: Response,
+): Promise<{ readonly detail?: string; readonly code?: string }> {
+  if (response.status < 400) return {};
   try {
     const body: unknown = await response.clone().json();
-    if (body === null || typeof body !== "object" || !("error" in body)) return undefined;
+    if (body === null || typeof body !== "object" || !("error" in body)) return {};
     const error = (body as { error: unknown }).error;
-    if (error === null || typeof error !== "object") return undefined;
+    if (error === null || typeof error !== "object") return {};
     const rec = error as { message?: unknown; code?: unknown; data?: unknown };
+    const code = typeof rec.code === "string" ? rec.code : undefined;
     if (typeof rec.message === "string" && rec.message.trim().length > 0) {
-      return rec.message.trim();
+      return { detail: rec.message.trim(), ...(code ? { code } : {}) };
     }
     if (
       rec.data !== null &&
@@ -103,14 +108,25 @@ export async function failureDetailFromResponse(response: Response): Promise<str
       typeof (rec.data as { reason: unknown }).reason === "string"
     ) {
       const reason = (rec.data as { reason: string }).reason;
-      const code = typeof rec.code === "string" ? rec.code : "Error";
-      return `${code}: ${reason}`;
+      return {
+        detail: `${code ?? "Error"}: ${reason}`,
+        ...(code ? { code } : {}),
+      };
     }
-    if (typeof rec.code === "string") return rec.code;
+    if (code) return { detail: code, code };
   } catch {
     // non-JSON error bodies stay status-only
   }
-  return undefined;
+  return {};
+}
+
+/**
+ * Extract a short failure detail from an OKE JSON envelope body.
+ *
+ * @param response - HTTP response (cloned; original body stays readable)
+ */
+export async function failureDetailFromResponse(response: Response): Promise<string | undefined> {
+  return (await failureEnvelopeFromResponse(response)).detail;
 }
 
 /**
@@ -135,6 +151,7 @@ export function logDevRequest(input: DevRequestLogInput): void {
       status: input.status,
       ms: input.ms,
       detail: input.detail,
+      errorCode: input.errorCode,
     }),
   );
 }
@@ -167,7 +184,7 @@ export async function timedDevFetch(
   const url = new URL(request.url);
   const method = request.method.toUpperCase();
   const response = await handle(request);
-  const detail = await failureDetailFromResponse(response);
+  const envelope = await failureEnvelopeFromResponse(response);
   logDevRequest({
     surface: options.surface ?? currentDevSurface(),
     method,
@@ -176,7 +193,8 @@ export async function timedDevFetch(
     runId: options.resolveRunId?.(request, response),
     status: response.status,
     ms: Math.round(performance.now() - started),
-    detail,
+    detail: envelope.detail,
+    errorCode: envelope.code,
   });
   return response;
 }