@facilis.dev/db 0.0.0-stage → 0.1.1

package/dist/snapshot.d.ts

@@ -0,0 +1,92 @@
+import type { FacilisDb } from "./client.js";
+/** SPEC §7.3 taxonomy. Core re-exports these types as the manifest contract. */
+export type PolicyCommand = "SELECT" | "INSERT" | "UPDATE" | "DELETE" | "ALL";
+export interface PolicySnapshot {
+    name: string;
+    command: PolicyCommand;
+    using: string | null;
+    withCheck: string | null;
+    sql: string;
+}
+export interface ColumnSnapshot {
+    name: string;
+    type: string;
+    notNull: boolean;
+    default: string | null;
+    isPrimaryKey: boolean;
+    isUnique: boolean;
+    /**
+     * Identity columns are readable but not renderable by the v1 generator
+     * (`GENERATED ... AS IDENTITY` sequence options are lost in this projection), so the
+     * flag is carried and the P2 planner refuses instead of writing a plain column.
+     */
+    identity?: "always" | "byDefault";
+    /** Generated/computed columns: same fail-closed treatment, no faithful v1 DDL. */
+    generated?: true;
+}
+export interface ForeignKeySnapshot {
+    columns: string[];
+    targetTable: string;
+    targetColumns: string[];
+    onDelete?: "cascade" | "set null" | "restrict" | "no action";
+    onUpdate?: "cascade" | "set null" | "restrict" | "no action";
+}
+export interface IndexSnapshot {
+    name: string;
+    /** Plain column names only; any other index shape lands in `unsupported`. */
+    columns: string[];
+    unique: boolean;
+}
+export interface CheckSnapshot {
+    name: string;
+    /** Rendered with PgDialect, like `default`; columns may stay table-qualified. */
+    expression: string;
+}
+/** A table-level `unique()`, distinct from a column's `isUnique`. */
+export interface UniqueConstraintSnapshot {
+    name: string;
+    columns: string[];
+}
+export interface EnumSnapshot {
+    name: string;
+    values: string[];
+}
+/**
+ * A declaration the snapshot can read but the v1 shapes above cannot represent (expression,
+ * partial or method-specific indexes; `ON DELETE SET DEFAULT`). It is carried, never
+ * dropped, so the P2 generator can fail the release closed instead of silently ignoring it
+ * (D-158: an unsupported declaration fails the release, never degrades silently).
+ */
+export interface UnsupportedDeclarationSnapshot {
+    construct: "index" | "foreign_key";
+    name: string;
+}
+export interface ScopeColumnSnapshot {
+    name: string;
+    kind: "tenant" | "owner";
+}
+export interface TableSnapshot {
+    name: string;
+    rlsEnabled: boolean;
+    columns: ColumnSnapshot[];
+    foreignKeys: ForeignKeySnapshot[];
+    policies: PolicySnapshot[];
+    scopeColumn?: ScopeColumnSnapshot;
+    /** Ordered column names of the primary key; empty when the table has none. */
+    primaryKey?: string[];
+    indexes?: IndexSnapshot[];
+    checks?: CheckSnapshot[];
+    uniqueConstraints?: UniqueConstraintSnapshot[];
+    unsupported?: UnsupportedDeclarationSnapshot[];
+}
+export interface SchemaSnapshot {
+    tables: TableSnapshot[];
+    /** Enum types referenced by columns, deduped by name. */
+    enums?: EnumSnapshot[];
+}
+/**
+ * Derives the SPEC §7.3 schema snapshot from the Drizzle schema namespace passed to
+ * `createDb`. No database round-trip: the code schema is the source of truth, as in
+ * SPEC §11.1's code↔live comparison.
+ */
+export declare function schemaSnapshot(db: FacilisDb): Promise<SchemaSnapshot>;

package/dist/snapshot.js

@@ -0,0 +1,21 @@
+import { is } from "drizzle-orm";
+import { PgTable } from "drizzle-orm/pg-core";
+import { snapshotTable } from "./snapshot-readers.js";
+/**
+ * Derives the SPEC §7.3 schema snapshot from the Drizzle schema namespace passed to
+ * `createDb`. No database round-trip: the code schema is the source of truth, as in
+ * SPEC §11.1's code↔live comparison.
+ */
+export async function schemaSnapshot(db) {
+    const enums = new Map();
+    const tables = Object.values(db.schema)
+        .filter((value) => is(value, PgTable))
+        .map((table) => snapshotTable(table, enums))
+        .toSorted((left, right) => left.name.localeCompare(right.name));
+    return {
+        tables,
+        enums: [...enums.entries()]
+            .map(([name, values]) => ({ name, values }))
+            .toSorted((left, right) => left.name.localeCompare(right.name)),
+    };
+}

package/dist/sudo-audit.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Sudo audit trail (D-099).
+ *
+ * A sudo escalation is recorded on a dedicated, append-only sink, never in the database:
+ * the trail must survive the transaction rollback it describes, and the framework has no
+ * update/delete operation for it. The default sink is stdout (one JSON line per event) so a
+ * deploy's log platform can ship it to WORM/retention storage; tests swap the sink.
+ *
+ * Fail closed: if the sink throws, the escalation must not happen, so writeSudoAudit throws
+ * a SudoAuditUnavailableError and the caller refuses to switch roles.
+ */
+export type SudoAuditEventName = "started" | "succeeded" | "failed";
+/** One immutable audit entry. `id` is shared by every entry of the same sudo call. */
+export interface SudoAuditEvent {
+    readonly event: SudoAuditEventName;
+    /** Shared call id; also written to the app.sudo_id GUC while the role is elevated. */
+    readonly id: string;
+    /** ISO-8601 timestamp of the append (not of the call start). */
+    readonly at: string;
+    /** Acting user id; absent for a system job (actor is the label). */
+    readonly actorUserId?: string;
+    /** "user:<id>" for a route session, "system:<job>" for a job/CLI caller. */
+    readonly actor: string;
+    /** SHA-256 of the session id; the raw cookie/token is never logged. */
+    readonly sessionHash?: string;
+    readonly roles: readonly string[];
+    readonly tenantId?: string;
+    /** Request pathname, e.g. "/api/order-requests". */
+    readonly route?: string;
+    /** Request method, when known. */
+    readonly method?: string;
+    /** The route's declared permission (the first one), for context. */
+    readonly permission?: string;
+    readonly operation: string;
+    readonly reason: string;
+    readonly tables: readonly string[];
+    /** Succeeded entries: the declared tables the elevated callback actually reached (D-157). */
+    readonly observedTables?: readonly string[];
+    readonly requestId?: string;
+    /** Terminal entries only: how the elevated block ended. */
+    readonly outcome?: "succeeded" | "failed";
+    /** Terminal failure entries: canonical code, never the internal message. */
+    readonly errorCode?: string;
+    readonly durationMs?: number;
+}
+/** Appends one entry. Synchronous by design: a sink cannot silently promise to log later. */
+export type SudoAuditSink = (event: SudoAuditEvent) => void;
+/** Thrown when the audit sink is not writable; sudo refuses to escalate untraced. */
+export declare class SudoAuditUnavailableError extends Error {
+    readonly code = "sudo_audit_unavailable";
+    constructor(cause: unknown);
+}
+/** New call id: WebCrypto randomUUID (available in Node and the browser VM alike). */
+export declare function newSudoId(): string;
+/** Replaces the process-wide sink (tests/tooling). Production leaves the stdout default. */
+export declare function setSudoAuditSink(next: SudoAuditSink): void;
+/** Restores the default stdout sink. */
+export declare function resetSudoAuditSink(): void;
+/** Append one entry, failing closed: a broken sink throws instead of dropping the trail. */
+export declare function writeSudoAudit(event: SudoAuditEvent): void;

package/dist/sudo-audit.js

@@ -0,0 +1,45 @@
+/**
+ * Sudo audit trail (D-099).
+ *
+ * A sudo escalation is recorded on a dedicated, append-only sink, never in the database:
+ * the trail must survive the transaction rollback it describes, and the framework has no
+ * update/delete operation for it. The default sink is stdout (one JSON line per event) so a
+ * deploy's log platform can ship it to WORM/retention storage; tests swap the sink.
+ *
+ * Fail closed: if the sink throws, the escalation must not happen, so writeSudoAudit throws
+ * a SudoAuditUnavailableError and the caller refuses to switch roles.
+ */
+/** Thrown when the audit sink is not writable; sudo refuses to escalate untraced. */
+export class SudoAuditUnavailableError extends Error {
+    code = "sudo_audit_unavailable";
+    constructor(cause) {
+        super("The sudo audit sink is not writable; refusing to escalate a database call.", { cause });
+        this.name = "SudoAuditUnavailableError";
+    }
+}
+/** New call id: WebCrypto randomUUID (available in Node and the browser VM alike). */
+export function newSudoId() {
+    return globalThis.crypto.randomUUID();
+}
+const consoleSink = (event) => {
+    // oxlint-disable-next-line no-console -- the default audit sink IS stdout: one JSON line per entry for the deploy's log pipeline.
+    console.log("facilis:sudo " + JSON.stringify(event));
+};
+let sink = consoleSink;
+/** Replaces the process-wide sink (tests/tooling). Production leaves the stdout default. */
+export function setSudoAuditSink(next) {
+    sink = next;
+}
+/** Restores the default stdout sink. */
+export function resetSudoAuditSink() {
+    sink = consoleSink;
+}
+/** Append one entry, failing closed: a broken sink throws instead of dropping the trail. */
+export function writeSudoAudit(event) {
+    try {
+        sink(event);
+    }
+    catch (cause) {
+        throw new SudoAuditUnavailableError(cause);
+    }
+}

package/dist/sudo.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Audited sudo (D-099): run a block of code in the current transaction as the framework's
+ * `facilis_system` Postgres role.
+ *
+ * The system role is the one named exception to SPEC §8.4.5's "no Postgres roles" rule: it
+ * is NOLOGIN, NOSUPERUSER with BYPASSRLS and DML grants only (no DDL), it is never assigned
+ * to users and never referenced by policies, and it is reachable only through this module.
+ * Every escalation is recorded on the append-only audit sink first (fail closed), then in
+ * the SAVEPOINT, so a crash between entries leaves a visible trace instead of a silent one.
+ */
+import type { FacilisDb } from "./client.js";
+import { type PolicyScopedDatabase } from "./policy.js";
+/** The elevated Postgres role; provisioned by `ensureSystemRole` (dev) or the deploy step. */
+export declare const SYSTEM_ROLE = "facilis_system";
+/** GUC carrying the audit call id while a sudo block runs. Not a provenance column. */
+export declare const SUDO_ID_GUC = "app.sudo_id";
+/**
+ * Creates the system role and grants it DML on the public schema, plus membership to
+ * facilis_app (production connects as the app role and must be able to SET ROLE). Idempotent
+ * and re-asserting, like ensureAppRole: an older dataDir must not keep weaker attributes.
+ */
+export declare function ensureSystemRole(db: FacilisDb): Promise<void>;
+export interface RunWithSystemRoleOptions {
+    /** Audit call id, exposed as app.sudo_id for correlation inside the block. */
+    readonly sudoId: string;
+}
+/**
+ * Runs `fn` in a SAVEPOINT of the current transaction as facilis_system.
+ *
+ * On success the role is restored to facilis_app explicitly: RESET ROLE would return to the
+ * connecting session user (a superuser in dev) and silently widen the rest of the request.
+ * On failure the savepoint rollback restores both the role and the GUCs.
+ */
+export declare function runWithSystemRole<T>(db: PolicyScopedDatabase, options: RunWithSystemRoleOptions, fn: (systemDb: PolicyScopedDatabase) => Promise<T>): Promise<T>;
+export interface RunAsSystemOptions {
+    /** Audit actor label for a job/CLI caller, e.g. "system:nightly-reindex". */
+    readonly actor: `system:${string}`;
+    readonly operation: string;
+    readonly reason: string;
+    /**
+     * The job's declared tables and views (SQL names), possibly empty. The elevated client is
+     * guarded by this declaration, not by whatever the system role happens to reach (D-157).
+     */
+    readonly dbTables: readonly string[];
+    /** Explicit exception for raw SQL inside the job (D-157); default false. */
+    readonly rawSql?: boolean;
+    /** Correlation id when the job was triggered by a request. */
+    readonly requestId?: string;
+}
+/**
+ * Runs `fn` in its own transaction as facilis_system, audited like `ctx.sudo`, and returns
+ * its result. This is the job/CLI counterpart of the route context's sudo.
+ */
+export declare function runAsSystem<T>(db: FacilisDb, options: RunAsSystemOptions, fn: (systemDb: PolicyScopedDatabase) => Promise<T>): Promise<T>;

package/dist/sudo.js

@@ -0,0 +1,137 @@
+/**
+ * Audited sudo (D-099): run a block of code in the current transaction as the framework's
+ * `facilis_system` Postgres role.
+ *
+ * The system role is the one named exception to SPEC §8.4.5's "no Postgres roles" rule: it
+ * is NOLOGIN, NOSUPERUSER with BYPASSRLS and DML grants only (no DDL), it is never assigned
+ * to users and never referenced by policies, and it is reachable only through this module.
+ * Every escalation is recorded on the append-only audit sink first (fail closed), then in
+ * the SAVEPOINT, so a crash between entries leaves a visible trace instead of a silent one.
+ */
+import { sql } from "drizzle-orm";
+import { APP_ROLE } from "./policy.js";
+import { newSudoId, writeSudoAudit } from "./sudo-audit.js";
+import { guardDatabase, TableAccessError } from "./table-guard.js";
+/** The elevated Postgres role; provisioned by `ensureSystemRole` (dev) or the deploy step. */
+export const SYSTEM_ROLE = "facilis_system";
+/** GUC carrying the audit call id while a sudo block runs. Not a provenance column. */
+export const SUDO_ID_GUC = "app.sudo_id";
+/**
+ * Creates the system role and grants it DML on the public schema, plus membership to
+ * facilis_app (production connects as the app role and must be able to SET ROLE). Idempotent
+ * and re-asserting, like ensureAppRole: an older dataDir must not keep weaker attributes.
+ */
+export async function ensureSystemRole(db) {
+    const existing = await db.db.execute(sql `select 1 from pg_roles where rolname = ${SYSTEM_ROLE}`);
+    if (existing.rows.length === 0) {
+        await db.db.execute(sql.raw(`CREATE ROLE ${SYSTEM_ROLE} NOLOGIN NOSUPERUSER BYPASSRLS`));
+    }
+    // Re-assert attributes in case an older dev dataDir created the role differently.
+    await db.db.execute(sql.raw(`ALTER ROLE ${SYSTEM_ROLE} NOSUPERUSER BYPASSRLS NOLOGIN`));
+    await db.db.execute(sql.raw(`GRANT USAGE ON SCHEMA public TO ${SYSTEM_ROLE}`));
+    await db.db.execute(sql.raw(`GRANT SELECT, INSERT, UPDATE, DELETE ON ALL TABLES IN SCHEMA public TO ${SYSTEM_ROLE}`));
+    await db.db.execute(sql.raw(`ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT SELECT, INSERT, UPDATE, DELETE ON TABLES TO ${SYSTEM_ROLE}`));
+    await db.db.execute(sql.raw(`GRANT USAGE, SELECT ON ALL SEQUENCES IN SCHEMA public TO ${SYSTEM_ROLE}`));
+    await db.db.execute(sql.raw(`ALTER DEFAULT PRIVILEGES IN SCHEMA public GRANT USAGE, SELECT ON SEQUENCES TO ${SYSTEM_ROLE}`));
+    // The runtime may connect as facilis_app: membership is what lets it SET ROLE.
+    await db.db.execute(sql.raw(`GRANT ${SYSTEM_ROLE} TO ${APP_ROLE}`));
+}
+/**
+ * Runs `fn` in a SAVEPOINT of the current transaction as facilis_system.
+ *
+ * On success the role is restored to facilis_app explicitly: RESET ROLE would return to the
+ * connecting session user (a superuser in dev) and silently widen the rest of the request.
+ * On failure the savepoint rollback restores both the role and the GUCs.
+ */
+export async function runWithSystemRole(db, options, fn) {
+    return db.transaction(async (tx) => {
+        await tx.execute(sql.raw(`SET LOCAL ROLE ${SYSTEM_ROLE}`));
+        await tx.execute(sql `select set_config('app.sudo_id', ${options.sudoId}, true)`);
+        const result = await fn(tx);
+        await tx.execute(sql.raw(`SET LOCAL ROLE ${APP_ROLE}`));
+        await tx.execute(sql `select set_config('app.sudo_id', '', true)`);
+        return result;
+    });
+}
+/**
+ * Runs `fn` in its own transaction as facilis_system, audited like `ctx.sudo`, and returns
+ * its result. This is the job/CLI counterpart of the route context's sudo.
+ */
+export async function runAsSystem(db, options, fn) {
+    assertSystemRunOptions(options);
+    const id = newSudoId();
+    const startedAt = Date.now();
+    // Relations the guarded client actually reached; only declared ones can get this far.
+    const observed = new Set();
+    const base = {
+        id,
+        actor: options.actor,
+        roles: [],
+        operation: options.operation,
+        reason: options.reason,
+        tables: options.dbTables,
+        ...(options.requestId === undefined ? {} : { requestId: options.requestId }),
+    };
+    writeSudoAudit({ ...base, event: "started", at: new Date().toISOString() });
+    try {
+        const result = await db.db.transaction((tx) => runWithSystemRole(tx, { sudoId: id }, (systemDb) => fn(guardDatabase(systemDb, {
+            declared: options.dbTables,
+            allowRawSql: options.rawSql === true,
+            onRelation: (relation) => observed.add(relation),
+        }))));
+        writeSudoAudit({
+            ...base,
+            event: "succeeded",
+            outcome: "succeeded",
+            observedTables: [...observed],
+            at: new Date().toISOString(),
+            durationMs: Date.now() - startedAt,
+        });
+        return result;
+    }
+    catch (error) {
+        // Canonical code only: the internal message may name the relation, which is not audited.
+        writeSudoAudit({
+            ...base,
+            event: "failed",
+            outcome: "failed",
+            at: new Date().toISOString(),
+            errorCode: error instanceof TableAccessError ? error.code : "handler_failed",
+            durationMs: Date.now() - startedAt,
+        });
+        throw error;
+    }
+}
+/**
+ * Rejects a job call that could not produce a meaningful audit entry.
+ *
+ * An empty `dbTables` list is deliberately allowed here (D-107): a job may declare that it
+ * touches no relation, and it is the only caller permitted to do so — `ctx.sudo`/`ctx.system`
+ * still reject an empty subset in @facilis.dev/core. The declaration is enforced by the guard.
+ */
+function assertSystemRunOptions(options) {
+    if (typeof options.actor !== "string" || !options.actor.startsWith("system:")) {
+        throw new Error('sudo_invalid_actor: actor must be "system:<job>" for a system run.');
+    }
+    if (typeof options.operation !== "string" || options.operation.trim().length === 0) {
+        throw new Error("sudo_invalid_operation: operation must be a non-empty string.");
+    }
+    if (typeof options.reason !== "string" || options.reason.trim().length === 0) {
+        throw new Error("sudo_invalid_reason: reason must be a non-empty string.");
+    }
+    if (!isStringList(options.dbTables)) {
+        throw new Error("sudo_invalid_dbTables: dbTables must be an array of non-empty strings (possibly empty).");
+    }
+    if (options.rawSql !== undefined && typeof options.rawSql !== "boolean") {
+        throw new Error("sudo_invalid_rawSql: rawSql must be a boolean when present.");
+    }
+}
+/**
+ * An array of non-empty strings, possibly empty: a job that declares no relation still
+ * produces a valid audit entry (D-107). The empty case is left to the caller's policy, so
+ * runAsSystem can accept it while the route-scoped sudo keeps its non-empty subset rule.
+ */
+function isStringList(value) {
+    return (Array.isArray(value) &&
+        value.every((entry) => typeof entry === "string" && entry.length > 0));
+}

package/dist/table-guard.d.ts

@@ -0,0 +1,37 @@
+/**
+ * Runtime enforcement of a route's `dbTables` declaration (D-157).
+ *
+ * The static analyzer can see a route's queries, but only the wrapper sees every relation
+ * the handler actually touches. `guardDatabase` wraps the policy-scoped client in a Proxy:
+ * a relation is checked against the declaration before its query builder runs, so an
+ * incomplete declaration fails closed instead of querying and auditing whatever it likes.
+ *
+ * The wrapper never executes a query itself: it forwards fluent calls to the real Drizzle
+ * builder and only intercepts the next relation-bearing call. Query builders are thenable,
+ * so `then`/`catch`/`finally` are bound to the unwrapped target and awaiting a guarded
+ * builder still runs the original query exactly once.
+ */
+import type { PolicyScopedDatabase } from "./policy.js";
+/** Canonical failure codes of the guard; both are 500s in the core error registry. */
+export type TableAccessErrorCode = "table_not_declared" | "raw_sql_not_allowed";
+/** Thrown before execution when a route reaches outside its declaration. */
+export declare class TableAccessError extends Error {
+    readonly code: TableAccessErrorCode;
+    /** Server-side context only: the route wrapper never puts it in the response body. */
+    readonly relation?: string;
+    constructor(code: TableAccessErrorCode, relation?: string);
+}
+/** What a route exposes to the guard: its declaration plus the audited-observation hook. */
+export interface TableGuardOptions {
+    /** The route's `dbTables` (tables and views, SQL names). */
+    readonly declared: readonly string[];
+    /** `rawSql: true` on the route; only then may `db.execute` run. */
+    readonly allowRawSql?: boolean;
+    /** Called for every declared relation the handler actually reaches (sudo audit, D-157). */
+    readonly onRelation?: (relation: string) => void;
+}
+/**
+ * Wraps a policy-scoped client so every relation is checked against `declared` before the
+ * query executes. The returned value is the same Drizzle transaction surface.
+ */
+export declare function guardDatabase(db: PolicyScopedDatabase, options: TableGuardOptions): PolicyScopedDatabase;

package/dist/table-guard.js

@@ -0,0 +1,228 @@
+/**
+ * Runtime enforcement of a route's `dbTables` declaration (D-157).
+ *
+ * The static analyzer can see a route's queries, but only the wrapper sees every relation
+ * the handler actually touches. `guardDatabase` wraps the policy-scoped client in a Proxy:
+ * a relation is checked against the declaration before its query builder runs, so an
+ * incomplete declaration fails closed instead of querying and auditing whatever it likes.
+ *
+ * The wrapper never executes a query itself: it forwards fluent calls to the real Drizzle
+ * builder and only intercepts the next relation-bearing call. Query builders are thenable,
+ * so `then`/`catch`/`finally` are bound to the unwrapped target and awaiting a guarded
+ * builder still runs the original query exactly once.
+ */
+import { Column, Table, ViewBaseConfig, getTableName, getViewName, is, isView } from "drizzle-orm";
+/** Thrown before execution when a route reaches outside its declaration. */
+export class TableAccessError extends Error {
+    code;
+    /** Server-side context only: the route wrapper never puts it in the response body. */
+    relation;
+    constructor(code, relation) {
+        super(code === "raw_sql_not_allowed"
+            ? "db.execute is not allowed: the route must declare rawSql: true."
+            : `Relation "${relation ?? "unknown"}" is not declared in the route's dbTables.`);
+        this.name = "TableAccessError";
+        this.code = code;
+        if (relation !== undefined)
+            this.relation = relation;
+    }
+}
+/** Calls that take a relation and must be checked before the builder runs. */
+const RELATION_METHODS = new Set([
+    "select",
+    "selectDistinct",
+    "insert",
+    "update",
+    "delete",
+    "from",
+    "join",
+    "leftJoin",
+    "rightJoin",
+    "innerJoin",
+    "fullJoin",
+    "into",
+]);
+/** Query-builder promise methods: bound to the real builder, never wrapped as fluent calls. */
+const THEN_METHODS = new Set(["then", "catch", "finally"]);
+/** Runtime table symbols; Drizzle 0.45 omits its `Table.Symbol` from the declarations. */
+const TABLE_SYMBOLS = Table.Symbol;
+/**
+ * Wraps a policy-scoped client so every relation is checked against `declared` before the
+ * query executes. The returned value is the same Drizzle transaction surface.
+ */
+export function guardDatabase(db, options) {
+    const state = {
+        declared: new Set(options.declared),
+        allowRawSql: options.allowRawSql === true,
+        onRelation: options.onRelation,
+        proxies: new WeakMap(),
+        targets: new WeakMap(),
+        rawSqlUsed: false,
+    };
+    return wrapSurface(db, "db", state);
+}
+function wrapSurface(target, kind, state) {
+    const wrapped = state.proxies.get(target);
+    if (wrapped !== undefined)
+        return wrapped;
+    const proxy = new Proxy(target, createHandler(state, kind));
+    state.proxies.set(target, proxy);
+    state.targets.set(proxy, target);
+    return proxy;
+}
+function createHandler(state, kind) {
+    return {
+        get(target, property) {
+            const value = Reflect.get(target, property);
+            // Awaiting a guarded builder must call the real builder's then/catch/finally.
+            if (typeof property === "string" && THEN_METHODS.has(property)) {
+                return typeof value === "function"
+                    ? value.bind(target)
+                    : value;
+            }
+            // The relational API is keyed by relation: validate before handing out the builder.
+            if (kind === "db" && property === "query") {
+                return isObject(value) ? wrapSurface(value, "query", state) : value;
+            }
+            if (kind === "query" && typeof property === "string") {
+                if (!isObject(value))
+                    return value;
+                const relation = relationFromQueryEntry(value) ?? property;
+                observe(relation, state);
+                return wrapSurface(value, "relation", state);
+            }
+            // The raw driver escape hatches are exactly the SQL the declaration cannot describe.
+            if (kind === "db" &&
+                !state.allowRawSql &&
+                (property === "$client" || property === "session")) {
+                throw new TableAccessError("raw_sql_not_allowed");
+            }
+            if (typeof value !== "function")
+                return value;
+            return createMethod(target, property, value, kind, state);
+        },
+    };
+}
+function createMethod(target, property, method, kind, state) {
+    return (...args) => {
+        if (kind === "db" && property === "execute") {
+            if (!state.allowRawSql)
+                throw new TableAccessError("raw_sql_not_allowed");
+            state.rawSqlUsed = true;
+        }
+        if (kind === "db" && property === "transaction") {
+            return runTransaction(target, method, args, state);
+        }
+        if (typeof property === "string" && RELATION_METHODS.has(property)) {
+            for (const arg of args)
+                observeArgument(arg, state);
+        }
+        const result = Reflect.apply(method, target, unwrapArgs(args, state));
+        return wrapResult(result, target, state);
+    };
+}
+/** Runs the callback with a guarded nested transaction; the query itself still executes once. */
+function runTransaction(target, method, args, state) {
+    const [callback, ...rest] = args;
+    if (typeof callback !== "function") {
+        return Reflect.apply(method, target, unwrapArgs(args, state));
+    }
+    const wrapped = (tx, ...inner) => callback(isObject(tx) ? wrapSurface(tx, "db", state) : tx, ...inner.map((value) => unwrap(value, state)));
+    return Reflect.apply(method, target, [wrapped, ...unwrapArgs(rest, state)]);
+}
+function wrapResult(result, target, state) {
+    // Drizzle returns `this` from fluent methods: reuse the existing proxy, do not nest.
+    if (result === target)
+        return state.proxies.get(target);
+    if (isObject(result) && isBuilderLike(result))
+        return wrapSurface(result, "builder", state);
+    return result;
+}
+/** Thenable query builders plus the pre-`from` select builder, which is not thenable yet. */
+function isBuilderLike(value) {
+    if (isThenable(value))
+        return true;
+    for (const method of RELATION_METHODS) {
+        if (typeof value[method] === "function")
+            return true;
+    }
+    return false;
+}
+function observeArgument(value, state, seen = new Set()) {
+    if (!isObject(value) || seen.has(value))
+        return;
+    seen.add(value);
+    const relation = relationNameOf(value);
+    if (relation !== null) {
+        observe(relation, state);
+        return;
+    }
+    if (Array.isArray(value)) {
+        for (const item of value)
+            observeArgument(item, state, seen);
+        return;
+    }
+    if (is(value, Column)) {
+        observeArgument(value.table, state, seen);
+        return;
+    }
+    if (isPlainObject(value)) {
+        for (const item of Object.values(value))
+            observeArgument(item, state, seen);
+    }
+}
+function observe(relation, state) {
+    if (!state.declared.has(relation))
+        throw new TableAccessError("table_not_declared", relation);
+    state.onRelation?.(relation);
+}
+/**
+ * SQL name of a relation: aliased tables resolve to their original name, and a view is its
+ * own relation (D-097/D-098), never its base tables.
+ */
+function relationNameOf(value) {
+    if (is(value, Table)) {
+        // Drizzle 0.45 exposes the symbol table at runtime but not in its type declarations.
+        const symbols = Table.Symbol;
+        const table = value;
+        if (table[symbols.IsAlias] === true) {
+            const original = table[symbols.OriginalName];
+            if (typeof original === "string" && original.length > 0)
+                return original;
+        }
+        const name = getTableName(value);
+        return typeof name === "string" && name.length > 0 ? name : null;
+    }
+    if (isView(value)) {
+        const config = value[ViewBaseConfig];
+        if (isObject(config)) {
+            const record = config;
+            const name = record["isAlias"] === true ? (record["originalName"] ?? record["name"]) : record["name"];
+            if (typeof name === "string" && name.length > 0)
+                return name;
+        }
+        const name = getViewName(value);
+        return typeof name === "string" && name.length > 0 ? name : null;
+    }
+    return null;
+}
+function relationFromQueryEntry(value) {
+    const table = value.table;
+    return isObject(table) ? relationNameOf(table) : null;
+}
+function unwrap(value, state) {
+    return isObject(value) ? (state.targets.get(value) ?? value) : value;
+}
+function unwrapArgs(args, state) {
+    return args.map((value) => unwrap(value, state));
+}
+function isThenable(value) {
+    return typeof value.then === "function";
+}
+function isObject(value) {
+    return typeof value === "object" && value !== null;
+}
+function isPlainObject(value) {
+    const prototype = Object.getPrototypeOf(value);
+    return prototype === Object.prototype || prototype === null;
+}