@spfn/core 0.2.0-beta.9 → 0.3.0-beta.1

package/dist/db/index.d.ts

@@ -1,12 +1,48 @@
 import { PostgresJsDatabase } from 'drizzle-orm/postgres-js';
 import postgres, { Sql } from 'postgres';
-import * as drizzle_orm from 'drizzle-orm';
-import { SQL } from 'drizzle-orm';
 import * as drizzle_orm_pg_core from 'drizzle-orm/pg-core';
-import { PgColumn, PgTable } from 'drizzle-orm/pg-core';
+import { PgAsyncDatabase, PgAsyncTransaction, PgColumn, PgTable } from 'drizzle-orm/pg-core';
+import * as drizzle_orm from 'drizzle-orm';
+import { SQL, InferSelectModel, InferInsertModel, AnyRelations, EmptyRelations } from 'drizzle-orm';
 import * as hono_types from 'hono/types';
 import { DatabaseError } from '@spfn/core/errors';
 
+/**
+ * Database Manager Types
+ */
+
+/**
+ * DB connection type
+ */
+type DbConnectionType = 'read' | 'write';
+/**
+ * Common base for PostgreSQL Drizzle drivers.
+ *
+ * Both the built-in postgres.js database and externally supplied drivers such
+ * as PGlite extend this class.
+ */
+type DrizzleDatabase = PgAsyncDatabase<any, any>;
+/** Default database type used by the environment-backed postgres.js path. */
+type DefaultDatabase = PostgresJsDatabase;
+/** Resolve the transaction type belonging to a PostgreSQL Drizzle database. */
+type DatabaseTransaction<TDatabase extends DrizzleDatabase> = TDatabase extends PgAsyncDatabase<infer TQueryResult, infer TRelations> ? PgAsyncTransaction<TQueryResult, TRelations> : never;
+/**
+ * An externally owned PostgreSQL Drizzle database.
+ *
+ * The provider owns connection creation. SPFN calls `close` at most once when
+ * `closeDatabase()` or server shutdown releases the registered provider.
+ */
+interface DatabaseProvider<TDatabase extends DrizzleDatabase = DrizzleDatabase> {
+    /** Primary database for writes (and reads when no replica is supplied). */
+    write: TDatabase;
+    /** Optional read replica. Falls back to `write`. */
+    read?: TDatabase;
+    /** Driver identifier used for diagnostics, for example `pglite`. */
+    kind: string;
+    /** Release provider-owned resources. */
+    close?: () => void | Promise<void>;
+}
+
 /**
  * Database Configuration
  *
@@ -23,11 +59,11 @@ import { DatabaseError } from '@spfn/core/errors';
  * - src/server/core/db/index.ts (main exports)
  */
 
-interface DatabaseClients {
+interface DatabaseClients<TDatabase extends DrizzleDatabase = PostgresJsDatabase> {
     /** Primary database for writes (or both read/write if no replica) */
-    write?: PostgresJsDatabase;
+    write?: TDatabase;
     /** Replica database for reads (optional, falls back to write) */
-    read?: PostgresJsDatabase;
+    read?: TDatabase;
     /** Raw postgres client for write operations (for cleanup) */
     writeClient?: Sql;
     /** Raw postgres client for read operations (for cleanup) */
@@ -71,6 +107,17 @@ interface DatabaseOptions {
      */
     monitoring?: Partial<MonitoringConfig>;
 }
+/** Database initialization options, including an optional external provider. */
+interface DatabaseInitOptions<TDatabase extends DrizzleDatabase = PostgresJsDatabase> extends DatabaseOptions {
+    /**
+     * Externally owned PostgreSQL Drizzle provider.
+     *
+     * When set, environment-based postgres.js initialization, health checks,
+     * and automatic reconnect are skipped. The provider's `close` callback is
+     * used during shutdown.
+     */
+    provider?: DatabaseProvider<TDatabase>;
+}
 /**
  * Connection pool configuration
  *
@@ -81,6 +128,21 @@ interface PoolConfig {
     max: number;
     /** Idle connection timeout in seconds */
     idleTimeout: number;
+    /**
+     * Maximum connections for the read-replica pool. Defaults to `max`. Set
+     * separately (DB_POOL_READ_MAX) so a master-replica app can size the two
+     * pools independently and keep `write.max + read.max` under the server's
+     * `max_connections` (otherwise each process opens up to 2 × max).
+     */
+    readMax?: number;
+    /**
+     * Use server-side prepared statements (postgres-js `prepare`). When
+     * `undefined`, the connection layer auto-detects: it is disabled for
+     * transaction-mode poolers (PgBouncer/Supavisor, e.g. Supabase :6543),
+     * where cached statements break as the pooler rotates backends, and
+     * enabled otherwise. Set explicitly (or via `SPFN_DB_PREPARE`) to override.
+     */
+    prepare?: boolean;
 }
 /**
  * Retry configuration for exponential backoff algorithm
@@ -134,15 +196,6 @@ interface RetryConfig {
  */
 declare function createDatabaseFromEnv(options?: DatabaseOptions): Promise<DatabaseClients>;
 
-/**
- * Database Manager Types
- */
-
-/**
- * DB connection type
- */
-type DbConnectionType = 'read' | 'write';
-
 /**
  * Global Database instance manager
  * Provides singleton access to database across all modules
@@ -169,7 +222,7 @@ type DbConnectionType = 'read' | 'write';
  * const posts = await dbRead.select().from(postsTable);
  * ```
  */
-declare function getDatabase(type?: DbConnectionType): PostgresJsDatabase<Record<string, unknown>>;
+declare function getDatabase<TDatabase extends DrizzleDatabase = DefaultDatabase>(type?: DbConnectionType): TDatabase;
 /**
  * Set global database instances (for testing or manual configuration)
  *
@@ -199,9 +252,17 @@ declare function getDatabase(type?: DbConnectionType): PostgresJsDatabase<Record
  * setDatabase(undefined, undefined);
  * ```
  */
-declare function setDatabase(write: PostgresJsDatabase<Record<string, unknown>> | undefined, read?: PostgresJsDatabase<Record<string, unknown>> | undefined): void;
+declare function setDatabase<TDatabase extends DrizzleDatabase = DefaultDatabase>(write: TDatabase | undefined, read?: TDatabase | undefined): void;
+/**
+ * Register an externally owned PostgreSQL Drizzle provider.
+ *
+ * This is the synchronous/manual counterpart to `initDatabase({ provider })`.
+ * It performs no connection test. Use `closeDatabase()` to invoke the
+ * provider's close callback and clear the global instances.
+ */
+declare function setDatabaseProvider<TDatabase extends DrizzleDatabase>(provider: DatabaseProvider<TDatabase>): DatabaseClients<TDatabase>;
 /**
- * Initialize database from environment variables
+ * Initialize a database provider or create postgres.js clients from environment variables
  * Automatically called by server startup
  *
  * Supported environment variables:
@@ -246,14 +307,11 @@ declare function setDatabase(write: PostgresJsDatabase<Record<string, unknown>>
  * });
  * ```
  */
-declare function initDatabase(options?: DatabaseOptions): Promise<{
-    write?: PostgresJsDatabase<Record<string, unknown>>;
-    read?: PostgresJsDatabase<Record<string, unknown>>;
-}>;
+declare function initDatabase<TDatabase extends DrizzleDatabase = DefaultDatabase>(options?: DatabaseInitOptions<TDatabase>): Promise<DatabaseClients<TDatabase>>;
 /**
- * Close all database connections and cleanup
+ * Close the active database provider or postgres.js connections and clean up
  *
- * Properly closes postgres connection pools with timeout.
+ * Invokes an external provider's close callback, or closes postgres.js pools with timeout.
  * Should be called during graceful shutdown or after tests.
  *
  * @example
@@ -273,6 +331,36 @@ declare function initDatabase(options?: DatabaseOptions): Promise<{
  * ```
  */
 declare function closeDatabase(): Promise<void>;
+/**
+ * Force an immediate database pool rebuild
+ *
+ * Destroys the current postgres.js pool(s) and rebuilds them with the same
+ * configuration passed to the original `initDatabase()` call (or whatever
+ * was detected from environment variables). Uses the same atomic-swap
+ * strategy as the periodic health check: new connections are created and
+ * tested BEFORE the old ones are torn down, so `getDatabase()` callers never
+ * observe a missing instance.
+ *
+ * Use this when application code detects that the pool is stuck and does not
+ * want to wait for the next periodic health check tick. Concurrent calls are
+ * coalesced — if a reconnect is already in progress, this resolves to `false`
+ * without starting a second one.
+ *
+ * @param reason - Short label describing why the rebuild was requested (for logs)
+ * @returns `true` if a reconnection ran, `false` if one was already in-flight.
+ *          Resolves after the rebuild completes (success or max retries exhausted).
+ *
+ * @example
+ * ```typescript
+ * import { forceReconnectDatabase } from '@spfn/core/db';
+ *
+ * app.post('/admin/db/reconnect', async (c) => {
+ *     const ran = await forceReconnectDatabase('admin_request');
+ *     return c.json({ reconnected: ran });
+ * });
+ * ```
+ */
+declare function forceReconnectDatabase(reason?: string): Promise<boolean>;
 /**
  * Get database connection info (for debugging)
  *
@@ -306,8 +394,63 @@ declare function getDatabaseInfo(): {
     hasWrite: boolean;
     hasRead: boolean;
     isReplica: boolean;
+    providerKind?: string;
 };
 
+/**
+ * Reconnect Trigger — Query-error driven pool rebuild
+ *
+ * Complements the periodic health check with a fast-path: when application
+ * queries start failing with connection-level errors, we do not wait up to
+ * DB_HEALTH_CHECK_INTERVAL (default 60s) to notice. A sliding-window counter
+ * trips a force-reconnect as soon as the failure rate crosses a threshold.
+ *
+ * Why this exists:
+ *  - postgres.js transparently drops dead sockets and opens new ones on the
+ *    next query. A single `SELECT 1` on the periodic interval can therefore
+ *    false-pass while user-facing queries keep hitting the remaining dead
+ *    sockets in the pool.
+ *  - This module observes real query errors and, when it sees a burst of
+ *    connection-level failures, calls triggerForceReconnect() which performs
+ *    the same atomic-swap rebuild as the health check.
+ *
+ * Configuration (env vars, hardcoded defaults):
+ *  - DB_RECONNECT_ERROR_THRESHOLD (default 3): errors needed in window
+ *  - DB_RECONNECT_ERROR_WINDOW_MS (default 10000): sliding window size
+ */
+/**
+ * Determine whether an error looks like a pool/connection failure
+ *
+ * Returns true when any layer in the error chain exposes a connection-level
+ * code (postgres.js driver code, Node network errno, PG SQLSTATE class 08 etc.)
+ * or is an instance of our own ConnectionError wrapper.
+ *
+ * Returns false for query errors (syntax, constraint violations, etc.) — those
+ * should NOT trigger a pool rebuild.
+ */
+declare function isConnectionLevelError(error: unknown): boolean;
+/**
+ * Reset the internal error counter
+ *
+ * Exposed for tests that need a clean slate between cases. Does not clear
+ * the WeakSet (which is GC-backed and self-cleans with error lifetimes).
+ */
+declare function resetConnectionErrorCounter(): void;
+/**
+ * Report a database error to the reconnect trigger
+ *
+ * Call this from any site that catches a query error before rethrowing.
+ * It is a no-op for non-connection-level errors. When the threshold is
+ * crossed it calls triggerForceReconnect() in the background — callers
+ * should NOT await it.
+ *
+ * Safe to call from any context: catches its own errors so it cannot
+ * disrupt the calling catch block. Deduplicates across error-chain
+ * re-wrapping so one failure counts exactly once regardless of how many
+ * catch layers it passes through.
+ */
+declare function reportDatabaseError(error: unknown): void;
+
 /**
  * Create database connection with exponential backoff retry strategy
  *
@@ -380,6 +523,8 @@ interface DrizzleConfigOptions {
     schemaFilter?: string[];
     /** Auto-detect PostgreSQL schemas from entity files (requires expandGlobs: true) */
     autoDetectSchemas?: boolean;
+    /** Migration prefix strategy (default: 'timestamp') */
+    migrationPrefix?: 'index' | 'timestamp' | 'unix' | 'none';
 }
 /**
  * Detect database dialect from connection URL
@@ -411,6 +556,9 @@ declare function getDrizzleConfig(options?: DrizzleConfigOptions): {
     dbCredentials: {
         url: string;
     };
+    migrations: {
+        prefix: "timestamp" | "none" | "index" | "unix";
+    };
     schemaFilter?: undefined;
 } | {
     schema: string | string[];
@@ -420,6 +568,9 @@ declare function getDrizzleConfig(options?: DrizzleConfigOptions): {
         url: string;
     };
     schemaFilter: string[] | undefined;
+    migrations: {
+        prefix: "timestamp" | "none" | "index" | "unix";
+    };
 };
 /**
  * Generate drizzle.config.ts file content
@@ -442,12 +593,23 @@ declare function generateDrizzleConfigFile(options?: DrizzleConfigOptions): stri
  * });
  * ```
  */
-declare function id(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm_pg_core.PgBigSerial53BuilderInitial<"id">>>;
+declare function id(): drizzle_orm_pg_core.SetIsPrimaryKey<drizzle_orm_pg_core.PgBigSerial53Builder>;
 /**
  * Standard timestamp fields (createdAt, updatedAt)
  *
- * Both fields are timezone-aware, auto-set to current time on creation.
- * updatedAt must be manually updated in your application code.
+ * Both fields are timezone-aware and come from the database clock, never from the
+ * application process. On insert both take `now()` through their column default, so a
+ * new row's two timestamps are equal. On update Drizzle sets `updated_at = now()` for
+ * you — do not pass `new Date()` yourself.
+ *
+ * Stamping `updated_at` from the application would read a second clock: the app host
+ * and the database host are the same machine in development and different machines in
+ * production, so a row could record an update earlier than its own creation, and
+ * ordering rows by `updated_at` would order by whichever host's clock ran ahead.
+ *
+ * `now()` is the transaction's start time, matching what `.defaultNow()` writes. It is
+ * not a commit-order sequence — anything that needs a true sequence needs a sequence
+ * column, not a timestamp.
  *
  * @returns Object with createdAt and updatedAt columns
  *
@@ -459,23 +621,20 @@ declare function id(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm_
  *     ...timestamps(),
  * });
  *
- * // Manual update
+ * // updated_at is stamped by the database — it is not named here
  * await db.update(users)
- *     .set({
- *         email: 'new@example.com',
- *         updatedAt: new Date()
- *     })
+ *     .set({ email: 'new@example.com' })
  *     .where(eq(users.id, userId));
  * ```
  */
 declare function timestamps(): {
-    createdAt: drizzle_orm.NotNull<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgTimestampBuilderInitial<"created_at">>>;
-    updatedAt: drizzle_orm.NotNull<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgTimestampBuilderInitial<"updated_at">>>;
+    createdAt: drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgTimestampBuilder>>;
+    updatedAt: drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgTimestampBuilder>>>;
 };
 /**
  * Foreign key reference to another table
  *
- * Creates a bigserial column with cascade delete.
+ * Creates a bigint column with cascade delete.
  * Type-safe: ensures the reference points to a valid PostgreSQL column.
  *
  * @param name - Column name (e.g., 'author' creates 'author_id')
@@ -495,7 +654,7 @@ declare function timestamps(): {
  */
 declare function foreignKey<T extends PgColumn>(name: string, reference: () => T, options?: {
     onDelete?: 'cascade' | 'set null' | 'restrict' | 'no action';
-}): drizzle_orm.NotNull<drizzle_orm_pg_core.PgBigSerial53BuilderInitial<`${string}_id`>>;
+}): drizzle_orm_pg_core.SetNotNull<drizzle_orm_pg_core.PgBigInt53Builder>;
 /**
  * Optional foreign key reference (nullable)
  *
@@ -515,7 +674,7 @@ declare function foreignKey<T extends PgColumn>(name: string, reference: () => T
  */
 declare function optionalForeignKey<T extends PgColumn>(name: string, reference: () => T, options?: {
     onDelete?: 'cascade' | 'set null' | 'restrict' | 'no action';
-}): drizzle_orm_pg_core.PgBigSerial53BuilderInitial<`${string}_id`>;
+}): drizzle_orm_pg_core.PgBigInt53Builder;
 /**
  * UUID primary key
  *
@@ -533,7 +692,7 @@ declare function optionalForeignKey<T extends PgColumn>(name: string, reference:
  * });
  * ```
  */
-declare function uuid(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_orm.HasDefault<drizzle_orm_pg_core.PgUUIDBuilderInitial<"id">>>>;
+declare function uuid(): drizzle_orm_pg_core.SetIsPrimaryKey<drizzle_orm_pg_core.SetHasDefault<drizzle_orm_pg_core.PgUUIDBuilder>>;
 /**
  * Audit fields for tracking record creators and updaters
  *
@@ -559,8 +718,8 @@ declare function uuid(): drizzle_orm.IsPrimaryKey<drizzle_orm.NotNull<drizzle_or
  * ```
  */
 declare function auditFields(): {
-    createdBy: drizzle_orm_pg_core.PgTextBuilderInitial<"created_by", [string, ...string[]]>;
-    updatedBy: drizzle_orm_pg_core.PgTextBuilderInitial<"updated_by", [string, ...string[]]>;
+    createdBy: drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>;
+    updatedBy: drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>;
 };
 /**
  * Publishing fields for content management
@@ -591,8 +750,8 @@ declare function auditFields(): {
  * ```
  */
 declare function publishingFields(): {
-    publishedAt: drizzle_orm_pg_core.PgTimestampBuilderInitial<"published_at">;
-    publishedBy: drizzle_orm_pg_core.PgTextBuilderInitial<"published_by", [string, ...string[]]>;
+    publishedAt: drizzle_orm_pg_core.PgTimestampBuilder;
+    publishedBy: drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>;
 };
 /**
  * Custom verification timestamp field
@@ -621,7 +780,7 @@ declare function publishingFields(): {
  * ```
  */
 declare function verificationTimestamp(fieldName: string): {
-    [x: string]: drizzle_orm_pg_core.PgTimestampBuilderInitial<string>;
+    [x: string]: drizzle_orm_pg_core.PgTimestampBuilder;
 };
 /**
  * Soft delete fields
@@ -655,8 +814,8 @@ declare function verificationTimestamp(fieldName: string): {
  * ```
  */
 declare function softDelete(): {
-    deletedAt: drizzle_orm_pg_core.PgTimestampBuilderInitial<"deleted_at">;
-    deletedBy: drizzle_orm_pg_core.PgTextBuilderInitial<"deleted_by", [string, ...string[]]>;
+    deletedAt: drizzle_orm_pg_core.PgTimestampBuilder;
+    deletedBy: drizzle_orm_pg_core.PgTextBuilder<[string, ...string[]]>;
 };
 /**
  * UTC timestamp field
@@ -688,7 +847,7 @@ declare function softDelete(): {
  * });
  * ```
  */
-declare function utcTimestamp(fieldName: string, mode?: 'date' | 'string'): drizzle_orm_pg_core.PgTimestampBuilderInitial<string>;
+declare function utcTimestamp(fieldName: string, mode?: 'date' | 'string'): drizzle_orm_pg_core.PgTimestampBuilder;
 /**
  * Type-safe enum text field
  *
@@ -722,7 +881,7 @@ declare function utcTimestamp(fieldName: string, mode?: 'date' | 'string'): driz
  * });
  * ```
  */
-declare function enumText<T extends readonly [string, ...string[]]>(fieldName: string, values: T): drizzle_orm_pg_core.PgTextBuilderInitial<string, drizzle_orm.Writable<T & [string, ...string[]]>>;
+declare function enumText<T extends readonly [string, ...string[]]>(fieldName: string, values: T): drizzle_orm_pg_core.PgTextBuilder<drizzle_orm.Writable<T & [string, ...string[]]>>;
 /**
  * Type-safe JSONB field
  *
@@ -765,7 +924,7 @@ declare function enumText<T extends readonly [string, ...string[]]>(fieldName: s
  * tags: typedJsonb<string[]>('tags').notNull(),
  * ```
  */
-declare function typedJsonb<T>(fieldName: string): drizzle_orm.$Type<drizzle_orm_pg_core.PgJsonbBuilderInitial<string>, T>;
+declare function typedJsonb<T>(fieldName: string): drizzle_orm_pg_core.Set$Type<drizzle_orm_pg_core.PgJsonbBuilder, T>;
 
 /**
  * Database Schema Helper
@@ -828,6 +987,137 @@ declare function getSchemaInfo(packageName: string): {
     scope: string | null;
 };
 
+/**
+ * Function Package Migration Discovery
+ *
+ * Finds the migrations shipped by installed SPFN function packages (e.g.
+ * `@spfn/auth`) and reads their entries. Both drizzle-kit layouts are
+ * supported — `NNNN_name.sql` + `meta/_journal.json` (≤0.31) and
+ * `<YYYYMMDDHHMMSS>_name/migration.sql` (1.0) — so an installed package keeps
+ * working regardless of which drizzle-kit generated it.
+ *
+ * This module only reads the filesystem. Applying migrations is the CLI's job
+ * (`spfn db migrate`); the server and `spfn db status` share the reading half.
+ */
+type FunctionMigrationInfo = {
+    packageName: string;
+    migrationsDir: string;
+    packagePath: string;
+};
+type FunctionMigrationEntry = {
+    name: string;
+    statements: string[];
+    hash: string;
+    millis: number;
+};
+/**
+ * Per-package migrations table name — must match the CLI's migration runner.
+ */
+declare function functionMigrationsTable(packageName: string): string;
+/**
+ * Discover all installed SPFN function packages that ship migrations.
+ *
+ * A package opts in with a `spfn.migrations.dir` field in its package.json.
+ * Returns an empty list when the project has no `node_modules/@spfn` at all,
+ * which is also the "nothing to check" answer for apps without function packages.
+ */
+declare function discoverFunctionMigrations(cwd?: string): FunctionMigrationInfo[];
+/**
+ * Read a package's migration entries, auto-detecting the folder layout.
+ *
+ * A `meta/_journal.json` marks the drizzle-kit ≤0.31 layout; without it the
+ * directory is read as the drizzle-kit 1.0 layout.
+ */
+declare function readMigrationEntries(migrationsDir: string, packageName: string): FunctionMigrationEntry[];
+
+/**
+ * Migration Status Inspection
+ *
+ * Compares what each migration folder ships (function packages, plus the
+ * project's own `src/server/drizzle`) against what the database records as
+ * applied. `spfn db status`, the server's boot gate and the detailed health
+ * endpoint all read this one implementation.
+ */
+
+/**
+ * Project migrations use drizzle's default table, in the `drizzle` schema.
+ */
+declare const PROJECT_MIGRATIONS_TABLE = "__drizzle_migrations";
+/**
+ * The name `spfn db status` and health use for the project's own migrations.
+ */
+declare const PROJECT_TARGET_NAME = "project (src/server/drizzle)";
+type MigrationTargetStatus = {
+    name: string;
+    total: number;
+    applied: number;
+    pending: number;
+    pendingTags: string[];
+};
+type MigrationStatus = {
+    packages: MigrationTargetStatus[];
+    project: MigrationTargetStatus | null;
+};
+/**
+ * The minimum surface needed to read migration bookkeeping: anything that can
+ * run a drizzle `sql` fragment. The server passes its own pool, the CLI passes
+ * a short-lived connection.
+ */
+interface MigrationStatusDb {
+    execute(query: SQL): Promise<unknown>;
+}
+/**
+ * An entry counts as applied when its name is recorded (drizzle-orm 1.0
+ * projects) or its timestamp is not newer than the last applied record —
+ * the rule the CLI's function-migration runner and drizzle-orm ≤0.45 share.
+ */
+declare function filterPendingEntries(entries: FunctionMigrationEntry[], lastAppliedMillis: number, appliedNames: Set<string>): FunctionMigrationEntry[];
+/**
+ * Every target the status covers, packages first, in the order `spfn db status`
+ * prints them.
+ */
+declare function migrationTargets(status: MigrationStatus): MigrationTargetStatus[];
+/**
+ * The targets that still have migrations waiting.
+ */
+declare function pendingMigrationTargets(status: MigrationStatus): MigrationTargetStatus[];
+/**
+ * Total number of migrations waiting across every target.
+ */
+declare function countPendingMigrations(status: MigrationStatus): number;
+/**
+ * True when the project has nothing whose migration state could be inspected —
+ * no function package ships migrations and there is no project migrations
+ * folder. Callers use this to skip the database round-trip entirely.
+ */
+declare function hasMigrationTargets(cwd?: string): boolean;
+declare function projectMigrationsDir(cwd?: string): string;
+/**
+ * Read applied/pending counts for every function package and for the project.
+ *
+ * The project's own migrations are included when `src/server/drizzle` exists.
+ * A built server image usually does not ship that folder, so the project target
+ * is simply absent there — never reported as drift.
+ */
+declare function collectMigrationStatus(db: MigrationStatusDb, cwd?: string): Promise<MigrationStatus>;
+
+/**
+ * One wording for pending migrations, shared by the server's boot gate and the
+ * CLI's pre-flight check — an operator should read the same lines wherever the
+ * refusal comes from.
+ */
+
+declare const RUN_MIGRATIONS_HINT = "Run: pnpm spfn db migrate";
+/**
+ * Plain (uncoloured) lines listing every target with pending migrations and the
+ * name of each migration still waiting.
+ */
+declare function formatPendingMigrations(targets: MigrationTargetStatus[]): string[];
+/**
+ * The single-sentence reason a boot was refused.
+ */
+declare function pendingMigrationsSummary(targets: MigrationTargetStatus[]): string;
+
 /**
  * AsyncLocalStorage-based Transaction Context
  *
@@ -842,26 +1132,37 @@ declare function getSchemaInfo(packageName: string): {
  */
 
 /**
- * Transaction database type
- * Uses Record<string, unknown> to accept any schema shape
+ * Transaction type belonging to a PostgreSQL Drizzle database.
  */
-type TransactionDB = PostgresJsDatabase<Record<string, unknown>>;
+type TransactionDB<TDatabase extends DrizzleDatabase = DefaultDatabase> = DatabaseTransaction<TDatabase>;
+/**
+ * afterCommit callback type
+ */
+type AfterCommitCallback = () => void | Promise<void>;
 /**
  * Transaction context stored in AsyncLocalStorage
  */
-type TransactionContext = {
+type TransactionContext<TDatabase extends DrizzleDatabase = DrizzleDatabase> = {
     /** The actual Drizzle transaction object */
-    tx: TransactionDB;
+    tx: TransactionDB<TDatabase>;
     /** Unique transaction ID for logging and tracing */
     txId: string;
     level: number;
+    /** Callbacks to execute after root transaction commits */
+    afterCommitCallbacks: AfterCommitCallback[];
 };
+/**
+ * Get current transaction object and metadata from AsyncLocalStorage
+ *
+ * @returns TransactionContext if available, null otherwise
+ */
+declare function getTransactionContext<TDatabase extends DrizzleDatabase = DefaultDatabase>(): TransactionContext<TDatabase> | null;
 /**
  * Get current transaction from AsyncLocalStorage
  *
  * @returns Transaction if available, null otherwise
  */
-declare function getTransaction(): TransactionDB | null;
+declare function getTransaction<TDatabase extends DrizzleDatabase = DefaultDatabase>(): TransactionDB<TDatabase> | null;
 /**
  * Run a function within a transaction context
  *
@@ -873,8 +1174,33 @@ declare function getTransaction(): TransactionDB | null;
  * @param callback - Function to run within transaction context
  * @returns Result of the callback
  */
-declare function runWithTransaction<T>(tx: TransactionDB, txId: string, // Add txId parameter
+declare function runWithTransaction<T, TDatabase extends DrizzleDatabase = DefaultDatabase>(tx: TransactionDB<TDatabase>, txId: string, // Add txId parameter
 callback: () => Promise<T>): Promise<T>;
+/**
+ * Register a callback to run after the current transaction commits
+ *
+ * - Inside a transaction: queued and executed after root transaction commits
+ * - Outside a transaction: executed immediately (already "committed")
+ * - Nested transactions: callbacks bubble up to root transaction
+ * - Callbacks run outside transaction context (new connection for DB access)
+ * - Errors are logged but never thrown (commit already succeeded)
+ *
+ * @example
+ * ```typescript
+ * import { onAfterCommit } from '@spfn/core/db/transaction';
+ *
+ * async function submit(spaceId: string, chatId: string)
+ * {
+ *     const publication = await publicationRepo.create({...});
+ *     await requestRepo.updateStatusAtomically(...);
+ *
+ *     onAfterCommit(() => generateArticle(spaceId, chatId, publication.id));
+ *
+ *     return publication;
+ * }
+ * ```
+ */
+declare function onAfterCommit(callback: AfterCommitCallback): void;
 
 /**
  * Transaction middleware options
@@ -910,6 +1236,15 @@ interface TransactionalOptions {
      * ```
      */
     timeout?: number;
+    /**
+     * Idle-in-transaction timeout in milliseconds — Postgres reclaims the pooled
+     * connection if the transaction sits idle (e.g. the handler awaits external
+     * I/O) longer than this. A backstop against pool starvation, not a license
+     * to do non-DB work inside a transaction. `0` disables it.
+     *
+     * @default 30000 (30s) or TRANSACTION_IDLE_TIMEOUT environment variable
+     */
+    idleTimeout?: number;
 }
 /**
  * Transaction middleware for Hono routes
@@ -955,6 +1290,93 @@ interface TransactionalOptions {
  */
 declare function Transactional(options?: TransactionalOptions): hono_types.MiddlewareHandler<any, string, {}, Response>;
 
+/**
+ * Transaction runner options
+ */
+interface RunInTransactionOptions {
+    /**
+     * Slow transaction warning threshold in milliseconds
+     * @default 1000 (1 second)
+     */
+    slowThreshold?: number;
+    /**
+     * Enable transaction logging
+     * @default true
+     */
+    enableLogging?: boolean;
+    /**
+     * Transaction timeout in milliseconds
+     *
+     * Sets PostgreSQL `statement_timeout` to enforce database-level timeout.
+     * If transaction exceeds this duration, PostgreSQL will automatically cancel
+     * the query and rollback the transaction, ensuring data consistency.
+     *
+     * Behavior:
+     * - `timeout: 0` - Disables timeout (unlimited execution time)
+     * - `timeout: null` - Uses default (30s or TRANSACTION_TIMEOUT env var)
+     * - `timeout: undefined` - Uses default (30s or TRANSACTION_TIMEOUT env var)
+     * - `timeout: N` - Sets timeout to N milliseconds (1 to 2147483647)
+     *
+     * Note: Timeout is only applied to root transactions. Nested transactions
+     * (SAVEPOINTs) inherit the timeout from the outer transaction.
+     *
+     * @default 30000 (30 seconds) or TRANSACTION_TIMEOUT environment variable
+     *
+     * @example
+     * ```typescript
+     * // Use default timeout (30s)
+     * await runInTransaction(callback);
+     *
+     * // Disable timeout for long-running operations
+     * await runInTransaction(callback, { timeout: 0 });
+     *
+     * // Set custom timeout (60s)
+     * await runInTransaction(callback, { timeout: 60000 });
+     * ```
+     */
+    timeout?: number;
+    /**
+     * Idle-in-transaction timeout in milliseconds (root transactions only).
+     *
+     * Sets PostgreSQL `idle_in_transaction_session_timeout`: if the transaction
+     * sits open without running a query for longer than this — e.g. while the
+     * handler awaits external I/O inside the transaction — Postgres terminates
+     * the session and rolls back, reclaiming the pooled connection instead of
+     * letting one stuck request hold it (and its row locks) indefinitely.
+     *
+     * Do not put external I/O inside a transaction; this is a backstop, not a
+     * license. `0` disables it.
+     *
+     * @default 30000 (30s) or TRANSACTION_IDLE_TIMEOUT environment variable
+     */
+    idleTimeout?: number;
+    /**
+     * Context string for logging (e.g., 'migration:add-user', 'script:cleanup')
+     * @default 'transaction'
+     */
+    context?: string;
+}
+/**
+ * Run a callback function within a database transaction
+ *
+ * Automatically manages transaction lifecycle:
+ * - Commits on success
+ * - Rolls back on error
+ * - Tracks execution time
+ * - Warns about slow transactions
+ * - Enforces timeout if configured
+ *
+ * Errors are propagated to the caller without modification.
+ * Caller is responsible for error handling and conversion.
+ *
+ * @param callback - Function to execute within transaction
+ * @param options - Transaction options
+ * @returns Result of callback function
+ * @throws TransactionError if database not initialized or timeout exceeded
+ * @throws Any error thrown by callback function
+ */
+declare function runInTransaction<T, TDatabase extends DrizzleDatabase = DefaultDatabase>(callback: (tx: TransactionDB<TDatabase>) => Promise<T>, options?: RunInTransactionOptions): Promise<T>;
+
 /**
  * PostgreSQL Error Conversion Utilities
  *
@@ -1007,14 +1429,6 @@ declare function fromPostgresError(error: any): DatabaseError;
  * ```
  */
 
-/**
- * Infer SELECT model from PgTable
- */
-type InferSelectModel<T extends PgTable> = T['$inferSelect'];
-/**
- * Infer INSERT model from PgTable
- */
-type InferInsertModel<T extends PgTable> = T['$inferInsert'];
 /**
  * Object-based where condition (AND only, equality only)
  */
@@ -1126,8 +1540,8 @@ declare function createMany<T extends PgTable>(table: T, data: InferInsertModel<
  * }, {
  *     target: [cmsPublishedCache.section, cmsPublishedCache.locale],
  *     set: {
- *         content: data.content,
- *         updatedAt: new Date()
+ *         content: data.content
+ *         // updatedAt is stamped by the database — do not name it here
  *     }
  * });
  *
@@ -1279,10 +1693,10 @@ declare function count<T extends PgTable>(table: T, where?: WhereObject<InferSel
  *
  * @example With Custom Schema Type
  * ```typescript
- * import type { AppSchema } from './schema';
+ * import type { AppRelations } from './relations';
  *
- * export class UserRepository extends BaseRepository<AppSchema> {
- *     // Now this.db and this.readDb are typed with AppSchema
+ * export class UserRepository extends BaseRepository<AppRelations> {
+ *     // Now this.db and this.readDb preserve the app's Drizzle relations
  * }
  * ```
  *
@@ -1302,6 +1716,8 @@ declare function count<T extends PgTable>(table: T, where?: WhereObject<InferSel
  * ```
  */
 
+/** Database surface available to repositories inside and outside transactions. */
+type RepositoryDatabase<TDatabase extends DrizzleDatabase> = TDatabase extends PgAsyncDatabase<infer TQueryResult, infer TRelations> ? PgAsyncDatabase<TQueryResult, TRelations> : never;
 /**
  * Enhanced error class that includes repository context
  */
@@ -1323,9 +1739,10 @@ declare class RepositoryError extends Error {
  * - Inside transaction: Uses transaction DB
  * - Outside transaction: Uses global DB instance (with read/write separation)
  *
- * @template TSchema - Database schema type (defaults to Record<string, unknown>)
+ * @template TRelations - Drizzle relations type (defaults to no relations)
+ * @template TDatabase - PostgreSQL Drizzle driver type (defaults to postgres.js)
  */
-declare abstract class BaseRepository<TSchema extends Record<string, unknown> = Record<string, unknown>> {
+declare abstract class BaseRepository<TRelations extends AnyRelations = EmptyRelations, TDatabase extends DrizzleDatabase = PostgresJsDatabase<TRelations>> {
     /**
      * Write database instance
      *
@@ -1342,7 +1759,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * }
      * ```
      */
-    protected get db(): PostgresJsDatabase<TSchema>;
+    protected get db(): RepositoryDatabase<TDatabase>;
     /**
      * Read database instance
      *
@@ -1363,7 +1780,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * }
      * ```
      */
-    protected get readDb(): PostgresJsDatabase<TSchema>;
+    protected get readDb(): RepositoryDatabase<TDatabase>;
     /**
      * Wrap query execution with repository context
      *
@@ -1409,7 +1826,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * const user = await this._findOne(users, eq(users.id, 1));
      * ```
      */
-    protected _findOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<T['$inferSelect'] | null>;
+    protected _findOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<InferSelectModel<T> | null>;
     /**
      * Find multiple records
      *
@@ -1431,7 +1848,33 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
         orderBy?: SQL | SQL[];
         limit?: number;
         offset?: number;
-    }): Promise<T['$inferSelect'][]>;
+    }): Promise<InferSelectModel<T>[]>;
+    /**
+     * Keyset (cursor) pagination — O(limit) instead of OFFSET's O(offset).
+     *
+     * Pages by a strictly-ordered, unique column instead of a numeric offset, so a
+     * deep page doesn't scan and discard everything before it. Pass the cursor
+     * column's value from the last row of the previous page as `after`; omit it for
+     * the first page. The column must be unique and the sole sort key (e.g. an
+     * auto-increment id or a ULID).
+     *
+     * @example
+     * ```typescript
+     * const page1 = await this._findManyKeyset(users, { cursorColumn: users.id, limit: 20 });
+     * const page2 = await this._findManyKeyset(users, {
+     *     cursorColumn: users.id,
+     *     after: page1.at(-1)?.id,
+     *     limit: 20,
+     * });
+     * ```
+     */
+    protected _findManyKeyset<T extends PgTable>(table: T, options: {
+        cursorColumn: PgColumn;
+        limit: number;
+        after?: string | number | bigint | Date;
+        order?: 'asc' | 'desc';
+        where?: Record<string, any> | SQL | undefined;
+    }): Promise<InferSelectModel<T>[]>;
     /**
      * Create a new record
      *
@@ -1447,7 +1890,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * });
      * ```
      */
-    protected _create<T extends PgTable>(table: T, data: T['$inferInsert']): Promise<T['$inferSelect']>;
+    protected _create<T extends PgTable>(table: T, data: InferInsertModel<T>): Promise<InferSelectModel<T>>;
     /**
      * Create multiple records
      *
@@ -1463,7 +1906,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * ]);
      * ```
      */
-    protected _createMany<T extends PgTable>(table: T, data: T['$inferInsert'][]): Promise<T['$inferSelect'][]>;
+    protected _createMany<T extends PgTable>(table: T, data: InferInsertModel<T>[]): Promise<InferSelectModel<T>[]>;
     /**
      * Upsert a record (INSERT or UPDATE on conflict)
      *
@@ -1479,14 +1922,14 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      *     value: {...}
      * }, {
      *     target: [cache.key],
-     *     set: { value: data.value, updatedAt: new Date() }
+     *     set: { value: data.value } // updatedAt is stamped by the database
      * });
      * ```
      */
-    protected _upsert<T extends PgTable>(table: T, data: T['$inferInsert'], options: {
+    protected _upsert<T extends PgTable>(table: T, data: InferInsertModel<T>, options: {
         target: PgColumn[];
-        set?: Partial<T['$inferInsert']> | Record<string, SQL | any>;
-    }): Promise<T['$inferSelect']>;
+        set?: Partial<InferInsertModel<T>> | Record<string, SQL | any>;
+    }): Promise<InferSelectModel<T>>;
     /**
      * Update a single record
      *
@@ -1503,7 +1946,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * );
      * ```
      */
-    protected _updateOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined, data: Partial<T['$inferInsert']>): Promise<T['$inferSelect'] | null>;
+    protected _updateOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined, data: Partial<InferInsertModel<T>>): Promise<InferSelectModel<T> | null>;
     /**
      * Update multiple records
      *
@@ -1520,7 +1963,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * );
      * ```
      */
-    protected _updateMany<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined, data: Partial<T['$inferInsert']>): Promise<T['$inferSelect'][]>;
+    protected _updateMany<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined, data: Partial<InferInsertModel<T>>): Promise<InferSelectModel<T>[]>;
     /**
      * Delete a single record
      *
@@ -1533,7 +1976,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * const user = await this._deleteOne(users, { id: 1 });
      * ```
      */
-    protected _deleteOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<T['$inferSelect'] | null>;
+    protected _deleteOne<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<InferSelectModel<T> | null>;
     /**
      * Delete multiple records
      *
@@ -1546,7 +1989,7 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
      * const users = await this._deleteMany(users, { verified: false });
      * ```
      */
-    protected _deleteMany<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<T['$inferSelect'][]>;
+    protected _deleteMany<T extends PgTable>(table: T, where: Record<string, any> | SQL | undefined): Promise<InferSelectModel<T>[]>;
     /**
      * Count records
      *
@@ -1563,4 +2006,4 @@ declare abstract class BaseRepository<TSchema extends Record<string, unknown> =
     protected _count<T extends PgTable>(table: T, where?: Record<string, any> | SQL | undefined): Promise<number>;
 }
 
-export { BaseRepository, type DatabaseClients, type DrizzleConfigOptions, type PoolConfig, RepositoryError, type RetryConfig, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, auditFields, checkConnection, closeDatabase, count, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, enumText, findMany, findOne, foreignKey, fromPostgresError, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, id, initDatabase, optionalForeignKey, packageNameToSchema, publishingFields, runWithTransaction, setDatabase, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };
+export { type AfterCommitCallback, BaseRepository, type DatabaseClients, type DatabaseInitOptions, type DatabaseOptions, type DatabaseProvider, type DatabaseTransaction, type DefaultDatabase, type DrizzleConfigOptions, type DrizzleDatabase, type FunctionMigrationEntry, type FunctionMigrationInfo, type MigrationStatus, type MigrationStatusDb, type MigrationTargetStatus, PROJECT_MIGRATIONS_TABLE, PROJECT_TARGET_NAME, type PoolConfig, RUN_MIGRATIONS_HINT, type RepositoryDatabase, RepositoryError, type RetryConfig, type RunInTransactionOptions, type TransactionContext, type TransactionDB, Transactional, type TransactionalOptions, auditFields, checkConnection, closeDatabase, collectMigrationStatus, count, countPendingMigrations, create, createDatabaseConnection, createDatabaseFromEnv, createMany, createSchema, deleteMany, deleteOne, detectDialect, discoverFunctionMigrations, enumText, filterPendingEntries, findMany, findOne, forceReconnectDatabase, foreignKey, formatPendingMigrations, fromPostgresError, functionMigrationsTable, generateDrizzleConfigFile, getDatabase, getDatabaseInfo, getDrizzleConfig, getSchemaInfo, getTransaction, getTransactionContext, hasMigrationTargets, id, initDatabase, isConnectionLevelError, migrationTargets, onAfterCommit, optionalForeignKey, packageNameToSchema, pendingMigrationTargets, pendingMigrationsSummary, projectMigrationsDir, publishingFields, readMigrationEntries, reportDatabaseError, resetConnectionErrorCounter, runInTransaction, runWithTransaction, setDatabase, setDatabaseProvider, softDelete, timestamps, typedJsonb, updateMany, updateOne, upsert, utcTimestamp, uuid, verificationTimestamp };