@vertz/db 0.2.0 → 0.2.1

package/dist/index.d.ts

@@ -38,6 +38,28 @@ declare function formatDiagnostic(diag: DiagnosticResult): string;
 * @returns Formatted diagnostic string, or a fallback message
 */
 declare function explainError(message: string): string;
+/**
+* Database driver interface.
+*
+* Provides a unified interface for different database backends
+* (PostgreSQL, SQLite/D1, etc.) with query and execute methods.
+*/
+interface DbDriver {
+	/**
+	* Execute a read query and return results.
+	*/
+	query<T = unknown>(sql: string, params?: unknown[]): Promise<T[]>;
+	/**
+	* Execute a write query and return affected row count.
+	*/
+	execute(sql: string, params?: unknown[]): Promise<{
+		rowsAffected: number;
+	}>;
+	/**
+	* Close the database connection.
+	*/
+	close(): Promise<void>;
+}
 interface JsonbValidator<T> {
 	parse(value: unknown): T;
 }
@@ -47,8 +69,9 @@ interface ColumnMetadata {
 	readonly unique: boolean;
 	readonly nullable: boolean;
 	readonly hasDefault: boolean;
-	readonly sensitive: boolean;
-	readonly hidden: boolean;
+	readonly _annotations: Record<string, true>;
+	readonly isReadOnly: boolean;
+	readonly isAutoUpdate: boolean;
 	readonly isTenant: boolean;
 	readonly references: {
 		readonly table: string;
@@ -63,6 +86,7 @@ interface ColumnMetadata {
 	readonly enumName?: string;
 	readonly enumValues?: readonly string[];
 	readonly validator?: JsonbValidator<unknown>;
+	readonly generate?: "cuid" | "uuid" | "nanoid";
 }
 /** Phantom symbol to carry the TypeScript type without a runtime value. */
 declare const PhantomType: unique symbol;
@@ -73,9 +97,12 @@ interface ColumnBuilder<
 	/** Phantom field -- only exists at the type level for inference. Do not access at runtime. */
 	readonly [PhantomType]: TType;
 	readonly _meta: TMeta;
-	primary(): ColumnBuilder<TType, Omit<TMeta, "primary" | "hasDefault"> & {
+	primary(options?: {
+		generate?: "cuid" | "uuid" | "nanoid";
+	}): ColumnBuilder<TType, Omit<TMeta, "primary" | "hasDefault" | "generate"> & {
 		readonly primary: true;
 		readonly hasDefault: true;
+		readonly generate?: "cuid" | "uuid" | "nanoid";
 	}>;
 	unique(): ColumnBuilder<TType, Omit<TMeta, "unique"> & {
 		readonly unique: true;
@@ -87,11 +114,15 @@ interface ColumnBuilder<
 		readonly hasDefault: true;
 		readonly defaultValue: TType | "now";
 	}>;
-	sensitive(): ColumnBuilder<TType, Omit<TMeta, "sensitive"> & {
-		readonly sensitive: true;
+	is<TFlag extends string>(flag: TFlag): ColumnBuilder<TType, Omit<TMeta, "_annotations"> & {
+		readonly _annotations: TMeta["_annotations"] & { readonly [K in TFlag] : true };
 	}>;
-	hidden(): ColumnBuilder<TType, Omit<TMeta, "hidden"> & {
-		readonly hidden: true;
+	readOnly(): ColumnBuilder<TType, Omit<TMeta, "isReadOnly"> & {
+		readonly isReadOnly: true;
+	}>;
+	autoUpdate(): ColumnBuilder<TType, Omit<TMeta, "isAutoUpdate" | "isReadOnly"> & {
+		readonly isAutoUpdate: true;
+		readonly isReadOnly: true;
 	}>;
 	check(sql: string): ColumnBuilder<TType, Omit<TMeta, "check"> & {
 		readonly check: string;
@@ -110,8 +141,9 @@ type DefaultMeta<TSqlType extends string> = {
 	readonly unique: false;
 	readonly nullable: false;
 	readonly hasDefault: false;
-	readonly sensitive: false;
-	readonly hidden: false;
+	readonly _annotations: {};
+	readonly isReadOnly: false;
+	readonly isAutoUpdate: false;
 	readonly isTenant: false;
 	readonly references: null;
 	readonly check: null;
@@ -149,8 +181,9 @@ type SerialMeta = {
 	readonly unique: false;
 	readonly nullable: false;
 	readonly hasDefault: true;
-	readonly sensitive: false;
-	readonly hidden: false;
+	readonly _annotations: {};
+	readonly isReadOnly: false;
+	readonly isAutoUpdate: false;
 	readonly isTenant: false;
 	readonly references: null;
 	readonly check: null;
@@ -161,8 +194,9 @@ type TenantMeta = {
 	readonly unique: false;
 	readonly nullable: false;
 	readonly hasDefault: false;
-	readonly sensitive: false;
-	readonly hidden: false;
+	readonly _annotations: {};
+	readonly isReadOnly: false;
+	readonly isAutoUpdate: false;
 	readonly isTenant: true;
 	readonly references: {
 		readonly table: string;
@@ -189,26 +223,35 @@ interface ManyRelationDef<TTarget extends TableDef<ColumnRecord> = TableDef<Colu
 }
 interface IndexDef {
 	readonly columns: readonly string[];
+	readonly name?: string;
+	readonly unique?: boolean;
 }
 /** A record of column builders -- the shape passed to d.table(). */
 type ColumnRecord = Record<string, ColumnBuilder<unknown, ColumnMetadata>>;
 /** Extract the TypeScript type from every column in a record. */
 type InferColumns<T extends ColumnRecord> = { [K in keyof T] : InferColumnType<T[K]> };
-/** Keys of columns where a given metadata flag is `true`. */
+/** Keys of columns where a given metadata property is `true`. */
 type ColumnKeysWhere<
 	T extends ColumnRecord,
 	Flag extends keyof ColumnMetadata
 > = { [K in keyof T] : T[K] extends ColumnBuilder<unknown, infer M> ? M extends Record<Flag, true> ? K : never : never }[keyof T];
-/** Keys of columns where a given metadata flag is NOT `true` (i.e., false). */
+/** Keys of columns where a given metadata property is NOT `true` (i.e., false). */
 type ColumnKeysWhereNot<
 	T extends ColumnRecord,
 	Flag extends keyof ColumnMetadata
 > = { [K in keyof T] : T[K] extends ColumnBuilder<unknown, infer M> ? M extends Record<Flag, true> ? never : K : never }[keyof T];
+/** Keys of columns that do NOT have ANY of the specified annotations in `_annotations`. */
+type ColumnKeysWithoutAnyAnnotation<
+	T extends ColumnRecord,
+	Annotations extends string
+> = { [K in keyof T] : T[K] extends ColumnBuilder<unknown, infer M> ? M["_annotations"] extends Record<Annotations, true> ? never : K : never }[keyof T];
+/** Extracts the union of all annotation names present across all columns in a record. */
+type AllAnnotations<T extends ColumnRecord> = { [K in keyof T] : T[K] extends ColumnBuilder<unknown, infer M> ? keyof M["_annotations"] & string : never }[keyof T];
 /**
 * $infer -- default SELECT type.
-* Excludes hidden columns. Includes everything else (including sensitive).
+* Excludes columns annotated 'hidden'. Includes everything else.
 */
-type Infer<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "hidden">] : InferColumnType<T[K]> };
+type Infer<T extends ColumnRecord> = { [K in ColumnKeysWithoutAnyAnnotation<T, "hidden">] : InferColumnType<T[K]> };
 /**
 * $infer_all -- all columns including hidden.
 */
@@ -224,21 +267,26 @@ type Insert<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "hasDefault"
 */
 type Update<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "primary">]? : InferColumnType<T[K]> };
 /**
-* $not_sensitive -- excludes columns marked .sensitive() OR .hidden().
-* (hidden implies sensitive for read purposes)
+* $response -- API response shape. Excludes columns annotated 'hidden'.
+*/
+type Response<T extends ColumnRecord> = { [K in ColumnKeysWithoutAnyAnnotation<T, "hidden">] : InferColumnType<T[K]> };
+/**
+* $create_input -- API create input shape.
+* Excludes readOnly and primary key columns.
+* Columns with defaults are optional.
 */
-type NotSensitive<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "sensitive"> & ColumnKeysWhereNot<T, "hidden"> & keyof T] : InferColumnType<T[K]> };
+type ApiCreateInput<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "isReadOnly"> & ColumnKeysWhereNot<T, "primary"> & ColumnKeysWhereNot<T, "hasDefault"> & string] : InferColumnType<T[K]> } & { [K in ColumnKeysWhereNot<T, "isReadOnly"> & ColumnKeysWhereNot<T, "primary"> & ColumnKeysWhere<T, "hasDefault"> & string]? : InferColumnType<T[K]> };
 /**
-* $not_hidden -- excludes columns marked .hidden().
-* Same as $infer (excludes hidden, keeps sensitive).
+* $update_input -- API update input shape.
+* Excludes readOnly and primary key columns. All fields optional (partial update).
 */
-type NotHidden<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "hidden">] : InferColumnType<T[K]> };
+type ApiUpdateInput<T extends ColumnRecord> = { [K in ColumnKeysWhereNot<T, "isReadOnly"> & ColumnKeysWhereNot<T, "primary"> & string]? : InferColumnType<T[K]> };
 interface TableDef<TColumns extends ColumnRecord = ColumnRecord> {
 	readonly _name: string;
 	readonly _columns: TColumns;
 	readonly _indexes: readonly IndexDef[];
 	readonly _shared: boolean;
-	/** Default SELECT type -- excludes hidden columns. */
+	/** Default SELECT type -- excludes columns annotated 'hidden'. */
 	readonly $infer: Infer<TColumns>;
 	/** All columns including hidden. */
 	readonly $infer_all: InferAll<TColumns>;
@@ -246,10 +294,12 @@ interface TableDef<TColumns extends ColumnRecord = ColumnRecord> {
 	readonly $insert: Insert<TColumns>;
 	/** Update type -- all non-PK columns optional. ALL columns included. */
 	readonly $update: Update<TColumns>;
-	/** Excludes sensitive and hidden columns. */
-	readonly $not_sensitive: NotSensitive<TColumns>;
-	/** Excludes hidden columns. */
-	readonly $not_hidden: NotHidden<TColumns>;
+	/** API response shape — excludes columns annotated 'hidden'. */
+	readonly $response: Response<TColumns>;
+	/** API create input — excludes readOnly + PK; defaulted columns optional. */
+	readonly $create_input: ApiCreateInput<TColumns>;
+	/** API update input — excludes readOnly + PK; all fields optional. */
+	readonly $update_input: ApiUpdateInput<TColumns>;
 	/** Mark this table as shared / cross-tenant. */
 	shared(): TableDef<TColumns>;
 }
@@ -257,185 +307,397 @@ interface TableOptions {
 	relations?: Record<string, RelationDef>;
 	indexes?: IndexDef[];
 }
-interface ColumnSnapshot {
-	type: string;
-	nullable: boolean;
-	primary: boolean;
-	unique: boolean;
-	default?: string;
-	sensitive?: boolean;
-	hidden?: boolean;
+/**
+* Database Adapter Types for @vertz/db
+*
+* Generic adapter interface that abstracts database operations.
+* Implemented by SQLite, D1, and other database adapters.
+*/
+interface ListOptions {
+	where?: Record<string, unknown>;
+	orderBy?: Record<string, "asc" | "desc">;
+	limit?: number;
+	/** Cursor-based pagination: fetch records after this ID. */
+	after?: string;
 }
-interface IndexSnapshot {
-	columns: string[];
+interface EntityDbAdapter {
+	get(id: string): Promise<Record<string, unknown> | null>;
+	list(options?: ListOptions): Promise<{
+		data: Record<string, unknown>[];
+		total: number;
+	}>;
+	create(data: Record<string, unknown>): Promise<Record<string, unknown>>;
+	update(id: string, data: Record<string, unknown>): Promise<Record<string, unknown>>;
+	delete(id: string): Promise<Record<string, unknown> | null>;
 }
-interface ForeignKeySnapshot {
-	column: string;
-	targetTable: string;
-	targetColumn: string;
+interface D1DatabaseBinding {
+	prepare(sql: string): D1PreparedStatement;
 }
-interface TableSnapshot {
-	columns: Record<string, ColumnSnapshot>;
-	indexes: IndexSnapshot[];
-	foreignKeys: ForeignKeySnapshot[];
-	_metadata: Record<string, unknown>;
+interface D1PreparedStatement {
+	bind(...values: unknown[]): D1PreparedStatement;
+	all(): Promise<{
+		results: unknown[];
+	}>;
+	run(): Promise<{
+		meta: {
+			changes: number;
+		};
+	}>;
 }
-interface SchemaSnapshot {
-	version: 1;
-	tables: Record<string, TableSnapshot>;
-	enums: Record<string, string[]>;
+interface D1AdapterOptions<T extends ColumnRecord> {
+	/** The table schema definition */
+	schema: TableDef<T>;
+	/** D1 database binding from Cloudflare env */
+	d1: D1DatabaseBinding;
+	/**
+	* Whether migrations should be applied at runtime.
+	* NOTE: For D1, migrations should typically be run via `wrangler d1 migrations apply`
+	* during deployment, not at runtime. Set to false for production use.
+	*/
+	migrations?: {
+		autoApply?: boolean;
+	};
 }
 /**
-* The query function type expected by the migration runner.
+* Create a DbDriver from a D1 database binding.
 */
-type MigrationQueryFn = (sql: string, params: readonly unknown[]) => Promise<{
-	rows: readonly Record<string, unknown>[];
-	rowCount: number;
-}>;
+declare function createD1Driver(d1: D1DatabaseBinding): DbDriver;
 /**
-* Represents a migration file on disk.
+* Create a D1 EntityDbAdapter from a schema and D1 binding.
+*
+* NOTE: For production D1 deployments, migrations should be run via
+* `wrangler d1 migrations apply` during deployment, NOT at runtime.
+* Set `migrations.autoApply = false` or omit the migrations option for production.
 */
-interface MigrationFile {
-	name: string;
-	sql: string;
-	timestamp: number;
+declare function createD1Adapter<T extends ColumnRecord>(options: D1AdapterOptions<T>): EntityDbAdapter;
+import { Result } from "@vertz/schema";
+type IdStrategy = "cuid" | "uuid" | "nanoid";
+declare function generateId(strategy: IdStrategy): string;
+interface Dialect {
+	/** Dialect name. */
+	readonly name: "postgres" | "sqlite";
+	/**
+	* Parameter placeholder: $1, $2 (postgres) or ? (sqlite).
+	* @param index - 1-based parameter index
+	*/
+	param(index: number): string;
+	/** SQL function for current timestamp. */
+	now(): string;
+	/**
+	* Map a vertz column sqlType to the dialect's SQL type.
+	* @param sqlType - The generic sqlType from column metadata
+	* @param meta - Additional metadata (enum values, length, precision)
+	*/
+	mapColumnType(sqlType: string, meta?: ColumnTypeMeta): string;
+	/** Whether the dialect supports RETURNING clause. */
+	readonly supportsReturning: boolean;
+	/** Whether the dialect supports array operators (@>, <@, &&). */
+	readonly supportsArrayOps: boolean;
+	/** Whether the dialect supports JSONB path operators (->>, ->). */
+	readonly supportsJsonbPath: boolean;
+}
+interface ColumnTypeMeta {
+	readonly enumName?: string;
+	readonly enumValues?: readonly string[];
+	readonly length?: number;
+	readonly precision?: number;
+	readonly scale?: number;
 }
 /**
-* Result of applying (or dry-running) a migration.
+* PostgreSQL dialect implementation.
+*
+* Extracted from existing behavior — no functional changes.
 */
-interface ApplyResult {
-	/** The migration name. */
-	name: string;
-	/** The SQL that was (or would be) executed. */
-	sql: string;
-	/** The computed checksum of the migration SQL. */
-	checksum: string;
-	/** Whether this was a dry run. */
-	dryRun: boolean;
-	/** The statements that were (or would be) executed, in order. */
-	statements: string[];
-}
-interface MigrateDeployOptions {
-	queryFn: MigrationQueryFn;
-	migrationFiles: MigrationFile[];
-	/** When true, return the SQL that would be executed without applying. */
-	dryRun?: boolean;
-}
-interface MigrateDeployResult {
-	applied: string[];
-	alreadyApplied: string[];
-	/** When dry-run is enabled, contains the details of each migration that would be applied. */
-	dryRun: boolean;
-	/** Detailed results for each migration that was (or would be) applied. */
-	migrations?: ApplyResult[];
+declare class PostgresDialect implements Dialect {
+	readonly name: "postgres";
+	readonly supportsReturning: true;
+	readonly supportsArrayOps: true;
+	readonly supportsJsonbPath: true;
+	param(index: number): string;
+	now(): string;
+	mapColumnType(sqlType: string, meta?: ColumnTypeMeta): string;
 }
+/** Default Postgres dialect instance. */
+declare const defaultPostgresDialect: PostgresDialect;
 /**
-* Apply all pending migrations in order.
+* SQLite dialect implementation.
 *
-* In dry-run mode, returns the SQL that would be executed without modifying the database.
+* SQLite 3.35+ supports RETURNING clause.
 */
-declare function migrateDeploy(options: MigrateDeployOptions): Promise<MigrateDeployResult>;
-interface RenameSuggestion {
-	table: string;
-	oldColumn: string;
-	newColumn: string;
-	confidence: number;
+declare class SqliteDialect implements Dialect {
+	readonly name: "sqlite";
+	readonly supportsReturning: true;
+	readonly supportsArrayOps: false;
+	readonly supportsJsonbPath: false;
+	param(_index: number): string;
+	now(): string;
+	mapColumnType(sqlType: string, _meta?: ColumnTypeMeta): string;
 }
-interface MigrateDevOptions {
-	queryFn: MigrationQueryFn;
-	currentSnapshot: SchemaSnapshot;
-	previousSnapshot: SchemaSnapshot;
-	migrationName: string;
-	existingFiles: string[];
-	migrationsDir: string;
-	writeFile: (path: string, content: string) => Promise<void>;
-	dryRun: boolean;
+/** Default SQLite dialect instance. */
+declare const defaultSqliteDialect: SqliteDialect;
+interface DbErrorJson {
+	readonly error: string;
+	readonly code: string;
+	readonly message: string;
+	readonly table?: string;
+	readonly column?: string;
 }
-interface MigrateDevResult {
-	migrationFile: string;
-	sql: string;
-	appliedAt?: Date;
-	dryRun: boolean;
-	renames?: RenameSuggestion[];
-	snapshot: SchemaSnapshot;
+declare abstract class DbError extends Error {
+	abstract readonly code: string;
+	/** Raw PostgreSQL SQLSTATE code, if applicable. */
+	readonly pgCode?: string | undefined;
+	readonly table?: string | undefined;
+	readonly query?: string | undefined;
+	constructor(message: string);
+	toJSON(): DbErrorJson;
 }
-/**
-* Generate a migration from schema diff, optionally apply it.
-*
-* In dry-run mode, generates SQL and returns it WITHOUT applying or writing files.
-*/
-declare function migrateDev(options: MigrateDevOptions): Promise<MigrateDevResult>;
-interface PushOptions {
-	queryFn: MigrationQueryFn;
-	currentSnapshot: SchemaSnapshot;
-	previousSnapshot: SchemaSnapshot;
+interface UniqueConstraintErrorOptions {
+	readonly table: string;
+	readonly column: string;
+	readonly value?: string;
+	readonly query?: string;
 }
-interface PushResult {
-	sql: string;
-	tablesAffected: string[];
+declare class UniqueConstraintError extends DbError {
+	readonly code: "UNIQUE_VIOLATION";
+	readonly pgCode: "23505";
+	readonly table: string;
+	readonly query: string | undefined;
+	readonly column: string;
+	readonly value: string | undefined;
+	constructor(options: UniqueConstraintErrorOptions);
+	toJSON(): DbErrorJson;
 }
-/**
-* Push schema changes directly to the database without creating a migration file.
-*/
-declare function push(options: PushOptions): Promise<PushResult>;
-interface MigrateStatusOptions {
-	queryFn: MigrationQueryFn;
-	migrationFiles: MigrationFile[];
+interface ForeignKeyErrorOptions {
+	readonly table: string;
+	readonly constraint: string;
+	readonly detail?: string;
+	readonly query?: string;
 }
-interface MigrationInfo {
-	name: string;
-	checksum: string;
-	appliedAt: Date;
+declare class ForeignKeyError extends DbError {
+	readonly code: "FOREIGN_KEY_VIOLATION";
+	readonly pgCode: "23503";
+	readonly table: string;
+	readonly query: string | undefined;
+	readonly constraint: string;
+	readonly detail: string | undefined;
+	constructor(options: ForeignKeyErrorOptions);
+	toJSON(): DbErrorJson;
 }
-interface MigrateStatusResult {
-	applied: MigrationInfo[];
-	pending: string[];
+interface NotNullErrorOptions {
+	readonly table: string;
+	readonly column: string;
+	readonly query?: string;
 }
-/**
-* Report the status of migrations: which are applied and which are pending.
-*/
-declare function migrateStatus(options: MigrateStatusOptions): Promise<MigrateStatusResult>;
-/**
-* Query executor — wraps raw SQL execution with error mapping.
-*
-* Takes a query function (from the database driver) and wraps it to:
-* 1. Execute parameterized SQL
-* 2. Map PG errors to typed DbError subclasses
-* 3. Return typed QueryResult
-*/
-interface ExecutorResult<T> {
-	readonly rows: readonly T[];
-	readonly rowCount: number;
+declare class NotNullError extends DbError {
+	readonly code: "NOT_NULL_VIOLATION";
+	readonly pgCode: "23502";
+	readonly table: string;
+	readonly query: string | undefined;
+	readonly column: string;
+	constructor(options: NotNullErrorOptions);
+	toJSON(): DbErrorJson;
 }
-type QueryFn = <T>(sql: string, params: readonly unknown[]) => Promise<ExecutorResult<T>>;
-/** Operators available for comparable types (number, string, Date, bigint). */
-interface ComparisonOperators<T> {
-	readonly eq?: T;
-	readonly ne?: T;
-	readonly gt?: T;
-	readonly gte?: T;
-	readonly lt?: T;
-	readonly lte?: T;
-	readonly in?: readonly T[];
-	readonly notIn?: readonly T[];
+interface CheckConstraintErrorOptions {
+	readonly table: string;
+	readonly constraint: string;
+	readonly query?: string;
 }
-/** Additional operators for string columns. */
-interface StringOperators {
-	readonly contains?: string;
-	readonly startsWith?: string;
-	readonly endsWith?: string;
+declare class CheckConstraintError extends DbError {
+	readonly code: "CHECK_VIOLATION";
+	readonly pgCode: "23514";
+	readonly table: string;
+	readonly query: string | undefined;
+	readonly constraint: string;
+	constructor(options: CheckConstraintErrorOptions);
+	toJSON(): DbErrorJson;
 }
-/** The `isNull` operator — only available for nullable columns. */
-interface NullOperator {
-	readonly isNull?: boolean;
+declare class NotFoundError extends DbError {
+	readonly code: "NotFound";
+	readonly table: string;
+	readonly query: string | undefined;
+	constructor(table: string, query?: string);
+	toJSON(): DbErrorJson;
 }
-/**
-* Resolves the filter operators for a single column based on its inferred type
-* and nullable metadata.
-*
-* - All types get comparison + in/notIn
-* - String types additionally get contains, startsWith, endsWith
-* - Nullable columns additionally get isNull
+declare class ConnectionError extends DbError {
+	readonly code: string;
+	constructor(message: string);
+}
+declare class ConnectionPoolExhaustedError extends ConnectionError {
+	readonly code: "POOL_EXHAUSTED";
+	constructor(poolSize: number);
+}
+/**
+* Maps semantic error names to their corresponding PostgreSQL SQLSTATE codes.
+*
+* Usage in switch statements:
+* ```ts
+* switch (error.code) {
+*   case 'UNIQUE_VIOLATION':   // ...
+*   case 'FOREIGN_KEY_VIOLATION': // ...
+* }
+* ```
+*
+* Reverse lookup (semantic name -> PG code):
+* ```ts
+* DbErrorCode.UNIQUE_VIOLATION // '23505'
+* ```
+*/
+declare const DbErrorCode: {
+	readonly UNIQUE_VIOLATION: "23505";
+	readonly FOREIGN_KEY_VIOLATION: "23503";
+	readonly NOT_NULL_VIOLATION: "23502";
+	readonly CHECK_VIOLATION: "23514";
+	readonly EXCLUSION_VIOLATION: "23P01";
+	readonly SERIALIZATION_FAILURE: "40001";
+	readonly DEADLOCK_DETECTED: "40P01";
+	readonly CONNECTION_EXCEPTION: "08000";
+	readonly CONNECTION_DOES_NOT_EXIST: "08003";
+	readonly CONNECTION_FAILURE: "08006";
+	readonly NotFound: "NotFound";
+	readonly CONNECTION_ERROR: "CONNECTION_ERROR";
+	readonly POOL_EXHAUSTED: "POOL_EXHAUSTED";
+};
+/** Union of all semantic error code keys (e.g., `'UNIQUE_VIOLATION' | 'FOREIGN_KEY_VIOLATION' | ...`). */
+type DbErrorCodeName = keyof typeof DbErrorCode;
+/** Union of all raw PG error code values (e.g., `'23505' | '23503' | ...`). */
+type DbErrorCodeValue = (typeof DbErrorCode)[keyof typeof DbErrorCode];
+/**
+* Reverse map: raw PG code -> semantic name.
+* Built at module load time from DbErrorCode.
+*/
+declare const PgCodeToName: Readonly<Record<string, DbErrorCodeName | undefined>>;
+/**
+* Look up the semantic name for a raw PG error code.
+* Returns the key (e.g., `'UNIQUE_VIOLATION'`) or `undefined` if unmapped.
+*/
+declare function resolveErrorCode(pgCode: string): DbErrorCodeName | undefined;
+interface HttpErrorResponse {
+	readonly status: number;
+	readonly body: DbErrorJson;
+}
+/**
+* Maps a DbError to an HTTP error response with the appropriate status code.
+*
+* - UniqueConstraintError  -> 409 Conflict
+* - NotFoundError          -> 404 Not Found
+* - ForeignKeyError        -> 422 Unprocessable Entity
+* - NotNullError           -> 422 Unprocessable Entity
+* - CheckConstraintError   -> 422 Unprocessable Entity
+* - ConnectionError        -> 503 Service Unavailable
+* - Unknown DbError        -> 500 Internal Server Error
+*/
+declare function dbErrorToHttpError(error: DbError): HttpErrorResponse;
+interface PgErrorInput {
+	readonly code: string;
+	readonly message: string;
+	readonly table?: string;
+	readonly column?: string;
+	readonly constraint?: string;
+	readonly detail?: string;
+}
+/**
+* Maps a raw PostgreSQL error object to a typed DbError subclass.
+*
+* Extracts structured metadata (column, constraint, value) from the
+* PG error's `detail` and `message` fields.
+*/
+declare function parsePgError(pgError: PgErrorInput, query?: string): DbError;
+/**
+* Base interface for database errors with code, message, and optional cause.
+*/
+interface DbErrorBase {
+	readonly code: string;
+	readonly message: string;
+	readonly cause?: unknown;
+}
+/**
+* Connection errors - failed to connect or connection lost.
+*/
+interface DbConnectionError extends DbErrorBase {
+	readonly code: "CONNECTION_ERROR";
+}
+/**
+* Query execution errors - SQL syntax, timeout, etc.
+*/
+interface DbQueryError extends DbErrorBase {
+	readonly code: "QUERY_ERROR";
+	readonly sql?: string;
+}
+/**
+* Constraint violations - unique, foreign key, not null, check.
+*/
+interface DbConstraintError extends DbErrorBase {
+	readonly code: "CONSTRAINT_ERROR";
+	readonly constraint?: string;
+	readonly table?: string;
+	readonly column?: string;
+}
+/**
+* Record not found - for getOrThrow, update, delete operations.
+*/
+interface DbNotFoundError extends DbErrorBase {
+	readonly code: "NotFound";
+	readonly table: string;
+}
+/**
+* Read operations can fail with connection errors, query errors, or not found.
+*/
+type ReadError = DbConnectionError | DbQueryError | DbNotFoundError;
+/**
+* Write operations can fail with connection errors, query errors, or constraint violations.
+*/
+type WriteError = DbConnectionError | DbQueryError | DbConstraintError;
+/**
+* Maps a raw error to a ReadError.
+* Categorizes PostgreSQL errors into appropriate error types.
+*/
+declare function toReadError(error: unknown, query?: string): ReadError;
+/**
+* Maps a raw error to a WriteError.
+* Categorizes PostgreSQL errors into appropriate error types.
+*/
+declare function toWriteError(error: unknown, query?: string): WriteError;
+/**
+* Query executor — wraps raw SQL execution with error mapping.
+*
+* Takes a query function (from the database driver) and wraps it to:
+* 1. Execute parameterized SQL
+* 2. Map PG errors to typed DbError subclasses
+* 3. Return typed QueryResult
+*/
+interface ExecutorResult<T> {
+	readonly rows: readonly T[];
+	readonly rowCount: number;
+}
+type QueryFn = <T>(sql: string, params: readonly unknown[]) => Promise<ExecutorResult<T>>;
+/** Operators available for comparable types (number, string, Date, bigint). */
+interface ComparisonOperators<T> {
+	readonly eq?: T;
+	readonly ne?: T;
+	readonly gt?: T;
+	readonly gte?: T;
+	readonly lt?: T;
+	readonly lte?: T;
+	readonly in?: readonly T[];
+	readonly notIn?: readonly T[];
+}
+/** Additional operators for string columns. */
+interface StringOperators {
+	readonly contains?: string;
+	readonly startsWith?: string;
+	readonly endsWith?: string;
+}
+/** The `isNull` operator — only available for nullable columns. */
+interface NullOperator {
+	readonly isNull?: boolean;
+}
+/**
+* Resolves the filter operators for a single column based on its inferred type
+* and nullable metadata.
+*
+* - All types get comparison + in/notIn
+* - String types additionally get contains, startsWith, endsWith
+* - Nullable columns additionally get isNull
 *
 * Uses [T] extends [string] to prevent union distribution -- ensures that a
 * union like 'admin' | 'editor' keeps the full union in each operator slot.
@@ -461,42 +723,41 @@ type OrderByType<TColumns extends ColumnRecord> = { [K in keyof TColumns]? : "as
 * SelectOption<TColumns> — the `select` field in query options.
 *
 * Either:
-* - `{ not: 'sensitive' | 'hidden' }` — exclude columns by visibility category
+* - `{ not: Annotation | Annotation[] }` — exclude columns by annotation(s)
 * - `{ [column]: true }` — explicitly pick columns
 *
 * The two forms are mutually exclusive, enforced via `never` mapped keys.
 */
 type SelectOption<TColumns extends ColumnRecord> = ({
-	readonly not: "sensitive" | "hidden";
+	readonly not: AllAnnotations<TColumns> | readonly AllAnnotations<TColumns>[];
 } & { readonly [K in keyof TColumns]? : never }) | ({ readonly [K in keyof TColumns]? : true } & {
 	readonly not?: never;
 });
-/** Keys of columns where a given metadata flag is NOT `true`. */
-type ColumnKeysWhereNot2<
-	T extends ColumnRecord,
-	Flag extends keyof ColumnMetadata
-> = { [K in keyof T] : T[K] extends ColumnBuilder<unknown, infer M> ? M extends Record<Flag, true> ? never : K : never }[keyof T];
 /** Extract selected keys from a select map (keys set to `true`). */
 type SelectedKeys<
 	TColumns extends ColumnRecord,
 	TSelect
 > = { [K in keyof TSelect] : K extends keyof TColumns ? (TSelect[K] extends true ? K : never) : never }[keyof TSelect];
 /**
+* Normalize `not` value to a union of annotation strings.
+* - `'annotation'` → `'annotation'`
+* - `readonly ['a', 'b']` → `'a' | 'b'`
+*/
+type NormalizeAnnotations<T> = T extends readonly (infer F)[] ? F extends string ? F : never : T extends string ? T : never;
+/**
 * SelectNarrow<TColumns, TSelect> — applies a select clause to narrow the result type.
 *
-* - `{ not: 'sensitive' }` → excludes sensitive AND hidden columns
-* - `{ not: 'hidden' }` → excludes hidden columns
+* - `{ not: 'sensitive' }` → excludes 'sensitive'-annotated AND 'hidden'-annotated columns
+* - `{ not: ['sensitive', 'patchable'] }` → excludes columns with ANY listed annotation + 'hidden'
 * - `{ id: true, name: true }` → picks only id and name
-* - `undefined` → default: excludes hidden columns ($infer behavior)
+* - `undefined` → default: excludes 'hidden'-annotated columns ($infer behavior)
 */
 type SelectNarrow<
 	TColumns extends ColumnRecord,
 	TSelect
 > = TSelect extends {
-	not: "sensitive";
-} ? { [K in ColumnKeysWhereNot2<TColumns, "sensitive"> & ColumnKeysWhereNot2<TColumns, "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> } : TSelect extends {
-	not: "hidden";
-} ? { [K in ColumnKeysWhereNot2<TColumns, "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> } : TSelect extends Record<string, true | undefined> ? { [K in SelectedKeys<TColumns, TSelect> & keyof TColumns] : InferColumnType<TColumns[K]> } : { [K in ColumnKeysWhereNot2<TColumns, "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> };
+	not: infer TNot;
+} ? { [K in ColumnKeysWithoutAnyAnnotation<TColumns, NormalizeAnnotations<TNot> | "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> } : TSelect extends Record<string, true | undefined> ? { [K in SelectedKeys<TColumns, TSelect> & keyof TColumns] : InferColumnType<TColumns[K]> } : { [K in ColumnKeysWithoutAnyAnnotation<TColumns, "hidden"> & keyof TColumns] : InferColumnType<TColumns[K]> };
 /** Relations record — maps relation names to RelationDef. */
 type RelationsRecord = Record<string, RelationDef>;
 /**
@@ -574,8 +835,8 @@ type InsertInput<TTable extends TableDef<ColumnRecord>> = TTable["$insert"];
 * All non-PK columns, all optional.
 */
 type UpdateInput<TTable extends TableDef<ColumnRecord>> = TTable["$update"];
-/** A table entry in the database registry, pairing a table with its relations. */
-interface TableEntry<
+/** A model entry in the database registry, pairing a table with its relations. */
+interface ModelEntry<
 	TTable extends TableDef<ColumnRecord> = TableDef<ColumnRecord>,
 	TRelations extends RelationsRecord = RelationsRecord
 > {
@@ -583,13 +844,13 @@ interface TableEntry<
 	readonly relations: TRelations;
 }
 /**
-* Database<TTables> — type that carries the full table registry.
+* Database<TModels> — type that carries the full model registry.
 *
 * Used as the foundation for typed query methods (implemented in later tickets).
 * Provides type-safe access to table definitions and their relations.
 */
-interface Database<TTables extends Record<string, TableEntry> = Record<string, TableEntry>> {
-	readonly _tables: TTables;
+interface Database<TModels extends Record<string, ModelEntry> = Record<string, ModelEntry>> {
+	readonly _models: TModels;
 }
 /**
 * SQL tagged template literal and escape hatch.
@@ -619,6 +880,26 @@ interface SqlFragment {
 	readonly sql: string;
 	readonly params: readonly unknown[];
 }
+/**
+* D1 database binding interface.
+*/
+interface D1Database {
+	prepare(sql: string): D1PreparedStatement2;
+}
+/**
+* D1 prepared statement interface.
+*/
+interface D1PreparedStatement2 {
+	bind(...values: unknown[]): D1PreparedStatement2;
+	all(): Promise<{
+		results: unknown[];
+	}>;
+	run(): Promise<{
+		meta: {
+			changes: number;
+		};
+	}>;
+}
 interface TenantGraph {
 	/** The tenant root table name (e.g., "organizations"). Null if no tenant columns exist. */
 	readonly root: string | null;
@@ -668,15 +949,26 @@ interface PoolConfig {
 	*/
 	readonly replicas?: readonly string[];
 }
-interface CreateDbOptions<TTables extends Record<string, TableEntry>> {
+interface CreateDbOptions<TModels extends Record<string, ModelEntry>> {
+	/** Model registry mapping logical names to table definitions + relations. */
+	readonly models: TModels;
+	/** Database dialect to use. Defaults to 'postgres' if not specified. */
+	readonly dialect?: "postgres" | "sqlite";
+	/** D1 database binding (required when dialect is 'sqlite'). */
+	readonly d1?: D1Database;
 	/** PostgreSQL connection URL. */
-	readonly url: string;
-	/** Table registry mapping logical names to table definitions + relations. */
-	readonly tables: TTables;
+	readonly url?: string;
 	/** Connection pool configuration. */
 	readonly pool?: PoolConfig;
 	/** Column name casing strategy. */
 	readonly casing?: "snake_case" | "camelCase";
+	/**
+	* Custom casing overrides for edge cases (e.g., OAuth, ID).
+	* Maps camelCase keys to snake_case column names.
+	* These overrides run BEFORE auto-casing logic.
+	* Example: { 'oAuthToken': 'oauth_token', 'userID': 'user_id' }
+	*/
+	readonly casingOverrides?: Record<string, string>;
 	/** Log function for notices (e.g., unscoped table warnings). */
 	readonly log?: (message: string) => void;
 	/**
@@ -690,21 +982,21 @@ interface QueryResult<T> {
 	readonly rows: readonly T[];
 	readonly rowCount: number;
 }
-/** Extract the TableDef from a TableEntry. */
-type EntryTable<TEntry extends TableEntry> = TEntry["table"];
-/** Extract the relations record from a TableEntry. */
-type EntryRelations<TEntry extends TableEntry> = TEntry["relations"];
-/** Extract columns from a TableEntry's table. */
-type EntryColumns<TEntry extends TableEntry> = EntryTable<TEntry>["_columns"];
+/** Extract the TableDef from a ModelEntry. */
+type EntryTable<TEntry extends ModelEntry> = TEntry["table"];
+/** Extract the relations record from a ModelEntry. */
+type EntryRelations<TEntry extends ModelEntry> = TEntry["relations"];
+/** Extract columns from a ModelEntry's table. */
+type EntryColumns<TEntry extends ModelEntry> = EntryTable<TEntry>["_columns"];
 /** Options for get / getOrThrow — typed per-table. */
-type TypedGetOptions<TEntry extends TableEntry> = {
+type TypedGetOptions<TEntry extends ModelEntry> = {
 	readonly where?: FilterType<EntryColumns<TEntry>>;
 	readonly select?: SelectOption<EntryColumns<TEntry>>;
 	readonly orderBy?: OrderByType<EntryColumns<TEntry>>;
 	readonly include?: IncludeOption<EntryRelations<TEntry>>;
 };
 /** Options for list / listAndCount — typed per-table. */
-type TypedListOptions<TEntry extends TableEntry> = {
+type TypedListOptions<TEntry extends ModelEntry> = {
 	readonly where?: FilterType<EntryColumns<TEntry>>;
 	readonly select?: SelectOption<EntryColumns<TEntry>>;
 	readonly orderBy?: OrderByType<EntryColumns<TEntry>>;
@@ -717,174 +1009,115 @@ type TypedListOptions<TEntry extends TableEntry> = {
 	readonly include?: IncludeOption<EntryRelations<TEntry>>;
 };
 /** Options for create — typed per-table. */
-type TypedCreateOptions<TEntry extends TableEntry> = {
+type TypedCreateOptions<TEntry extends ModelEntry> = {
 	readonly data: InsertInput<EntryTable<TEntry>>;
 	readonly select?: SelectOption<EntryColumns<TEntry>>;
 };
 /** Options for createManyAndReturn — typed per-table. */
-type TypedCreateManyAndReturnOptions<TEntry extends TableEntry> = {
+type TypedCreateManyAndReturnOptions<TEntry extends ModelEntry> = {
 	readonly data: readonly InsertInput<EntryTable<TEntry>>[];
 	readonly select?: SelectOption<EntryColumns<TEntry>>;
 };
 /** Options for createMany — typed per-table. */
-type TypedCreateManyOptions<TEntry extends TableEntry> = {
+type TypedCreateManyOptions<TEntry extends ModelEntry> = {
 	readonly data: readonly InsertInput<EntryTable<TEntry>>[];
 };
 /** Options for update — typed per-table. */
-type TypedUpdateOptions<TEntry extends TableEntry> = {
+type TypedUpdateOptions<TEntry extends ModelEntry> = {
 	readonly where: FilterType<EntryColumns<TEntry>>;
 	readonly data: UpdateInput<EntryTable<TEntry>>;
 	readonly select?: SelectOption<EntryColumns<TEntry>>;
 };
 /** Options for updateMany — typed per-table. */
-type TypedUpdateManyOptions<TEntry extends TableEntry> = {
+type TypedUpdateManyOptions<TEntry extends ModelEntry> = {
 	readonly where: FilterType<EntryColumns<TEntry>>;
 	readonly data: UpdateInput<EntryTable<TEntry>>;
 };
 /** Options for upsert — typed per-table. */
-type TypedUpsertOptions<TEntry extends TableEntry> = {
+type TypedUpsertOptions<TEntry extends ModelEntry> = {
 	readonly where: FilterType<EntryColumns<TEntry>>;
 	readonly create: InsertInput<EntryTable<TEntry>>;
 	readonly update: UpdateInput<EntryTable<TEntry>>;
 	readonly select?: SelectOption<EntryColumns<TEntry>>;
 };
 /** Options for delete — typed per-table. */
-type TypedDeleteOptions<TEntry extends TableEntry> = {
+type TypedDeleteOptions<TEntry extends ModelEntry> = {
 	readonly where: FilterType<EntryColumns<TEntry>>;
 	readonly select?: SelectOption<EntryColumns<TEntry>>;
 };
 /** Options for deleteMany — typed per-table. */
-type TypedDeleteManyOptions<TEntry extends TableEntry> = {
+type TypedDeleteManyOptions<TEntry extends ModelEntry> = {
 	readonly where: FilterType<EntryColumns<TEntry>>;
 };
 /** Options for count — typed per-table. */
-type TypedCountOptions<TEntry extends TableEntry> = {
+type TypedCountOptions<TEntry extends ModelEntry> = {
 	readonly where?: FilterType<EntryColumns<TEntry>>;
 };
-interface DatabaseInstance<TTables extends Record<string, TableEntry>> {
-	/** The table registry for type-safe access. */
-	readonly _tables: TTables;
-	/** The computed tenant scoping graph. */
-	readonly $tenantGraph: TenantGraph;
-	/**
-	* Execute a raw SQL query via the sql tagged template.
-	*/
-	query<T = Record<string, unknown>>(fragment: SqlFragment): Promise<QueryResult<T>>;
-	/**
-	* Close all pool connections.
-	*/
-	close(): Promise<void>;
-	/**
-	* Check if the database connection is healthy.
-	*/
-	isHealthy(): Promise<boolean>;
-	/**
-	* Get a single row or null.
-	*/
-	get<
-		TName extends keyof TTables & string,
-		TOptions extends TypedGetOptions<TTables[TName]>
-	>(table: TName, options?: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>> | null>;
-	/**
-	* Get a single row or throw NotFoundError.
-	*/
-	getOrThrow<
-		TName extends keyof TTables & string,
-		TOptions extends TypedGetOptions<TTables[TName]>
-	>(table: TName, options?: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>>;
-	/**
-	* List multiple rows.
-	*/
-	list<
-		TName extends keyof TTables & string,
-		TOptions extends TypedListOptions<TTables[TName]>
-	>(table: TName, options?: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>[]>;
-	/**
-	* List multiple rows with total count.
-	*/
-	listAndCount<
-		TName extends keyof TTables & string,
-		TOptions extends TypedListOptions<TTables[TName]>
-	>(table: TName, options?: TOptions): Promise<{
-		data: FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>[];
+interface ModelDelegate<TEntry extends ModelEntry> {
+	/** Get a single row or null. */
+	get<TOptions extends TypedGetOptions<TEntry>>(options?: TOptions): Promise<Result<FindResult<EntryTable<TEntry>, TOptions, EntryRelations<TEntry>> | null, ReadError>>;
+	/** Get a single row or return NotFoundError. */
+	getOrThrow<TOptions extends TypedGetOptions<TEntry>>(options?: TOptions): Promise<Result<FindResult<EntryTable<TEntry>, TOptions, EntryRelations<TEntry>>, ReadError>>;
+	/** List multiple rows. */
+	list<TOptions extends TypedListOptions<TEntry>>(options?: TOptions): Promise<Result<FindResult<EntryTable<TEntry>, TOptions, EntryRelations<TEntry>>[], ReadError>>;
+	/** List multiple rows with total count. */
+	listAndCount<TOptions extends TypedListOptions<TEntry>>(options?: TOptions): Promise<Result<{
+		data: FindResult<EntryTable<TEntry>, TOptions, EntryRelations<TEntry>>[];
 		total: number;
-	}>;
-	/** @deprecated Use `get` instead */
-	findOne: DatabaseInstance<TTables>["get"];
-	/** @deprecated Use `getOrThrow` instead */
-	findOneOrThrow: DatabaseInstance<TTables>["getOrThrow"];
-	/** @deprecated Use `list` instead */
-	findMany: DatabaseInstance<TTables>["list"];
-	/** @deprecated Use `listAndCount` instead */
-	findManyAndCount: DatabaseInstance<TTables>["listAndCount"];
-	/**
-	* Insert a single row and return it.
-	*/
-	create<
-		TName extends keyof TTables & string,
-		TOptions extends TypedCreateOptions<TTables[TName]>
-	>(table: TName, options: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>>;
-	/**
-	* Insert multiple rows and return the count.
-	*/
-	createMany<TName extends keyof TTables & string>(table: TName, options: TypedCreateManyOptions<TTables[TName]>): Promise<{
+	}, ReadError>>;
+	/** Insert a single row and return it. */
+	create<TOptions extends TypedCreateOptions<TEntry>>(options: TOptions): Promise<Result<FindResult<EntryTable<TEntry>, TOptions, EntryRelations<TEntry>>, WriteError>>;
+	/** Insert multiple rows and return the count. */
+	createMany(options: TypedCreateManyOptions<TEntry>): Promise<Result<{
 		count: number;
-	}>;
-	/**
-	* Insert multiple rows and return them.
-	*/
-	createManyAndReturn<
-		TName extends keyof TTables & string,
-		TOptions extends TypedCreateManyAndReturnOptions<TTables[TName]>
-	>(table: TName, options: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>[]>;
-	/**
-	* Update matching rows and return the first. Throws NotFoundError if none match.
-	*/
-	update<
-		TName extends keyof TTables & string,
-		TOptions extends TypedUpdateOptions<TTables[TName]>
-	>(table: TName, options: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>>;
-	/**
-	* Update matching rows and return the count.
-	*/
-	updateMany<TName extends keyof TTables & string>(table: TName, options: TypedUpdateManyOptions<TTables[TName]>): Promise<{
+	}, WriteError>>;
+	/** Insert multiple rows and return them. */
+	createManyAndReturn<TOptions extends TypedCreateManyAndReturnOptions<TEntry>>(options: TOptions): Promise<Result<FindResult<EntryTable<TEntry>, TOptions, EntryRelations<TEntry>>[], WriteError>>;
+	/** Update matching rows and return the first. */
+	update<TOptions extends TypedUpdateOptions<TEntry>>(options: TOptions): Promise<Result<FindResult<EntryTable<TEntry>, TOptions, EntryRelations<TEntry>>, WriteError>>;
+	/** Update matching rows and return the count. */
+	updateMany(options: TypedUpdateManyOptions<TEntry>): Promise<Result<{
 		count: number;
-	}>;
-	/**
-	* Insert or update a row.
-	*/
-	upsert<
-		TName extends keyof TTables & string,
-		TOptions extends TypedUpsertOptions<TTables[TName]>
-	>(table: TName, options: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>>;
-	/**
-	* Delete a matching row and return it. Throws NotFoundError if none match.
-	*/
-	delete<
-		TName extends keyof TTables & string,
-		TOptions extends TypedDeleteOptions<TTables[TName]>
-	>(table: TName, options: TOptions): Promise<FindResult<EntryTable<TTables[TName]>, TOptions, EntryRelations<TTables[TName]>>>;
-	/**
-	* Delete matching rows and return the count.
-	*/
-	deleteMany<TName extends keyof TTables & string>(table: TName, options: TypedDeleteManyOptions<TTables[TName]>): Promise<{
+	}, WriteError>>;
+	/** Insert or update a row. */
+	upsert<TOptions extends TypedUpsertOptions<TEntry>>(options: TOptions): Promise<Result<FindResult<EntryTable<TEntry>, TOptions, EntryRelations<TEntry>>, WriteError>>;
+	/** Delete a matching row and return it. */
+	delete<TOptions extends TypedDeleteOptions<TEntry>>(options: TOptions): Promise<Result<FindResult<EntryTable<TEntry>, TOptions, EntryRelations<TEntry>>, WriteError>>;
+	/** Delete matching rows and return the count. */
+	deleteMany(options: TypedDeleteManyOptions<TEntry>): Promise<Result<{
 		count: number;
-	}>;
-	/**
-	* Count rows matching an optional filter.
-	*/
-	count<TName extends keyof TTables & string>(table: TName, options?: TypedCountOptions<TTables[TName]>): Promise<number>;
-	/**
-	* Run aggregation functions on a table.
-	*/
-	aggregate<TName extends keyof TTables & string>(table: TName, options: exports_aggregate.AggregateArgs): Promise<Record<string, unknown>>;
-	/**
-	* Group rows by columns and apply aggregation functions.
-	*/
-	groupBy<TName extends keyof TTables & string>(table: TName, options: exports_aggregate.GroupByArgs): Promise<Record<string, unknown>[]>;
+	}, WriteError>>;
+	/** Count rows matching an optional filter. */
+	count(options?: TypedCountOptions<TEntry>): Promise<Result<number, ReadError>>;
+	/** Run aggregation functions on a table. */
+	aggregate(options: agg.AggregateArgs): Promise<Result<Record<string, unknown>, ReadError>>;
+	/** Group rows by columns and apply aggregation functions. */
+	groupBy(options: agg.GroupByArgs): Promise<Result<Record<string, unknown>[], ReadError>>;
 }
+interface DatabaseInternals<TModels extends Record<string, ModelEntry>> {
+	/** The model registry. */
+	readonly models: TModels;
+	/** The SQL dialect used by this database instance. */
+	readonly dialect: Dialect;
+	/** The computed tenant scoping graph. */
+	readonly tenantGraph: TenantGraph;
+}
+type DatabaseClient<TModels extends Record<string, ModelEntry>> = { readonly [K in keyof TModels] : ModelDelegate<TModels[K]> } & {
+	/** Execute a raw SQL query via the sql tagged template. */
+	query<T = Record<string, unknown>>(fragment: SqlFragment): Promise<Result<QueryResult<T>, ReadError>>;
+	/** Close all pool connections. */
+	close(): Promise<void>;
+	/** Check if the database connection is healthy. */
+	isHealthy(): Promise<boolean>;
+	/** Internal properties — not part of the public API. */
+	readonly _internals: DatabaseInternals<TModels>;
+};
 /**
-* Creates a typed Database instance.
+* Creates a typed database client with Prisma-style model delegates.
+*
+* Instead of `db.get('users', opts)`, use `db.users.get(opts)`.
+* Each model in the registry becomes a property on the returned client
+* with all CRUD methods typed for that specific model.
 *
 * Computes the tenant graph at creation time from d.tenant() metadata,
 * traversing references to find indirect tenant paths.
@@ -904,222 +1137,381 @@ interface DatabaseInstance<TTables extends Record<string, TableEntry>> {
 * idle connections are closed after 30 seconds. Set `idleTimeout` explicitly
 * to override (value in milliseconds, e.g., `60000` for 60s).
 */
-declare function createDb<TTables extends Record<string, TableEntry>>(options: CreateDbOptions<TTables>): DatabaseInstance<TTables>;
-interface EnumSchemaLike<T extends readonly string[]> {
-	readonly values: T;
+declare function createDb<TModels extends Record<string, ModelEntry>>(options: CreateDbOptions<TModels>): DatabaseClient<TModels>;
+/**
+* Creates an EntityDbAdapter backed by a DatabaseClient for a specific table.
+*
+* Bridges the gap between the entity layer's simple adapter interface and the
+* query builder's rich, typed API. Unwraps Result<T, E> from the query builder
+* into the throw/return-null pattern expected by the entity pipeline.
+*/
+declare function createDatabaseBridgeAdapter<
+	TModels extends Record<string, ModelEntry>,
+	TName extends keyof TModels & string
+>(db: DatabaseClient<TModels>, tableName: TName): EntityDbAdapter;
+interface SqliteAdapterOptions<T extends ColumnRecord> {
+	/** The table schema definition */
+	schema: TableDef<T>;
+	/** Path to the SQLite database file */
+	dbPath?: string;
+	/** Directory to store the database file (alternative to dbPath) */
+	dataDir?: string;
+	/** Auto-apply migrations on startup */
+	migrations?: {
+		autoApply?: boolean;
+	};
 }
-declare const d: {
-	uuid(): ColumnBuilder<string, DefaultMeta<"uuid">>;
-	text(): ColumnBuilder<string, DefaultMeta<"text">>;
-	varchar<TLength extends number>(length: TLength): ColumnBuilder<string, VarcharMeta<TLength>>;
-	email(): ColumnBuilder<string, FormatMeta<"text", "email">>;
-	boolean(): ColumnBuilder<boolean, DefaultMeta<"boolean">>;
-	integer(): ColumnBuilder<number, DefaultMeta<"integer">>;
-	bigint(): ColumnBuilder<bigint, DefaultMeta<"bigint">>;
-	decimal<
-		TPrecision extends number,
-		TScale extends number
-	>(precision: TPrecision, scale: TScale): ColumnBuilder<string, DecimalMeta<TPrecision, TScale>>;
-	real(): ColumnBuilder<number, DefaultMeta<"real">>;
-	doublePrecision(): ColumnBuilder<number, DefaultMeta<"double precision">>;
-	serial(): ColumnBuilder<number, SerialMeta>;
-	timestamp(): ColumnBuilder<Date, DefaultMeta<"timestamp with time zone">>;
-	date(): ColumnBuilder<string, DefaultMeta<"date">>;
-	time(): ColumnBuilder<string, DefaultMeta<"time">>;
-	jsonb<T = unknown>(opts?: {
-		validator: JsonbValidator<T>;
-	}): ColumnBuilder<T, DefaultMeta<"jsonb">>;
-	textArray(): ColumnBuilder<string[], DefaultMeta<"text[]">>;
-	integerArray(): ColumnBuilder<number[], DefaultMeta<"integer[]">>;
-	enum<
-		TName extends string,
-		const TValues extends readonly string[]
-	>(name: TName, values: TValues): ColumnBuilder<TValues[number], EnumMeta<TName, TValues>>;
-	enum<
-		TName extends string,
-		const TValues extends readonly [string, ...string[]]
-	>(name: TName, schema: EnumSchemaLike<TValues>): ColumnBuilder<TValues[number], EnumMeta<TName, TValues>>;
-	tenant(targetTable: TableDef<ColumnRecord>): ColumnBuilder<string, TenantMeta>;
-	table<TColumns extends ColumnRecord>(name: string, columns: TColumns, options?: TableOptions): TableDef<TColumns>;
-	index(columns: string | string[]): IndexDef;
-	ref: {
-		one<TTarget extends TableDef<ColumnRecord>>(target: () => TTarget, foreignKey: string): RelationDef<TTarget, "one">;
-		many<TTarget extends TableDef<ColumnRecord>>(target: () => TTarget, foreignKey: string): RelationDef<TTarget, "many">;
-		many<TTarget extends TableDef<ColumnRecord>>(target: () => TTarget): ManyRelationDef<TTarget>;
-	};
-	entry<TTable extends TableDef<ColumnRecord>>(table: TTable): TableEntry<TTable, {}>;
-	entry<
-		TTable extends TableDef<ColumnRecord>,
-		TRelations extends Record<string, RelationDef>
-	>(table: TTable, relations: TRelations): TableEntry<TTable, TRelations>;
-};
-interface DbErrorJson {
-	readonly error: string;
-	readonly code: string;
-	readonly message: string;
-	readonly table?: string;
-	readonly column?: string;
-}
-declare abstract class DbError extends Error {
-	abstract readonly code: string;
-	/** Raw PostgreSQL SQLSTATE code, if applicable. */
-	readonly pgCode?: string | undefined;
-	readonly table?: string | undefined;
-	readonly query?: string | undefined;
-	constructor(message: string);
-	toJSON(): DbErrorJson;
+/**
+* Create a SQLite driver using bun:sqlite or better-sqlite3.
+*/
+declare function createSqliteDriver2(dbPath: string): DbDriver;
+/**
+* Create a SQLite EntityDbAdapter from a schema.
+*/
+declare function createSqliteAdapter<T extends ColumnRecord>(options: SqliteAdapterOptions<T>): Promise<EntityDbAdapter>;
+import { Result as Result3 } from "@vertz/errors";
+import { MigrationError as MigrationError2 } from "@vertz/errors";
+/**
+* The query function type expected by the migration runner.
+*/
+type MigrationQueryFn = (sql: string, params: readonly unknown[]) => Promise<{
+	rows: readonly Record<string, unknown>[];
+	rowCount: number;
+}>;
+/**
+* Represents a migration file on disk.
+*/
+interface MigrationFile {
+	name: string;
+	sql: string;
+	timestamp: number;
 }
-interface UniqueConstraintErrorOptions {
-	readonly table: string;
-	readonly column: string;
-	readonly value?: string;
-	readonly query?: string;
+/**
+* Result of applying (or dry-running) a migration.
+*/
+interface ApplyResult {
+	/** The migration name. */
+	name: string;
+	/** The SQL that was (or would be) executed. */
+	sql: string;
+	/** The computed checksum of the migration SQL. */
+	checksum: string;
+	/** Whether this was a dry run. */
+	dryRun: boolean;
+	/** The statements that were (or would be) executed, in order. */
+	statements: string[];
 }
-declare class UniqueConstraintError extends DbError {
-	readonly code: "UNIQUE_VIOLATION";
-	readonly pgCode: "23505";
-	readonly table: string;
-	readonly query: string | undefined;
-	readonly column: string;
-	readonly value: string | undefined;
-	constructor(options: UniqueConstraintErrorOptions);
-	toJSON(): DbErrorJson;
+/**
+* Parse a migration filename to extract its timestamp number.
+* Expected format: NNNN_description.sql
+*/
+declare function parseMigrationName(filename: string): {
+	timestamp: number;
+	name: string;
+} | null;
+interface ColumnSnapshot {
+	type: string;
+	nullable: boolean;
+	primary: boolean;
+	unique: boolean;
+	default?: string;
+	annotations?: string[];
 }
-interface ForeignKeyErrorOptions {
-	readonly table: string;
-	readonly constraint: string;
-	readonly detail?: string;
-	readonly query?: string;
+interface IndexSnapshot {
+	columns: string[];
+	name?: string;
+	unique?: boolean;
 }
-declare class ForeignKeyError extends DbError {
-	readonly code: "FOREIGN_KEY_VIOLATION";
-	readonly pgCode: "23503";
-	readonly table: string;
-	readonly query: string | undefined;
-	readonly constraint: string;
-	readonly detail: string | undefined;
-	constructor(options: ForeignKeyErrorOptions);
-	toJSON(): DbErrorJson;
+interface ForeignKeySnapshot {
+	column: string;
+	targetTable: string;
+	targetColumn: string;
 }
-interface NotNullErrorOptions {
-	readonly table: string;
-	readonly column: string;
-	readonly query?: string;
+interface TableSnapshot {
+	columns: Record<string, ColumnSnapshot>;
+	indexes: IndexSnapshot[];
+	foreignKeys: ForeignKeySnapshot[];
+	_metadata: Record<string, unknown>;
 }
-declare class NotNullError extends DbError {
-	readonly code: "NOT_NULL_VIOLATION";
-	readonly pgCode: "23502";
-	readonly table: string;
-	readonly query: string | undefined;
-	readonly column: string;
-	constructor(options: NotNullErrorOptions);
-	toJSON(): DbErrorJson;
+interface SchemaSnapshot {
+	version: 1;
+	tables: Record<string, TableSnapshot>;
+	enums: Record<string, string[]>;
 }
-interface CheckConstraintErrorOptions {
-	readonly table: string;
-	readonly constraint: string;
-	readonly query?: string;
+declare function createSnapshot(tables: TableDef<ColumnRecord>[]): SchemaSnapshot;
+type ChangeType = "table_added" | "table_removed" | "column_added" | "column_removed" | "column_altered" | "column_renamed" | "index_added" | "index_removed" | "enum_added" | "enum_removed" | "enum_altered";
+interface CollisionInfo {
+	existingName: string;
+	conflictingName: string;
+	sequenceNumber: number;
+	suggestedName: string;
 }
-declare class CheckConstraintError extends DbError {
-	readonly code: "CHECK_VIOLATION";
-	readonly pgCode: "23514";
-	readonly table: string;
-	readonly query: string | undefined;
-	readonly constraint: string;
-	constructor(options: CheckConstraintErrorOptions);
-	toJSON(): DbErrorJson;
+interface BaselineOptions {
+	queryFn: MigrationQueryFn;
+	migrationFiles: MigrationFile[];
+	dialect?: Dialect;
 }
-declare class NotFoundError extends DbError {
-	readonly code: "NOT_FOUND";
-	readonly table: string;
-	readonly query: string | undefined;
-	constructor(table: string, query?: string);
-	toJSON(): DbErrorJson;
+interface BaselineResult {
+	recorded: string[];
 }
-declare class ConnectionError extends DbError {
-	readonly code: string;
-	constructor(message: string);
+/**
+* Mark all existing migration files as applied without executing them.
+* Used when adopting vertz on a database that already has the schema.
+*/
+declare function baseline(options: BaselineOptions): Promise<Result3<BaselineResult, MigrationError2>>;
+import { Result as Result4 } from "@vertz/errors";
+interface MigrateDeployOptions {
+	queryFn: MigrationQueryFn;
+	migrationFiles: MigrationFile[];
+	/** When true, return the SQL that would be executed without applying. */
+	dryRun?: boolean;
 }
-declare class ConnectionPoolExhaustedError extends ConnectionError {
-	readonly code: "POOL_EXHAUSTED";
-	constructor(poolSize: number);
+interface MigrateDeployResult {
+	applied: string[];
+	alreadyApplied: string[];
+	/** When dry-run is enabled, contains the details of each migration that would be applied. */
+	dryRun: boolean;
+	/** Detailed results for each migration that was (or would be) applied. */
+	migrations?: ApplyResult[];
 }
 /**
-* Maps semantic error names to their corresponding PostgreSQL SQLSTATE codes.
+* Apply all pending migrations in order.
 *
-* Usage in switch statements:
-* ```ts
-* switch (error.code) {
-*   case 'UNIQUE_VIOLATION':   // ...
-*   case 'FOREIGN_KEY_VIOLATION': // ...
-* }
-* ```
+* In dry-run mode, returns the SQL that would be executed without modifying the database.
+*/
+declare function migrateDeploy(options: MigrateDeployOptions): Promise<Result4<MigrateDeployResult, MigrationError2>>;
+interface RenameSuggestion {
+	table: string;
+	oldColumn: string;
+	newColumn: string;
+	confidence: number;
+}
+interface MigrateDevOptions {
+	queryFn: MigrationQueryFn;
+	currentSnapshot: SchemaSnapshot;
+	previousSnapshot: SchemaSnapshot;
+	migrationName?: string;
+	existingFiles: string[];
+	migrationsDir: string;
+	writeFile: (path: string, content: string) => Promise<void>;
+	readFile?: (path: string) => Promise<string>;
+	dryRun: boolean;
+}
+interface MigrateDevResult {
+	migrationFile: string;
+	sql: string;
+	appliedAt?: Date;
+	dryRun: boolean;
+	renames?: RenameSuggestion[];
+	collisions?: CollisionInfo[];
+	snapshot: SchemaSnapshot;
+}
+/**
+* Generate a migration from schema diff, optionally apply it.
 *
-* Reverse lookup (semantic name -> PG code):
-* ```ts
-* DbErrorCode.UNIQUE_VIOLATION // '23505'
-* ```
+* In dry-run mode, generates SQL and returns it WITHOUT applying or writing files.
 */
-declare const DbErrorCode: {
-	readonly UNIQUE_VIOLATION: "23505";
-	readonly FOREIGN_KEY_VIOLATION: "23503";
-	readonly NOT_NULL_VIOLATION: "23502";
-	readonly CHECK_VIOLATION: "23514";
-	readonly EXCLUSION_VIOLATION: "23P01";
-	readonly SERIALIZATION_FAILURE: "40001";
-	readonly DEADLOCK_DETECTED: "40P01";
-	readonly CONNECTION_EXCEPTION: "08000";
-	readonly CONNECTION_DOES_NOT_EXIST: "08003";
-	readonly CONNECTION_FAILURE: "08006";
-	readonly NOT_FOUND: "NOT_FOUND";
-	readonly CONNECTION_ERROR: "CONNECTION_ERROR";
-	readonly POOL_EXHAUSTED: "POOL_EXHAUSTED";
-};
-/** Union of all semantic error code keys (e.g., `'UNIQUE_VIOLATION' | 'FOREIGN_KEY_VIOLATION' | ...`). */
-type DbErrorCodeName = keyof typeof DbErrorCode;
-/** Union of all raw PG error code values (e.g., `'23505' | '23503' | ...`). */
-type DbErrorCodeValue = (typeof DbErrorCode)[keyof typeof DbErrorCode];
+declare function migrateDev(options: MigrateDevOptions): Promise<MigrateDevResult>;
+interface PushOptions {
+	queryFn: MigrationQueryFn;
+	currentSnapshot: SchemaSnapshot;
+	previousSnapshot: SchemaSnapshot;
+}
+interface PushResult {
+	sql: string;
+	tablesAffected: string[];
+}
 /**
-* Reverse map: raw PG code -> semantic name.
-* Built at module load time from DbErrorCode.
+* Push schema changes directly to the database without creating a migration file.
 */
-declare const PgCodeToName: Readonly<Record<string, DbErrorCodeName | undefined>>;
+declare function push(options: PushOptions): Promise<PushResult>;
+import { Result as Result5 } from "@vertz/errors";
+interface ResetOptions {
+	queryFn: MigrationQueryFn;
+	migrationFiles: MigrationFile[];
+	dialect?: Dialect;
+}
+interface ResetResult {
+	tablesDropped: string[];
+	migrationsApplied: string[];
+}
 /**
-* Look up the semantic name for a raw PG error code.
-* Returns the key (e.g., `'UNIQUE_VIOLATION'`) or `undefined` if unmapped.
+* Drop all user tables and re-apply all migrations from scratch.
+* Development use only.
 */
-declare function resolveErrorCode(pgCode: string): DbErrorCodeName | undefined;
-interface HttpErrorResponse {
-	readonly status: number;
-	readonly body: DbErrorJson;
+declare function reset(options: ResetOptions): Promise<Result5<ResetResult, MigrationError2>>;
+import { Result as Result6 } from "@vertz/errors";
+interface MigrateStatusOptions {
+	queryFn: MigrationQueryFn;
+	migrationFiles: MigrationFile[];
+	currentSnapshot?: SchemaSnapshot;
+	savedSnapshot?: SchemaSnapshot;
+	dialect?: Dialect;
+}
+interface MigrationInfo {
+	name: string;
+	checksum: string;
+	appliedAt: Date;
+}
+interface CodeChange {
+	description: string;
+	type: ChangeType;
+	table?: string;
+	column?: string;
+}
+interface DriftEntry {
+	description: string;
+	type: "extra_table" | "missing_table" | "extra_column" | "missing_column" | "column_type_mismatch";
+	table: string;
+	column?: string;
 }
+interface MigrateStatusResult {
+	applied: MigrationInfo[];
+	pending: string[];
+	codeChanges: CodeChange[];
+	drift: DriftEntry[];
+}
+declare function detectSchemaDrift(expected: SchemaSnapshot, actual: SchemaSnapshot): DriftEntry[];
 /**
-* Maps a DbError to an HTTP error response with the appropriate status code.
+* Report the status of migrations: which are applied and which are pending.
+* Optionally detects code changes and database drift.
+*/
+declare function migrateStatus(options: MigrateStatusOptions): Promise<Result6<MigrateStatusResult, MigrationError2>>;
+interface PostgresDriver extends DbDriver {
+	/** The QueryFn adapter for use with createDb. */
+	readonly queryFn: QueryFn;
+	/** Check connection health with SELECT 1. */
+	isHealthy(): Promise<boolean>;
+}
+/**
+* Create a PostgreSQL driver from a connection URL and optional pool config.
 *
-* - UniqueConstraintError  -> 409 Conflict
-* - NotFoundError          -> 404 Not Found
-* - ForeignKeyError        -> 422 Unprocessable Entity
-* - NotNullError           -> 422 Unprocessable Entity
-* - CheckConstraintError   -> 422 Unprocessable Entity
-* - ConnectionError        -> 503 Service Unavailable
-* - Unknown DbError        -> 500 Internal Server Error
+* Note: Query routing (to replicas) is handled at the database.ts layer (createDb).
+* This driver provides a simple connection to a single PostgreSQL instance.
+*
+* @param url - PostgreSQL connection URL (e.g., postgres://user:pass@host:5432/db)
+* @param pool - Optional pool configuration
+* @returns A PostgresDriver with queryFn, close(), and isHealthy()
 */
-declare function dbErrorToHttpError(error: DbError): HttpErrorResponse;
-interface PgErrorInput {
-	readonly code: string;
-	readonly message: string;
-	readonly table?: string;
-	readonly column?: string;
-	readonly constraint?: string;
-	readonly detail?: string;
+declare function createPostgresDriver(url: string, pool?: PoolConfig): PostgresDriver;
+interface SchemaLike<T> {
+	parse(value: unknown): {
+		ok: true;
+		data: T;
+	} | {
+		ok: false;
+		error: Error;
+	};
+}
+interface ModelSchemas<TTable extends TableDef<ColumnRecord>> {
+	readonly response: SchemaLike<TTable["$response"]>;
+	readonly createInput: SchemaLike<TTable["$create_input"]>;
+	readonly updateInput: SchemaLike<TTable["$update_input"]>;
+}
+interface ModelDef<
+	TTable extends TableDef<ColumnRecord> = TableDef<ColumnRecord>,
+	TRelations extends Record<string, RelationDef> = {}
+> {
+	readonly table: TTable;
+	readonly relations: TRelations;
+	readonly schemas: ModelSchemas<TTable>;
+}
+interface EnumSchemaLike<T extends readonly string[]> {
+	readonly values: T;
 }
+declare const d: {
+	uuid(): ColumnBuilder<string, DefaultMeta<"uuid">>;
+	text(): ColumnBuilder<string, DefaultMeta<"text">>;
+	varchar<TLength extends number>(length: TLength): ColumnBuilder<string, VarcharMeta<TLength>>;
+	email(): ColumnBuilder<string, FormatMeta<"text", "email">>;
+	boolean(): ColumnBuilder<boolean, DefaultMeta<"boolean">>;
+	integer(): ColumnBuilder<number, DefaultMeta<"integer">>;
+	bigint(): ColumnBuilder<bigint, DefaultMeta<"bigint">>;
+	decimal<
+		TPrecision extends number,
+		TScale extends number
+	>(precision: TPrecision, scale: TScale): ColumnBuilder<string, DecimalMeta<TPrecision, TScale>>;
+	real(): ColumnBuilder<number, DefaultMeta<"real">>;
+	doublePrecision(): ColumnBuilder<number, DefaultMeta<"double precision">>;
+	serial(): ColumnBuilder<number, SerialMeta>;
+	timestamp(): ColumnBuilder<Date, DefaultMeta<"timestamp with time zone">>;
+	date(): ColumnBuilder<string, DefaultMeta<"date">>;
+	time(): ColumnBuilder<string, DefaultMeta<"time">>;
+	jsonb<T = unknown>(schemaOrOpts?: SchemaLike<T> | {
+		validator: JsonbValidator<T>;
+	}): ColumnBuilder<T, DefaultMeta<"jsonb">>;
+	textArray(): ColumnBuilder<string[], DefaultMeta<"text[]">>;
+	integerArray(): ColumnBuilder<number[], DefaultMeta<"integer[]">>;
+	enum<
+		TName extends string,
+		const TValues extends readonly string[]
+	>(name: TName, values: TValues): ColumnBuilder<TValues[number], EnumMeta<TName, TValues>>;
+	enum<
+		TName extends string,
+		const TValues extends readonly [string, ...string[]]
+	>(name: TName, schema: EnumSchemaLike<TValues>): ColumnBuilder<TValues[number], EnumMeta<TName, TValues>>;
+	tenant(targetTable: TableDef<ColumnRecord>): ColumnBuilder<string, TenantMeta>;
+	table<TColumns extends ColumnRecord>(name: string, columns: TColumns, options?: TableOptions): TableDef<TColumns>;
+	index(columns: string | string[]): IndexDef;
+	ref: {
+		one<TTarget extends TableDef<ColumnRecord>>(target: () => TTarget, foreignKey: string): RelationDef<TTarget, "one">;
+		many<TTarget extends TableDef<ColumnRecord>>(target: () => TTarget, foreignKey: string): RelationDef<TTarget, "many">;
+		many<TTarget extends TableDef<ColumnRecord>>(target: () => TTarget): ManyRelationDef<TTarget>;
+	};
+	entry<TTable extends TableDef<ColumnRecord>>(table: TTable): ModelEntry<TTable, {}>;
+	entry<
+		TTable extends TableDef<ColumnRecord>,
+		TRelations extends Record<string, RelationDef>
+	>(table: TTable, relations: TRelations): ModelEntry<TTable, TRelations>;
+	model<TTable extends TableDef<ColumnRecord>>(table: TTable): ModelDef<TTable, {}>;
+	model<
+		TTable extends TableDef<ColumnRecord>,
+		TRelations extends Record<string, RelationDef>
+	>(table: TTable, relations: TRelations): ModelDef<TTable, TRelations>;
+};
 /**
-* Maps a raw PostgreSQL error object to a typed DbError subclass.
+* Convenience utility for creating a frozen bag of annotation constants.
 *
-* Extracts structured metadata (column, constraint, value) from the
-* PG error's `detail` and `message` fields.
+* Usage:
+* ```typescript
+* const Annotation = defineAnnotations('sensitive', 'hidden', 'patchable');
+* // typeof Annotation = { readonly sensitive: 'sensitive'; readonly hidden: 'hidden'; readonly patchable: 'patchable' }
+*
+* d.text().is(Annotation.hidden);
+* ```
 */
-declare function parsePgError(pgError: PgErrorInput, query?: string): DbError;
+declare function defineAnnotations<const T extends readonly string[]>(...annotations: T): { readonly [K in T[number]] : K };
+/**
+* Shared enum registry — define enums once, reuse across tables.
+*
+* @example
+* ```ts
+* const enums = createEnumRegistry({
+*   status: ['active', 'inactive', 'pending'],
+*   role: ['admin', 'editor', 'viewer'],
+* } as const);
+*
+* const orders = d.table('orders', {
+*   status: d.enum('status', enums.status),
+* });
+* const users = d.table('users', {
+*   role: d.enum('role', enums.role),
+* });
+* ```
+*/
+/** A registered enum entry with name and values accessible for d.enum(). */
+interface RegisteredEnum<TValues extends readonly string[]> {
+	/** The enum name (same as the registry key). */
+	readonly name: string;
+	/** The enum values — compatible with d.enum()'s EnumSchemaLike interface. */
+	readonly values: TValues;
+}
+type EnumRegistry<T extends Record<string, readonly string[]>> = { readonly [K in keyof T] : RegisteredEnum<T[K]> };
+/**
+* Creates a shared enum registry from a map of enum names to their values.
+* The returned object can be passed directly to `d.enum(name, enums.myEnum)`.
+*/
+declare function createEnumRegistry<T extends Record<string, readonly string[]>>(definitions: T): EnumRegistry<T>;
 /**
 * Extracts the string column keys from a TableDef's _columns record.
 * Used to constrain FK arguments at the type level.
@@ -1132,34 +1524,34 @@ type ColumnKeys<T extends TableDef<ColumnRecord>> = T extends TableDef<infer C>
 * - `many()` validates: target name is a registry key, FK is a column of the TARGET table
 */
 interface TypedRef<
-	TTables extends Record<string, TableDef<ColumnRecord>>,
+	TModels extends Record<string, TableDef<ColumnRecord>>,
 	TSourceTable extends TableDef<ColumnRecord>
 > {
 	/** belongsTo — FK lives on the source table */
 	one<
-		TTargetName extends Extract<keyof TTables, string>,
+		TTargetName extends Extract<keyof TModels, string>,
 		TFK extends ColumnKeys<TSourceTable>
-	>(target: TTargetName, foreignKey: TFK): RelationDef<TTables[TTargetName], "one">;
+	>(target: TTargetName, foreignKey: TFK): RelationDef<TModels[TTargetName], "one">;
 	/** hasMany — FK lives on the target table */
 	many<
-		TTargetName extends Extract<keyof TTables, string>,
-		TFK extends ColumnKeys<TTables[TTargetName]>
-	>(target: TTargetName, foreignKey: TFK): RelationDef<TTables[TTargetName], "many">;
+		TTargetName extends Extract<keyof TModels, string>,
+		TFK extends ColumnKeys<TModels[TTargetName]>
+	>(target: TTargetName, foreignKey: TFK): RelationDef<TModels[TTargetName], "many">;
 }
 /**
 * An object keyed by table name where each value is a TypedRef scoped
 * to that table as the source. This enables `ref.posts.one('users', 'authorId')`
 * where TypeScript knows 'authorId' must be a column of `posts`.
 */
-type PerTableRefFactory<TTables extends Record<string, TableDef<ColumnRecord>>> = { [K in Extract<keyof TTables, string>] : TypedRef<TTables, TTables[K]> };
+type PerTableRefFactory<TModels extends Record<string, TableDef<ColumnRecord>>> = { [K in Extract<keyof TModels, string>] : TypedRef<TModels, TModels[K]> };
 /**
-* Maps each table key to a TableEntry, merging the table with its relations
+* Maps each table key to a ModelEntry, merging the table with its relations
 * from the callback (or empty relations if the table was omitted).
 */
 type RegistryOutput<
-	TTables extends Record<string, TableDef<ColumnRecord>>,
-	TRelMap extends { [K in keyof TTables]? : Record<string, RelationDef> }
-> = { [K in keyof TTables] : TableEntry<TTables[K], K extends keyof TRelMap ? TRelMap[K] extends Record<string, RelationDef> ? TRelMap[K] : {} : {}> };
+	TModels extends Record<string, TableDef<ColumnRecord>>,
+	TRelMap extends { [K in keyof TModels]? : Record<string, RelationDef> }
+> = { [K in keyof TModels] : ModelEntry<TModels[K], K extends keyof TRelMap ? TRelMap[K] extends Record<string, RelationDef> ? TRelMap[K] : {} : {}> };
 /**
 * Creates a typed table registry with compile-time validated relations.
 *
@@ -1170,7 +1562,7 @@ type RegistryOutput<
 *
 * @example
 * ```typescript
-* const tables = createRegistry(
+* const models = createRegistry(
 *   { users, posts, comments },
 *   (ref) => ({
 *     posts: {
@@ -1186,40 +1578,9 @@ type RegistryOutput<
 * ```
 */
 declare function createRegistry<
-	TTables extends Record<string, TableDef<ColumnRecord>>,
-	TRelMap extends { [K in keyof TTables]? : Record<string, RelationDef> }
->(tables: TTables, relationsCallback: (ref: PerTableRefFactory<TTables>) => TRelMap): RegistryOutput<TTables, TRelMap>;
-/**
-* Shared enum registry — define enums once, reuse across tables.
-*
-* @example
-* ```ts
-* const enums = createEnumRegistry({
-*   status: ['active', 'inactive', 'pending'],
-*   role: ['admin', 'editor', 'viewer'],
-* } as const);
-*
-* const orders = d.table('orders', {
-*   status: d.enum('status', enums.status),
-* });
-* const users = d.table('users', {
-*   role: d.enum('role', enums.role),
-* });
-* ```
-*/
-/** A registered enum entry with name and values accessible for d.enum(). */
-interface RegisteredEnum<TValues extends readonly string[]> {
-	/** The enum name (same as the registry key). */
-	readonly name: string;
-	/** The enum values — compatible with d.enum()'s EnumSchemaLike interface. */
-	readonly values: TValues;
-}
-type EnumRegistry<T extends Record<string, readonly string[]>> = { readonly [K in keyof T] : RegisteredEnum<T[K]> };
-/**
-* Creates a shared enum registry from a map of enum names to their values.
-* The returned object can be passed directly to `d.enum(name, enums.myEnum)`.
-*/
-declare function createEnumRegistry<T extends Record<string, readonly string[]>>(definitions: T): EnumRegistry<T>;
+	TModels extends Record<string, TableDef<ColumnRecord>>,
+	TRelMap extends { [K in keyof TModels]? : Record<string, RelationDef> }
+>(tables: TModels, relationsCallback: (ref: PerTableRefFactory<TModels>) => TRelMap): RegistryOutput<TModels, TRelMap>;
 /**
 * Branded error types for readable compiler messages.
 *
@@ -1288,59 +1649,4 @@ type StrictKeys<
 	TAllowed extends string,
 	TTable extends string
 > = TRecord extends Record<string, unknown> ? { [K in keyof TRecord] : K extends TAllowed ? TRecord[K] : InvalidColumn<K & string, TTable> } : TRecord;
-/**
-* Type generation for DB client codegen.
-*
-* This module generates TypeScript types from domain definitions.
-*/
-interface DomainField {
-	type: "string" | "number" | "boolean" | "date" | "json" | "uuid" | "enum";
-	primary?: boolean;
-	required?: boolean;
-	references?: string;
-	enumName?: string;
-	enumValues?: string[];
-}
-interface DomainRelation {
-	type: "belongsTo" | "hasMany";
-	target: string;
-	foreignKey: string;
-}
-interface DomainDefinition {
-	name: string;
-	fields: Record<string, DomainField>;
-	relations?: Record<string, DomainRelation>;
-}
-/**
-* Generate TypeScript types from a domain definition.
-* This function should generate:
-* - Entity interface (e.g., interface User { ... })
-* - Create input type (required fields only)
-* - Update input type (all fields optional)
-* - Where/filter type
-* - OrderBy type
-* - CRUD method signatures
-*/
-declare function generateTypes(domain: DomainDefinition): string;
-/**
-* Generate the typed database client from domain definitions.
-* This function should generate:
-* - A db object with entity accessors
-* - Each entity has: list, get, create, update, delete methods
-* - Typed filter/where parameters
-* - Relation accessors
-*/
-declare function generateClient(domains: DomainDefinition[]): string;
-/**
-* Define a domain for DB client codegen.
-* This creates a domain definition that can be used to generate types and client.
-*/
-declare function defineDomain(name: string, config: {
-	fields: Record<string, Omit<DomainField, "type"> & {
-		type: DomainField["type"];
-	}>;
-	relations?: Record<string, Omit<DomainRelation, "type"> & {
-		type: DomainRelation["type"];
-	}>;
-}): DomainDefinition;
-export { resolveErrorCode, push, parsePgError, migrateStatus, migrateDev, migrateDeploy, generateTypes, generateClient, formatDiagnostic, explainError, diagnoseError, defineDomain, dbErrorToHttpError, d, createRegistry, createEnumRegistry, createDb, computeTenantGraph, VarcharMeta, ValidateKeys, UpdateInput, UniqueConstraintErrorOptions, UniqueConstraintError, TenantMeta, TenantGraph, TableEntry, TableDef, StrictKeys, SelectOption, SelectNarrow, RenameSuggestion, RelationDef, RegisteredEnum, QueryResult, PushResult, PushOptions, PoolConfig, PgErrorInput, PgCodeToName, OrderByType, NotNullErrorOptions, NotNullError, NotFoundError, MixedSelectError, MigrationInfo, MigrateStatusResult, MigrateStatusOptions, MigrateDevResult, MigrateDevOptions, MigrateDeployResult, MigrateDeployOptions, JsonbValidator, InvalidRelation, InvalidFilterType, InvalidColumn, InsertInput, InferColumnType, IndexDef, IncludeResolve, IncludeOption, HttpErrorResponse, FormatMeta, ForeignKeyErrorOptions, ForeignKeyError, FindResult, FindOptions, FilterType, EnumMeta, DomainRelation, DomainField, DomainDefinition, DiagnosticResult, DecimalMeta, DbErrorJson, DbErrorCodeValue, DbErrorCodeName, DbErrorCode, DbError, DatabaseInstance, Database, CreateDbOptions, ConnectionPoolExhaustedError, ConnectionError, ColumnMetadata, ColumnBuilder, CheckConstraintErrorOptions, CheckConstraintError };
+export { toWriteError, toReadError, resolveErrorCode, reset, push, parsePgError, parseMigrationName, migrateStatus, migrateDev, migrateDeploy, generateId, formatDiagnostic, explainError, diagnoseError, detectSchemaDrift, defineAnnotations, defaultSqliteDialect, defaultPostgresDialect, dbErrorToHttpError, d, createSqliteDriver2 as createSqliteDriver, createSqliteAdapter, createSnapshot, createRegistry, createPostgresDriver, createEnumRegistry, createDb, createDatabaseBridgeAdapter, createD1Driver, createD1Adapter, computeTenantGraph, baseline, WriteError, VarcharMeta, ValidateKeys, UpdateInput, UniqueConstraintErrorOptions, UniqueConstraintError, TenantMeta, TenantGraph, TableDef, StrictKeys, SqliteDialect, SqliteAdapterOptions, SelectOption, SelectNarrow, SchemaSnapshot, SchemaLike, ResetResult, ResetOptions, RenameSuggestion, RelationDef, RegisteredEnum, ReadError, QueryResult, PushResult, PushOptions, PostgresDriver, PostgresDialect, PoolConfig, PgErrorInput, PgCodeToName, OrderByType, NotNullErrorOptions, NotNullError, NotFoundError, ModelSchemas, ModelEntry, ModelDelegate, ModelDef, MixedSelectError, MigrationQueryFn, MigrationInfo, MigrationFile, MigrationError2 as MigrationError, MigrateStatusResult, MigrateStatusOptions, MigrateDevResult, MigrateDevOptions, MigrateDeployResult, MigrateDeployOptions, ListOptions, JsonbValidator, InvalidRelation, InvalidFilterType, InvalidColumn, InsertInput, InferColumnType, IndexDef, IncludeResolve, IncludeOption, HttpErrorResponse, FormatMeta, ForeignKeyErrorOptions, ForeignKeyError, FindResult, FindOptions, FilterType, EnumMeta, EntityDbAdapter, DriftEntry, Dialect, DiagnosticResult, DecimalMeta, DbQueryError, DbNotFoundError, DbErrorJson, DbErrorCodeValue, DbErrorCodeName, DbErrorCode, DbErrorBase, DbError, DbDriver, DbConstraintError, DbConnectionError, DatabaseInternals, DatabaseClient, Database, D1PreparedStatement, D1DatabaseBinding, D1AdapterOptions, CreateDbOptions, ConnectionPoolExhaustedError, ConnectionError, ColumnTypeMeta, ColumnMetadata, ColumnBuilder, CodeChange, CheckConstraintErrorOptions, CheckConstraintError, BaselineResult, BaselineOptions };