okengine 0.1.4

package/src/elements/store/table.ts

@@ -0,0 +1,282 @@
+/**
+ * Lightweight table handles for the sql facet.
+ *
+ * Drizzle table objects are accepted via duck-typing when the peer is present;
+ * this module never imports `drizzle-orm` so it stays unbundled.
+ */
+
+import type { ColumnClassification } from "../../manifest/types.ts";
+
+/** Column descriptor with optional classification. */
+export interface ColumnDef {
+  /** Column name in the database. */
+  readonly name: string;
+  /** Privacy / retention tags. */
+  readonly classification?: ColumnClassification;
+}
+
+/** Table handle used by `fx.store(db).select().from(table)`. */
+export interface TableHandle {
+  /** Table name. */
+  readonly name: string;
+  /** Column descriptors. */
+  readonly columns: Readonly<Record<string, ColumnDef>>;
+}
+
+/**
+ * Define a table handle with optional per-column classification.
+ *
+ * @param name - Table name
+ * @param columns - Column map (values may be `classify({ pii: true })` or full defs)
+ */
+export function defineTable(
+  name: string,
+  columns: Readonly<
+    Record<string, ColumnDef | ColumnClassification | true | undefined>
+  >,
+): TableHandle {
+  const resolved: Record<string, ColumnDef> = {};
+  for (const [key, value] of Object.entries(columns)) {
+    if (value === undefined || value === true) {
+      resolved[key] = { name: key };
+      continue;
+    }
+    if ("name" in value && typeof value.name === "string") {
+      resolved[key] = value as ColumnDef;
+      continue;
+    }
+    resolved[key] = {
+      name: key,
+      classification: value as ColumnClassification,
+    };
+  }
+  return { name, columns: resolved };
+}
+
+/** One introspected column (TableHandle or Drizzle). */
+export interface ResolvedColumn {
+  /** JS / object key (e.g. `createdAt`). */
+  readonly key: string;
+  /** Database column name (e.g. `created_at`). */
+  readonly sqlName: string;
+  /** Whether this column is the primary key. */
+  readonly primary: boolean;
+  /** SQL type hint for DDL. */
+  readonly sqlType: "TEXT" | "INTEGER" | "REAL" | "BLOB";
+  /** Optional `$defaultFn` from Drizzle. */
+  readonly defaultFn?: () => unknown;
+}
+
+/**
+ * Resolve a table name from an okengine {@link TableHandle} or a Drizzle table.
+ *
+ * @param table - Table-like value
+ */
+export function resolveTableName(table: unknown): string {
+  if (typeof table === "string") return table;
+  if (table && typeof table === "object") {
+    const t = table as Record<string, unknown>;
+    if (typeof t.name === "string" && !isDrizzleTable(t)) return t.name;
+    // Drizzle stores the name on an internal symbol; also expose via _.name / [Symbol]
+    for (const key of Object.getOwnPropertySymbols(t)) {
+      const val = (t as Record<symbol, unknown>)[key];
+      if (typeof val === "string" && /^[a-zA-Z_][a-zA-Z0-9_]*$/.test(val)) {
+        return val;
+      }
+    }
+    const underscore = t._;
+    if (underscore && typeof underscore === "object") {
+      const name = (underscore as { name?: unknown }).name;
+      if (typeof name === "string") return name;
+    }
+  }
+  throw new TypeError("Unable to resolve table name from value");
+}
+
+/**
+ * True when `table` looks like a Drizzle table object.
+ *
+ * @param t - Candidate
+ */
+export function isDrizzleTable(t: Record<string, unknown>): boolean {
+  if ("columns" in t && t.columns && typeof t.columns === "object") {
+    // okengine TableHandle
+    return false;
+  }
+  for (const key of Object.getOwnPropertySymbols(t)) {
+    if (String(key).includes("IsDrizzleTable")) {
+      return (t as Record<symbol, unknown>)[key] === true;
+    }
+  }
+  return ("$" in t || "_" in t) && !("columns" in t);
+}
+
+/**
+ * Introspect columns from a TableHandle or Drizzle table.
+ *
+ * @param table - Table-like value
+ */
+export function resolveColumns(table: unknown): ResolvedColumn[] {
+  if (table && typeof table === "object") {
+    const t = table as Record<string, unknown>;
+    if ("columns" in t && t.columns && typeof t.columns === "object") {
+      return Object.entries(t.columns as Record<string, ColumnDef>).map(
+        ([key, col]) => ({
+          key,
+          sqlName: col.name,
+          primary: col.name === "id" || key === "id",
+          sqlType: "TEXT" as const,
+        }),
+      );
+    }
+    if (isDrizzleTable(t)) {
+      return drizzleColumns(t);
+    }
+  }
+  return [];
+}
+
+function drizzleColumns(t: Record<string, unknown>): ResolvedColumn[] {
+  let cols: Record<string, unknown> | undefined;
+  for (const key of Object.getOwnPropertySymbols(t)) {
+    if (String(key).includes("Columns") && !String(key).includes("Extra")) {
+      const val = (t as Record<symbol, unknown>)[key];
+      if (val && typeof val === "object") {
+        cols = val as Record<string, unknown>;
+        break;
+      }
+    }
+  }
+  if (!cols) {
+    // Fallback: own enumerable column keys on the table object.
+    cols = {};
+    for (const [key, val] of Object.entries(t)) {
+      if (val && typeof val === "object" && "name" in (val as object)) {
+        cols[key] = val;
+      }
+    }
+  }
+  const out: ResolvedColumn[] = [];
+  for (const [key, raw] of Object.entries(cols)) {
+    if (!raw || typeof raw !== "object") continue;
+    const col = raw as {
+      name?: string;
+      primary?: boolean;
+      columnType?: string;
+      dataType?: string;
+      defaultFn?: () => unknown;
+      config?: { primaryKey?: boolean };
+    };
+    const sqlName = typeof col.name === "string" ? col.name : key;
+    const primary = Boolean(
+      col.primary || col.config?.primaryKey || sqlName === "id",
+    );
+    const sqlType = drizzleSqlType(col.columnType, col.dataType);
+    out.push({
+      key,
+      sqlName,
+      primary,
+      sqlType,
+      ...(typeof col.defaultFn === "function"
+        ? { defaultFn: col.defaultFn.bind(col) }
+        : {}),
+    });
+  }
+  return out;
+}
+
+function drizzleSqlType(
+  columnType: string | undefined,
+  dataType: string | undefined,
+): ResolvedColumn["sqlType"] {
+  const ct = (columnType ?? "").toLowerCase();
+  const dt = (dataType ?? "").toLowerCase();
+  if (ct.includes("int") || dt.includes("int") || dt.includes("number")) {
+    return "INTEGER";
+  }
+  if (ct.includes("real") || ct.includes("numeric") || dt.includes("float")) {
+    return "REAL";
+  }
+  if (ct.includes("blob") || dt.includes("buffer")) return "BLOB";
+  return "TEXT";
+}
+
+/**
+ * Map a JS-keyed row to SQL column names; apply Drizzle `$defaultFn`s.
+ *
+ * @param table - Table-like value
+ * @param row - Incoming values (JS keys)
+ */
+export function prepareInsertRow(
+  table: unknown,
+  row: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const cols = resolveColumns(table);
+  if (cols.length === 0) return { ...row };
+  const out: Record<string, unknown> = {};
+  const byKey = new Map(cols.map((c) => [c.key, c]));
+  const bySql = new Map(cols.map((c) => [c.sqlName, c]));
+
+  for (const col of cols) {
+    let value: unknown;
+    if (col.key in row) value = row[col.key];
+    else if (col.sqlName in row) value = row[col.sqlName];
+    else if (col.defaultFn) value = col.defaultFn();
+    else continue;
+    out[col.sqlName] = value;
+  }
+  // Pass through unknown keys as-is (already SQL names).
+  for (const [k, v] of Object.entries(row)) {
+    if (byKey.has(k) || bySql.has(k)) continue;
+    out[k] = v;
+  }
+  return out;
+}
+
+/**
+ * Map a SQL-keyed row back to JS keys when Drizzle/TableHandle metadata exists.
+ *
+ * @param table - Table-like value
+ * @param row - Driver row
+ */
+export function mapRowToJs(
+  table: unknown,
+  row: Readonly<Record<string, unknown>>,
+): Record<string, unknown> {
+  const cols = resolveColumns(table);
+  if (cols.length === 0) return { ...row };
+  const out: Record<string, unknown> = { ...row };
+  for (const col of cols) {
+    if (col.sqlName in row) out[col.key] = row[col.sqlName];
+  }
+  return out;
+}
+
+/**
+ * Extract classifications from a {@link TableHandle}.
+ *
+ * @param table - Table handle
+ */
+export function classificationsFromTable(
+  table: TableHandle,
+): Record<string, ColumnClassification> {
+  const out: Record<string, ColumnClassification> = {};
+  for (const [key, col] of Object.entries(table.columns)) {
+    if (col.classification) out[key] = col.classification;
+  }
+  return out;
+}
+
+/**
+ * Generate a unique id (UUID). Suitable for `$defaultFn(id)` in schemas.
+ */
+export function id(): string {
+  return crypto.randomUUID();
+}
+
+/**
+ * Current epoch-ms. Suitable for `$defaultFn(now)` in schemas.
+ */
+export function now(): number {
+  return Date.now();
+}

package/src/elements/store.test.ts

@@ -0,0 +1,370 @@
+/**
+ * Store element acceptance:
+ * - same flow runs unchanged against sqlite and postgres
+ * - read-only flow provably hits a replica
+ * - auto-invalidation fires on exactly the writes touching the read's keys
+ * - SELECT * masks classified columns
+ */
+
+import { describe, expect, test } from "bun:test";
+import {
+  createPostgresFakeClient,
+  postgresDriver,
+  sqliteDriver,
+} from "../drivers/index.ts";
+import type { Effects } from "../manifest/types.ts";
+import {
+  classify,
+  computedCacheKey,
+  createStoreCache,
+  createStoreRuntime,
+  defineTable,
+  id,
+  isInvalidatedByWrite,
+  isReadOnlyStoreFlow,
+  maskRows,
+  buildClassificationMap,
+  now,
+  PII_MASK,
+  resolveSqlTarget,
+  sqlRoleForEffects,
+  store,
+  tier1KeysForReads,
+  type SqlStoreHandle,
+} from "./store.ts";
+
+const notes = defineTable("notes", {
+  id: true,
+  title: true,
+  email: classify({ pii: true }),
+});
+
+function asSql(handle: unknown): SqlStoreHandle {
+  if (
+    !handle ||
+    typeof handle !== "object" ||
+    !("ensureTable" in handle) ||
+    typeof (handle as SqlStoreHandle).ensureTable !== "function"
+  ) {
+    throw new Error("expected sql handle");
+  }
+  return handle as SqlStoreHandle;
+}
+
+/** Flow body — identical for every SQL driver. */
+async function notesFlow(handle: SqlStoreHandle) {
+  await handle.ensureTable(notes);
+  const [created] = await handle
+    .insert(notes)
+    .values({ id: id(), title: "t", email: "secret@example.com" })
+    .returning();
+  const listed = await handle.select().from(notes);
+  const got = await handle.findById(notes, String(created!.id));
+  return { created, listed, got };
+}
+
+describe("store facets", () => {
+  test("declares sql · kv · files · index with resource refs", () => {
+    expect(store.sql("notes").ref).toBe("sql:notes");
+    expect(store.kv("sessions").ref).toBe("kv:sessions");
+    expect(store.files("uploads").ref).toBe("files:uploads");
+    expect(store.index("kb", { dims: 8 }).ref).toBe("index:kb");
+  });
+
+  test("id and now helpers", () => {
+    expect(id()).toMatch(
+      /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i,
+    );
+    expect(now()).toBeGreaterThan(0);
+  });
+});
+
+describe("same flow against sqlite and postgres", () => {
+  test("insert / select / findById unchanged across drivers", async () => {
+    const decl = store.sql("notes", {
+      schema: { notes },
+      classify: { notes: { email: classify({ pii: true }) } },
+    });
+
+    for (const [label, driver, client] of [
+      ["sqlite", sqliteDriver, undefined],
+      ["postgres", postgresDriver, createPostgresFakeClient()],
+    ] as const) {
+      const runtime = createStoreRuntime({
+        drivers: { sql: driver },
+        sql: {
+          notes: {
+            name: "notes",
+            primary: { url: ":memory:", client },
+          },
+        },
+      });
+      runtime.register(decl);
+      const handle = asSql(
+        await runtime.open(decl, {
+          effects: { writes: ["sql:notes"], reads: ["sql:notes"] },
+        }),
+      );
+      const result = await notesFlow(handle);
+      expect(result.created?.title, label).toBe("t");
+      expect(result.listed).toHaveLength(1);
+      expect(result.got?.id, label).toBe(result.created?.id);
+      // PII masked at boundary even through the flow
+      expect(result.listed[0]?.email, label).toBe(PII_MASK);
+      await runtime.close();
+    }
+  });
+});
+
+describe("replica routing from effects", () => {
+  test("read-only flows are detected from the effect set", () => {
+    expect(isReadOnlyStoreFlow({ reads: ["sql:notes"] })).toBe(true);
+    expect(
+      isReadOnlyStoreFlow({ reads: ["sql:notes"], writes: ["sql:notes"] }),
+    ).toBe(false);
+    expect(sqlRoleForEffects({ reads: ["sql:notes"] }, true)).toBe("replica");
+    expect(
+      sqlRoleForEffects({ reads: ["sql:notes"], writes: ["sql:notes"] }, true),
+    ).toBe("primary");
+  });
+
+  test("read-only flow provably hits a replica", async () => {
+    const primaryClient = createPostgresFakeClient();
+    const replicaClient = createPostgresFakeClient();
+    // Seed replica only — if primary were used, SELECT would be empty.
+    await replicaClient.unsafe(
+      `CREATE TABLE IF NOT EXISTS "notes" ("id" TEXT PRIMARY KEY, "title" TEXT, "email" TEXT)`,
+    );
+    await replicaClient.unsafe(
+      `INSERT INTO "notes" ("id", "title", "email") VALUES ($1, $2, $3)`,
+      ["n1", "from-replica", "x@y.z"],
+    );
+
+    const decl = store.sql("notes", {
+      classify: { notes: { email: classify({ pii: true }) } },
+    });
+    const runtime = createStoreRuntime({
+      drivers: { sql: postgresDriver },
+      sql: {
+        notes: {
+          name: "notes",
+          primary: { client: primaryClient },
+          replicas: [{ client: replicaClient }],
+        },
+      },
+    });
+    runtime.register(decl);
+
+    const readEffects: Effects = { reads: ["sql:notes"] };
+    const handle = asSql(await runtime.open(decl, { effects: readEffects }));
+    expect(handle.routedRole).toBe("replica");
+    const rows = await handle.raw(`SELECT * FROM notes`);
+    expect(rows).toHaveLength(1);
+    expect(rows[0]?.title).toBe("from-replica");
+
+    const writeHandle = asSql(
+      await runtime.open(decl, {
+        effects: { reads: ["sql:notes"], writes: ["sql:notes"] },
+      }),
+    );
+    expect(writeHandle.routedRole).toBe("primary");
+    await runtime.close();
+  });
+
+  test("resolveSqlTarget picks replica options", () => {
+    const target = resolveSqlTarget(
+      {
+        primary: { url: "postgres://primary" },
+        replicas: [{ url: "postgres://replica-1" }],
+      },
+      { reads: ["sql:notes"] },
+    );
+    expect(target.role).toBe("replica");
+    expect(target.options.url).toBe("postgres://replica-1");
+  });
+});
+
+describe("tier-1 cache invalidation from effects", () => {
+  test("auto-invalidation fires on exactly the writes touching the read's keys", () => {
+    const cache = createStoreCache();
+    const readEffects: Effects = { reads: ["sql:notes"] };
+    const keys = tier1KeysForReads(readEffects);
+    expect(keys).toEqual([computedCacheKey("sql:notes")]);
+
+    cache.set({
+      tier: 1,
+      key: keys[0]!,
+      value: [{ id: "n1" }],
+      resources: ["sql:notes"],
+      expiresAt: null,
+    });
+    cache.set({
+      tier: 1,
+      key: computedCacheKey("sql:orders"),
+      value: [],
+      resources: ["sql:orders"],
+      expiresAt: null,
+    });
+    cache.set({
+      tier: 3,
+      key: "fx-rate:USD-SAR",
+      value: 3.75,
+      resources: [],
+      expiresAt: null,
+    });
+
+    expect(isInvalidatedByWrite(keys[0]!, { writes: ["sql:notes"] })).toBe(
+      true,
+    );
+    expect(isInvalidatedByWrite(keys[0]!, { writes: ["sql:orders"] })).toBe(
+      false,
+    );
+
+    const event = cache.invalidateFromEffects({ writes: ["sql:notes"] });
+    expect(event.keys).toEqual([computedCacheKey("sql:notes")]);
+    expect(cache.get(computedCacheKey("sql:notes"))).toBeUndefined();
+    expect(cache.get<unknown[]>(computedCacheKey("sql:orders"))).toEqual([]);
+    expect(cache.get<number>("fx-rate:USD-SAR")).toBe(3.75);
+  });
+
+  test("runtime putTier1 + onWriteEffects", async () => {
+    const runtime = createStoreRuntime({
+      drivers: { sql: sqliteDriver },
+      sql: { notes: { name: "notes", primary: { url: ":memory:" } } },
+    });
+    const keys = runtime.putTier1({ reads: ["sql:notes"] }, ["cached"]);
+    expect(runtime.cache.get<string[]>(keys[0]!)).toEqual(["cached"]);
+    const ev = runtime.onWriteEffects({ writes: ["sql:notes"] });
+    expect(ev.keys).toEqual(keys);
+    await runtime.close();
+  });
+});
+
+describe("exists and increment helpers", () => {
+  const counters = defineTable("counters", {
+    id: true,
+    clicks: true,
+  });
+
+  test("exists returns correctly for present / absent rows across sqlite and postgres", async () => {
+    for (const [label, driver, client] of [
+      ["sqlite", sqliteDriver, undefined],
+      ["postgres", postgresDriver, createPostgresFakeClient()],
+    ] as const) {
+      const decl = store.sql("counters");
+      const runtime = createStoreRuntime({
+        drivers: { sql: driver },
+        sql: {
+          counters: {
+            name: "counters",
+            primary: { url: ":memory:", client },
+          },
+        },
+      });
+      runtime.register(decl);
+      const handle = asSql(
+        await runtime.open(decl, {
+          effects: { writes: ["sql:counters"], reads: ["sql:counters"] },
+        }),
+      );
+      await handle.ensureTable(counters);
+      await handle
+        .insert(counters)
+        .values({ id: "c1", clicks: 0 })
+        .execute();
+
+      expect(await handle.exists(counters, { id: "c1" }), label).toBe(true);
+      expect(await handle.exists(counters, { id: "gone" }), label).toBe(false);
+      await runtime.close();
+    }
+  });
+
+  test("increment under 100 concurrent callers lands on the correct final value", async () => {
+    for (const [label, driver, client] of [
+      ["sqlite", sqliteDriver, undefined],
+      ["postgres", postgresDriver, createPostgresFakeClient()],
+    ] as const) {
+      const decl = store.sql("counters");
+      const runtime = createStoreRuntime({
+        drivers: { sql: driver },
+        sql: {
+          counters: {
+            name: "counters",
+            primary: { url: ":memory:", client },
+          },
+        },
+      });
+      runtime.register(decl);
+      const handle = asSql(
+        await runtime.open(decl, {
+          effects: { writes: ["sql:counters"], reads: ["sql:counters"] },
+        }),
+      );
+      await handle.ensureTable(counters);
+      await handle
+        .insert(counters)
+        .values({ id: "c1", clicks: 0 })
+        .execute();
+
+      const n = 100;
+      const results = await Promise.all(
+        Array.from({ length: n }, () =>
+          handle.increment(counters, "c1", "clicks"),
+        ),
+      );
+      expect(new Set(results).size, label).toBe(n);
+      expect(Math.max(...results), label).toBe(n);
+      const row = await handle.findById(counters, "c1");
+      expect(Number(row?.clicks), label).toBe(n);
+      await runtime.close();
+    }
+  });
+});
+
+describe("PII masking at the driver boundary", () => {
+  test("SELECT * masks classified columns", async () => {
+    const decl = store.sql("notes", {
+      classify: { notes: { email: classify({ pii: true }) } },
+    });
+    const runtime = createStoreRuntime({
+      drivers: { sql: sqliteDriver },
+      sql: { notes: { name: "notes", primary: { url: ":memory:" } } },
+    });
+    runtime.register(decl);
+    const handle = asSql(
+      await runtime.open(decl, {
+        effects: { reads: ["sql:notes"], writes: ["sql:notes"] },
+      }),
+    );
+    await handle.ensureTable(notes);
+    await handle
+      .insert(notes)
+      .values({ id: "1", title: "t", email: "pii@x.com" })
+      .execute();
+
+    const rows = await handle.raw(`SELECT * FROM notes`);
+    expect(rows[0]?.title).toBe("t");
+    expect(rows[0]?.email).toBe(PII_MASK);
+
+    const revealed = asSql(
+      await runtime.open(decl, {
+        effects: { reads: ["sql:notes"] },
+        revealPii: true,
+      }),
+    );
+    const clear = await revealed.raw(`SELECT * FROM notes`);
+    expect(clear[0]?.email).toBe("pii@x.com");
+    await runtime.close();
+  });
+
+  test("maskRows uses schema classification, not hard-coded names", () => {
+    const map = buildClassificationMap({
+      users: { phone: classify({ pii: true }) },
+    });
+    const masked = maskRows([{ id: "1", phone: "555", name: "Ada" }], {
+      classifications: map,
+      table: "users",
+    });
+    expect(masked[0]).toEqual({ id: "1", phone: PII_MASK, name: "Ada" });
+  });
+});