@tangen/db 0.0.0-stage → 0.1.54

package/src/instrument.ts

@@ -0,0 +1,139 @@
+/**
+ * File Name: instrument.ts
+ * Purpose: Query Monitor capture layer - wraps a postgres.js client so every
+ *   query (drizzle funnels through client.unsafe(); raw call sites use it
+ *   directly) reports { sql, durationMs } to a hook. Near-zero overhead when
+ *   no hook is set (one ref read per query).
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Three load-bearing details, all verified against
+ *   drizzle-orm 0.45 postgres-js driver + postgres.js 3.4 sources:
+ *   1. postgres.js Query is a LAZY Promise subclass - execution starts on the
+ *      first .then/.execute. Drizzle mutates the query (.values()) before
+ *      awaiting, so the wrapper must NEVER call .then itself; it patches the
+ *      instance's handle/resolve/reject (own properties) for timing instead.
+ *   2. resolve/reject fire in the connection socket's async context, where
+ *      AsyncLocalStorage would misattribute. Hence the TWO-PHASE hook: the
+ *      hook factory runs at unsafe()-call time (inside the caller's async
+ *      chain, where ALS is correct) and returns a recorder that is invoked
+ *      later at settle time.
+ *   3. begin()/savepoint()/reserve() hand out FRESH scoped Sql instances with
+ *      their own unsafe closures - they are instrumented recursively or
+ *      transaction/reserved-connection queries would be invisible.
+ */
+
+export interface QueryEvent {
+  /** Parameterized SQL text ($1 placeholders) - parameter VALUES are never captured. */
+  sql: string
+  /** Execution time: socket write → settle (excludes pool-queue wait). */
+  durationMs: number
+  /** Time spent queued waiting for a free pooled connection, when measurable. */
+  waitMs?: number
+  error?: boolean
+}
+
+/**
+ * Two-phase hook: called at query-issue time (correct async context); returns
+ * the recorder to invoke at settle time, or null to skip this query.
+ */
+export type QueryHook = () => ((e: QueryEvent) => void) | null
+
+const hookRef: { current: QueryHook | null } = { current: null }
+
+/** Install (or clear with null) the process-wide query hook. */
+export function setQueryHook(hook: QueryHook | null): void {
+  hookRef.current = hook
+}
+
+/** Patch one lazy Query instance for timing without forcing execution. */
+function instrumentQuery(q: any, sqlText: string, record: (e: QueryEvent) => void): void {
+  let start = performance.now()   // fallback if handle never fires (cached/errored early)
+  let execStart: number | null = null
+  const origHandle = q.handle
+  q.handle = function (this: any, ...args: unknown[]) {
+    if (!this.executed) start = performance.now()
+    return origHandle.apply(this, args)
+  }
+  // q.active flips true exactly when a connection makes this query its
+  // CURRENT one (verified postgres.js 3.4: connection.js:170 immediately on
+  // an idle connection, :573 when the preceding pipelined query finishes;
+  // resolve/reject set it back to false - falsy, ignored here). Trapping it
+  // separates waiting (pool queue + pipeline) from real execution: with the
+  // old creation→settle clock, a burst of concurrent requests counted all
+  // that waiting as "db time" (8x inflation observed on a cold admin load).
+  let activeVal = q.active
+  Object.defineProperty(q, 'active', {
+    configurable: true,
+    get: () => activeVal,
+    set: (v) => {
+      if (execStart === null && v) execStart = performance.now()
+      activeVal = v
+    },
+  })
+  const origResolve = q.resolve
+  const origReject = q.reject
+  const settle = (error?: boolean) => {
+    const now = performance.now()
+    const waitMs = execStart !== null ? Math.max(0, execStart - start) : 0
+    record({
+      sql: sqlText,
+      durationMs: now - (execStart ?? start),
+      ...(waitMs >= 0.5 ? { waitMs } : {}),
+      ...(error ? { error: true } : {}),
+    })
+  }
+  q.resolve = (v: unknown) => { settle(); return origResolve(v) }
+  q.reject = (e: unknown) => { settle(true); return origReject(e) }
+}
+
+/**
+ * Instruments a postgres.js client (or a scoped tx/reserved instance) in
+ * place - identity is preserved, so $rawClient consumers and duck-typed
+ * checks ({ unsafe, release }) keep working. Idempotent.
+ */
+export function instrumentSql<T extends object>(sql: T): T {
+  const s = sql as any
+  if (s.__qmInstrumented) return sql
+  s.__qmInstrumented = true
+
+  const origUnsafe = s.unsafe
+  if (typeof origUnsafe === 'function') {
+    s.unsafe = function (this: any, query: string, args?: unknown, opts?: unknown) {
+      const q = origUnsafe.call(this, query, args, opts)
+      const record = hookRef.current?.()   // two-phase: capture recorder NOW
+      if (record) instrumentQuery(q, query, record)
+      return q
+    }
+  }
+
+  if (typeof s.begin === 'function') {
+    const origBegin = s.begin
+    s.begin = function (this: any, options: any, fn?: any) {
+      const wrap = (f: any) => (txSql: any) => f(instrumentSql(txSql))
+      return typeof options === 'function'
+        ? origBegin.call(this, wrap(options))
+        : origBegin.call(this, options, wrap(fn))
+    }
+  }
+
+  if (typeof s.savepoint === 'function') {
+    const origSavepoint = s.savepoint
+    s.savepoint = function (this: any, name: any, fn?: any) {
+      const wrap = (f: any) => (spSql: any) => f(instrumentSql(spSql))
+      return typeof name === 'function'
+        ? origSavepoint.call(this, wrap(name))
+        : origSavepoint.call(this, name, wrap(fn))
+    }
+  }
+
+  if (typeof s.reserve === 'function') {
+    const origReserve = s.reserve
+    s.reserve = async function (this: any) {
+      return instrumentSql(await origReserve.call(this))
+    }
+  }
+
+  return sql
+}

package/src/knowledge-schema.ts

@@ -0,0 +1,232 @@
+/**
+ * File Name: knowledge-schema.ts
+ * Purpose: The ONE authority for the Knowledge tables' DDL (freeze review C4).
+ *          The canonical statements live here; migration 0041 carries them
+ *          verbatim (a test proves it); `ensureConditionalSystemSchema` applies
+ *          the pgvector-dependent part from the canonical migration entrypoint
+ *          when the extension arrived after the migration ran; and
+ *          `pinKnowledgeVectorSpace` is the single configuration-driven DDL
+ *          step - typing `embedding` to the configured model's dimensions and
+ *          building its ANN index - owned here, not by @tangen/knowledge.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: pgvector is an OPERATOR PREREQUISITE (decision B in
+ *          docs/architecture/database-safety.md): Tangen never runs
+ *          `CREATE EXTENSION vector`. `knowledge_meta`, `knowledge_qa` and
+ *          `knowledge_queries` need nothing and always exist after 0041;
+ *          `knowledge_chunks` needs the `vector` type and exists once it does.
+ *          Every statement is idempotent so the migration adopts tables an
+ *          older @tangen/knowledge created at runtime without touching a row.
+ */
+
+/** One statement in, rows out; the shape postgres.js `unsafe` and PGlite `query` both give. */
+export type SystemSqlExec = (text: string, params?: unknown[]) => Promise<Array<Record<string, unknown>>>
+
+export const KNOWLEDGE_TABLES = ['knowledge_meta', 'knowledge_chunks', 'knowledge_qa', 'knowledge_queries'] as const
+export type KnowledgeTable = typeof KNOWLEDGE_TABLES[number]
+
+/** The tables that need nothing but PostgreSQL. Idempotent: adoption of runtime-created tables is a no-op. */
+export const KNOWLEDGE_TABLE_DDL: readonly string[] = [
+  `CREATE TABLE IF NOT EXISTS "knowledge_meta" (
+  "workspace_id" text NOT NULL,
+  "provider" text NOT NULL,
+  "model" text NOT NULL,
+  "dimensions" integer NOT NULL,
+  "updated_at" timestamptz NOT NULL DEFAULT now(),
+  PRIMARY KEY ("workspace_id")
+)`,
+  `CREATE TABLE IF NOT EXISTS "knowledge_qa" (
+  "id" text PRIMARY KEY,
+  "workspace_id" text NOT NULL,
+  "question" text NOT NULL,
+  "answer" text NOT NULL,
+  "audience" text NOT NULL DEFAULT 'public',
+  "enabled" boolean NOT NULL DEFAULT true,
+  "updated_by" text,
+  "created_at" timestamptz NOT NULL DEFAULT now(),
+  "updated_at" timestamptz NOT NULL DEFAULT now()
+)`,
+  `CREATE INDEX IF NOT EXISTS "knowledge_qa_scope_idx" ON "knowledge_qa" ("workspace_id")`,
+  `CREATE TABLE IF NOT EXISTS "knowledge_queries" (
+  "id" bigserial PRIMARY KEY,
+  "workspace_id" text NOT NULL,
+  "query" text NOT NULL,
+  "source" text NOT NULL,
+  "audience" text NOT NULL DEFAULT 'public',
+  "locale" text NOT NULL DEFAULT '',
+  "top_score" real,
+  "hit_count" integer NOT NULL DEFAULT 0,
+  "answered" boolean NOT NULL DEFAULT false,
+  "created_at" timestamptz NOT NULL DEFAULT now()
+)`,
+  `CREATE INDEX IF NOT EXISTS "knowledge_queries_scope_idx" ON "knowledge_queries" ("workspace_id", "created_at")`,
+]
+
+/**
+ * The table that needs pgvector's `vector` type. `embedding` is declared
+ * without dimensions: they belong to the configured model and are applied by
+ * `pinKnowledgeVectorSpace`. Installs whose table an older runtime created
+ * already carry `vector(N)`; the pin leaves a matching column alone.
+ */
+export const KNOWLEDGE_CHUNKS_DDL: readonly string[] = [
+  `CREATE TABLE IF NOT EXISTS "knowledge_chunks" (
+  "id" bigserial PRIMARY KEY,
+  "workspace_id" text NOT NULL,
+  "source_kind" text NOT NULL,
+  "source_id" text NOT NULL,
+  "source_group" text NOT NULL DEFAULT '',
+  "field" text NOT NULL DEFAULT '',
+  "locale" text NOT NULL DEFAULT '',
+  "audience" text NOT NULL DEFAULT 'public',
+  "chunk_index" integer NOT NULL DEFAULT 0,
+  "content" text NOT NULL,
+  "content_hash" text NOT NULL,
+  "metadata" jsonb,
+  "embedding" vector NOT NULL,
+  "updated_at" timestamptz NOT NULL DEFAULT now()
+)`,
+  `ALTER TABLE "knowledge_chunks" ADD COLUMN IF NOT EXISTS "audience" text NOT NULL DEFAULT 'public'`,
+  `CREATE INDEX IF NOT EXISTS "knowledge_chunks_scope_idx" ON "knowledge_chunks" ("workspace_id", "source_kind", "source_id")`,
+]
+
+/** The migration's form of the pgvector-dependent DDL: applied only when the `vector` type is installed. */
+export function knowledgeChunksMigrationBlock(): string {
+  const body = KNOWLEDGE_CHUNKS_DDL.map((s) => `    EXECUTE $ddl$${s}$ddl$;`).join('\n')
+  return `DO $$
+BEGIN
+  IF EXISTS (SELECT 1 FROM pg_type WHERE typname = 'vector') THEN
+${body}
+  END IF;
+END $$;`
+}
+
+export const VECTOR_INSTALLED_SQL = `SELECT 1 AS ok FROM pg_type WHERE typname = 'vector'`
+
+/** True when pgvector's `vector` type exists in this database. */
+export async function isVectorInstalled(exec: SystemSqlExec): Promise<boolean> {
+  return (await exec(VECTOR_INSTALLED_SQL)).length > 0
+}
+
+/**
+ * The part of the system schema that depends on an optional server extension,
+ * applied from the canonical migration entrypoint (`runMigrations`) so an
+ * extension installed AFTER migration 0041 ran still yields the table the
+ * migration declares. Idempotent; nothing when pgvector is absent.
+ */
+export async function ensureConditionalSystemSchema(exec: SystemSqlExec): Promise<{ knowledgeChunks: 'applied' | 'skipped' }> {
+  if (!(await isVectorInstalled(exec))) return { knowledgeChunks: 'skipped' }
+  for (const stmt of KNOWLEDGE_CHUNKS_DDL) await exec(stmt)
+  return { knowledgeChunks: 'applied' }
+}
+
+export interface KnowledgeSchemaStatus {
+  /** pgvector's `vector` type exists in this database. */
+  vectorInstalled: boolean
+  /** The server ships pgvector (installable); null when it could not be asked. */
+  vectorAvailable: boolean | null
+  tables: Record<KnowledgeTable, boolean>
+  /** The typed dimensions of `knowledge_chunks.embedding`; null when untyped; undefined when the table is absent. */
+  embeddingDimensions: number | null | undefined
+}
+
+const EMBEDDING_TYPE_SQL = `SELECT format_type(a.atttypid, a.atttypmod) AS type
+  FROM pg_attribute a
+  JOIN pg_class c ON c.oid = a.attrelid
+  JOIN pg_namespace n ON n.oid = c.relnamespace
+  WHERE n.nspname = current_schema() AND c.relname = 'knowledge_chunks' AND a.attname = 'embedding' AND NOT a.attisdropped`
+
+function parseVectorType(type: string | undefined): number | null | undefined {
+  if (type === undefined) return undefined
+  const m = /^vector\((\d+)\)$/.exec(type)
+  return m ? Number(m[1]) : null
+}
+
+/** What doctor and the diagnostics look at: the extension, the four tables, the typed dimensions. */
+export async function readKnowledgeSchemaStatus(exec: SystemSqlExec): Promise<KnowledgeSchemaStatus> {
+  const vectorInstalled = await isVectorInstalled(exec)
+  let vectorAvailable: boolean | null = null
+  try {
+    vectorAvailable = (await exec(`SELECT 1 AS ok FROM pg_available_extensions WHERE name = 'vector'`)).length > 0
+  } catch { vectorAvailable = null }
+  // No bind parameters: doctor's read-only query takes a bare statement.
+  const present = new Set((await exec(
+    `SELECT table_name FROM information_schema.tables WHERE table_schema = current_schema() AND table_name IN (${KNOWLEDGE_TABLES.map((t) => `'${t}'`).join(', ')})`,
+  )).map((r) => String(r.table_name)))
+  const tables = Object.fromEntries(KNOWLEDGE_TABLES.map((t) => [t, present.has(t)])) as Record<KnowledgeTable, boolean>
+  const typeRows = tables.knowledge_chunks ? await exec(EMBEDDING_TYPE_SQL) : []
+  return { vectorInstalled, vectorAvailable, tables, embeddingDimensions: parseVectorType(typeRows[0]?.type as string | undefined) }
+}
+
+/** What an operator has to do, given the status; empty when Knowledge can run. */
+export function knowledgeSchemaAdvice(status: KnowledgeSchemaStatus): string {
+  if (!status.vectorInstalled) {
+    return status.vectorAvailable === false
+      ? 'pgvector is not installed on this PostgreSQL server. It is a prerequisite Tangen does not install: add the package for your platform (docs/knowledge.md, "Enabling pgvector"), run `CREATE EXTENSION vector;` as the database owner, then start Tangen again so its migrations create knowledge_chunks.'
+      : 'pgvector is available on this server but not enabled in this database. Run `CREATE EXTENSION vector;` as the database owner, then start Tangen again (or run `bun run db:migrate` in packages/db) so its migrations create knowledge_chunks.'
+  }
+  const missing = KNOWLEDGE_TABLES.filter((t) => !status.tables[t])
+  if (missing.length > 0) {
+    return `The knowledge table${missing.length === 1 ? '' : 's'} ${missing.join(', ')} ${missing.length === 1 ? 'is' : 'are'} missing: Tangen's migrations have not run against this database. They run at API boot (unless TANGEN_SKIP_MIGRATE=1), or run \`bun run db:migrate\` in packages/db.`
+  }
+  return ''
+}
+
+export class KnowledgeSchemaError extends Error {
+  readonly status: KnowledgeSchemaStatus
+  constructor(status: KnowledgeSchemaStatus, message = knowledgeSchemaAdvice(status)) {
+    super(message)
+    this.name = 'KnowledgeSchemaError'
+    this.status = status
+  }
+}
+
+export interface VectorSpacePin {
+  dimensions: number
+  /** The column was (re)typed to these dimensions. */
+  retyped: boolean
+  /** The ANN index now on the column: built here, already there, or none (sequential scan). */
+  index: 'hnsw' | 'ivfflat' | 'existing' | 'none'
+}
+
+/**
+ * Pins `knowledge_chunks.embedding` to the configured model's dimensions and
+ * gives it an ANN index. The one configuration-driven DDL step Knowledge has;
+ * owned here so the DDL has exactly one author. Idempotent: a column already
+ * typed to `dimensions` is left alone. Refuses to retype a column that holds
+ * rows in another space - that is a rebuild, and the caller says so.
+ */
+export async function pinKnowledgeVectorSpace(exec: SystemSqlExec, dimensions: number): Promise<VectorSpacePin> {
+  const dims = Math.floor(dimensions)
+  if (!(dims > 0)) throw new Error(`knowledge: embedding dimensions must be a positive integer, got ${dimensions}`)
+  const status = await readKnowledgeSchemaStatus(exec)
+  if (!status.tables.knowledge_chunks) throw new KnowledgeSchemaError(status)
+
+  let retyped = false
+  if (status.embeddingDimensions !== dims) {
+    if (status.embeddingDimensions !== null && status.embeddingDimensions !== undefined) {
+      const n = Number((await exec(`SELECT count(*)::int AS n FROM "knowledge_chunks"`))[0]?.n ?? 0)
+      if (n > 0) {
+        throw new Error(`knowledge_chunks holds ${n} chunk${n === 1 ? '' : 's'} in a ${status.embeddingDimensions}-dimension vector space and the configured model needs ${dims}. Run: tangen knowledge index --rebuild`)
+      }
+    }
+    await exec(`ALTER TABLE "knowledge_chunks" ALTER COLUMN "embedding" TYPE vector(${dims})`)
+    retyped = true
+  }
+
+  const existing = await exec(`SELECT 1 AS ok FROM pg_indexes WHERE schemaname = current_schema() AND tablename = 'knowledge_chunks' AND indexname = 'knowledge_chunks_embedding_idx'`)
+  if (existing.length > 0) return { dimensions: dims, retyped, index: 'existing' }
+  // HNSW when the server has it (pgvector >= 0.5); ivfflat otherwise; a sequential scan still answers at small scale.
+  try {
+    await exec(`CREATE INDEX IF NOT EXISTS "knowledge_chunks_embedding_idx" ON "knowledge_chunks" USING hnsw ("embedding" vector_cosine_ops)`)
+    return { dimensions: dims, retyped, index: 'hnsw' }
+  } catch {
+    try {
+      await exec(`CREATE INDEX IF NOT EXISTS "knowledge_chunks_embedding_idx" ON "knowledge_chunks" USING ivfflat ("embedding" vector_cosine_ops) WITH (lists = 100)`)
+      return { dimensions: dims, retyped, index: 'ivfflat' }
+    } catch {
+      return { dimensions: dims, retyped, index: 'none' }
+    }
+  }
+}

package/src/migrate.ts

@@ -0,0 +1,67 @@
+/**
+ * File Name: migrate.ts
+ * Purpose: Applies pending Drizzle ORM migrations against a PostgreSQL database,
+ *          and can be run directly as a CLI script via `bun src/migrate.ts`.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: Uses a single-connection postgres.js client (max: 1) and
+ *                     holds ONE session advisory lock for the whole run, so N
+ *                     replicas booting together migrate one after another: the
+ *                     first applies, the rest wait and find nothing pending
+ *                     (plan T1.16). Requires DATABASE_URL
+ *                     environment variable when invoked as a script. After the
+ *                     ledgered migrations it applies the conditional system
+ *                     schema (knowledge_chunks once pgvector exists) - see
+ *                     knowledge-schema.ts; this is the ONLY entrypoint for it.
+ */
+import postgres from 'postgres'
+import { drizzle } from 'drizzle-orm/postgres-js'
+import { migrate } from 'drizzle-orm/postgres-js/migrator'
+import { join } from 'node:path'
+import { ensureConditionalSystemSchema } from './knowledge-schema'
+
+const migrationsFolder = join(import.meta.dir, '..', 'drizzle')
+
+/** One key for every Tangen migrator on a database ("tangen" as digits). */
+export const MIGRATION_LOCK_KEY = 7461676531
+
+/**
+ * Applies all pending Drizzle migrations from the `drizzle/` folder to the target database.
+ * @param databaseUrl - PostgreSQL connection string for the target database
+ */
+export async function runMigrations(databaseUrl: string): Promise<void> {
+  // onnotice: idempotent re-runs emit "already exists, skipping" NOTICEs —
+  // expected, so keep them out of stdout.
+  const client = postgres(databaseUrl, { max: 1, onnotice: () => {} })
+  const db = drizzle(client)
+  try {
+    // Session-level: released explicitly below, and by the server if this
+    // connection dies. Every migrator on this database queues here.
+    await client.unsafe(`SELECT pg_advisory_lock(${MIGRATION_LOCK_KEY})`)
+    // Migration 0051 (remove environments) keeps one environment per workspace;
+    // when that choice is ambiguous the operator names it, and the migration
+    // reads the name from this session setting.
+    const keep = process.env.TANGEN_KEEP_ENVIRONMENT?.trim()
+    if (keep) await client.unsafe(`SET tangen.keep_environment = '${keep.replace(/'/g, "''")}'`)
+    await migrate(db, { migrationsFolder })
+    // The part of the system schema that waits on an optional server
+    // extension: the migration declares it, and this applies it once the
+    // extension is there - the same canonical text, from the same entrypoint.
+    await ensureConditionalSystemSchema((text, params) => client.unsafe(text, (params ?? []) as never) as unknown as Promise<Array<Record<string, unknown>>>)
+    console.log('Migrations applied successfully')
+  } finally {
+    await client.unsafe(`SELECT pg_advisory_unlock(${MIGRATION_LOCK_KEY})`).catch(() => {})
+    await client.end()
+  }
+}
+
+if (import.meta.main) {
+  const url = process.env.DATABASE_URL
+  if (!url) {
+    console.error('DATABASE_URL is required')
+    process.exit(1)
+  }
+  await runMigrations(url)
+}

package/src/prepare-policy.ts

@@ -0,0 +1,118 @@
+/**
+ * File Name: prepare-policy.ts
+ * Purpose: Make `TANGEN_DB_PREPARE=true` mean what it says for ordinary
+ *   Drizzle queries, which postgres.js otherwise executes unprepared however
+ *   the connection is configured.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: This is a compatibility shim, not a feature. postgres.js
+ *   3.4 builds every `unsafe()` query with a per-query `prepare: false`:
+ *
+ *     // postgres/src/index.js
+ *     function unsafe(string, args = [], options = {}) {
+ *       const query = new Query([string], args, handler, cancel, {
+ *         prepare: false, ...options, simple: ...
+ *       })
+ *
+ *   and the connection resolves the two levels with the per-query value
+ *   winning outright:
+ *
+ *     // postgres/src/connection.js
+ *     q.prepare = options.prepare && ('prepare' in q.options ? q.options.prepare : true)
+ *
+ *   drizzle-orm 0.45's postgres-js session issues EVERY query as
+ *   `client.unsafe(sql, params)` with no third argument, so no Drizzle query is
+ *   ever prepared and each one pays Parse + Describe + Flush before
+ *   Bind + Execute - two network round trips instead of one. Measured against a
+ *   cloud database 23 ms away that is 47.7 ms per statement instead of 23.4 ms.
+ *
+ *   Upstream: drizzle-orm issue #6096, open as of 2026-08-28; 1.0.0-rc.4 does
+ *   not address ordinary-query preparation for this driver.
+ *
+ *   REMOVAL CONDITION: when the installed drizzle-orm passes a preparation
+ *   option through to `client.unsafe`, delete this file and its call in
+ *   `createDb`. `prepare-policy.test.ts` fails loudly if that ever happens
+ *   silently, because it asserts the third argument this shim adds.
+ *
+ *   Three properties are deliberate:
+ *   1. It engages ONLY when preparation was explicitly asked for. Unset means
+ *      today's behaviour, unchanged.
+ *   2. It cannot force preparation on. postgres.js ANDs the connection-level
+ *      flag first, so `prepare: false` on the pool stays genuinely unprepared
+ *      even with this wrapper installed. Proven by test.
+ *   3. It touches only parameterized queries. BEGIN/COMMIT/ROLLBACK carry no
+ *      parameters, take the simple-query path, and are left byte-identical.
+ */
+
+/** Marks a client this policy has already wrapped; wrapping twice is a no-op. */
+const APPLIED = '__tangenPreparePolicy'
+
+/** postgres.js `unsafe(string, args?, options?)` in its three calling shapes. */
+type UnsafeFn = (query: string, args?: unknown, opts?: unknown) => unknown
+
+/**
+ * Threads an explicit preparation policy through a postgres.js client, and
+ * through the scoped clients `begin`/`savepoint`/`reserve` hand out, so
+ * transaction-scoped Drizzle queries follow the same policy as ordinary ones.
+ *
+ * Composes with instrumentSql in either order: both wrap `unsafe` and both
+ * recurse into the scoped clients, so Query Monitor capture is unaffected.
+ *
+ * @param sql - A postgres.js client, or a transaction/reserved scope of one.
+ * @param prepare - True to ask for prepared execution. Anything else returns
+ *   the client untouched, so the unprepared path keeps its exact behaviour.
+ * @returns The same client instance, mutated in place (identity preserved).
+ */
+export function applyPreparePolicy<T extends object>(sql: T, prepare: boolean): T {
+  if (!prepare) return sql
+  const s = sql as unknown as Record<string, unknown>
+  if (s[APPLIED]) return sql
+  s[APPLIED] = true
+
+  const origUnsafe = s.unsafe as UnsafeFn | undefined
+  if (typeof origUnsafe === 'function') {
+    s.unsafe = function (this: unknown, query: string, args?: unknown, opts?: unknown) {
+      // `unsafe(string, options)` is a supported two-argument shape: a
+      // non-array second argument IS the options object. Passing a third
+      // argument would stop postgres.js collapsing it, so collapse it here.
+      const twoArgOptions = args !== undefined && !Array.isArray(args)
+      const params = twoArgOptions ? [] : ((args as unknown[] | undefined) ?? [])
+      const given = (twoArgOptions ? args : opts) as Record<string, unknown> | undefined
+
+      // Only parameterized statements are affected. A statement with no
+      // parameters takes the simple-query path, which is already one round
+      // trip and which transaction control depends on.
+      if (params.length === 0) return origUnsafe.call(this, query, params, given ?? {})
+
+      // An explicit per-call option always wins: this fills a gap, it does not
+      // overrule a caller who has decided.
+      const merged = given && 'prepare' in given ? given : { ...given, prepare: true }
+      return origUnsafe.call(this, query, params, merged)
+    } as UnsafeFn
+  }
+
+  // The scoped clients begin/savepoint/reserve hand out are fresh instances
+  // with their own unsafe closures. Without recursion, every statement inside
+  // a transaction would keep the old behaviour - which is most of a write.
+  for (const key of ['begin', 'savepoint'] as const) {
+    const orig = s[key] as ((a: unknown, b?: unknown) => unknown) | undefined
+    if (typeof orig !== 'function') continue
+    s[key] = function (this: unknown, first: unknown, second?: unknown) {
+      const wrap = (f: (scoped: object) => unknown) => (scoped: object) => f(applyPreparePolicy(scoped, true))
+      return typeof first === 'function'
+        ? orig.call(this, wrap(first as (scoped: object) => unknown))
+        : orig.call(this, first, wrap(second as (scoped: object) => unknown))
+    }
+  }
+
+  const origReserve = s.reserve as (() => Promise<object>) | undefined
+  if (typeof origReserve === 'function') {
+    s.reserve = async function (this: unknown) {
+      return applyPreparePolicy(await origReserve.call(this), true)
+    }
+  }
+
+  return sql
+}

package/src/reconcile.ts

@@ -0,0 +1,115 @@
+/**
+ * File Name: reconcile.ts
+ * Purpose: Safety latch for drizzle migration-ledger drift — records migrations
+ *          whose SQL is ALREADY applied to the database but was never written to
+ *          `drizzle.__drizzle_migrations` (e.g. schema applied via `push` or an
+ *          out-of-band `ALTER` before the migrator ran). Pure bookkeeping: it
+ *          never runs migration SQL, it only inserts the missing ledger rows with
+ *          the correct sha256 hash + journal timestamp.
+ *
+ * Author: Raghunath J
+ * License: MIT
+ *
+ * Dependencies/Notes: SAFETY — only reconcile when the schema is genuinely up to
+ *          date (tables/columns exist from push or a partial migrate). It marks
+ *          migrations as applied WITHOUT running them, so on a truly-behind DB it
+ *          would skip real schema changes. Dry-run by default; `apply` writes.
+ */
+import { createHash } from 'node:crypto'
+import { readFileSync } from 'node:fs'
+import { join } from 'node:path'
+import postgres from 'postgres'
+
+const migrationsFolder = join(import.meta.dir, '..', 'drizzle')
+
+export interface JournalMigration { idx: number; tag: string; when: number; hash: string }
+
+/**
+ * Read the drizzle journal and compute each migration's sha256 (the exact value
+ * the __drizzle_migrations table stores — a hash of the raw .sql file content).
+ */
+export function readJournalMigrations(folder = migrationsFolder): JournalMigration[] {
+  const journal = JSON.parse(readFileSync(join(folder, 'meta', '_journal.json'), 'utf8')) as {
+    entries: { idx: number; tag: string; when: number }[]
+  }
+  return journal.entries.map((e) => ({
+    idx: e.idx,
+    tag: e.tag,
+    when: e.when,
+    hash: createHash('sha256').update(readFileSync(join(folder, `${e.tag}.sql`), 'utf8')).digest('hex'),
+  }))
+}
+
+/** Pure: journal migrations not present in the recorded-hash set, in journal order. */
+export function computeMissingMigrations(
+  journal: JournalMigration[],
+  recordedHashes: ReadonlySet<string>,
+): JournalMigration[] {
+  return journal.filter((m) => !recordedHashes.has(m.hash))
+}
+
+export interface ReconcileResult {
+  /** True when the ledger table exists; false means the DB was never migrated. */
+  ledgerExists: boolean
+  recorded: number
+  total: number
+  missing: JournalMigration[]
+  applied: boolean
+}
+
+/**
+ * Reconcile the migration ledger with the journal. Dry-run by default (reports
+ * what's missing); pass `{ apply: true }` to insert the missing rows.
+ */
+export async function reconcileMigrations(
+  databaseUrl: string,
+  opts: { apply?: boolean } = {},
+): Promise<ReconcileResult> {
+  const journal = readJournalMigrations()
+  const sql = postgres(databaseUrl, { max: 1 })
+  try {
+    const exists = await sql.unsafe(
+      `SELECT to_regclass('drizzle.__drizzle_migrations') IS NOT NULL AS present`,
+    )
+    if (!exists[0]?.present) {
+      return { ledgerExists: false, recorded: 0, total: journal.length, missing: [], applied: false }
+    }
+    const rows = await sql.unsafe(`SELECT hash FROM drizzle.__drizzle_migrations`)
+    const recorded = new Set(rows.map((r) => (r as unknown as { hash: string }).hash))
+    const missing = computeMissingMigrations(journal, recorded)
+    if (opts.apply) {
+      for (const m of missing) {
+        await sql.unsafe(
+          `INSERT INTO drizzle.__drizzle_migrations (hash, created_at) VALUES ($1, $2)`,
+          [m.hash, m.when],
+        )
+      }
+    }
+    return { ledgerExists: true, recorded: recorded.size, total: journal.length, missing, applied: !!opts.apply }
+  } finally {
+    await sql.end()
+  }
+}
+
+// CLI: `bun src/reconcile.ts [--apply]`. Dry-run reports drift; --apply records it.
+if (import.meta.main) {
+  const url = process.env.DATABASE_URL
+  if (!url) {
+    console.error('DATABASE_URL is required')
+    process.exit(1)
+  }
+  const apply = process.argv.includes('--apply')
+  const res = await reconcileMigrations(url, { apply })
+  if (!res.ledgerExists) {
+    console.log('No migration ledger found - this DB has never been migrated. Run `db:migrate` first.')
+  } else if (res.missing.length === 0) {
+    console.log(`Migration ledger is in sync (${res.recorded}/${res.total} recorded). Nothing to reconcile.`)
+  } else if (apply) {
+    console.log(`Recorded ${res.missing.length} previously-applied migration(s): ${res.missing.map((m) => m.tag).join(', ')}`)
+    console.log(`Ledger now in sync (${res.total}/${res.total}).`)
+  } else {
+    console.log(`Ledger drift: ${res.recorded}/${res.total} recorded. Missing (already applied, not recorded):`)
+    for (const m of res.missing) console.log(`  - ${m.tag}`)
+    console.log('\nRun with --apply to record them (only do this if the schema is actually up to date).')
+  }
+}