@cosmicdrift/kumiko-framework 0.362.0 → 0.363.0

package/dist/db/dialect.js

@@ -18,6 +18,7 @@
 // crashed on timestamptz writes without it (#1480).
 import { KUMIKO_COLUMNS_SYMBOL, KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+import { schemaTableName } from "./table-introspection.js";
 function isNumericPgType(t) {
     return t.startsWith("numeric(");
 }
@@ -76,9 +77,8 @@ function buildColumn(sqlName, pgType, opts) {
             return value ? "true" : "false";
         if (typeof value === "bigint")
             return value.toString();
-        if (value && typeof value === "object" && SQL_EXPR_BRAND in value) {
+        if (isSqlExpression(value))
             return value.text;
-        }
         if (typeof value === "function")
             return null; // function-defaults stay JS-side
         // Object/array → jsonb literal
@@ -256,6 +256,13 @@ export function primaryKey(opts) {
 // `{ kind: "sql-expr" }` from a client-controlled schema definition is never
 // spliced into SQL text anywhere.
 export const SQL_EXPR_BRAND = Symbol("sql-expr");
+export function isSqlExpression(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        SQL_EXPR_BRAND in value &&
+        "text" in value &&
+        typeof value.text === "string");
+}
 export function sql(strings, ...values) {
     const parts = [];
     const params = [];
@@ -263,7 +270,7 @@ export function sql(strings, ...values) {
         parts.push(strings[i] ?? "");
         if (i < values.length) {
             const v = values[i];
-            if (v && typeof v === "object" && SQL_EXPR_BRAND in v) {
+            if (isSqlExpression(v)) {
                 parts.push(v.text);
             }
             else {
@@ -279,6 +286,15 @@ sql.raw = (text) => ({
     params: [],
     [SQL_EXPR_BRAND]: true,
 });
+function isIndexOrPkList(opts) {
+    return Array.isArray(opts);
+}
+function isPrimaryKeyDescriptor(value) {
+    return "__pk" in value && value.__pk === true;
+}
+function isIndexBuilderWithCols(value) {
+    return "__index" in value && value.__index === true;
+}
 export function table(tableName, cols, optsFn) {
     // Finalise columns + build the column-handle map.
     const handles = {};
@@ -316,25 +332,24 @@ export function table(tableName, cols, optsFn) {
     if (optsFn) {
         const tHandle = handles;
         const opts = optsFn(tHandle);
-        const entries = Array.isArray(opts)
+        const entries = isIndexOrPkList(opts)
             ? opts.map((v, i) => [String(i), v])
             : Object.entries(opts);
         for (const [key, value] of entries) {
             if (!value)
                 continue;
-            if ("__pk" in value && value.__pk === true) {
+            if (isPrimaryKeyDescriptor(value)) {
                 compositePrimaryKey = {
                     name: value.name ?? `${tableName}_pk`,
                     columns: value.columns,
                 };
             }
-            else if ("__index" in value && value.__index === true) {
-                const idx = value;
+            else if (isIndexBuilderWithCols(value)) {
                 indexes.push({
-                    name: idx.name,
-                    columns: idx.columns,
-                    ...(idx.unique && { unique: true }),
-                    ...(idx.whereSql !== undefined && { whereSql: idx.whereSql }),
+                    name: value.name,
+                    columns: value.columns,
+                    ...(value.unique && { unique: true }),
+                    ...(value.whereSql !== undefined && { whereSql: value.whereSql }),
                 });
             }
             else {
@@ -367,8 +382,8 @@ export function extractTableName(table, context = "extractTableName") {
     if (typeof table !== "object" || table === null) {
         throw new Error(`${context}: table is not an object`);
     }
-    const name = table[KUMIKO_NAME_SYMBOL];
-    if (typeof name !== "string") {
+    const name = schemaTableName(table);
+    if (name === undefined) {
         throw new Error(`${context}: table missing kumiko:schema:Name symbol`);
     }
     return name;

package/dist/db/entity-table-from-registry.js

@@ -17,7 +17,7 @@ export function entityTableFromRegistry(registry, entityName, entity) {
             continue;
         if (projection.source !== entityName)
             continue;
-        // @cast-boundary registry-projection — ProjectionDefinition.table is the
+        // @cast-boundary projection-table — ProjectionDefinition.table is the
         // untyped table object every projection registrar accepts.
         return projection.table;
     }

package/dist/db/entity-table-meta.js

@@ -16,7 +16,7 @@
 //      hand-built path; app author owns tenant scoping / versioning. Prefer a
 //      `store_` table name — `read_` is reserved for managed projections (#1208/#1220).
 import { collectPiiEncryptedFields } from "../crypto/index.js";
-import { SQL_EXPR_BRAND } from "./dialect.js";
+import { isSqlExpression } from "./dialect.js";
 import { READ_MODEL_PREFIX, SOFT_DELETE_LIVE_ROW_PREDICATE, toSnakeCase, toTableName, } from "./table-builder.js";
 // Standard base columns for event-sourced read-model tables. Mirrors
 // `buildBaseColumns()` from table-builder.ts (drizzle variant).
@@ -226,9 +226,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
         // Unmanaged direct-write stores bypass validateRecordOwnedSubjects (it only walks
         // feature.entities), yet encryptForDirectWrite still keys recordOwned fields as
         // `record:<entity>:<id>`; forgetSubject requires a UUID, so the value could never be shredded.
-        const recordOwnedField = Object.entries(entity.fields).find(
-        // @cast-boundary schema-walk — PII flags live on the resolved field annotation
-        ([, field]) => field.recordOwned === true);
+        const recordOwnedField = Object.entries(entity.fields).find(([, field]) => "recordOwned" in field && field.recordOwned === true);
         if (recordOwnedField) {
             throw new Error(`deriveEntityTableMeta("${entityName}", { source: "unmanaged" }): field "${recordOwnedField[0]}" is recordOwned but the entity declares idType: "serial" — the record subject key is "record:${entityName}:<id>" and forgetSubject validates that id as a UUID, so this field could never be shredded. Use idType: "uuid", or give the field a different personal stance.`);
         }
@@ -302,7 +300,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
     // Explicitly declared indexes (EntityIndexDef). `def.where` is a
     // SqlExpression (`sql\`…\`` from @cosmicdrift/kumiko-framework/db) —
     // renderable via `.text`. Unknown where-shapes stay needsManualWhere.
-    for (const def of (entity.indexes ?? [])) {
+    for (const def of entity.indexes ?? []) {
         const cols = def.columns.map((fieldName) => fieldNameToSnake.get(fieldName) ?? toSnakeCase(fieldName));
         const suffix = def.unique === true ? "unique" : "idx";
         const indexName = def.name ?? `${tableName}_${cols.join("_")}_${suffix}`;
@@ -358,13 +356,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
 /** @deprecated Use {@link deriveEntityTableMeta} — the old name read as an unmanaged escape hatch (#1208). */
 export const buildEntityTableMeta = deriveEntityTableMeta;
 function sqlExpressionText(where) {
-    if (typeof where === "object" &&
-        where !== null &&
-        SQL_EXPR_BRAND in where &&
-        typeof where.text === "string") {
-        return where.text;
-    }
-    return undefined;
+    return isSqlExpression(where) ? where.text : undefined;
 }
 // Validates that a backing Drizzle table (declared via `r.entity(name, def,
 // { table })`) is a SUPERSET of the field-derived meta: every column the
@@ -423,7 +415,7 @@ export function defineUnmanagedTable(input) {
         }),
         source: "unmanaged",
         ...(input.tenancy === "global" && { tenancy: "global" }),
-        // @cast-boundary type-brand — TenancyBrand<T> is a phantom marker with no runtime representation.
+        // @cast-boundary phantom-brand — TenancyBrand<T> is a phantom marker with no runtime representation.
     };
 }
 function assertUnmanagedTableName(tableName, via) {

package/dist/db/event-store-executor-context.js

@@ -1,4 +1,3 @@
-import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { requestContext } from "../api/request-context.js";
 import { collectPiiEncryptedFields, configuredPiiSubjectKms, decryptPiiFieldValues, encryptPiiFieldValues, KeyErasedError, } from "../crypto/index.js";
 import { personalFieldsRekeyedOnOwnerTransition } from "../crypto/owner-transition-rekey.js";
@@ -12,6 +11,7 @@ import { rehydrateCompoundTypes } from "./compound-types.js";
 import { collectEncryptedFieldNames, decryptEntityFieldValues, encryptEntityFieldValues, logUndecryptableField, resolveEntityFieldEncryption, } from "./entity-field-encryption.js";
 import { constraintOf, isUniqueViolation } from "./pg-error.js";
 import { toSnakeCase } from "./table-builder.js";
+import { columnHandleName, schemaTableName } from "./table-introspection.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
 // Screen-Filter (Tier 2.7c) — Op-Mapping als Where-Operator. Boot-
 // Validator pinst field-Existenz + filterable + op-vs-Type-Compat.
@@ -312,7 +312,7 @@ export function buildExecutorContext(table, entity, options) {
         }
         // ownership has raw SQL — splice it into a raw query alongside the
         // idFilter + tenant-filter that TenantDb would have added.
-        const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+        const tableName = String(schemaTableName(table));
         const { whereParts, params } = buildRawIdWhere(db, idWhere, ownership);
         const sqlText = `SELECT * FROM "${tableName}" WHERE ${whereParts.join(" AND ")} LIMIT 1`;
         return [
@@ -323,7 +323,7 @@ export function buildExecutorContext(table, entity, options) {
     // TenantDb.fetchOne/readWhere add. idFilter only yields `id` and a boolean
     // `isDeleted`, so no null/IS NULL branch is needed.
     function buildRawIdWhere(db, idWhere, ownership) {
-        const colSql = (field) => `"${table[field]?.name ?? toSnakeCase(field)}"`;
+        const colSql = (field) => `"${columnHandleName(table, field) ?? toSnakeCase(field)}"`;
         const whereParts = [];
         const params = [];
         if (table["tenantId"] !== undefined && db.mode === "tenant") {
@@ -357,7 +357,7 @@ export function buildExecutorContext(table, entity, options) {
     async function loadDetailSnapshot(db, idWhere, ownership, streamTenantId, aggregateId) {
         if (ownership.kind === "empty")
             return { row: null, streamVersion: 0 };
-        const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+        const tableName = String(schemaTableName(table));
         const { whereParts, params } = buildRawIdWhere(db, idWhere, ownership);
         params.push(aggregateId, streamTenantId);
         const sqlText = `SELECT *, ${streamVersionSubquerySql(params.length - 1, params.length)} ` +
@@ -393,8 +393,8 @@ export function buildExecutorContext(table, entity, options) {
             }
         }
         const quote = (name) => `"${name.replace(/"/g, '""')}"`;
-        const columnOf = (field) => quote(table[field]?.name ?? toSnakeCase(field));
-        const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+        const columnOf = (field) => quote(columnHandleName(table, field) ?? toSnakeCase(field));
+        const tableName = String(schemaTableName(table));
         const selectCols = expectKeys.map((key) => `${columnOf(key)} AS ${quote(key)}`);
         const whereParts = [`${columnOf("id")} = $1`];
         const params = [id];

package/dist/db/event-store-executor-read.js

@@ -1,4 +1,4 @@
-import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { escapeLikePattern } from "../crypto/ciphertext-pattern.js";
 import { computeBlindIndex, configuredBlindIndexKey } from "../crypto/index.js";
 import { executeRawQueryRead } from "../db/queries/raw-sql.js";
@@ -14,6 +14,7 @@ import { hasSearchablePlaintext, isSensitiveLabelField } from "./entity-field-en
 import { buildFilterWhere, } from "./event-store-executor-context.js";
 import { buildParentRefClause } from "./parent-ref-clause.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
+import { schemaTableName } from "./table-introspection.js";
 import { tenantDbRunner } from "./tenant-db-runner.js";
 // The two read verbs (list/detail) of the event-store-executor. Split out
 // of event-store-executor.ts (#1005, Welle 2) — behavior-preserving
@@ -57,7 +58,7 @@ function toCursorSortText(value) {
     if (value instanceof Date)
         return value.toISOString();
     if (typeof value === "object") {
-        const tag = value[Symbol.toStringTag];
+        const tag = Reflect.get(value, Symbol.toStringTag);
         if (typeof tag === "string" && tag.startsWith("Temporal."))
             return String(value);
         return JSON.stringify(value);
@@ -154,9 +155,8 @@ function applyScreenFilter(table, colSql, whereSql, params, f) {
             });
             whereSql.push(`${colSql(field)} IN (${placeholders.join(", ")})`);
         }
-        else if (typeof value === "object") {
-            const valueObj = value;
-            if (valueObj["ne"] === null && Object.keys(valueObj).length === 1) {
+        else if (isPlainObject(value)) {
+            if (value["ne"] === null && Object.keys(value).length === 1) {
                 whereSql.push(`${colSql(field)} IS NOT NULL`);
                 continue;
             }
@@ -362,7 +362,7 @@ async function resolveReferenceMatches(descriptor, searchTerm, resolveEntity, db
         return undefined;
     }
     const targetTable = referenceTargetTable(descriptor.targetEntityName, targetEntity);
-    const targetTableName = String(targetTable[KUMIKO_NAME_SYMBOL]);
+    const targetTableName = String(schemaTableName(targetTable));
     if (!isSensitiveLabelField(targetEntity, descriptor.labelField)) {
         return resolveReferenceMatchesViaIlike(descriptor, searchTerm, targetEntity, targetTable, targetTableName, user, db);
     }
@@ -419,7 +419,7 @@ function buildReferenceSortExpr(outerTableName, ownColumnSql, descriptor, resolv
     const ownership = buildOwnershipClause(user, targetEntity.access?.read, targetTable);
     if (ownership.kind === "empty")
         return undefined;
-    const targetTableName = String(targetTable[KUMIKO_NAME_SYMBOL]);
+    const targetTableName = String(schemaTableName(targetTable));
     const labelCol = physicalColumnName(targetTable, descriptor.labelField);
     const tenantScoped = targetTable["tenantId"] !== undefined && db.mode === "tenant";
     const tenantCol = tenantScoped ? physicalColumnName(targetTable, "tenantId") : "";
@@ -456,7 +456,7 @@ export function createReadVerbs(ctx) {
             const runner = tenantDbRunner(db);
             const { limit, offset } = resolveListPagination(payload);
             const totalCount = payload.totalCount === true;
-            const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+            const tableName = String(schemaTableName(table));
             // H.2 — entity-level read ownership, AND-ed with the parent-ref
             // read-gate (join-row entities derive their visibility from a host
             // row's own read path — see db/parent-ref-clause.ts). Decide before
@@ -709,7 +709,7 @@ export function createReadVerbs(ctx) {
             };
         },
         async detail(payload, user, db, options) {
-            const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+            const tableName = String(schemaTableName(table));
             // H.2 — ownership check, AND-ed with the parent-ref read-gate (see
             // db/parent-ref-clause.ts). `empty` → the user can never see this row
             // regardless of its id. Return null (same shape as "not found", so a

package/dist/db/migrate-generator.js

@@ -15,6 +15,7 @@
 // uncommenten + ggf. Data-Backup-Schritt vorlauf einfügen. Default:
 // niemals automatisch droppen.
 import { readFileSync, writeFileSync } from "node:fs";
+import { errorCodeOf, isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { compareByCodepoint } from "../utils/index.js";
 import { renderIndex, renderTableDdl } from "./render-ddl.js";
 import { findRetiredTableDrops } from "./retired-framework-tables.js";
@@ -36,13 +37,14 @@ export function loadSnapshotJson(path) {
     try {
         const text = readFileSync(path, "utf8");
         const parsed = JSON.parse(text);
-        if (parsed.version !== SNAPSHOT_VERSION) {
-            throw new Error(`Snapshot at ${path} has version ${String(parsed.version)}, expected ${SNAPSHOT_VERSION}`);
+        const version = isPlainObject(parsed) ? parsed["version"] : undefined;
+        if (version !== SNAPSHOT_VERSION) {
+            throw new Error(`Snapshot at ${path} has version ${String(version)}, expected ${SNAPSHOT_VERSION}`);
         }
         return parsed;
     }
     catch (err) {
-        if (err.code === "ENOENT")
+        if (errorCodeOf(err) === "ENOENT")
             return null;
         throw err;
     }

package/dist/db/migrate-runner.js

@@ -16,25 +16,8 @@
 import { createHash } from "node:crypto";
 import { existsSync, readdirSync, readFileSync } from "node:fs";
 import { join } from "node:path";
-// Adapter: extract raw postgres-js client from drizzle DbConnection,
-// or use Bun.sql instance directly. Either way `.unsafe()` is the
-// runtime call.
-function rawClient(db) {
-    const dbAny = db;
-    if (typeof dbAny["unsafe"] === "function" && typeof dbAny["begin"] === "function") {
-        return dbAny;
-    }
-    const $client = dbAny["$client"];
-    if ($client && typeof $client["unsafe"] === "function") {
-        return $client;
-    }
-    const session = dbAny["session"];
-    const sessionClient = session?.["client"];
-    if (sessionClient && typeof sessionClient["unsafe"] === "function") {
-        return sessionClient;
-    }
-    throw new Error("migrate-runner: db argument has no .unsafe() (need Bun.SQL or drizzle DbConnection)");
-}
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { asRawClient } from "../bun-db/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).
@@ -181,24 +164,35 @@ export function readMigrationSqlTexts(dir) {
         .sort()
         .map((file) => readFileSync(join(dir, file), "utf8"));
 }
+// Stricter than asRawClient on purpose: a direct handle must also offer
+// begin(), because runMigrations wraps every file in a transaction. Handles
+// without it fall through to the drizzle wrappers and otherwise fail here,
+// before any SQL runs, with the migrate-runner message.
+function migrationClient(db) {
+    const hasDirectClient = typeof propertyOf(db, "unsafe") === "function" && typeof propertyOf(db, "begin") === "function";
+    if (hasDirectClient)
+        return asRawClient(db);
+    for (const wrapped of [
+        propertyOf(db, "$client"),
+        propertyOf(propertyOf(db, "session"), "client"),
+    ]) {
+        if (typeof propertyOf(wrapped, "unsafe") === "function")
+            return asRawClient(wrapped);
+    }
+    throw new Error("migrate-runner: db argument has no .unsafe() (need Bun.SQL or drizzle DbConnection)");
+}
 // Raw-SQL via postgres-js or Bun.sql .unsafe() — same shape for both.
 async function executeRaw(db, sqlText) {
-    await rawClient(db).unsafe(sqlText);
+    await migrationClient(db).unsafe(sqlText);
 }
 export async function fetchAppliedMigrations(db) {
-    const result = await rawClient(db).unsafe(`SELECT id, checksum FROM "_kumiko_migrations" ORDER BY id`);
+    const result = await migrationClient(db).unsafe(`SELECT id, checksum FROM "_kumiko_migrations" ORDER BY id`);
     const rows = Array.isArray(result) ? result : [];
     const applied = [];
     for (const row of rows) {
-        if (typeof row === "object" &&
-            row !== null &&
-            typeof row.id === "string" &&
-            typeof row.checksum === "string") {
-            applied.push({
-                id: row.id,
-                checksum: row.checksum,
-            });
-        }
+        const { id, checksum } = row;
+        if (typeof id === "string" && typeof checksum === "string")
+            applied.push({ id, checksum });
     }
     return applied;
 }
@@ -239,13 +233,15 @@ export async function runMigrations(db, migrations) {
             // Apply file content + INSERT tracking-row in einer TX. Wenn ein
             // Statement bricht, Rollback inkl. Tracking-Row → kein partial-apply
             // stuck in den books.
-            const client = rawClient(db);
+            const client = migrationClient(db);
             await client.begin(async (tx) => {
-                const txClient = tx;
                 for (const stmt of m.statements) {
-                    await txClient.unsafe(stmt);
+                    await tx.unsafe(stmt);
                 }
-                await txClient.unsafe(`INSERT INTO "_kumiko_migrations" ("id", "checksum") VALUES ($1, $2)`, [m.id, m.checksum]);
+                await tx.unsafe(`INSERT INTO "_kumiko_migrations" ("id", "checksum") VALUES ($1, $2)`, [
+                    m.id,
+                    m.checksum,
+                ]);
             });
             appliedIds.push(m.id);
         }
@@ -270,7 +266,7 @@ export async function baselineMigrations(db, migrations) {
     const applied = new Set((await fetchAppliedMigrations(db)).map((a) => a.id));
     const marked = [];
     const alreadyTracked = [];
-    const client = rawClient(db);
+    const client = migrationClient(db);
     for (const m of migrations) {
         if (applied.has(m.id)) {
             alreadyTracked.push(m.id);

package/dist/db/parent-ref-clause.js

@@ -1,14 +1,14 @@
-import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { buildOwnershipClause } from "../engine/ownership.js";
 import { SYSTEM_TENANT_ID, UUID_SHAPE_PATTERN } from "../engine/types/identifiers.js";
 import { buildEntityTable, physicalColumnName } from "./table-builder.js";
+import { schemaTableName } from "./table-introspection.js";
 const candidateStaticsCache = new WeakMap();
 function candidateStaticsFor(candidateName, candidate) {
     const cached = candidateStaticsCache.get(candidate);
     if (cached)
         return cached;
     const table = buildEntityTable(candidateName, candidate);
-    const tableName = String(table[KUMIKO_NAME_SYMBOL]);
+    const tableName = String(schemaTableName(table));
     const statics = {
         table,
         tableName,

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

@@ -49,6 +49,7 @@
 // plaintext); the next snapshotting load recreates them. AFTER a run, rebuild the
 // affected projections — applyEntityEvent materializes ciphertext AND the
 // blind-index columns, which keeps equality lookups (login by email) alive.
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { asRawClient } from "../../bun-db/index.js";
 import { quoteIdent } from "../../crypto/ciphertext-pattern.js";
 import { configuredEventPiiCatalog } from "../../crypto/event-pii.js";
@@ -127,6 +128,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
     const { entityTargets, eventCatalog } = collectPiiTargets(registry);
     const aggregateTypes = [...entityTargets.keys()];
     const catalogTypes = [...eventCatalog.keys()];
+    const failures = [];
     const result = {
         scannedEvents: 0,
         updatedEvents: 0,
@@ -136,7 +138,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
         ownerFromProjection: 0,
         erasedUnresolvable: 0,
         deletedSnapshots: 0,
-        failures: [],
+        failures,
     };
     const emptyBatch = () => ({
         ...result,
@@ -148,7 +150,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
     });
     if (aggregateTypes.length === 0 && catalogTypes.length === 0)
         return emptyBatch();
-    const rows = (await (options.eventIds
+    const rows = await (options.eventIds
         ? raw.unsafe(`SELECT "id", "aggregate_id", "aggregate_type", "tenant_id", "type", "payload"
            FROM "kumiko_events"
           WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" = ANY($3::bigint[])
@@ -157,7 +159,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
            FROM "kumiko_events"
           WHERE ("aggregate_type" = ANY($1::text[]) OR "type" = ANY($2::text[])) AND "id" > $3::bigint
           ORDER BY "id" ASC
-          LIMIT $4`, [aggregateTypes, catalogTypes, String(options.afterEventId ?? 0), batchSize])));
+          LIMIT $4`, [aggregateTypes, catalogTypes, String(options.afterEventId ?? 0), batchSize]));
     const last = rows[rows.length - 1];
     if (last === undefined)
         return emptyBatch();
@@ -203,7 +205,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
     }
     // Snapshots may cache the plaintext state of touched aggregates.
     if (!options.dryRun && touchedAggregates.size > 0) {
-        const deleted = (await raw.unsafe(`DELETE FROM "kumiko_snapshots" WHERE "aggregate_id" = ANY($1::uuid[]) RETURNING "aggregate_id"`, [[...touchedAggregates]]));
+        const deleted = await raw.unsafe(`DELETE FROM "kumiko_snapshots" WHERE "aggregate_id" = ANY($1::uuid[]) RETURNING "aggregate_id"`, [[...touchedAggregates]]);
         result.deletedSnapshots = deleted.length;
     }
     return {
@@ -222,7 +224,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
         // Pre-KMS forgets left no key tombstone — the *.forgotten event on the
         // stream is the only durable marker. aggregate_id doubles as the user id
         // for user-subject lookups.
-        const forgottenRows = (await raw.unsafe(`SELECT DISTINCT "aggregate_id" FROM "kumiko_events" WHERE "type" LIKE '%.forgotten'`));
+        const forgottenRows = await raw.unsafe(`SELECT DISTINCT "aggregate_id" FROM "kumiko_events" WHERE "type" LIKE '%.forgotten'`);
         scanCache.forgottenAggregates = new Set(forgottenRows.map((r) => r.aggregate_id));
         return scanCache.forgottenAggregates;
     }
@@ -248,7 +250,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
             // aborts the surrounding transaction (25P02). Entity never mounted/rebuilt
             // → stage 3 still gets a chance; this batch just contributes no owners.
             if (await tableExists(db, `public.${tableName}`)) {
-                const projectionRows = (await raw.unsafe(`SELECT * FROM ${quoteIdent(tableName)} WHERE "id" = ANY($1::uuid[])`, [[...ids]]));
+                const projectionRows = await raw.unsafe(`SELECT * FROM ${quoteIdent(tableName)} WHERE "id" = ANY($1::uuid[])`, [[...ids]]);
                 for (const projectionRow of projectionRows) {
                     const id = projectionRow["id"];
                     if (typeof id === "string") {
@@ -273,7 +275,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
             erasedUnresolvable: 0,
         };
         const payload = structuredClone(row.payload);
-        const tenantId = row.tenant_id; // @cast-boundary db-read — tenant_id column is the branded TenantId
+        const tenantId = row.tenant_id;
         const catalogFields = eventCatalog.get(row.type);
         if (catalogFields) {
             for (const [field, spec] of Object.entries(catalogFields)) {
@@ -443,7 +445,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
     async function loadDestroyedTenants() {
         if (scanCache.destroyedTenants)
             return scanCache.destroyedTenants;
-        const rows = (await raw.unsafe(`SELECT id::text AS id FROM read_tenants WHERE destroyed_at IS NOT NULL`));
+        const rows = await raw.unsafe(`SELECT id::text AS id FROM read_tenants WHERE destroyed_at IS NOT NULL`);
         scanCache.destroyedTenants = new Set(rows.map((r) => r.id));
         return scanCache.destroyedTenants;
     }
@@ -557,7 +559,7 @@ function isLifecycleEventOf(eventType, aggregateType) {
     if (!eventType.startsWith(`${aggregateType}.`))
         return false;
     const verb = eventType.slice(aggregateType.length + 1);
-    return LIFECYCLE_VERBS.includes(verb);
+    return isOneOf(LIFECYCLE_VERBS, verb);
 }
 // created events carry the fields flat; updated carries { changes, previous };
 // deleted/forgotten/restored carry { previous }. Returned sections are the

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

@@ -5,6 +5,6 @@ export async function acquireEsOpsAdvisoryLock(db) {
     await asRawClient(db).unsafe(`SELECT pg_advisory_xact_lock($1)`, [ES_OPS_ADVISORY_LOCK_KEY]);
 }
 export async function esOperationExists(db, operationId) {
-    const rows = (await asRawClient(db).unsafe(`SELECT 1 FROM "kumiko_es_operations" WHERE id = $1 LIMIT 1`, [operationId]));
+    const rows = await asRawClient(db).unsafe(`SELECT 1 FROM "kumiko_es_operations" WHERE id = $1 LIMIT 1`, [operationId]);
     return rows.length > 0;
 }

package/dist/db/queries/event-consumer.d.ts

@@ -13,7 +13,7 @@ export declare function selectProvablyIdleConsumerPairs(db: AnyDb, names: readon
     readonly name: string;
     readonly instanceId: string;
 }>>;
-export declare function selectConsumerForUpdateSkipLocked(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
+export declare function selectConsumerForUpdateSkipLocked<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string): Promise<TRow | undefined>;
 export declare function markConsumerProcessing(db: AnyDb, name: string, instanceId: string): Promise<void>;
 export declare function recordConsumerPassFailure(db: AnyDb, name: string, instanceId: string, errorMessage: string, cursorBeforePass?: bigint): Promise<void>;
 export type ConsumerDeliveryOutcome = {
@@ -26,11 +26,11 @@ export type ConsumerDeliveryOutcome = {
     readonly failedEventId: bigint | null;
 };
 export declare function updateConsumerDeliveryOutcome(db: AnyDb, name: string, instanceId: string, outcome: ConsumerDeliveryOutcome): Promise<void>;
-export declare function updateConsumerStatusReturning(db: AnyDb, name: string, instanceId: string, status: "idle" | "disabled"): Promise<Record<string, unknown> | undefined>;
-export declare function advanceConsumerPastEventReturning(db: AnyDb, name: string, instanceId: string, eventId: bigint, pendingGaps: readonly PendingGapEntry[]): Promise<Record<string, unknown> | undefined>;
+export declare function updateConsumerStatusReturning<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string, status: "idle" | "disabled"): Promise<TRow | undefined>;
+export declare function advanceConsumerPastEventReturning<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string, eventId: bigint, pendingGaps: readonly PendingGapEntry[]): Promise<TRow | undefined>;
 export declare function resetConsumerForMspRebuild(db: AnyDb, name: string, instanceId: string): Promise<void>;
-export declare function selectConsumerForUpdate(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
+export declare function selectConsumerForUpdate<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string): Promise<TRow | undefined>;
 export declare function updateConsumerRebuildCursor(db: AnyDb, name: string, instanceId: string, lastProcessedEventId: bigint, pendingGaps: readonly PendingGapEntry[]): Promise<void>;
 export declare function markConsumerRebuildFailed(db: AnyDb, name: string, instanceId: string, errorMessage: string): Promise<void>;
-export declare function rearmDeadConsumer(db: AnyDb, name: string, instanceId: string): Promise<Record<string, unknown> | undefined>;
-export declare function removePendingGapReturning(db: AnyDb, name: string, instanceId: string, newPendingGaps: readonly PendingGapEntry[]): Promise<Record<string, unknown> | undefined>;
+export declare function rearmDeadConsumer<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string): Promise<TRow | undefined>;
+export declare function removePendingGapReturning<TRow = Record<string, unknown>>(db: AnyDb, name: string, instanceId: string, newPendingGaps: readonly PendingGapEntry[]): Promise<TRow | undefined>;