@cosmicdrift/kumiko-framework 0.386.0 → 0.388.0

package/dist/db/migrate-runner.js

@@ -1,26 +1,26 @@
-// Migrate-Runner: applied checked-in SQL-Files gegen eine DB.
-// Ersatz für `drizzle-kit migrate` als Runtime-Komponente.
+// Migration runner: applies checked-in SQL files to a database.
+// Replaces `drizzle-kit migrate` as a runtime component.
 //
-// **NO-MAGIC-ON-DATA Kernprinzip** (siehe drizzle-replacement.md):
-//   - Runner liest NUR checked-in `<dir>/*.sql` Files
-//   - Kein Reach-back zu EntityDefinition zur Runtime
-//   - Kein Auto-Apply-on-App-Boot — Deploy-Skript oder Init-Container ruft
-//     `kumiko migrate apply` als eigenen Schritt
-//   - Schema-Drift wird durch Checksum-Mismatch fail-loud detektiert
+// **NO-MAGIC-ON-DATA core principle** (see drizzle-replacement.md):
+//   - The runner reads ONLY checked-in `<dir>/*.sql` files.
+//   - It does not reach back to EntityDefinition at runtime.
+//   - It does not auto-apply on app boot — a deploy script or init container
+//     invokes `kumiko migrate apply` as a separate step.
+//   - Schema drift is detected fail-loudly through checksum mismatches.
 //
-// Tracking-Table `_kumiko_migrations(id, applied_at, checksum)`. id = filename
-// ohne .sql-Endung. Checksum = sha256 vom File-Content beim Apply. Wenn ein
-// schon-appliedes File nachträglich editiert wird, schlägt der nächste Apply
-// fehl mit klarer Fehlermeldung (production-DBs haben das alte SQL drin —
-// edit nachträglich = production-state inkonsistent mit committed-state).
+// Tracking table: `_kumiko_migrations(id, applied_at, checksum)`. `id` is the
+// filename without the `.sql` suffix. The checksum is the sha256 hash of the
+// file content at apply time. If an already-applied file is edited, the next
+// apply fails with a clear error (production databases contain the old SQL —
+// editing it makes production state inconsistent with committed state).
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
 import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { asRawClient, hasBegin, } from "./query.js";
-// Advisory-lock key (random 32-bit int, stable). Verhindert dass zwei
-// gleichzeitig bootende Pods beide migrate apply laufen lassen (zweiter
-// blockiert bis erster fertig).
+// Advisory-lock key (random 32-bit integer, stable). Prevents two Pods
+// booting at the same time from both running migrate apply (the second
+// blocks until the first finishes).
 export const MIGRATION_ADVISORY_LOCK_KEY = 0x6b756d69; // "kumi" in ASCII
 const MIGRATIONS_TABLE_DDL = `
 CREATE TABLE IF NOT EXISTS "_kumiko_migrations" (
@@ -147,7 +147,7 @@ function sha256Hex(content) {
 // returns Migration[] with id + checksum + statements. `preprocess` is an
 // optional hook applied to each file's raw content before splitting/hashing
 // — used by replayMigrationsDir to expand its DESTRUCTIVE-marker comments
-// without a second, drifting copy of this file-discovery logic (#1522/9).
+// without a second, drifting copy of this file-discovery logic.
 export function loadMigrationsFromDir(dir, preprocess) {
     const files = readdirSync(dir)
         .filter((f) => f.endsWith(".sql"))
@@ -230,9 +230,9 @@ export class MigrationChecksumMismatchError extends Error {
         this.name = "MigrationChecksumMismatchError";
     }
 }
-// Apply pending migrations. Idempotent: schon applied migrations werden via
-// _kumiko_migrations-Lookup übersprungen. Checksum-Mismatch wirft fail-loud.
-// Advisory-Lock verhindert concurrent-apply-races.
+// Applies pending migrations. Idempotent: already-applied migrations are
+// skipped via the _kumiko_migrations lookup. Checksum mismatches fail loudly.
+// The advisory lock prevents concurrent-apply races.
 export async function runMigrations(db, migrations) {
     // Session-level advisory lock and per-migration BEGIN/COMMIT must share one
     // session. Pool calls may land on different connections (the pool round-robins),
@@ -256,9 +256,9 @@ export async function runMigrations(db, migrations) {
                     skippedIds.push(m.id);
                     continue;
                 }
-                // Apply file content + INSERT tracking-row in einer TX. Wenn ein
-                // Statement bricht, Rollback inkl. Tracking-Row → kein partial-apply
-                // stuck in den books.
+                // Applies the file content and INSERT tracking row in one transaction. If a
+                // statement fails, the rollback includes the tracking row, so no partial
+                // apply remains stuck in the books.
                 await conn.unsafe("BEGIN");
                 try {
                     for (const stmt of m.statements) {
@@ -280,7 +280,10 @@ export async function runMigrations(db, migrations) {
             return { applied: appliedIds, skipped: skippedIds };
         }
         finally {
-            await conn.unsafe(`SELECT pg_advisory_unlock(${MIGRATION_ADVISORY_LOCK_KEY})`);
+            // A dropped session already released its lock; failing here would mask the migration error.
+            await conn
+                .unsafe(`SELECT pg_advisory_unlock(${MIGRATION_ADVISORY_LOCK_KEY})`)
+                .catch(() => undefined);
         }
     }
     finally {
@@ -289,8 +292,8 @@ export async function runMigrations(db, migrations) {
         await conn.release();
     }
 }
-// Convenience: load + run in einem Call. Wird vom `kumiko migrate apply`
-// CLI-Command + von Test-Setup-Helfern verwendet.
+// Convenience: loads and runs migrations in one call. Used by the
+// `kumiko migrate apply` CLI command and by test setup helpers.
 export async function runMigrationsFromDir(db, dir) {
     const migrations = loadMigrationsFromDir(dir);
     return runMigrations(db, migrations);

package/dist/db/money.d.ts

@@ -15,17 +15,17 @@ export type MoneyRead = {
      * @deprecated Removed in 0.390.0. Use `amountScaled` — this name implies ISO-4217 minor units
      * (cents), which is wrong once a currency needing a different scale than
      * the current flat MINOR_UNIT_SCALE=100 lands (e.g. JPY, 0 decimals).
-     * Alias of `amountScaled`, kept until #1976/4 and #1976/5 migrate their
-     * consumers off it.
+     * Alias of `amountScaled`, kept until the consumers migrate off it.
      */
     readonly amountMinor: number;
 };
 /**
- * DB → API: zwei flache Spalten zu combined { amount, currency } rehydraten.
+ * Rehydrate two flat DB columns into a combined `{ amount, currency }` value.
  *
- * Wirft loud bei korrupter DB-Form (string das nicht zur Zahl wird) — silent
- * data-loss wäre Bug-Vektor. NULL/undefined amount → field aus Output entfernt.
+ * Throws loudly for corrupt DB values (for example, a string that cannot be
+ * converted to a number), because silent data loss would hide a bug. A
+ * NULL/undefined amount removes the field from the output.
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate its input.
  */
 export declare function rehydrateMoney(row: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;

package/dist/db/money.js

@@ -1,17 +1,17 @@
-// Auto-Convert für money-Felder im DB-Layer.
+// Automatically convert money fields in the DB layer.
 //
-// Vertrag (siehe auch db/located-timestamp.ts — gleicher Compound-Type-Pattern):
-//   API-Form:    { amount, currency } | number — amount in MAJOR units (56799.16 EUR)
-//   DB-Form:     <name> BIGINT (minor units, e.g. cents) + <name>Currency TEXT
-//   Read-Form:   { amount, currency, amountScaled } — amount in MAJOR units again,
-//                amountScaled sits alongside as the exact integer value in
-//                MINOR_UNIT_SCALE units (fw#1830) for callers that need
-//                scale-exact comparisons (e.g. invoice sums) instead of
-//                round-tripping the float amount through /100·*100.
+// Contract (see also db/located-timestamp.ts — the same compound-type pattern):
+//   API form:   { amount, currency } | number — amount in MAJOR units (56799.16 EUR)
+//   DB form:    <name> BIGINT (minor units, e.g. cents) + <name>Currency TEXT
+//   Read form:  { amount, currency, amountScaled } — amount in MAJOR units again,
+//               amountScaled sits alongside as the exact integer value in
+//               MINOR_UNIT_SCALE units for callers that need scale-exact
+//               comparisons (e.g. invoice sums) instead of round-tripping the
+//               float amount through /100·*100.
 //                `amountMinor` stays as a @deprecated alias of the same
-//                value until #1976/4 and #1976/5 migrate their remaining
-//                consumers (renderer/web/primitives/index.tsx,
-//                renderer/components/render-field.tsx) off the old name.
+//               value until the remaining consumers
+//               (renderer/web/primitives/index.tsx,
+//               renderer/components/render-field.tsx) migrate off the old name.
 //
 // table-builder.ts's moneyAmount column has always documented BIGINT as
 // "the integer minor unit" — this file used to just pass the API amount
@@ -23,13 +23,13 @@
 // pass/receive ordinary decimal amounts; DB storage stays exact-integer
 // cents (no float drift in SUM()/aggregate queries).
 //
-// Permissiv-Insert: primitive number wird als amount akzeptiert (Legacy aus
-// pre-Stufe-3-Samples). Currency fällt dann auf entity.defaultCurrency
-// zurück (oder DEFAULT_CURRENCIES[0] = "EUR" als Framework-Fallback).
+// Permissive insert: a primitive number is accepted as amount (legacy from
+// pre-Stufe-3 samples). Currency then falls back to entity.defaultCurrency
+// (or DEFAULT_CURRENCIES[0] = "EUR" as the framework fallback).
 //
-// Anders als locatedTimestamp behalten wir den Field-Namen `<name>` als
-// amount-Spalte (Legacy DB-Convention für Money — `SUM(buying_price)` bleibt
-// idiomatisch). `<name>Currency` ist die zusätzliche Spalte.
+// Unlike locatedTimestamp, we retain the field name `<name>` as the
+// amount column (legacy DB convention for money — `SUM(buying_price)` remains
+// idiomatic). `<name>Currency` is the additional column.
 import { MINOR_UNIT_SCALE, toMinorUnits } from "../engine/minor-units.js";
 import { DEFAULT_CURRENCIES } from "../engine/types/index.js";
 const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
@@ -46,9 +46,9 @@ function toMajorUnits(amountScaled) {
 // scaled the same way. `applyTotalsMatchRefinements` (schema-builder.ts)
 // uses this internally for `EmbeddedFieldDef.totalsMatch`; exported so a
 // custom write-handler doing its own total check doesn't have to re-derive
-// this unwrap-and-scale step by hand (kumiko-framework#1972 — a hand-rolled
-// comparison of a raw `{amount}` against a raw minor-unit row sum is exactly
-// what silently fails 100x off).
+// this unwrap-and-scale step by hand. A hand-rolled comparison of a raw
+// `{amount}` against a raw minor-unit row sum is exactly what silently fails
+// 100× off.
 export function moneyPayloadToMinorUnits(raw) {
     if (typeof raw === "number")
         return toMinorUnits(raw);
@@ -81,7 +81,7 @@ export function flattenMoney(payload, entity) {
         }
         else if (typeof raw === "number") {
             amount = raw;
-            // Expliziter currency-key im Payload überschreibt den Default-Fallback.
+            // An explicit currency key in the payload overrides the default fallback.
             const explicitCurrency = result[`${name}Currency`];
             currency = typeof explicitCurrency === "string" ? explicitCurrency : fallbackCurrency;
         }
@@ -95,12 +95,13 @@ export function flattenMoney(payload, entity) {
     return result;
 }
 /**
- * DB → API: zwei flache Spalten zu combined { amount, currency } rehydraten.
+ * Rehydrate two flat DB columns into a combined `{ amount, currency }` value.
  *
- * Wirft loud bei korrupter DB-Form (string das nicht zur Zahl wird) — silent
- * data-loss wäre Bug-Vektor. NULL/undefined amount → field aus Output entfernt.
+ * Throws loudly for corrupt DB values (for example, a string that cannot be
+ * converted to a number), because silent data loss would hide a bug. A
+ * NULL/undefined amount removes the field from the output.
  *
- * Pure — mutiert nicht.
+ * Pure — does not mutate its input.
  */
 export function rehydrateMoney(row, entity) {
     const result = { ...row };
@@ -126,7 +127,8 @@ export function rehydrateMoney(row, entity) {
             }
         }
         else if (typeof amountRaw === "string" && amountRaw !== "") {
-            // PG-driver liefert BIGINT manchmal als String (>2^53 sicher).
+            // The PG driver sometimes returns BIGINT as a string (when it exceeds the
+            // safe integer range of 2^53).
             amountScaled = Number(amountRaw);
             if (!Number.isSafeInteger(amountScaled)) {
                 throw new Error(`rehydrateMoney: field "${name}" amount string "${amountRaw}" is not a safe integer — DB corruption?`);

package/dist/db/queries/backfill-pii.js

@@ -1,18 +1,18 @@
-// One-time backfill for pre-KMS plaintext PII in kumiko_events (#799).
+// One-time backfill for pre-KMS plaintext PII in kumiko_events.
 //
-// Crypto-shredding (#724/#818) only covers NEW writes — events appended
+// Crypto-shredding only covers NEW writes — events appended
 // before a KMS was configured still carry plaintext (user.created email,
 // delivery attempt recipientAddress, job payloads). This tool re-encrypts
 // them in place, per field, under the owning subject's DEK:
 //
 //   - entity lifecycle events (<entity>.created/updated/deleted/forgotten/
 //     restored) for every entity with PII subject annotations — generic over
-//     subject kind (user/tenant/record, fw#2790), since it goes through the
+//     subject kind (user/tenant/record), since it goes through the
 //     same collectPiiEncryptedFields/resolveSubjectForField the live write
 //     path uses
 //   - custom events from the event-PII catalog (r.defineEvent piiFields) —
 //     user/tenant/self subjects, via the same resolveEventSubject the live
-//     append path uses (fw#2801)
+//     append path uses
 //
 // Already-forgotten subjects must NOT get a fresh key minted for their old
 // plaintext — three erased-detection layers write [[erased]] instead:
@@ -28,7 +28,7 @@
 // Owner resolution for entity-lifecycle events. The live write path
 // (event-store-executor-write.ts) resolves the same chain via
 // subject-resolver.ts: row owner, then the owner the same event sets, then
-// the field's whenAbsent (fw#3654). Backfill adds two opt-in stages and
+// the field's whenAbsent. Backfill adds two opt-in stages and
 // delays whenAbsent behind the projection so a known owner is never shadowed:
 //   1. payload — the event section (plus the owner the same event sets) names
 //      the owner field; whenAbsent is not applied yet.

package/dist/db/queries/ddl.js

@@ -12,7 +12,7 @@ export async function alterTableAddColumn(db, tableName, columnName, columnType,
 // throwing when a column already exists with a different shape than
 // EntityTableMeta expects — that's how it surfaces drift. Callers that
 // just need an idempotent, race-safe backfill (e.g. event-consumer-state's
-// multi-instance boot path, #1362) opt in explicitly.
+// multi-instance boot path) opt in explicitly.
 ifNotExists = false) {
     await asRawClient(db).unsafe(`ALTER TABLE ${quoteTableIdent(tableName)} ADD COLUMN ${ifNotExists ? "IF NOT EXISTS " : ""}${quoteTableIdent(columnName)} ${columnType}${defaultClause}${notNull}`);
 }

package/dist/db/queries/es-ops.d.ts

@@ -1,5 +1,5 @@
 import type { AnyDb } from "../query.ts";
-/** Stabiler Lock-Key für pg_advisory_xact_lock — multi-replica seed boots. */
+/** Stable lock key for pg_advisory_xact_lock across multi-replica seed boots. */
 export declare const ES_OPS_ADVISORY_LOCK_KEY = 1702063984;
 export declare function acquireEsOpsAdvisoryLock(db: AnyDb): Promise<void>;
 export declare function esOperationExists(db: AnyDb, operationId: string): Promise<boolean>;

package/dist/db/queries/es-ops.js

@@ -1,5 +1,5 @@
 import { asRawClient } from "../query.js";
-/** Stabiler Lock-Key für pg_advisory_xact_lock — multi-replica seed boots. */
+/** Stable lock key for pg_advisory_xact_lock across multi-replica seed boots. */
 export const ES_OPS_ADVISORY_LOCK_KEY = 0x65_73_6f_70; // 'esop'
 export async function acquireEsOpsAdvisoryLock(db) {
     await asRawClient(db).unsafe(`SELECT pg_advisory_xact_lock($1)`, [ES_OPS_ADVISORY_LOCK_KEY]);

package/dist/db/queries/event-consumer.js

@@ -24,7 +24,7 @@ export async function lockEventConsumersShareMode(db) {
     await asRawClient(db).unsafe(`LOCK TABLE "kumiko_event_consumers" IN SHARE MODE`);
 }
 // The MAX(id) horizon plus every currently-open id gap below it, read from a
-// single statement snapshot. Used both to seed startFrom "now" (#3231) and to
+// single statement snapshot. Used both to seed startFrom "now" and to
 // seed an MSP rebuild's handoff to the live dispatcher (msp-rebuild.ts).
 //
 // Scan lower bound: the consumer with the highest cursor already tracks every
@@ -84,7 +84,7 @@ export async function selectEventIdHorizonWithMissingRanges(db) {
 // WithMissingRanges): a transaction holding a lower id can still be
 // in-flight at boot, and without seeding those gaps its event would commit
 // after the cursor already sits above it, so `id > cursor` would never
-// deliver it (#3231). The cheap existence check skips the scan entirely for
+// deliver it. The cheap existence check skips the scan entirely for
 // the (overwhelmingly common) case of an already-registered consumer.
 // ON CONFLICT DO NOTHING keeps both branches safe for an existing row: the
 // subquery only ever affects the row this statement inserts.
@@ -144,7 +144,7 @@ export async function markConsumerProcessing(db, name, instanceId) {
 // repeated infra blips (the exact case this backoff exists for) dead-letter
 // the consumer on the next real handler failure instead of after
 // maxAttempts. Visibility is covered by last_error, updated_at, and the
-// caller's console.error — status and the cursor are left as-is too, since
+// caller's error log — status and the cursor are left as-is too, since
 // we don't know at this point whether the consumer should be "dead" (that's
 // the deliverEvents/maxAttempts contract, which never ran this pass).
 //

package/dist/db/queries/event-store.js

@@ -1,7 +1,9 @@
+import { createFallbackLogger } from "../../logging/utils.js";
 import { constraintOf, isLockNotAvailable, isTableAlreadyExists, isUniqueViolation, } from "../pg-error.js";
 import { asRawClient, runInNewTransaction, runnerCanBeginTransaction, unsafeReadRetrying, } from "../query.js";
 import { withoutStatementTimeout } from "../statement-timeout.js";
 import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
+const log = createFallbackLogger("event-store");
 // Gap-finality (event-dispatcher pending_gaps) needs every holder of an
 // event id to already have a *real* xact id by the time it inserts — Postgres
 // assigns those lazily on first write, so a bare INSERT alone doesn't
@@ -81,9 +83,9 @@ async function buildIdempotencyKeyIndex(db) {
             // skip: sibling pod already built a valid index — this race loser is done.
             if ((await indexValidity(client)) === true)
                 return;
-            console.warn(`ensureIdempotencyKeyIndex: backed off on a "benign" race (${String(e)}) but ` +
+            log.warn(`ensureIdempotencyKeyIndex: backed off on a "benign" race but ` +
                 `"events_idempotency_uq" is still missing/invalid afterward — likely a ` +
-                `lock_timeout during CREATE INDEX CONCURRENTLY, not an actual winner/loser race.`);
+                `lock_timeout during CREATE INDEX CONCURRENTLY, not an actual winner/loser race.`, { err: e });
             throw e;
         }
         throw duplicateIdempotencyKeyErrorOr(e);

package/dist/db/queries/projection-rebuild.js

@@ -14,7 +14,7 @@ export async function markProjectionRebuilding(db, projectionName) {
 export async function selectEventsForProjectionRebuildBatch(db, aggregateTypes, eventTypes, afterId, limit) {
     // Archived streams don't replay (Marten-aligned): their aggregates are
     // frozen ops-tombstones — replaying them would resurrect rows (or, for
-    // stranded duplicate-aggregates like fw#832, collide on unique indexes).
+    // stranded duplicate-aggregates, collide on unique indexes).
     return unsafeReadRetrying(db, `SELECT * FROM "kumiko_events" e
      WHERE e."aggregate_type" = ANY($1::text[])
        AND e."type" = ANY($2::text[])
@@ -29,9 +29,9 @@ export async function selectEventsForProjectionRebuildBatch(db, aggregateTypes,
 // Total subscribed events in the log — same source/type filter as
 // selectEventsForProjectionRebuildBatch, no id cursor. Under the cutover fence
 // this is the ground-truth count the rebuild must have applied; a shortfall
-// means a lower-id event committed late and the id-cursor leapt past it (#443).
+// means a lower-id event committed late and the id-cursor leapt past it.
 export async function countSubscribedEvents(db, aggregateTypes, eventTypes) {
-    // Same archived-streams exclusion as the batch query — the #443 recompute
+    // Same archived-streams exclusion as the batch query — the recompute
     // compares this count against applied events; a filter mismatch would make
     // every rebuild with an archived stream loop the full-re-replay forever.
     const rows = await unsafeReadRetrying(db, `SELECT count(*)::bigint AS n FROM "kumiko_events" e

package/dist/db/queries/raw-sql.d.ts

@@ -1,9 +1,9 @@
 import type { AnyDb } from "../query.ts";
 /** Escape hatch for caller-built SQL that may write (or lock). No closed-connection retry —
- *  retrying an ambiguous write risks double-apply (#1358). Prefer {@link executeRawQueryRead}
+ *  retrying an ambiguous write risks double-apply. Prefer {@link executeRawQueryRead}
  *  for SELECT-only paths. */
 export declare function executeRawQuery<T = Record<string, unknown>>(db: AnyDb, sqlText: string, params?: readonly unknown[]): Promise<readonly T[]>;
-/** SELECT-only escape hatch with the #1163 closed-connection retry. Do not pass
+/** SELECT-only escape hatch with the closed-connection retry. Do not pass
  *  INSERT/UPDATE/DELETE — retry re-executes the statement. */
 export declare function executeRawQueryRead<T = Record<string, unknown>>(db: AnyDb, sqlText: string, params?: readonly unknown[]): Promise<readonly T[]>;
 export declare function pingDatabase(db: AnyDb): Promise<void>;

package/dist/db/queries/raw-sql.js

@@ -1,11 +1,11 @@
 import { asRawClient, unsafeReadRetrying } from "../query.js";
 /** Escape hatch for caller-built SQL that may write (or lock). No closed-connection retry —
- *  retrying an ambiguous write risks double-apply (#1358). Prefer {@link executeRawQueryRead}
+ *  retrying an ambiguous write risks double-apply. Prefer {@link executeRawQueryRead}
  *  for SELECT-only paths. */
 export async function executeRawQuery(db, sqlText, params = []) {
     return await asRawClient(db).unsafe(sqlText, params);
 }
-/** SELECT-only escape hatch with the #1163 closed-connection retry. Do not pass
+/** SELECT-only escape hatch with the closed-connection retry. Do not pass
  *  INSERT/UPDATE/DELETE — retry re-executes the statement. */
 // @wrapper-known semantic-alias
 export async function executeRawQueryRead(db, sqlText, params = []) {

package/dist/db/queries/shadow-swap.js

@@ -64,10 +64,10 @@ export function rebuildMetaOrThrow(table, projectionName) {
     return meta;
 }
 // Fence against a rebuild running with a registry that does not match the
-// migrated live schema (#835): during a rolling deploy, a pod still running
+// migrated live schema: during a rolling deploy, a pod still running
 // the previous build can pick up an async rebuild job; its shadow — built from
 // the stale EntityTableMeta — would swap away a freshly-migrated column
-// (recurrence class of #494). Compares COLUMN NAMES only; a type-/nullability-
+// (a recurring failure). Compares COLUMN NAMES only; a type-/nullability-
 // only drift passes (schema regression, not data loss — the boot gate of the
 // next deploy catches it). A missing live table is fine: nothing to wipe.
 // Must run BEFORE buildShadowTable; columnNamesOf pins table_schema='public',
@@ -93,7 +93,7 @@ export async function assertLiveColumnsMatchMeta(db, meta, projectionName) {
         "Rebuilding would swap away the difference. Likely cause: this pod runs a build whose registry is behind (or ahead of) the applied migrations — rolling deploy in progress? — or DDL was applied by hand. " +
         "Rebuild aborted; retry from a pod whose code matches the migrated schema.");
 }
-// EntityTableMeta carries no RLS/policies, so the swap would silently drop them (#2907).
+// EntityTableMeta carries no RLS/policies, so the swap would silently drop them.
 export async function assertLiveTableHasNoRowLevelSecurity(tx, tableName, projectionName) {
     const rows = await asRawClient(tx).unsafe(`SELECT c.relrowsecurity AS rls_enabled, c.relforcerowsecurity AS rls_forced,
        (SELECT count(*)::int FROM pg_policy p WHERE p.polrelid = c.oid) AS policy_count
@@ -158,7 +158,7 @@ const UNREACHABLE_SAMPLE_LIMIT = 20;
 // Runs INSIDE the rebuild tx, under the fence, before swapShadowIntoLive. A live
 // row whose aggregate id has NO event in the projection's source streams is
 // UNREACHABLE: no replay can ever reconstruct it, so the swap would silently
-// drop it. That is the #498 ghost — a row direct-inserted without ever emitting
+// drop it. That is a ghost row direct-inserted without ever emitting
 // a .created event. The static CI guard cannot see it in data that already
 // exists in production, or on table identifiers it couldn't resolve; this
 // catches it at cutover and aborts (tx rolls back, live untouched).
@@ -169,14 +169,14 @@ const UNREACHABLE_SAMPLE_LIMIT = 20;
 //   - a blind-index column recomputed to NULL after the subject's key is
 //     shredded (GDPR erase) — the NULL is the intended end state;
 //   - a `sensitive` column stripped from the event log by design;
-//   - an archived stream that stops replaying (fw#832) — the row's wipe is the
+//   - an archived stream that stops replaying — the row's wipe is the
 //     intended tombstone behavior, reported via backfill's `failed` list;
 //   - a legacy column direct-written before its handler emitted events, healed
-//     by the #494 backfill-then-rebuild flow.
+//     by the backfill-then-rebuild flow.
 // Checking event existence INCLUDING archived streams leaves every one of them
 // alone: those rows all have a real event, so they are not ghosts. Column-level
-// drift is a SEPARATE, non-blocking check — see countColumnDrift below (#916,
-// resolves the #722 open question: observe, don't block).
+// drift is a SEPARATE, non-blocking check — see countColumnDrift below,
+// which resolves the open question: observe, don't block.
 //
 // Implicit projections only (caller-gated). aggregate_id and the entity id are
 // both uuid, so the anti-join probes the events index without a cast.
@@ -298,8 +298,8 @@ async function assertBlindIndexKeyMatchesLive(raw, tableName, quotedTable, bidxC
         `untouched.`);
 }
 // The bidx column is schema-driven, not key-driven: it exists NULL in a
-// plaintext install and in the fw#1610 case (KMS configured, no index key),
-// both of which are correct as-is. Only a POPULATED column with no key
+// plaintext install and in the case where KMS is configured but no index key
+// is present, both of which are correct as-is. Only a POPULATED column with no key
 // configured in THIS process means the rebuild is about to overwrite proof
 // of a real index with NULL — that's the one provable data-loss case.
 export async function assertNoBlindIndexLoss(tx, tableName, meta, projectionName) {
@@ -331,29 +331,29 @@ export async function assertNoBlindIndexLoss(tx, tableName, meta, projectionName
 // live-vs-shadow divergence. A blind-index column (`<field>_bidx`) is
 // recomputed to NULL on GDPR key-shredding; the NULL is the intended end
 // state, not drift. Everything else that legitimately diverges (archived
-// streams, #494 backfill) either never reaches this comparison (archived rows
+// streams, backfill) either never reaches this comparison (archived rows
 // are absent from the shadow entirely, see swapShadowIntoLive) or IS real
-// column drift that the #494 backfill-then-rebuild flow relies on replay to
+// column drift that the backfill-then-rebuild flow relies on replay to
 // heal — reporting it (without blocking) is correct, not a false positive.
 const COLUMN_DRIFT_SAMPLE_LIMIT = 20;
 // Runs INSIDE the rebuild tx, in the same slot as assertNoUnreachableLiveRows
 // (after replay settles, before swapShadowIntoLive). Non-blocking counterpart
 // to the ghost-row guard: reports live rows whose column values differ from
-// the freshly-replayed shadow, WITHOUT aborting the swap (#916, resolves the
-// #722 open question in favor of observe-not-block).
+// the freshly-replayed shadow, WITHOUT aborting the swap (it resolves the
+// open question in favor of observe-not-block).
 //
 // Why non-blocking: a legacy column direct-written before its handler emitted
-// events (#494) diverges from replay by design — that divergence is exactly
+// events diverges from replay by design — that divergence is exactly
 // what the backfill-then-rebuild flow relies on replay to heal. Failing hard
 // here would make rebuild mutually exclusive with that shipped healing path.
-// There is no reliable metadata to distinguish "#494 healing in progress" from
+// There is no reliable metadata to distinguish "healing in progress" from
 // "someone else corrupted this row" short of an open-ended per-column policy
 // blocklist — wrong-by-default whenever a class is missed. So: surface it,
 // don't police it. The caller logs the result; ops decides.
 //
-// Caveat: sensitive CUSTOM fields still diverge until #972 (Subject-DEK
-// design) — regular sensitive fields carry event-payload ciphertext parity
-// post-#973 and don't drift. Both are reported the same as any other column
+// Caveat: sensitive CUSTOM fields still diverge until the Subject-DEK
+// design — regular sensitive fields carry event-payload ciphertext parity
+// post-design and don't drift. Both are reported the same as any other column
 // drift; this is deliberate (see module comment above), not an oversight.
 //
 // Relies on assertLiveColumnsMatchMeta having already run: live/shadow/meta

package/dist/db/query.d.ts

@@ -1,9 +1,9 @@
 import type { AggregateRow, AggregateSpec } from "@cosmicdrift/kumiko-types/aggregate-types";
 import type { DbRunner, DbTx } from "@cosmicdrift/kumiko-types/db-connection";
 import type { ExecutorManagedRunner, ExecutorManagedWriteCapability, WritableTable } from "@cosmicdrift/kumiko-types/executor-brand";
-import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { SelectOptions, WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
 import type { EntityTableMeta } from "./entity-table-meta.ts";
+import { type TableInfo } from "./table-info.ts";
 import { asEntityTableMeta, requireEntityTableMeta } from "./table-introspection.ts";
 export { asEntityTableMeta, requireEntityTableMeta };
 export type ReservedClient = {
@@ -24,26 +24,14 @@ export declare function hasBegin(client: RawClient): client is RawClientWithBegi
 export declare function asRawClient(db: unknown): RawClient;
 export declare function runnerCanBeginTransaction(db: unknown): boolean;
 export declare function runInSavepoint<T>(tx: ExecutorManagedRunner, fn: (sp: ExecutorManagedRunner) => Promise<T>): Promise<T>;
-export declare function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promise<T>): Promise<T>;
+export declare function runInSavepoint<T>(tx: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
 export declare function runInSavepointIfSupported<T>(db: ExecutorManagedRunner, fn: (sp: ExecutorManagedRunner) => Promise<T>): Promise<T>;
 export declare function runInSavepointIfSupported<T>(db: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
 export type AnyDb = DbRunner | unknown;
 type AnyRow = any;
 export type { JsonTextMatch, OrderByClause, SelectOptions, WhereObject, WhereOperator, WhereValue, } from "@cosmicdrift/kumiko-types/where-clause-types";
-type TableLike = EntityTableMeta | any;
-export type TableInfo = {
-    readonly name: string;
-    readonly columnOf: (field: string) => string;
-    readonly pgTypeOf: (column: string) => string | undefined;
-    readonly bigintJsModeOf: (column: string) => "number" | "bigint" | undefined;
-    readonly fieldOf: (column: string) => string;
-    readonly hasColumn: (fieldOrColumn: string) => boolean;
-};
-export declare function extractTableInfo(table: TableLike): TableInfo;
+export type TableLike = EntityTableMeta | any;
 export declare function coerceRow<TOut = Record<string, unknown>>(row: Record<string, unknown>, info: TableInfo): TOut;
-export declare function instantToTimestamptzParam(instant: Temporal.Instant): string;
-export declare function isClosedConnectionError(err: unknown): boolean;
-export declare function describeClosedConnectionFailure(raw: unknown, err: unknown, attempts: number): Record<string, unknown> | undefined;
 export declare function unsafeReadRetrying<TRow>(db: AnyDb, sqlText: string, params: readonly unknown[]): Promise<readonly TRow[]>;
 export declare function selectMany<TRow = AnyRow>(db: AnyDb, table: TableLike, where?: WhereObject, options?: SelectOptions): Promise<readonly TRow[]>;
 export declare function fetchOne<TRow = AnyRow>(db: AnyDb, table: TableLike, where: WhereObject): Promise<TRow | undefined>;
@@ -92,7 +80,6 @@ export type DeleteManyBatchedResult = {
     readonly batches: number;
 };
 export declare function countWhere(db: AnyDb, table: TableLike, where?: WhereObject): Promise<number>;
-export declare function isTimestamptzType(pgType: string | undefined): boolean;
 export declare function aggregateWhere(db: AnyDb, table: TableLike, spec: AggregateSpec, where?: WhereObject): Promise<readonly AggregateRow[]>;
 export declare function upsertOnConflict<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
 export declare function upsertOnConflict<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;