@palbase/backend 3.0.0 → 4.0.0

package/dist/{index-CXUs9iTQ.d.ts → index-DZW9CjiY.d.ts}

@@ -1,5 +1,5 @@
 import { Tables, TableTypes } from './db/env.js';
-import { D as DBClient } from './endpoint-DJ98tQd6.js';
+import { D as DBClient } from './endpoint-2d_DpASt.js';
 
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
@@ -98,29 +98,165 @@ declare function jsonb(): ColumnBuilder<'jsonb', false, false, never>;
  */
 declare function enumType<const V extends readonly string[]>(name: string, values: V): ColumnBuilder<'enum', false, false, V[number]>;
 
+/**
+ * policy.ts — the RLS policy authoring DSL.
+ *
+ * `policy(name)` returns a fluent builder that mirrors the `ColumnBuilder`
+ * style in columns.ts: each chainable method mutates the underlying
+ * definition and returns the builder so calls compose. The terminal value is
+ * a plain {@link PolicyDef} — the exact JSON shape the runtime's
+ * `schema_extract.js` reads off the bundled module and the Go side parses into
+ * `PolicyJSON` (CONTRACT-POLICY).
+ *
+ * @example
+ * import { policy } from "@palbase/backend";
+ *
+ * policy("owner_select")
+ *   .for("select")
+ *   .to("authenticated")
+ *   .using("owner = (select auth.uid())");
+ */
+/** The SQL command a policy applies to. `"all"` covers SELECT/INSERT/UPDATE/DELETE. */
+type PolicyCommand = "all" | "select" | "insert" | "update" | "delete";
+/** Whether a policy is permissive (OR-combined, the default) or restrictive
+ * (AND-combined). Mirrors Postgres `CREATE POLICY ... AS PERMISSIVE|RESTRICTIVE`. */
+type PolicyMode = "permissive" | "restrictive";
+/**
+ * The compiled, serializable policy definition — the EXACT shape consumed by
+ * `schema_extract.js` → Go `PolicyJSON` (CONTRACT-POLICY).
+ *
+ * - `roles`: the DB roles this policy applies to (`TO` clause). An empty array
+ *   means the policy applies to PUBLIC (all roles) — the Postgres default.
+ * - `using`: the `USING (...)` row-visibility expression, or `null` when none.
+ * - `withCheck`: the `WITH CHECK (...)` write-validation expression, or `null`.
+ * - `permissive`: `true` for `AS PERMISSIVE` (default), `false` for restrictive.
+ */
+interface PolicyDef {
+    name: string;
+    command: PolicyCommand;
+    roles: string[];
+    using: string | null;
+    withCheck: string | null;
+    permissive: boolean;
+}
+/**
+ * Fluent RLS policy builder.
+ *
+ * Defaults (documented, applied at construction):
+ *  - `command`: `"all"` — applies to every SQL command unless `.for(...)` narrows it.
+ *  - `roles`: `["authenticated"]` — the common case is "rule applies to signed-in
+ *    users". Call `.to(...)` to override; pass `.to()` with no roles (or never
+ *    call it after a reset) to target PUBLIC.
+ *  - `using` / `withCheck`: `null` — no row filter / write check until set.
+ *  - `permissive`: `true` — `AS PERMISSIVE` (policies OR together).
+ *
+ * Each method mutates `_def` in place and returns `this`, so the chain is a
+ * single builder instance (no per-call allocation, like a tagged-template
+ * compile target). The terminal `PolicyDef` is read directly off `_def` by
+ * `schema_extract.js`.
+ */
+declare class PolicyBuilder {
+    readonly _def: PolicyDef;
+    constructor(name: string);
+    /** Restrict the policy to a single SQL command (default `"all"`). */
+    for(command: PolicyCommand): this;
+    /**
+     * Set the DB roles the policy applies to (the `TO` clause), replacing any
+     * previously-set roles. Call with no arguments to target PUBLIC (all roles).
+     *
+     * @example
+     * policy("p").to("authenticated")
+     * policy("p").to("authenticated", "service_role")
+     * policy("p").to() // PUBLIC
+     */
+    to(...roles: string[]): this;
+    /** Set the `USING (...)` row-visibility expression (raw SQL). */
+    using(sqlExpr: string): this;
+    /** Set the `WITH CHECK (...)` write-validation expression (raw SQL). */
+    withCheck(sqlExpr: string): this;
+    /** Set the policy mode: `"permissive"` (default, OR-combined) or
+     * `"restrictive"` (AND-combined). */
+    as(mode: PolicyMode): this;
+}
+/**
+ * Start authoring an RLS policy. Returns a {@link PolicyBuilder}; the resulting
+ * `PolicyBuilder` is accepted directly in a table's `policies: [...]` array
+ * (its `_def` is read at schema-extract time).
+ *
+ * @param name The policy name. Palbase reconciliation keys policies by
+ *             `(table, name)`, so names must be unique per table.
+ */
+declare function policy(name: string): PolicyBuilder;
+
+/**
+ * Postgres extensions a Palbase project can enable from its schema.
+ *
+ * Extensions are config-as-code: declare them in `defineSchema({ extensions })`
+ * and the deploy installs them (CREATE EXTENSION … SCHEMA extensions) using the
+ * deploy path's privileged connection. They are NOT toggled live from Studio —
+ * CREATE EXTENSION requires a superuser role that only the deploy path holds.
+ *
+ * The list is an allowlist (a string-literal union) so editors autocomplete the
+ * supported names and a typo fails typecheck. It is intentionally extensible:
+ * add a name here (+ confirm the base image ships it) to support more.
+ */
+declare const PALBASE_EXTENSIONS: readonly ["vector", "pg_trgm", "unaccent", "citext", "postgis", "cube", "earthdistance", "hstore", "ltree", "pg_cron", "pgcrypto", "uuid-ossp"];
+/** A Postgres extension supported by Palbase (allowlist union). */
+type PalbaseExtension = (typeof PALBASE_EXTENSIONS)[number];
+/**
+ * Extensions that depend on another extension. The deploy installs
+ * dependencies first; declaring `earthdistance` without `cube` still works
+ * because the deploy resolves the order, but listing both is clearer.
+ */
+declare const EXTENSION_DEPENDENCIES: Partial<Record<PalbaseExtension, PalbaseExtension[]>>;
+/** Runtime guard: is `name` a supported Palbase extension? */
+declare function isPalbaseExtension(name: string): name is PalbaseExtension;
+
 /**
  * A map of column builders keyed by column name — the value you write under
- * each key of `defineSchema({ tables: { <name>: <columns> } })`.
+ * the `columns` key of `defineSchema({ tables: { <name>: { columns } } })`.
  *
  * The default `Record<string, ColumnBuilder>` keeps bare references compiling
  * without a type argument.
  */
 type ColumnMap = Record<string, ColumnBuilder>;
 /**
- * A table definition with its name and columns.
+ * The author-facing value written under each table key:
+ * `{ columns, rls?, policies? }`.
+ *
+ * - `columns`: the column map (required).
+ * - `rls`: enable + FORCE row-level security on this table. Implied when
+ *   `policies` is non-empty; set it explicitly to enable RLS with no policies
+ *   yet (deny-all — useful only as an intermediate step).
+ * - `policies`: the RLS policies for this table, authored with `policy(name)`.
+ *   Each entry may be a {@link PolicyBuilder} (the normal `policy(...)` chain)
+ *   or a raw {@link PolicyDef} object.
+ *
+ * The `C` type parameter preserves the precise per-column phantom types so the
+ * typed `Database.tables.*` surface keeps inferring insert/row shapes.
+ */
+interface TableInput<C extends ColumnMap = ColumnMap> {
+    columns: C;
+    rls?: boolean;
+    policies?: (PolicyBuilder | PolicyDef)[];
+}
+/**
+ * A table definition — the runtime value the Go runtime's `schema_extract.js`
+ * reads. It keys tables by `tableDef.name`, reads `tableDef.columns` for the
+ * column DDL, and `tableDef.rls` + `tableDef.policies` for RLS.
  *
- * The runtime value shape — `{ name, columns }` — is the contract the Go
- * runtime's `schema_extract.js` reads (it keys tables by `tableDef.name`).
  * `defineSchema` derives `name` from the object key, so authors never repeat
- * the table name.
+ * the table name. `rls`/`policies` are always present after normalization
+ * (defaulted to `false`/`[]`).
  *
- * The `C` type parameter preserves the precise per-column phantom types so
- * that downstream mapped types (InsertShape, RowShape) can discriminate on
- * them.
+ * The `C` type parameter preserves the precise per-column phantom types so that
+ * downstream mapped types (InsertShape, RowShape) can discriminate on them.
  */
 interface TableDef<C extends ColumnMap = ColumnMap> {
     name: string;
     columns: C;
+    rls: boolean;
+    policies: PolicyDef[];
 }
 /**
  * A schema definition containing multiple tables, keyed by table name.
@@ -131,49 +267,61 @@ interface TableDef<C extends ColumnMap = ColumnMap> {
  */
 interface SchemaDef<T extends Record<string, TableDef> = Record<string, TableDef>> {
     tables: T;
+    /** Postgres extensions to install on deploy. Normalized to `[]` when absent. */
+    extensions: PalbaseExtension[];
 }
 /** The author-facing input to `defineSchema` — a `tables` map whose keys are
- * the table names and whose values are the column maps. */
-interface SchemaInput<T extends Record<string, ColumnMap> = Record<string, ColumnMap>> {
+ * the table names and whose values are `{ columns, rls?, policies? }`, plus an
+ * optional `extensions` allowlist. */
+interface SchemaInput<T extends Record<string, TableInput> = Record<string, TableInput>> {
     tables: T;
+    /**
+     * Postgres extensions to enable for this project, e.g. `["vector"]`.
+     * Config-as-code: installed by the deploy (CREATE EXTENSION … SCHEMA
+     * extensions) with the privileged deploy connection. The type is an
+     * allowlist union, so unsupported names fail typecheck.
+     */
+    extensions?: PalbaseExtension[];
 }
-/** Map the author's `{ tables: { <name>: <columns> } }` input to the
- * `{ tables: { <name>: TableDef<columns> } }` runtime/type shape. */
-type TablesFromInput<T extends Record<string, ColumnMap>> = {
-    [K in keyof T]: TableDef<T[K]>;
+/** Map the author's `{ tables: { <name>: { columns } } }` input to the
+ * `{ tables: { <name>: TableDef<columns> } }` runtime/type shape, threading the
+ * per-table column map `T[K]["columns"]` so column-level inference survives. */
+type TablesFromInput<T extends Record<string, TableInput>> = {
+    [K in keyof T]: TableDef<T[K]["columns"]>;
 };
 /**
- * Define a schema. The table NAME comes from the object key — there is one
- * canonical form:
+ * Define a schema. The table NAME comes from the object key. Each table value
+ * is `{ columns, rls?, policies? }`:
  *
  *   export default defineSchema({
  *     tables: {
  *       todos: {
- *         id:    uuid().primaryKey().defaultRandom(),
- *         title: text().notNull(),
+ *         columns: {
+ *           id:    uuid().primaryKey().defaultRandom(),
+ *           owner: text().notNull(),
+ *           title: text().notNull(),
+ *         },
+ *         rls: true,
+ *         policies: [
+ *           policy("owner_all").for("all").to("authenticated")
+ *             .using("owner = (select auth.uid())")
+ *             .withCheck("owner = (select auth.uid())"),
+ *         ],
  *       },
  *     },
  *   });
  *
- * The returned value is `{ tables: { todos: { name: "todos", columns: {...} } } }`
- * — the exact shape the runtime schema extractor parses. Per-column phantom
- * types are preserved so `Database.tables.todos.insert({...})` is typed.
+ * The returned value is
+ * `{ tables: { todos: { name, columns, rls, policies } } }` — the exact shape
+ * the runtime schema extractor parses. Per-column phantom types are preserved
+ * so `Database.tables.todos.insert({...})` stays typed.
  *
- * @example
- * import { defineSchema, uuid, text, timestamp } from "@palbase/backend";
- *
- * export default defineSchema({
- *   tables: {
- *     todos: {
- *       id:         uuid().primaryKey().defaultRandom(),
- *       title:      text().notNull(),
- *       done:       boolean().default(false),
- *       created_at: timestamp().defaultNow(),
- *     },
- *   },
- * });
+ * RLS normalization: `rls` defaults to `false`, `policies` to `[]`. When
+ * `policies` is non-empty, `rls` is forced on (ENABLE + FORCE) regardless of
+ * the declared `rls` flag — a table with policies must have RLS enabled or the
+ * policies would be inert.
  */
-declare function defineSchema<T extends Record<string, ColumnMap>>(input: SchemaInput<T>): SchemaDef<TablesFromInput<T>>;
+declare function defineSchema<T extends Record<string, TableInput>>(input: SchemaInput<T>): SchemaDef<TablesFromInput<T>>;
 
 /**
  * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.
@@ -278,17 +426,38 @@ type EnvTables = {
 interface EnvTypedTx {
     tables: EnvTables;
 }
+/**
+ * The RLS-bypass sibling returned by `Database.asService()`. Same typed surface
+ * as {@link EnvTypedDatabase} — `tables`, the raw string ops, and a typed
+ * `transaction` — but it does NOT re-expose `asService` (no double-bypass).
+ * Every op it performs runs as the `service_role` (BYPASSRLS).
+ */
+interface EnvServiceDatabase extends Omit<DBClient, "transaction" | "asService"> {
+    tables: EnvTables;
+    transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;
+}
 /**
  * The typed-by-default Database surface: the raw string-keyed `DBClient` ops
- * PLUS a `tables` map typed against the project's generated `palbase-env.d.ts`
- * and a `transaction` whose callback receives the typed tables.
+ * PLUS a `tables` map typed against the project's generated `palbase-env.d.ts`,
+ * a `transaction` whose callback receives the typed tables, and `asService()`
+ * for the explicit RLS-bypass sibling.
  *
  * `transaction` is declared here (overriding `DBClient["transaction"]`) so the
- * `tx` the callback receives carries the typed `.tables` API.
+ * `tx` the callback receives carries the typed `.tables` API. `asService` is
+ * re-typed to return the typed {@link EnvServiceDatabase} sibling.
  */
-interface EnvTypedDatabase extends Omit<DBClient, "transaction"> {
+interface EnvTypedDatabase extends Omit<DBClient, "transaction" | "asService"> {
     tables: EnvTables;
     transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;
+    /**
+     * Return a sibling that bypasses RLS by running as the `service_role`. Use
+     * sparingly and explicitly — the default `Database.*` path is RLS-enforced.
+     *
+     * @example
+     * const all = await Database.asService().tables.todos.findMany({});
+     * const rows = await Database.asService().query("SELECT * FROM todos");
+     */
+    asService(): EnvServiceDatabase;
 }
 
-export { ColumnBuilder as C, type EnvTypedDatabase as E, type InsertShape as I, type OnDeleteAction as O, type RowShape as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, type EnvTables as d, type EnvTypedTable as e, type EnvTypedTx as f, type SchemaInput as g, type TypedDB as h, type TypedTable as i, type TypedTx as j, boolean as k, defineSchema as l, enumType as m, integer as n, jsonb as o, makeTypedDB as p, timestamp as q, text as t, uuid as u };
+export { text as A, timestamp as B, ColumnBuilder as C, uuid as D, type EnvTypedDatabase as E, type InsertShape as I, type OnDeleteAction as O, PALBASE_EXTENSIONS as P, type RowShape as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, EXTENSION_DEPENDENCIES as d, type EnvServiceDatabase as e, type EnvTables as f, type EnvTypedTable as g, type EnvTypedTx as h, type PalbaseExtension as i, PolicyBuilder as j, type PolicyCommand as k, type PolicyDef as l, type PolicyMode as m, type SchemaInput as n, type TableInput as o, type TypedDB as p, type TypedTable as q, type TypedTx as r, boolean as s, defineSchema as t, enumType as u, integer as v, isPalbaseExtension as w, jsonb as x, makeTypedDB as y, policy as z };

package/dist/{index-CZAwpQE1.d.cts → index-DzRFS3Tl.d.cts}

@@ -1,5 +1,5 @@
 import { Tables, TableTypes } from './db/env.cjs';
-import { D as DBClient } from './endpoint-DJ98tQd6.cjs';
+import { D as DBClient } from './endpoint-2d_DpASt.cjs';
 
 /** On delete action for foreign key references. */
 type OnDeleteAction = 'cascade' | 'set null' | 'restrict' | 'no action';
@@ -98,29 +98,165 @@ declare function jsonb(): ColumnBuilder<'jsonb', false, false, never>;
  */
 declare function enumType<const V extends readonly string[]>(name: string, values: V): ColumnBuilder<'enum', false, false, V[number]>;
 
+/**
+ * policy.ts — the RLS policy authoring DSL.
+ *
+ * `policy(name)` returns a fluent builder that mirrors the `ColumnBuilder`
+ * style in columns.ts: each chainable method mutates the underlying
+ * definition and returns the builder so calls compose. The terminal value is
+ * a plain {@link PolicyDef} — the exact JSON shape the runtime's
+ * `schema_extract.js` reads off the bundled module and the Go side parses into
+ * `PolicyJSON` (CONTRACT-POLICY).
+ *
+ * @example
+ * import { policy } from "@palbase/backend";
+ *
+ * policy("owner_select")
+ *   .for("select")
+ *   .to("authenticated")
+ *   .using("owner = (select auth.uid())");
+ */
+/** The SQL command a policy applies to. `"all"` covers SELECT/INSERT/UPDATE/DELETE. */
+type PolicyCommand = "all" | "select" | "insert" | "update" | "delete";
+/** Whether a policy is permissive (OR-combined, the default) or restrictive
+ * (AND-combined). Mirrors Postgres `CREATE POLICY ... AS PERMISSIVE|RESTRICTIVE`. */
+type PolicyMode = "permissive" | "restrictive";
+/**
+ * The compiled, serializable policy definition — the EXACT shape consumed by
+ * `schema_extract.js` → Go `PolicyJSON` (CONTRACT-POLICY).
+ *
+ * - `roles`: the DB roles this policy applies to (`TO` clause). An empty array
+ *   means the policy applies to PUBLIC (all roles) — the Postgres default.
+ * - `using`: the `USING (...)` row-visibility expression, or `null` when none.
+ * - `withCheck`: the `WITH CHECK (...)` write-validation expression, or `null`.
+ * - `permissive`: `true` for `AS PERMISSIVE` (default), `false` for restrictive.
+ */
+interface PolicyDef {
+    name: string;
+    command: PolicyCommand;
+    roles: string[];
+    using: string | null;
+    withCheck: string | null;
+    permissive: boolean;
+}
+/**
+ * Fluent RLS policy builder.
+ *
+ * Defaults (documented, applied at construction):
+ *  - `command`: `"all"` — applies to every SQL command unless `.for(...)` narrows it.
+ *  - `roles`: `["authenticated"]` — the common case is "rule applies to signed-in
+ *    users". Call `.to(...)` to override; pass `.to()` with no roles (or never
+ *    call it after a reset) to target PUBLIC.
+ *  - `using` / `withCheck`: `null` — no row filter / write check until set.
+ *  - `permissive`: `true` — `AS PERMISSIVE` (policies OR together).
+ *
+ * Each method mutates `_def` in place and returns `this`, so the chain is a
+ * single builder instance (no per-call allocation, like a tagged-template
+ * compile target). The terminal `PolicyDef` is read directly off `_def` by
+ * `schema_extract.js`.
+ */
+declare class PolicyBuilder {
+    readonly _def: PolicyDef;
+    constructor(name: string);
+    /** Restrict the policy to a single SQL command (default `"all"`). */
+    for(command: PolicyCommand): this;
+    /**
+     * Set the DB roles the policy applies to (the `TO` clause), replacing any
+     * previously-set roles. Call with no arguments to target PUBLIC (all roles).
+     *
+     * @example
+     * policy("p").to("authenticated")
+     * policy("p").to("authenticated", "service_role")
+     * policy("p").to() // PUBLIC
+     */
+    to(...roles: string[]): this;
+    /** Set the `USING (...)` row-visibility expression (raw SQL). */
+    using(sqlExpr: string): this;
+    /** Set the `WITH CHECK (...)` write-validation expression (raw SQL). */
+    withCheck(sqlExpr: string): this;
+    /** Set the policy mode: `"permissive"` (default, OR-combined) or
+     * `"restrictive"` (AND-combined). */
+    as(mode: PolicyMode): this;
+}
+/**
+ * Start authoring an RLS policy. Returns a {@link PolicyBuilder}; the resulting
+ * `PolicyBuilder` is accepted directly in a table's `policies: [...]` array
+ * (its `_def` is read at schema-extract time).
+ *
+ * @param name The policy name. Palbase reconciliation keys policies by
+ *             `(table, name)`, so names must be unique per table.
+ */
+declare function policy(name: string): PolicyBuilder;
+
+/**
+ * Postgres extensions a Palbase project can enable from its schema.
+ *
+ * Extensions are config-as-code: declare them in `defineSchema({ extensions })`
+ * and the deploy installs them (CREATE EXTENSION … SCHEMA extensions) using the
+ * deploy path's privileged connection. They are NOT toggled live from Studio —
+ * CREATE EXTENSION requires a superuser role that only the deploy path holds.
+ *
+ * The list is an allowlist (a string-literal union) so editors autocomplete the
+ * supported names and a typo fails typecheck. It is intentionally extensible:
+ * add a name here (+ confirm the base image ships it) to support more.
+ */
+declare const PALBASE_EXTENSIONS: readonly ["vector", "pg_trgm", "unaccent", "citext", "postgis", "cube", "earthdistance", "hstore", "ltree", "pg_cron", "pgcrypto", "uuid-ossp"];
+/** A Postgres extension supported by Palbase (allowlist union). */
+type PalbaseExtension = (typeof PALBASE_EXTENSIONS)[number];
+/**
+ * Extensions that depend on another extension. The deploy installs
+ * dependencies first; declaring `earthdistance` without `cube` still works
+ * because the deploy resolves the order, but listing both is clearer.
+ */
+declare const EXTENSION_DEPENDENCIES: Partial<Record<PalbaseExtension, PalbaseExtension[]>>;
+/** Runtime guard: is `name` a supported Palbase extension? */
+declare function isPalbaseExtension(name: string): name is PalbaseExtension;
+
 /**
  * A map of column builders keyed by column name — the value you write under
- * each key of `defineSchema({ tables: { <name>: <columns> } })`.
+ * the `columns` key of `defineSchema({ tables: { <name>: { columns } } })`.
  *
  * The default `Record<string, ColumnBuilder>` keeps bare references compiling
  * without a type argument.
  */
 type ColumnMap = Record<string, ColumnBuilder>;
 /**
- * A table definition with its name and columns.
+ * The author-facing value written under each table key:
+ * `{ columns, rls?, policies? }`.
+ *
+ * - `columns`: the column map (required).
+ * - `rls`: enable + FORCE row-level security on this table. Implied when
+ *   `policies` is non-empty; set it explicitly to enable RLS with no policies
+ *   yet (deny-all — useful only as an intermediate step).
+ * - `policies`: the RLS policies for this table, authored with `policy(name)`.
+ *   Each entry may be a {@link PolicyBuilder} (the normal `policy(...)` chain)
+ *   or a raw {@link PolicyDef} object.
+ *
+ * The `C` type parameter preserves the precise per-column phantom types so the
+ * typed `Database.tables.*` surface keeps inferring insert/row shapes.
+ */
+interface TableInput<C extends ColumnMap = ColumnMap> {
+    columns: C;
+    rls?: boolean;
+    policies?: (PolicyBuilder | PolicyDef)[];
+}
+/**
+ * A table definition — the runtime value the Go runtime's `schema_extract.js`
+ * reads. It keys tables by `tableDef.name`, reads `tableDef.columns` for the
+ * column DDL, and `tableDef.rls` + `tableDef.policies` for RLS.
  *
- * The runtime value shape — `{ name, columns }` — is the contract the Go
- * runtime's `schema_extract.js` reads (it keys tables by `tableDef.name`).
  * `defineSchema` derives `name` from the object key, so authors never repeat
- * the table name.
+ * the table name. `rls`/`policies` are always present after normalization
+ * (defaulted to `false`/`[]`).
  *
- * The `C` type parameter preserves the precise per-column phantom types so
- * that downstream mapped types (InsertShape, RowShape) can discriminate on
- * them.
+ * The `C` type parameter preserves the precise per-column phantom types so that
+ * downstream mapped types (InsertShape, RowShape) can discriminate on them.
  */
 interface TableDef<C extends ColumnMap = ColumnMap> {
     name: string;
     columns: C;
+    rls: boolean;
+    policies: PolicyDef[];
 }
 /**
  * A schema definition containing multiple tables, keyed by table name.
@@ -131,49 +267,61 @@ interface TableDef<C extends ColumnMap = ColumnMap> {
  */
 interface SchemaDef<T extends Record<string, TableDef> = Record<string, TableDef>> {
     tables: T;
+    /** Postgres extensions to install on deploy. Normalized to `[]` when absent. */
+    extensions: PalbaseExtension[];
 }
 /** The author-facing input to `defineSchema` — a `tables` map whose keys are
- * the table names and whose values are the column maps. */
-interface SchemaInput<T extends Record<string, ColumnMap> = Record<string, ColumnMap>> {
+ * the table names and whose values are `{ columns, rls?, policies? }`, plus an
+ * optional `extensions` allowlist. */
+interface SchemaInput<T extends Record<string, TableInput> = Record<string, TableInput>> {
     tables: T;
+    /**
+     * Postgres extensions to enable for this project, e.g. `["vector"]`.
+     * Config-as-code: installed by the deploy (CREATE EXTENSION … SCHEMA
+     * extensions) with the privileged deploy connection. The type is an
+     * allowlist union, so unsupported names fail typecheck.
+     */
+    extensions?: PalbaseExtension[];
 }
-/** Map the author's `{ tables: { <name>: <columns> } }` input to the
- * `{ tables: { <name>: TableDef<columns> } }` runtime/type shape. */
-type TablesFromInput<T extends Record<string, ColumnMap>> = {
-    [K in keyof T]: TableDef<T[K]>;
+/** Map the author's `{ tables: { <name>: { columns } } }` input to the
+ * `{ tables: { <name>: TableDef<columns> } }` runtime/type shape, threading the
+ * per-table column map `T[K]["columns"]` so column-level inference survives. */
+type TablesFromInput<T extends Record<string, TableInput>> = {
+    [K in keyof T]: TableDef<T[K]["columns"]>;
 };
 /**
- * Define a schema. The table NAME comes from the object key — there is one
- * canonical form:
+ * Define a schema. The table NAME comes from the object key. Each table value
+ * is `{ columns, rls?, policies? }`:
  *
  *   export default defineSchema({
  *     tables: {
  *       todos: {
- *         id:    uuid().primaryKey().defaultRandom(),
- *         title: text().notNull(),
+ *         columns: {
+ *           id:    uuid().primaryKey().defaultRandom(),
+ *           owner: text().notNull(),
+ *           title: text().notNull(),
+ *         },
+ *         rls: true,
+ *         policies: [
+ *           policy("owner_all").for("all").to("authenticated")
+ *             .using("owner = (select auth.uid())")
+ *             .withCheck("owner = (select auth.uid())"),
+ *         ],
  *       },
  *     },
  *   });
  *
- * The returned value is `{ tables: { todos: { name: "todos", columns: {...} } } }`
- * — the exact shape the runtime schema extractor parses. Per-column phantom
- * types are preserved so `Database.tables.todos.insert({...})` is typed.
+ * The returned value is
+ * `{ tables: { todos: { name, columns, rls, policies } } }` — the exact shape
+ * the runtime schema extractor parses. Per-column phantom types are preserved
+ * so `Database.tables.todos.insert({...})` stays typed.
  *
- * @example
- * import { defineSchema, uuid, text, timestamp } from "@palbase/backend";
- *
- * export default defineSchema({
- *   tables: {
- *     todos: {
- *       id:         uuid().primaryKey().defaultRandom(),
- *       title:      text().notNull(),
- *       done:       boolean().default(false),
- *       created_at: timestamp().defaultNow(),
- *     },
- *   },
- * });
+ * RLS normalization: `rls` defaults to `false`, `policies` to `[]`. When
+ * `policies` is non-empty, `rls` is forced on (ENABLE + FORCE) regardless of
+ * the declared `rls` flag — a table with policies must have RLS enabled or the
+ * policies would be inert.
  */
-declare function defineSchema<T extends Record<string, ColumnMap>>(input: SchemaInput<T>): SchemaDef<TablesFromInput<T>>;
+declare function defineSchema<T extends Record<string, TableInput>>(input: SchemaInput<T>): SchemaDef<TablesFromInput<T>>;
 
 /**
  * typed-db.ts — Task 2: TypedDB schema-derived insert/row shapes.
@@ -278,17 +426,38 @@ type EnvTables = {
 interface EnvTypedTx {
     tables: EnvTables;
 }
+/**
+ * The RLS-bypass sibling returned by `Database.asService()`. Same typed surface
+ * as {@link EnvTypedDatabase} — `tables`, the raw string ops, and a typed
+ * `transaction` — but it does NOT re-expose `asService` (no double-bypass).
+ * Every op it performs runs as the `service_role` (BYPASSRLS).
+ */
+interface EnvServiceDatabase extends Omit<DBClient, "transaction" | "asService"> {
+    tables: EnvTables;
+    transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;
+}
 /**
  * The typed-by-default Database surface: the raw string-keyed `DBClient` ops
- * PLUS a `tables` map typed against the project's generated `palbase-env.d.ts`
- * and a `transaction` whose callback receives the typed tables.
+ * PLUS a `tables` map typed against the project's generated `palbase-env.d.ts`,
+ * a `transaction` whose callback receives the typed tables, and `asService()`
+ * for the explicit RLS-bypass sibling.
  *
  * `transaction` is declared here (overriding `DBClient["transaction"]`) so the
- * `tx` the callback receives carries the typed `.tables` API.
+ * `tx` the callback receives carries the typed `.tables` API. `asService` is
+ * re-typed to return the typed {@link EnvServiceDatabase} sibling.
  */
-interface EnvTypedDatabase extends Omit<DBClient, "transaction"> {
+interface EnvTypedDatabase extends Omit<DBClient, "transaction" | "asService"> {
     tables: EnvTables;
     transaction<T>(fn: (tx: EnvTypedTx) => Promise<T>): Promise<T>;
+    /**
+     * Return a sibling that bypasses RLS by running as the `service_role`. Use
+     * sparingly and explicitly — the default `Database.*` path is RLS-enforced.
+     *
+     * @example
+     * const all = await Database.asService().tables.todos.findMany({});
+     * const rows = await Database.asService().query("SELECT * FROM todos");
+     */
+    asService(): EnvServiceDatabase;
 }
 
-export { ColumnBuilder as C, type EnvTypedDatabase as E, type InsertShape as I, type OnDeleteAction as O, type RowShape as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, type EnvTables as d, type EnvTypedTable as e, type EnvTypedTx as f, type SchemaInput as g, type TypedDB as h, type TypedTable as i, type TypedTx as j, boolean as k, defineSchema as l, enumType as m, integer as n, jsonb as o, makeTypedDB as p, timestamp as q, text as t, uuid as u };
+export { text as A, timestamp as B, ColumnBuilder as C, uuid as D, type EnvTypedDatabase as E, type InsertShape as I, type OnDeleteAction as O, PALBASE_EXTENSIONS as P, type RowShape as R, type SchemaDef as S, type TableDef as T, type ColumnDef as a, type ColumnMap as b, type ColumnType as c, EXTENSION_DEPENDENCIES as d, type EnvServiceDatabase as e, type EnvTables as f, type EnvTypedTable as g, type EnvTypedTx as h, type PalbaseExtension as i, PolicyBuilder as j, type PolicyCommand as k, type PolicyDef as l, type PolicyMode as m, type SchemaInput as n, type TableInput as o, type TypedDB as p, type TypedTable as q, type TypedTx as r, boolean as s, defineSchema as t, enumType as u, integer as v, isPalbaseExtension as w, jsonb as x, makeTypedDB as y, policy as z };