okengine 0.20.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";
@@ -58,16 +61,9 @@ import {
   recordWouldHaveFired,
   touchDryRunStore,
 } from "./dry-run.ts";
-import { fail, type FailOptions, type FlowFailure } from "./errors.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";
 
@@ -82,9 +78,31 @@ import { okid } from "../okid.ts";
 import { lazyRequire } from "./lazy-require.ts";
 import type { AppMessageKey, MessageValues } from "../i18n/types.ts";
 
+function loadFail(): FailFn {
+  return lazyRequire<typeof import("./fail-helpers.ts")>(
+    import.meta.dir,
+    ["fail", "helpers"].join("-"),
+  ).fail;
+}
+
 /** 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(""));
 }
 
 /**
@@ -383,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");
 
@@ -435,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.
  *
@@ -884,11 +861,10 @@ export interface Fx {
   /**
    * Flow-boundary failure value (does not throw).
    *
-   * @param code - Declared error code (narrowed by clients via `error.code`)
-   * @param data - Error payload
-   * @param opts - Optional message
+   * Built-in helpers (`fx.fail.notFound`, `fx.fail.forbidden`, …) need no
+   * `errors:` declaration. Domain codes still use `fx.fail("OutOfStock", data)`.
    */
-  fail<E>(code: string, data: E, opts?: FailOptions): FlowFailure<E>;
+  readonly fail: FailFn;
   /** JSON response helpers (status + Stripe-style envelope). */
   readonly json: FxJson;
   /**
@@ -1287,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",
@@ -1611,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),
         });
       }
 
@@ -2246,7 +1960,7 @@ export function createFxContext(options: CreateFxOptions): FxContext {
     operator,
     principal,
     tenant,
-    fail,
+    fail: loadFail(),
     json: {
       ok<T>(value: T, opts?: { readonly meta?: Record<string, unknown> }): JsonResult<T> {
         return {
@@ -2286,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/index.ts

@@ -106,14 +106,15 @@ export {
   type RunTelemetry,
 } from "./run-telemetry.ts";
 
+export { fail } from "./fail-helpers.ts";
 export {
-  fail,
   formatOkeMessage,
   lookupOkeError,
   OKE_ERROR_RANGES,
   OKE_ERRORS,
   OkeError,
   throwOke,
+  type FailFn,
   type FailOptions,
   type FlowErrorValue,
   type FlowFailure,
@@ -122,6 +123,16 @@ export {
   type OkeErrorDomain,
   type OkeErrorParams,
 } from "./errors.ts";
+export {
+  BUILTIN_ERROR_STATUS,
+  httpStatusForFailure,
+  statusForBuiltinError,
+  type BuiltinErrorBag,
+  type BuiltinErrorCode,
+  type BuiltinErrorMap,
+  type BuiltinValidationIssue,
+  type DatabaseErrorReason,
+} from "./builtin-errors.ts";
 
 export {
   flow,

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`.