@makaio/framework 1.0.0-dev-1781117225170 → 1.0.0-dev-1781260968078

package/dist/storage/drizzle/index.d.mts

@@ -1,9 +1,668 @@
-import { t as MakaioDatabase } from "../../types-yTKQTAok.mjs";
+import { a as DATABASE_DIALECT, c as getDatabaseDialect, n as DatabaseClientConfig, o as MakaioDatabase, s as StorageDialect, t as DatabaseClient } from "../../client-BJVDImPV.mjs";
 import { IMakaioBus } from "@makaio/framework/bus";
 import { ExtensionContext } from "@makaio/framework/contracts";
-import { Table } from "drizzle-orm";
+import * as _$drizzle_orm_sqlite_core0 from "drizzle-orm/sqlite-core";
+import { SQLiteColumn, SQLiteColumnBuilderBase, SQLiteTable, SQLiteTableExtraConfigValue, SQLiteTableWithColumns } from "drizzle-orm/sqlite-core";
+import * as _$drizzle_orm_pg_core0 from "drizzle-orm/pg-core";
+import { PgColumn, PgColumnBuilderBase, PgTable, PgTableExtraConfigValue, PgTableWithColumns } from "drizzle-orm/pg-core";
+import * as _$drizzle_orm0 from "drizzle-orm";
+import { $Type, BuildColumns, BuildExtraConfigColumns, ColumnBuilderBase, SQL, Table } from "drizzle-orm";
 import { StorageNamespace, StorageNamespaceConfig, StorageNamespaceExtensions, createStorageNamespace } from "@makaio/framework/storage";
 
+//#region storage/drizzle/src/raw-sql.d.ts
+/**
+ * Statement surface available both standalone and inside a pinned session.
+ */
+interface RawSqlSession {
+  /**
+   * Execute one statement. Affected-row count where the driver reports one
+   * (drivers that report nothing yield `rowsAffected: 0`).
+   * @param query - SQL statement to execute.
+   * @returns Normalized write result.
+   */
+  run(query: SQL): Promise<{
+    rowsAffected: number;
+  }>;
+  /**
+   * Execute a query and return rows as column-name-keyed objects.
+   * @param query - SQL query to execute.
+   * @returns All result rows.
+   * @typeParam TRow - Expected row shape keyed by column name.
+   */
+  all<TRow extends Record<string, unknown>>(query: SQL): Promise<TRow[]>;
+}
+/**
+ * Dialect-portable raw SQL executor, attached to every handle by
+ * `createDatabaseClient`. The ONLY sanctioned path for raw statements.
+ *
+ * INVARIANT: raw transaction control (BEGIN/COMMIT/ROLLBACK) may only ever be
+ * issued inside {@link RawSqlExecutor.withSession}. On Postgres, standalone
+ * `run` goes through the pool — raw BEGIN there would stripe statements
+ * across connections.
+ */
+interface RawSqlExecutor extends RawSqlSession {
+  /** Storage dialect this executor speaks. Matches the handle's brand. */
+  readonly dialect: StorageDialect;
+  /**
+   * Run `fn` with every statement pinned to one connection. Postgres: a
+   * checked-out `pool.connect()` client that is always released — returned to
+   * the pool on success, destroyed via `release(true)` when the callback
+   * rejects so a poisoned connection (open or aborted transaction) never
+   * re-enters the pool. SQLite: the single connection (trivial).
+   * @param fn - Work to execute against the pinned session.
+   * @returns The value resolved by `fn`.
+   * @typeParam T - Result type produced by the session callback.
+   */
+  withSession<T>(fn: (session: RawSqlSession) => Promise<T>): Promise<T>;
+}
+/**
+ * Attach the storage-dialect brand and the raw SQL executor to a drizzle
+ * database instance.
+ *
+ * Both properties are non-enumerable so they never leak through spreads or
+ * property enumeration, and non-writable/non-configurable so a handle's
+ * dialect and executor cannot change after creation (re-branding throws).
+ * Every branded handle carries an executor — `getRawSqlExecutor` relies on
+ * this invariant, so the executor's dialect must match the brand.
+ * @param db - Drizzle database instance to brand.
+ * @param dialect - Storage dialect served by the instance.
+ * @param executor - Raw SQL executor for the instance's connection(s).
+ * @returns The same instance, branded.
+ */
+declare function brandDatabase<TDb extends object>(db: TDb, dialect: StorageDialect, executor: RawSqlExecutor): TDb;
+/**
+ * Resolve the raw SQL executor for a database handle.
+ *
+ * Factory-created handles return the executor attached by
+ * `createDatabaseClient`. Unbranded handles that expose the native SQLite
+ * `run`/`all` API (hand-rolled test clients built directly on
+ * `drizzle-orm/libsql` or `drizzle-orm/bun-sqlite`) get a synthesized SQLite
+ * executor — mirroring the unbranded→`'sqlite'` dialect default.
+ * @param db - Database handle to resolve the executor for.
+ * @returns The handle's raw SQL executor.
+ * @throws Error when the handle carries no executor and exposes no native
+ *   SQLite raw API — create handles with `createDatabaseClient` instead.
+ */
+declare function getRawSqlExecutor(db: MakaioDatabase): RawSqlExecutor;
+//#endregion
+//#region storage/drizzle/src/import-runtime-module.d.ts
+/**
+ * Bundler-opaque dynamic module loading.
+ *
+ * Leaf module with no package-internal imports so any layer (client factory,
+ * engine implementations, runtime hosts) can load optional or runtime-gated
+ * modules without creating import cycles.
+ * @packageDocumentation
+ */
+/**
+ * Imports a module whose specifier must stay opaque to bundlers.
+ *
+ * `bun:sqlite` and `drizzle-orm/bun-sqlite` are optional or runtime-gated
+ * modules that may only be resolved when their branch is actually reached at
+ * runtime. A literal `import('pg')` — or a `const id = 'pg'; import(id)`
+ * indirection, which minifiers constant-fold back into the literal form — lets
+ * bundlers (Vite, esbuild, rolldown) resolve the specifier at bundle time and
+ * fail or inline it. Routing the specifier through a function parameter keeps
+ * the emitted call a fully dynamic `import(specifier)` that bundlers treat as
+ * runtime-only, in source and in minified distribution output alike.
+ *
+ * Resolution caveat: the `import()` resolves relative to this module, so this
+ * helper is only for modules that belong to this package's dependency closure.
+ * Host-installed optional packages must be resolved from a host-provided base
+ * before importing the resulting file URL.
+ * @param specifier - Bare module specifier to import at runtime.
+ * @typeParam TModule - Structural surface of the module the caller consumes.
+ * @returns Promise of the loaded module, typed by the caller.
+ */
+declare function importRuntimeModule<TModule>(specifier: string): Promise<TModule>;
+//#endregion
+//#region storage/drizzle/src/fts/strategy.d.ts
+/**
+ * Input for message-level full-text search operations.
+ */
+interface FtsMessageSearchInput {
+  /**
+   * Raw search query as received from the caller. The strategy owns
+   * sanitization/trimming; callers must short-circuit empty/whitespace
+   * queries before calling the strategy.
+   */
+  readonly query: string;
+  /** Optional session scope; omitted searches across all sessions. */
+  readonly sessionId?: string | undefined;
+  /** Maximum number of rows to return (callers apply their own defaults). */
+  readonly limit: number;
+}
+/**
+ * One ranked excerpt hit returned by {@link FtsSearchStrategy.searchMessageExcerpts}.
+ */
+interface FtsMessageExcerptHit {
+  /** Message identifier of the hit. */
+  readonly messageId: string;
+  /** Session the message belongs to. */
+  readonly sessionId: string;
+  /**
+   * Positive relevance score. Magnitudes are dialect-specific (negated bm25
+   * on SQLite, ts_rank on Postgres) — only relative ordering within one
+   * result set is meaningful.
+   */
+  readonly score: number;
+  /** Highlighted excerpt with `<mark>…</mark>` around matched terms. */
+  readonly excerpt: string;
+}
+/**
+ * Input for session-level full-text search.
+ */
+interface FtsSessionSearchInput {
+  /**
+   * Normalized (trimmed) search query text matched against message content.
+   * Callers trim once because the LIKE pattern is derived from the same text.
+   */
+  readonly query: string;
+  /** Lowercased `%query%` pattern for the title LIKE match. */
+  readonly likePattern: string;
+  /** Maximum number of session rows to return. */
+  readonly limit: number;
+  /** Optional status filter; `undefined` means "any status". */
+  readonly status?: string | undefined;
+  /** Optional import-flag filter; `undefined` means "any". */
+  readonly isImported?: boolean | undefined;
+}
+/**
+ * Input for counting session-level matches — the search input minus the page
+ * window (totals are independent of pagination).
+ */
+type FtsSessionCountInput = Omit<FtsSessionSearchInput, 'limit'>;
+/**
+ * Dialect-owned full-text-search operations.
+ *
+ * The `messagesTable` parameters are typed as the canonical SQLite face; under
+ * Postgres the runtime object is the congruent twin resolved per handle (the
+ * same honesty model as `resolveSchema`). Strategies that build raw SQL
+ * against fixed physical names accept and ignore the parameter.
+ */
+interface FtsSearchStrategy {
+  /** Storage dialect this strategy serves. */
+  readonly dialect: StorageDialect;
+  /**
+   * Provision the engine's search index over the `messages` table.
+   *
+   * Called after central migrations on every boot; implementations must be
+   * idempotent. Engines whose index ships through the regular migration chain
+   * implement this as a no-op.
+   * @param db - Database handle with the central schema already applied.
+   */
+  provisionSearchIndex(db: MakaioDatabase): Promise<void>;
+  /**
+   * Search full message rows ranked by relevance.
+   * @param db - Database handle to query.
+   * @param messagesTable - Resolved messages table of the handle's dialect.
+   * @param input - Query text, optional session scope, and page limit.
+   * @returns Ranked message rows plus the page-independent total match count.
+   * @typeParam TRow - Row shape produced by the messages table (callers pass
+   *   their select-row type; the strategy returns rows column-compatible with
+   *   the messages table).
+   */
+  searchMessages<TRow extends Record<string, unknown>>(db: MakaioDatabase, messagesTable: SQLiteTable, input: FtsMessageSearchInput): Promise<{
+    rows: TRow[];
+    total: number;
+  }>;
+  /**
+   * Search messages and return scored `<mark>`-highlighted excerpts instead
+   * of full rows.
+   * @param db - Database handle to query.
+   * @param messagesTable - Resolved messages table of the handle's dialect.
+   * @param input - Query text, optional session scope, and page limit.
+   * @returns Ranked excerpt hits plus the page-independent total match count.
+   */
+  searchMessageExcerpts(db: MakaioDatabase, messagesTable: SQLiteTable, input: FtsMessageSearchInput): Promise<{
+    results: FtsMessageExcerptHit[];
+    total: number;
+  }>;
+  /**
+   * Search sessions whose message content matches the query or whose title
+   * matches the LIKE pattern, newest activity first.
+   * @param db - Database handle to query.
+   * @param input - Query text, title pattern, page limit, and optional filters.
+   * @returns Matching session rows (snake_case physical column keys).
+   * @typeParam TRow - Session row shape expected by the caller.
+   */
+  searchSessionRows<TRow extends Record<string, unknown>>(db: MakaioDatabase, input: FtsSessionSearchInput): Promise<TRow[]>;
+  /**
+   * Count all sessions matching the query/pattern and filters, without
+   * pagination.
+   * @param db - Database handle to query.
+   * @param input - Query text, title pattern, and optional filters.
+   * @returns Total number of unique matching sessions.
+   */
+  countSessionMatches(db: MakaioDatabase, input: FtsSessionCountInput): Promise<number>;
+  /**
+   * Resolve the first user message per session as a preview, tie-breaking
+   * same-timestamp messages with the engine's deterministic ordering
+   * surrogate (rowid on SQLite, message_id on Postgres).
+   * @param db - Database handle to query.
+   * @param sessionIds - Session IDs to resolve previews for; an empty list
+   *   resolves to an empty map without touching the database.
+   * @returns First user message text keyed by session ID.
+   */
+  fetchFirstUserMessagePreviews(db: MakaioDatabase, sessionIds: readonly string[]): Promise<Map<string, string | null>>;
+}
+//#endregion
+//#region storage/drizzle/src/engine/types.d.ts
+/**
+ * Dialect-specific classification of database errors.
+ *
+ * Raw DDL flows (migration adoption, idempotent CREATE) and bounded-retry
+ * write paths need to recognize driver failures portably. Each engine owns
+ * the knowledge of how its drivers report these conditions.
+ */
+interface StorageEngineErrorClassifiers {
+  /**
+   * Returns `true` when the error (or any link in its cause chain) reports
+   * that a schema object (table, index, trigger, …) already exists.
+   *
+   * Used by the migration applicator to decide whether a failed first CREATE
+   * can be adopted into the ledger.
+   * @param error - Error thrown by a DDL statement.
+   * @returns Whether the failure is a duplicate-schema-object conflict.
+   */
+  isDuplicateObjectError(error: unknown): boolean;
+  /**
+   * Returns `true` when the error (or any link in its cause chain) reports a
+   * unique-constraint violation.
+   *
+   * Used by write paths that resolve write-write races through a bounded
+   * retry (for example MAX-based counter assignment). The optional
+   * `constraint` scope lets callers react to one specific index without
+   * swallowing unrelated violations; engines whose drivers do not report
+   * constraint names ignore the scope.
+   * @param error - Error thrown by a DML statement.
+   * @param constraint - Optional constraint/index name to scope the match.
+   * @returns Whether the failure is a unique-constraint violation.
+   */
+  isUniqueViolationError(error: unknown, constraint?: string): boolean;
+}
+/**
+ * Runtime capabilities a consumer can query instead of branching on the
+ * dialect identifier.
+ */
+interface StorageEngineCapabilities {
+  /**
+   * SQL column type used for binary payloads in hand-written DDL
+   * (for example `'BLOB'` on SQLite, `'bytea'` on Postgres).
+   */
+  readonly binaryColumnType: string;
+  /**
+   * Whether concurrent MAX-based counter assignment can race under this
+   * engine's default isolation level and therefore needs a bounded
+   * unique-violation retry. `false` for engines whose writes serialize at the
+   * connection level.
+   */
+  readonly maxCounterAssignmentRaces: boolean;
+  /**
+   * Probe the engine's catalog for a table's existence.
+   * @param executor - Raw SQL executor of the target database handle.
+   * @param tableName - Unqualified table name to probe.
+   * @returns `true` when the table exists.
+   */
+  tableExists(executor: RawSqlExecutor, tableName: string): Promise<boolean>;
+}
+/**
+ * Migration behavior owned by an engine: ledger naming and DDL, journal
+ * dialect, chain directory layout, and transaction semantics.
+ *
+ * The statement texts and naming schemes exposed here are cross-version
+ * contracts — runners built from different framework versions must agree on
+ * them, otherwise concurrent runs stop serializing against each other or stop
+ * recognizing each other's ledgers.
+ */
+interface StorageEngineMigrationBehavior {
+  /** Default migration ledger table name for this engine. */
+  readonly defaultLedgerTable: string;
+  /**
+   * `dialect` value expected in a migration chain's `_journal.json` for this
+   * engine (drizzle-kit vocabulary, e.g. `'sqlite'` or `'postgresql'`).
+   */
+  readonly journalDialect: string;
+  /**
+   * Name of the directory holding this engine's bundled migration chain
+   * inside a package's distribution artifacts.
+   */
+  readonly chainDirName: string;
+  /**
+   * Resolve the absolute source directory of this engine's migration chain.
+   *
+   * Optional extension point for engines whose chain ships outside the
+   * default location implied by {@link chainDirName}; engines that omit it
+   * use the caller's default chain discovery.
+   * @returns Absolute path to the chain directory.
+   */
+  resolveSourceChainDir?(): string;
+  /**
+   * Build the idempotent `CREATE TABLE IF NOT EXISTS` DDL for the migration
+   * ledger table. The exact statement text is a cross-version contract pinned
+   * by tests.
+   * @param tableName - Ledger table name (engine default or caller-provided).
+   * @returns Complete DDL statement text.
+   */
+  buildLedgerDdl(tableName: string): string;
+  /**
+   * `BEGIN` statement that opens a migration transaction, including any
+   * isolation-level pinning the engine's ledger recheck protocol requires.
+   */
+  readonly beginTransactionStatement: string;
+  /**
+   * Acquire the engine's cross-process migration lock inside an open
+   * transaction.
+   *
+   * Optional: engines whose writes already serialize at the connection level
+   * omit it. Presence of this member is the single seam the applicator
+   * derives all cross-process locking behavior from (locked ledger snapshot
+   * plus in-lock recheck) — there is no separate flag that could disagree.
+   * @param session - Pinned raw SQL session with the transaction open.
+   * @param ledgerTableName - Ledger table name the lock key is derived from.
+   * @returns Resolves once the lock is held for the transaction's lifetime.
+   */
+  acquireTransactionLock?(session: RawSqlSession, ledgerTableName: string): Promise<void>;
+  /**
+   * Derive the per-extension migration ledger table name from an extension
+   * source hash. The naming scheme is a cross-version contract: ledgers
+   * written by one framework version must be found by the next.
+   * @param sourceHash - Stable hash identifying the extension's migration source.
+   * @returns Ledger table name for that extension.
+   */
+  extensionLedgerName(sourceHash: string): string;
+}
+/**
+ * Everything dialect-specific about a storage backend, packaged behind one
+ * contract.
+ *
+ * Engines are registered with the engine registry (explicitly via
+ * `registerStorageEngine` or through host boot options); the built-in SQLite
+ * engine is pre-registered and serves as the default engine for every URL no
+ * registered engine claims.
+ */
+interface StorageEngine {
+  /** Storage dialect this engine serves. */
+  readonly dialect: StorageDialect;
+  /**
+   * Returns `true` when a database URL selects this engine.
+   *
+   * Optional: the default engine (SQLite) omits it and serves every URL no
+   * registered engine claims.
+   * @param url - Database URL to test.
+   * @returns Whether the URL selects this engine.
+   */
+  matchesUrl?(url: string): boolean;
+  /**
+   * Create a database client for this engine.
+   * @param config - Database configuration options.
+   * @returns Database client with drizzle ORM instance and close method.
+   */
+  createClient(config: DatabaseClientConfig): Promise<DatabaseClient>;
+  /** Dialect-specific error classification. */
+  readonly errors: StorageEngineErrorClassifiers;
+  /** Runtime capabilities consumers query instead of branching on dialect. */
+  readonly capabilities: StorageEngineCapabilities;
+  /** Migration ledger, journal, and transaction behavior. */
+  readonly migrations: StorageEngineMigrationBehavior;
+  /**
+   * Full-text-search provisioning and query operations.
+   *
+   * Required: every built-in engine implements full-text search for real.
+   * Future engines without a search backend ship a refusing strategy rather
+   * than omitting the member, so the seam stays uniform for consumers.
+   */
+  readonly fts: FtsSearchStrategy;
+}
+/**
+ * Quote a SQL identifier (table, column, or index name) for safe inlining
+ * into hand-written statement text.
+ *
+ * Uses double-quote delimiters with embedded double quotes doubled — the
+ * standard SQL identifier escaping shared by SQLite and Postgres.
+ * @param name - Raw identifier to quote.
+ * @returns The quoted identifier, safe to interpolate into SQL text.
+ */
+declare function quoteSqlIdentifier(name: string): string;
+//#endregion
+//#region storage/drizzle/src/engine/registry.d.ts
+/**
+ * Register a storage engine for its dialect.
+ *
+ * Re-registering the same engine object is a no-op, so idempotent
+ * registration helpers and duplicated boot paths are safe. Registering a
+ * *different* engine object for an already-registered dialect throws: one
+ * dialect has exactly one engine per process, and silently replacing it would
+ * change behavior for every open handle.
+ * @param engine - Engine to register under its `dialect`.
+ * @throws Error when a different engine is already registered for the dialect.
+ */
+declare function registerStorageEngine(engine: StorageEngine): void;
+/**
+ * Resolve the engine registered for a dialect, throwing an actionable error
+ * when it is absent.
+ *
+ * For dialects with a known engine package (see the URL hint table) the error
+ * names the package to install; otherwise it points at
+ * {@link registerStorageEngine}.
+ * @param dialect - Storage dialect to resolve.
+ * @returns The registered engine.
+ * @throws Error when no engine is registered for the dialect.
+ */
+declare function getStorageEngine(dialect: StorageDialect): StorageEngine;
+/**
+ * Resolve the engine registered for a dialect, or `undefined` when absent.
+ * @param dialect - Storage dialect to look up.
+ * @returns The registered engine, or `undefined`.
+ */
+declare function findStorageEngine(dialect: StorageDialect): StorageEngine | undefined;
+/**
+ * Resolve the engine serving a database handle, via the handle's dialect
+ * brand (unbranded handles resolve to the SQLite default engine).
+ * @param db - Database handle to resolve the engine for.
+ * @returns The engine serving the handle's dialect.
+ * @throws Error when no engine is registered for the handle's dialect.
+ */
+declare function resolveStorageEngine(db: MakaioDatabase<Record<string, unknown>>): StorageEngine;
+/**
+ * Result of resolving a database URL against the engine registry.
+ *
+ * - `'engine'` — a registered engine serves the URL.
+ * - `'missing-engine'` — the URL is recognized (hint table) but the engine
+ *   package is not registered; `packageName` names the package to install or
+ *   auto-import.
+ * - `'default'` — no engine claims the URL; it belongs to the default
+ *   (SQLite) engine.
+ */
+type StorageEngineUrlResolution = {
+  kind: 'engine';
+  engine: StorageEngine;
+} | {
+  kind: 'missing-engine';
+  dialect: StorageDialect;
+  packageName: string;
+} | {
+  kind: 'default';
+};
+/**
+ * Resolve a database URL to the engine that serves it.
+ *
+ * Checks registered engines' `matchesUrl` claims in registration order, then
+ * the URL hint table, and falls back to `'default'`. A hint match is reported
+ * as `'missing-engine'` only when the hinted dialect truly has no registered
+ * engine — when one is registered (without claiming the URL itself), the
+ * registered engine wins so the result kind stays honest.
+ * @param url - Database URL to resolve.
+ * @returns The resolution: a serving engine, a missing-engine hint, or the default.
+ */
+declare function resolveStorageEngineForUrl(url: string): StorageEngineUrlResolution;
+//#endregion
+//#region storage/drizzle/src/engine/hints.d.ts
+/**
+ * Static mapping from a recognizable database URL shape to the package that
+ * provides the engine for it.
+ */
+interface StorageEngineUrlHint {
+  /** Dialect the hinted engine serves. */
+  readonly dialect: StorageDialect;
+  /** Package that exports the engine as `storageEngine`. */
+  readonly packageName: string;
+  /**
+   * Returns `true` when a database URL belongs to the hinted engine.
+   * @param url - Database URL to test.
+   * @returns Whether the URL is recognized by this hint.
+   */
+  matchesUrl(url: string): boolean;
+}
+/**
+ * All known URL hints, in match order.
+ *
+ * Postgres: both `postgres://` and `postgresql://` schemes are accepted,
+ * case-insensitively. The engine lives in `@makaio/storage-pg`.
+ */
+declare const STORAGE_ENGINE_URL_HINTS: readonly StorageEngineUrlHint[];
+/**
+ * Build the actionable error message for a dialect whose engine is not
+ * registered.
+ *
+ * Single source of truth for both failure surfaces: the client factory's
+ * missing-engine rejection and the runtime host's boot error.
+ * @param dialect - Dialect the caller tried to resolve.
+ * @param packageName - Package that provides the missing engine.
+ * @returns Human-readable, actionable error message.
+ */
+declare function describeMissingStorageEngine(dialect: StorageDialect, packageName: string): string;
+//#endregion
+//#region storage/drizzle/src/engine/generation.d.ts
+/**
+ * One non-baseline engine's drizzle-kit generation leg.
+ *
+ * The baseline dialect (SQLite) has no entry here: its chain is generated by
+ * the orchestrator directly. Every other dialect that can contribute a chain
+ * declares its leg through this descriptor so the orchestrator stays free of
+ * per-engine wiring.
+ */
+interface StorageEngineGenerationLeg {
+  /** Dialect this generation leg produces a migration chain for. */
+  readonly dialect: StorageDialect;
+  /** Package that provides the engine and its drizzle-kit generation assets. */
+  readonly enginePackageName: string;
+  /**
+   * Name of the directory holding this engine's generated migration chain,
+   * relative to the engine package root.
+   */
+  readonly chainDirName: string;
+  /**
+   * drizzle-kit config path for this engine, relative to the engine package
+   * root. The orchestrator resolves the package root, then joins this path to
+   * run `drizzle-kit generate --config <root>/<drizzleConfigSpecifier>`.
+   */
+  readonly drizzleConfigSpecifier: string;
+  /**
+   * Post-generation normalize script path for this engine, relative to the
+   * engine package root. Optional: engines whose generated chains need no
+   * normalization omit it.
+   */
+  readonly normalizeScriptSpecifier?: string;
+}
+/**
+ * All non-baseline generation legs, in run order.
+ *
+ * Postgres: the engine lives in `@makaio/storage-pg`, its chain lands in
+ * `drizzle-postgres`, drizzle-kit reads `drizzle.config.ts`, and the generated
+ * SQL is normalized by `scripts/normalize-migrations.ts` — all relative to the
+ * engine package root.
+ */
+declare const NON_BASELINE_GENERATION_LEGS: readonly StorageEngineGenerationLeg[];
+/**
+ * Find the generation leg for a dialect, if one exists.
+ * @param dialect - Storage dialect to look up.
+ * @returns The generation leg for the dialect, or `undefined` when the dialect
+ *   has no non-baseline generation leg (the baseline dialect always returns
+ *   `undefined`).
+ */
+declare function findGenerationLegForDialect(dialect: StorageDialect): StorageEngineGenerationLeg | undefined;
+//#endregion
+//#region storage/drizzle/src/engine/sqlite/engine.d.ts
+/**
+ * The built-in SQLite engine.
+ *
+ * This is the default engine: it deliberately omits {@link StorageEngine.matchesUrl}
+ * and serves every database URL no registered engine claims (local `file:`
+ * and `:memory:` databases as well as remote libSQL/Turso connections).
+ *
+ * Migration behavior keeps Drizzle's historical SQLite contracts byte-for-byte
+ * (`__drizzle_migrations` ledger name and DDL shape, bare `BEGIN`,
+ * `__drizzle_migrations_<hash>` extension ledgers) so existing ledgers keep
+ * matching across framework versions. No `acquireTransactionLock`: SQLite
+ * writes serialize at the connection level, so the migration applicator needs
+ * no cross-process lock protocol here.
+ */
+declare const sqliteStorageEngine: StorageEngine;
+//#endregion
+//#region storage/drizzle/src/errors.d.ts
+/**
+ * Engine-owned classification of database errors.
+ *
+ * Raw DDL flows (migration adoption, idempotent CREATE) and bounded-retry
+ * write paths need to recognize driver failures portably. Each storage engine
+ * owns the knowledge of how its drivers report these conditions; consumers go
+ * through `StorageEngine.errors` instead of branching on the dialect.
+ *
+ * This module hosts the SQLite classifiers backing the built-in engine, plus
+ * the cause-chain inspection helpers engine packages build their own
+ * classifiers from.
+ * @packageDocumentation
+ */
+/**
+ * Walk an error's cause chain until a link satisfies the predicate.
+ *
+ * Building block for engine error classifiers: drivers and call sites
+ * routinely wrap failures (`new Error(..., { cause })`), so classification
+ * must consider every `Error` link in the chain, not just the outermost one.
+ * @param error - Error (or arbitrary thrown value) to inspect.
+ * @param predicate - Test applied to every `Error` link in the chain.
+ * @returns `true` when any link in the cause chain satisfies the predicate.
+ */
+declare function someInCauseChain(error: unknown, predicate: (link: Error) => boolean): boolean;
+/**
+ * Read a string `code` property off an error, if present.
+ *
+ * Driver errors (node-postgres `DatabaseError`, libsql errors) carry their
+ * SQLSTATE / driver code as a non-standard `code` property. Building block
+ * for engine error classifiers that match on those codes.
+ * @param error - Error link to read from.
+ * @returns The string code, or `undefined` when absent or non-string.
+ */
+declare function readErrorCode(error: Error): string | undefined;
+/**
+ * Returns `true` when the error (or any link in its cause chain) reports
+ * that a schema object already exists on SQLite.
+ *
+ * Matches the `already exists` message text — SQLite reports duplicate schema
+ * objects only through the error message. Used by the migration applicator to
+ * decide whether a failed first CREATE can be adopted into the ledger.
+ * @param error - Error thrown by a DDL statement.
+ * @returns Whether the failure is a duplicate-schema-object conflict.
+ */
+declare function isSqliteDuplicateObjectError(error: unknown): boolean;
+/**
+ * Returns `true` when the error (or any link in its cause chain) reports a
+ * SQLite unique-constraint violation.
+ *
+ * Matches the `UNIQUE constraint failed` message text. SQLite errors carry
+ * the violated column list, not constraint names, so constraint scoping is a
+ * Postgres-only concept honored by the Postgres engine's classifier — the
+ * built-in engine ignores the optional scope when delegating here.
+ *
+ * Used by write paths that resolve write-write races through a bounded retry
+ * (for example MAX-based counter assignment on engines whose default
+ * isolation level lets two concurrent statements compute the same next value).
+ * @param error - Error thrown by a DML statement.
+ * @returns Whether the failure is a unique-constraint violation.
+ */
+declare function isSqliteUniqueViolationError(error: unknown): boolean;
+//#endregion
 //#region storage/drizzle/src/transaction.d.ts
 type LibSQLTransactionExecutor = MakaioDatabase['transaction'];
 /**
@@ -19,9 +678,18 @@ type TransactionCallback<T> = Parameters<LibSQLTransactionExecutor>[0] extends (
 /**
  * Execute a database transaction through a shared transaction seam.
  *
- * Transaction work is serialized per database instance. SQLite permits only
- * one active transaction on a connection; without this queue, concurrent bus
- * handlers can fail at `BEGIN` with SQLITE_BUSY before busy_timeout can help.
+ * **Serialization contract:** transaction callbacks are serialized per
+ * database handle within this process, on every dialect. SQLite needs the
+ * queue for single-writer safety — it permits only one active transaction
+ * per connection, and without the queue concurrent bus handlers fail at
+ * `BEGIN` with SQLITE_BUSY before busy_timeout can help. Postgres needs the
+ * queue so read-modify-write callbacks observe each other's commits: MVCC
+ * runs concurrent transactions against isolated snapshots, so two unqueued
+ * "read current state, then write" callbacks (e.g. clear the old default
+ * row, then mark the new one) can both act on the same stale read. The
+ * guarantee is process-local — multi-process Postgres deployments need
+ * database-level coordination (advisory locks or unique-constraint retries)
+ * at the caller seam.
  *
  * **Driver compatibility:** `MakaioDatabase` is typed as `LibSQLDatabase`
  * (Node.js async dialect), which runs the transaction asynchronously and
@@ -35,7 +703,7 @@ type TransactionCallback<T> = Parameters<LibSQLTransactionExecutor>[0] extends (
  */
 declare function executeTransaction<T>(db: MakaioDatabase, callback: TransactionCallback<T>): Promise<T>;
 //#endregion
-//#region storage/drizzle/src/fts.d.ts
+//#region storage/drizzle/src/fts/sanitize.d.ts
 /**
  * FTS5 query utilities for SQLite full-text search.
  */
@@ -56,44 +724,73 @@ declare function executeTransaction<T>(db: MakaioDatabase, callback: Transaction
  */
 declare function sanitizeFtsQuery(query: string): string;
 //#endregion
+//#region storage/drizzle/src/fts/preview-query.d.ts
+/**
+ * Build the query resolving the first user message per session.
+ *
+ * Selects, for every given session, the user message no other user message of
+ * the same session precedes — "precedes" meaning an earlier timestamp, or an
+ * equal timestamp with the engine's tie-break predicate. Callers must not
+ * pass an empty `sessionIds` list (an empty `IN ()` list is invalid SQL);
+ * strategies short-circuit empty inputs before building the query.
+ * @param sessionIds - Session IDs to resolve previews for (deduplicated here).
+ * @param tieBreaker - Predicate over aliases `m2`/`m` that is `true` when
+ *   `m2` precedes `m` among same-timestamp user messages.
+ * @returns Query yielding `sessionId` / `preview` rows.
+ */
+declare function buildFirstUserMessagePreviewQuery(sessionIds: readonly string[], tieBreaker: SQL): SQL;
+//#endregion
+//#region storage/drizzle/src/engine/sqlite/fts-strategy.d.ts
+/**
+ * The built-in SQLite FTS strategy: FTS5 provisioning, bm25-ranked message
+ * search, `snippet()` excerpts, and session search over `messages_fts`.
+ */
+declare const sqliteFtsSearchStrategy: FtsSearchStrategy;
+//#endregion
 //#region storage/drizzle/src/result.d.ts
 /**
  * Cross-driver result helpers for Drizzle write operations.
  *
- * The libsql dialect returns `{ rowsAffected: number }` while the bun-sqlite
- * dialect returns `{ changes: number }`. Consumers must not depend on either
- * field directly — use {@link didAffectRows} to normalise across drivers.
+ * The libsql dialect returns `{ rowsAffected: number }`, the bun-sqlite
+ * dialect returns `{ changes: number }`, and the node-postgres dialect returns
+ * `{ rowCount: number }`. Consumers must not depend on any of these fields
+ * directly — use {@link didAffectRows} to normalise across drivers.
  * @packageDocumentation
  */
 /**
  * Shape emitted by Drizzle write operations across all supported drivers.
  *
- * The libsql (Node.js) driver populates `rowsAffected`; the bun-sqlite driver
- * populates `changes`. Both may be present when a future driver version unifies
- * the surface; either being absent is normal.
+ * The libsql (Node.js) driver populates `rowsAffected`, the bun-sqlite driver
+ * populates `changes`, and the node-postgres driver populates `rowCount`.
+ * Several may be present when a future driver version unifies the surface;
+ * any being absent is normal.
  */
 interface DrizzleWriteResult {
+  /** Affected-row count reported by the libsql driver. */
   readonly rowsAffected?: number | null;
+  /** Affected-row count reported by the bun-sqlite driver. */
   readonly changes?: number | null;
+  /** Affected-row count reported by the node-postgres driver. */
+  readonly rowCount?: number | null;
 }
 /**
- * Determine whether a Drizzle write operation mutated at least one row.
+ * Extract the affected row count from a Drizzle write result.
  *
- * Normalises the driver-specific result shape so callers do not need to know
- * which SQLite dialect is active at runtime.
+ * Returns the driver-appropriate count regardless of which supported driver
+ * is active at runtime.
  * @param result - Write result from a Drizzle `insert`, `update`, or `delete`.
- * @returns `true` when one or more rows were affected.
+ * @returns Number of affected rows, defaulting to `0` when no field is set.
  */
-declare function didAffectRows(result: DrizzleWriteResult): boolean;
+declare function affectedRowCount(result: DrizzleWriteResult): number;
 /**
- * Extract the affected row count from a Drizzle write result.
+ * Determine whether a Drizzle write operation mutated at least one row.
  *
- * Returns the driver-appropriate count regardless of whether the libsql or
- * bun-sqlite dialect is active.
+ * Normalises the driver-specific result shape so callers do not need to know
+ * which dialect is active at runtime.
  * @param result - Write result from a Drizzle `insert`, `update`, or `delete`.
- * @returns Number of affected rows, defaulting to `0` when neither field is set.
+ * @returns `true` when one or more rows were affected.
  */
-declare function affectedRowCount(result: DrizzleWriteResult): number;
+declare function didAffectRows(result: DrizzleWriteResult): boolean;
 //#endregion
 //#region storage/drizzle/src/register-handlers.d.ts
 /**
@@ -118,6 +815,262 @@ type DrizzleHandlerRegistration<TSchema extends Record<string, unknown> = Record
  */
 declare function registerDrizzleHandlers<TSchema extends Record<string, unknown> = Record<string, never>>(registration: DrizzleHandlerRegistration<TSchema>): (bus: IMakaioBus, db: unknown, ctx: ExtensionContext) => (() => void) | void;
 //#endregion
+//#region storage/drizzle/src/dialect.d.ts
+/**
+ * Bidirectional type equality — resolves to `true` only when `A` and `B` are
+ * mutually identical (not merely mutually assignable in one direction).
+ */
+type Equal<A, B> = (<T>() => T extends A ? 1 : 2) extends (<T>() => T extends B ? 1 : 2) ? true : false;
+/**
+ * The single Postgres-only generated column key that is exempt from the
+ * select-row equality check in {@link PostgresTwinSchema}.
+ *
+ * Only this named key is exempt; any other extra, missing, or mistyped
+ * Postgres column still fails compilation. The structural parity test
+ * (`schema-parity.test.ts`) polices the exempted key per-table via
+ * `PG_ONLY_COLUMNS`.
+ */
+type PostgresOnlyGeneratedColumnKey = 'contentTsv';
+/**
+ * Validation type for a Postgres twin record: for every SQLite table key, the
+ * twin's `$inferSelect` row — with the Postgres-only generated column omitted
+ * via {@link PostgresOnlyGeneratedColumnKey} — must be identical to the
+ * canonical table's. On drift the expected property type collapses to an
+ * error-literal object that names the offending table key in the compile error.
+ */
+type PostgresTwinSchema<TSqlite extends Record<string, SQLiteTable>, TPostgres extends Record<keyof TSqlite, PgTable>> = { readonly [K in keyof TSqlite]: Equal<TSqlite[K]['$inferSelect'], Omit<TPostgres[K]['$inferSelect'], PostgresOnlyGeneratedColumnKey>> extends true ? TPostgres[K] : {
+  readonly 'postgres twin has select-row drift for table': K;
+} };
+/**
+ * A schema declared for both storage dialects — a per-dialect table registry
+ * whose keys ARE the closed `StorageDialect` union, so {@link resolveSchema}
+ * resolves by plain key lookup. `postgres` is intentionally typed as
+ * `TSqlite`: at runtime it holds real `pgTable` twins, presented through the
+ * canonical SQLite-typed face (the same documented honesty model as the
+ * driver cast in `client.ts`). Congruence is compiler-enforced by
+ * {@link PostgresTwinSchema} at construction and by the structural parity test.
+ */
+interface DialectSchema<TSqlite extends Record<string, SQLiteTable>> {
+  readonly sqlite: TSqlite;
+  readonly postgres: TSqlite;
+}
+/**
+ * Build a {@link DialectSchema} from a canonical SQLite table record and its
+ * congruent Postgres twins. Compile-time net: a missing twin, a non-PgTable
+ * value, or any select-row drift (outside the named
+ * {@link PostgresOnlyGeneratedColumnKey} exemption) fails compilation naming
+ * the table key. `$inferInsert` is deliberately NOT pinned (identity columns
+ * are absent from PG insert models while optional on SQLite autoincrement).
+ * @param sqlite - Canonical SQLite table objects, keyed by export name.
+ * @param postgres - Postgres twin table objects under the same keys.
+ * @returns The dialect schema consumed by {@link resolveSchema}.
+ */
+declare function defineDialectSchema<TSqlite extends Record<string, SQLiteTable>, TPostgres extends Record<keyof TSqlite, PgTable>>(sqlite: TSqlite, postgres: TPostgres & PostgresTwinSchema<TSqlite, TPostgres>): DialectSchema<TSqlite>;
+/**
+ * Resolve the dialect-correct table objects for a database handle.
+ *
+ * {@link DialectSchema} is a per-dialect table registry keyed by
+ * `StorageDialect` — its keys ARE the closed dialect union — so resolution is
+ * a branch-free registry lookup by the handle's dialect brand. Returns the
+ * SQLite-typed view in both cases; under Postgres the runtime objects are the
+ * congruent twins, so drizzle compiles correct SQL and value mappings.
+ * @param db - Database handle (brand read via `getDatabaseDialect`; unbranded
+ *   handles resolve to SQLite). The brand is schema-independent, so handles of
+ *   any schema generic are accepted (plain `MakaioDatabase` is assignable to
+ *   this parameter type).
+ * @param schema - Dialect schema built by {@link defineDialectSchema}.
+ * @returns The table record for the handle's active dialect.
+ */
+declare function resolveSchema<TSqlite extends Record<string, SQLiteTable>>(db: MakaioDatabase<Record<string, unknown>>, schema: DialectSchema<TSqlite>): TSqlite;
+//#endregion
+//#region storage/drizzle/src/dual-table.d.ts
+type NotNullOf<B, TBase> = B extends {
+  notNull(): infer R extends TBase;
+} ? R : never;
+type DefaultOf<B, TBase> = B extends {
+  default(value: never): infer R extends TBase;
+} ? R : never;
+type PrimaryKeyOf<B, TBase> = B extends {
+  primaryKey(): infer R extends TBase;
+} ? R : never;
+type UniqueOf<B, TBase> = B extends {
+  unique(name?: string): infer R extends TBase;
+} ? R : never;
+/** Data type accepted by `.default()` — honours `$type` pinning like drizzle does. */
+type DataOf<B extends ColumnBuilderBase> = B['_'] extends {
+  $type: infer U;
+} ? U : B['_']['data'];
+/**
+ * Foreign-key actions — shared shape across both dialects (drizzle's
+ * `ReferenceConfig['actions']` is identical for sqlite-core and pg-core).
+ */
+interface DualReferenceActions {
+  readonly onUpdate?: 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+  readonly onDelete?: 'cascade' | 'restrict' | 'no action' | 'set null' | 'set default';
+}
+/**
+ * A built foreign-key target as a pair of both dialects' columns. Returned by
+ * {@link DualTable.columnPair} and consumed by {@link DualColumnRef}.
+ */
+interface DualColumnPair {
+  readonly sqlite: SQLiteColumn;
+  readonly postgres: PgColumn;
+}
+/**
+ * A dual reference target: a lazy thunk returning BOTH dialects' built
+ * columns. For a cross-table FK this is `() => other.columnPair('col')`; for a
+ * self-FK it is `() => self.columnPair('col')` resolved against the table this
+ * very builder is part of. `references()` forwards `.sqlite` to the SQLite
+ * builder and `.postgres` to the Postgres builder, so each dialect receives the
+ * dialect-correct column with NO per-dialect annotation at the call site — the
+ * per-dialect column annotation a hand-written twin needs is absorbed once,
+ * here.
+ */
+type DualColumnRef = () => DualColumnPair;
+/**
+ * Structural base used as the generic constraint in `defineDualTable` —
+ * deliberately WITHOUT the chain methods so concrete `DualBuilder`
+ * instantiations stay assignable to it.
+ */
+interface DualColumnBuilderBase<S extends SQLiteColumnBuilderBase = SQLiteColumnBuilderBase, P extends PgColumnBuilderBase = PgColumnBuilderBase> {
+  readonly sqlite: S;
+  readonly postgres: P;
+}
+/** Chainable pair of one SQLite builder and one Postgres builder. */
+interface DualBuilder<S extends SQLiteColumnBuilderBase, P extends PgColumnBuilderBase> extends DualColumnBuilderBase<S, P> {
+  notNull(): DualBuilder<NotNullOf<S, SQLiteColumnBuilderBase>, NotNullOf<P, PgColumnBuilderBase>>;
+  default(value: (DataOf<S> & DataOf<P>) | SQL): DualBuilder<DefaultOf<S, SQLiteColumnBuilderBase>, DefaultOf<P, PgColumnBuilderBase>>;
+  primaryKey(): DualBuilder<PrimaryKeyOf<S, SQLiteColumnBuilderBase>, PrimaryKeyOf<P, PgColumnBuilderBase>>;
+  unique(name?: string): DualBuilder<UniqueOf<S, SQLiteColumnBuilderBase>, UniqueOf<P, PgColumnBuilderBase>>;
+  $type<T>(): DualBuilder<$Type<S, T>, $Type<P, T>>;
+  /**
+   * Declare a foreign key for BOTH dialects from one call.
+   * `references()` returns `this` on both drizzle builders, so the dual type is
+   * unchanged — chaining stays exact.
+   * @param ref - Lazy dual column-pair thunk (cross-table or self-FK).
+   * @param actions - Optional `onDelete` / `onUpdate` (shared shape).
+   */
+  references(ref: DualColumnRef, actions?: DualReferenceActions): DualBuilder<S, P>;
+}
+declare const dualColumns: {
+  /**
+   * Plain text column — `text` on both dialects (drizzle core per dialect).
+   * @param name - SQL column name.
+   * @returns Dual builder for a `text` column.
+   */
+  text: <TName extends string>(name: TName) => DualBuilder<_$drizzle_orm_sqlite_core0.SQLiteTextBuilderInitial<TName, [string, ...string[]], number | undefined>, _$drizzle_orm_pg_core0.PgTextBuilderInitial<TName, [string, ...string[]]>>;
+  /**
+   * Enum-config text — preserves the `enum` name-literal generic on BOTH
+   * dialects (`text(name, { enum })`).
+   *
+   * The signature mirrors drizzle's own `text` overload: generic over the
+   * element union `U` and the readonly tuple `T extends Readonly<[U, ...U[]]>`
+   * so the literal values flow into `$inferSelect` as `'a' | 'b'`, not `string`.
+   * A naive `{ enum: TEnum }` parameter widens the array literal to `string[]`
+   * and collapses the union.
+   * @param name - SQL column name.
+   * @param config - Drizzle text config carrying the `enum` literal tuple.
+   * @returns Dual builder for a `text` column narrowed to the enum union.
+   */
+  textEnum: <TName extends string, U extends string, T extends Readonly<[U, ...U[]]>>(name: TName, config: {
+    enum: T;
+  }) => DualBuilder<_$drizzle_orm_sqlite_core0.SQLiteTextBuilderInitial<TName, _$drizzle_orm0.Writable<T>, number | undefined>, _$drizzle_orm_pg_core0.PgTextBuilderInitial<TName, _$drizzle_orm0.Writable<T>>>;
+  /**
+   * Unix-epoch-ms — SQLite `integer` / PG `bigint` ('number' mode).
+   * @param name - SQL column name.
+   * @returns Dual builder for a millisecond-epoch column.
+   */
+  epochMs: (name: string) => DualBuilder<_$drizzle_orm_sqlite_core0.SQLiteIntegerBuilderInitial<string>, _$drizzle_orm_pg_core0.PgBigInt53BuilderInitial<string>>;
+  /**
+   * Boolean — SQLite `integer` (boolean mode) / PG native `boolean`.
+   * @param name - SQL column name.
+   * @returns Dual builder for a boolean column.
+   */
+  bool: (name: string) => DualBuilder<_$drizzle_orm_sqlite_core0.SQLiteBooleanBuilderInitial<string>, _$drizzle_orm_pg_core0.PgBooleanBuilderInitial<string>>;
+  /**
+   * Structured JSON — SQLite `text` (json mode) / PG `jsonb`, pinned to T.
+   * @param name - SQL column name.
+   * @returns Dual builder for a JSON column typed as `T`.
+   */
+  jsonCol: <T>(name: string) => DualBuilder<$Type<_$drizzle_orm_sqlite_core0.SQLiteTextJsonBuilderInitial<string>, T>, $Type<_$drizzle_orm_pg_core0.PgJsonbBuilderInitial<string>, T>>;
+  /**
+   * Auto PK — SQLite `integer PK AUTOINCREMENT` / PG identity `bigint` PK.
+   * @param name - SQL column name.
+   * @returns Dual builder for an auto-generated primary key column.
+   */
+  autoPk: (name: string) => DualBuilder<_$drizzle_orm0.IsPrimaryKey<_$drizzle_orm0.HasDefault<_$drizzle_orm0.NotNull<_$drizzle_orm_sqlite_core0.SQLiteIntegerBuilderInitial<string>>>>, _$drizzle_orm0.IsPrimaryKey<_$drizzle_orm0.NotNull<_$drizzle_orm0.IsIdentity<_$drizzle_orm_pg_core0.PgBigInt53BuilderInitial<string>, "always">>>>;
+  /**
+   * 8-byte float — SQLite `real` / PG `double precision`.
+   * @param name - SQL column name.
+   * @returns Dual builder for an 8-byte floating-point column.
+   */
+  float8: (name: string) => DualBuilder<_$drizzle_orm_sqlite_core0.SQLiteRealBuilderInitial<string>, _$drizzle_orm_pg_core0.PgDoublePrecisionBuilderInitial<string>>;
+  /**
+   * 32-bit integer — SQLite `integer` / PG `integer` (int4↔int4). For values
+   * that fit comfortably in 32 bits (PIDs, ordinals, attempt counters).
+   * @param name - SQL column name.
+   * @returns Dual builder for a 32-bit integer column.
+   */
+  int4: (name: string) => DualBuilder<_$drizzle_orm_sqlite_core0.SQLiteIntegerBuilderInitial<string>, _$drizzle_orm_pg_core0.PgIntegerBuilderInitial<string>>;
+  /**
+   * 64-bit integer — SQLite `integer` / PG `bigint` ('number' mode, int53-safe).
+   * For values that exceed the 32-bit range (byte cursors over large files).
+   * Distinct from `epochMs` only in intent; identical SQL mapping.
+   * @param name - SQL column name.
+   * @returns Dual builder for a 64-bit integer column.
+   */
+  int8: (name: string) => DualBuilder<_$drizzle_orm_sqlite_core0.SQLiteIntegerBuilderInitial<string>, _$drizzle_orm_pg_core0.PgBigInt53BuilderInitial<string>>;
+};
+/**
+ * Dialect-neutral column bundle passed to {@link defineDualTable}'s `colsFn`.
+ *
+ * Each helper builds both dialects' column builders from a single call, so a
+ * column declared once can never silently drift between the SQLite and Postgres
+ * faces.
+ */
+type DualColumnBundle = typeof dualColumns;
+type SqliteSplit<TCols extends Record<string, DualColumnBuilderBase>> = { [K in keyof TCols]: TCols[K]['sqlite'] };
+type PgSplit<TCols extends Record<string, DualColumnBuilderBase>> = { [K in keyof TCols]: TCols[K]['postgres'] };
+/** Result of {@link defineDualTable}: both real drizzle tables, fully typed. */
+interface DualTable<TName extends string, TCols extends Record<string, DualColumnBuilderBase>> {
+  readonly sqlite: SQLiteTableWithColumns<{
+    name: TName;
+    schema: undefined;
+    columns: BuildColumns<TName, SqliteSplit<TCols>, 'sqlite'>;
+    dialect: 'sqlite';
+  }>;
+  readonly postgres: PgTableWithColumns<{
+    name: TName;
+    schema: undefined;
+    columns: BuildColumns<TName, PgSplit<TCols>, 'pg'>;
+    dialect: 'pg';
+  }>;
+  /**
+   * Lazy dual column-pair accessor for foreign-key targets. Returns the BUILT
+   * columns of both faces under one key, so a referencing table can write
+   * `() => target.columnPair('id')` and have each dialect resolve correctly.
+   * @param key - Column key (the JS property name on the dual record).
+   * @returns The SQLite and Postgres built columns for `key`.
+   */
+  columnPair<K extends keyof TCols>(key: K): DualColumnPair;
+}
+/**
+ * Dialect-divergent extra config (indexes etc.). TWO callbacks: partial-index
+ * predicates legitimately differ (`= 1` vs `= true`).
+ */
+interface DualTableExtras<TName extends string, TCols extends Record<string, DualColumnBuilderBase>> {
+  readonly sqlite?: (self: BuildColumns<TName, SqliteSplit<TCols>, 'sqlite'>) => SQLiteTableExtraConfigValue[];
+  readonly postgres?: (self: BuildExtraConfigColumns<TName, PgSplit<TCols>, 'pg'>) => PgTableExtraConfigValue[];
+}
+/**
+ * Define ONE table for BOTH dialects from a single column definition.
+ * @param name - SQL table name (shared by both dialects).
+ * @param colsFn - Column definition over the dialect-neutral bundle.
+ * @param extras - Optional per-dialect indexes/constraints.
+ * @returns A {@link DualTable} exposing both built table objects and `columnPair`.
+ */
+declare function defineDualTable<TName extends string, TCols extends Record<string, DualColumnBuilderBase>>(name: TName, colsFn: (c: DualColumnBundle) => TCols, extras?: DualTableExtras<TName, TCols>): DualTable<TName, TCols>;
+//#endregion
 //#region storage/drizzle/src/index.d.ts
 /**
  * Drizzle schema record type.
@@ -134,4 +1087,4 @@ declare module '@makaio/framework/storage' {
   }
 }
 //#endregion
-export { type DrizzleHandlerRegistration, DrizzleSchemaRecord, type MakaioDatabase, type StorageNamespace, type StorageNamespaceConfig, type StorageNamespaceExtensions, type TransactionCallback, affectedRowCount, createStorageNamespace, didAffectRows, executeTransaction, registerDrizzleHandlers, sanitizeFtsQuery };
+export { DATABASE_DIALECT, type DialectSchema, type DrizzleHandlerRegistration, DrizzleSchemaRecord, type DrizzleWriteResult, type DualBuilder, type DualColumnBuilderBase, type DualColumnBundle, type DualColumnRef, type DualReferenceActions, type DualTable, type DualTableExtras, type Equal, type FtsMessageExcerptHit, type FtsMessageSearchInput, type FtsSearchStrategy, type FtsSessionCountInput, type FtsSessionSearchInput, type MakaioDatabase, NON_BASELINE_GENERATION_LEGS, type PostgresTwinSchema, type RawSqlExecutor, type RawSqlSession, STORAGE_ENGINE_URL_HINTS, type StorageDialect, type StorageEngine, type StorageEngineCapabilities, type StorageEngineErrorClassifiers, type StorageEngineGenerationLeg, type StorageEngineMigrationBehavior, type StorageEngineUrlHint, type StorageEngineUrlResolution, type StorageNamespace, type StorageNamespaceConfig, type StorageNamespaceExtensions, type TransactionCallback, affectedRowCount, brandDatabase, buildFirstUserMessagePreviewQuery, createStorageNamespace, defineDialectSchema, defineDualTable, describeMissingStorageEngine, didAffectRows, executeTransaction, findGenerationLegForDialect, findStorageEngine, getDatabaseDialect, getRawSqlExecutor, getStorageEngine, importRuntimeModule, isSqliteDuplicateObjectError, isSqliteUniqueViolationError, quoteSqlIdentifier, readErrorCode, registerDrizzleHandlers, registerStorageEngine, resolveSchema, resolveStorageEngine, resolveStorageEngineForUrl, sanitizeFtsQuery, someInCauseChain, sqliteFtsSearchStrategy, sqliteStorageEngine };