better-supabase 0.12.0 → 0.14.0

package/dist/config-BuOz_O-y.d.ts

@@ -0,0 +1,2152 @@
+/// <reference lib="esnext.temporal" />
+import { F as BucketPolicyName, I as Casing, k as AccessBucketPolicy, lt as SchemaMeta, xt as BucketLifecycle } from "./executor-CPyrQdjh.js";
+import { _ as BlocksConfig, a as AuthorizationProvider, d as AccessBlockConfig, g as BlockScope, m as BlockConfig, p as AnyBlocksConfig } from "./authorization-BuT26_sR.js";
+import { i as BlockCategory, y as PortName } from "./define-block-COpcS6aT.js";
+import { i as FieldSpec } from "./table-schema-Cb-IV_pZ.js";
+import { n as SubjectsConfig } from "./subjects-B6p4oAZJ.js";
+import { f as ModuleTableSpec, l as ModuleEntitySpec } from "./context-9Q23weHu.js";
+import { i as FIELD_FORMAT_NAMES, s as FieldFormatName } from "./field-formats-DbjaDXoZ.js";
+//#region src/config/names.d.ts
+/** The steps `better-supabase gen` runs, in the order it runs them. */
+declare const GEN_TASKS: readonly ["types", "sql", "spec", "seed", "scaffold", "env"];
+/** Glue `better-supabase init` and `add` write for a framework or runtime. */
+declare const INTEGRATION_NAMES: readonly ["next", "hono", "orpc", "edge", "expo", "mcp", "client", "react"];
+/**
+ * An integration as `init`, `add` and `/create` show it, and the integrations
+ * it needs.
+ */
+interface IntegrationInfo {
+  readonly title: string;
+  /** What `init` or `add` writes, one sentence. */
+  readonly description: string;
+  readonly requires: readonly (typeof INTEGRATION_NAMES)[number][];
+}
+declare const INTEGRATION_INFO: Readonly<Record<(typeof INTEGRATION_NAMES)[number], IntegrationInfo>>;
+/** The agent folders `better-supabase skills install` writes to. */
+declare const SKILLS_AGENTS: readonly ["cursor", "claude", "agents"];
+//#endregion
+//#region src/config/generator-metadata.d.ts
+/**
+ * A copy of `@supabase/postgrest-typegen`'s `GeneratorMetadata` contract
+ * (version 1), so the published types don't reference the package: it is an
+ * optional peer that only the CLI loads.
+ * `tests/config/generator-metadata.test-d.ts` checks the copy against the
+ * pinned version.
+ */
+interface PostgresColumn {
+  table_id: number;
+  schema: string;
+  table: string;
+  id: string;
+  ordinal_position: number;
+  name: string;
+  default_value: unknown;
+  data_type: string;
+  format: string;
+  type_schema: string;
+  is_identity: boolean;
+  identity_generation: "ALWAYS" | "BY DEFAULT" | null;
+  is_generated: boolean;
+  is_nullable: boolean;
+  is_updatable: boolean;
+  is_unique: boolean;
+  enums: string[];
+  check: string | null;
+  comment: string | null;
+}
+interface PostgresFunctionArg {
+  mode: "in" | "inout" | "out" | "table" | "variadic";
+  name: string;
+  type_id: number;
+  has_default: boolean | null;
+}
+interface PostgresFunction {
+  id: number;
+  schema: string;
+  name: string;
+  language: string;
+  definition: string;
+  complete_statement: string;
+  args: PostgresFunctionArg[];
+  argument_types: string;
+  identity_argument_types: string;
+  return_type_id: number;
+  return_type: string;
+  return_type_relation_id: number | null;
+  is_set_returning_function: boolean;
+  prorows: number | null;
+  behavior: "IMMUTABLE" | "STABLE" | "VOLATILE";
+  security_definer: boolean;
+  config_params: {
+    [x: string]: string;
+  } | null;
+}
+/**
+ * A reference to a `types` entry by oid; `null` names when it is not in
+ * `types`.
+ */
+interface RpcTypeReference {
+  type_id: number;
+  format: string | null;
+  type_schema: string | null;
+}
+interface RpcFunctionArg extends RpcTypeReference {
+  name: string;
+  mode: "in" | "inout" | "variadic";
+  has_default: boolean;
+  relation_id: number | null;
+}
+interface RpcReturnColumn extends RpcTypeReference {
+  name: string;
+}
+interface RpcFunctionReturns extends RpcTypeReference {
+  relation_id: number | null;
+  columns: RpcReturnColumn[] | null;
+}
+interface RpcFunctionOverload {
+  function_id: number;
+  args: RpcFunctionArg[];
+  returns: RpcFunctionReturns;
+  is_set_returning: boolean;
+  rows_estimate: number | null;
+  setof_options: {
+    from: string;
+    to: string;
+    is_one_to_one: boolean;
+    is_setof_return: boolean;
+  } | null;
+  computed_field_of: number | null;
+  error: string | null;
+}
+/** A function PostgREST exposes under `/rpc`, with its overloads resolved. */
+interface RpcFunction {
+  schema: string;
+  name: string;
+  overloads: RpcFunctionOverload[];
+}
+interface GeneratorMetadata {
+  version: 1;
+  schemas: {
+    id: number;
+    name: string;
+    owner: string;
+  }[];
+  tables: {
+    bytes: number;
+    comment: string | null;
+    dead_rows_estimate: number;
+    id: number;
+    live_rows_estimate: number;
+    name: string;
+    replica_identity: "DEFAULT" | "FULL" | "INDEX" | "NOTHING";
+    rls_enabled: boolean;
+    rls_forced: boolean;
+    schema: string;
+    size: string;
+  }[];
+  foreignTables: {
+    comment: string | null;
+    id: number;
+    name: string;
+    schema: string;
+  }[];
+  views: {
+    comment: string | null;
+    id: number;
+    is_insert_enabled?: boolean | undefined;
+    is_updatable: boolean;
+    is_update_enabled?: boolean | undefined;
+    name: string;
+    schema: string;
+  }[];
+  materializedViews: {
+    comment: string | null;
+    id: number;
+    is_populated: boolean;
+    name: string;
+    schema: string;
+  }[];
+  columns: PostgresColumn[];
+  primaryKeys: {
+    schema: string;
+    table_name: string;
+    name: string;
+    table_id: number;
+  }[];
+  relationships: {
+    foreign_key_name: string;
+    schema: string;
+    relation: string;
+    columns: string[];
+    is_one_to_one: boolean;
+    referenced_schema: string;
+    referenced_relation: string;
+    referenced_columns: string[];
+  }[];
+  functions: PostgresFunction[];
+  types: {
+    id: number;
+    name: string;
+    schema: string;
+    format: string;
+    enums: string[];
+    attributes: {
+      name: string;
+      type_id: number;
+    }[];
+    comment: string | null;
+    type_relation_id: number | null;
+  }[];
+  /**
+   * Derived from `functions`; generators resolve it themselves when it is
+   * absent, which is how better-supabase stores metadata.
+   */
+  rpcFunctions?: RpcFunction[] | undefined;
+}
+//#endregion
+//#region src/config/snapshot.d.ts
+/**
+ * What `better-supabase introspect` reads from Postgres. `generator` is the
+ * `@supabase/postgrest-typegen` contract (the same metadata behind `supabase
+ * gen types`); `extras` holds what that contract leaves out. Codegen and doctor
+ * both work from this snapshot, so either can run offline from a saved file.
+ */
+interface Snapshot {
+  readonly $schema?: string;
+  readonly version: 2;
+  /** Every schema that was read, including helper schemas for doctor. */
+  readonly schemas: readonly string[];
+  readonly generator: GeneratorMetadata;
+  readonly extras: SnapshotExtras;
+}
+/** Catalog details `GeneratorMetadata` does not carry. */
+interface SnapshotExtras {
+  readonly tables: readonly ExtrasTable[];
+  readonly buckets: readonly SnapshotBucket[];
+  /** Tables in the `supabase_realtime` publication, as `schema.table`. */
+  readonly realtime: readonly string[];
+  /**
+   * `alter role ... set` values for the Data API roles (`authenticator`), such
+   * as `pgrst.db_aggregates_enabled`. Absent in older snapshots.
+   */
+  readonly roleSettings?: Readonly<Record<string, Readonly<Record<string, string>>>>;
+  /**
+   * Functions that policies in the read schemas call, plus functions in those
+   * schemas with `set` options. Absent in older snapshots.
+   */
+  readonly functions?: readonly ExtrasFunction[];
+  /**
+   * The Postgres functions `supabase/config.toml` configures as Auth hooks, in
+   * any schema. Absent in older snapshots and without a `config.toml`.
+   */
+  readonly hooks?: readonly ExtrasHook[];
+  /**
+   * Comments of the functions in the read schemas that carry a gen tag
+   * (`@notNull`), keyed by `schema.name(signature)`. Absent when none do.
+   */
+  readonly functionComments?: Readonly<Record<string, string>>;
+  /**
+   * Domains that the read schemas' functions take or return, with their base
+   * type. Typegen leaves them `unknown`; `gen` types them by the base type, and
+   * a `returns table` column of a NOT NULL domain is never null. Absent when no
+   * function uses a domain.
+   */
+  readonly domains?: readonly ExtrasDomain[];
+  /**
+   * Set when the snapshot comes from a `GeneratorMetadata` document alone (`gen
+   * --metadata`): unique keys, checks and foreign keys are inferred from the
+   * columns and relationships, and the rest is empty, so doctor skips the rules
+   * that read it.
+   */
+  readonly fromMetadata?: true;
+}
+interface ExtrasDomain {
+  readonly schema: string;
+  readonly name: string;
+  /** The base type's name (`uuid`, `_text`). */
+  readonly baseType: string;
+  readonly baseSchema: string;
+  /** Declared `not null`. */
+  readonly notNull: boolean;
+}
+/** An `[auth.hook.<name>]` with a `pg-functions://` URI. */
+interface ExtrasHook {
+  /** `custom_access_token`, `send_email`, ... */
+  readonly hook: string;
+  readonly schema: string;
+  readonly name: string;
+  /** Every overload with that name; empty when the function does not exist. */
+  readonly functions: readonly ExtrasHookFunction[];
+}
+interface ExtrasHookFunction extends ExtrasFunction {
+  /**
+   * Of `supabase_auth_admin`, `authenticated` and `anon`, the roles that may
+   * execute it (directly or through `public`).
+   */
+  readonly execute: readonly string[];
+  /** Whether `public` may execute it (the default until revoked). */
+  readonly publicExecute: boolean;
+  /** Of the same roles, those with `usage` on its schema. */
+  readonly schemaUsage: readonly string[];
+  /** The function body (`pg_proc.prosrc`). Absent in snapshots that predate it. */
+  readonly source?: string;
+}
+/** A function as doctor needs it for RLS checks, in any schema. */
+interface ExtrasFunction {
+  readonly schema: string;
+  readonly name: string;
+  /** Identity arguments, e.g. `organization uuid`. */
+  readonly signature: string;
+  /** `sql`, `plpgsql`, `c`, ... */
+  readonly language: string;
+  readonly volatility: "immutable" | "stable" | "volatile";
+  readonly securityDefiner: boolean;
+  /** `set` options, e.g. `{ statement_timeout: '5s' }`. */
+  readonly settings: Readonly<Record<string, string>>;
+  /**
+   * Which of `anon` and `authenticated` may execute it. Absent in older
+   * snapshots.
+   */
+  readonly execute?: readonly string[];
+}
+interface ExtrasTable {
+  /** Table oid, matching `GeneratorMetadata.tables[].id`. */
+  readonly id: number;
+  readonly schema: string;
+  readonly name: string;
+  /** Primary key columns in key order. */
+  readonly primaryKey: readonly string[];
+  readonly uniques: readonly CatalogUnique[];
+  readonly foreignKeys: readonly {
+    readonly name: string;
+    readonly onDelete: ForeignKeyAction;
+    readonly onUpdate: ForeignKeyAction;
+  }[];
+  readonly checks: readonly CatalogCheck[];
+  readonly indexes: readonly CatalogIndex[];
+  readonly policies: readonly CatalogPolicy[];
+  readonly triggers: readonly CatalogTrigger[];
+  readonly grants: readonly CatalogGrant[];
+  /** Absent in snapshots taken before column grants were introspected. */
+  readonly columnGrants?: readonly CatalogColumnGrant[];
+  /**
+   * Postgres estimates at least `LARGE_TABLE_ROWS` rows; the `unbounded-read`
+   * lint reads it.
+   */
+  readonly large?: true;
+  /** The partitioned parent as `schema.name`, when the table is a partition. */
+  readonly partitionOf?: string;
+}
+type ForeignKeyAction = "no action" | "restrict" | "cascade" | "set null" | "set default";
+interface CatalogUnique {
+  readonly name: string;
+  readonly columns: readonly string[];
+}
+interface CatalogCheck {
+  readonly name: string;
+  readonly definition: string;
+}
+interface CatalogIndex {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly unique: boolean;
+  readonly primary: boolean;
+  readonly partial: boolean;
+  /** Access method (`btree`, `gin`, `gist`, ...). Absent in older snapshots. */
+  readonly method?: string;
+  /**
+   * The `where` of a partial index, as Postgres prints it. Absent in older
+   * snapshots.
+   */
+  readonly predicate?: string | null;
+}
+interface CatalogPolicy {
+  readonly name: string;
+  readonly command: "all" | "select" | "insert" | "update" | "delete";
+  readonly roles: readonly string[];
+  readonly permissive: boolean;
+  readonly using: string | null;
+  readonly check: string | null;
+  /**
+   * Functions the policy expressions call, as `schema.name`, from `pg_depend`.
+   * Absent in older snapshots.
+   */
+  readonly functions?: readonly string[];
+}
+interface CatalogTrigger {
+  readonly name: string;
+  readonly timing: "before" | "after" | "instead of";
+  readonly events: readonly ("insert" | "update" | "delete" | "truncate")[];
+  readonly level: "row" | "statement";
+  readonly function: string;
+  /** The `create trigger` arguments, when there are any. */
+  readonly args?: readonly string[];
+  /**
+   * The function's body, only for functions that call `realtime.send()` or
+   * `realtime.broadcast_changes()`, other than `broadcast_topic()`.
+   */
+  readonly source?: string;
+  /** The function's comment, for the same functions as `source`. */
+  readonly comment?: string;
+}
+interface CatalogGrant {
+  readonly role: string;
+  readonly privileges: readonly string[];
+}
+/**
+ * A column-level `select`, `insert` or `update` grant to `anon` or
+ * `authenticated`.
+ */
+interface CatalogColumnGrant {
+  readonly column: string;
+  readonly role: string;
+  readonly privileges: readonly string[];
+}
+interface SnapshotBucket {
+  readonly id: string;
+  readonly public: boolean;
+  readonly fileSizeLimit: number | null;
+  readonly allowedMimeTypes: readonly string[] | null;
+  /** `versioning_status`; absent when Storage has no versioning. */
+  readonly versioning?: "DISABLED" | "ENABLED" | "SUSPENDED" | null;
+  /** `lifecycle_configuration`; absent when Storage has no lifecycles. */
+  readonly lifecycle?: unknown;
+}
+/**
+ * The snapshot joined into one record per table, function and enum. Codegen and
+ * doctor read this view rather than the raw snapshot.
+ */
+interface Catalog {
+  readonly schemas: readonly string[];
+  readonly tables: readonly CatalogTable[];
+  readonly enums: readonly CatalogEnum[];
+  readonly functions: readonly CatalogFunction[];
+  readonly buckets: readonly SnapshotBucket[];
+  readonly realtime: readonly string[];
+}
+interface CatalogTable {
+  readonly id: number;
+  readonly schema: string;
+  readonly name: string;
+  /** Materialized views count as views; foreign tables as tables. */
+  readonly kind: "table" | "view";
+  readonly rls: boolean;
+  readonly forceRls: boolean;
+  readonly replicaIdentity: "DEFAULT" | "INDEX" | "FULL" | "NOTHING" | null;
+  /** Inserts work (always true for tables). */
+  readonly insertable: boolean;
+  /** Updates work (always true for tables). */
+  readonly updatable: boolean;
+  readonly comment: string | null;
+  readonly columns: readonly CatalogColumn[];
+  readonly primaryKey: readonly string[];
+  readonly uniques: readonly CatalogUnique[];
+  readonly foreignKeys: readonly CatalogForeignKey[];
+  readonly checks: readonly CatalogCheck[];
+  readonly indexes: readonly CatalogIndex[];
+  readonly policies: readonly CatalogPolicy[];
+  readonly triggers: readonly CatalogTrigger[];
+  readonly grants: readonly CatalogGrant[];
+  /** Absent in snapshots taken before column grants were introspected. */
+  readonly columnGrants?: readonly CatalogColumnGrant[];
+  /** The partitioned parent as `schema.name`, when the table is a partition. */
+  readonly partitionOf?: string;
+}
+interface CatalogColumn {
+  readonly name: string;
+  /** Type name; the element type for arrays (`uuid`, `int8`, `note_kind`). */
+  readonly udt: string;
+  /** Raw type name as Postgres reports it (`_text` for `text[]`). */
+  readonly format: string;
+  readonly typeSchema: string;
+  readonly isArray: boolean;
+  readonly isEnum: boolean;
+  readonly nullable: boolean;
+  readonly hasDefault: boolean;
+  readonly default: string | null;
+  readonly identity: "always" | "by default" | null;
+  readonly generated: boolean;
+  readonly updatable: boolean;
+  readonly comment: string | null;
+}
+interface CatalogForeignKey {
+  readonly name: string;
+  readonly columns: readonly string[];
+  readonly refSchema: string;
+  readonly refTable: string;
+  readonly refColumns: readonly string[];
+  readonly oneToOne: boolean;
+  readonly onDelete: ForeignKeyAction;
+  readonly onUpdate: ForeignKeyAction;
+}
+interface CatalogEnum {
+  readonly schema: string;
+  readonly name: string;
+  readonly values: readonly string[];
+}
+interface CatalogFunction {
+  readonly schema: string;
+  readonly name: string;
+  /** Signature that tells overloads apart, e.g. `a integer, b text`. */
+  readonly signature: string;
+  readonly args: readonly CatalogFunctionArg[];
+  /** Columns for `returns table (...)` functions. */
+  readonly returnsTable: readonly {
+    readonly name: string;
+    readonly udt: string;
+    /** Schema of the column's type, when typegen knows it. */
+    readonly typeSchema?: string;
+    /** The column's type is a NOT NULL domain. */
+    readonly notNull?: true;
+  }[] | null;
+  /** Return type name (`int4`, `_text`, a table's row type). */
+  readonly returns: string;
+  /** Schema of the return type, when typegen knows it. */
+  readonly returnsSchema?: string;
+  /** `schema.table` when the function returns rows of a table or view. */
+  readonly returnsRelation: string | null;
+  readonly returnsSet: boolean;
+  readonly volatility: "immutable" | "stable" | "volatile";
+  readonly securityDefiner: boolean;
+  readonly language: string;
+  /** `search_path` from `SET search_path`, or `null` when unset. */
+  readonly searchPath: string | null;
+  /** The function's comment, when it carries a gen tag such as `@notNull`. */
+  readonly comment?: string;
+}
+interface CatalogFunctionArg {
+  readonly name: string;
+  readonly udt: string;
+  /** Schema of the argument's type, when typegen knows it. */
+  readonly typeSchema?: string;
+  readonly isArray: boolean;
+  readonly hasDefault: boolean;
+}
+//#endregion
+//#region src/config/types/tooling.d.ts
+interface OpenApiConfig {
+  /**
+   * Module exporting the document (or a function returning it) as `openapi` or
+   * default.
+   */
+  readonly entry?: string;
+  /** JSON file `better-supabase spec emit openapi` writes. */
+  readonly output?: string;
+}
+/** A docs UI `spec emit --ui` writes next to an OpenAPI document. */
+type SpecUiName = "scalar" | "swagger" | "redoc" | "elements" | "rapidoc";
+/** One document `better-supabase spec emit` writes. */
+interface SpecOutputConfig {
+  /** A format id: `openapi`, `asyncapi` or `arazzo`. */
+  readonly format: string;
+  /** Defaults to the format's default version, e.g. `3.1` for OpenAPI. */
+  readonly version?: string;
+  /** File to write, relative to the root. Defaults to the format's file name. */
+  readonly output?: string;
+  /** Overlay files (JSON or YAML), applied in order. */
+  readonly overlays?: readonly string[];
+  /**
+   * Defaults to `yaml` when `output` ends in `.yaml` or `.yml`, otherwise
+   * `json`.
+   */
+  readonly serialize?: "json" | "yaml";
+  /**
+   * Also writes a reference page (`openapi.html` for `openapi.json`) next to
+   * OpenAPI outputs.
+   */
+  readonly ui?: SpecUiName;
+}
+interface SpecsConfig {
+  /**
+   * Module exporting a `defineApi()` result (or a function returning one) as
+   * `api` or default.
+   */
+  readonly entry?: string;
+  /** The documents to write. Defaults to one OpenAPI document. */
+  readonly outputs?: readonly SpecOutputConfig[];
+  /**
+   * The lowest severity that fails `spec emit`, `check` and `validate`.
+   * Defaults to `error`.
+   */
+  readonly failOn?: "error" | "warning" | "never";
+  /**
+   * Also write the diagnostics manifest (JSON) to this file, like `spec
+   * --manifest`.
+   */
+  readonly manifest?: string;
+}
+/** A step `better-supabase gen` runs. */
+type GenTask = (typeof GEN_TASKS)[number];
+interface GenConfig {
+  /**
+   * The steps `better-supabase gen` runs, in this order: `types` (the generated
+   * modules and `generators`), `sql` (`sql sync`), `spec` (`spec emit`),
+   * `seed`, `scaffold` (`scaffold api`, its generated file only) and `env`.
+   * Without a list, `types` runs, plus `sql` when `blocks` or
+   * `realtime.policies` is set, `spec` and `seed` when their entry file exists,
+   * and `scaffold` when `scaffold.api` is set. `env` runs only when listed,
+   * because it needs the local stack. A listed step always runs.
+   */
+  readonly tasks?: readonly GenTask[];
+  /** Milliseconds between checks in `gen --watch` and `spec emit --watch`. */
+  readonly watchInterval?: number;
+}
+/** Glue `better-supabase init` and `add` write for a framework or runtime. */
+type IntegrationName = (typeof INTEGRATION_NAMES)[number];
+interface EnvFileConfig {
+  /** Env file `better-supabase env` writes. Defaults to `.env.local`. */
+  readonly output?: string;
+  /**
+   * Prefix for the browser variables, such as `NEXT_PUBLIC_`; `'none'` for no
+   * prefix. Detected from the framework by default.
+   */
+  readonly prefix?: string;
+}
+interface ScaffoldApiConfig {
+  /** Detected from `package.json` when the project has exactly one of them. */
+  readonly framework?: "hono" | "next";
+  /** Tables to serve. Defaults to every table and view in the public schema. */
+  readonly tables?: readonly string[];
+  /**
+   * The API module's name: `lib/<name>.ts` and `lib/<name>.generated.ts`.
+   * Defaults to `api`.
+   */
+  readonly name?: string;
+  /** Where the resources are served. Defaults to `/api`. */
+  readonly basePath?: string;
+}
+interface ScaffoldConfig {
+  /**
+   * What `better-supabase scaffold api` writes; the `scaffold` gen step keeps
+   * its generated file current.
+   */
+  readonly api?: ScaffoldApiConfig;
+}
+/** An agent folder `better-supabase skills install` writes to. */
+type SkillsAgent = (typeof SKILLS_AGENTS)[number];
+interface SkillsConfig {
+  /** Defaults to the agent folders the project has, else `agents`. */
+  readonly agents?: readonly SkillsAgent[];
+}
+interface KeysConfig {
+  /**
+   * Signing key file `better-supabase keys` writes. Defaults to
+   * `supabase/signing_keys.json`.
+   */
+  readonly output?: string;
+}
+interface DoctorConfig {
+  /** Finding codes to skip, e.g. `['BS204']`. */
+  readonly ignore?: readonly string[];
+  /** Run only these checks, e.g. `['BS100', 'BS304']`. */
+  readonly only?: readonly string[];
+  /** Treat warnings as errors. */
+  readonly strict?: boolean;
+  /**
+   * Report format: `text` (default), `sarif` (code scanning) or `github`
+   * (workflow annotations). `--json` still wins.
+   */
+  readonly format?: "text" | "sarif" | "github";
+  /** Write the report to this file. */
+  readonly output?: string;
+  /**
+   * App source files doctor scans for API use (BS210). Globs relative to the
+   * root. Defaults to `['src/**\/*.{ts,tsx}']`.
+   */
+  readonly sources?: readonly string[];
+  /**
+   * How many policies a security definer helper may appear in before BS206 asks
+   * for an inlinable `language sql stable` function. Defaults to 5.
+   */
+  readonly policyHelperLimit?: number;
+  /**
+   * The BS405 limit in bytes. When the authorization provider's token hook has
+   * a budget, it replaces that budget and the whole token keeps 2048. Otherwise
+   * it limits the whole token's claims (default 2048).
+   */
+  readonly claimsLimit?: number;
+  /** Which migrations the lock checks (BS229 to BS235) read. */
+  readonly migrationSafety?: MigrationSafetyConfig;
+}
+interface MigrationSafetyConfig {
+  /**
+   * The newest migration that is already applied everywhere, by file name
+   * (`20260101000000_init.sql`) or version (`20260101000000`). Offline, doctor
+   * checks only the migrations after it; with `--db-url` it checks the ones the
+   * database hasn't applied. `init` and `adopt` set it to the latest
+   * migration.
+   */
+  readonly since?: string;
+}
+//#endregion
+//#region src/preset/fields.d.ts
+/**
+ * How `/create` and `init` show one value: its label and, where the label is
+ * not enough, a hint.
+ */
+interface PresetValueInfo {
+  readonly label: string;
+  readonly hint?: string;
+}
+/**
+ * One convention a preset sets. `values` and the field list are append-only: a
+ * code stores each value's index in `bits` bits, so a value keeps its index
+ * forever and a new value fits only while `values` stays within `bits`. A
+ * `multi` field stores one bit per value.
+ */
+interface PresetCodeField<K extends string = string, V extends string = string> {
+  readonly key: K;
+  readonly values: readonly V[];
+  readonly default: V | readonly V[];
+  readonly bits: number;
+  readonly multi?: true;
+  /**
+   * The code version that added the field; older codes decode it as its
+   * default.
+   */
+  readonly since: number;
+}
+/** A convention field with the names `/create` and the `init` prompts show. */
+interface PresetField<K extends string = string, V extends string = string> extends PresetCodeField<K, V> {
+  readonly label: string;
+  readonly labels: { readonly [P in V]: PresetValueInfo; };
+}
+/** The value each convention field takes. */
+interface PresetConventions {
+  readonly framework: PresetFramework;
+  readonly platforms: "web" | "native" | "both";
+  readonly casing: "snake" | "camel";
+  readonly idType: "uuid" | "text" | "bigint" | "integer";
+  readonly scope: "tenant" | "user" | "none";
+  readonly tenantName: PresetTenantName;
+  readonly access: "roles" | "catalog" | "provider" | "custom";
+  readonly api: "none" | "api";
+  readonly integrations: readonly IntegrationName[];
+}
+/** A convention field's key. */
+type PresetFieldKey = keyof PresetConventions;
+/** The values a convention field takes. */
+type PresetFieldValue<K extends PresetFieldKey> = ValueOf<K>;
+type ValueOf<K extends PresetFieldKey> = PresetConventions[K] extends readonly (infer V extends string)[] ? V : Extract<PresetConventions[K], string>;
+/**
+ * The tenant names a preset can set (`blocks.tenant.entities.organization`), in
+ * code order.
+ */
+declare const PRESET_TENANT_NAMES: readonly ["organization", "workspace", "team"];
+type PresetTenantName = (typeof PRESET_TENANT_NAMES)[number];
+/** The frameworks `/create` and `init --preset` set up glue for. */
+declare const PRESET_FRAMEWORKS: readonly ["next", "vite", "tanstack-start", "expo", "sveltekit", "nuxt", "hono", "astro", "react-router"];
+type PresetFramework = (typeof PRESET_FRAMEWORKS)[number];
+/**
+ * The convention fields, in code order. Append new fields at the end with the
+ * next `since`, and never remove or reorder one.
+ */
+declare const PRESET_FIELDS: readonly PresetField<PresetFieldKey>[];
+/** A convention field by key, with its values and labels typed. */
+declare function presetField<K extends PresetFieldKey>(key: K): PresetField<K, ValueOf<K>>;
+/** A field value's label, or the value itself when it has none. */
+declare function presetValueLabel(key: PresetFieldKey, value: string): PresetValueInfo;
+/**
+ * The integrations `init --preset` adds for a framework whatever the selection
+ * says: the framework's own one, when it has one, then what that one requires.
+ */
+declare function integrationsForFramework(framework: PresetFramework): readonly IntegrationName[];
+type PresetPlatforms = PresetConventions["platforms"];
+type PresetScope = PresetConventions["scope"];
+type PresetAccess = PresetConventions["access"];
+/** A block selection and its conventions: what a preset code encodes. */
+interface Preset extends PresetConventions {
+  /**
+   * Block names (`blocks` keys in the config), as selected; `resolvePreset`
+   * adds what they require.
+   */
+  readonly blocks: readonly string[];
+}
+/** The newest code version; `encodePreset` writes it. */
+declare const PRESET_VERSION = 1;
+/** Every convention at its default. */
+declare const DEFAULT_CONVENTIONS: PresetConventions;
+//#endregion
+//#region src/preset/presets.d.ts
+/** Where a named preset sits in the `/create` and `init` pickers. */
+type PresetGroup = "starters" | "products" | "verticals" | "ai" | "platforms" | "everything";
+/** The preset groups in display order, with their headings. */
+declare const PRESET_GROUPS: Readonly<Record<PresetGroup, string>>;
+/** A named starting point: a block selection with the default conventions. */
+interface NamedPreset {
+  readonly name: string;
+  readonly title: string;
+  readonly description: string;
+  readonly group: PresetGroup;
+  /** The blocks it selects; `resolvePreset` adds what they require. */
+  readonly blocks: readonly string[];
+  /** The conventions it sets over the defaults, such as a user scope. */
+  readonly conventions?: Partial<PresetConventions>;
+}
+/** A named preset's name. */
+type PresetName = "minimal" | "saas" | "consumer" | "crm" | "projects" | "helpdesk" | "chat" | "commerce" | "marketplace" | "scheduling" | "people" | "drive" | "docs" | "invoicing" | "forms" | "property" | "field-service" | "clinic" | "lms" | "events" | "legal" | "spend" | "contracts" | "customer-success" | "logistics" | "pos" | "fitness" | "nonprofit" | "itsm" | "compliance" | "construction" | "claims" | "community" | "feedback" | "ai" | "ai-chat" | "ai-agents" | "developer-api" | "automation" | "enterprise" | "admin" | "everything";
+/** The named presets, for `defineConfig({ preset })` and `/create`. */
+declare const PRESETS: Readonly<Record<PresetName, NamedPreset>>;
+/** The named presets in display order, grouped by `group`. */
+declare const PRESET_NAMES: readonly PresetName[];
+declare function isPresetName(value: string): value is PresetName;
+/** The named preset as a `Preset`: the default conventions, then its own. */
+declare function namedPreset(name: PresetName): Preset;
+/** The preset `/create` and `init` start from. */
+declare const DEFAULT_PRESET_NAME: "saas";
+/** The default preset as a `Preset`, so a new design can start from it. */
+declare function defaultPreset(): Preset;
+/** The default preset's code, for a `/create` URL or `init --preset`. */
+declare function defaultPresetCode(): string;
+//#endregion
+//#region src/config/expose.d.ts
+/** A privilege the Data API roles can be granted on a table or view. */
+type Privilege = "select" | "insert" | "update" | "delete";
+type ColumnPrivilege = `${"select" | "insert" | "update"}(${string})`;
+type ExposePrivilege = Privilege | ColumnPrivilege;
+/** A role the `grants` module writes privileges for. */
+type ExposeRole = "anon" | "authenticated" | "service_role";
+/**
+ * Data API grants for one table: privileges for `authenticated`, or per role.
+ * `serviceRole` defaults to every privilege. For a function, keyed by its
+ * signature (`search_notes(text, integer)`), `execute` lists the roles that may
+ * call it; `service_role` is added unless `serviceRole` is false.
+ */
+type ExposeConfig = readonly ExposePrivilege[] | {
+  readonly anon?: readonly ExposePrivilege[];
+  readonly authenticated?: readonly ExposePrivilege[];
+  readonly serviceRole?: readonly ExposePrivilege[];
+} | {
+  readonly execute: readonly ("anon" | "authenticated")[];
+  readonly serviceRole?: boolean;
+};
+/** Resolved grants for one table. */
+interface ResolvedExpose {
+  readonly anon: readonly ExposePrivilege[];
+  readonly authenticated: readonly ExposePrivilege[];
+  readonly serviceRole: readonly ExposePrivilege[];
+}
+//#endregion
+//#region src/config/types/app-tables.d.ts
+/**
+ * The column types an app table may use. Money is a `bigint` of minor units
+ * next to a `text` currency column (ADR 0024 and 0037), never `numeric`.
+ */
+declare const APP_COLUMN_TYPES: readonly ["text", "uuid", "integer", "bigint", "numeric", "boolean", "timestamptz", "date", "jsonb", "text[]"];
+type AppColumnType = (typeof APP_COLUMN_TYPES)[number];
+/**
+ * What a reference does when the row it points at is deleted
+ * (`references.onDelete`).
+ */
+declare const APP_ON_DELETE_ACTIONS: readonly ["cascade", "restrict", "set null", "no action"];
+type AppOnDeleteAction = (typeof APP_ON_DELETE_ACTIONS)[number];
+/**
+ * What a column references: another app table, `auth.users` (`{ table:
+ * "auth.users" }`), or a logical table of an installed block (`{ block: "crm",
+ * table: "contacts" }`), which follows the block's renames.
+ */
+type AppReferenceTarget = {
+  readonly table: string;
+} | {
+  readonly block: string;
+  readonly table: string;
+};
+type AppReference = AppReferenceTarget & {
+  /** Defaults to `no action`. */
+  readonly onDelete?: AppOnDeleteAction;
+};
+/**
+ * What a column holds, beyond its Postgres type. `email`, `url`, `rating` and
+ * `percent` add a check; the others tell the UI and `gen` how to show the
+ * value. `FIELD_FORMATS` lists the types each fits and its input.
+ */
+declare const APP_COLUMN_FORMATS: typeof FIELD_FORMAT_NAMES;
+type AppColumnFormat = FieldFormatName;
+interface AppColumnConfig {
+  readonly type: AppColumnType;
+  /** Defaults to true. */
+  readonly nullable?: boolean;
+  /**
+   * The column default, from an allowlist: `now()`, `gen_random_uuid()`,
+   * `auth.uid()`, `true`, `false`, a number, a `'quoted'` text literal, and
+   * `'{}'` or `'[]'` for `jsonb` and `text[]`.
+   */
+  readonly default?: string;
+  readonly unique?: boolean;
+  readonly references?: AppReference;
+  /** What the column holds; see `APP_COLUMN_FORMATS`. */
+  readonly format?: AppColumnFormat;
+  /**
+   * The values a `text` column (single select) or each element of a `text[]`
+   * column (multi-select) may take, checked by the database.
+   */
+  readonly options?: readonly string[];
+  /** The smallest value of a number column, or the shortest `text`. */
+  readonly min?: number;
+  /** The largest value of a number column, or the longest `text`. */
+  readonly max?: number;
+  /** Rendered as `comment on column`. */
+  readonly comment?: string;
+  /**
+   * An `integer` or `bigint` the database numbers (`generated by default as
+   * identity`).
+   */
+  readonly identity?: boolean;
+  /**
+   * Who reaches the column, through column grants (ADR 0051). By default
+   * signed-in users read and write it, within the row's policies. `read` lets
+   * them read it while only the service role, triggers and defaults write it;
+   * `server` hides it from them, so only the service role reads and writes it.
+   */
+  readonly access?: AppColumnAccess;
+  /**
+   * Stores the column encrypted with the row's tenant (or user) data key from
+   * Supabase Vault, through the `field-encryption` block. Signed-in users write
+   * plaintext and never select the column; they read it through
+   * `public.<table>_reveal(ids)`, which checks the row's policy and decrypts.
+   * It can't be unique, a reference, an identity, indexed or searched.
+   */
+  readonly encrypted?: boolean;
+}
+declare const APP_COLUMN_ACCESS: readonly ["read", "server"];
+type AppColumnAccess = (typeof APP_COLUMN_ACCESS)[number];
+/**
+ * A table the app owns, created in `public` by `better-supabase sql sync` next
+ * to the block files. Every table gets `id`, the scope column and (unless
+ * `timestamps: false`) `created_at` and `updated_at`.
+ */
+interface AppTableConfig {
+  /** The table's own columns, keyed by lower snake name. */
+  readonly columns?: Readonly<Record<string, AppColumnConfig>>;
+  /**
+   * Who reaches a row. `inherit` (the default) follows `sql.scope`: per tenant,
+   * members of the row's tenant; per user, the row's user. `user` keeps rows
+   * per user in any scope, and `none` lets signed-in users read every row while
+   * only the service role writes.
+   */
+  readonly scope?: "inherit" | "user" | "none";
+  /** `created_at` and `updated_at`. Defaults to true. */
+  readonly timestamps?: boolean;
+  /**
+   * The id's type: `uuid` (the default, `gen_random_uuid()`) or `bigint` (an
+   * identity). A reference to the table needs a column of the same type.
+   */
+  readonly id?: "uuid" | "bigint";
+  /** Sets of columns that are unique together, each a unique constraint. */
+  readonly unique?: readonly (readonly string[])[];
+  /**
+   * Sets of columns to index, in order. Reference and scope columns already
+   * have one.
+   */
+  readonly indexes?: readonly (readonly string[])[];
+  /** Rendered as `comment on table`. */
+  readonly comment?: string;
+  /**
+   * Registers the table as a subject (ADR 0043), so blocks that attach rows to
+   * subjects (comments, attachments, tags, versions, search and others) reach
+   * its rows without a `subjects` entry.
+   */
+  readonly subject?: AppTableSubject;
+  /**
+   * Values computed from the rows of another app table that references this
+   * one, keyed by the column name they get in `public.<table>_view` (ADR
+   * 0044).
+   */
+  readonly rollups?: Readonly<Record<string, AppRollupConfig>>;
+  /**
+   * Columns of the row a reference points at, keyed by the column name they get
+   * in `public.<table>_view` (ADR 0044).
+   */
+  readonly lookups?: Readonly<Record<string, AppLookupConfig>>;
+  /**
+   * Emits an outbox event for each insert, update and delete (ADR 0048):
+   * `<subject type or table>.created`, `.updated` and `.deleted`. Needs the
+   * `outbox` block.
+   */
+  readonly events?: true | AppTableEvents;
+  /**
+   * Writes an audit log entry in the `read` category for each call of
+   * `public.<table>_reveal`: who read which rows and when, one entry per tenant
+   * per call. Needs an `encrypted` column and the `audit` block.
+   */
+  readonly auditReads?: boolean;
+}
+declare const APP_TABLE_EVENT_KINDS: readonly ["created", "updated", "deleted"];
+type AppTableEventKind = (typeof APP_TABLE_EVENT_KINDS)[number];
+/** Which writes emit an event and which column values its payload carries. */
+interface AppTableEvents {
+  /** Defaults to all three. */
+  readonly on?: readonly AppTableEventKind[];
+  /**
+   * Columns whose values go in the payload. By default it holds the row id and,
+   * for updates, the names of the changed columns.
+   */
+  readonly include?: readonly string[];
+}
+declare const APP_ROLLUP_AGGREGATES: readonly ["count", "sum", "min", "max", "avg"];
+type AppRollupAggregate = (typeof APP_ROLLUP_AGGREGATES)[number];
+/**
+ * An aggregate over the rows of `table` whose `via` column references this
+ * table: `{ table: "tasks", via: "project_id", aggregate: "count" }`.
+ */
+interface AppRollupConfig {
+  /** The app table whose rows are aggregated. */
+  readonly table: string;
+  /** The column of `table` that references this table. */
+  readonly via: string;
+  /** `sum` of no rows is 0; `min`, `max` and `avg` of no rows are null. */
+  readonly aggregate: AppRollupAggregate;
+  /**
+   * The column of `table` the aggregate reads: a number for `sum` and `avg`, a
+   * number, date, time or text for `min` and `max`. `count` takes none and
+   * counts rows.
+   */
+  readonly column?: string;
+  /**
+   * Only the rows whose select column (a `text` column with `options`) holds
+   * `equals`.
+   */
+  readonly where?: {
+    readonly column: string;
+    readonly equals: string;
+  };
+}
+/** The `column` of the app table row that this table's `via` column references. */
+interface AppLookupConfig {
+  /** A column of this table that references another app table. */
+  readonly via: string;
+  /** A column of the referenced table. */
+  readonly column: string;
+}
+/**
+ * The subject an app table registers. The table, id type and tenant column come
+ * from the table itself.
+ */
+interface AppTableSubject {
+  /** The subject type, lowercase letters, digits and underscores. */
+  readonly type: string;
+  /** The column `subject_title` returns. */
+  readonly title?: string;
+  /**
+   * The path `subject_url` returns, with `{column}` placeholders:
+   * `/projects/{id}`.
+   */
+  readonly url?: string;
+  /** The columns a search index reads. */
+  readonly search?: {
+    readonly title?: string;
+    readonly body?: readonly string[];
+  };
+  /**
+   * A permission key per action that `can_subject` checks; see
+   * `SubjectConfig.permissions`.
+   */
+  readonly permissions?: Readonly<Record<string, string>>;
+  /**
+   * Adds a `rank text collate "C"` column for `move()` (ADR 0021), ordered
+   * within `group` when set.
+   */
+  readonly rank?: true | {
+    readonly group?: string;
+  };
+  /**
+   * Adds a `deleted_at timestamptz` column that blocks treat as the soft-delete
+   * time.
+   */
+  readonly softDelete?: boolean;
+  /**
+   * Registers the table with the versions block: `true` snapshots every column
+   * of the table on each change; `columns` and `auto` narrow it.
+   */
+  readonly versions?: true | AppTableVersions;
+}
+/** What the versions block keeps of an app table's rows. */
+interface AppTableVersions {
+  /**
+   * The columns a snapshot copies and a restore writes back; every column of
+   * the table by default.
+   */
+  readonly columns?: readonly string[];
+  /** Snapshot on each change to `columns`, debounced; `true` by default. */
+  readonly auto?: boolean;
+}
+type AppTablesConfig = Readonly<Record<string, AppTableConfig>>;
+//#endregion
+//#region src/config/types/database.d.ts
+interface BucketConfig {
+  readonly id?: string;
+  readonly public?: boolean;
+  /**
+   * Path template with `{placeholders}`, e.g.
+   * `{organizationId}/{customerId}/logo.webp`, or several when the bucket
+   * stores objects in more than one layout. A last segment `{...rest}` matches
+   * one or more segments.
+   */
+  readonly path: string | readonly [string, ...string[]];
+  /** Generated storage policy, or an access contract policy (`{ access }`). */
+  readonly policy?: BucketPolicyName | AccessBucketPolicy;
+  readonly fileSizeLimit?: string;
+  readonly allowedMimeTypes?: readonly string[];
+  /**
+   * Keep earlier object versions. `bucket.apply()` sets it; doctor (BS302)
+   * compares it.
+   */
+  readonly versioning?: boolean;
+  /** When noncurrent versions expire. Needs `versioning: true`. */
+  readonly lifecycle?: BucketLifecycle;
+}
+/**
+ * How the SQL modules reach the database: `pg-delta` (Supabase Declarative
+ * Schemas 2.0, `supabase db schema declarative sync`), `migra` (declarative
+ * schemas 1.0, `supabase db diff`) or `migrations` (no declarative schemas: the
+ * `sql` commands write the modules into a migration).
+ */
+type SqlWorkflow = "pg-delta" | "migra" | "migrations";
+interface SqlConfig {
+  /**
+   * The workflow. Unset, better-supabase reads `supabase/config.toml`: pg-delta
+   * when it enables it or nothing says otherwise, migra when it turns pg-delta
+   * off or the project keeps migra's declarative schemas.
+   */
+  readonly workflow?: SqlWorkflow;
+  /** Directory declarative schema files are written to. */
+  readonly dir?: string;
+  /** File name prefix, so generated files sort after yours. */
+  readonly prefix?: string;
+  /** Directory pgTAP files (the `pgtap` module) are written to. */
+  readonly testsDir?: string;
+  /**
+   * The schema every module writes its functions and managed tables to, unless
+   * `blocks.<name>.schema` sets its own. Defaults to `better_supabase`.
+   */
+  readonly schema?: string;
+  /**
+   * The Data API schema, such as `api`, every module writes its `security
+   * invoker` wrappers to, unless `blocks.<name>.api` sets its own or `false`.
+   */
+  readonly api?: string;
+  /**
+   * Who a block's rows belong to, unless `blocks.<name>.scope` sets its own:
+   * `tenant` (a tenant, checked through the access contract; the default),
+   * `user` (the signed-in user, with no tenants) or `none` (one shared space
+   * every signed-in user reads and writes).
+   */
+  readonly scope?: BlockScope;
+}
+/** `sql` with defaults applied. */
+interface ResolvedSqlConfig {
+  /** Unset when the config leaves it to `supabase/config.toml`. */
+  readonly workflow?: SqlWorkflow;
+  readonly dir: string;
+  readonly prefix: string;
+  readonly testsDir: string;
+  /** Unset means `tenant`. */
+  readonly scope?: BlockScope;
+}
+interface SeedConfig {
+  /** Module exporting `defineSeed(...)` as `seed` or default. */
+  readonly entry?: string;
+  /** SQL file `better-supabase seed` writes. Add it to `[db.seed] sql_paths`. */
+  readonly output?: string;
+  /**
+   * Module exporting `defineTenantSeed(...)` as `seed` or default.
+   * `better-supabase seed --tenant <slug>` applies it to one tenant.
+   */
+  readonly perTenant?: string;
+}
+interface RealtimeConfig {
+  /**
+   * Tables that broadcast a change signal for live queries (`table` or
+   * `schema.table`). Tenant tables broadcast per tenant. Install the triggers
+   * with `better-supabase add realtime-tables`.
+   */
+  readonly tables?: readonly string[];
+  /**
+   * Tables in `tables` without a tenant column. They broadcast on one topic
+   * every signed-in user receives. With the `tenant` plugin, a table that lacks
+   * the tenant column and is not listed here fails to install.
+   */
+  readonly global?: readonly string[];
+  /**
+   * Tables in `tables` whose rows belong to one user: table to its user column
+   * (`{ notifications: "user_id" }`). They broadcast on a topic per user,
+   * `bs:t:<schema>.<table>:u:<user id>`, which only that user receives, instead
+   * of the tenant's topic.
+   */
+  readonly users?: Readonly<Record<string, string>>;
+  /**
+   * Writes the `realtime.messages` policies of the topics that `from` exports
+   * (`defineTopic`) to `output`, a file in `supabase/schemas`, on
+   * `better-supabase sql sync`; `sql sync --check` fails when it is stale.
+   */
+  readonly policies?: TopicPoliciesConfig;
+  /**
+   * Broadcast triggers that `sql sync` writes to `policies.output` next to the
+   * policies, through the topic's `trigger()`, for topics that `policies.from`
+   * exports. A trigger with column values, one topic, a `keys` or `row` payload
+   * and one event name calls `better_supabase.broadcast_topic()` (the
+   * `realtime-tables` module); any other gets a generated function.
+   */
+  readonly triggers?: readonly TopicTriggerConfig[];
+}
+interface TopicTriggerLookupConfig {
+  readonly from: string;
+  readonly via: TopicTriggerValueConfig;
+  readonly select: string;
+  readonly key?: string;
+}
+type TopicTriggerValueConfig = string | TopicTriggerLookupConfig;
+type TopicTriggerPayloadValueConfig = TopicTriggerValueConfig | {
+  readonly sql: string;
+};
+interface TopicTriggerTopicConfig {
+  readonly topic: string;
+  readonly values?: Readonly<Record<string, TopicTriggerValueConfig>>;
+}
+/** One `realtime.triggers` entry: a table whose row changes go to a topic. */
+interface TopicTriggerConfig {
+  /** The template of a topic that `realtime.policies.from` exports. */
+  readonly topic: string;
+  /** `table` or `schema.table`. */
+  readonly table: string;
+  /**
+   * The column or lookup per placeholder. Defaults to the placeholder in
+   * snake_case. A row whose topic comes out null is not sent to it.
+   */
+  readonly values?: Readonly<Record<string, TopicTriggerValueConfig>>;
+  /** Defaults to all three. */
+  readonly events?: readonly ("insert" | "update" | "delete")[];
+  /**
+   * The broadcast event name, or one per operation (`{ insert: "created",
+   * delete: "deleted" }`). Defaults to the operation.
+   */
+  readonly event?: string | {
+    readonly insert?: string;
+    readonly update?: string;
+    readonly delete?: string;
+  };
+  /**
+   * `"keys"` (default) sends the primary key and the placeholder values.
+   * `"row"` sends the whole row, which bypasses column grants. An object is the
+   * payload itself: each key is a column, a lookup, or `{ sql }`, an expression
+   * on the row `{row}` (`tg_op` is the operation).
+   */
+  readonly payload?: "keys" | "row" | Readonly<Record<string, TopicTriggerPayloadValueConfig>>;
+  readonly topics?: readonly TopicTriggerTopicConfig[];
+  readonly functionSchema?: string;
+  /**
+   * `{ changed: ["status"] }` sends an UPDATE only when one of these columns
+   * changed. Inserts and deletes always send.
+   */
+  readonly when?: {
+    readonly changed: readonly string[];
+  };
+}
+/** `realtime.policies`: where topic policies come from and go. */
+interface TopicPoliciesConfig {
+  /** Modules that export `defineTopic` results. Node imports them. */
+  readonly from: readonly string[];
+  /** The SQL file to write, such as `supabase/schemas/905_topics.sql`. */
+  readonly output: string;
+}
+/**
+ * Pgvector distance: `<=>` (cosine), `<->` (l2) or `<#>` (negative inner
+ * product).
+ */
+type VectorDistance = "cosine" | "l2" | "inner_product";
+/** The embedding column, or the column and its distance (default `cosine`). */
+type VectorSearchConfig = string | {
+  readonly column: string;
+  readonly distance?: VectorDistance;
+  /** The column's pgvector type. Defaults to `vector`. */
+  readonly type?: "vector" | "halfvec";
+  /**
+   * The primary key column `db.$search({ score: true })` merges by.
+   * Defaults to `id`.
+   */
+  readonly key?: string;
+  /**
+   * Fuses a full-text ranking over a `tsvector` column with the vector
+   * ranking (reciprocal rank fusion), for `db.$search({ text })`.
+   */
+  readonly hybrid?: {
+    readonly tsvector: string;
+    /** The query's text search configuration. Defaults to `simple`. */
+    readonly config?: string;
+    /** The RRF constant. Defaults to 60. */
+    readonly k?: number;
+  };
+  /**
+   * A SQL expression over the row `t` the score is multiplied by, such as
+   * `t.priority`.
+   */
+  readonly boost?: string;
+  /** Columns `db.$search({ filter })` narrows before ranking. */
+  readonly prefilter?: readonly string[];
+  /**
+   * A SQL condition over the row `t` every candidate must meet, applied
+   * before ranking: ranges, a parent row, such as `t.expires_at > now() and
+   * exists (select 1 from public.folders f where f.id = t.folder_id and not
+   * f.disabled)`.
+   */
+  readonly predicate?: string;
+  /** How `boost` combines with the score: `multiply` (default) or `add`. */
+  readonly boostMode?: "multiply" | "add";
+  /**
+   * A SQL `order by` list over the row `t` that breaks score ties, such as
+   * `t.created_at desc`.
+   */
+  readonly order?: string;
+};
+//#endregion
+//#region src/config/types/entitlements.d.ts
+interface EntitlementsConfig {
+  /**
+   * `table.column` (or `schema.table.column`) holding each tenant's Stripe
+   * customer id, read by the `entitlements` SQL module. Required without the
+   * `organizations` module; with it, defaults to the `stripe_customer_id`
+   * column that module adds.
+   */
+  readonly customer?: string;
+  /** The tenant id column of that table. Defaults to `id`. */
+  readonly key?: string;
+  /**
+   * Where `has_entitlement` and `feature_claims` read memberships from.
+   * `"provider"` calls the authorization provider's `memberIds` and
+   * `memberIdsFor` functions; `"tenant"` reads `better_supabase.memberships`.
+   * Defaults to `"provider"` when `authorization` is set, else `"tenant"`.
+   */
+  readonly memberships?: "tenant" | "provider";
+  /**
+   * Where each tenant's entitlements come from. `"stripe-sync"` (the default)
+   * reads the Stripe Sync Engine's `stripe.active_entitlements` through
+   * `customer`. `{ plans }` reads a plan catalog: the tenant's active
+   * subscription and the features its plan includes. `"custom"` leaves
+   * `better_supabase.tenant_entitlements(tenant)` to you; the module writes the
+   * checks and the claim over it.
+   */
+  readonly source?: "stripe-sync" | "custom" | EntitlementPlansSource;
+  /**
+   * The shape of the features claim `feature_claims` writes, which every token
+   * carries. `false` writes `{}` (check entitlements in SQL with
+   * `has_entitlement` only); `maxTenants` keeps at most that many tenants;
+   * `keys` writes short codes instead of the feature keys. Pass the same `keys`
+   * to `hasEntitlement`.
+   */
+  readonly claim?: false | {
+    readonly maxTenants?: number;
+    readonly keys?: Readonly<Record<string, string>>;
+  };
+}
+/** `entitlements.source.plans`: a plan catalog in your own tables. */
+interface EntitlementPlansSource {
+  readonly plans: {
+    readonly subscriptions: {
+      /** `table` or `schema.table`. */
+      readonly table: string;
+      /** The tenant id column. */
+      readonly tenant: string;
+      /** The plan key column. */
+      readonly plan: string;
+      /** A status column; with it, only rows in `activeStatuses` count. */
+      readonly status?: string;
+      /** Defaults to `["active", "trialing"]`. */
+      readonly activeStatuses?: readonly string[];
+    };
+    readonly features: {
+      /** `table` or `schema.table`. */
+      readonly table: string;
+      /** The plan key column. */
+      readonly plan: string;
+      /** The feature key column: what `has_entitlement` and the claim name. */
+      readonly feature: string;
+      /** A boolean column; with it, only included features count. */
+      readonly included?: string;
+      /**
+       * A column with the feature's value (a number, text or jsonb), such as a
+       * limit, that `tenant_entitlement_value` returns.
+       */
+      readonly value?: string;
+    };
+  };
+}
+//#endregion
+//#region src/config/types/config.d.ts
+interface BetterSupabaseConfig {
+  readonly $schema?: string;
+  readonly source?: SourceConfig;
+  /** Postgres schemas to generate. Defaults to `['public']`. */
+  readonly schemas?: readonly string[];
+  /** Casing of generated models and returned rows. Defaults to `'snake'`. */
+  readonly casing?: Casing;
+  readonly tables?: Readonly<Record<string, TableConfig>>;
+  /**
+   * Main generated module. Defaults to `src/lib/supabase/generated.ts`;
+   * `database.types.ts` is written next to it.
+   */
+  readonly output?: string;
+  /**
+   * PostgREST major version, written to `__InternalSupabase` in
+   * `database.types.ts` so `createClient` picks matching behavior. Defaults to
+   * `'13'`.
+   */
+  readonly postgrestVersion?: string;
+  /**
+   * Write one record feature per subject into `features/` next to `output`,
+   * with a section for each installed block that adds one, and
+   * `navigation.generated.ts` and `commands.generated.ts` with the subjects'
+   * list routes. Defaults to `true`.
+   */
+  readonly generateFeatures?: boolean;
+  /** Types for jsonb columns, keyed by `table.column`. */
+  readonly json?: Readonly<Record<string, JsonTypeConfig>>;
+  readonly codecs?: CodecsConfig;
+  readonly relations?: RelationsConfig;
+  /**
+   * Columns that must not be read by accident (`table.column` or
+   * `schema.table.column`, database names), for the `noSensitiveSelect` rule.
+   */
+  readonly sensitive?: readonly string[];
+  /**
+   * Text columns that hold an object path, keyed by `table.column` or
+   * `schema.table.column` (database names), with the bucket as the value (a
+   * `buckets` key or a bucket id). Generated rows type them as
+   * `StoragePath<'bucket-id'>`.
+   */
+  readonly storagePaths?: Readonly<Record<string, string>>;
+  /**
+   * Function results `gen` may type as not null, keyed by function name.
+   * Results are `| null` by default, since Postgres can't promise a function
+   * returns a value. `notNull: true` covers the whole result (each element of a
+   * set, each column of `returns table`); a list names the `returns table`
+   * columns that are never null.
+   */
+  readonly functions?: Readonly<Record<string, FunctionConfig>>;
+  /**
+   * Data API grants, keyed by `table` or `schema.table`, and function `execute`
+   * grants, keyed by `name(argument types)` or `schema.name(argument types)`. A
+   * project with default privileges turned off grants new tables to no Data API
+   * role; the `grants` SQL module writes these as the complete privilege set
+   * (it revokes what is not listed), and doctor (BS106) checks them. Tables not
+   * listed need `select, insert, update, delete` for `authenticated` (`select`
+   * for views).
+   */
+  readonly expose?: Readonly<Record<string, ExposeConfig>>;
+  /**
+   * Modules that export `defineReadSet` results. `gen` compiles each set to a
+   * function in the `read-sets` SQL module. Node imports them, so relative
+   * imports need their `.ts` extension.
+   */
+  readonly readSets?: readonly string[];
+  readonly generators?: readonly Generator[];
+  /** Enables plugin flags in the generated metadata. */
+  readonly plugins?: PluginFlagsConfig;
+  readonly claims?: ClaimsConfig;
+  readonly buckets?: Readonly<Record<string, BucketConfig>>;
+  /**
+   * Realtime topic templates: `{ notifications:
+   * 'organization:{organizationId}:notifications' }`.
+   */
+  readonly topics?: Readonly<Record<string, string>>;
+  readonly realtime?: RealtimeConfig;
+  readonly entitlements?: EntitlementsConfig;
+  /**
+   * An authorization system the SQL modules, policies and doctor delegate to:
+   * the `provider` access model, `entitlements.memberships` and the hook and
+   * policy checks.
+   */
+  readonly authorization?: AuthorizationProvider;
+  /**
+   * Embedding columns, keyed by `table` or `schema.table`. The `vector-search`
+   * SQL module writes `search_<table>(query, k)` for each, which
+   * `db.$search(table, { vector, k })` calls.
+   */
+  readonly vectorSearch?: Readonly<Record<string, VectorSearchConfig>>;
+  /**
+   * The app's subject types: the entities blocks attach tags, comments, fields
+   * and ranks to. Subject-bound SQL modules read this registry, the `subjects`
+   * module writes `subject_title`, `subject_url` and `can_subject` from it, and
+   * `gen` types `SubjectType` from its keys.
+   */
+  readonly subjects?: SubjectsConfig;
+  /**
+   * A named preset (`saas`, `crm`, ...), a code from `/create`, or its URL.
+   * `defineConfig` expands it into `blocks`, with the blocks they require, and
+   * the conventions it sets (`casing`, `sql.api`, `integrations`); the keys you
+   * set win.
+   */
+  readonly preset?: PresetName | (string & {});
+  /**
+   * The blocks to install and keep in sync (`better-supabase add`): a list of
+   * names, or an object keyed by block name whose values set each block's mode,
+   * schema, table and column names, permission keys and options. The foundation
+   * blocks (`tenant`, `access`, `updated-at`, `ensure-rls`, ...) are configured
+   * here too.
+   */
+  readonly blocks?: readonly string[] | BlocksConfig;
+  /**
+   * Tables the app owns, keyed by name, created in `public` by `better-supabase
+   * sql sync` with an `id`, the scope column, timestamps, row level security
+   * and policies for the scope. Columns reference each other, `auth.users` or a
+   * block's logical table. ADR 0040.
+   */
+  readonly appTables?: AppTablesConfig;
+  /**
+   * SQL-wide settings: the workflow, paths, and the `schema` and `api` every
+   * block inherits.
+   */
+  readonly sql?: SqlConfig;
+  readonly seed?: SeedConfig;
+  /** @deprecated Use `specs`; `openapi.entry` and `openapi.output` map onto it. */
+  readonly openapi?: OpenApiConfig;
+  /**
+   * The documents `better-supabase spec emit` writes (OpenAPI, AsyncAPI,
+   * Arazzo).
+   */
+  readonly specs?: SpecsConfig;
+  readonly doctor?: DoctorConfig;
+  /** What `better-supabase gen` runs. */
+  readonly gen?: GenConfig;
+  readonly env?: EnvFileConfig;
+  readonly scaffold?: ScaffoldConfig;
+  /**
+   * The integrations `init` and `add` wrote; `add` without a name sets up the
+   * ones that have no files yet.
+   */
+  readonly integrations?: readonly IntegrationName[];
+  readonly skills?: SkillsConfig;
+  readonly keys?: KeysConfig;
+  /**
+   * Overrides per environment, keyed by name. The CLI applies the block for
+   * `--env <name>`, else `$BETTER_SUPABASE_ENV`, else `ci` when `$CI` is set.
+   * Objects merge into the config; arrays and other values replace.
+   */
+  readonly $env?: Readonly<Record<string, EnvironmentConfig>>;
+  /** Shorthand for `$env.development`. */
+  readonly $development?: EnvironmentConfig;
+  /** Shorthand for `$env.production`. */
+  readonly $production?: EnvironmentConfig;
+  /** Shorthand for `$env.test`. */
+  readonly $test?: EnvironmentConfig;
+  /** Shorthand for `$env.ci`, which the CLI picks when `$CI` is set. */
+  readonly $ci?: EnvironmentConfig;
+}
+/** The keys an environment block may override. */
+type EnvironmentConfig = Omit<BetterSupabaseConfig, "$schema" | "$env" | "$development" | "$production" | "$test" | "$ci" | "preset">;
+/** The config with defaults applied. */
+interface ResolvedConfig {
+  readonly root: string;
+  readonly source: SourceConfig;
+  readonly schemas: readonly string[];
+  readonly casing: Casing;
+  readonly tables: Readonly<Record<string, TableConfig>>;
+  readonly output: string;
+  /** `database.types.ts` next to `output`. */
+  readonly databaseTypesOutput: string;
+  readonly postgrestVersion: string;
+  readonly generateFeatures: boolean;
+  readonly json: Readonly<Record<string, JsonTypeConfig>>;
+  readonly codecs: Required<CodecsConfig>;
+  readonly relations: Required<RelationsConfig>;
+  readonly sensitive: readonly string[];
+  readonly storagePaths: Readonly<Record<string, string>>;
+  readonly functions: Readonly<Record<string, FunctionConfig>>;
+  /** The table entries of `expose`. */
+  readonly expose: Readonly<Record<string, ResolvedExpose>>;
+  /** The function entries of `expose`: the roles that may execute each one. */
+  readonly exposeFunctions: Readonly<Record<string, readonly ExposeRole[]>>;
+  readonly readSets: readonly string[];
+  readonly generators: readonly Generator[];
+  readonly plugins: {
+    readonly timestamps: Required<TimestampsConfig> | undefined;
+    readonly softDelete: Required<SoftDeleteConfig> | undefined;
+    readonly tenant: Required<TenantConfig> | undefined;
+    readonly actor: Required<ActorConfig> | undefined;
+  };
+  readonly claims: Required<ClaimsConfig>;
+  readonly buckets: Readonly<Record<string, BucketConfig>>;
+  readonly entitlements: {
+    /** Unset without `entitlements.customer`. */
+    readonly table?: string;
+    readonly column?: string;
+    readonly key: string;
+    readonly memberships: "tenant" | "provider";
+    readonly source: NonNullable<EntitlementsConfig["source"]>;
+    readonly claim?: NonNullable<EntitlementsConfig["claim"]>;
+  };
+  readonly authorization?: AuthorizationProvider;
+  readonly vectorSearch: readonly ({
+    readonly table: string;
+    readonly column: string;
+    readonly distance: VectorDistance;
+  } & Omit<Exclude<VectorSearchConfig, string>, "column" | "distance">)[];
+  readonly subjects: SubjectsConfig;
+  readonly topics: Readonly<Record<string, string>>;
+  readonly realtime: Required<Omit<RealtimeConfig, "policies">> & {
+    readonly policies?: TopicPoliciesConfig;
+  };
+  /**
+   * The `preset` the config started from, as written; `blocks` already holds it
+   * expanded.
+   */
+  readonly preset?: string;
+  /** `blocks` with `sql.schema` and `sql.api` applied, keyed by block name. */
+  readonly blocks: AnyBlocksConfig;
+  /** The installed blocks, in config order. */
+  readonly blockNames: readonly string[];
+  /** `appTables`, checked; empty without any. */
+  readonly appTables: AppTablesConfig;
+  readonly sql: ResolvedSqlConfig;
+  readonly seed: Required<SeedConfig>;
+  readonly openapi: Required<OpenApiConfig>;
+  readonly specs: {
+    readonly entry: string;
+    readonly outputs: readonly SpecOutputConfig[];
+    readonly failOn: NonNullable<SpecsConfig["failOn"]>;
+    readonly manifest?: string;
+  };
+  readonly doctor: Required<Omit<DoctorConfig, "claimsLimit" | "output" | "migrationSafety">> & Pick<DoctorConfig, "claimsLimit" | "output" | "migrationSafety">;
+  /**
+   * `tasks` stays unset without a list, so `gen` picks the steps the project
+   * uses.
+   */
+  readonly gen: GenConfig;
+  readonly env: {
+    readonly output: string;
+    readonly prefix?: string;
+  };
+  readonly scaffold: ScaffoldConfig;
+  readonly integrations: readonly IntegrationName[];
+  readonly skills: SkillsConfig;
+  readonly keys: KeysConfig;
+  /** The environment block the CLI applied, when one was active. */
+  readonly environment?: string;
+}
+//#endregion
+//#region src/config/types/codegen.d.ts
+/**
+ * Where codegen reads the database from. Without any of these, `$DATABASE_URL`,
+ * `$SUPABASE_DB_URL` and then the local stack (`supabase start`) are used.
+ */
+interface SourceConfig {
+  /** Postgres connection string. */
+  readonly dbUrl?: string;
+  /**
+   * Hosted project ref. Read through the Management API's read-only SQL
+   * endpoint, so no database password is needed.
+   */
+  readonly projectRef?: string;
+  /**
+   * Management API token for `projectRef`. Defaults to
+   * `$SUPABASE_ACCESS_TOKEN`; prefer the env var over committing a token.
+   */
+  readonly accessToken?: string;
+  /** Read a saved `better-supabase introspect` snapshot instead of connecting. */
+  readonly snapshot?: string;
+  /**
+   * Read a Supabase Lite project's schema the way Lite runs it, from `[db]
+   * driver` in `supabase/config.toml`. On by default when that key is present;
+   * `false` reads the database like any other project.
+   */
+  readonly lite?: boolean;
+}
+/**
+ * A JSON Schema object, or a Standard JSON Schema value (zod 4, valibot,
+ * arktype, ...) that can produce one.
+ */
+type JsonSchemaSource = Readonly<Record<string, unknown>> | {
+  readonly "~standard": {
+    readonly jsonSchema: {
+      readonly input: (options: {
+        readonly target: string;
+      }) => Record<string, unknown>;
+    };
+  };
+};
+type JsonTypeConfig = ({
+  readonly import: string;
+} | {
+  readonly type: string;
+}) & {
+  /**
+   * Enforced in the database by `better-supabase add jsonb-schemas`
+   * (pg_jsonschema).
+   */
+  readonly schema?: JsonSchemaSource;
+};
+interface TableConfig {
+  readonly casing?: Casing;
+  /** Leave the table out of the generated models. */
+  readonly exclude?: boolean;
+  /**
+   * Keep the table off the Data API on purpose: only `service_role` reaches it.
+   * The models are still generated for admin clients, and doctor (BS106) checks
+   * that `anon` and `authenticated` have no grants instead of requiring them.
+   */
+  readonly serviceRole?: boolean;
+  /** Rename generated relations: `{ primaryContact: 'contact' }`. */
+  readonly relations?: Readonly<Record<string, string>>;
+  /**
+   * Database names of not-null columns an insert may leave out because the
+   * database fills them, for example from a `before insert` trigger. `gen`
+   * makes them optional in `InsertOf` and the insert validators.
+   */
+  readonly insertOptional?: readonly string[];
+}
+interface FunctionConfig {
+  /**
+   * `true`, or the `returns table` columns (database names) that are never
+   * null.
+   */
+  readonly notNull?: true | readonly string[];
+}
+interface TimestampsConfig {
+  readonly createdAt?: string;
+  readonly updatedAt?: string;
+}
+interface SoftDeleteConfig {
+  readonly column?: string;
+}
+interface TenantConfig {
+  /**
+   * Defaults to `organization_id`, or
+   * `<blocks.tenant.entities.organization>_id` when the tenant is renamed.
+   */
+  readonly column?: string;
+}
+/** Claim names shared by the SQL modules, codegen and the runtime defaults. */
+interface ClaimsConfig {
+  /** Top-level claim holding the active tenant id. Defaults to `tenant_id`. */
+  readonly tenant?: string;
+  /**
+   * `scope` of the tenant entries `membership_claims()` writes. Defaults to
+   * `tenant`.
+   */
+  readonly scope?: string;
+  /**
+   * Claim holding plan features per tenant (`{ [tenantId]: string[] }`).
+   * Defaults to `features`.
+   */
+  readonly features?: string;
+  /**
+   * Claim the memberships hook (`membership_claims()` or the provider's)
+   * writes. Defaults to `memberships`.
+   */
+  readonly memberships?: string;
+}
+interface ActorConfig {
+  readonly createdBy?: string;
+  readonly updatedBy?: string;
+  /**
+   * Defaults to `impersonated_by`, the column the SQL modules' `track_actor`
+   * fills.
+   */
+  readonly impersonatedBy?: string;
+}
+interface PluginFlagsConfig {
+  readonly timestamps?: boolean | TimestampsConfig;
+  readonly softDelete?: boolean | SoftDeleteConfig;
+  readonly tenant?: boolean | TenantConfig;
+  readonly actor?: boolean | ActorConfig;
+}
+/**
+ * Runtime types for columns whose JSON form loses information. Defaults match
+ * `supabase gen types`: timestamps as ISO strings, `int8` and `numeric` as
+ * numbers.
+ */
+interface CodecsConfig {
+  /**
+   * `'instant'` decodes `timestamptz` columns to `Temporal.Instant` and
+   * `timestamp` columns to `Temporal.PlainDateTime`. `'utc'` keeps
+   * `timestamptz` columns as strings, always in UTC as ISO 8601 with a `Z` and
+   * every fraction digit (`2026-10-21T05:10:00.123456Z`).
+   */
+  readonly timestamptz?: "string" | "instant" | "utc";
+  /** `'bigint'` or `'string'` read `int8` exactly (above 2^53). */
+  readonly int8?: "number" | "string" | "bigint";
+  /** `'string'` reads `numeric` exactly. */
+  readonly numeric?: "number" | "string";
+}
+interface GeneratedFile {
+  /** Path relative to the project root. */
+  readonly path: string;
+  readonly contents: string;
+}
+interface GeneratorInput {
+  readonly meta: SchemaMeta;
+  /**
+   * The `@supabase/postgrest-typegen` metadata for the configured schemas, the
+   * same contract `supabase gen types` is built on.
+   */
+  readonly introspection: GeneratorMetadata;
+  /** Constraints, indexes, policies, triggers and grants typegen leaves out. */
+  readonly extras: SnapshotExtras;
+  readonly config: ResolvedConfig;
+  /** Absolute path of the main generated module. */
+  readonly output: string;
+  /** Import path from `from` (a generated file) to `to`, with extension. */
+  readonly importPath: (from: string, to: string) => string;
+  /**
+   * Where generated files import `better-supabase` runtime helpers from.
+   * Defaults to `better-supabase`.
+   */
+  readonly runtimeImport?: string;
+  /**
+   * The tables and enums `gen` emits, with the TypeScript type it wrote for
+   * each column (after `json` overrides, codecs and enum unions). Frozen.
+   */
+  readonly model: GeneratorModel;
+}
+interface GeneratorColumn {
+  /** Name in rows, after casing. */
+  readonly app: string;
+  /** Database name. */
+  readonly db: string;
+  /** TypeScript type without `| null`. */
+  readonly tsType: string;
+  readonly nullable: boolean;
+  /** Optional on insert. */
+  readonly optional: boolean;
+  /** Generated or identity always: never written. */
+  readonly readonly: boolean;
+  /** Enum or check-constraint values, when the column has a closed set. */
+  readonly values: readonly string[] | undefined;
+  readonly json: boolean;
+}
+interface GeneratorTable {
+  /** Key in `schema.tables` and on the client. */
+  readonly key: string;
+  readonly schema: string;
+  readonly name: string;
+  readonly casing: Casing;
+  readonly columns: readonly GeneratorColumn[];
+}
+interface GeneratorFunctionArg {
+  readonly name: string;
+  /** TypeScript type, as `$rpc` takes it. */
+  readonly tsType: string;
+  /** Has a default, so callers may leave it out. */
+  readonly optional: boolean;
+  /** Enum values, when the argument is an enum (or an array of one). */
+  readonly values: readonly string[] | undefined;
+}
+/** A function `$rpc` calls, with the types `gen` wrote for it. */
+interface GeneratorFunction {
+  /** Name on `$rpc`. */
+  readonly key: string;
+  readonly schema: string;
+  readonly args: readonly GeneratorFunctionArg[];
+  /** TypeScript type of the result, as `$rpc` returns it. */
+  readonly returns: string;
+  readonly returnsSet: boolean;
+  readonly volatility: "immutable" | "stable" | "volatile";
+}
+/** JSON Schema (draft 2020-12) for one value. */
+type GeneratorJsonSchema = Readonly<Record<string, unknown>>;
+/**
+ * One field of a block input schema: its scalar kind with the flags and bounds
+ * `entitySchema` takes. It never carries a nested `schema`.
+ */
+type GeneratorField = FieldSpec;
+/** One of a block's input schemas, in the block's default names. */
+interface GeneratorInputSchema {
+  /** The type it validates (`WorkItemInput`). */
+  readonly title: string;
+  readonly fields: Readonly<Record<string, GeneratorField>>;
+  /** The same schema as JSON Schema (draft 2020-12), in its wire form. */
+  readonly jsonSchema: GeneratorJsonSchema;
+}
+/**
+ * The inputs a block's client takes for one entity. Each is absent when the
+ * block declares none.
+ */
+interface GeneratorEntitySchemas {
+  /** What creating one takes (`WorkItemInput`). */
+  readonly input?: GeneratorInputSchema;
+  /** What updating one takes (`WorkItemChange`). */
+  readonly change?: GeneratorInputSchema;
+  /** What listing them takes (`WorkItemListOptions`). */
+  readonly listFilter?: GeneratorInputSchema;
+}
+interface GeneratorNoun {
+  readonly singular: string;
+  readonly plural: string;
+}
+/** One of an installed block's entities, under the name the config gives it. */
+interface GeneratorBlockEntity {
+  /** The entity's key in the block's manifest: its default singular noun. */
+  readonly key: string;
+  /** The block's own noun (`work_item`). */
+  readonly from: GeneratorNoun;
+  /** The noun `blocks.<name>.entities` gives it (`task`). */
+  readonly to: GeneratorNoun;
+  readonly primary: boolean;
+  /** The table that holds it, as the SQL names it; undefined when none. */
+  readonly table: string | undefined;
+  /** `blocks.<name>.entities.<entity>.url`, with column placeholders. */
+  readonly url: string | undefined;
+  readonly schemas: GeneratorEntitySchemas;
+}
+/** An installed block, with its final names. */
+interface GeneratorBlock {
+  readonly name: string;
+  /** The schema its tables and functions live in. */
+  readonly schema: string;
+  /**
+   * The block's client in `blocks.generated.ts` (`tasksBlock`) and the subpath
+   * its default export comes from, or undefined for blocks with only SQL.
+   */
+  readonly client: {
+    readonly export: string;
+    readonly subpath: string;
+  } | undefined;
+  readonly entities: readonly GeneratorBlockEntity[];
+}
+interface GeneratorModel {
+  readonly tables: readonly GeneratorTable[];
+  readonly enums: readonly {
+    readonly schema: string;
+    readonly name: string;
+    readonly values: readonly string[];
+  }[];
+  /** The functions `$rpc` calls, one entry per overload. */
+  readonly functions: readonly GeneratorFunction[];
+  /** The installed blocks, in config order. */
+  readonly blocks: readonly GeneratorBlock[];
+}
+/**
+ * Codegen extension point. First-party generators: `zod()`, `valibot()`,
+ * `jsonSchema()`, `standardSchema()`. Prove custom ones with `testGenerator`.
+ */
+interface Generator {
+  /** The generator contract it targets. `gen` refuses versions it doesn't know. */
+  readonly apiVersion?: 1;
+  readonly name: string;
+  generate(input: GeneratorInput): readonly GeneratedFile[] | Promise<readonly GeneratedFile[]>;
+}
+interface RelationsConfig {
+  /**
+   * Type a to-one include as `| null` when the related table has row level
+   * security, even over a `not null` foreign key, since a policy can hide the
+   * related row. `required: true` on the include keeps it non-null. Defaults to
+   * `false`.
+   */
+  readonly nullableUnderRls?: boolean;
+}
+//#endregion
+//#region src/preset/catalog-types.d.ts
+/** One SQL module in the preset catalog: a key of `blocks` in the config. */
+interface PresetCatalogBlock {
+  readonly name: string;
+  readonly title: string;
+  readonly category: BlockCategory;
+  /** The modules it needs with the default options. */
+  readonly requires: readonly string[];
+  /** What it needs instead under an access model, where that differs. */
+  readonly requiresByAccess?: Partial<Readonly<Record<PresetAccess, readonly string[]>>>;
+  /** The scopes it runs in; unset, every scope. */
+  readonly scopes?: readonly PresetScope[];
+  /** Tenant names that would rename a table or column to a name it already uses. */
+  readonly tenantNameClashes?: readonly PresetTenantName[];
+  /**
+   * The logical table `options.extraColumns` adds columns to, when it takes
+   * them.
+   */
+  readonly extraColumns?: string;
+  /**
+   * The nouns `blocks.<name>.entities` renames, with what config resolution
+   * needs to name them and register their subjects.
+   */
+  readonly entities?: PresetCatalogEntities;
+  /** Modules it works with when installed; `*` is every module. */
+  readonly integrates: readonly string[];
+  /** The manifest that installs it, a key of `manifests`. */
+  readonly manifest: string;
+}
+/** A block's entities as the catalog carries them. */
+interface PresetCatalogEntities {
+  readonly specs: Readonly<Record<string, ModuleEntitySpec>>;
+  /** The tables that hold them, with their default names and columns. */
+  readonly tables: Readonly<Record<string, Pick<ModuleTableSpec, "name" | "columns">>>;
+  /** The default permission key of each module action. */
+  readonly keys: Readonly<Record<string, string>>;
+}
+/** One block manifest (ADR 0029): what `lib/blocks.ts` wires. */
+interface PresetCatalogManifest {
+  readonly name: string;
+  /** The SQL modules it installs. */
+  readonly sql: readonly string[];
+  readonly category: BlockCategory;
+  /** Its export and subpath, when it has a TypeScript client. */
+  readonly client: {
+    readonly export: string;
+    readonly subpath: string;
+  } | null;
+  readonly consumes: Partial<Readonly<Record<PortName, "optional" | "required">>>;
+  readonly provides: readonly PortName[];
+  /**
+   * The types its subpath exports that carry one of its entities' names, which
+   * `gen` aliases under the renamed names.
+   */
+  readonly entityTypes?: readonly PresetCatalogEntityType[];
+  /**
+   * JSON Schemas of the inputs its client takes, by entity key, from the
+   * Standard Schemas the block exports.
+   */
+  readonly entitySchemas?: Readonly<Record<string, PresetCatalogEntitySchemas>>;
+  /**
+   * The block's events: the event map type its subpath exports and the event
+   * types, in its default names.
+   */
+  readonly events?: {
+    readonly type: string;
+    readonly types: readonly string[];
+  };
+  /**
+   * The record sections its client adds (`block.sections`) with each one's
+   * write names, which `gen` puts on each subject's record feature.
+   */
+  readonly sections?: Readonly<Record<string, readonly string[]>>;
+}
+/** One entity's input schemas, in the block's default names. */
+interface PresetCatalogEntitySchemas {
+  readonly input?: PresetCatalogInputSchema;
+  readonly change?: PresetCatalogInputSchema;
+  readonly listFilter?: PresetCatalogInputSchema;
+}
+/** One input schema: its fields as `entitySchema` takes them, and JSON Schema. */
+interface PresetCatalogInputSchema {
+  readonly title: string;
+  readonly fields: Readonly<Record<string, FieldSpec>>;
+  readonly jsonSchema: Readonly<Record<string, unknown>>;
+}
+/** A block type named after one of its entities, such as `WorkItem`. */
+interface PresetCatalogEntityType {
+  readonly name: string;
+  /** Takes the extra columns as its first type parameter, `F`. */
+  readonly fields?: true;
+}
+/**
+ * One item of the `@better-supabase` shadcn registry: glue the app copies (`npx
+ * shadcn add @better-supabase/<name>`), for some blocks, frameworks and
+ * platforms.
+ */
+interface PresetGlueItem {
+  readonly name: string;
+  readonly title: string;
+  /** The SQL modules the item needs. */
+  readonly blocks: readonly string[];
+  readonly frameworks: readonly string[];
+  readonly platforms: readonly ("web" | "native")[];
+  /** Where its files go, as shadcn targets (`@lib/blocks.ts`, `~/app/...`). */
+  readonly targets: readonly string[];
+  /** The named preset a bundle item (`registry:item`) installs the glue of. */
+  readonly preset?: string;
+}
+/** What `scripts/build-catalog.ts` writes to `catalog.generated.ts`. */
+interface PresetCatalog {
+  readonly blocks: readonly PresetCatalogBlock[];
+  readonly manifests: readonly PresetCatalogManifest[];
+  readonly glue: readonly PresetGlueItem[];
+}
+//#endregion
+//#region src/preset/resolve.d.ts
+/** One block in a resolved preset, with why it is there. */
+interface ResolvedPresetBlock {
+  readonly name: string;
+  readonly title: string;
+  readonly category: BlockCategory;
+  /** Whether the preset names it, rather than another block requiring it. */
+  readonly selected: boolean;
+  /** The blocks in the set that require it. */
+  readonly requiredBy: readonly string[];
+  /** "selected", or "required by comments and tags". */
+  readonly reason: string;
+}
+/** A soft integration between two blocks that are both in the set. */
+interface PresetIntegration {
+  /** The block that works with `to`. */
+  readonly from: string;
+  readonly to: string;
+}
+/** Something in the preset that can't install, and why. */
+interface PresetConflict {
+  readonly block?: string;
+  readonly field?: PresetFieldKey;
+  readonly reason: string;
+}
+/** What `resolvePreset` returns. */
+interface ResolvedPreset {
+  readonly preset: Preset;
+  /** Every block to install, in install order; conflicting blocks are left out. */
+  readonly blocks: readonly ResolvedPresetBlock[];
+  /** The soft integrations active between blocks in the set. */
+  readonly integrations: readonly PresetIntegration[];
+  readonly conflicts: readonly PresetConflict[];
+  /** The manifests that cover `blocks`, for `lib/blocks.ts`. */
+  readonly manifests: readonly PresetCatalogManifest[];
+}
+/** "a", "a and b", "a, b and c". */
+declare function listNames(names: readonly string[]): string;
+/**
+ * Why `name` can't install with the preset's conventions, or undefined.
+ * `/create` disables a block with this reason before it is selected.
+ */
+declare function presetBlockConflict(preset: Pick<Preset, "access" | "scope">, name: string, catalog?: PresetCatalog): string | undefined;
+/**
+ * The full block set for a preset: the selected blocks and what they require, a
+ * reason per block, the soft integrations active between them, and what can't
+ * install. It reads the generated catalog, never the SQL renderers, so it runs
+ * in the browser.
+ */
+declare function resolvePreset(preset: Preset, catalog?: PresetCatalog): ResolvedPreset;
+//#endregion
+//#region src/preset/config.d.ts
+/** A named preset, a code, a `/create?preset=` URL, or a preset object. */
+type PresetInput = string | (Partial<Preset> & {
+  readonly blocks?: readonly string[];
+});
+/** Reads a named preset, a code or a `/create?preset=` URL into a `Preset`. */
+declare function presetOf(input: PresetInput): Preset;
+/**
+ * The conventions that map onto config keys; `tenantName` takes any name
+ * `blocks.tenant.entities.organization` allows.
+ */
+type ConfigConventions = Pick<Preset, "casing" | "idType" | "scope" | "access" | "api"> & {
+  readonly tenantName: string;
+};
+/**
+ * The config keys conventions set without a preset: `casing`, `sql`,
+ * `blocks.access` when the access model or id type differ from the defaults,
+ * and `blocks.tenant` when the tenant has another name.
+ */
+declare function conventionConfig(conventions: ConfigConventions): Pick<BetterSupabaseConfig, "casing" | "sql"> & {
+  readonly blocks?: {
+    readonly access?: AccessBlockConfig;
+    readonly tenant?: BlockConfig;
+  };
+};
+/**
+ * The config keys a resolved preset sets: its blocks and the conventions that
+ * differ from the defaults.
+ */
+declare function presetConfig(resolved: ResolvedPreset): Pick<BetterSupabaseConfig, "casing" | "sql" | "integrations"> & {
+  readonly blocks: BlocksConfig;
+};
+/**
+ * A literal config after `expandPreset`: the same type without a preset, and
+ * with one, every key but `blocks` and `sql` as written, those two merged with
+ * the preset's.
+ */
+type ExpandedConfig<C extends BetterSupabaseConfig> = C extends {
+  readonly preset: NonNullable<BetterSupabaseConfig["preset"]>;
+} ? Omit<C, "blocks" | "sql"> & Pick<BetterSupabaseConfig, "blocks" | "sql"> : C;
+/**
+ * `config` with its `preset` expanded: the preset's blocks (and what they
+ * require) and conventions first, then the config's own keys over them, so
+ * explicit config wins. A block in both keeps the preset's settings that the
+ * config's entry leaves unset. Expanding twice gives the same config.
+ */
+declare function expandPreset<const C extends BetterSupabaseConfig>(config: C): ExpandedConfig<C>;
+//#endregion
+export { ResolvedSqlConfig as $, RpcFunction as $n, PRESET_VERSION as $t, GeneratorFunctionArg as A, CatalogEnum as An, AppTableVersions as At, RelationsConfig as B, ExtrasDomain as Bn, PRESETS as Bt, Generator as C, ScaffoldConfig as Cn, AppReferenceTarget as Ct, GeneratorEntitySchemas as D, CatalogCheck as Dn, AppTableEventKind as Dt, GeneratorColumn as E, Catalog as En, AppTableConfig as Et, GeneratorNoun as F, CatalogIndex as Fn, ExposeRole as Ft, TimestampsConfig as G, ForeignKeyAction as Gn, defaultPreset as Gt, SourceConfig as H, ExtrasHook as Hn, PRESET_NAMES as Ht, GeneratorTable as I, CatalogPolicy as In, Privilege as It, ResolvedConfig as J, SnapshotExtras as Jn, namedPreset as Jt, BetterSupabaseConfig as K, Snapshot as Kn, defaultPresetCode as Kt, JsonSchemaSource as L, CatalogTable as Ln, ResolvedExpose as Lt, GeneratorInputSchema as M, CatalogFunction as Mn, ColumnPrivilege as Mt, GeneratorJsonSchema as N, CatalogFunctionArg as Nn, ExposeConfig as Nt, GeneratorField as O, CatalogColumn as On, AppTableEvents as Ot, GeneratorModel as P, CatalogGrant as Pn, ExposePrivilege as Pt, RealtimeConfig as Q, PostgresFunctionArg as Qn, PRESET_TENANT_NAMES as Qt, JsonTypeConfig as R, CatalogTrigger as Rn, DEFAULT_PRESET_NAME as Rt, GeneratedFile as S, ScaffoldApiConfig as Sn, AppReference as St, GeneratorBlockEntity as T, SkillsConfig as Tn, AppRollupConfig as Tt, TableConfig as U, ExtrasHookFunction as Un, PresetGroup as Ut, SoftDeleteConfig as V, ExtrasFunction as Vn, PRESET_GROUPS as Vt, TenantConfig as W, ExtrasTable as Wn, PresetName as Wt, EntitlementsConfig as X, PostgresColumn as Xn, PRESET_FIELDS as Xt, EntitlementPlansSource as Y, GeneratorMetadata as Yn, DEFAULT_CONVENTIONS as Yt, BucketConfig as Z, PostgresFunction as Zn, PRESET_FRAMEWORKS as Zt, PresetCatalogManifest as _, GenTask as _n, AppColumnConfig as _t, expandPreset as a, PresetFieldKey as an, GEN_TASKS as ar, TopicTriggerPayloadValueConfig as at, ClaimsConfig as b, MigrationSafetyConfig as bn, AppLookupConfig as bt, PresetConflict as c, PresetPlatforms as cn, IntegrationInfo as cr, VectorDistance as ct, ResolvedPresetBlock as d, integrationsForFramework as dn, APP_COLUMN_FORMATS as dt, Preset as en, RpcFunctionArg as er, SeedConfig as et, listNames as f, presetField as fn, APP_COLUMN_TYPES as ft, PresetCatalogBlock as g, GenConfig as gn, AppColumnAccess as gt, PresetCatalog as h, EnvFileConfig as hn, APP_TABLE_EVENT_KINDS as ht, conventionConfig as i, PresetField as in, RpcTypeReference as ir, TopicTriggerLookupConfig as it, GeneratorInput as j, CatalogForeignKey as jn, AppTablesConfig as jt, GeneratorFunction as k, CatalogColumnGrant as kn, AppTableSubject as kt, PresetIntegration as l, PresetScope as ln, SKILLS_AGENTS as lr, VectorSearchConfig as lt, resolvePreset as m, DoctorConfig as mn, APP_ROLLUP_AGGREGATES as mt, ExpandedConfig as n, PresetCodeField as nn, RpcFunctionReturns as nr, SqlWorkflow as nt, presetConfig as o, PresetFieldValue as on, INTEGRATION_INFO as or, TopicTriggerTopicConfig as ot, presetBlockConflict as p, presetValueLabel as pn, APP_ON_DELETE_ACTIONS as pt, EnvironmentConfig as q, SnapshotBucket as qn, isPresetName as qt, PresetInput as r, PresetConventions as rn, RpcReturnColumn as rr, TopicTriggerConfig as rt, presetOf as s, PresetFramework as sn, INTEGRATION_NAMES as sr, TopicTriggerValueConfig as st, ConfigConventions as t, PresetAccess as tn, RpcFunctionOverload as tr, SqlConfig as tt, ResolvedPreset as u, PresetValueInfo as un, APP_COLUMN_ACCESS as ut, PresetGlueItem as v, IntegrationName as vn, AppColumnFormat as vt, GeneratorBlock as w, SkillsAgent as wn, AppRollupAggregate as wt, CodecsConfig as x, OpenApiConfig as xn, AppOnDeleteAction as xt, ActorConfig as y, KeysConfig as yn, AppColumnType as yt, PluginFlagsConfig as z, CatalogUnique as zn, NamedPreset as zt };