@facilis.dev/db 0.0.0-stage → 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 facilis-dev
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,19 @@
-# Temporary Holding Version
+# @facilis.dev/db
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Facilis database layer: Drizzle + PGlite client, RLS policy helpers and release diffing.
+
+Part of [Facilis](https://github.com/facilis-dev/facilis), a browser-first low-code framework: the Studio
+runs a generated project in a WebContainer where vite dev is the only dev server
+and Nitro v3 runs as a Vite plugin. Framework contracts live in
+[docs/SPEC.md](https://github.com/facilis-dev/facilis/blob/main/docs/SPEC.md) and architectural decisions in
+[docs/DECISIONS.md](https://github.com/facilis-dev/facilis/blob/main/docs/DECISIONS.md).
+
+```sh
+npm install @facilis.dev/db
+```
+
+The package publishes its TypeScript sources and its compiled dist/; the exports map
+of the published manifest points at dist/, so Node and bundlers load JavaScript and
+the bundled .d.ts files.
+
+Licensed under the MIT License.

package/dist/client.d.ts

@@ -0,0 +1,78 @@
+import type { PgDatabase, PgQueryResultHKT } from "drizzle-orm/pg-core";
+/** Drivers the public API promises. Both are implemented; `snapshot()` is PGlite-only. */
+export type DbDriver = "pglite" | "postgres";
+/**
+ * Result kind shared by both drivers. drizzle's abstract `PgQueryResultHKT` only brands the
+ * kind (`type: unknown`), which would degrade every `execute()` result to `unknown`;
+ * PGlite and node-postgres both resolve to a `{ rows }` object, so this HKT restores the
+ * common surface for the driver-agnostic client type.
+ */
+export interface FacilisQueryResultHKT extends PgQueryResultHKT {
+    readonly type: {
+        readonly rows: Record<string, unknown>[];
+    };
+}
+/**
+ * Root Drizzle client type. It is the only Drizzle client type allowed to leak past
+ * this package (AGENTS.md security rule 5 keeps raw Drizzle imports here). Both drivers
+ * cast their concrete client to this base class: the per-driver `$client` is never used
+ * here, so PGlite and node-postgres collapse to the shared Postgres query surface.
+ */
+export type PgDatabaseLike = PgDatabase<FacilisQueryResultHKT, Record<string, unknown>>;
+/** A Drizzle schema namespace, e.g. `import * as schema from "./db/schema.ts"`. */
+export type FacilisSchema = Readonly<Record<string, unknown>>;
+export interface CreateDbOptions {
+    readonly driver?: DbDriver;
+    readonly url?: string;
+    readonly dataDir?: string;
+    /**
+     * Restore a `snapshot()` archive instead of starting from an empty cluster.
+     * Dev persistence (D-052) keeps the cluster in memory and restores it from
+     * `.facilis/db/snapshot.tar.gz`; production uses a real Postgres instead.
+     */
+    readonly loadSnapshot?: Uint8Array;
+    /** Schema namespace used by migrations and by `schemaSnapshot`. */
+    readonly schema?: FacilisSchema;
+    /** Maximum pooled connections for driver "postgres" (`pg.Pool` `max`). Defaults to 10. */
+    readonly poolMax?: number;
+}
+export interface FacilisDb {
+    readonly driver: DbDriver;
+    readonly db: PgDatabaseLike;
+    readonly schema: FacilisSchema;
+    close(): Promise<void>;
+    /**
+     * Monotonic count of client operations (query/exec/transaction). The dev snapshotter
+     * polls this instead of every write: only a cluster that changed is dumped.
+     */
+    activity(): number;
+    /**
+     * Serialize the whole cluster as the gzip tar the `loadSnapshot` option restores.
+     * Only driver "pglite" can dump itself; driver "postgres" throws SnapshotUnavailableError.
+     */
+    snapshot(): Promise<Uint8Array>;
+}
+/** Column names treated as tenant scopes (SPEC §7.1 Appendix B defaults). */
+export declare const DEFAULT_TENANT_COLUMNS: readonly string[];
+/** Column names treated as per-row owner scopes (SPEC §7.1 Appendix B defaults). */
+export declare const DEFAULT_OWNER_COLUMNS: readonly string[];
+/** Thrown for a driver id that neither branch below can serve. */
+export declare class DriverNotImplementedError extends Error {
+    readonly code = "driver_not_implemented";
+    constructor(driver: DbDriver);
+}
+/** Thrown instead of resolving when the postgres pool cannot be opened or probed. */
+export declare class DbConnectionError extends Error {
+    readonly code = "db_connection_failed";
+    constructor(cause: unknown);
+}
+/** Thrown by snapshot() on a driver that has no hot cluster dump. */
+export declare class SnapshotUnavailableError extends Error {
+    readonly code = "snapshot_unavailable";
+    constructor();
+}
+/**
+ * Opens the Facilis database. An explicit `url` without a driver means "postgres";
+ * `driver: "pglite"` is the embedded, in-memory or `dataDir` cluster.
+ */
+export declare function createDb(options?: CreateDbOptions): Promise<FacilisDb>;

package/dist/client.js

@@ -0,0 +1,208 @@
+import { createRequire } from "node:module";
+import { join } from "node:path";
+import { drizzle } from "drizzle-orm/pglite";
+/**
+ * PGlite must come from its CJS build (vendor/vivari/AGENTS.md, "In-VM databases"):
+ * the ESM build locates `pglite.wasm` and `pglite.data` through `import.meta.url`, and
+ * that URL is only as good as the module id the bundler handed the module. A relative id
+ * becomes `file://home/…` — the first segment parses as a URL *host* — so the resolved
+ * path loses `/home` (`/user/projects/…`) and the DB cannot boot with ENOENT. The CJS
+ * build resolves the same artifacts from `__filename`, a real VFS path, through
+ * `new URL("file:" + __filename)` = `file:/home/…`; the pinned runtime converts that back
+ * to the intended path even where the browser parses it as hostful, i.e. on Chrome/Windows
+ * (fork `e654919`, D-039 and D-041).
+ *
+ * Two resolution bases: this module's own URL (works in Node and under Vitest), then the
+ * project root, which is the cwd the in-VM Nitro dev server runs in.
+ */
+function loadPglite() {
+    let lastError;
+    for (const base of [import.meta.url, join(process.cwd(), "package.json")]) {
+        try {
+            return createRequire(base)("@electric-sql/pglite");
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new Error("facilis: cannot load @electric-sql/pglite — is it installed?", {
+        cause: lastError,
+    });
+}
+const { PGlite } = loadPglite();
+/** Column names treated as tenant scopes (SPEC §7.1 Appendix B defaults). */
+export const DEFAULT_TENANT_COLUMNS = ["tenantId", "tenant_id"];
+/** Column names treated as per-row owner scopes (SPEC §7.1 Appendix B defaults). */
+export const DEFAULT_OWNER_COLUMNS = [
+    "ownerId",
+    "owner_id",
+    "userId",
+    "user_id",
+];
+/** Thrown for a driver id that neither branch below can serve. */
+export class DriverNotImplementedError extends Error {
+    code = "driver_not_implemented";
+    constructor(driver) {
+        super(`The "${driver}" driver is not implemented; use driver "pglite" or "postgres".`);
+        this.name = "DriverNotImplementedError";
+    }
+}
+/** Thrown instead of resolving when the postgres pool cannot be opened or probed. */
+export class DbConnectionError extends Error {
+    code = "db_connection_failed";
+    constructor(cause) {
+        // The connection string may embed a password, so neither it nor the driver message
+        // (which repeats host/port) is forwarded into the public message.
+        super("The postgres driver could not connect; check the database settings.", { cause });
+        this.name = "DbConnectionError";
+    }
+}
+/** Thrown by snapshot() on a driver that has no hot cluster dump. */
+export class SnapshotUnavailableError extends Error {
+    code = "snapshot_unavailable";
+    constructor() {
+        super('The postgres driver has no cluster dump; snapshot() is available only for "pglite".');
+        this.name = "SnapshotUnavailableError";
+    }
+}
+/**
+ * Opens the Facilis database. An explicit `url` without a driver means "postgres";
+ * `driver: "pglite"` is the embedded, in-memory or `dataDir` cluster.
+ */
+export async function createDb(options = {}) {
+    const driver = options.driver ?? (options.url === undefined ? "pglite" : "postgres");
+    // facilis.config.ts is user code and may be plain JavaScript, so re-check the union.
+    if (driver !== "pglite" && driver !== "postgres")
+        throw new DriverNotImplementedError(driver);
+    return driver === "postgres" ? openPostgresDb(options) : openPgliteDb(options);
+}
+async function openPgliteDb(options) {
+    const client = await openPglite(options);
+    const activity = { count: 0 };
+    // Drizzle talks to this facade; counting here is the only reliable "did the cluster
+    // change since the last dump" signal, because PGlite exposes no change hook. Methods
+    // are bound to the real client so `this` and the WASM instance are untouched.
+    const tracked = new Proxy(client, {
+        get(target, property, receiver) {
+            const value = Reflect.get(target, property, receiver);
+            if (typeof value !== "function")
+                return value;
+            if (property === "query" || property === "exec" || property === "transaction") {
+                return (...args) => {
+                    activity.count += 1;
+                    return value.apply(target, args);
+                };
+            }
+            return value.bind(target);
+        },
+    });
+    return {
+        driver: "pglite",
+        db: createPgliteDrizzleClient(tracked, options.schema),
+        schema: options.schema ?? {},
+        activity: () => activity.count,
+        async snapshot() {
+            const dump = await client.dumpDataDir("gzip");
+            return new Uint8Array(await dump.arrayBuffer());
+        },
+        async close() {
+            await client.close();
+        },
+    };
+}
+async function openPostgresDb(options) {
+    const { pg, drizzle: drizzlePg } = loadPostgres();
+    const url = options.url;
+    if (url === undefined)
+        throw new DbConnectionError(new Error("no connection url was provided"));
+    const pool = new pg.Pool({
+        connectionString: url,
+        max: options.poolMax ?? 10,
+        application_name: "facilis",
+        // TLS comes from the connection string (e.g. ?sslmode=require) and pg parses it there;
+        // this layer must not re-implement it.
+    });
+    try {
+        // The pool is lazy: without the probe a bad URL would resolve createDb and only fail
+        // on the first request, which the framework treats as a runtime bug instead of config.
+        await pool.query("select 1");
+    }
+    catch (cause) {
+        // The failed probe leaves the pool unusable; draining it is best effort.
+        await pool.end().catch(() => undefined);
+        throw new DbConnectionError(cause);
+    }
+    const schema = options.schema;
+    // Same generic collapse as the PGlite client: callers get builders from their tables.
+    const db = (schema === undefined
+        ? drizzlePg(pool)
+        : drizzlePg(pool, { schema: { ...schema } }));
+    return {
+        driver: "postgres",
+        db,
+        schema: schema ?? {},
+        // The dev snapshotter (D-052) is installed only for driver "pglite" and polls that
+        // client's counter; a remote Postgres cluster has no equivalent hook.
+        activity: () => 0,
+        async snapshot() {
+            throw new SnapshotUnavailableError();
+        },
+        async close() {
+            await pool.end();
+        },
+    };
+}
+/**
+ * Open the PGlite cluster: from a dev snapshot when one is supplied, else from
+ * `dataDir`, else empty.
+ *
+ * The restore goes through the documented static `create({ loadDataDir })`: the
+ * constructor overload accepts the option but does not wire it (measured), and a
+ * silently empty restore is the one failure a dev database must not have.
+ */
+async function openPglite(options) {
+    const snapshot = options.loadSnapshot;
+    if (snapshot !== undefined && snapshot.length > 0) {
+        // Copy into a plain ArrayBuffer-backed view: a Uint8Array<ArrayBufferLike> is not a
+        // BlobPart (its buffer could be a SharedArrayBuffer), and the archive is small.
+        const bytes = new Uint8Array(snapshot.byteLength);
+        bytes.set(snapshot);
+        return (await PGlite.create({
+            loadDataDir: new Blob([bytes]),
+        }));
+    }
+    const client = options.dataDir === undefined ? new PGlite() : new PGlite(options.dataDir);
+    // PGlite boots lazily; awaiting the ready promise makes createDb's contract truthful.
+    await client.waitReady;
+    return client;
+}
+function createPgliteDrizzleClient(client, schema) {
+    // The cast collapses Drizzle's schema-dependent generics: @facilis.dev/db does not consume
+    // the relational query API, and callers get typed query builders from their table objects.
+    if (schema === undefined)
+        return drizzle(client);
+    return drizzle(client, { schema: { ...schema } });
+}
+/**
+ * `pg` (node:net/node:tls) and drizzle's node-postgres driver are loaded lazily: the
+ * generated project runs server code inside a WebContainer, where the postgres branch is
+ * inert, and a static import would drag Node's socket stack into the in-VM bundle. Same
+ * two resolution bases as loadPglite: this module's URL, then the project root.
+ */
+function loadPostgres() {
+    let lastError;
+    for (const base of [import.meta.url, join(process.cwd(), "package.json")]) {
+        try {
+            const require = createRequire(base);
+            const pg = require("pg");
+            const driver = require("drizzle-orm/node-postgres");
+            return { pg, drizzle: driver.drizzle };
+        }
+        catch (error) {
+            lastError = error;
+        }
+    }
+    throw new Error("facilis: cannot load pg / drizzle-orm/node-postgres — are they installed?", {
+        cause: lastError,
+    });
+}

package/dist/files.d.ts

@@ -0,0 +1,268 @@
+import { type PgColumn, type PgTable } from "drizzle-orm/pg-core";
+/**
+ * One uploaded file's metadata. The uniqueness of `hash` is a storage concern (the local
+ * driver and S3 both address by content), so the same bytes may have several rows with
+ * different names/mime types.
+ *
+ * Access to the bytes is decided by the routes that issue signed URLs, not by a per-row
+ * owner policy here: tenant isolation is the structural boundary, and a file attached to
+ * an entity is readable by whoever can read that entity. `owner_id` is the audit/issuer
+ * identity (and the owner check the upload route uses).
+ */
+export declare const facilisFiles: Omit<import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "facilis_files";
+    schema: undefined;
+    columns: {
+        id: PgColumn<{
+            name: "id";
+            tableName: "facilis_files";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        hash: PgColumn<{
+            name: "hash";
+            tableName: "facilis_files";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        name: PgColumn<{
+            name: "name";
+            tableName: "facilis_files";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        mime: PgColumn<{
+            name: "mime";
+            tableName: "facilis_files";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        size: PgColumn<{
+            name: "size";
+            tableName: "facilis_files";
+            dataType: "number";
+            columnType: "PgBigInt53";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tenantId: PgColumn<{
+            name: string;
+            tableName: "facilis_files";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        ownerId: PgColumn<{
+            name: "owner_id";
+            tableName: "facilis_files";
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: PgColumn<{
+            name: "created_at";
+            tableName: "facilis_files";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>, "enableRLS">;
+export type FacilisFile = typeof facilisFiles.$inferSelect;
+export type NewFacilisFile = typeof facilisFiles.$inferInsert;
+export interface FileLinksOptions {
+    /** Name of the generated link table, e.g. "todo_files". */
+    readonly table: string;
+    /** FK column name in the link table, e.g. "todo_id". Defaults to "parent_id". */
+    readonly column?: string;
+}
+/**
+ * Build the link table that lets one application table contain files.
+ *
+ * ```ts
+ * export const todoFiles = fileLinks(todos, { table: "todo_files", column: "todo_id" });
+ * ```
+ *
+ * The parent needs a single-column primary key (uuid recommended: the FK is a uuid). The
+ * generated table carries a restrictive tenant policy and a permissive `parent_access`
+ * policy: `EXISTS (SELECT 1 FROM parent WHERE parent.pk = link.parent_id)`. Postgres
+ * evaluates that subquery under the caller's role, so the parent table's policies decide
+ * visibility — the link inherits the parent's access rules instead of restating them.
+ */
+export declare function fileLinks<TParent extends PgTable>(parent: TParent, options: FileLinksOptions): Omit<import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: string;
+    schema: undefined;
+    columns: {
+        id: PgColumn<{
+            name: "id";
+            tableName: string;
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: true;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        parentId: PgColumn<{
+            name: string;
+            tableName: string;
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        fileId: PgColumn<{
+            name: "file_id";
+            tableName: string;
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        tenantId: PgColumn<{
+            name: string;
+            tableName: string;
+            dataType: "string";
+            columnType: "PgUUID";
+            data: string;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: PgColumn<{
+            name: "created_at";
+            tableName: string;
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>, "enableRLS">;
+export type FileLinksTable = ReturnType<typeof fileLinks>;

package/dist/files.js

@@ -0,0 +1,88 @@
+// File metadata and per-entity attachment links (D-053).
+//
+// The bytes live in content-addressed storage (`@facilis.dev/storage`), never in Postgres:
+// `facilis_files` is the metadata row (content hash, name, mime, size, owner), and a
+// generated link table attaches a file to one row of an application table. Bytes are
+// deduplicated by hash, so two uploads of the same content share one blob.
+//
+// The link table is generated rather than polymorphic on purpose: a real foreign key per
+// entity keeps referential integrity (`ON DELETE CASCADE`), lets the manifest/OpenAPI name
+// the relation, and inherits the parent's RLS through an EXISTS policy evaluated with the
+// parent's own policies. A `(entity_table, entity_id)` pair would have none of that.
+import { sql } from "drizzle-orm";
+import { bigint, getTableConfig, pgPolicy, pgTable, text, timestamp, uuid, } from "drizzle-orm/pg-core";
+import { tenantIsolationPolicy } from "./rls.js";
+import { tenantColumn } from "./tenant-column.js";
+/**
+ * One uploaded file's metadata. The uniqueness of `hash` is a storage concern (the local
+ * driver and S3 both address by content), so the same bytes may have several rows with
+ * different names/mime types.
+ *
+ * Access to the bytes is decided by the routes that issue signed URLs, not by a per-row
+ * owner policy here: tenant isolation is the structural boundary, and a file attached to
+ * an entity is readable by whoever can read that entity. `owner_id` is the audit/issuer
+ * identity (and the owner check the upload route uses).
+ */
+export const facilisFiles = pgTable("facilis_files", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    hash: text("hash").notNull(),
+    name: text("name").notNull(),
+    mime: text("mime").notNull(),
+    size: bigint("size", { mode: "number" }).notNull(),
+    tenantId: tenantColumn(),
+    ownerId: uuid("owner_id").notNull(),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+}, () => [
+    tenantIsolationPolicy(),
+    // A RESTRICTIVE policy only narrows what a permissive policy already allows; with no
+    // permissive policy Postgres denies every row (D-008). Uploads insert a metadata row
+    // as facilis_app, so the scoped tenant needs this gate — like auth users and
+    // facilis_jobs. The RESTRICTIVE tenant policy still confines visible rows to the tenant.
+    pgPolicy("facilis_files_tenant_access", {
+        for: "all",
+        using: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+        withCheck: sql `nullif(current_setting('app.tenant_id', true), '') IS NOT NULL`,
+    }),
+]).enableRLS();
+/**
+ * Build the link table that lets one application table contain files.
+ *
+ * ```ts
+ * export const todoFiles = fileLinks(todos, { table: "todo_files", column: "todo_id" });
+ * ```
+ *
+ * The parent needs a single-column primary key (uuid recommended: the FK is a uuid). The
+ * generated table carries a restrictive tenant policy and a permissive `parent_access`
+ * policy: `EXISTS (SELECT 1 FROM parent WHERE parent.pk = link.parent_id)`. Postgres
+ * evaluates that subquery under the caller's role, so the parent table's policies decide
+ * visibility — the link inherits the parent's access rules instead of restating them.
+ */
+export function fileLinks(parent, options) {
+    const config = getTableConfig(parent);
+    // A column-level `.primaryKey()` lives on the column, not in `primaryKeys` (which only
+    // records table-level composite keys), so collect both and require exactly one.
+    const parentKey = config.columns.find((column) => column.primary);
+    if (parentKey === undefined) {
+        throw new Error(`fileLinks(${config.name}): the parent table needs exactly one primary-key column`);
+    }
+    const parentColumn = parentKey;
+    const parentTable = parent;
+    return pgTable(options.table, {
+        id: uuid("id").primaryKey().defaultRandom(),
+        parentId: uuid(options.column ?? "parent_id")
+            .notNull()
+            .references(() => parentColumn, { onDelete: "cascade" }),
+        fileId: uuid("file_id")
+            .notNull()
+            .references(() => facilisFiles.id, { onDelete: "cascade" }),
+        tenantId: tenantColumn(),
+        createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    }, (link) => [
+        tenantIsolationPolicy(),
+        pgPolicy("parent_access", {
+            for: "all",
+            using: sql `exists (select 1 from ${parentTable} where ${parentColumn} = ${link.parentId})`,
+            withCheck: sql `exists (select 1 from ${parentTable} where ${parentColumn} = ${link.parentId})`,
+        }),
+    ]).enableRLS();
+}