@facilis.dev/db 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,23 @@
+/**
+ * @facilis.dev/db — Drizzle client for PGlite and Postgres, policy scope, RLS policy
+ * generators, schema snapshot and idempotent statement runner.
+ */
+export { createDb, DbConnectionError, DEFAULT_OWNER_COLUMNS, DEFAULT_TENANT_COLUMNS, DriverNotImplementedError, SnapshotUnavailableError, type CreateDbOptions, type DbDriver, type FacilisDb, type FacilisSchema, type PgDatabaseLike, } from "./client.js";
+export { APP_ROLE, AppRoleUnavailableError, ensureAppRole, runWithPolicyScope, type AppRoleProvisioning, type PolicyScope, type PolicyScopedDatabase, type PolicyScopedTransaction, } from "./policy.js";
+export { ownerIsolationPolicy, policyCreateSql, rlsForTable, rolePolicy, tenantIsolationPolicy, withRls, type RlsExtras, type RlsOptions, } from "./rls.js";
+export { tenantColumn, tenantDefaultSql } from "./tenant-column.js";
+export { facilisFiles, fileLinks, type FacilisFile, type FileLinksOptions, type FileLinksTable, type NewFacilisFile, } from "./files.js";
+export { schemaSnapshot, type CheckSnapshot, type ColumnSnapshot, type EnumSnapshot, type ForeignKeySnapshot, type IndexSnapshot, type PolicySnapshot, type SchemaSnapshot, type TableSnapshot, type UniqueConstraintSnapshot, type UnsupportedDeclarationSnapshot, } from "./snapshot.js";
+export { liveSchemaSnapshot, type LiveColumnSnapshot, type LivePolicySnapshot, type LiveSchemaSnapshot, type LiveTableSnapshot, } from "./live-schema.js";
+export { canonicalColumnType, diffSchemaSnapshots, type SchemaDrift, type SchemaDriftKind, } from "./schema-drift.js";
+export { canonicalDigestJson, declaredDigestSchema, digestSchema, liveDigestSchema, SCHEMA_DIGEST_VERSION, type DigestColumn, type DigestPolicy, type DigestSchema, type DigestTable, } from "./schema-digest.js";
+export { applyMigrations, applyStatements, type MigrationSource } from "./migrator.js";
+export { applyViews, collectViewMetadata, defineView, grantViewSelect, isFacilisView, viewCreateStatement, viewDefinitionStatement, viewMetadata, ViewDefinitionError, VIEW_BRAND, VIEW_NAME_PATTERN, VIEW_PERMISSION_PATTERN, type DefineViewOptions, type FacilisView, type ViewApplyFailure, type ViewApplyOptions, type ViewApplyResult, type ViewErrorCode, type ViewMetadata, } from "./views.js";
+export { ensureSystemRole, runAsSystem, runWithSystemRole, SUDO_ID_GUC, SYSTEM_ROLE, type RunAsSystemOptions, type RunWithSystemRoleOptions, } from "./sudo.js";
+export { FACILIS_JOB_STATUSES, facilisJobs, type FacilisJobRow, type FacilisJobStatus, type NewFacilisJobRow, } from "./jobs.js";
+export { FACILIS_TASK_DECISIONS, FACILIS_TASK_KINDS, FACILIS_TASK_STATUSES, facilisTasks, type FacilisTaskDecision, type FacilisTaskKind, type FacilisTaskRow, type FacilisTaskStatus, type NewFacilisTaskRow, } from "./tasks.js";
+export { FACILIS_WORKFLOW_STATUSES, facilisWorkflows, type FacilisWorkflowRow, type FacilisWorkflowStatus, type NewFacilisWorkflowRow, } from "./workflows.js";
+export { newSudoId, resetSudoAuditSink, setSudoAuditSink, writeSudoAudit, SudoAuditUnavailableError, type SudoAuditEvent, type SudoAuditEventName, type SudoAuditSink, } from "./sudo-audit.js";
+export { firstKeyword, hasMultipleStatements, isReadOnlySql, stripTrailingSemicolon, } from "./read-only-sql.js";
+export { guardDatabase, TableAccessError, type TableAccessErrorCode, type TableGuardOptions, } from "./table-guard.js";
+export { createLiveView, DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, QueryExecutionError, QUERY_STATEMENT_TIMEOUT_MS, runReadOnlyQuery, toJsonValue, type QueryColumn, type QueryExecution, type QueryExecutionErrorCode, } from "./query-console.js";

package/dist/index.js

@@ -0,0 +1,23 @@
+/**
+ * @facilis.dev/db — Drizzle client for PGlite and Postgres, policy scope, RLS policy
+ * generators, schema snapshot and idempotent statement runner.
+ */
+export { createDb, DbConnectionError, DEFAULT_OWNER_COLUMNS, DEFAULT_TENANT_COLUMNS, DriverNotImplementedError, SnapshotUnavailableError, } from "./client.js";
+export { APP_ROLE, AppRoleUnavailableError, ensureAppRole, runWithPolicyScope, } from "./policy.js";
+export { ownerIsolationPolicy, policyCreateSql, rlsForTable, rolePolicy, tenantIsolationPolicy, withRls, } from "./rls.js";
+export { tenantColumn, tenantDefaultSql } from "./tenant-column.js";
+export { facilisFiles, fileLinks, } from "./files.js";
+export { schemaSnapshot, } from "./snapshot.js";
+export { liveSchemaSnapshot, } from "./live-schema.js";
+export { canonicalColumnType, diffSchemaSnapshots, } from "./schema-drift.js";
+export { canonicalDigestJson, declaredDigestSchema, digestSchema, liveDigestSchema, SCHEMA_DIGEST_VERSION, } from "./schema-digest.js";
+export { applyMigrations, applyStatements } from "./migrator.js";
+export { applyViews, collectViewMetadata, defineView, grantViewSelect, isFacilisView, viewCreateStatement, viewDefinitionStatement, viewMetadata, ViewDefinitionError, VIEW_BRAND, VIEW_NAME_PATTERN, VIEW_PERMISSION_PATTERN, } from "./views.js";
+export { ensureSystemRole, runAsSystem, runWithSystemRole, SUDO_ID_GUC, SYSTEM_ROLE, } from "./sudo.js";
+export { FACILIS_JOB_STATUSES, facilisJobs, } from "./jobs.js";
+export { FACILIS_TASK_DECISIONS, FACILIS_TASK_KINDS, FACILIS_TASK_STATUSES, facilisTasks, } from "./tasks.js";
+export { FACILIS_WORKFLOW_STATUSES, facilisWorkflows, } from "./workflows.js";
+export { newSudoId, resetSudoAuditSink, setSudoAuditSink, writeSudoAudit, SudoAuditUnavailableError, } from "./sudo-audit.js";
+export { firstKeyword, hasMultipleStatements, isReadOnlySql, stripTrailingSemicolon, } from "./read-only-sql.js";
+export { guardDatabase, TableAccessError, } from "./table-guard.js";
+export { createLiveView, DEFAULT_QUERY_LIMIT, MAX_QUERY_LIMIT, QueryExecutionError, QUERY_STATEMENT_TIMEOUT_MS, runReadOnlyQuery, toJsonValue, } from "./query-console.js";

package/dist/jobs.d.ts

@@ -0,0 +1,255 @@
+/** Every `facilis_jobs.status` value, in lifecycle order. */
+export declare const FACILIS_JOB_STATUSES: readonly ["queued", "running", "succeeded", "failed", "cancelled"];
+export type FacilisJobStatus = (typeof FACILIS_JOB_STATUSES)[number];
+/**
+ * One job instance. `input`/`output` are JSONB because the job contract is serialized
+ * data (docs/JOBS.md §5); `status` is text rather than a Postgres enum so a new status is a
+ * code change, not a migration.
+ */
+export declare const facilisJobs: Omit<import("drizzle-orm/pg-core").PgTableWithColumns<{
+    name: "facilis_jobs";
+    schema: undefined;
+    columns: {
+        id: import("drizzle-orm/pg-core").PgColumn<{
+            name: "id";
+            tableName: "facilis_jobs";
+            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;
+        }, {}, {}>;
+        name: import("drizzle-orm/pg-core").PgColumn<{
+            name: "name";
+            tableName: "facilis_jobs";
+            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;
+        }, {}, {}>;
+        status: import("drizzle-orm/pg-core").PgColumn<{
+            name: "status";
+            tableName: "facilis_jobs";
+            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;
+        }, {}, {}>;
+        input: import("drizzle-orm/pg-core").PgColumn<{
+            name: "input";
+            tableName: "facilis_jobs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        output: import("drizzle-orm/pg-core").PgColumn<{
+            name: "output";
+            tableName: "facilis_jobs";
+            dataType: "json";
+            columnType: "PgJsonb";
+            data: unknown;
+            driverParam: unknown;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        error: import("drizzle-orm/pg-core").PgColumn<{
+            name: "error";
+            tableName: "facilis_jobs";
+            dataType: "string";
+            columnType: "PgText";
+            data: string;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: [string, ...string[]];
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        attempts: import("drizzle-orm/pg-core").PgColumn<{
+            name: "attempts";
+            tableName: "facilis_jobs";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: true;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        maxAttempts: import("drizzle-orm/pg-core").PgColumn<{
+            name: "max_attempts";
+            tableName: "facilis_jobs";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        timeoutMs: import("drizzle-orm/pg-core").PgColumn<{
+            name: "timeout_ms";
+            tableName: "facilis_jobs";
+            dataType: "number";
+            columnType: "PgInteger";
+            data: number;
+            driverParam: string | number;
+            notNull: true;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        runAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "run_at";
+            tableName: "facilis_jobs";
+            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;
+        }, {}, {}>;
+        startedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "started_at";
+            tableName: "facilis_jobs";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        finishedAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "finished_at";
+            tableName: "facilis_jobs";
+            dataType: "date";
+            columnType: "PgTimestamp";
+            data: Date;
+            driverParam: string;
+            notNull: false;
+            hasDefault: false;
+            isPrimaryKey: false;
+            isAutoincrement: false;
+            hasRuntimeDefault: false;
+            enumValues: undefined;
+            baseColumn: never;
+            identity: undefined;
+            generated: undefined;
+        }, {}, {}>;
+        createdAt: import("drizzle-orm/pg-core").PgColumn<{
+            name: "created_at";
+            tableName: "facilis_jobs";
+            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;
+        }, {}, {}>;
+        tenantId: import("drizzle-orm/pg-core").PgColumn<{
+            name: string;
+            tableName: "facilis_jobs";
+            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;
+        }, {}, {}>;
+    };
+    dialect: 'pg';
+}>, "enableRLS">;
+export type FacilisJobRow = typeof facilisJobs.$inferSelect;
+export type NewFacilisJobRow = typeof facilisJobs.$inferInsert;

package/dist/jobs.js

@@ -0,0 +1,64 @@
+// The persisted job queue (D-107, docs/JOBS.md §8).
+//
+// The queue is framework state, not application data: it is tenant-scoped so the structural
+// invariant holds (`pgPolicy` + `ENABLE ROW LEVEL SECURITY`), the project re-exports the
+// table from `db/schema.ts`, and the framework owns its DDL via a Drizzle migration. The
+// engine's own writes run as the app role under the deployment tenant; a job *body* runs as
+// the system role in its own audited transaction.
+import { sql } from "drizzle-orm";
+import { integer, jsonb, pgPolicy, pgTable, text, timestamp, uuid } from "drizzle-orm/pg-core";
+import { tenantIsolationPolicy } from "./rls.js";
+import { tenantColumn } from "./tenant-column.js";
+/** Every `facilis_jobs.status` value, in lifecycle order. */
+export const FACILIS_JOB_STATUSES = [
+    "queued",
+    "running",
+    "succeeded",
+    "failed",
+    "cancelled",
+];
+/**
+ * One job instance. `input`/`output` are JSONB because the job contract is serialized
+ * data (docs/JOBS.md §5); `status` is text rather than a Postgres enum so a new status is a
+ * code change, not a migration.
+ */
+export const facilisJobs = pgTable("facilis_jobs", {
+    id: uuid("id").primaryKey().defaultRandom(),
+    name: text("name").notNull(),
+    status: text("status").notNull(),
+    input: jsonb("input").notNull(),
+    output: jsonb("output"),
+    error: text("error"),
+    attempts: integer("attempts").notNull().default(0),
+    maxAttempts: integer("max_attempts").notNull(),
+    timeoutMs: integer("timeout_ms").notNull(),
+    /** When the job becomes eligible (a future instant means "scheduled"). */
+    runAt: timestamp("run_at", { withTimezone: true }).notNull().defaultNow(),
+    startedAt: timestamp("started_at", { withTimezone: true }),
+    finishedAt: timestamp("finished_at", { withTimezone: true }),
+    createdAt: timestamp("created_at", { withTimezone: true }).notNull().defaultNow(),
+    tenantId: tenantColumn(),
+}, () => [
+    tenantIsolationPolicy(),
+    // RLS is tenant-only (D-008); the queue is additionally gated by app permissions, so a
+    // route that touches facilis_jobs without jobs:read/jobs:exec fails at the database, not
+    // only in its own wrapper check. The framework engine's scope passes both permissions
+    // explicitly (db-store); a request scope carries the session's expanded permissions.
+    pgPolicy("facilis_jobs_read", {
+        for: "select",
+        using: sql `nullif(current_setting('app.permissions', true), '')::jsonb ? 'jobs:read'`,
+    }),
+    pgPolicy("facilis_jobs_insert", {
+        for: "insert",
+        withCheck: sql `nullif(current_setting('app.permissions', true), '')::jsonb ? 'jobs:exec'`,
+    }),
+    pgPolicy("facilis_jobs_update", {
+        for: "update",
+        using: sql `nullif(current_setting('app.permissions', true), '')::jsonb ? 'jobs:exec'`,
+        withCheck: sql `nullif(current_setting('app.permissions', true), '')::jsonb ? 'jobs:exec'`,
+    }),
+    pgPolicy("facilis_jobs_delete", {
+        for: "delete",
+        using: sql `nullif(current_setting('app.permissions', true), '')::jsonb ? 'jobs:exec'`,
+    }),
+]).enableRLS();

package/dist/live-schema.d.ts

@@ -0,0 +1,39 @@
+import type { FacilisDb } from "./client.js";
+/**
+ * Live database introspection (SPEC §11.1): the catalog side of the code↔live diff.
+ *
+ * Everything here reads Postgres system catalogs, never the Drizzle schema, so the
+ * snapshot describes the database the running project is actually talking to (PGlite in
+ * dev, Postgres in production). Tables are restricted to the connection's current schema:
+ * Facilis projects keep their tables in `public`, and framework-internal schemas such as
+ * `drizzle` must not show up as drift.
+ */
+export interface LiveColumnSnapshot {
+    name: string;
+    /** `format_type()` rendering, e.g. `character varying(120)` or `timestamp with time zone`. */
+    type: string;
+    notNull: boolean;
+    default: string | null;
+    isPrimaryKey: boolean;
+}
+export interface LivePolicySnapshot {
+    name: string;
+    /** SQL command the policy applies to: ALL, SELECT, INSERT, UPDATE or DELETE. */
+    command: string;
+    /** RESTRICTIVE policies are AND-ed with the permissive ones (D-008). */
+    restrictive: boolean;
+    roles: string[];
+    using: string | null;
+    withCheck: string | null;
+}
+export interface LiveTableSnapshot {
+    name: string;
+    rlsEnabled: boolean;
+    columns: LiveColumnSnapshot[];
+    policies: LivePolicySnapshot[];
+}
+export interface LiveSchemaSnapshot {
+    tables: LiveTableSnapshot[];
+}
+/** Introspect the live database behind a Facilis project. */
+export declare function liveSchemaSnapshot(db: FacilisDb): Promise<LiveSchemaSnapshot>;

package/dist/live-schema.js

@@ -0,0 +1,97 @@
+import { sql } from "drizzle-orm";
+import { MIGRATION_TRACKING_TABLE } from "./migrator.js";
+/**
+ * Tables this package owns for its own bookkeeping. They exist in every migrated database
+ * but never in the project schema, so they would otherwise show up as permanent drift.
+ */
+const INTERNAL_TABLES = new Set([MIGRATION_TRACKING_TABLE]);
+/**
+ * One row per column; table-level attributes (`relrowsecurity`) repeat on every row and
+ * are lifted onto the table when the first column is seen.
+ */
+const COLUMNS_QUERY = sql `
+  select
+    c.relname as table_name,
+    c.relrowsecurity as rls_enabled,
+    a.attname as column_name,
+    format_type(a.atttypid, a.atttypmod) as column_type,
+    a.attnotnull as not_null,
+    pg_get_expr(d.adbin, d.adrelid) as column_default,
+    exists (
+      select 1
+      from pg_index i
+      where i.indrelid = c.oid and i.indisprimary and a.attnum = any (i.indkey)
+    ) as is_primary_key
+  from pg_class c
+  join pg_namespace n on n.oid = c.relnamespace
+  join pg_attribute a on a.attrelid = c.oid
+  left join pg_attrdef d on d.adrelid = c.oid and d.adnum = a.attnum
+  where n.nspname = current_schema()
+    and c.relkind = 'r'
+    and a.attnum > 0
+    and not a.attisdropped
+  order by c.relname, a.attnum
+`;
+/** `pg_policies` is the catalog view over `pg_policy`; it renders each qualifier as SQL. */
+const POLICIES_QUERY = sql `
+  select tablename, policyname, permissive, roles, cmd, qual, with_check
+  from pg_policies
+  where schemaname = current_schema()
+  order by tablename, policyname
+`;
+/** Introspect the live database behind a Facilis project. */
+export async function liveSchemaSnapshot(db) {
+    const columnResult = await db.db.execute(COLUMNS_QUERY);
+    const tables = new Map();
+    for (const row of columnResult.rows) {
+        const tableName = readText(row, "table_name");
+        const columnName = readText(row, "column_name");
+        if (tableName === null || columnName === null || INTERNAL_TABLES.has(tableName))
+            continue;
+        const table = tableFor(tables, tableName);
+        table.rlsEnabled = row["rls_enabled"] === true;
+        table.columns.push({
+            name: columnName,
+            type: readText(row, "column_type") ?? "",
+            notNull: row["not_null"] === true,
+            default: readText(row, "column_default"),
+            isPrimaryKey: row["is_primary_key"] === true,
+        });
+    }
+    const policyResult = await db.db.execute(POLICIES_QUERY);
+    for (const row of policyResult.rows) {
+        const tableName = readText(row, "tablename");
+        const policyName = readText(row, "policyname");
+        if (tableName === null || policyName === null || INTERNAL_TABLES.has(tableName))
+            continue;
+        tableFor(tables, tableName).policies.push({
+            name: policyName,
+            command: (readText(row, "cmd") ?? "ALL").toUpperCase(),
+            restrictive: (readText(row, "permissive") ?? "").toUpperCase() === "RESTRICTIVE",
+            roles: readTextArray(row, "roles"),
+            using: readText(row, "qual"),
+            withCheck: readText(row, "with_check"),
+        });
+    }
+    return {
+        tables: [...tables.values()].toSorted((left, right) => left.name.localeCompare(right.name)),
+    };
+}
+function tableFor(tables, name) {
+    const existing = tables.get(name);
+    if (existing !== undefined)
+        return existing;
+    const table = { name, rlsEnabled: false, columns: [], policies: [] };
+    tables.set(name, table);
+    return table;
+}
+function readText(row, key) {
+    const value = row[key];
+    return typeof value === "string" ? value : null;
+}
+function readTextArray(row, key) {
+    const value = row[key];
+    if (!Array.isArray(value))
+        return [];
+    return value.filter((entry) => typeof entry === "string");
+}

package/dist/migrator.d.ts

@@ -0,0 +1,20 @@
+import type { FacilisDb } from "./client.js";
+/** Bookkeeping table owned by this package, not by the project schema: introspection skips it. */
+export declare const MIGRATION_TRACKING_TABLE = "_facilis_applied_statements";
+export type MigrationSource = string | readonly string[] | {
+    readonly directory: string;
+};
+/**
+ * Applies statements in order inside one transaction. Statements are keyed by content
+ * hash and skipped when already applied, so bootstrapping a persistent dataDir twice is
+ * safe; a failure rolls back both the statements and the tracking rows.
+ *
+ * Array entries may either be one SQL statement or a whole file separated by drizzle-kit's
+ * "--> statement-breakpoint" marker (plain semicolons are never used as separators).
+ */
+export declare function applyStatements(db: FacilisDb, statements: readonly string[]): Promise<void>;
+/**
+ * Convenience runner for tests/examples: plain SQL text, a statement list, or a directory
+ * of drizzle-kit `.sql` files (applied in filename order).
+ */
+export declare function applyMigrations(db: FacilisDb, source: MigrationSource): Promise<void>;

package/dist/migrator.js

@@ -0,0 +1,66 @@
+import { readFileSync, readdirSync } from "node:fs";
+import { join } from "node:path";
+import { sql } from "drizzle-orm";
+/** drizzle-kit separates statements in generated SQL files with this marker. */
+const STATEMENT_BREAKPOINT = "--> statement-breakpoint";
+/** Bookkeeping table owned by this package, not by the project schema: introspection skips it. */
+export const MIGRATION_TRACKING_TABLE = "_facilis_applied_statements";
+/**
+ * Applies statements in order inside one transaction. Statements are keyed by content
+ * hash and skipped when already applied, so bootstrapping a persistent dataDir twice is
+ * safe; a failure rolls back both the statements and the tracking rows.
+ *
+ * Array entries may either be one SQL statement or a whole file separated by drizzle-kit's
+ * "--> statement-breakpoint" marker (plain semicolons are never used as separators).
+ */
+export async function applyStatements(db, statements) {
+    await db.db.transaction(async (tx) => {
+        await tx.execute(sql.raw(`CREATE TABLE IF NOT EXISTS ${MIGRATION_TRACKING_TABLE} (id text PRIMARY KEY, applied_at timestamptz NOT NULL DEFAULT now())`));
+        for (const statement of statements.flatMap(splitStatementBatch)) {
+            const trimmed = statement.trim();
+            if (trimmed.length === 0)
+                continue;
+            // no-await-in-loop: statements must run one at a time on the transaction's connection.
+            // eslint-disable-next-line no-await-in-loop
+            const hashed = await tx.execute(sql `select md5(${trimmed}) as id`);
+            const row = hashed.rows[0];
+            if (row === undefined || typeof row.id !== "string") {
+                throw new Error("applyStatements: failed to hash a migration statement");
+            }
+            const id = row.id;
+            // eslint-disable-next-line no-await-in-loop
+            const seen = await tx.execute(sql `select 1 from ${sql.identifier(MIGRATION_TRACKING_TABLE)} where id = ${id}`);
+            if (seen.rows.length > 0)
+                continue;
+            // eslint-disable-next-line no-await-in-loop
+            await tx.execute(sql.raw(trimmed));
+            // eslint-disable-next-line no-await-in-loop
+            await tx.execute(sql `insert into ${sql.identifier(MIGRATION_TRACKING_TABLE)} (id) values (${id})`);
+        }
+    });
+}
+/**
+ * Convenience runner for tests/examples: plain SQL text, a statement list, or a directory
+ * of drizzle-kit `.sql` files (applied in filename order).
+ */
+export async function applyMigrations(db, source) {
+    const statements = typeof source === "string"
+        ? [source]
+        : isMigrationDirectory(source)
+            ? readMigrationDirectory(source.directory)
+            : source;
+    await applyStatements(db, statements);
+}
+function splitStatementBatch(batch) {
+    return batch.split(STATEMENT_BREAKPOINT);
+}
+function isMigrationDirectory(source) {
+    return typeof source === "object" && "directory" in source;
+}
+function readMigrationDirectory(directory) {
+    const files = readdirSync(directory, { withFileTypes: true })
+        .filter((entry) => entry.isFile() && entry.name.endsWith(".sql"))
+        .map((entry) => entry.name)
+        .toSorted();
+    return files.map((file) => readFileSync(join(directory, file), "utf8"));
+}

package/dist/policy.d.ts

@@ -0,0 +1,50 @@
+import type { FacilisDb, PgDatabaseLike } from "./client.js";
+/** Non-superuser role used for policy-scoped work; RLS is bypassed by superusers (D-008). */
+export declare const APP_ROLE = "facilis_app";
+/** Values exported to Postgres GUCs for one policy-scoped operation (contract §4.2). */
+export interface PolicyScope {
+    readonly tenantId?: string;
+    readonly userId?: string;
+    readonly roles?: readonly string[];
+    /** The session's expanded permissions, read by permission views (D-098). */
+    readonly permissions?: readonly string[];
+}
+/** Transaction handed to `runWithPolicyScope` callbacks. */
+export type PolicyScopedTransaction = Parameters<Parameters<PgDatabaseLike["transaction"]>[0]>[0];
+/** Drizzle database or transaction accepted by every scoped query helper. */
+export type PolicyScopedDatabase = PgDatabaseLike | PolicyScopedTransaction;
+/** Thrown when the app role has not been bootstrapped yet (`ensureAppRole`). */
+export declare class AppRoleUnavailableError extends Error {
+    readonly code = "app_role_unavailable";
+    constructor(cause: unknown);
+}
+/**
+ * The classification `ensureAppRole` derives from the live schema: every table in `public`
+ * is either RLS-scoped (the app role has DML and the policies decide the rows) or
+ * system-only (no table privilege at all; reachable only through the system identity).
+ * D-136 makes this the invariant: a table without RLS is never app-reachable.
+ */
+export interface AppRoleProvisioning {
+    readonly systemOnlyTables: readonly string[];
+}
+/**
+ * Creates the non-superuser role that policy-scoped queries run as and reconciles its
+ * privileges with the live schema: **RLS is the grant boundary** (D-136). A table with RLS
+ * enabled gets DML for the app role (its policies then decide the rows); a table without RLS
+ * gets no table privilege at all, so only the system identity can touch it. Sequences stay
+ * granted to both classes: USAGE can neither read nor write a table, and serial/identity
+ * columns need it for inserts. Idempotent and re-asserting: safe on every boot, and the
+ * blanket grants an older cluster carries are revoked the next time this runs.
+ *
+ * The role is `NOINHERIT` on purpose. It is a member of `facilis_system` so a deployment
+ * whose connection already is `facilis_app` can `SET ROLE` for the audited elevation
+ * (D-099); membership must not hand the request identity the system role's grants, or the
+ * system-only tables would be reachable from every handler. `SET ROLE` still works with
+ * `NOINHERIT`: only implicit inheritance of the member role's privileges is disabled.
+ */
+export declare function ensureAppRole(db: FacilisDb): Promise<AppRoleProvisioning>;
+/**
+ * Runs `fn` in one transaction whose Postgres identity is facilis_app and whose GUCs carry
+ * the scope. GUC values travel through set_config parameters, never string concatenation.
+ */
+export declare function runWithPolicyScope<T>(db: FacilisDb, scope: PolicyScope, fn: (tx: PolicyScopedDatabase) => Promise<T>): Promise<T>;