okengine 0.14.1 → 0.16.0

package/src/elements/gate/declare.ts

@@ -5,6 +5,7 @@
  */
 
 import type { RateStrategy } from "../../manifest/types.ts";
+import { gateRegistry } from "../../kernel/element-registries.ts";
 import { DEFAULT_RATE_STRATEGY } from "./constants.ts";
 import { GATE_PUBLIC_NAME, type GateAllDecl, type GateMember } from "./flatten.ts";
 
@@ -18,6 +19,8 @@ export interface GatePolicyContext {
     readonly userId: string | null;
     readonly scopes: ReadonlySet<string>;
     readonly verified?: boolean;
+    /** Authenticating API key id when the principal is a key; otherwise omitted. */
+    readonly apiKeyId?: string | null;
   };
   /** Operator-plane principal (`fx.operator`). */
   readonly operator: {
@@ -89,6 +92,29 @@ export interface RateGateDecl {
 /** Declared gate handle. */
 export type GateDecl = PolicyGateDecl | RateGateDecl;
 
+/**
+ * `gate.policy` / `gate.scope` / `gate.rate` push into the shared
+ * {@link gateRegistry} (`src/kernel/element-registries.ts`) so {@link oke}
+ * can auto-populate `gate.policies` with zero explicit array — mirrors the
+ * {@link on} trigger-drain registry (`src/kernel/on.ts`). `gate.public` is
+ * built into the runtime; `gate.all` is a composition of already-registered
+ * members.
+ *
+ * Snapshot of every policy / rate declared since the last reset.
+ */
+export function listGates(): readonly GateDecl[] {
+  return gateRegistry.slice();
+}
+
+/**
+ * Clear the gate registry (tests / fresh app adopt).
+ *
+ * @internal
+ */
+export function resetGates(): void {
+  gateRegistry.length = 0;
+}
+
 /**
  * Shape of the {@link gate} element namespace.
  */
@@ -151,9 +177,11 @@ export const gate: GateNamespace = {
       );
     }
     if (typeof checkOrOptions === "function") {
-      return { kind: "policy", name, check: checkOrOptions };
+      const decl: PolicyGateDecl = { kind: "policy", name, check: checkOrOptions };
+      gateRegistry.push(decl);
+      return decl;
     }
-    return {
+    const decl: PolicyGateDecl = {
       kind: "policy",
       name,
       check: checkOrOptions.check,
@@ -161,6 +189,8 @@ export const gate: GateNamespace = {
         ? { description: checkOrOptions.description }
         : {}),
     };
+    gateRegistry.push(decl);
+    return decl;
   },
 
   /**
@@ -172,12 +202,14 @@ export const gate: GateNamespace = {
     if (name === GATE_PUBLIC_NAME) {
       throw new TypeError('gate.scope: name "public" is reserved — use gate.public');
     }
-    return {
+    const decl: PolicyGateDecl = {
       kind: "policy",
       name,
       check: ({ auth }) => auth.scopes.has(name),
       scopes: [name],
     };
+    gateRegistry.push(decl);
+    return decl;
   },
 
   public: {
@@ -201,7 +233,7 @@ export const gate: GateNamespace = {
     }
     const strategy = options.strategy ?? DEFAULT_RATE_STRATEGY;
     const name = `rate:${strategy}:${options.max}/${options.per}`;
-    return {
+    const decl: RateGateDecl = {
       kind: "rate",
       name,
       strategy,
@@ -211,6 +243,8 @@ export const gate: GateNamespace = {
       overridable: options.overridable ?? false,
       ...(options.description !== undefined ? { description: options.description } : {}),
     };
+    gateRegistry.push(decl);
+    return decl;
   },
 
   /**

package/src/elements/gate/flatten.ts

@@ -7,7 +7,7 @@
 
 import type { GateDecl } from "./declare.ts";
 
-/** Reserved policy name for `gate.public` / `.gate.public`. */
+/** Reserved policy name for `gate.public` / `.public()`. */
 export const GATE_PUBLIC_NAME = "public";
 
 /** Member of `gate.all` — a policy/rate or a nested `all` handle. */

package/src/elements/gate/runtime.ts

@@ -70,7 +70,7 @@ export interface GateRuntime {
  */
 export function createGateRuntime(options: CreateGateRuntimeOptions = {}): GateRuntime {
   const map = new Map<string, GateDecl>();
-  // Built-in sentinel — `.gate.public` works without listing it in `oke({ gates })`.
+  // Built-in sentinel — `.public()` works without listing it in `oke({ gates })`.
   map.set(gate.public.name, gate.public);
   for (const g of options.gates ?? []) {
     if (isGateAllDecl(g)) {

package/src/elements/store/cache.ts

@@ -63,7 +63,7 @@ export function tier1KeysForReads(
  * @param effects - Write flow effects
  */
 export function resourcesTouchedByWrites(effects: Effects): ResourceRef[] {
-  return [...(effects.writes ?? [])];
+  return (effects.writes ?? []).filter((r): r is ResourceRef => isStoreResourceRef(r));
 }
 
 /**

package/src/elements/store/declare.ts

@@ -122,13 +122,12 @@ export interface IndexStoreDecl extends StoreDeclBase {
 export type StoreDecl = SqlStoreDecl | KvStoreDecl | FilesStoreDecl | IndexStoreDecl;
 
 /**
- * `store.sql` / `store.files` push into the shared {@link storeRegistry}
+ * Every `store.*` facet pushes into the shared {@link storeRegistry}
  * (`src/kernel/element-registries.ts`) so {@link oke} can auto-populate
  * `stores` with zero explicit array — mirrors the {@link on} trigger-drain
- * registry (`src/kernel/on.ts`). `store.kv` / `store.index` are
- * intentionally not auto-registered (out of scope).
+ * registry (`src/kernel/on.ts`).
  *
- * Snapshot of every `store.sql` / `store.files` declared since the last reset.
+ * Snapshot of every store declared since the last reset.
  */
 export function listStores(): readonly StoreDecl[] {
   return storeRegistry.slice();
@@ -180,13 +179,15 @@ export function sql(name: string, options: SqlStoreOptions = {}): SqlStoreDecl {
  * @param options - Options
  */
 export function kv(name: string, options: KvStoreOptions = {}): KvStoreDecl {
-  return {
+  const decl: KvStoreDecl = {
     facet: "kv",
     name,
     ref: `kv:${name}`,
     ...(options.description !== undefined ? { description: options.description } : {}),
     ...(options.durable === true ? { durable: true } : {}),
   };
+  storeRegistry.push(decl);
+  return decl;
 }
 
 /**
@@ -213,13 +214,15 @@ export function files(name: string, options: FilesStoreOptions = {}): FilesStore
  * @param options - Dimensions
  */
 export function index(name: string, options: IndexStoreOptions = {}): IndexStoreDecl {
-  return {
+  const decl: IndexStoreDecl = {
     facet: "index",
     name,
     ref: `index:${name}`,
     ...(options.description !== undefined ? { description: options.description } : {}),
     dims: options.dims,
   };
+  storeRegistry.push(decl);
+  return decl;
 }
 
 /** Public `store` element — four facets + abstract schema declare + resource. */

package/src/elements/store/emit-drizzle.ts

@@ -21,9 +21,11 @@ import {
   type SchemaColumnDecl,
   type SchemaColumnInput,
   type SchemaRelationEntry,
+  type SchemaPolicyDecl,
   type SchemaRelationsDecl,
   type SchemaTableDecl,
 } from "./schema-decl.ts";
+import { emitPgPolicySource, parseSqlPolicySpec } from "../../drivers/pg-rls.ts";
 
 /** Supported Drizzle dialects for domain schema emit (Postgres-family only). */
 export type SqlDialect = "postgres";
@@ -186,7 +188,12 @@ export function emitDrizzleSource(
     Object.values(t.columns).some((c) => c.sqlType === "integer"),
   );
   const pgIntImport = needsInteger ? "bigint" : null;
-  const coreImport = `import { pgTable, text${pgIntImport ? `, ${pgIntImport}` : ""} } from "drizzle-orm/pg-core";`;
+  const needsPolicy = tables.some((t) => (t.policies?.length ?? 0) > 0);
+  const coreNames = ["pgTable", "text", pgIntImport, needsPolicy ? "pgPolicy" : null].filter(
+    (name): name is string => name !== null,
+  );
+  const coreImport = `import { ${coreNames.join(", ")} } from "drizzle-orm/pg-core";`;
+  const sqlImport = needsPolicy ? `import { sql } from "drizzle-orm";\n` : "";
 
   const needsId = tables.some((t) =>
     Object.values(t.columns).some((c) => c.defaultFnKind === "id"),
@@ -204,19 +211,14 @@ export function emitDrizzleSource(
   const relationsImport =
     relations.length > 0 ? `import { defineRelations } from "drizzle-orm";\n` : "";
 
-  const blocks = tables.map((table) => {
-    const lines = Object.values(table.columns).map(
-      (col) => `  ${col.key}: ${emitColumnSource(col, dialect)},`,
-    );
-    const sqlName = schemaTableSqlName(table) ?? table.name;
-    return `export const ${exportNameForTable(sqlName)} = pgTable(${JSON.stringify(sqlName)}, {\n${lines.join("\n")}\n});`;
-  });
+  const blocks = tables.map((table) => emitTableBlock(table, dialect));
 
   const relationsBlock = emitRelationsSource(relations);
 
   return [
     GENERATED_SCHEMA_HEADER,
     coreImport,
+    sqlImport.trimEnd(),
     relationsImport.trimEnd(),
     helperImport.trimEnd(),
     "",
@@ -228,6 +230,40 @@ export function emitDrizzleSource(
     .join("\n");
 }
 
+function emitTableBlock(table: SchemaTableDecl, dialect: SqlDialect): string {
+  const lines = Object.values(table.columns).map(
+    (col) => `  ${col.key}: ${emitColumnSource(col, dialect)},`,
+  );
+  const sqlName = schemaTableSqlName(table) ?? table.name;
+  const exportName = exportNameForTable(sqlName);
+  const cols = `{\n${lines.join("\n")}\n}`;
+  const policies = table.policies ?? [];
+  if (policies.length === 0) {
+    const ctor = table.rls === true ? "pgTable.withRLS" : "pgTable";
+    return `export const ${exportName} = ${ctor}(${JSON.stringify(sqlName)}, ${cols});`;
+  }
+  const extras = policies.map((policy) => `  ${emitPolicyExtra(policy, sqlName)},`).join("\n");
+  return `export const ${exportName} = pgTable(${JSON.stringify(sqlName)}, ${cols}, (_t) => [\n${extras}\n]);`;
+}
+
+function emitPolicyExtra(policy: SchemaPolicyDecl, table: string): string {
+  const roles = Array.isArray(policy.to)
+    ? policy.to.join(", ")
+    : typeof policy.to === "string"
+      ? policy.to
+      : "public";
+  const spec = parseSqlPolicySpec({
+    name: policy.name,
+    table,
+    as: policy.as,
+    to: roles,
+    for: policy.for,
+    using: policy.using,
+    withCheck: policy.withCheck,
+  });
+  return emitPgPolicySource(spec).replaceAll("\n", "\n  ");
+}
+
 function exportNameForTable(name: string): string {
   // Keep simple SQL names as-is; camelCase odd names.
   if (/^[a-zA-Z_][a-zA-Z0-9_]*$/.test(name)) return name;

package/src/elements/store/resource.test.ts

@@ -7,7 +7,7 @@
 
 import { afterAll, afterEach, beforeAll, beforeEach, describe, expect, test } from "bun:test";
 import { integer, pgTable, text } from "drizzle-orm/pg-core";
-import { createInsertSchema, createSelectSchema } from "drizzle-zod";
+import { createInsertSchema, createSelectSchema } from "drizzle-orm/zod";
 import { z } from "zod";
 import { pgliteDriver } from "../../drivers/pglite.ts";
 import type { SqlConnection } from "../../drivers/types.ts";

package/src/elements/store/rls-identity.test.ts

@@ -0,0 +1,95 @@
+import { describe, expect, test } from "bun:test";
+import type { Manifest } from "../../manifest/types.ts";
+import { firstPolicyOrPublic, resolveRlsIdentity, rlsIdentityFromAuth } from "./rls-identity.ts";
+
+const MANIFEST: Manifest = {
+  oke: "1.0",
+  app: "app",
+  gates: {
+    public: { kind: "policy" },
+    member: { kind: "policy", description: "Signed-in" },
+    "booking:create": { kind: "policy", scopes: ["booking:create"] },
+    "rate:x": { kind: "rate", max: 1, per: "1m" },
+  },
+};
+
+describe("resolveRlsIdentity", () => {
+  test("operator omit and bypass skip the stamp", () => {
+    expect(resolveRlsIdentity({})).toBeNull();
+    expect(resolveRlsIdentity({ asGate: "member", bypass: true })).toBeNull();
+  });
+
+  test("public and policy-only leave userId empty", () => {
+    expect(resolveRlsIdentity({ asGate: "public", manifest: MANIFEST })).toEqual({
+      gate: "public",
+      userId: "",
+      scopes: [],
+    });
+    expect(resolveRlsIdentity({ asGate: "member", manifest: MANIFEST })).toEqual({
+      gate: "member",
+      userId: "",
+      scopes: ["member"],
+    });
+    expect(resolveRlsIdentity({ asGate: "booking:create", manifest: MANIFEST })).toEqual({
+      gate: "booking:create",
+      userId: "",
+      scopes: ["booking:create"],
+    });
+  });
+
+  test("seeded user keeps real id and mapped gate", () => {
+    expect(
+      resolveRlsIdentity({
+        asUserId: "u1",
+        asGate: "member",
+        identities: [{ id: "u1", scopes: ["member"], status: "active" }],
+        manifest: MANIFEST,
+      }),
+    ).toEqual({ gate: "member", userId: "u1", scopes: ["member"] });
+  });
+
+  test("refuses rate gates", () => {
+    expect(resolveRlsIdentity({ asGate: "rate:x", manifest: MANIFEST })).toBeNull();
+  });
+});
+
+describe("rlsIdentityFromAuth", () => {
+  test("uses the first policy/public and live userId", () => {
+    expect(
+      rlsIdentityFromAuth({
+        userId: "u1",
+        scopes: new Set(["member", "booking:create"]),
+        gateNames: ["member", "booking:create"],
+      }),
+    ).toEqual({
+      gate: "member",
+      userId: "u1",
+      scopes: ["member", "booking:create"],
+    });
+  });
+
+  test("skips cron (no gates) and operator bypass", () => {
+    expect(
+      rlsIdentityFromAuth({
+        userId: null,
+        scopes: [],
+        gateNames: [],
+      }),
+    ).toBeNull();
+    expect(
+      rlsIdentityFromAuth({
+        userId: "op",
+        scopes: [],
+        gateNames: ["member"],
+        operator: true,
+      }),
+    ).toBeNull();
+  });
+});
+
+describe("firstPolicyOrPublic", () => {
+  test("skips rate ids", () => {
+    expect(firstPolicyOrPublic(["rate:x", "member"])).toBe("member");
+    expect(firstPolicyOrPublic(["public"])).toBe("public");
+  });
+});

package/src/elements/store/rls-identity.ts

@@ -0,0 +1,116 @@
+/**
+ * One Gate → RLS identity bag for Console, Call API, and `fx.store`.
+ */
+
+import type { Manifest } from "../../manifest/types.ts";
+import type { RlsIdentity } from "../../drivers/pg-rls.ts";
+
+export type { RlsIdentity };
+
+/** Seeded Console identity used by invoke-as / Gate picker. */
+export type RlsIdentityRow = {
+  readonly id: string;
+  readonly scopes: readonly string[];
+  readonly status?: string;
+};
+
+/** Input to {@link resolveRlsIdentity}. */
+export type ResolveRlsIdentityInput = {
+  readonly asGate?: string | null;
+  readonly asUserId?: string | null;
+  readonly bypass?: boolean;
+  readonly identities?: readonly RlsIdentityRow[];
+  readonly manifest?: Manifest | null;
+};
+
+/**
+ * Console / Call API bag. Operator and `bypass` return `null` (no stamp).
+ *
+ * @param input - Picker + Manifest
+ */
+export function resolveRlsIdentity(input: ResolveRlsIdentityInput): RlsIdentity | null {
+  if (input.bypass === true) return null;
+  const asGate = input.asGate?.trim() || null;
+  const asUserId = input.asUserId?.trim() || null;
+  if (!asGate && !asUserId) return null;
+
+  if (asUserId) {
+    const identity = (input.identities ?? []).find(
+      (row) => row.id === asUserId && row.status !== "disabled",
+    );
+    if (!identity) return null;
+    const gate = asGate ?? policyGateForScopes(identity.scopes, input.manifest);
+    if (!gate) return null;
+    return { gate, userId: identity.id, scopes: [...identity.scopes] };
+  }
+
+  if (!asGate) return null;
+  if (asGate === "public") {
+    return { gate: "public", userId: "", scopes: [] };
+  }
+
+  const declared = input.manifest?.gates?.[asGate];
+  if (!declared || declared.kind === "rate" || asGate.startsWith("rate:")) return null;
+  const scopes = declared.scopes && declared.scopes.length > 0 ? declared.scopes : [asGate];
+  return { gate: asGate, userId: "", scopes: [...scopes] };
+}
+
+/**
+ * Live HTTP / resource-mount bag after Gate passes.
+ *
+ * @param input - `fx.auth` + trigger gate names
+ */
+export function rlsIdentityFromAuth(input: {
+  readonly userId: string | null;
+  readonly scopes: ReadonlySet<string> | readonly string[];
+  readonly gateNames: readonly string[];
+  readonly bypass?: boolean;
+  readonly operator?: boolean;
+}): RlsIdentity | null {
+  if (input.bypass === true || input.operator === true) return null;
+  const gate = firstPolicyOrPublic(input.gateNames);
+  if (!gate) return null;
+  const scopes = Array.isArray(input.scopes) ? input.scopes : [...input.scopes];
+  return {
+    gate,
+    userId: input.userId ?? "",
+    scopes,
+  };
+}
+
+/**
+ * First policy/public name (rate ids skipped).
+ *
+ * @param names - Trigger gate names
+ */
+export function firstPolicyOrPublic(names: readonly string[]): string | null {
+  for (const name of names) {
+    if (name.startsWith("rate:")) continue;
+    if (name.length > 0) return name;
+  }
+  return null;
+}
+
+/**
+ * First Manifest policy implied by scopes (name, then declared roles).
+ *
+ * @param scopes - Identity scopes
+ * @param manifest - Current Manifest
+ */
+export function policyGateForScopes(
+  scopes: readonly string[],
+  manifest: Manifest | null | undefined,
+): string | null {
+  const gates = manifest?.gates ?? {};
+  for (const scope of scopes) {
+    const gate = gates[scope];
+    if (gate && gate.kind !== "rate") return scope;
+  }
+  for (const scope of scopes) {
+    for (const [name, gate] of Object.entries(gates)) {
+      if (gate.kind === "rate") continue;
+      if ((gate.roles ?? []).includes(scope)) return name;
+    }
+  }
+  return null;
+}

package/src/elements/store/runtime.ts

@@ -24,6 +24,7 @@ import type {
   VectorIndexStore,
 } from "../../drivers/types.ts";
 import { indexDriverNeedsSql } from "../../drivers/types.ts";
+import type { RlsIdentity } from "../../drivers/pg-rls.ts";
 import { buildClassificationMap, type MaskRowsOptions } from "./classify.ts";
 import {
   createStoreCache,
@@ -112,6 +113,8 @@ export interface StoreInvokeContext {
   readonly effects: Effects;
   /** Reveal PII (gated elsewhere). */
   readonly revealPii?: boolean;
+  /** Gate identity for RLS (`oke.gate` / `oke.user` / `oke.has_scope`). */
+  readonly rls?: RlsIdentity;
 }
 
 /** Unified handle returned for any facet. */
@@ -236,6 +239,13 @@ export interface StoreRuntime {
    * @param ref - `kv:name`
    */
   kvNamespace(ref: ResourceRef): Promise<KvNamespace>;
+  /**
+   * Shared primary SQL connection (`sharedSqlConn`).
+   *
+   * Host auth persist (`oke_api_keys`) and durable KV borrow this same
+   * connection — never a second open against `store.sql()` / `DATABASE_URL`.
+   */
+  primarySql(): Promise<SqlConnection | undefined>;
   /**
    * Register a declaration (usually done at module load).
    *
@@ -347,6 +357,7 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
       revealPii: ctx.revealPii,
       routedRole: target.role,
       domainDdl: options.domainDdl ?? "ensure",
+      ...(ctx.rls ? { rls: ctx.rls } : {}),
     });
   }
 
@@ -541,6 +552,13 @@ export function createStoreRuntime(options: CreateStoreRuntimeOptions): StoreRun
       if (!ns) throw new Error(`Unknown kv ref: ${ref}`);
       return ns;
     },
+    async primarySql() {
+      const sqlDriver = options.drivers.sql;
+      if (!sqlDriver) return undefined;
+      const firstSql = Object.values(options.sql ?? [])[0];
+      const url = options.sqlUrl ?? firstSql?.primary.url;
+      return sharedSqlConn(sqlDriver, "primary", { url });
+    },
     onWriteEffects(effects) {
       return cache.invalidateFromEffects(effects);
     },

package/src/elements/store/schema-decl.test.ts

@@ -260,3 +260,40 @@ describe("emitDrizzleSource — references + relations (Linkly-shaped)", () => {
     expect(relations.config.daily?.link?.target).toBe("links");
   });
 });
+
+describe("store.schema RLS extras", () => {
+  test("helpers stamp rls + named policies", () => {
+    const bookings = store.schema.table(
+      "bookings",
+      {
+        id: field.text().primaryKey(),
+        owner: field.text().notNull(),
+      },
+      [
+        store.schema.policy.gate("member", { for: "select" }),
+        store.schema.policy.owner("owner", { for: "all" }),
+        store.schema.policy.scope("booking:create", { for: "insert" }),
+      ],
+    );
+    expect(bookings.rls).toBe(true);
+    expect(bookings.policies?.map((p) => p.name)).toEqual([
+      "gate_member_select",
+      "owner_owner_all",
+      "scope_booking_create_insert",
+    ]);
+    const src = emitDrizzleSource([bookings], "postgres");
+    expect(src).toContain("pgPolicy");
+    expect(src).toContain("oke.gate() = ");
+    expect(src).toContain("oke.user()");
+    expect(src).toContain("oke.has_scope(");
+  });
+
+  test("rls() without policies emits pgTable.withRLS", () => {
+    const notes = store.schema.table("notes", { id: field.text().primaryKey() }, [
+      store.schema.rls(),
+    ]);
+    expect(notes.rls).toBe(true);
+    expect(notes.policies).toBeUndefined();
+    expect(emitDrizzleSource([notes], "postgres")).toContain("pgTable.withRLS");
+  });
+});