okengine 0.15.2 → 0.17.0

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

@@ -6,6 +6,7 @@
  */
 
 import type { ColumnClassification } from "../../manifest/types.ts";
+import { lazyRequire } from "../../kernel/lazy-require.ts";
 import type { ColumnDef, TableHandle } from "./table.ts";
 import { id as idHelper, now as nowHelper } from "./table.ts";
 
@@ -38,8 +39,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 +54,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;
@@ -93,8 +105,14 @@ export interface SchemaRlsEnableDecl {
   readonly kind: "schema-rls";
 }
 
+/** Opt out of tenant isolation for a schema table when tenancy is on. */
+export interface SchemaTenantScopedDecl {
+  readonly kind: "schema-tenant-scoped";
+  readonly tenantScoped: false;
+}
+
 /** Third-arg extra for {@link schemaTable}. */
-export type SchemaTableExtra = SchemaPolicyDecl | SchemaRlsEnableDecl;
+export type SchemaTableExtra = SchemaPolicyDecl | SchemaRlsEnableDecl | SchemaTenantScopedDecl;
 
 /** Options for {@link schemaPolicy} / Gate helpers. */
 export interface SchemaPolicyOptions {
@@ -118,35 +136,45 @@ export interface SchemaTableDecl extends TableHandle {
   readonly rls?: boolean;
   /** Declared policies (emit + Manifest). */
   readonly policies?: readonly SchemaPolicyDecl[];
+  /** When `false`, skip fail-loud tenant-policy requirement. */
+  readonly tenantScoped?: boolean;
 }
 
-/** 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 {
@@ -186,31 +214,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,
@@ -218,7 +254,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 } : {}),
@@ -240,15 +276,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,
@@ -256,8 +292,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}.
@@ -301,7 +348,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;
 }
@@ -333,14 +380,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).
@@ -356,7 +423,7 @@ export function schemaTable<C extends Record<string, SchemaColumnInput>>(
   name: string,
   columns: C,
   extras: readonly SchemaTableExtra[] = [],
-): SchemaTableWithColumns<{ [K in keyof C]: SchemaColumnDecl }> {
+): 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)) {
@@ -366,18 +433,22 @@ export function schemaTable<C extends Record<string, SchemaColumnInput>>(
     (extra): extra is SchemaPolicyDecl => extra.kind === "schema-policy",
   );
   const rls = extras.some((extra) => extra.kind === "schema-rls") || policies.length > 0;
+  const unscoped = extras.some(
+    (extra) => extra.kind === "schema-tenant-scoped" && extra.tenantScoped === false,
+  );
   const table = {
     name,
     columns: stamped,
     ...stamped,
     ...(rls ? { rls: true } : {}),
     ...(policies.length > 0 ? { policies } : {}),
+    ...(unscoped ? { tenantScoped: false } : {}),
   };
   // 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]> }>;
 }
 
 /**
@@ -409,12 +480,25 @@ function sqlStringLiteral(value: string): string {
   return `'${value.replaceAll("'", "''")}'`;
 }
 
-function helperPolicyName(prefix: string, key: string, command: SchemaPolicyFor): string {
+/**
+ * Policy name `prefix_key_command`.
+ *
+ * @param prefix - Helper kind
+ * @param key - Gate / column / scope
+ * @param command - SQL command
+ */
+export 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(
+/**
+ * USING / WITH CHECK split for a helper expression.
+ *
+ * @param command - SQL command
+ * @param expr - Predicate
+ */
+export function policyPredicates(
   command: SchemaPolicyFor,
   expr: string,
 ): { readonly using?: string; readonly withCheck?: string } {
@@ -482,13 +566,46 @@ export type SchemaPolicyApi = typeof schemaPolicy & {
   readonly gate: typeof schemaPolicyGate;
   readonly owner: typeof schemaPolicyOwner;
   readonly scope: typeof schemaPolicyScope;
+  readonly tenant: (
+    column: string,
+    options?: Pick<SchemaPolicyOptions, "for" | "as" | "to">,
+  ) => SchemaPolicyDecl;
 };
 
+function loadSchemaTenant(): {
+  tenant: SchemaPolicyApi["tenant"];
+  unscoped: () => SchemaTenantScopedDecl;
+} {
+  return lazyRequire(import.meta.dir, ["schema", "tenant"].join("-"));
+}
+
+/**
+ * Tenant-column policy — `tenant_id = oke.tenant()`.
+ *
+ * @param column - SQL / JS column name
+ * @param options - Command (default `all`)
+ */
+export function schemaPolicyTenant(
+  column: string,
+  options: Pick<SchemaPolicyOptions, "for" | "as" | "to"> = {},
+): SchemaPolicyDecl {
+  return loadSchemaTenant().tenant(column, options);
+}
+
+/**
+ * Mark a table as globally shared (`tenantScoped: false`).
+ * Required when `gate.auth.tenant` is on and the table has no tenant policy.
+ */
+export function schemaUnscoped(): SchemaTenantScopedDecl {
+  return loadSchemaTenant().unscoped();
+}
+
 /** `store.schema.policy` — raw + Gate helpers. */
 export const schemaPolicyApi: SchemaPolicyApi = Object.assign(schemaPolicy, {
   gate: schemaPolicyGate,
   owner: schemaPolicyOwner,
   scope: schemaPolicyScope,
+  tenant: schemaPolicyTenant,
 });
 
 // ─── Relations (mirrors drizzle-orm `defineRelations`) ───────────────────────
@@ -688,6 +805,7 @@ export const schema = {
   relations: schemaRelations,
   rls: schemaRls,
   policy: schemaPolicyApi,
+  unscoped: schemaUnscoped,
 } as const;
 
 /**

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

@@ -0,0 +1,41 @@
+/**
+ * Tenant schema helpers — lazy chunk off Store-only `oke()` graphs.
+ *
+ * `store.schema.policy.tenant` / `store.schema.unscoped` stay on the public
+ * API via getters; this module is loaded on first access.
+ */
+
+import {
+  schemaPolicy,
+  helperPolicyName,
+  policyPredicates,
+  type SchemaPolicyDecl,
+  type SchemaPolicyOptions,
+  type SchemaTenantScopedDecl,
+} from "./schema-decl.ts";
+
+/**
+ * Tenant-column policy — `tenant_id = oke.tenant()`.
+ *
+ * @param column - SQL / JS column name
+ * @param options - Command (default `all`)
+ */
+export function tenant(
+  column: string,
+  options: Pick<SchemaPolicyOptions, "for" | "as" | "to"> = {},
+): SchemaPolicyDecl {
+  const command = options.for ?? "all";
+  return schemaPolicy(helperPolicyName("tenant", column, command), {
+    ...options,
+    for: command,
+    ...policyPredicates(command, `${column} = oke.tenant()`),
+  });
+}
+
+/**
+ * Mark a table as globally shared (`tenantScoped: false`).
+ * Required when `gate.auth.tenant` is on and the table has no tenant policy.
+ */
+export function unscoped(): SchemaTenantScopedDecl {
+  return { kind: "schema-tenant-scoped", tenantScoped: false };
+}

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

@@ -100,6 +100,45 @@ describe("sql-session RLS isolation (pglite)", () => {
       { id: "b", owner: "bob" },
     ]);
   });
+
+  test("tenant_id = oke.tenant() isolates concurrent tenants", async () => {
+    await conn.exec(`CREATE TABLE bookings (
+      id text PRIMARY KEY,
+      tenant_id text NOT NULL,
+      body text NOT NULL
+    )`);
+    await conn.exec(`INSERT INTO bookings VALUES ('1', 'acme', 'a'), ('2', 'globex', 'b')`);
+    await conn.exec(`ALTER TABLE bookings ENABLE ROW LEVEL SECURITY`);
+    await conn.exec(`GRANT SELECT, INSERT, UPDATE, DELETE ON bookings TO oke_app`);
+    await conn.exec(`CREATE POLICY tenant_all ON bookings
+      AS PERMISSIVE FOR ALL TO public
+      USING (tenant_id = oke.tenant())
+      WITH CHECK (tenant_id = oke.tenant())`);
+
+    const asAcme = createSqlStoreHandle("sql:app", {
+      connection: conn,
+      classifications: new Map(),
+      routedRole: "primary",
+      domainDdl: "off",
+      rls: { gate: "member", userId: "u1", scopes: ["member"], tenantId: "acme" },
+    });
+    const asGlobex = createSqlStoreHandle("sql:app", {
+      connection: conn,
+      classifications: new Map(),
+      routedRole: "primary",
+      domainDdl: "off",
+      rls: { gate: "member", userId: "u1", scopes: ["member"], tenantId: "globex" },
+    });
+
+    const [acme, globex, acmeAgain] = await Promise.all([
+      asAcme.raw(`SELECT id, tenant_id FROM bookings ORDER BY id`),
+      asGlobex.raw(`SELECT id, tenant_id FROM bookings ORDER BY id`),
+      asAcme.raw(`SELECT id, tenant_id FROM bookings ORDER BY id`),
+    ]);
+    expect(acme).toEqual([{ id: "1", tenant_id: "acme" }]);
+    expect(globex).toEqual([{ id: "2", tenant_id: "globex" }]);
+    expect(acmeAgain).toEqual([{ id: "1", tenant_id: "acme" }]);
+  });
 });
 
 const LIVE_PG =

package/src/elements/store/sql-select.types.test.ts

@@ -0,0 +1,71 @@
+/**
+ * Type-level proof: `select().from(store.schema.table())` resolves to the
+ * declared column JS shape — not `SqlRow`.
+ */
+import { describe, expect, test } from "bun:test";
+
+import type { SqlRow } from "../../drivers/types.ts";
+import { field, schemaTable } from "./schema-decl.ts";
+import type { InferSelectRow, SqlStoreHandle } from "./sql-session.ts";
+import { defineTable } from "./table.ts";
+
+/** Compile-time equality. */
+type Eq<A, B> = (<T>() => T extends A ? 1 : 2) extends <T>() => T extends B ? 1 : 2 ? true : false;
+type Assert<T extends true> = T;
+
+const items = schemaTable("items", {
+  id: field.text().primaryKey(),
+  title: field.text().notNull(),
+  note: field.text(),
+  count: field.integer().notNull(),
+  score: field.integer(),
+});
+
+type ExpectedRow = {
+  id: string;
+  title: string;
+  note: string | null;
+  count: number;
+  score: number | null;
+};
+
+async function selectAll(db: SqlStoreHandle) {
+  return db.select().from(items);
+}
+
+async function selectWhere(db: SqlStoreHandle) {
+  return db.select().from(items).where({ id: "x" });
+}
+
+async function selectOrder(db: SqlStoreHandle) {
+  return db.select().from(items).orderBy(items.title);
+}
+
+async function selectLimit(db: SqlStoreHandle) {
+  return db.select().from(items).limit(1);
+}
+
+async function selectProj(db: SqlStoreHandle) {
+  return db.select({ title: items.title }).from(items);
+}
+
+const bare = defineTable("bare", { id: { name: "id" } });
+
+async function selectBare(db: SqlStoreHandle) {
+  return db.select().from(bare);
+}
+
+type _Infer = Assert<Eq<InferSelectRow<typeof items>, ExpectedRow>>;
+type _All = Assert<Eq<Awaited<ReturnType<typeof selectAll>>, ExpectedRow[]>>;
+type _Where = Assert<Eq<Awaited<ReturnType<typeof selectWhere>>, ExpectedRow[]>>;
+type _Order = Assert<Eq<Awaited<ReturnType<typeof selectOrder>>, ExpectedRow[]>>;
+type _Limit = Assert<Eq<Awaited<ReturnType<typeof selectLimit>>, ExpectedRow[]>>;
+type _Proj = Assert<Eq<Awaited<ReturnType<typeof selectProj>>, SqlRow[]>>;
+type _Bare = Assert<Eq<Awaited<ReturnType<typeof selectBare>>, SqlRow[]>>;
+
+describe("select().from() row inference", () => {
+  test("type-level row shape matches declared columns", () => {
+    const _keep: _Infer & _All & _Where & _Order & _Limit & _Proj & _Bare = true;
+    expect(_keep).toBe(true);
+  });
+});