@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

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/queries/test-stack.d.ts

@@ -2,5 +2,8 @@ import type { AnyDb } from "../query.ts";
 export { alterTableAddColumn, createIndexIfNotExists, executeDdlStatement } from "./ddl.ts";
 export declare function truncateTablesRestartIdentity(db: AnyDb, tableNames: readonly string[]): Promise<void>;
 export declare function databaseExists(db: AnyDb, dbName: string): Promise<boolean>;
-export declare function createDatabase(db: AnyDb, dbName: string): Promise<void>;
+export declare function createDatabase(db: AnyDb, dbName: string, templateDbName?: string): Promise<void>;
+export declare function renameDatabase(db: AnyDb, fromName: string, toName: string): Promise<void>;
+export declare function listDatabaseNamesWithPrefix(db: AnyDb, prefix: string): Promise<readonly string[]>;
+export declare function acquireSessionAdvisoryLock(db: AnyDb, key: string): Promise<void>;
 export declare function dropDatabaseIfExists(db: AnyDb, dbName: string): Promise<void>;

package/dist/db/queries/test-stack.js

@@ -12,8 +12,21 @@ export async function databaseExists(db, dbName) {
     const rows = await asRawClient(db).unsafe(`SELECT EXISTS (SELECT 1 FROM pg_database WHERE datname = $1) AS exists`, [dbName]);
     return rows[0]?.exists === true;
 }
-export async function createDatabase(db, dbName) {
-    await asRawClient(db).unsafe(`CREATE DATABASE ${quoteTableIdent(dbName)}`);
+export async function createDatabase(db, dbName, templateDbName) {
+    const template = templateDbName === undefined ? "" : ` TEMPLATE ${quoteTableIdent(templateDbName)}`;
+    await asRawClient(db).unsafe(`CREATE DATABASE ${quoteTableIdent(dbName)}${template}`);
+}
+export async function renameDatabase(db, fromName, toName) {
+    await asRawClient(db).unsafe(`ALTER DATABASE ${quoteTableIdent(fromName)} RENAME TO ${quoteTableIdent(toName)}`);
+}
+export async function listDatabaseNamesWithPrefix(db, prefix) {
+    const rows = await asRawClient(db).unsafe(`SELECT datname FROM pg_database WHERE starts_with(datname, $1) ORDER BY datname`, [prefix]);
+    return rows.map((row) => row.datname);
+}
+// Session-scoped: CREATE DATABASE cannot run inside a transaction, so the
+// xact-scoped variant cannot guard it. Released when the session closes.
+export async function acquireSessionAdvisoryLock(db, key) {
+    await asRawClient(db).unsafe(`SELECT pg_advisory_lock(hashtext($1))`, [key]);
 }
 export async function dropDatabaseIfExists(db, dbName) {
     await asRawClient(db).unsafe(`DROP DATABASE IF EXISTS ${quoteTableIdent(dbName)}`);

package/dist/db/query.d.ts

@@ -24,7 +24,7 @@ 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;

package/dist/db/query.js

@@ -13,7 +13,7 @@
 //
 // `table` is an EntityTableMeta; the legacy table objects carrying it under a Symbol are accepted too.
 // Static import (not getTemporal()): coercion works without an installed
-// global and returns the same Temporal classes as the rest of the repo (#1480).
+// global and returns the same Temporal classes as the rest of the repo.
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import { isOneOf, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { requestContext } from "../api/request-context.js";
@@ -279,7 +279,7 @@ function isTemporalPlainDateTimeLike(v) {
         "toPlainDate" in v &&
         typeof v.toPlainDate === "function");
 }
-// Verified empirically (kumiko-framework#1924): a `date`
+// Verified empirically: a `date`
 // column comes back as a native JS Date, but ALWAYS anchored at UTC
 // midnight regardless of process TZ — epochMilliseconds is stable across
 // zones, only the local wall-clock read of that Date would drift the day
@@ -339,7 +339,7 @@ function coerceDriverRow(row, info) {
     const out = {};
     let changed = false;
     for (const key of Object.keys(row)) {
-        // Blind-index columns (#818) are pure lookup artifacts — the
+        // Blind-index columns are pure lookup artifacts — the
         // deterministic HMAC must never leak into caller/API responses.
         if ((key.endsWith("_bidx") || key.endsWith("Bidx")) && info.hasColumn(key)) {
             changed = true;
@@ -420,7 +420,7 @@ function isSqlExpression(v) {
 // as-is — no Instant detour. Postgres parses a DATE literal without ever
 // consulting the session timezone, so this is TZ-independent by construction
 // (verified empirically — see plainDateFromDriver above for the read side).
-// Compat cushion: pre-#1924 code (this field used to be an Instant) may still
+// Compat cushion: code (this field used to be an Instant) may still
 // hand a Temporal.Instant into a where-filter or write on a `date` column —
 // same UTC anchor as plainDateFromDriver's read side, so a filter built with
 // `Temporal.Now.instant()` keeps working instead of binding a raw Instant the
@@ -515,7 +515,7 @@ function buildWhereClause(info, where, startIndex, qualifier) {
     // multiSelect (and any other jsonb-array-of-scalars column) stores an
     // array — a filter value is one option, not the whole array, so eq/ne/in
     // must check array containment (`@>`) instead of scalar `=`/`<>`/`IN`
-    // against the jsonb column, which Postgres rejects outright (fw#2490).
+    // against the jsonb column, which Postgres rejects outright.
     // Mirrors event-store-executor-read.ts's applyFilter — keep in lock-step.
     function jsonbContainsAny(col, candidates) {
         if (candidates.length === 0)
@@ -703,7 +703,7 @@ function buildWhereClause(info, where, startIndex, qualifier) {
                 conditions.push(`${ref(col)} = ${p.literal}`);
             }
             else {
-                // Blind-index OR rewrite (#818): if the column has a bidx
+                // Blind-index OR rewrite: if the column has a bidx
                 // counterpart (suffix convention `<col>_bidx`, framework-reserved)
                 // and a key is configured, equality matches both arms —
                 // plaintext legacy rows via the plaintext arm, encrypted rows

package/dist/db/rebuild-marker.js

@@ -1,20 +1,18 @@
-// Rebuild-Marker für den drizzle-freien Migrations-Pfad.
+// Rebuild marker for the drizzle-free migration path.
 //
-// `kumiko schema generate` schreibt neben jedes `NNNN_<name>.sql` einen
-// Sibling-Marker `NNNN_<name>.rebuild.json`, der die in dieser Migration
-// geänderten/neu angelegten Tabellen listet. `kumiko schema apply` liest den
-// Marker für jede frisch applizierte Migration und rebuildet die betroffenen
-// Projektionen.
+// `kumiko schema generate` writes a sibling marker
+// `NNNN_<name>.rebuild.json` next to each `NNNN_<name>.sql`, listing the tables
+// changed or created by that migration. `kumiko schema apply` reads the marker
+// for each newly applied migration and rebuilds the affected projections.
 //
-// Bewusst nur **Tabellennamen** (kein Projection-Name): der Generator ist
-// registry-frei (kennt die App-Projektionen nicht). Die Auflösung
-// Tabelle→Projection passiert app-seitig beim Apply via
-// `buildProjectionTableIndex(registry)`. Tabellen ohne zugehörige Projektion
-// werden dort einfach übersprungen.
+// Deliberately stores only **table names** (not projection names): the generator
+// is registry-free and does not know the app's projections. The table-to-
+// projection resolution happens in the app during apply via
+// `buildProjectionTableIndex(registry)`. Tables without a corresponding
+// projection are simply skipped there.
 //
-// Marker werden zum generate-Zeitpunkt aus dem strukturierten `SchemaDiff`
-// geschrieben — nicht beim Apply aus dem (ggf. hand-editierten) SQL
-// re-derived.
+// Markers are written at generate time from the structured `SchemaDiff`, rather
+// than being re-derived during apply from the possibly hand-edited SQL.
 import { existsSync, readFileSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
 import { managedChangeRequiresRecreate } from "./migrate-generator.js";
@@ -29,12 +27,12 @@ function markerPathFor(migrationsDir, migrationId) {
 // (managedChangeRequiresRecreate: drop/NOT-NULL-w/o-default/unique-index/type-
 // or nullability-change) — then the table is emptied and must be re-derived from
 // events. A pure additive nullable column is an in-place `ADD COLUMN` ALTER that
-// already brings the table to the target state (same logic #181 applied to
+// already brings the table to the target state (same logic applied to
 // index-/default-only changes). Rebuilding it anyway is wasted replay AND — the
 // bug this closes — a co-triggered rebuild can drop the fresh column (rebuild
 // runs from the rebuilding process's registry meta; on a rolling deploy an older
 // pod's meta lacks the column → shadow-swap wipes it → phantom migration + boot-
-// drift crash; see 0008_add_pending_deletion_request_id / #494 / #835).
+// drift crash).
 //
 // If a NEW additive column genuinely needs value-backfill from historical events
 // (a column DERIVED from existing event fields), opt in explicitly by hand-adding
@@ -60,18 +58,19 @@ export function rebuildTablesFromDiff(diff) {
     }
     return [...names].sort();
 }
-// Schreibt `<sqlFilename ohne .sql>.rebuild.json`. Leere Tabellen-Liste →
-// kein Marker (z.B. reine Drop-Migration).
+// Writes `<sqlFilename without .sql>.rebuild.json`. An empty table list writes no
+// marker (for example, a drop-only migration).
 export function writeRebuildMarker(migrationsDir, sqlFilename, tables) {
-    // skip: leere Tabellen-Liste → kein Marker (z.B. reine Drop-Migration).
+    // skip: empty table list means no marker is written (for example, for a
+    // migration that only drops tables).
     if (tables.length === 0)
         return;
     const migrationId = sqlFilename.replace(/\.sql$/, "");
     const marker = { version: MARKER_VERSION, tables };
     writeFileSync(markerPathFor(migrationsDir, migrationId), `${JSON.stringify(marker, null, 2)}\n`);
 }
-// Liest die Tabellen-Liste für eine applizierte Migration. Kein Marker /
-// kaputtes File → leere Liste (Migration ohne Projection-Impact).
+// Reads the table list for an applied migration. A missing or malformed file
+// yields an empty list (the migration has no projection impact).
 export function readRebuildMarker(migrationsDir, migrationId) {
     const path = markerPathFor(migrationsDir, migrationId);
     if (!existsSync(path))

package/dist/db/replay-migration-sql.js

@@ -70,7 +70,7 @@ function parseColumnNames(body) {
 // through to the fail-loud check as "unparsed". RENAME TO / RENAME COLUMN
 // are not listed here: they change identity and are applied explicitly.
 const SHAPE_NEUTRAL_ALTER_CLAUSE_RE = new RegExp([
-    `ALTER COLUMN\\s+${IDENT}\\s+TYPE\\b`, // #1085 int/bigint-catchup fixes
+    `ALTER COLUMN\\s+${IDENT}\\s+TYPE\\b`, // int/bigint-catchup fixes
     `ALTER COLUMN\\s+${IDENT}\\s+(SET|DROP)\\s+NOT NULL\\b`,
     `ALTER COLUMN\\s+${IDENT}\\s+(SET DEFAULT\\b|DROP DEFAULT\\b)`,
     `(ADD|DROP)\\s+CONSTRAINT\\s+${IDENT}`,
@@ -269,7 +269,7 @@ function applyStatement(schema, statement, context) {
 // Reuses the real runner's file-discovery + statement-splitting
 // (loadMigrationsFromDir) instead of a second copy, so any future change to
 // sub-directory handling, numeric sort order, or the .sql filter can't
-// silently drift between the runner and this replay (#1522/9).
+// silently drift between the runner and this replay.
 export function replayMigrationsDir(migrationsDir) {
     const schema = new Map();
     const migrations = loadMigrationsFromDir(migrationsDir, expandDestructiveMarkers);

package/dist/db/schema-inspection.js

@@ -26,11 +26,10 @@ function resolveUnsafeClient(db) {
 //   await unsafePushTables(db, { events: eventsTable });
 export async function tableExists(db, fullyQualifiedName) {
     const unsafe = resolveUnsafeClient(db);
-    // quote_ident-Round-trip auf SQL-Seite: ohne Quotes folded postgres
-    // unquoted identifier case-insensitiv (myWidget → mywidget), während die
-    // generierte DDL den Namen via quoteIdent("myWidget") → "myWidget" case-
-    // preserved schreibt. quote_ident sorgt für identische Quotierung beidseits.
-    // Schema-qualifizierte Namen (`public.events`) werden per Split einzeln quotet.
+    // SQL-side quote_ident round-trip: unquoted PostgreSQL identifiers are folded case-insensitively
+    // (`myWidget` → `mywidget`), while generated DDL preserves the case via
+    // `quoteIdent("myWidget")` → `"myWidget"`. quote_ident keeps both sides quoted identically.
+    // Schema-qualified names (`public.events`) are quoted one component at a time after splitting.
     const dotIdx = fullyQualifiedName.indexOf(".");
     const [sql, params] = dotIdx >= 0
         ? [

package/dist/db/table-builder.d.ts

@@ -196,8 +196,7 @@ export type EntityRow<E extends EntityDefinition = EntityDefinition> = string ex
 export type { ExecutorManagedRunner, ExecutorManagedWriteCapability, Writable, WritableSchemaTable, WritableTable, } from "@cosmicdrift/kumiko-types/executor-brand";
 export type { EntityTenancy, TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 type EntityTableTenancy<E extends EntityDefinition> = [NonNullable<E["tenancy"]>] extends [never] ? "tenant" : [NonNullable<E["tenancy"]>] extends ["global"] ? "global" : "tenant";
-export type EntityTable<E extends EntityDefinition = EntityDefinition> = TableColumns<// biome-ignore lint/suspicious/noExplicitAny: drizzle's internal table-config stays generic; we layer typed columns on top via the intersection below.
-any> & BaseColumnsType<E> & SoftDeleteColumnsType & ColumnsForEntity<E["fields"]> & TenancyBrand<EntityTableTenancy<E>>;
+export type EntityTable<E extends EntityDefinition = EntityDefinition> = TableColumns & BaseColumnsType<E> & SoftDeleteColumnsType & ColumnsForEntity<E["fields"]> & TenancyBrand<EntityTableTenancy<E>>;
 export declare function buildBaseColumns(softDelete: boolean, idType?: "serial" | "uuid"): {
     id: ColumnBuilder<string> | ColumnBuilder<number>;
     tenantId: ColumnBuilder<string>;