okengine 0.21.0 → 0.21.1

package/src/kernel/fx.ts

@@ -9,10 +9,16 @@
  * for deterministic tests (§7.6).
  */
 
+import {
+  isJsonResult,
+  isJsonStreamResult,
+  jsonResultBrand,
+  type JsonResult,
+  type JsonStreamResult,
+} from "./json-result.ts";
 import type { Effects, ResourceRef, SignalResourceRef } from "../manifest/types.ts";
 import { isMcpToolRef } from "../manifest/mcp-ref.ts";
 import type { QueryPageSpec } from "./list-page.ts";
-import { schemaTableName, sqlTableRef } from "../manifest/sql-resource.ts";
 import type {
   FilesStoreDecl,
   FilesStoreFxHandle,
@@ -20,8 +26,6 @@ import type {
   IndexStoreFxHandle,
   KvStoreDecl,
   KvStoreFxHandle,
-  SelectFromBuilder,
-  SelectOrderBuilder,
   SqlStoreDecl,
   StoreDecl,
   StoreHandle,
@@ -30,7 +34,6 @@ import type {
 } from "../elements/store.ts";
 import { rlsIdentityFromAuth } from "../elements/store.ts";
 import type { RlsIdentity } from "../drivers/pg-rls.ts";
-import type { SqlRow } from "../drivers/types.ts";
 import type { SignalDecl, SignalRuntime } from "../elements/signal.ts";
 import type { DeadLetter, SignalEmitOptions } from "../drivers/signal-types.ts";
 import type { VaultActor, VaultAdapter, VaultRuntime } from "../elements/vault.ts";
@@ -60,14 +63,7 @@ import {
 } from "./dry-run.ts";
 import type { FailFn } from "./errors.ts";
 import { currentAbortSignal, linkAbort } from "./abort-scope.ts";
-import {
-  fxAll,
-  fxRace,
-  fxRetry,
-  fxUsing,
-  type FxRetryOptions,
-  type FxThunk,
-} from "./concurrency.ts";
+import type { FxRetryOptions, FxThunk } from "./concurrency.ts";
 import { maskRedactedDeep, Redacted } from "./redacted.ts";
 import type { JournalSession, JournalStepOptions } from "./journal.ts";
 
@@ -90,8 +86,23 @@ function loadFail(): FailFn {
 }
 
 /** Lazy runs/window helpers — kept off the cold `oke` static graph. */
-async function loadRunsWindow(): Promise<typeof import("../runs/window.ts")> {
-  return import("../runs/window.ts");
+function loadRunsWindow(): typeof import("../runs/window.ts") {
+  const stem = ["win", "dow"].join("");
+  try {
+    return lazyRequire(`${import.meta.dir}/../runs`, stem);
+  } catch {
+    return lazyRequire(import.meta.dir, stem);
+  }
+}
+
+/** Driver-backed SQL query builder — off the edge profile until `fx.store` opens SQL. */
+function loadFxSql(): typeof import("./fx-sql-handle.ts") {
+  return lazyRequire(import.meta.dir, ["fx", "sql", "handle"].join("-"));
+}
+
+/** `fx.all` / `race` / `retry` / `using` — off the edge profile until called. */
+function loadConcurrency(): typeof import("./concurrency.ts") {
+  return lazyRequire(import.meta.dir, ["concur", "rency"].join(""));
 }
 
 /**
@@ -390,29 +401,8 @@ export interface FxSearchOptions {
   readonly topK?: number;
 }
 
-/** Brand for {@link JsonResult} (kept internal — flows never construct it). */
-export const jsonResultBrand: unique symbol = Symbol.for("oke.json");
-
-/** Carrier from {@link FxJson} — status + body read by the response encoder. */
-export interface JsonResult<T = unknown> {
-  readonly [jsonResultBrand]: true;
-  readonly status: number;
-  readonly value?: T;
-  readonly meta?: Record<string, unknown>;
-  readonly kind?: undefined;
-}
-
-/** SSE carrier from {@link FxJson.stream} / {@link Fx.live}. */
-export interface JsonStreamResult {
-  readonly [jsonResultBrand]: true;
-  readonly kind: "stream";
-  readonly status: 200;
-  readonly chunks: AsyncIterable<unknown>;
-  /** Awaited before the 200 SSE body; throws OKE1210 on a missing resume cursor. */
-  ready?: () => Promise<void>;
-  /** Set by the kernel to commit journal / Runs after the stream settles. */
-  finalize?: () => Promise<void>;
-}
+export { isJsonResult, isJsonStreamResult, jsonResultBrand };
+export type { JsonResult, JsonStreamResult };
 
 const sseFrameBrand: unique symbol = Symbol.for("oke.sse.frame");
 
@@ -442,26 +432,6 @@ export function isSseFrame(value: unknown): value is SseFrame {
   return typeof value === "object" && value !== null && (value as SseFrame)[sseFrameBrand] === true;
 }
 
-/** True when `value` is an {@link FxJson} JSON-envelope carrier. */
-export function isJsonResult(value: unknown): value is JsonResult {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    (value as JsonResult)[jsonResultBrand] === true &&
-    (value as JsonStreamResult).kind !== "stream"
-  );
-}
-
-/** True when `value` is an SSE stream carrier from {@link FxJson.stream}. */
-export function isJsonStreamResult(value: unknown): value is JsonStreamResult {
-  return (
-    typeof value === "object" &&
-    value !== null &&
-    (value as JsonStreamResult)[jsonResultBrand] === true &&
-    (value as JsonStreamResult).kind === "stream"
-  );
-}
-
 /**
  * Paginated JSON page — `data` is Flow `out`; `meta` is the HTTP pager.
  *
@@ -1293,271 +1263,6 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     };
   }
 
-  /**
-   * Lazy, capability-gated proxy over a driver-backed {@link SqlStoreHandle}.
-   *
-   * @param decl - Store declaration
-   * @param open - Opens (and caches) the runtime handle
-   */
-  function gatedSqlHandle(decl: StoreDecl, open: () => Promise<SqlStoreHandle>): SqlStoreHandle {
-    const ref = decl.ref as `sql:${string}`;
-    let cached: SqlStoreHandle | undefined;
-    const ensure = async (): Promise<SqlStoreHandle> => {
-      if (!cached) cached = await open();
-      return cached;
-    };
-    /** Driver-backed SQL has no dry-run transaction — refuse writes. */
-    const refuseDryRunWrite = (): void => {
-      if (isDryRun()) {
-        throw new DryRunWriteIsolationError(
-          `Driver-backed store "${ref}" cannot isolate writes during dry-run; dry-run refused rather than risk a double-write.`,
-        );
-      }
-    };
-    /**
-     * Gate a table-scoped SQL operation. Prefers the precise `sql:<table>`
-     * ref (matches what the compiler's AST inference derives from the same
-     * call site — {@link "../manifest/sql-resource.ts"}); falls back to the
-     * store-level ref when the table ref isn't declared — every flow that
-     * hand-declared the older `effects: { writes: ["sql:<store>"] }`
-     * convention (every existing template, `upsert-app.test.ts`, …) must
-     * keep working unchanged. Ledger / journal record whichever ref the
-     * capability check actually matched, not always the coarser one.
-     *
-     * @param kind - Effect kind
-     * @param table - Table argument passed to a `SqlStoreHandle` method
-     * @param body - Work to run under the gate
-     */
-    const gatedTable = <T>(
-      kind: Parameters<CapabilityToken["assert"]>[0],
-      table: unknown,
-      body: () => T | Promise<T>,
-    ): Promise<T> => {
-      const externalOf = (): EffectExternal | undefined => cached?.external;
-      const name = schemaTableName(table);
-      if (name !== undefined) {
-        const perTable = sqlTableRef(name);
-        if (perTable !== ref && capability.allows(kind, perTable)) {
-          return gated(kind, perTable, body, externalOf);
-        }
-      }
-      return gated(kind, ref, body, externalOf);
-    };
-
-    return {
-      ref,
-      get routedRole() {
-        return cached?.routedRole ?? "primary";
-      },
-      get driverId() {
-        return cached?.driverId ?? "memory";
-      },
-      select: ((columns?: unknown) => {
-        return {
-          from(table: unknown) {
-            const run = (plan: {
-              where?: unknown;
-              orders?: readonly unknown[];
-              limit?: number;
-              offset?: number;
-            }): Promise<SqlRow[]> =>
-              gatedTable("read", table, async () => {
-                const h = await ensure();
-                const from = h.select(columns).from(table) as SelectFromBuilder;
-                const filtered = plan.where === undefined ? from : from.where(plan.where);
-                const ordered =
-                  plan.orders === undefined ? filtered : filtered.orderBy(...plan.orders);
-                if (plan.offset !== undefined) return ordered.offset(plan.offset);
-                return plan.limit === undefined ? ordered : ordered.limit(plan.limit);
-              });
-
-            const tail = (plan: {
-              where?: unknown;
-              orders?: readonly unknown[];
-            }): SelectOrderBuilder => ({
-              limit(n) {
-                return run({ ...plan, limit: n });
-              },
-              offset(n) {
-                return run({ ...plan, offset: n });
-              },
-              then(onfulfilled, onrejected) {
-                return run(plan).then(onfulfilled, onrejected);
-              },
-            });
-
-            return {
-              where(where: unknown) {
-                return {
-                  ...tail({ where }),
-                  orderBy: (...orders: readonly unknown[]) => tail({ where, orders }),
-                };
-              },
-              orderBy: (...orders: readonly unknown[]) => tail({ orders }),
-              limit(n: number) {
-                return run({ limit: n });
-              },
-              offset(n: number) {
-                return run({ offset: n });
-              },
-              then(
-                onfulfilled: (value: SqlRow[]) => unknown,
-                onrejected?: (reason: unknown) => unknown,
-              ) {
-                return run({}).then(onfulfilled, onrejected);
-              },
-            };
-          },
-        };
-      }) as SqlStoreHandle["select"],
-      insert(table) {
-        return {
-          values(row) {
-            const runExecute = () =>
-              gatedTable("write", table, async () => {
-                refuseDryRunWrite();
-                const h = await ensure();
-                await h.insert(table).values(row).execute();
-              });
-            return {
-              returning() {
-                return gatedTable("write", table, async () => {
-                  refuseDryRunWrite();
-                  const h = await ensure();
-                  return h.insert(table).values(row).returning();
-                });
-              },
-              execute: runExecute,
-              then(onfulfilled, onrejected) {
-                return runExecute().then(onfulfilled, onrejected);
-              },
-            };
-          },
-        };
-      },
-      update(table) {
-        return {
-          set(row) {
-            return {
-              where(where) {
-                return gatedTable("write", table, async () => {
-                  refuseDryRunWrite();
-                  const h = await ensure();
-                  return h.update(table).set(row).where(where);
-                });
-              },
-            };
-          },
-        };
-      },
-      findById(table, id) {
-        return gatedTable("read", table, async () => {
-          const h = await ensure();
-          return h.findById(table, id);
-        });
-      },
-      delete(table: Parameters<SqlStoreHandle["delete"]>[0], id?: string) {
-        if (id !== undefined) {
-          return gatedTable("write", table, async () => {
-            refuseDryRunWrite();
-            const h = await ensure();
-            return h.delete(table, id);
-          });
-        }
-        return {
-          where(where: unknown) {
-            return gatedTable("write", table, async () => {
-              refuseDryRunWrite();
-              const h = await ensure();
-              return h.delete(table).where(where);
-            });
-          },
-        };
-      },
-      exists(table, idOrWhere) {
-        return gatedTable("read", table, async () => {
-          const h = await ensure();
-          return h.exists(table, idOrWhere);
-        });
-      },
-      upsert(table, matchOn, values, upsertOptions) {
-        return gatedTable("write", table, async () => {
-          refuseDryRunWrite();
-          const h = await ensure();
-          return h.upsert(table, matchOn, values, upsertOptions);
-        });
-      },
-      increment(table, id, column, by) {
-        return gatedTable("write", table, async () => {
-          refuseDryRunWrite();
-          const h = await ensure();
-          return h.increment(table, id, column, by);
-        });
-      },
-      raw(sql, params) {
-        return gated("read", ref, async () => {
-          const h = await ensure();
-          return h.raw(sql, params);
-        });
-      },
-      count(table, where) {
-        return gatedTable("read", table, async () => {
-          const h = await ensure();
-          return h.count(table, where);
-        });
-      },
-      page(table, pageOptions) {
-        return gatedTable("read", table, async () => {
-          const h = await ensure();
-          return h.page(table, pageOptions);
-        });
-      },
-      search(table, searchOptions) {
-        return gatedTable("read", table, async () => {
-          const h = await ensure();
-          const result = await h.search(table, searchOptions);
-          // Optional rerank via fx.ask — only when explicitly requested.
-          if (
-            searchOptions.rerank &&
-            typeof searchOptions.rerank === "object" &&
-            searchOptions.rerank.model
-          ) {
-            const model = searchOptions.rerank.model;
-            const pk = "id";
-            const docs = result.data.map((row) => ({
-              id: String(row[pk] ?? ""),
-              text: Object.values(row)
-                .filter((v) => typeof v === "string")
-                .join("\n"),
-              score: 0,
-            }));
-            const out = (await fx.ask(model, {
-              query: searchOptions.query,
-              docs,
-            })) as { rankedIds?: string[] };
-            if (out.rankedIds && out.rankedIds.length > 0) {
-              const byId = new Map(result.data.map((r) => [String(r[pk] ?? ""), r]));
-              return {
-                ...result,
-                data: out.rankedIds
-                  .map((id) => byId.get(id))
-                  .filter((r): r is NonNullable<typeof r> => r !== undefined),
-              };
-            }
-          }
-          return result;
-        });
-      },
-      ensureTable(table) {
-        return gatedTable("write", table, async () => {
-          refuseDryRunWrite();
-          const h = await ensure();
-          return h.ensureTable(table);
-        });
-      },
-    } as SqlStoreHandle;
-  }
-
   function loadFxTenantStore(): {
     kv: (
       mode: "in" | "out",
@@ -1617,9 +1322,12 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       };
 
       if (decl.facet === "sql") {
-        return gatedSqlHandle(decl, async () => {
-          const h = await open();
-          return h as SqlStoreHandle;
+        return loadFxSql().createGatedSqlHandle({
+          decl,
+          open: async () => (await open()) as SqlStoreHandle,
+          gated,
+          capability,
+          ask: (model, input) => fx.ask(model, input),
         });
       }
 
@@ -2292,16 +2000,16 @@ export function createFxContext(options: CreateFxOptions): FxContext {
       return rlsInvokeContext().rls;
     },
     all(thunks) {
-      return fxAll(thunks);
+      return loadConcurrency().fxAll(thunks);
     },
     race(thunks) {
-      return fxRace(thunks);
+      return loadConcurrency().fxRace(thunks);
     },
     retry(fn, opts) {
-      return fxRetry(fn, opts);
+      return loadConcurrency().fxRetry(fn, opts);
     },
     using(acquire, release, use) {
-      return fxUsing(acquire, release, use);
+      return loadConcurrency().fxUsing(acquire, release, use);
     },
   };
 

package/src/kernel/json-result.ts

@@ -0,0 +1,59 @@
+/**
+ * `fx.json` carriers — brand and guards, with no `fx` / Store graph.
+ *
+ * `project-out` and the HTTP encoder need these on the cold-start path.
+ * Importing them from `fx.ts` would evaluate the Store barrel (Zod, hybrid
+ * search) before the server listens.
+ */
+
+/** Brand for {@link JsonResult} (kept internal — flows never construct it). */
+export const jsonResultBrand: unique symbol = Symbol.for("oke.json");
+
+/** Carrier from `fx.json` — status + body read by the response encoder. */
+export interface JsonResult<T = unknown> {
+  readonly [jsonResultBrand]: true;
+  readonly status: number;
+  readonly value?: T;
+  readonly meta?: Record<string, unknown>;
+  readonly kind?: undefined;
+}
+
+/** SSE carrier from `fx.json.stream` / `fx.live`. */
+export interface JsonStreamResult {
+  readonly [jsonResultBrand]: true;
+  readonly kind: "stream";
+  readonly status: 200;
+  readonly chunks: AsyncIterable<unknown>;
+  /** Awaited before the 200 SSE body; throws OKE1210 on a missing resume cursor. */
+  ready?: () => Promise<void>;
+  /** Set by the kernel to commit journal / Runs after the stream settles. */
+  finalize?: () => Promise<void>;
+}
+
+/**
+ * True when `value` is an `fx.json` envelope carrier.
+ *
+ * @param value - Unknown handler output
+ */
+export function isJsonResult(value: unknown): value is JsonResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as JsonResult)[jsonResultBrand] === true &&
+    (value as JsonStreamResult).kind !== "stream"
+  );
+}
+
+/**
+ * True when `value` is an SSE stream carrier from `fx.json.stream`.
+ *
+ * @param value - Unknown handler output
+ */
+export function isJsonStreamResult(value: unknown): value is JsonStreamResult {
+  return (
+    typeof value === "object" &&
+    value !== null &&
+    (value as JsonStreamResult)[jsonResultBrand] === true &&
+    (value as JsonStreamResult).kind === "stream"
+  );
+}

package/src/kernel/project-out.ts

@@ -12,7 +12,12 @@
 
 import type { SchemaInput } from "../validation/standard-schema.ts";
 import { validate } from "../validation/standard-schema.ts";
-import { isJsonResult, isJsonStreamResult, jsonResultBrand, type JsonResult } from "./fx.ts";
+import {
+  isJsonResult,
+  isJsonStreamResult,
+  jsonResultBrand,
+  type JsonResult,
+} from "./json-result.ts";
 
 /**
  * Project `output` through `schema` when the exposure declared `out`.

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;
+}