okengine 0.2.8 → 0.3.4

package/src/elements/store/sql-session.ts

@@ -10,10 +10,17 @@ import type { ClassificationMap, SqlConnection, SqlRow } from "../../drivers/typ
 import { throwOke } from "../../kernel/errors.ts";
 import { maskRows, tableFromSql } from "./classify.ts";
 import { isMissingDomainRelationError } from "./missing-relation.ts";
-import { compileWhere, resolveSelectColumns, type WhereMap } from "./sql-condition.ts";
+import {
+  andWhere,
+  compileOrderBy,
+  compileWhere,
+  resolveSelectColumns,
+  type WhereMap,
+} from "./sql-condition.ts";
 import {
   mapRowToJs,
   prepareInsertRow,
+  prepareUpdateRow,
   resolveColumns,
   resolveTableName,
   type TableHandle,
@@ -40,28 +47,80 @@ export interface SqlSessionOptions {
 }
 
 /**
- * Continuations after `.where(...)` on a select — awaitable, optional `.limit`.
+ * Continuations after `.orderBy(...)` — awaitable, optional `.limit` /
+ * `.offset`.
+ */
+export interface SelectOrderBuilder extends PromiseLike<SqlRow[]> {
+  /**
+   * Cap the number of returned rows.
+   *
+   * @param n - Max rows
+   */
+  limit(n: number): Promise<SqlRow[]>;
+  /**
+   * Skip the first `n` rows (`LIMIT … OFFSET …`).
+   *
+   * @param n - Rows to skip
+   */
+  offset(n: number): Promise<SqlRow[]>;
+}
+
+/**
+ * Continuations after `.where(...)` on a select — awaitable, optional
+ * `.orderBy(...)` / `.limit(...)` / `.offset(...)`.
  */
 export interface SelectWhereBuilder extends PromiseLike<SqlRow[]> {
+  /**
+   * Order rows with Drizzle `asc()` / `desc()` terms.
+   *
+   * @param orders - Order terms
+   */
+  orderBy(...orders: readonly unknown[]): SelectOrderBuilder;
   /**
    * Cap the number of returned rows.
    *
    * @param n - Max rows
    */
   limit(n: number): Promise<SqlRow[]>;
+  /**
+   * Skip the first `n` rows.
+   *
+   * @param n - Rows to skip
+   */
+  offset(n: number): Promise<SqlRow[]>;
 }
 
 /**
- * Result of `.from(table)` — awaitable (all rows) or chain `.where(...)`.
+ * Result of `.from(table)` — awaitable (all rows) or chain
+ * `.where(...)` / `.orderBy(...)` / `.limit(...)` / `.offset(...)` in any
+ * order.
  */
 export interface SelectFromBuilder extends PromiseLike<SqlRow[]> {
   /**
    * Filter with a plain equality map or a Drizzle SQL condition
-   * (`eq`, `and`, `lt`, …).
+   * (`eq`, `and`, `or`, `lt`, `like`, …).
    *
    * @param where - Condition
    */
   where(where: unknown): SelectWhereBuilder;
+  /**
+   * Order rows with Drizzle `asc()` / `desc()` terms.
+   *
+   * @param orders - Order terms
+   */
+  orderBy(...orders: readonly unknown[]): SelectOrderBuilder;
+  /**
+   * Cap the number of returned rows.
+   *
+   * @param n - Max rows
+   */
+  limit(n: number): Promise<SqlRow[]>;
+  /**
+   * Skip the first `n` rows.
+   *
+   * @param n - Rows to skip
+   */
+  offset(n: number): Promise<SqlRow[]>;
 }
 
 /** Fluent select builder. */
@@ -194,6 +253,21 @@ export interface SqlStoreHandle {
    * @param params - Bound parameters
    */
   raw(sql: string, params?: readonly unknown[]): Promise<SqlRow[]>;
+  /**
+   * Count rows (`COUNT(*)`), optionally filtered.
+   *
+   * @param table - Table
+   * @param where - Optional condition
+   */
+  count(table: TableHandle | unknown, where?: unknown): Promise<number>;
+  /**
+   * One page of rows — offset or keyset mode, composed through the same
+   * fluent select path (Drizzle conditions in, `compileWhere` out).
+   *
+   * @param table - Table
+   * @param options - Page options
+   */
+  page(table: TableHandle | unknown, options: SqlPageOptions): Promise<SqlRow[]>;
   /**
    * Ensure a simple table exists (test / bootstrap helper).
    *
@@ -202,6 +276,24 @@ export interface SqlStoreHandle {
   ensureTable(table: TableHandle): Promise<void>;
 }
 
+/** Options for {@link SqlStoreHandle.page}. */
+export interface SqlPageOptions {
+  /** Filter condition (equality map or Drizzle SQL). */
+  readonly where?: unknown;
+  /** Drizzle `asc()` / `desc()` terms (or bare columns). */
+  readonly orderBy?: readonly unknown[];
+  /** Max rows to return. */
+  readonly limit?: number;
+  /** Offset mode — skip rows (uses `OFFSET`). */
+  readonly offset?: number;
+  /**
+   * Keyset mode — a Drizzle SQL condition describing "rows strictly after
+   * the cursor" (composed by the caller / `store.resource`); ANDed onto
+   * `where`. Cannot combine with `offset`.
+   */
+  readonly after?: unknown;
+}
+
 /**
  * Create a SQL store handle over a connection.
  *
@@ -287,11 +379,18 @@ export function createSqlStoreHandle(
     return compileWhere(where);
   }
 
+  /** Accumulated select state across the fluent chain. */
+  interface SelectPlan {
+    readonly where?: unknown;
+    readonly orders?: readonly unknown[];
+    readonly limit?: number;
+    readonly offset?: number;
+  }
+
   async function runSelect(
     table: TableHandle | unknown,
     projection: ReturnType<typeof resolveSelectColumns>,
-    where: unknown | undefined,
-    limit?: number,
+    plan: SelectPlan = {},
   ): Promise<SqlRow[]> {
     await ensureFromMeta(table);
     const name = resolveTableName(table);
@@ -308,20 +407,31 @@ export function createSqlStoreHandle(
 
     let sql = `SELECT ${selectList} FROM ${quoteIdent(name)}`;
     const params: unknown[] = [];
-    if (where !== undefined) {
-      const compiled = compileTableWhere(table, where);
+    if (plan.where !== undefined) {
+      const compiled = compileTableWhere(table, plan.where);
       if (compiled.clause) {
         sql += ` WHERE ${compiled.clause}`;
         params.push(...compiled.params);
       }
     }
-    if (limit !== undefined) {
-      sql += ` LIMIT ${Math.max(0, Math.floor(limit))}`;
+    if (plan.orders !== undefined && plan.orders.length > 0) {
+      const terms = compileOrderBy(plan.orders);
+      sql += ` ORDER BY ${terms.map((o) => `${quoteIdent(o.column)} ${o.direction}`).join(", ")}`;
+    }
+    if (plan.limit !== undefined) {
+      sql += ` LIMIT ${Math.max(0, Math.floor(plan.limit))}`;
+    }
+    if (plan.offset !== undefined) {
+      sql += ` OFFSET ${Math.max(0, Math.floor(plan.offset))}`;
     }
 
     const rows = await query(sql, params);
+    // Map to declared JS keys first, then mask — classifications are keyed by
+    // TS field names (`email`), so masking before remapping would miss a
+    // `.pii()` column whose SQL name differs (`email_addr`) and leak cleartext
+    // under the final client-facing key.
     if (projection === null) {
-      return toJs(table, mask(rows, name));
+      return mask(toJs(table, rows), name);
     }
     // Projected aliases are already the returned keys.
     return mask(
@@ -338,21 +448,37 @@ export function createSqlStoreHandle(
 
   function selectFrom(table: TableHandle | unknown, columns?: unknown): SelectFromBuilder {
     const projection = resolveSelectColumns(columns);
-    const all = runSelect(table, projection, undefined);
+
+    // Builders are lazy: the query runs on the first await / `.limit(n)` /
+    // `.offset(n)`, so a chained `where → orderBy → limit` issues one SELECT.
+    function tail(plan: SelectPlan): SelectOrderBuilder {
+      return {
+        limit(n) {
+          return runSelect(table, projection, { ...plan, limit: n });
+        },
+        offset(n) {
+          return runSelect(table, projection, { ...plan, offset: n });
+        },
+        then(onfulfilled, onrejected) {
+          return runSelect(table, projection, plan).then(onfulfilled, onrejected);
+        },
+      };
+    }
+
+    function filtered(where: unknown): SelectWhereBuilder {
+      const plan: SelectPlan = where === undefined ? {} : { where };
+      return {
+        ...tail(plan),
+        orderBy(...orders) {
+          return tail({ ...plan, orders });
+        },
+      };
+    }
+
     return {
+      ...filtered(undefined),
       where(where) {
-        const filtered = runSelect(table, projection, where);
-        return {
-          limit(n) {
-            return runSelect(table, projection, where, n);
-          },
-          then(onfulfilled, onrejected) {
-            return filtered.then(onfulfilled, onrejected);
-          },
-        };
-      },
-      then(onfulfilled, onrejected) {
-        return all.then(onfulfilled, onrejected);
+        return filtered(where);
       },
     };
   }
@@ -394,7 +520,7 @@ export function createSqlStoreHandle(
               const params = cols.map((c) => prepared[c]);
               const sql = `INSERT INTO ${quoteIdent(name)} (${colList}) VALUES (${placeholders}) RETURNING *`;
               const rows = await query(sql, params);
-              return toJs(table, mask(rows, name));
+              return mask(toJs(table, rows), name);
             },
             execute: runExecute,
             then(onfulfilled, onrejected) {
@@ -412,7 +538,7 @@ export function createSqlStoreHandle(
           return {
             async where(where) {
               await ensureFromMeta(table);
-              const prepared = prepareInsertRow(table, row);
+              const prepared = prepareUpdateRow(table, row);
               const setEntries = Object.entries(prepared);
               if (setEntries.length === 0) return 0;
               const setSql = setEntries.map(([col]) => `${quoteIdent(col)} = ?`).join(", ");
@@ -439,7 +565,7 @@ export function createSqlStoreHandle(
       const rows = await query(`SELECT * FROM ${quoteIdent(name)} WHERE ${quoteIdent(pk)} = ?`, [
         idValue,
       ]);
-      const masked = toJs(table, mask(rows, name));
+      const masked = mask(toJs(table, rows), name);
       return masked[0] ?? null;
     },
 
@@ -516,6 +642,40 @@ export function createSqlStoreHandle(
       return mask(rows, table);
     },
 
+    async count(table, where) {
+      await ensureFromMeta(table);
+      const name = resolveTableName(table);
+      let sql = `SELECT COUNT(*) AS "count" FROM ${quoteIdent(name)}`;
+      const params: unknown[] = [];
+      if (where !== undefined) {
+        const compiled = compileTableWhere(table, where);
+        if (compiled.clause) {
+          sql += ` WHERE ${compiled.clause}`;
+          params.push(...compiled.params);
+        }
+      }
+      const rows = await query(sql, params);
+      return asNumber(rows[0]?.count ?? rows[0]?.COUNT ?? 0, "count");
+    },
+
+    async page(table, options) {
+      if (options.offset !== undefined && options.after !== undefined) {
+        throw new Error("page(): offset and after (keyset) cannot combine");
+      }
+      const where =
+        options.after === undefined
+          ? options.where
+          : options.where === undefined
+            ? options.after
+            : andWhere(options.where, options.after);
+      return runSelect(table, null, {
+        where,
+        orders: options.orderBy,
+        limit: options.limit,
+        offset: options.offset,
+      });
+    },
+
     async ensureTable(table) {
       const cols = Object.values(table.columns);
       const pk = resolvePkColumn(table);

package/src/elements/store/table.ts

@@ -252,10 +252,39 @@ export function prepareInsertRow(
 }
 
 /**
- * Map a SQL-keyed row back to JS keys when Drizzle/TableHandle metadata exists.
+ * Map a JS-keyed partial row to SQL column names for `UPDATE … SET`.
+ * Unlike {@link prepareInsertRow}, `$defaultFn`s are never applied — column
+ * defaults are insert physics, not update physics.
  *
  * @param table - Table-like value
- * @param row - Driver row
+ * @param row - Incoming values (JS keys)
+ */
+export function prepareUpdateRow(
+  table: unknown,
+  row: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const cols = resolveColumns(table);
+  if (cols.length === 0) return { ...row };
+  const byKey = new Map(cols.map((c) => [c.key, c]));
+  const bySql = new Map(cols.map((c) => [c.sqlName, c]));
+  const out: Record<string, unknown> = {};
+  for (const [k, v] of Object.entries(row)) {
+    const col = byKey.get(k) ?? bySql.get(k);
+    out[col?.sqlName ?? k] = v;
+  }
+  return out;
+}
+
+/**
+ * Map a SQL-keyed driver row to declared JS field names only.
+ *
+ * When Drizzle/TableHandle metadata exists, the result contains exactly the
+ * table's declared keys (`createdAt`) — never the raw SQL names
+ * (`created_at`) alongside or instead of them. Without metadata, the row is
+ * returned as-is (opaque / raw SQL).
+ *
+ * @param table - Table-like value
+ * @param row - Driver row (SQL column names, or already JS-keyed)
  */
 export function mapRowToJs(
   table: unknown,
@@ -263,9 +292,10 @@ export function mapRowToJs(
 ): Record<string, unknown> {
   const cols = resolveColumns(table);
   if (cols.length === 0) return { ...row };
-  const out: Record<string, unknown> = { ...row };
+  const out: Record<string, unknown> = {};
   for (const col of cols) {
-    if (col.sqlName in row) out[col.key] = row[col.sqlName];
+    if (col.key in row) out[col.key] = row[col.key];
+    else if (col.sqlName in row) out[col.key] = row[col.sqlName];
   }
   return out;
 }

package/src/elements/store.ts

@@ -78,14 +78,30 @@ export type { SqlBindingConfig } from "./store/replica.ts";
 export { defineTable, resolveTableName, classificationsFromTable, id, now } from "./store/table.ts";
 export type { ColumnDef, TableHandle } from "./store/table.ts";
 
+export { resource } from "./store/resource.ts";
+export type {
+  ColumnScope,
+  ListCountMode,
+  ListPageMode,
+  ResourceColumns,
+  ResourceDef,
+  ResourceFlowDefs,
+  ResourceListOptions,
+  ResourceOptions,
+  ResolvedListConfig,
+} from "./store/resource.ts";
+
 export { createSqlStoreHandle, resolvePkColumn } from "./store/sql-session.ts";
 export type {
   SqlStoreHandle,
   SelectBuilder,
   SelectFromBuilder,
+  SelectWhereBuilder,
+  SelectOrderBuilder,
   InsertBuilder,
   InsertValuesBuilder,
   SqlSessionOptions,
+  SqlPageOptions,
   WhereMap,
 } from "./store/sql-session.ts";
 

package/src/elements/vault/runtime.ts

@@ -71,7 +71,7 @@ export interface CreateVaultRuntimeOptions {
   readonly secrets?: readonly VaultSecretDecl[];
   /**
    * Resolution chain — first hit wins.
-   * Default for prod: `[sops]`; for tests callers pass memory/env layers.
+   * Callers pass the env-appropriate layers (env / openbao / memory / …).
    */
   readonly chain?: readonly VaultChainLayer[];
   /**

package/src/elements/vault.test.ts

@@ -4,17 +4,10 @@
  * - a secret value never appears in a log or trace even when passed to fx.log
  * - fingerprints instead of values
  * - resolution chain (first hit wins)
- * - sops/age via Typage (in-process, no Go binary)
  */
 
 import { describe, expect, test } from "bun:test";
-import * as age from "age-encryption";
-import {
-  buildSopsFixture,
-  envVaultDriver,
-  memoryVaultDriver,
-  sopsVaultDriver,
-} from "../drivers/index.ts";
+import { envVaultDriver, memoryVaultDriver } from "../drivers/index.ts";
 import { createFx } from "../kernel/fx.ts";
 import {
   createVaultRuntime,
@@ -239,26 +232,6 @@ describe("redaction + fingerprints", () => {
   });
 });
 
-describe("sops / age (Typage)", () => {
-  test("decrypts SOPS JSON in-process with age-encryption", async () => {
-    const identity = await age.generateIdentity();
-    const recipient = await age.identityToRecipient(identity);
-    const { json } = await buildSopsFixture({ STRIPE_KEY: "sk_sops_decrypted" }, recipient);
-
-    const runtime = createVaultRuntime({
-      secrets: [vault("STRIPE_KEY")],
-      chain: [
-        {
-          driver: sopsVaultDriver,
-          options: { ciphertext: json, ageIdentity: identity },
-        },
-      ],
-    });
-    await runtime.boot();
-    expect(runtime.read("STRIPE_KEY")).toBe("sk_sops_decrypted");
-  });
-});
-
 /**
  * Helper — createFx with vault runtime + log sink.
  */

package/src/elements/vault.ts

@@ -2,7 +2,7 @@
  * Vault element — protected knowledge.
  *
  * Physics: secrets · config · environment.
- * Drivers: `sops` (Typage/age) · `env` · `openbao` · `infisical` · `managed`.
+ * Drivers: `env` · `openbao` · `infisical` · `managed`.
  *
  * A declaration is a contract, never a value. Boot validates every contract
  * and lists all gaps at once. Logs/traces receive fingerprints and redaction

package/src/kernel/app.ts

@@ -62,7 +62,7 @@ import {
   isJournalSuspend,
   type JournalSession,
 } from "./journal.ts";
-import { listBindings, type Binding } from "./on.ts";
+import { listBindings, resetBindings, type Binding } from "./on.ts";
 import {
   applyPrincipal,
   createElementPipelineHooks,
@@ -102,8 +102,23 @@ export interface OkeOptions {
    * Default `true`.
    */
   readonly aot?: boolean;
-  /** Extra bindings (in addition to the global {@link on} registry). */
+  /**
+   * Extra bindings. Combined with the global {@link on} registry unless
+   * {@link OkeOptions.registry} is `"ignore"` — then this is the only source.
+   */
   readonly bindings?: readonly Binding[];
+  /**
+   * How the global {@link on} registry is treated at construction.
+   *
+   * - `"consume"` (default) — adopt registered bindings, then clear the
+   *   registry so a later {@link oke} in the same process cannot inherit
+   *   this app's flows.
+   * - `"keep"` — adopt registered bindings and leave the registry intact
+   *   (legacy behavior).
+   * - `"ignore"` — adopt only {@link OkeOptions.bindings}; the registry is
+   *   neither read nor cleared (embedding / Console).
+   */
+  readonly registry?: "consume" | "keep" | "ignore";
   /** Base fx options applied to every invocation. */
   readonly fx?: Omit<CreateFxOptions, "flow" | "effects" | "capability">;
   /**
@@ -383,7 +398,12 @@ export interface OkeApp<D extends Record<string, unknown> = {}, R extends AppRou
  */
 export function oke(options: OkeOptions): OkeApp {
   const aot = options.aot !== false;
-  const adopted: Binding[] = [...listBindings(), ...(options.bindings ?? [])];
+  const registry = options.registry ?? "consume";
+  const adopted: Binding[] =
+    registry === "ignore"
+      ? [...(options.bindings ?? [])]
+      : [...listBindings(), ...(options.bindings ?? [])];
+  if (registry === "consume") resetBindings();
   /** Retained for test harness / boot merges. */
   const $options = options;
 
@@ -654,29 +674,37 @@ export function oke(options: OkeOptions): OkeApp {
 
     const alreadyValidated = extras?.validated === true;
 
-    const result = await runPipeline(ctx, fx, hooks, async () => {
-      try {
-        if (!alreadyValidated) {
-          const parsed = await validate(flowDef.in, ctx.input);
-          if (!parsed.ok) return parsed.failure;
-          ctx.input = parsed.value;
-          return await flowDef.do(parsed.value as never, fx);
-        }
-        return await flowDef.do(ctx.input as never, fx);
-      } catch (err) {
-        // A durable sleep that has not yet elapsed suspends the run — this
-        // is a park, not a pipeline failure, so it must not throw upward.
-        if (flowDef.durable && journalSession && isJournalSuspend(err)) {
-          ctx.state.sleeping = {
-            wakeAt: err.wakeAt,
-            label: err.label,
-            runId: journalSession.runId,
-          };
-          return undefined;
+    const result = await runPipeline(
+      ctx,
+      fx,
+      hooks,
+      async () => {
+        try {
+          if (!alreadyValidated) {
+            const parsed = await validate(flowDef.in, ctx.input);
+            if (!parsed.ok) return parsed.failure;
+            ctx.input = parsed.value;
+            return await flowDef.do(parsed.value as never, fx);
+          }
+          return await flowDef.do(ctx.input as never, fx);
+        } catch (err) {
+          // A durable sleep that has not yet elapsed suspends the run — this
+          // is a park, not a pipeline failure, so it must not throw upward.
+          if (flowDef.durable && journalSession && isJournalSuspend(err)) {
+            ctx.state.sleeping = {
+              wakeAt: err.wakeAt,
+              label: err.label,
+              runId: journalSession.runId,
+            };
+            return undefined;
+          }
+          throw err;
         }
-        throw err;
-      }
-    });
+      },
+      // HTTP flows serialize before `onResponse` so the last stage can see
+      // and replace the final response (plugin header/middleware surfaces).
+      trigger.kind === "http" ? encodeExecuteResult : undefined,
+    );
 
     const endedAt = now();
 
@@ -905,6 +933,12 @@ export function oke(options: OkeOptions): OkeApp {
 
       const matched = router.match(method, url.pathname);
       if (!matched) {
+        // Plugin edge handlers answer requests no flow owns (e.g. CORS
+        // preflight for a path bound to another method) — first Response wins.
+        for (const handle of pluginRegistry.edgeHandlers()) {
+          const edgeResponse = await handle(request, { method, path: url.pathname });
+          if (edgeResponse !== undefined) return respond(edgeResponse);
+        }
         return respond(new Response("Not Found", { status: 404 }));
       }
       const { value: binding, params } = matched;

package/src/kernel/boot-bind/channel.test.ts

@@ -0,0 +1,60 @@
+/**
+ * Channel binder — profile selection + SMTP env parsing.
+ */
+
+import { afterEach, describe, expect, test } from "bun:test";
+import { resolveEmailDriverId, smtpOptionsFromEnv } from "./channel.ts";
+
+const previous = {
+  url: process.env.SMTP_URL,
+  user: process.env.SMTP_USER,
+  password: process.env.SMTP_PASSWORD,
+  okeUrl: process.env.OKE_CHANNEL_EMAIL_URL,
+};
+
+afterEach(() => {
+  restoreEnv("SMTP_URL", previous.url);
+  restoreEnv("SMTP_USER", previous.user);
+  restoreEnv("SMTP_PASSWORD", previous.password);
+  restoreEnv("OKE_CHANNEL_EMAIL_URL", previous.okeUrl);
+});
+
+describe("bindChannel driver resolution", () => {
+  const options = {
+    config: {
+      drivers: {
+        channel: {
+          email: { local: "console", docker: "smtp", test: "console", prod: "smtp" },
+        },
+      },
+    },
+  };
+
+  test("uses console locally and smtp in docker", () => {
+    expect(resolveEmailDriverId(options, "local", false)).toBe("console");
+    expect(resolveEmailDriverId(options, "docker", true)).toBe("smtp");
+  });
+
+  test("parses SMTP_URL and optional auth overrides", () => {
+    process.env.SMTP_URL = "smtp://url-user:url-pass@127.0.0.1:20975";
+    process.env.SMTP_USER = "override-user";
+    process.env.SMTP_PASSWORD = "override-pass";
+    expect(smtpOptionsFromEnv(true)).toEqual({
+      host: "127.0.0.1",
+      port: 20975,
+      user: "override-user",
+      pass: "override-pass",
+    });
+  });
+
+  test("missing SMTP_URL includes docker recovery hint", () => {
+    delete process.env.SMTP_URL;
+    delete process.env.OKE_CHANNEL_EMAIL_URL;
+    expect(() => smtpOptionsFromEnv(true)).toThrow("docker/.env.docker");
+  });
+});
+
+function restoreEnv(key: string, value: string | undefined): void {
+  if (value === undefined) delete process.env[key];
+  else process.env[key] = value;
+}