okengine 0.14.1 → 0.16.0

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

@@ -38,8 +38,14 @@ export interface ColumnReference {
  * `getSQL` is a structural bridge so drizzle-orm operators (`eq`, `isNull`, …)
  * accept abstract columns in TypeScript. OKE’s SQL compiler never calls it —
  * it reads {@link SchemaColumnDecl.sqlName} / metadata directly.
+ *
+ * `TData` / `TNotNull` are type-level only (`$infer` is a phantom). They let
+ * {@link InferColumnJs} / table `$inferSelect` resolve real row shapes.
  */
-export interface SchemaColumnDecl extends ColumnDef {
+export interface SchemaColumnDecl<
+  TData = unknown,
+  TNotNull extends boolean = boolean,
+> extends ColumnDef {
   /** JS object key (e.g. `createdAt`). */
   readonly key: string;
   /** Database column name (e.g. `created_at`). */
@@ -47,7 +53,12 @@ export interface SchemaColumnDecl extends ColumnDef {
   /** Declared SQL type. */
   readonly sqlType: FieldSqlType;
   readonly primaryKey: boolean;
-  readonly notNull: boolean;
+  readonly notNull: TNotNull;
+  /**
+   * Phantom JS value type — not present at runtime. Distinguishes `string`
+   * vs `number` so structural typing does not collapse column data types.
+   */
+  readonly $infer?: TData;
   readonly unique: boolean;
   /** Literal `.default(v)` when set. */
   readonly defaultValue?: string | number | boolean | null;
@@ -69,6 +80,42 @@ export interface SchemaColumnDecl extends ColumnDef {
   getSQL(): never;
 }
 
+/** Policy command on a {@link SchemaPolicyDecl}. */
+export type SchemaPolicyFor = "all" | "select" | "insert" | "update" | "delete";
+
+/** Policy behavior on a {@link SchemaPolicyDecl}. */
+export type SchemaPolicyAs = "permissive" | "restrictive";
+
+/**
+ * Drizzle-shaped policy extra (`pgPolicy` emit).
+ */
+export interface SchemaPolicyDecl {
+  readonly kind: "schema-policy";
+  readonly name: string;
+  readonly as?: SchemaPolicyAs;
+  readonly to?: string | readonly string[];
+  readonly for?: SchemaPolicyFor;
+  readonly using?: string;
+  readonly withCheck?: string;
+}
+
+/** Enable RLS with no policies (`pgTable.withRLS`). */
+export interface SchemaRlsEnableDecl {
+  readonly kind: "schema-rls";
+}
+
+/** Third-arg extra for {@link schemaTable}. */
+export type SchemaTableExtra = SchemaPolicyDecl | SchemaRlsEnableDecl;
+
+/** Options for {@link schemaPolicy} / Gate helpers. */
+export interface SchemaPolicyOptions {
+  readonly as?: SchemaPolicyAs;
+  readonly to?: string | readonly string[];
+  readonly for?: SchemaPolicyFor;
+  readonly using?: string;
+  readonly withCheck?: string;
+}
+
 /** Table from {@link store.schema.table} — extends {@link TableHandle}. */
 export interface SchemaTableDecl extends TableHandle {
   readonly kind: "schema-table";
@@ -78,35 +125,47 @@ export interface SchemaTableDecl extends TableHandle {
    * (spreading columns would otherwise shadow {@link TableHandle.name}).
    */
   readonly tableName?: string;
+  /** `true` when {@link schemaRls} was declared or any policy is present. */
+  readonly rls?: boolean;
+  /** Declared policies (emit + Manifest). */
+  readonly policies?: readonly SchemaPolicyDecl[];
 }
 
-/** Fluent field builder before key finalization. */
-export interface FieldBuilder {
-  primaryKey(): FieldBuilder;
-  notNull(): FieldBuilder;
-  unique(): FieldBuilder;
-  default(value: string | number | boolean | null): FieldBuilder;
-  defaultFn(fn: () => unknown): FieldBuilder;
-  pii(): FieldBuilder;
-  sensitive(): FieldBuilder;
-  retain(duration: string): FieldBuilder;
+/**
+ * Fluent field builder before key finalization.
+ *
+ * `TData` is the JS value type (`string` / `number`). `TNotNull` is `true`
+ * after `.notNull()` or `.primaryKey()` — matching runtime finalize.
+ */
+export interface FieldBuilder<TData = unknown, TNotNull extends boolean = false> {
+  primaryKey(): FieldBuilder<TData, true>;
+  notNull(): FieldBuilder<TData, true>;
+  unique(): FieldBuilder<TData, TNotNull>;
+  default(value: string | number | boolean | null): FieldBuilder<TData, TNotNull>;
+  defaultFn(fn: () => unknown): FieldBuilder<TData, TNotNull>;
+  pii(): FieldBuilder<TData, TNotNull>;
+  sensitive(): FieldBuilder<TData, TNotNull>;
+  retain(duration: string): FieldBuilder<TData, TNotNull>;
   /** Override snake_case SQL name. */
-  as(sqlName: string): FieldBuilder;
+  as(sqlName: string): FieldBuilder<TData, TNotNull>;
   /** Optional human description for Console / docs (falls back to the JS key). */
-  describe(description: string): FieldBuilder;
+  describe(description: string): FieldBuilder<TData, TNotNull>;
   /**
    * Declare a foreign key to another column (dialect-agnostic).
    *
    * @param ref - Lazy target column (`() => links.code`)
    * @param actions - Optional ON DELETE / ON UPDATE
    */
-  references(ref: () => SchemaColumnDecl, actions?: ReferenceActions): FieldBuilder;
+  references(
+    ref: () => SchemaColumnDecl,
+    actions?: ReferenceActions,
+  ): FieldBuilder<TData, TNotNull>;
   /**
    * Bind the JS key and produce a {@link SchemaColumnDecl}.
    *
    * @param key - Object key in the table column map
    */
-  finalize(key: string): SchemaColumnDecl;
+  finalize(key: string): SchemaColumnDecl<TData, TNotNull>;
 }
 
 interface FieldState {
@@ -146,31 +205,39 @@ function mergeClassification(
   return { ...(current ?? {}), ...patch };
 }
 
-function createBuilder(state: FieldState): FieldBuilder {
-  const next = (patch: Partial<FieldState>): FieldBuilder => createBuilder({ ...state, ...patch });
+function createBuilder<TData, TNotNull extends boolean>(
+  state: FieldState,
+): FieldBuilder<TData, TNotNull> {
+  const next = <N extends boolean>(patch: Partial<FieldState>): FieldBuilder<TData, N> =>
+    createBuilder<TData, N>({ ...state, ...patch });
 
   return {
-    primaryKey: () => next({ primaryKey: true, notNull: true }),
-    notNull: () => next({ notNull: true }),
-    unique: () => next({ unique: true }),
-    default: (value) => next({ defaultValue: value }),
+    primaryKey: () => next<true>({ primaryKey: true, notNull: true }),
+    notNull: () => next<true>({ notNull: true }),
+    unique: () => next<TNotNull>({ unique: true }),
+    default: (value) => next<TNotNull>({ defaultValue: value }),
     defaultFn: (fn) =>
-      next({
+      next<TNotNull>({
         defaultFn: fn,
         defaultFnKind: defaultFnKindOf(fn),
       }),
-    pii: () => next({ classification: mergeClassification(state.classification, { pii: true }) }),
+    pii: () =>
+      next<TNotNull>({ classification: mergeClassification(state.classification, { pii: true }) }),
     sensitive: () =>
-      next({ classification: mergeClassification(state.classification, { sensitive: true }) }),
+      next<TNotNull>({
+        classification: mergeClassification(state.classification, { sensitive: true }),
+      }),
     retain: (duration) =>
-      next({ classification: mergeClassification(state.classification, { retain: duration }) }),
-    as: (sqlName) => next({ sqlName }),
-    describe: (description) => next({ description }),
+      next<TNotNull>({
+        classification: mergeClassification(state.classification, { retain: duration }),
+      }),
+    as: (sqlName) => next<TNotNull>({ sqlName }),
+    describe: (description) => next<TNotNull>({ description }),
     references: (ref, actions) =>
-      next({
+      next<TNotNull>({
         references: actions ? { ref, actions } : { ref },
       }),
-    finalize(key: string): SchemaColumnDecl {
+    finalize(key: string): SchemaColumnDecl<TData, TNotNull> {
       const sqlName = state.sqlName ?? camelToSnake(key);
       return {
         key,
@@ -178,7 +245,7 @@ function createBuilder(state: FieldState): FieldBuilder {
         sqlName,
         sqlType: state.sqlType,
         primaryKey: state.primaryKey,
-        notNull: state.notNull || state.primaryKey,
+        notNull: (state.notNull || state.primaryKey) as TNotNull,
         unique: state.unique,
         ...(state.defaultValue !== undefined ? { defaultValue: state.defaultValue } : {}),
         ...(state.defaultFn ? { defaultFn: state.defaultFn } : {}),
@@ -200,15 +267,15 @@ function createBuilder(state: FieldState): FieldBuilder {
  * Field builders — `field.text()` / `field.integer()`.
  */
 export const field = {
-  text: (): FieldBuilder =>
-    createBuilder({
+  text: (): FieldBuilder<string, false> =>
+    createBuilder<string, false>({
       sqlType: "text",
       primaryKey: false,
       notNull: false,
       unique: false,
     }),
-  integer: (): FieldBuilder =>
-    createBuilder({
+  integer: (): FieldBuilder<number, false> =>
+    createBuilder<number, false>({
       sqlType: "integer",
       primaryKey: false,
       notNull: false,
@@ -216,8 +283,19 @@ export const field = {
     }),
 } as const;
 
-/** Column map input for {@link schemaTable}. */
-export type SchemaColumnInput = FieldBuilder | SchemaColumnDecl;
+/**
+ * Column map input for {@link schemaTable}.
+ *
+ * Explicit `string` / `number` × nullability variants so `field.text()`
+ * (`FieldBuilder<string, false>`) remains assignable — methodful builders
+ * are invariant in their type parameters.
+ */
+export type SchemaColumnInput =
+  | FieldBuilder<string, false>
+  | FieldBuilder<string, true>
+  | FieldBuilder<number, false>
+  | FieldBuilder<number, true>
+  | SchemaColumnDecl;
 
 /**
  * Whether a value is a finalized {@link SchemaColumnDecl}.
@@ -261,7 +339,7 @@ export function finalizeColumnMap(
 ): Record<string, SchemaColumnDecl> {
   const out: Record<string, SchemaColumnDecl> = {};
   for (const [key, value] of Object.entries(columns)) {
-    out[key] = isFieldBuilder(value) ? value.finalize(key) : value;
+    out[key] = isFieldBuilder(value) ? value.finalize(key) : (value as SchemaColumnDecl);
   }
   return out;
 }
@@ -293,14 +371,34 @@ export function schemaTableSqlName(table: SchemaTableDecl): string | undefined {
   return undefined;
 }
 
+/**
+ * JS value type for a finalized column (`string` / `number`, plus `| null`
+ * when the column is nullable).
+ */
+export type InferColumnJs<C> =
+  C extends SchemaColumnDecl<infer D, infer N> ? (N extends true ? D : D | null) : unknown;
+
+/**
+ * Finalize a {@link schemaTable} column input into a typed decl.
+ */
+export type FinalizeColumn<T> =
+  T extends FieldBuilder<infer D, infer N>
+    ? SchemaColumnDecl<D, N>
+    : T extends SchemaColumnDecl<infer D, infer N>
+      ? SchemaColumnDecl<D, N>
+      : SchemaColumnDecl;
+
 /**
  * Table decl with columns as own properties (`links.code`) for FK / relations.
+ *
+ * `$inferSelect` is type-level only (Drizzle's own alias) — not set at runtime.
  */
 export type SchemaTableWithColumns<
   C extends Record<string, SchemaColumnDecl> = Record<string, SchemaColumnDecl>,
 > = Omit<SchemaTableDecl, "columns"> & {
   readonly columns: Readonly<C>;
-} & Omit<C, "kind" | "tableName">;
+  readonly $inferSelect: { [K in keyof C]: InferColumnJs<C[K]> };
+} & Omit<C, "kind" | "tableName" | "$inferSelect">;
 
 /**
  * Declare an abstract schema table (ORM-agnostic).
@@ -310,28 +408,147 @@ export type SchemaTableWithColumns<
  *
  * @param name - SQL table name
  * @param columns - Column map using {@link field} builders
+ * @param extras - RLS enable + {@link schemaPolicy} extras (Drizzle third arg)
  */
 export function schemaTable<C extends Record<string, SchemaColumnInput>>(
   name: string,
   columns: C,
-): SchemaTableWithColumns<{ [K in keyof C]: SchemaColumnDecl }> {
+  extras: readonly SchemaTableExtra[] = [],
+): SchemaTableWithColumns<{ [K in keyof C]: FinalizeColumn<C[K]> }> {
   const finalized = finalizeColumnMap(columns);
   const stamped: Record<string, SchemaColumnDecl> = {};
   for (const [key, col] of Object.entries(finalized)) {
     stamped[key] = { ...col, tableName: name };
   }
+  const policies = extras.filter(
+    (extra): extra is SchemaPolicyDecl => extra.kind === "schema-policy",
+  );
+  const rls = extras.some((extra) => extra.kind === "schema-rls") || policies.length > 0;
   const table = {
     name,
     columns: stamped,
     ...stamped,
+    ...(rls ? { rls: true } : {}),
+    ...(policies.length > 0 ? { policies } : {}),
   };
   // Survive columns named `name` or `kind` (they would otherwise shadow
   // the table discriminant / SQL name).
   Object.defineProperty(table, "kind", { value: "schema-table", enumerable: false });
   Object.defineProperty(table, "tableName", { value: name, enumerable: false });
-  return table as SchemaTableWithColumns<{ [K in keyof C]: SchemaColumnDecl }>;
+  return table as SchemaTableWithColumns<{ [K in keyof C]: FinalizeColumn<C[K]> }>;
 }
 
+/**
+ * Enable RLS with no policies (`pgTable.withRLS`).
+ */
+export function schemaRls(): SchemaRlsEnableDecl {
+  return { kind: "schema-rls" };
+}
+
+/**
+ * Raw Drizzle-shaped policy extra.
+ *
+ * @param name - Policy name
+ * @param options - `as` / `to` / `for` / `using` / `withCheck`
+ */
+export function schemaPolicy(name: string, options: SchemaPolicyOptions = {}): SchemaPolicyDecl {
+  return {
+    kind: "schema-policy",
+    name,
+    ...(options.as !== undefined ? { as: options.as } : {}),
+    ...(options.to !== undefined ? { to: options.to } : {}),
+    ...(options.for !== undefined ? { for: options.for } : {}),
+    ...(options.using !== undefined ? { using: options.using } : {}),
+    ...(options.withCheck !== undefined ? { withCheck: options.withCheck } : {}),
+  };
+}
+
+function sqlStringLiteral(value: string): string {
+  return `'${value.replaceAll("'", "''")}'`;
+}
+
+function helperPolicyName(prefix: string, key: string, command: SchemaPolicyFor): string {
+  const slug = key.replace(/[^A-Za-z0-9]+/g, "_").replace(/^_|_$/g, "");
+  return `${prefix}_${slug}_${command}`;
+}
+
+function policyPredicates(
+  command: SchemaPolicyFor,
+  expr: string,
+): { readonly using?: string; readonly withCheck?: string } {
+  if (command === "insert") return { withCheck: expr };
+  if (command === "update" || command === "all") return { using: expr, withCheck: expr };
+  return { using: expr };
+}
+
+/**
+ * Gate-name policy — `oke.gate() = 'member'`.
+ *
+ * @param gate - Policy / public Gate name
+ * @param options - Command (default `select`)
+ */
+export function schemaPolicyGate(
+  gate: string,
+  options: Pick<SchemaPolicyOptions, "for" | "as" | "to"> = {},
+): SchemaPolicyDecl {
+  const command = options.for ?? "select";
+  return schemaPolicy(helperPolicyName("gate", gate, command), {
+    ...options,
+    for: command,
+    ...policyPredicates(command, `oke.gate() = ${sqlStringLiteral(gate)}`),
+  });
+}
+
+/**
+ * Owner-column policy — `owner = oke.user()`.
+ *
+ * @param column - SQL / JS column name
+ * @param options - Command (default `all`)
+ */
+export function schemaPolicyOwner(
+  column: string,
+  options: Pick<SchemaPolicyOptions, "for" | "as" | "to"> = {},
+): SchemaPolicyDecl {
+  const command = options.for ?? "all";
+  return schemaPolicy(helperPolicyName("owner", column, command), {
+    ...options,
+    for: command,
+    ...policyPredicates(command, `${column} = oke.user()`),
+  });
+}
+
+/**
+ * Scope policy — `oke.has_scope('booking:create')`.
+ *
+ * @param scope - Scope string
+ * @param options - Command (default `insert`)
+ */
+export function schemaPolicyScope(
+  scope: string,
+  options: Pick<SchemaPolicyOptions, "for" | "as" | "to"> = {},
+): SchemaPolicyDecl {
+  const command = options.for ?? "insert";
+  return schemaPolicy(helperPolicyName("scope", scope, command), {
+    ...options,
+    for: command,
+    ...policyPredicates(command, `oke.has_scope(${sqlStringLiteral(scope)})`),
+  });
+}
+
+/** Callable `store.schema.policy` plus Gate helpers. */
+export type SchemaPolicyApi = typeof schemaPolicy & {
+  readonly gate: typeof schemaPolicyGate;
+  readonly owner: typeof schemaPolicyOwner;
+  readonly scope: typeof schemaPolicyScope;
+};
+
+/** `store.schema.policy` — raw + Gate helpers. */
+export const schemaPolicyApi: SchemaPolicyApi = Object.assign(schemaPolicy, {
+  gate: schemaPolicyGate,
+  owner: schemaPolicyOwner,
+  scope: schemaPolicyScope,
+});
+
 // ─── Relations (mirrors drizzle-orm `defineRelations`) ───────────────────────
 
 /** Column path recorded by relation helpers (`r.links.code`). */
@@ -527,6 +744,8 @@ export function schemaRelations<T extends Readonly<Record<string, SchemaTableDec
 export const schema = {
   table: schemaTable,
   relations: schemaRelations,
+  rls: schemaRls,
+  policy: schemaPolicyApi,
 } as const;
 
 /**

package/src/elements/store/seed.ts

@@ -61,7 +61,7 @@ export function resolveSeedIdentity(
 }
 
 /**
- * Confirm copy for `oke dev` / `oke db seed` — names this app's seed.
+ * Confirm copy for `oke db seed` — names this app's seed.
  *
  * @param identity - Resolved {@link SeedIdentity}
  */

package/src/elements/store/sql-condition.test.ts

@@ -86,6 +86,18 @@ describe("compileWhere", () => {
     expect(c.params).toEqual(["n1", "t"]);
   });
 
+  test("legacy array-valued StringChunk fragments still compile", () => {
+    const c = compileWhere({
+      queryChunks: [
+        notes.id,
+        { constructor: { name: "StringChunk" }, value: [" = "] },
+        { value: "n1" },
+      ],
+    });
+    expect(c.clause).toBe(`"id" = ?`);
+    expect(c.params).toEqual(["n1"]);
+  });
+
   test("inArray expands one placeholder per value", () => {
     const c = compileWhere(inArray(notes.id, ["a", "b", "c"]));
     expect(c.clause).toBe(`"id" in (?, ?, ?)`);

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

@@ -333,10 +333,33 @@ function chunksOf(node: unknown): readonly unknown[] {
   return (node as { queryChunks: unknown[] }).queryChunks;
 }
 
-/** Joined text of a Drizzle `StringChunk` (`{ value: string[] }`). */
+/**
+ * True when `chunk` is a Drizzle `StringChunk` (or the synthetic array-valued
+ * shape `resource.ts` still emits). `Param` also has a `value` field — never
+ * treat those as SQL text.
+ */
+function isStringChunk(chunk: object): boolean {
+  const ctor = (chunk as { constructor?: { name?: unknown } }).constructor?.name;
+  if (ctor === "StringChunk") return true;
+  const value = (chunk as { value?: unknown }).value;
+  return (
+    Array.isArray(value) &&
+    value.every((part) => typeof part === "string") &&
+    !("encoder" in chunk) &&
+    !("name" in chunk)
+  );
+}
+
+/**
+ * Joined text of a Drizzle `StringChunk`.
+ *
+ * drizzle-orm `1.0.0-rc.5-169397b` stores `value` as a `string`. Earlier
+ * snapshots (and the synthetic chunks in `resource.ts`) store `string[]`.
+ */
 function chunkText(chunk: unknown): string | undefined {
-  if (!chunk || typeof chunk !== "object") return undefined;
+  if (!chunk || typeof chunk !== "object" || !isStringChunk(chunk)) return undefined;
   const value = (chunk as { value?: unknown }).value;
+  if (typeof value === "string") return value;
   return Array.isArray(value) ? value.join("") : undefined;
 }
 
@@ -394,6 +417,7 @@ function asParamValue(chunk: unknown): { readonly found: boolean; readonly value
   if (chunk === undefined) return { found: false };
   if (chunk === null || typeof chunk !== "object") return { found: true, value: chunk };
   if (Array.isArray(chunk)) return { found: false };
+  if (isStringChunk(chunk)) return { found: false };
   if (!("value" in (chunk as object))) return { found: false };
   if (Array.isArray((chunk as { value: unknown }).value)) return { found: false };
   if ((chunk as { name?: unknown }).name) return { found: false };

package/src/elements/store/sql-rls-isolation.test.ts

@@ -0,0 +1,165 @@
+/**
+ * Real PGlite RLS isolation through {@link createSqlStoreHandle}.
+ *
+ * Covers the gap unit tests missed: a live policy, two concurrent identity
+ * bags on one shared connection, and row-level isolation. PGlite `query`
+ * rejects multi-command batches — the stamp is split statements pinned
+ * through `SqlConnection.transaction`.
+ */
+
+import { afterAll, beforeAll, describe, expect, test } from "bun:test";
+import { connectPglite } from "../../drivers/pglite.ts";
+import { connectPostgres } from "../../drivers/postgres.ts";
+import { installOkeRlsHelpers } from "../../drivers/pg-rls.ts";
+import type { SqlConnection } from "../../drivers/types.ts";
+import { createSqlStoreHandle, type SqlStoreHandle } from "./sql-session.ts";
+
+const NOTES_DDL = `CREATE TABLE notes (
+  id text PRIMARY KEY,
+  owner text NOT NULL,
+  body text NOT NULL
+)`;
+
+const OWNER_POLICY = `CREATE POLICY owner_select ON notes
+  AS PERMISSIVE FOR SELECT TO public
+  USING (owner = oke.user())`;
+
+/** File-scoped warmed PGlite. */
+let conn: SqlConnection;
+/** Stamped as alice. */
+let asAlice: SqlStoreHandle;
+/** Stamped as bob. */
+let asBob: SqlStoreHandle;
+/** No stamp — table-owner / superuser bypass. */
+let asOwner: SqlStoreHandle;
+
+beforeAll(async () => {
+  conn = await connectPglite({ url: "memory://sql-rls-isolation", role: "primary" });
+  await conn.exec(NOTES_DDL);
+  await conn.exec(`INSERT INTO notes VALUES ('a', 'alice', 'hi'), ('b', 'bob', 'yo')`);
+  await conn.exec(`ALTER TABLE notes ENABLE ROW LEVEL SECURITY`);
+  await installOkeRlsHelpers((sql) => conn.exec(sql));
+  await conn.exec(OWNER_POLICY);
+  asAlice = createSqlStoreHandle("sql:app", {
+    connection: conn,
+    classifications: new Map(),
+    routedRole: "primary",
+    domainDdl: "off",
+    rls: { gate: "member", userId: "alice", scopes: ["member"] },
+  });
+  asBob = createSqlStoreHandle("sql:app", {
+    connection: conn,
+    classifications: new Map(),
+    routedRole: "primary",
+    domainDdl: "off",
+    rls: { gate: "member", userId: "bob", scopes: ["member"] },
+  });
+  asOwner = createSqlStoreHandle("sql:app", {
+    connection: conn,
+    classifications: new Map(),
+    routedRole: "primary",
+    domainDdl: "off",
+  });
+}, 15_000);
+
+afterAll(async () => {
+  await conn.close();
+});
+
+describe("sql-session RLS isolation (pglite)", () => {
+  test("pglite query rejects a multi-command batch (the old prelude)", async () => {
+    await expect(
+      conn.query("BEGIN; SET LOCAL row_security = on; SELECT set_config('oke.user', $1, true)", [
+        "alice",
+      ]),
+    ).rejects.toThrow(/multiple commands/i);
+  });
+
+  test("sequential identities see only their rows", async () => {
+    const alice = await asAlice.raw(`SELECT id, owner FROM notes ORDER BY id`);
+    const bob = await asBob.raw(`SELECT id, owner FROM notes ORDER BY id`);
+    expect(alice).toEqual([{ id: "a", owner: "alice" }]);
+    expect(bob).toEqual([{ id: "b", owner: "bob" }]);
+  });
+
+  test("concurrent identities do not leak across the shared connection", async () => {
+    const [alice, bob, aliceAgain] = await Promise.all([
+      asAlice.raw(`SELECT id, owner FROM notes ORDER BY id`),
+      asBob.raw(`SELECT id, owner FROM notes ORDER BY id`),
+      asAlice.raw(`SELECT id, owner FROM notes ORDER BY id`),
+    ]);
+    expect(alice).toEqual([{ id: "a", owner: "alice" }]);
+    expect(bob).toEqual([{ id: "b", owner: "bob" }]);
+    expect(aliceAgain).toEqual([{ id: "a", owner: "alice" }]);
+  });
+
+  test("unstamped owner/superuser still sees every row", async () => {
+    const rows = await asOwner.raw(`SELECT id, owner FROM notes ORDER BY id`);
+    expect(rows).toEqual([
+      { id: "a", owner: "alice" },
+      { id: "b", owner: "bob" },
+    ]);
+  });
+});
+
+const LIVE_PG =
+  process.env.OKE_TEST_DOCKER === "1" &&
+  (process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL)?.startsWith("postgres");
+if (!LIVE_PG) {
+  console.log("skip: live Postgres RLS isolation needs OKE_TEST_DOCKER=1 and DATABASE_URL");
+}
+
+describe("sql-session RLS isolation (live postgres)", () => {
+  const live = LIVE_PG ? test : test.skip;
+  const table = "oke_rls_isolation_notes";
+
+  live(
+    "split stamp isolates concurrent identities",
+    async () => {
+      const pg = await connectPostgres({
+        url: process.env.DATABASE_URL ?? process.env.OKE_STORE_SQL_URL,
+        role: "primary",
+      });
+      try {
+        await pg.exec(`DROP TABLE IF EXISTS ${table}`);
+        await pg.exec(
+          `CREATE TABLE ${table} (id text PRIMARY KEY, owner text NOT NULL, body text NOT NULL)`,
+        );
+        await pg.exec(`INSERT INTO ${table} VALUES ('a', 'alice', 'hi'), ('b', 'bob', 'yo')`);
+        await pg.exec(`ALTER TABLE ${table} ENABLE ROW LEVEL SECURITY`);
+        await installOkeRlsHelpers((sql) => pg.exec(sql));
+        await pg.exec(
+          `CREATE POLICY owner_select ON ${table} AS PERMISSIVE FOR SELECT TO public USING (owner = oke.user())`,
+        );
+        const alice = createSqlStoreHandle("sql:app", {
+          connection: pg,
+          classifications: new Map(),
+          routedRole: "primary",
+          domainDdl: "off",
+          rls: { gate: "member", userId: "alice", scopes: ["member"] },
+        });
+        const bob = createSqlStoreHandle("sql:app", {
+          connection: pg,
+          classifications: new Map(),
+          routedRole: "primary",
+          domainDdl: "off",
+          rls: { gate: "member", userId: "bob", scopes: ["member"] },
+        });
+        const [a, b] = await Promise.all([
+          alice.raw(`SELECT id, owner FROM ${table} ORDER BY id`),
+          bob.raw(`SELECT id, owner FROM ${table} ORDER BY id`),
+        ]);
+        expect(a).toEqual([{ id: "a", owner: "alice" }]);
+        expect(b).toEqual([{ id: "b", owner: "bob" }]);
+      } finally {
+        try {
+          await pg.exec(`DROP TABLE IF EXISTS ${table}`);
+        } catch {
+          // Best-effort cleanup.
+        }
+        await pg.close();
+      }
+    },
+    20_000,
+  );
+});