@fabrika/platform-node 0.9.0-dev.1 → 0.9.0-dev.2

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@fabrika/platform-node",
-	"version": "0.9.0-dev.1",
+	"version": "0.9.0-dev.2",
 	"type": "module",
 	"repository": {
 		"type": "git",
@@ -13,22 +13,23 @@
 	"files": [
 		"src",
 		"migrations",
-		"!src/**/__tests__/**"
+		"!src/**/__tests__/**",
+		"types"
 	],
 	"exports": {
 		".": {
 			"bun": "./src/index.ts",
-			"types": "./src/index.ts",
+			"types": "./types/src/index.d.ts",
 			"default": "./src/index.ts"
 		},
 		"./postgres-migrations": {
 			"bun": "./src/postgres-migrations.ts",
-			"types": "./src/postgres-migrations.ts",
+			"types": "./types/src/postgres-migrations.d.ts",
 			"default": "./src/postgres-migrations.ts"
 		},
 		"./sql": {
 			"bun": "./src/sql.ts",
-			"types": "./src/sql.ts",
+			"types": "./types/src/sql.d.ts",
 			"default": "./src/sql.ts"
 		}
 	},
@@ -37,6 +38,6 @@
 		"test": "bun test"
 	},
 	"dependencies": {
-		"@fabrika/platform": "0.9.0-dev.1"
+		"@fabrika/platform": "0.9.0-dev.2"
 	}
 }

package/types/src/application-postgres-grants.d.ts

@@ -0,0 +1,19 @@
+import type { SqlDatabase } from '@fabrika/platform';
+/**
+ * Takes the migration's session-level advisory lock. Any role may take any advisory lock, the application's own
+ * runtime included, so an application's wait is bounded by `timeoutMs`; a service plan waits as long as it takes.
+ */
+export declare function acquireMigrationLock(db: SqlDatabase, lockKey: number, timeoutMs: number | undefined, label: string): Promise<void>;
+/**
+ * Clears PUBLIC from the default privileges of the session's role (the migration role), globally and in its schema,
+ * before the plan creates anything. A default the provisioning credential or a superuser set would otherwise hand
+ * every table a later migration creates to the runtime role through PUBLIC.
+ */
+export declare function normalizeDefaultPrivileges(db: SqlDatabase, schema: string): Promise<void>;
+/**
+ * Resets the schema's privileges to what the runtime role needs: PUBLIC and the runtime role lose everything on the
+ * schema and its objects, then the runtime role gets USAGE, DML on every table but the ledger, EXECUTE on the schema's
+ * routines and USAGE on its types. One transaction, so a live runtime never sees a gap. Then the effective privileges
+ * are verified, PUBLIC included, and anything beyond that stops the deploy.
+ */
+export declare function grantRuntimeRole(db: SqlDatabase, schema: string, ledgerTable: string, role: string): Promise<void>;

package/types/src/application-postgres-migrations.d.ts

@@ -0,0 +1,59 @@
+import type { SqlDatabase } from '@fabrika/platform';
+import { type ApplicationDatabaseRoles } from './application-postgres-roles';
+import { type DatabaseObject } from './migration-classify';
+import { type PostgresMigration, type PostgresMigrationPlan } from './postgres-migrations';
+/** Migration identity of every application (ADR-0017): bundle `app`, ledger `app_<id>.fabrika_migrations`. */
+export declare const APPLICATION_MIGRATION_BUNDLE = "app";
+export declare const APPLICATION_MIGRATION_LEDGER = "fabrika_migrations";
+/** Fails a migration that waits this long for a lock, so a blocked `ALTER` does not queue the live version's queries. */
+export declare const DEFAULT_MIGRATION_LOCK_TIMEOUT_MS = 5000;
+/** Bounds a statement such as a backfill or a non-concurrent index build, which holds its lock while it runs. */
+export declare const DEFAULT_MIGRATION_STATEMENT_TIMEOUT_MS = 60000;
+/** How long `migrate` waits for the application's migration lock: another container's migrations, or a stray holder. */
+export declare const DEFAULT_MIGRATION_ADVISORY_LOCK_TIMEOUT_MS = 300000;
+export interface PostgresApplicationMigrationsConfig {
+    readonly appId: string;
+    /** The application's `db/migrations/` directory. */
+    readonly directory: string;
+    readonly lockTimeoutMs?: number;
+    readonly statementTimeoutMs?: number;
+    readonly advisoryLockTimeoutMs?: number;
+    /**
+     * The framework's own tables (`fabrika_*`, `@fabrika/db/migrations`), applied as their own bundle before the
+     * application's, in the same ledger and under the same checksum rule.
+     */
+    readonly framework?: {
+        readonly bundle: string;
+        readonly migrations: readonly PostgresMigration[];
+    };
+}
+export interface PostgresApplicationMigrations {
+    /** `app_<id>`: the application's schema, which the data layer sets as its `search_path`. */
+    readonly schema: string;
+    readonly roles: ApplicationDatabaseRoles;
+    read(): PostgresMigration[];
+    plan(migrations?: readonly PostgresMigration[]): PostgresMigrationPlan;
+    /**
+     * The manifest of the framework's and the application's migrations: the database objects they declare, which the
+     * catalog check admits at every start (`fabrika db codegen`) as the runner does before each commit.
+     */
+    objects(migrations?: readonly PostgresMigration[]): DatabaseObject[];
+    /** Applies the plan over `db` as whatever role it connects as, and grants no runtime role: the runner's own tests. */
+    apply(db: SqlDatabase, migrations?: readonly PostgresMigration[]): Promise<string[]>;
+    /**
+     * What `fabrika db migrate` runs. With the provisioning credential it creates or checks the role family and the
+     * schema; then it applies the plan as the migration role and grants the runtime role. No migration runs as the
+     * provisioning credential, and a credential that cannot create roles is refused.
+     */
+    migrate(provisioningUrl: string, migrations?: readonly PostgresMigration[]): Promise<string[]>;
+}
+/** The first 48 bits of SHA-256(`fabrika-db:<appId>`), plus one: applications sharing a database do not serialize each other. */
+export declare function applicationMigrationLockKey(appId: string): number;
+/** The application's schema, its migration role (named like the schema) and its runtime role `run_<id>`. */
+export declare function applicationDatabaseRoles(appId: string): ApplicationDatabaseRoles;
+/** The runtime role's connection URL, derived from the provisioning credential the platform hands the application. */
+export declare function applicationRuntimeUrl(provisioningUrl: string, appId: string): string;
+/** Drops an application's schema and both of its roles, as the provisioning credential: for throwaway test databases. */
+export declare function dropApplicationDatabase(provisioningUrl: string, appId: string): Promise<void>;
+/** An application's migration wrapper: its schema, ledger, lock and timeouts are derived, never configured. */
+export declare function definePostgresApplicationMigrations(config: PostgresApplicationMigrationsConfig): PostgresApplicationMigrations;

package/types/src/application-postgres-roles.d.ts

@@ -0,0 +1,33 @@
+import type { SqlDatabase } from '@fabrika/platform';
+/** An application's schema and the two roles that reach it (ADR-0017). */
+export interface ApplicationDatabaseRoles {
+    /** `app_<id>`. */
+    readonly schema: string;
+    /** Owns the schema and every object in it, so it is the only role that runs DDL there. Named like the schema. */
+    readonly migration: string;
+    /** `run_<id>`: DML on the schema's tables except the migration ledger, and nothing else. */
+    readonly runtime: string;
+}
+export declare function provisioningCredential(provisioningUrl: string): {
+    readonly url: URL;
+    readonly password: string;
+};
+/** Postgres' SCRAM-SHA-256 verifier (RFC 7677): the password itself never reaches the server, so no statement log holds it. */
+export declare function scramVerifier(password: string): string;
+/** The URL `role` connects with: the provisioning URL's host, database and options, the role's name and derived password. */
+export declare function postgresRoleUrl(provisioningUrl: string, role: string): string;
+/**
+ * Creates the role family and the schema when absent, resets both roles' passwords to their derived values, and refuses
+ * a family that holds more than it should. Runs over one connection of the provisioning credential, under the
+ * application's migration lock, so two containers starting together do not race on the same catalog rows.
+ */
+export declare function provisionPostgresRoles(admin: SqlDatabase, provisioningUrl: string, roles: ApplicationDatabaseRoles, lock: {
+    readonly key: number;
+    readonly timeoutMs: number;
+}): Promise<void>;
+export declare const quotedIdentifier: (name: string) => string;
+/**
+ * Drops the schema and both roles: for throwaway test databases only. The schema is dropped as its owner, which a
+ * CREATEROLE provisioning credential may become (`provisionPostgresRoles` granted it the migration role).
+ */
+export declare function dropPostgresRoles(admin: SqlDatabase, roles: ApplicationDatabaseRoles): Promise<void>;

package/types/src/application-schema.d.ts

@@ -0,0 +1,3 @@
+export declare function validateApplicationId(appId: string): void;
+/** `app_<id>`: the schema an application's migrations create and its data layer sets as its `search_path`. */
+export declare function applicationDatabaseSchema(appId: string): string;

package/types/src/asset-server-fs.d.ts

@@ -0,0 +1,16 @@
+import type { AssetServer } from '@fabrika/platform';
+export interface FileSystemAssetServerOptions {
+    /** File served for a directory and for the SPA fallback. */
+    indexFile?: string;
+    /** Serve `indexFile` (200) for an unmatched document request. Off = everything unmatched 404s. */
+    spaFallback?: boolean;
+}
+export declare class FileSystemAssetServer implements AssetServer {
+    private readonly root;
+    private readonly indexFile;
+    private readonly spaFallback;
+    constructor(root: string, options?: FileSystemAssetServerOptions);
+    fetch(request: Request): Promise<Response>;
+    /** The file backing `pathname`, or null when there is none inside the root. */
+    private locate;
+}

package/types/src/blob-s3.d.ts

@@ -0,0 +1,34 @@
+import { type BlobStore, type FileObjectStore, type ObjectMetadata, type ObjectWriteOptions, type StoredObject } from '@fabrika/platform';
+/** Connection details for an S3-compatible bucket. `endpoint` is what makes it R2, MinIO, or AWS. */
+export interface S3BlobStoreOptions {
+    bucket: string;
+    accessKeyId: string;
+    secretAccessKey: string;
+    /** e.g. `https://<account>.r2.cloudflarestorage.com` (R2) or `http://storage:9000` (Zerops/MinIO). */
+    endpoint?: string;
+    /** Required by AWS; R2 wants `auto`; MinIO ignores it. */
+    region?: string;
+    /** Temporary-credential session token, when the deployment uses one. */
+    sessionToken?: string;
+    /** `https://<bucket>.<host>` addressing. MinIO normally wants this OFF (path-style). */
+    virtualHostedStyle?: boolean;
+}
+/** The blob body handed back by `get()` — a stream, opened lazily and only once, plus a text shortcut. */
+interface BlobBody {
+    body: ReadableStream;
+    text(): Promise<string>;
+}
+export declare class S3BlobStore implements BlobStore, FileObjectStore {
+    #private;
+    private readonly client;
+    constructor(client: Bun.S3Client);
+    /** Build a store from plain connection options. Never logs them. */
+    static connect(options: S3BlobStoreOptions): S3BlobStore;
+    put(key: string, value: string | ArrayBuffer | ReadableStream): Promise<void>;
+    get(key: string): Promise<BlobBody | null>;
+    delete(key: string): Promise<void>;
+    write(key: string, body: ReadableStream<Uint8Array>, options: ObjectWriteOptions): Promise<ObjectMetadata>;
+    read(key: string, signal?: AbortSignal): Promise<StoredObject | null>;
+    readVersion(key: string, version: string, signal?: AbortSignal): Promise<StoredObject | null>;
+}
+export {};

package/types/src/connection-capacity.d.ts

@@ -0,0 +1,29 @@
+/**
+ * SQLSTATE 53300 (`too_many_connections`): no slot the role may take is free, whether the server's, the database's or
+ * the role's limit is reached. It refuses a connection and never a statement on one that is open.
+ */
+export declare const TOO_MANY_CONNECTIONS = "53300";
+/** How every report of an exhausted connection limit starts, so a caller that reads only output can recognise one. */
+export declare const CONNECTION_CAPACITY_MESSAGE = "the database had no free connection slot";
+/** How long a caller waits for a free connection slot by default before it gives up. */
+export declare const DEFAULT_CONNECTION_WAIT_MS = 60000;
+/** Whether `error` is the server refusing a connection because every slot it may take is in use. */
+export declare function isConnectionCapacityError(error: unknown): boolean;
+/** The database kept refusing connections for lack of a free slot until the wait ran out. */
+export declare class ConnectionCapacityError extends Error {
+    readonly waitedMs: number;
+    constructor(waitedMs: number);
+}
+export interface ConnectionCapacityWait {
+    /** How long to keep retrying; `DEFAULT_CONNECTION_WAIT_MS` by default. */
+    readonly waitMs?: number;
+    readonly sleep?: (ms: number) => Promise<void>;
+    readonly now?: () => number;
+    readonly random?: () => number;
+}
+/**
+ * Runs `attempt` until it does not fail for lack of a connection slot, waiting with jittered exponential backoff between
+ * tries, and throws `ConnectionCapacityError` once `waitMs` has passed. Any other failure is thrown at once. `attempt`
+ * must release whatever it opened before it throws, so that a waiting caller holds no slot another needs.
+ */
+export declare function withConnectionCapacity<T>(attempt: () => Promise<T>, options?: ConnectionCapacityWait): Promise<T>;

package/types/src/database-code.d.ts

@@ -0,0 +1,16 @@
+import type { DatabaseObject } from './migration-classify';
+/**
+ * One row (`violation`) per escape and per undeclared object in `schema`. Escapes: a function that is `SECURITY
+ * DEFINER`, has a `SET` clause or a language other than `sql` and `plpgsql`; an event trigger on a function of the
+ * schema; and any dependency of an object of the schema on a type, function, relation, operator, operator class or
+ * collation outside the schema and `pg_catalog`; a routine that shadows a `pg_catalog` name or has more than one
+ * signature; a sequence other than an identity column's. Undeclared: a function, procedure or aggregate, operator,
+ * trigger (a foreign key's excepted), rule, view, policy or domain that `declared` does not name. Every name is
+ * qualified with `pg_catalog`, the query has no backslash, and the manifest is
+ * hex text, so the session's `search_path` and `standard_conforming_strings` cannot change what it finds.
+ */
+export declare function databaseCodeQuery(schema: string, declared: readonly DatabaseObject[]): string;
+/** The message a `databaseCodeCheck` failure carries before its list of violations. */
+export declare const DATABASE_CODE_FAILURE = "fabrika-migration-database-code: ";
+/** Fails the transaction it runs in when `schema` escapes or holds an object `declared` does not name. */
+export declare function databaseCodeCheck(schema: string, declared: readonly DatabaseObject[]): string;

package/types/src/file-table-ddl.d.ts

@@ -0,0 +1,36 @@
+import { type SqlToken } from './migration-sql';
+/**
+ * A file row's states. `pending`: its object is still being written. `quarantined`: written to a scanning collection
+ * and not yet given a clean verdict. `live`: served. `rejected`: refused by the scan and its object is gone.
+ */
+export declare const FILE_STATUSES: readonly ["pending", "live", "quarantined", "rejected"];
+export declare const FILE_TABLE_PREFIX = "fabrika_files_";
+/** Every stored file (`@fabrika/db`'s `0008_files.sql`): an application's file column is a foreign key to its `id`. */
+export declare const STORED_FILES_TABLE = "fabrika_files";
+/** What an application's last adoption migration of a file collection calls, with the collection's name. */
+export declare const FILES_RELEASE_FUNCTION = "fabrika_files_release";
+/**
+ * What an adoption migration calls right before it reads a collection's table: it copies the rows an older instance
+ * wrote after `0008_files.sql` ran, so every row the migration adopts has its `fabrika_files` row.
+ */
+export declare const FILES_COPY_FUNCTION = "fabrika_files_copy_legacy";
+/** The columns the scan job keeps: the scanned object's version, and the retry count and time of a file without a verdict. */
+export declare const FILE_SCAN_COLUMNS: readonly ["object_version TEXT", "scan_attempts INTEGER NOT NULL DEFAULT 0", "scan_after TIMESTAMPTZ"];
+/** The named status check of every state. */
+export declare function fileStatusCheck(table: string): string;
+/** The index the scan job selects its batch by. */
+export declare function fileScanIndex(table: string): string;
+/**
+ * The name Postgres gave the unnamed status check of a table an older release's `fileTableSql` created:
+ * `<table>_status_check`, the table's name cut to 50 characters first (`makeObjectName`).
+ */
+export declare function legacyStatusCheckName(table: string): string;
+/** The statement of an older release's `fileScanSql` that widens its collection table: its check and its columns. */
+export declare function fileScanAlter(table: string): string;
+/** The file table a statement is exactly `fileScanAlter` of, or `undefined`. */
+export declare function fileScanAlterTable(tokens: readonly SqlToken[]): string | undefined;
+/**
+ * Whether the migrations, in order, leave `table` able to hold the scan states: created with the check of every state
+ * and the scan columns, or widened by `fileScanAlter`. `undefined` when none of them creates it.
+ */
+export declare function fileTableScanReady(migrations: readonly string[], table: string): boolean | undefined;

package/types/src/index.d.ts

@@ -0,0 +1,15 @@
+export { APPLICATION_MIGRATION_BUNDLE, APPLICATION_MIGRATION_LEDGER, applicationDatabaseRoles, applicationMigrationLockKey, applicationRuntimeUrl, DEFAULT_MIGRATION_LOCK_TIMEOUT_MS, DEFAULT_MIGRATION_STATEMENT_TIMEOUT_MS, definePostgresApplicationMigrations, dropApplicationDatabase, type PostgresApplicationMigrations, type PostgresApplicationMigrationsConfig, } from './application-postgres-migrations';
+export type { ApplicationDatabaseRoles } from './application-postgres-roles';
+export { applicationDatabaseSchema } from './application-schema';
+export { FileSystemAssetServer, type FileSystemAssetServerOptions } from './asset-server-fs';
+export { S3BlobStore, type S3BlobStoreOptions } from './blob-s3';
+export { CONNECTION_CAPACITY_MESSAGE, ConnectionCapacityError, type ConnectionCapacityWait, DEFAULT_CONNECTION_WAIT_MS, isConnectionCapacityError, TOO_MANY_CONNECTIONS, withConnectionCapacity, } from './connection-capacity';
+export { databaseCodeQuery } from './database-code';
+export { decodeJob, type Job, PostgresJobConsumer, type PostgresJobConsumerOptions, PostgresJobQueue, type PostgresJobQueueOptions, } from './job-queue-postgres';
+export type { DatabaseObject, DatabaseObjectKind } from './migration-classify';
+export { rewritePlaceholders, type RewrittenSql } from './placeholders';
+export { applyPostgresMigrations, definePostgresMigrationPlan, migrationChecksum, platformNodePostgresMigrationBundle, type PostgresApplicationMigrationSettings, type PostgresMigration, type PostgresMigrationBundle, PostgresMigrationError, postgresMigrationFilenames, postgresMigrationIdentity, type PostgresMigrationPlan, readPostgresMigrationBundle, type ReadPostgresMigrationBundleOptions, } from './postgres-migrations';
+export { createTestProvisioner, type TestProvisioner } from './postgres-test-provisioner';
+export { definePostgresServiceMigrations, postgresMigrationResultMessage, type PostgresServiceMigrations, type PostgresServiceMigrationsConfig, } from './service-postgres-migrations';
+export { PostgresDatabase, PostgresStatement, type SqlBindValue } from './sql-postgres';
+export { type BackgroundTasks, type BackgroundTasksOptions, createBackgroundTasks } from './wait-until';

package/types/src/job-queue-postgres.d.ts

@@ -0,0 +1,106 @@
+import { type JobQueue, type SqlDatabase } from '@fabrika/platform';
+/** A claimed delivery. Raw claims carry stored JSON text; typed claims carry the caller's decoded payload. */
+export interface Job<T> {
+    id: string;
+    payload: T;
+    /** How many times this job has been claimed, including now. First delivery is 1. */
+    attempts: number;
+    /** Claims allowed before the job is abandoned. */
+    maxAttempts: number;
+}
+/** Parse and narrow one stored delivery without losing its settlement metadata. */
+export declare function decodeJob<T>(job: Job<string>, decode: (payload: unknown) => T): Job<T>;
+export interface PostgresJobQueueOptions {
+    /** Table holding the jobs. Must already exist; see migrations/0001_jobs.sql. */
+    table?: string;
+    /** Queue name, so several queues can share one table. */
+    queue?: string;
+    /** Claims allowed per job before it is abandoned. */
+    maxAttempts?: number;
+    /** Injectable clock (unix millis) so delays and timeouts are testable without sleeping. */
+    now?: () => number;
+}
+/**
+ * Producer + claim/ack primitives over one jobs table. Implements the `JobQueue` port (`send`); the
+ * rest is the consumer-side surface `PostgresJobConsumer` is built from and tests drive directly.
+ */
+export declare class PostgresJobQueue<T> implements JobQueue<T> {
+    private readonly db;
+    private readonly queue;
+    private readonly maxAttempts;
+    private readonly now;
+    private readonly sendSql;
+    private readonly claimSql;
+    private readonly ackSql;
+    private readonly deferSql;
+    constructor(db: SqlDatabase, options?: PostgresJobQueueOptions);
+    /** Enqueue a message. `delaySeconds` becomes a visible-after deadline, exactly as on Cloudflare Queues. */
+    send(message: T, options?: {
+        delaySeconds?: number;
+    }): Promise<void>;
+    /**
+     * Take up to `limit` due jobs and hide them for `visibilityTimeoutMs`. `decode` narrows the stored
+     * JSON at the deserialization boundary — a row this consumer cannot understand throws here rather
+     * than reaching a handler that assumes a shape.
+     */
+    claim(options: {
+        limit: number;
+        visibilityTimeoutMs: number;
+        decode: (payload: unknown) => T;
+    }): Promise<Job<T>[]>;
+    /** Claim stored JSON text so consumers can decode and settle each delivery independently. */
+    claimRaw(options: {
+        limit: number;
+        visibilityTimeoutMs: number;
+    }): Promise<Job<string>[]>;
+    /** The job is done (or permanently abandoned) — drop the row. Idempotent. */
+    ack(id: string): Promise<void>;
+    /** Make the job claimable again after `delayMs`. Used for retries and for a deferred (locked-out) run. */
+    defer(id: string, delayMs: number): Promise<void>;
+}
+export interface PostgresJobConsumerOptions<T> {
+    /** Narrow the stored JSON to the message type. Invalid deliveries retry until their budget is spent. */
+    decode: (payload: unknown) => T;
+    /** Handle one job. A throw schedules a retry until `maxAttempts` is spent. */
+    handler: (job: Job<T>) => Promise<void>;
+    /** Jobs claimed per pass. Handlers still run one at a time. */
+    batchSize?: number;
+    /** Sleep between passes that found nothing. A pass that found work polls again immediately. */
+    pollIntervalMs?: number;
+    /** How long a claimed job stays hidden. MUST exceed the slowest handler, or the job is redelivered mid-flight. */
+    visibilityTimeoutMs?: number;
+    /** Backoff before the next attempt, from the attempt count just consumed. */
+    retryDelayMs?: (attempts: number) => number;
+    /** A handler threw and the job will be retried. Never log the error object (it may carry a token). */
+    onError?: (error: unknown, job: Job<T>) => void;
+    /** A job spent its last attempt and was dropped. */
+    onAbandoned?: (job: Job<T>) => void;
+}
+/**
+ * The in-process poller. One pass = claim a batch, run the handlers in order, ack or reschedule each.
+ * Handlers run SEQUENTIALLY: a deploy consumer is one run per message and ordering per queue is the
+ * cheapest correct default; raise `batchSize` only for genuinely independent work.
+ *
+ * `start()` is fire-and-forget and never throws; `stop()` waits for the pass in flight, so a shutdown
+ * does not orphan a job it has already made invisible.
+ */
+export declare class PostgresJobConsumer<T> {
+    private readonly queue;
+    private readonly options;
+    private readonly onError;
+    private readonly onAbandoned;
+    private running;
+    private timer;
+    private pass;
+    constructor(queue: PostgresJobQueue<T>, options: PostgresJobConsumerOptions<T>);
+    /** Run one pass. Returns the raw claimed count, including invalid deliveries. Exposed for tests. */
+    poll(): Promise<number>;
+    /** Start polling in the background. Idempotent. */
+    start(): void;
+    /** Stop polling and wait for the pass in flight. Idempotent. */
+    stop(): Promise<void>;
+    private schedule;
+    private runPass;
+    private handleRaw;
+    private handle;
+}

package/types/src/migration-classify.d.ts

@@ -0,0 +1,105 @@
+/** A database object a migration declares, named as the catalog check names it (`trigger deals.audit`). */
+export type DatabaseObjectKind = 'function' | 'procedure' | 'trigger' | 'view' | 'materialized view' | 'rule' | 'policy';
+export interface DatabaseObject {
+    readonly kind: DatabaseObjectKind;
+    /** `<name>`, or `<table>.<name>` for a trigger, a rule and a policy. A routine has one signature, so its name is enough. */
+    readonly name: string;
+}
+/** Database code and unusual expressions: allowed, and shown to the approver as needing closer review. */
+export type DeviationKind = DatabaseObjectKind | 'do' | 'expression';
+/** One deviation. Its approval key is `kind` + `object`: a line moves when the file is edited, the key does not. */
+export interface MigrationDeviation {
+    readonly kind: DeviationKind;
+    /**
+     * The object's name; `block <n>` for the n-th `DO` of the file;
+     * `<where> calls <function>` for an expression, where `<where>` is a column, a constraint, a table or an index.
+     */
+    readonly object: string;
+    readonly file: string;
+    readonly line: number;
+}
+export interface MigrationRefusal {
+    /** What is refused, phrased to precede "is not allowed". */
+    readonly reason: string;
+    readonly file: string;
+    readonly line: number;
+}
+/** How one statement changes the set of declared objects, in file order. */
+export type ManifestChange = {
+    readonly change: 'create';
+    readonly object: DatabaseObject;
+} | {
+    readonly change: 'drop';
+    readonly object: DatabaseObject;
+} | {
+    readonly change: 'drop table';
+    readonly table: string;
+} | {
+    readonly change: 'rename table';
+    readonly from: string;
+    readonly to: string;
+} | {
+    readonly change: 'rename';
+    readonly from: DatabaseObject;
+    readonly to: DatabaseObject;
+}
+/** A routine's create also carries its argument list, as written, so a second signature for the name is refused. */
+ | {
+    readonly change: 'create routine';
+    readonly object: DatabaseObject;
+    readonly args: string;
+    readonly line: number;
+};
+export interface MigrationClassification {
+    readonly file: string;
+    /** One per refused statement, in order. A file with a refusal does not run. */
+    readonly refused: readonly MigrationRefusal[];
+    readonly deviations: readonly MigrationDeviation[];
+    /** The objects the file creates. */
+    readonly objects: readonly DatabaseObject[];
+    readonly changes: readonly ManifestChange[];
+}
+export interface ClassifyMigrationOptions {
+    readonly file: string;
+    /** The functions and procedures the whole migration set declares in the schema: a body or an expression may call them. */
+    readonly functions?: ReadonlySet<string>;
+    /** The framework's own bundle, which alone may name the framework's `fabrika_*` tables. */
+    readonly framework?: boolean;
+}
+export interface MigrationFile {
+    readonly name: string;
+    readonly sql: string;
+    readonly framework?: boolean;
+}
+export interface MigrationSetClassification {
+    readonly files: readonly MigrationClassification[];
+    /** The manifest: every object the files declare and do not drop, in order. The catalog check admits exactly these. */
+    readonly objects: readonly DatabaseObject[];
+}
+/**
+ * Classifies one application migration. Paved: `CREATE TABLE` (a column list and nothing after it), `ALTER TABLE`
+ * column, constraint and rename clauses, `CREATE [UNIQUE] INDEX`, `ALTER INDEX … RENAME TO`, `CREATE TYPE … AS ENUM`,
+ * `ALTER TYPE … ADD|RENAME VALUE`, `DROP`, `TRUNCATE`, `COMMENT ON` and `INSERT`/`UPDATE`/`DELETE` backfills.
+ * Deviations: functions and procedures (one signature per name), triggers, views, rules, policies, their
+ * `ALTER … RENAME TO`, `DO`, and a stored expression that calls anything but a paved built-in. Refused: a schema
+ * other than `schema` (`pg_catalog` relations included), a framework `fabrika_*` name, `SECURITY DEFINER`, a function
+ * `SET` clause, a language other than `sql` and `plpgsql`, a body that is not literal or that holds dynamic `EXECUTE`
+ * or a statement outside its allowlist, a call outside the function allowlist, and every form not named here:
+ * `COPY`, `GRANT`, `REVOKE`, roles, extensions, event triggers, domains (codegen cannot bind one), `SELECT`, `WITH`
+ * and `MERGE` among them. Transaction control and
+ * `SET`/`RESET` are refused for every plan before this runs (`refusedStatement`).
+ */
+export declare function classifyMigration(sql: string, schema: string, options: ClassifyMigrationOptions): MigrationClassification;
+/** The names of the functions and procedures a migration creates or renames to in `schema`, read without classifying them. */
+export declare function declaredFunctions(sql: string, schema: string): string[];
+/**
+ * The manifest of a migration set, folded in file order: a create adds an object (a replace keeps it), a drop removes
+ * it, dropping a table removes its triggers, rules and policies, and renaming a table renames them. A `CASCADE` may
+ * drop more than the manifest removes; a stale entry only admits an object that no longer exists.
+ */
+export declare function migrationManifest(classifications: readonly MigrationClassification[]): DatabaseObject[];
+/**
+ * Classifies a whole migration set in order. A body or an expression may call a function any file of the set
+ * declares; the manifest is what the catalog check admits.
+ */
+export declare function classifyMigrations(files: readonly MigrationFile[], schema: string): MigrationSetClassification;

package/types/src/migration-sql.d.ts

@@ -0,0 +1,63 @@
+export interface StatementStart {
+    /** The first two words of a top-level statement, upper-cased; fewer when the statement has fewer. */
+    readonly words: readonly string[];
+    /** 1-based line of the statement's first word. */
+    readonly line: number;
+}
+/** One lexical token of SQL: comments and whitespace are dropped; a literal or a quoted body keeps its contents. */
+export type SqlToken = {
+    readonly kind: 'word';
+    readonly text: string;
+    readonly line: number;
+} | {
+    readonly kind: 'quoted';
+    readonly text: string;
+    readonly line: number;
+}
+/** `text` is the literal's value for a plain `'…'` string; an `E'…'` string, whose escapes are not decoded, has none. */
+ | {
+    readonly kind: 'string';
+    readonly text: string | undefined;
+    readonly line: number;
+} | {
+    readonly kind: 'dollar';
+    readonly body: string;
+    readonly line: number;
+} | {
+    readonly kind: 'punct';
+    readonly char: string;
+    readonly line: number;
+};
+/**
+ * The tokens of `sql`. Comments (`--`, nested `/* *\/`), string literals (`''`, `E''` with backslash escapes), quoted
+ * identifiers (`""` unescaped) and dollar-quoted bodies are each one token, so a keyword inside them is no word.
+ */
+export declare function sqlTokens(sql: string): SqlToken[];
+/**
+ * The tokens of `sql`, and the line of the first string, quoted identifier, dollar-quoted body or block comment that
+ * never closes. Text after it is one token, which a check of names cannot read.
+ */
+export declare function lexSql(sql: string): {
+    readonly tokens: SqlToken[];
+    readonly unterminated: number | undefined;
+};
+export interface Statement {
+    /** The statement's tokens, without the `;` that ends it. */
+    readonly tokens: readonly SqlToken[];
+    /** 1-based line of the statement's first token. */
+    readonly line: number;
+}
+/**
+ * Splits SQL into top-level statements at every `;` outside a comment, a literal, a quoted identifier or a
+ * dollar-quoted body. Postgres admits a `;` inside parentheses only in a rule's actions, so splitting there too only
+ * makes a check stricter.
+ */
+export declare function topLevelStatements(sql: string): Statement[];
+export declare const upperWord: (token: SqlToken | undefined) => string | undefined;
+/** Reports how each top-level statement begins. A keyword inside a comment, a literal or a quoted body is no statement. */
+export declare function statementStarts(sql: string): StatementStart[];
+/** The first refused top-level statement of a migration file, or `undefined`. */
+export declare function refusedStatement(sql: string): {
+    readonly statement: string;
+    readonly line: number;
+} | undefined;

package/types/src/pg-catalog-names.d.ts

@@ -0,0 +1,11 @@
+/** The Postgres major versions the sets below are generated from. */
+export declare const PG_CATALOG_MAJORS: readonly number[];
+/** Every function name in `pg_catalog`: an application function may not take one, or a call could resolve to the built-in. */
+export declare const PG_CATALOG_FUNCTIONS: ReadonlySet<string>;
+/** Every SQL keyword, of every category: an application function may not take one (`operator`, `position`). */
+export declare const SQL_KEYWORDS: ReadonlySet<string>;
+/** Per major, the names of the sets above that its own catalog lacks. */
+export declare const PG_CATALOG_ABSENT: ReadonlyMap<number, {
+    functions: ReadonlySet<string>;
+    keywords: ReadonlySet<string>;
+}>;

package/types/src/placeholders.d.ts

@@ -0,0 +1,13 @@
+/** One rewritten statement. `count` is exactly how many values `bind()` must supply. */
+export interface RewrittenSql {
+    /** Postgres-dialect text: every positional `?` replaced by `$1..$n`, left to right. */
+    text: string;
+    /** How many placeholders were rewritten. */
+    count: number;
+}
+/**
+ * Rewrite a `?`-placeholder statement into Postgres `$n` form. Throws on an unterminated string,
+ * identifier, dollar-quote or block comment — the statement is malformed and no rewriting of it can
+ * be trusted.
+ */
+export declare function rewritePlaceholders(sql: string): RewrittenSql;

package/types/src/postgres-migration-error.d.ts

@@ -0,0 +1,4 @@
+/** A refusal or failure of the runner itself. Its message names no credential; a driver error is its `cause`. */
+export declare class PostgresMigrationError extends Error {
+    readonly name = "PostgresMigrationError";
+}

package/types/src/postgres-migrations.d.ts

@@ -0,0 +1,63 @@
+import type { SqlDatabase } from '@fabrika/platform';
+import { PostgresMigrationError } from './postgres-migration-error';
+export interface PostgresMigration {
+    name: string;
+    sql: string;
+}
+export interface PostgresMigrationBundle {
+    name: string;
+    migrations: readonly PostgresMigration[];
+}
+export interface PostgresMigrationPlan {
+    /** Service-scoped ledger table, such as `iam_schema_migrations`; an application's is qualified by its schema. */
+    ledgerTable: string;
+    /** Service-specific session advisory lock. Keep this stable across runner upgrades. */
+    lockKey: number;
+    bundles: readonly PostgresMigrationBundle[];
+    /** Present only in an application's plan (ADR-0017): its schema, a checksum per migration, and timeouts. */
+    application?: PostgresApplicationMigrationSettings;
+}
+export interface PostgresApplicationMigrationSettings {
+    /** Created when absent. Each migration runs with it as its only `search_path`. */
+    schema: string;
+    /** `lock_timeout` of each migration, so a blocked `ALTER` fails the deploy instead of stalling the live version. */
+    lockTimeoutMs: number;
+    statementTimeoutMs: number;
+    /** The framework's own bundle (`fabrika`), which alone may name the framework's `fabrika_*` tables. */
+    frameworkBundle?: string;
+    /**
+     * The application's runtime role. Before the plan runs, the migration role's default privileges are cleared of
+     * PUBLIC; after it ran, the runtime role's and PUBLIC's privileges in the schema are reset to the runtime role's DML
+     * on every table but the ledger and verified, in one transaction under the migration lock; it never gets DDL.
+     */
+    runtimeRole?: string;
+    /** How long the runner waits for the migration lock; any session may take an advisory lock, so the wait is bounded. */
+    advisoryLockTimeoutMs?: number;
+}
+export { PostgresMigrationError };
+export interface ReadPostgresMigrationBundleOptions {
+    name: string;
+    directory: string;
+    files?: readonly string[];
+}
+/** Read one ordered migration bundle from disk. An explicit file list fails closed when a file is absent. */
+export declare function readPostgresMigrationBundle(options: ReadPostgresMigrationBundleOptions): PostgresMigrationBundle;
+/** The generic migrations owned by the long-running Bun runtime. */
+export declare function platformNodePostgresMigrationBundle(files?: readonly string[]): PostgresMigrationBundle;
+/** Validate a complete plan at composition time, before any SQL is executed. */
+export declare function definePostgresMigrationPlan(plan: PostgresMigrationPlan): PostgresMigrationPlan;
+export declare function postgresMigrationIdentity(bundle: string, name: string): string;
+/** Preserve a service wrapper's historical filename-only result while the core uses qualified ids. */
+export declare function postgresMigrationFilenames(identities: readonly string[], bundle: string): string[];
+/**
+ * Apply a plan over one Postgres session.
+ *
+ * The caller must supply a database backed by a single-connection pool. Advisory locks are session
+ * state; allowing acquire and release to land on different pooled connections would make the runner
+ * appear serialized while providing no serialization at all.
+ */
+export declare function applyPostgresMigrations(db: SqlDatabase, input: PostgresMigrationPlan, options?: {
+    now?: () => number;
+}): Promise<string[]>;
+/** SHA-256 of the file's text, hex. */
+export declare function migrationChecksum(sql: string): string;

package/types/src/postgres-test-provisioner.d.ts

@@ -0,0 +1,37 @@
+import type { SqlDatabase } from '@fabrika/platform';
+/** A provisioning credential that exists for one test run only, and what it created. */
+export interface TestProvisioner {
+    /**
+     * Connects as `fabrika_tests_<hex>`: CREATEROLE and CREATE on the database, nothing of any application, and a login
+     * for `TEST_PROVISIONER_LIFETIME_MINUTES` only.
+     */
+    readonly url: string;
+    /** The provisioners of earlier runs that creating this one dropped. Role names, never a credential. */
+    readonly swept: readonly string[];
+    /** Drops every role the provisioner created, with everything those roles own, then the provisioner itself. */
+    drop(): Promise<void>;
+}
+/**
+ * Every grant or revoke on a database changes its one `pg_database` row, and two concurrent changes of that row fail with
+ * `tuple concurrently updated`, so each change waits for this transaction-level lock first.
+ */
+export declare const DATABASE_GRANT_LOCK_KEY: number;
+/**
+ * Grants (or revokes) CREATE on `database` to `role`, serialized with every other run that does so on the same server.
+ * Verified afterwards: a grantor that neither owns the database, is a superuser nor holds CREATE WITH GRANT OPTION only
+ * gets a WARNING, and the statement changes nothing.
+ */
+export declare function changeCreateOnDatabase(admin: SqlDatabase, change: 'grant' | 'revoke', role: string, database: string): Promise<void>;
+/**
+ * How long a provisioner can log in (`VALID UNTIL`). A run that a kill stopped before `drop()` leaves its provisioner
+ * behind, and nobody knows its password; after this time it also cannot log in, and the next run's sweep drops it. A
+ * run makes new connections until it ends, so this is far beyond the longest run.
+ */
+export declare const TEST_PROVISIONER_LIFETIME_MINUTES = 15;
+/**
+ * Creates a throwaway provisioning credential for code the platform runs but did not write, such as an application's
+ * generated tests: it can create the test kit's role families and schemas, and reaches no application's data, because
+ * a CREATEROLE role administers only the roles it created. The provisioning credential itself never leaves this process.
+ * First it drops the provisioners earlier runs left behind (`sweepTestProvisioners`).
+ */
+export declare function createTestProvisioner(provisioningUrl: string): Promise<TestProvisioner>;

package/types/src/service-postgres-migrations.d.ts

@@ -0,0 +1,25 @@
+import type { SqlDatabase } from '@fabrika/platform';
+import { type PostgresMigration, type PostgresMigrationBundle, type PostgresMigrationPlan } from './postgres-migrations';
+export interface PostgresServiceMigrationsConfig {
+    /** Stable service-owned bundle name. */
+    readonly name: string;
+    /** Stable service-owned ledger table. */
+    readonly ledgerTable: string;
+    /** Stable service advisory lock. */
+    readonly lockKey: number;
+    readonly directory: string;
+    /** Runtime-owned bundles applied before the service schema. */
+    readonly dependencies?: readonly PostgresMigrationBundle[];
+}
+export interface PostgresServiceMigrations {
+    read(directory?: string): PostgresMigration[];
+    plan(migrations?: readonly PostgresMigration[]): PostgresMigrationPlan;
+    apply(db: SqlDatabase, migrations?: readonly PostgresMigration[]): Promise<string[]>;
+    applyQualified(db: SqlDatabase, migrations?: readonly PostgresMigration[]): Promise<string[]>;
+}
+/**
+ * Define the repeated service migration wrapper while keeping service identity and lifecycle local.
+ * Bundle names, ledgers, lock ids, and dependency order remain explicit inputs.
+ */
+export declare function definePostgresServiceMigrations(config: PostgresServiceMigrationsConfig): PostgresServiceMigrations;
+export declare function postgresMigrationResultMessage(applied: readonly string[]): string;

package/types/src/sql-names.d.ts

@@ -0,0 +1,101 @@
+import { type SqlToken } from './migration-sql';
+export declare const isName: (token: SqlToken | undefined) => boolean;
+export declare const isPunct: (token: SqlToken | undefined, char: string) => boolean;
+/** A name as Postgres stores it: an unquoted one with only ASCII folded to lower case, either truncated to 63 bytes. */
+export declare function nameText(token: SqlToken | undefined): string | undefined;
+/** The index past a name at `index`, schema-qualified or not, or `undefined` when no name is there. */
+export declare function afterName(tokens: readonly SqlToken[], index: number): number | undefined;
+/** A possibly schema-qualified object name: `qualifier` is set only when the statement wrote one. */
+export interface ObjectName {
+    readonly qualifier: string | undefined;
+    readonly name: string;
+}
+/** The name at `index` (`name` or `schema.name`), or `undefined`. */
+export declare function objectNameAt(tokens: readonly SqlToken[], index: number): ObjectName | undefined;
+/** The index past the words `words` at `index`, or `index` itself when they are not all there. */
+export declare function skipWords(tokens: readonly SqlToken[], index: number, ...words: readonly string[]): number;
+/** The token lists between the commas at parenthesis depth 0 of `tokens`. */
+export declare function splitAtCommas(tokens: readonly SqlToken[]): SqlToken[][];
+/** The index of the `)` that closes the `(` at `open`, or `undefined`. */
+export declare function closingParenthesis(tokens: readonly SqlToken[], open: number): number | undefined;
+/** The index of the first word `word` at parenthesis depth 0 at or after `from`, or `undefined`. */
+export declare function wordAtDepthZero(tokens: readonly SqlToken[], word: string, from?: number): number | undefined;
+/**
+ * What a statement is, for a refusal to name: its first word, and after `CREATE`, `ALTER` or `DROP` (past `OR
+ * REPLACE`) the kind of object. A statement that does not begin with a word is named by its first token.
+ */
+export declare function statementKind(tokens: readonly SqlToken[]): string;
+/**
+ * The first schema a DDL statement names other than `schema`, `pg_catalog` included: every qualified name counts,
+ * since a DDL statement has no table alias to qualify a column with, and so does any unqualified `pg_…` name, which
+ * resolves to the catalog (`LIKE pg_authid`, `REFERENCES pg_class`).
+ */
+export declare function ddlForeignSchema(tokens: readonly SqlToken[], schema: string): string | undefined;
+/** How a name is used where it stands; `operator` is the operator `OPERATOR(schema.op)` names. */
+export type NameRole = 'relation' | 'call' | 'type' | 'operator' | 'other';
+/** One name of a statement: `qualifier` is the first part of a two- or three-part name. */
+export interface NameReference {
+    readonly qualifier: string | undefined;
+    readonly name: string;
+    readonly parts: number;
+    readonly role: NameRole;
+    readonly line: number;
+}
+/**
+ * Every name of a DML statement, a query or an expression, with its role. A name in a relation position (after
+ * `FROM`, `JOIN`, `USING`, `INTO`, `UPDATE`, `TABLE`, `REFERENCES`, or a `,` of a `FROM` list) is a relation; a name
+ * that `(` follows is a call, unless it is syntax or a type with a modifier; a name after `::` or `AS` is a type. A
+ * two-part name anywhere else is a column of a table or an alias (`d.note`, `NEW.stage`).
+ */
+export declare function nameReferences(tokens: readonly SqlToken[]): NameReference[];
+/**
+ * The first schema a DML statement, a query or a function body reaches other than `schema`, `pg_catalog` included: a
+ * qualified relation, call or type, or a three-part name. An unqualified relation whose name starts with `pg_`
+ * resolves to the catalog and counts as `pg_catalog`.
+ */
+export declare function dmlForeignSchema(tokens: readonly SqlToken[], schema: string): string | undefined;
+/**
+ * The first nested statement a nested position may not hold: in parentheses (a CTE body, a subquery) and after a
+ * CTE list, anything but a query or `INSERT`/`UPDATE`/`DELETE`, whose names the same checks read. `MERGE` among them.
+ */
+export declare function nestedStatement(tokens: readonly SqlToken[]): {
+    readonly statement: string;
+    readonly line: number;
+} | undefined;
+/**
+ * The first data-changing statement whose target is in parentheses (`UPDATE ONLY (t)`, `DELETE FROM (t)`): the
+ * classifier reads a target as the name after the keyword, so it refuses the form rather than read through a group.
+ */
+export declare function parenthesizedTarget(tokens: readonly SqlToken[]): {
+    readonly statement: string;
+    readonly line: number;
+} | undefined;
+/** The relations a DML statement or a query names, in order: what its static text reads or writes. */
+export declare function dmlRelations(tokens: readonly SqlToken[]): NameReference[];
+/**
+ * Whether a name is the framework's (`fabrika_…`): its tables share the application's schema and hold its secrets,
+ * leases and deliveries. Case-insensitive, so a quoted `"FABRIKA_x"` counts too.
+ */
+export declare function isFrameworkName(name: string): boolean;
+/** The first framework name among `tokens` that `allowed` does not hold, with its line. */
+export declare function frameworkReference(tokens: readonly SqlToken[], allowed?: ReadonlySet<string>): {
+    readonly name: string;
+    readonly line: number;
+} | undefined;
+/** `U&"…"`: an identifier whose escapes the lexer does not decode, so a name rule cannot read it. */
+export declare function unicodeIdentifier(tokens: readonly SqlToken[]): {
+    readonly line: number;
+} | undefined;
+/** How a call is admitted: `paved` and `reviewed` built-ins, `expression`-only ones, and the migrations' own functions. */
+export type FunctionUse = 'paved' | 'reviewed' | 'declared';
+/**
+ * How a call of `call` is admitted, or `undefined` when it is not. A function the migrations declare in `schema` may be
+ * called unqualified or qualified with `schema`; a built-in only unqualified, since a qualified one names `pg_catalog`.
+ */
+export declare function functionUse(call: NameReference, schema: string, functions: ReadonlySet<string>): FunctionUse | undefined;
+/**
+ * The first call among `tokens` that a body, a query or a backfill may not make: anything but a paved or reviewed
+ * built-in, or a function the migrations declare in `schema`. An allowlist, because a built-in such as
+ * `query_to_xml`, `dblink` or `lo_import` runs SQL from a string or reaches past the schema, which no name rule sees.
+ */
+export declare function refusedFunctionCall(tokens: readonly SqlToken[], schema: string, functions: ReadonlySet<string>): NameReference | undefined;

package/types/src/sql-postgres.d.ts

@@ -0,0 +1,51 @@
+import type { SqlDatabase, SqlQueryResult, SqlRunResult, SqlStatement } from '@fabrika/platform';
+/** What a bound value may be. Anything else is a programming error and throws at bind time, as D1 does. */
+export type SqlBindValue = string | number | bigint | boolean | Date | Uint8Array | null;
+/**
+ * One prepared statement. IMMUTABLE: `bind()` returns a NEW statement carrying the values and leaves
+ * the receiver untouched, which is D1's contract and what call sites rely on when they prepare once
+ * and bind in a loop.
+ */
+export declare class PostgresStatement implements SqlStatement {
+    private readonly sql;
+    private readonly text;
+    private readonly placeholders;
+    private readonly values;
+    constructor(sql: Bun.SQL, text: string, placeholders: number, values: readonly SqlBindValue[]);
+    bind(...values: unknown[]): SqlStatement;
+    first<T = Record<string, unknown>>(): Promise<T | null>;
+    all<T = Record<string, unknown>>(): Promise<SqlQueryResult<T>>;
+    run(): Promise<SqlRunResult>;
+    /** This statement, once every placeholder has its value: a wrong count fails before any connection is taken. */
+    bound(): PostgresStatement;
+    /**
+     * Run this statement on a specific handle — a reserved connection of the pool, or the one `batch()` holds its
+     * transaction on. Internal to the package; the port only ever sees `first`/`all`/`run`.
+     */
+    rows<T>(handle: Bun.SQL): Promise<T[]>;
+}
+/**
+ * A Postgres-backed `SqlDatabase`. Rewritten statement text is memoised per SQL string, so the
+ * prepare-once/bind-many idiom tokenises each statement exactly once.
+ */
+export declare class PostgresDatabase implements SqlDatabase {
+    private readonly sql;
+    private readonly rewrites;
+    constructor(sql: Bun.SQL);
+    /**
+     * Open a pooled client. The URL is a CREDENTIAL — it is never logged, and never included in an
+     * error message raised here.
+     */
+    static connect(url: string, options?: Omit<Bun.SQL.PostgresOrMySQLOptions, 'url' | 'adapter'>): PostgresDatabase;
+    prepare(sql: string): SqlStatement;
+    /**
+     * Run every statement in ONE transaction, in order. A throw rolls the whole batch back. The transaction is sent by
+     * hand on the reserved connection: Bun 1.3.14's `begin()` on a reserved connection rejects a failed statement twice,
+     * once unhandled.
+     */
+    batch<T = Record<string, unknown>>(statements: SqlStatement[]): Promise<SqlQueryResult<T>[]>;
+    /** Close the pool. Waits for in-flight queries unless a timeout is given. */
+    close(options?: {
+        timeout?: number;
+    }): Promise<void>;
+}

package/types/src/sql.d.ts

@@ -0,0 +1,6 @@
+export { applicationDatabaseSchema } from './application-schema';
+export { FILE_SCAN_COLUMNS, FILE_STATUSES, FILE_TABLE_PREFIX, fileScanAlter, fileScanAlterTable, fileScanIndex, fileStatusCheck, fileTableScanReady, legacyStatusCheckName, } from './file-table-ddl';
+export { classifyMigration, type ClassifyMigrationOptions, classifyMigrations, type DatabaseObject, type DatabaseObjectKind, declaredFunctions, type DeviationKind, type ManifestChange, type MigrationClassification, type MigrationDeviation, type MigrationFile, migrationManifest, type MigrationRefusal, type MigrationSetClassification, } from './migration-classify';
+export { lexSql, type SqlToken, sqlTokens, type Statement, topLevelStatements, upperWord } from './migration-sql';
+export { PG_CATALOG_FUNCTIONS, SQL_KEYWORDS } from './pg-catalog-names';
+export { afterName, closingParenthesis, ddlForeignSchema, dmlForeignSchema, dmlRelations, frameworkReference, type FunctionUse, functionUse, isFrameworkName, isPunct, type NameReference, nameReferences, type NameRole, nameText, nestedStatement, objectNameAt, parenthesizedTarget, refusedFunctionCall, skipWords, splitAtCommas, statementKind, unicodeIdentifier, } from './sql-names';

package/types/src/wait-until.d.ts

@@ -0,0 +1,20 @@
+import type { WaitUntil } from '@fabrika/platform';
+export interface BackgroundTasks {
+    /** The port itself. Hand it a promise and forget it; it never throws and never rejects. */
+    readonly waitUntil: WaitUntil;
+    /** How many supervised promises are still in flight. */
+    readonly pending: number;
+    /** Settle once every supervised promise has finished, including ones added while draining. */
+    drain(): Promise<void>;
+}
+export interface BackgroundTasksOptions {
+    /**
+     * Called for every rejection instead of the default log. Keep it cheap and non-throwing — a throw
+     * here is itself swallowed. NEVER log the error object: it may quote a clone URL with an embedded
+     * token.
+     */
+    onError?: (error: unknown) => void;
+    /** Prefix for the default log line, so a process running several of these can tell them apart. */
+    label?: string;
+}
+export declare function createBackgroundTasks(options?: BackgroundTasksOptions): BackgroundTasks;