@cosmicdrift/kumiko-framework 0.362.0 → 0.364.0

package/dist/db/index.js

@@ -27,4 +27,4 @@ export { diffReplayAgainstSnapshot, replayMigrationsDir, } from "./replay-migrat
 export { findCommentedDropTables, isRetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
-export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, } from "./tenant-db.js";
+export { castTenantRows, createSystemDbView, createTenantDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";

package/dist/db/lock-guard.d.ts

@@ -0,0 +1,4 @@
+import type { SessionUser } from "../engine/types/index.js";
+import type { LockGuardOption } from "./event-store-executor.js";
+export declare function isFrameworkSystemUser(user: SessionUser): boolean;
+export declare function isLockGuardBypassed(user: SessionUser, options: LockGuardOption | undefined): boolean;

package/dist/db/lock-guard.js

@@ -0,0 +1,14 @@
+import { SYSTEM_ROLE, SYSTEM_USER_ID } from "../engine/system-user.js";
+// Art. 17 erasure runs as the framework operator, not as a row owner; a
+// per-role ownership map can never cover it, and a silent deny means the
+// erasure never happened.
+export function isFrameworkSystemUser(user) {
+    return user.id === SYSTEM_USER_ID && user.roles.includes(SYSTEM_ROLE);
+}
+// Framework system writes that name a writePurpose (retention, erasure) are exempt:
+// statutory deletion must reach locked rows. The options are server-code only; no
+// request field is ever copied into them.
+export function isLockGuardBypassed(user, options) {
+    return (options?.unsafeSkipLockGuard === true ||
+        (options?.writePurpose !== undefined && isFrameworkSystemUser(user)));
+}

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;
     }
@@ -435,7 +437,7 @@ export function assertUniqueTableNames(metas) {
     const duplicates = [...counts].filter(([, count]) => count > 1);
     if (duplicates.length > 0) {
         throw new Error(duplicates
-            .map(([tableName, count]) => `ENTITY_METAS lists table "${tableName}" ${count} times — the migration diff would silently use only one definition. collectTableMetas(features) already includes every table a feature registers (r.storeTable, entities, projections); remove the hand-added meta for "${tableName}".`)
+            .map(([tableName, count]) => `ENTITY_METAS lists table "${tableName}" ${count} times — the migration diff would silently use only one definition. collectTableMetas(features) already includes every table a feature registers (r.storeTable, entities, projections); remove the duplicate entry for "${tableName}" (a hand-added meta, or two features registering the same table).`)
             .join("\n"));
     }
 }

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, hasBegin } 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,36 @@ 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) {
+    for (const candidate of [
+        db,
+        propertyOf(db, "$client"),
+        propertyOf(propertyOf(db, "session"), "client"),
+    ]) {
+        if (typeof propertyOf(candidate, "unsafe") !== "function")
+            continue;
+        const client = asRawClient(candidate);
+        if (hasBegin(client))
+            return client;
+    }
+    throw new Error("migrate-runner: db argument has no .unsafe() and .begin() (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 +234,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 +267,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.js

@@ -5,14 +5,14 @@ import { asRawClient } from "../query.js";
 // unassigned one. Both travel as strings — bigint/xid8 doesn't round-trip
 // through the driver as a JS number.
 export async function selectSnapshotXmin(db) {
-    const rows = (await asRawClient(db).unsafe(`SELECT pg_snapshot_xmin(pg_current_snapshot())::text AS xmin`));
+    const rows = await asRawClient(db).unsafe(`SELECT pg_snapshot_xmin(pg_current_snapshot())::text AS xmin`);
     const xmin = rows[0]?.xmin;
     if (xmin === undefined)
         throw new Error("selectSnapshotXmin: no row returned");
     return xmin;
 }
 export async function selectSnapshotXmax(db) {
-    const rows = (await asRawClient(db).unsafe(`SELECT pg_snapshot_xmax(pg_current_snapshot())::text AS xmax`));
+    const rows = await asRawClient(db).unsafe(`SELECT pg_snapshot_xmax(pg_current_snapshot())::text AS xmax`);
     const xmax = rows[0]?.xmax;
     if (xmax === undefined)
         throw new Error("selectSnapshotXmax: no row returned");
@@ -36,7 +36,7 @@ export async function lockEventConsumersShareMode(db) {
 // is still in flight, which pg_snapshot_xip being empty rules out, so the window
 // scan is skipped then.
 export async function selectEventIdHorizonWithMissingRanges(db) {
-    const rows = (await asRawClient(db).unsafe(`WITH a AS (
+    const rows = await asRawClient(db).unsafe(`WITH a AS (
        SELECT "last_processed_event_id" AS cursor, "pending_gaps" AS gaps
          FROM "kumiko_event_consumers"
         ORDER BY "last_processed_event_id" DESC
@@ -64,7 +64,7 @@ export async function selectEventIdHorizonWithMissingRanges(db) {
             r.t::text AS gap_to,
             r.x AS gap_xmax
        FROM b LEFT JOIN r ON true
-      ORDER BY r.f`));
+      ORDER BY r.f`);
     const first = rows[0];
     if (first === undefined)
         throw new Error("selectEventIdHorizonWithMissingRanges: no row returned");
@@ -89,7 +89,7 @@ export async function selectEventIdHorizonWithMissingRanges(db) {
 // subquery only ever affects the row this statement inserts.
 export async function insertConsumerIfAbsent(db, name, instanceId, startFrom = "beginning") {
     if (startFrom === "now") {
-        const existing = (await asRawClient(db).unsafe(`SELECT 1 FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2`, [name, instanceId]));
+        const existing = await asRawClient(db).unsafe(`SELECT 1 FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2`, [name, instanceId]);
         // skip: already registered — an existing cursor is never re-seeded.
         if (existing.length > 0)
             return;
@@ -116,18 +116,18 @@ export async function insertConsumerIfAbsent(db, name, instanceId, startFrom = "
 // cycle. The
 // type-only import keeps the parameter pinned to the "dead" literal.
 export async function selectProvablyIdleConsumerPairs(db, names, instanceIds, deadStatus) {
-    const rows = (await asRawClient(db).unsafe(`SELECT c."name" AS name, c."instance_id" AS instance_id
+    const rows = await asRawClient(db).unsafe(`SELECT c."name" AS name, c."instance_id" AS instance_id
      FROM "kumiko_event_consumers" c
      WHERE ("name", "instance_id") = ANY (SELECT * FROM unnest($1::text[], $2::text[]))
        AND "status" != $3
        AND "pending_gaps" = '[]'::jsonb
        AND NOT EXISTS (
          SELECT 1 FROM "kumiko_events" e WHERE e."id" > c."last_processed_event_id"
-       )`, [names, instanceIds, deadStatus]));
+       )`, [names, instanceIds, deadStatus]);
     return rows.map((r) => ({ name: r.name, instanceId: r.instance_id }));
 }
 export async function selectConsumerForUpdateSkipLocked(db, name, instanceId) {
-    const rows = (await asRawClient(db).unsafe(`SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE SKIP LOCKED`, [name, instanceId]));
+    const rows = await asRawClient(db).unsafe(`SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE SKIP LOCKED`, [name, instanceId]);
     return rows[0];
 }
 export async function markConsumerProcessing(db, name, instanceId) {
@@ -194,15 +194,15 @@ export async function updateConsumerDeliveryOutcome(db, name, instanceId, outcom
     ]);
 }
 export async function updateConsumerStatusReturning(db, name, instanceId, status) {
-    const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET "status" = $1, "attempts" = 0, "last_error" = NULL, "rearm_count" = 0, "updated_at" = now()
+    const rows = await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET "status" = $1, "attempts" = 0, "last_error" = NULL, "rearm_count" = 0, "updated_at" = now()
      WHERE "name" = $2 AND "instance_id" = $3
-     RETURNING *`, [status, name, instanceId]));
+     RETURNING *`, [status, name, instanceId]);
     return rows[0];
 }
 export async function advanceConsumerPastEventReturning(db, name, instanceId, eventId, 
 // Full list, including ids skipped over between the old cursor and eventId that were not visible yet.
 pendingGaps) {
-    const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
+    const rows = await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
        "last_processed_event_id" = $1,
        "status" = 'idle',
        "attempts" = 0,
@@ -213,7 +213,7 @@ pendingGaps) {
        "pending_gaps" = $4::text::jsonb,
        "updated_at" = now()
      WHERE "name" = $2 AND "instance_id" = $3
-     RETURNING *`, [eventId, name, instanceId, JSON.stringify(pendingGaps)]));
+     RETURNING *`, [eventId, name, instanceId, JSON.stringify(pendingGaps)]);
     return rows[0];
 }
 export async function resetConsumerForMspRebuild(db, name, instanceId) {
@@ -229,7 +229,7 @@ export async function resetConsumerForMspRebuild(db, name, instanceId) {
        "updated_at" = now()`, [name, instanceId]);
 }
 export async function selectConsumerForUpdate(db, name, instanceId) {
-    const rows = (await asRawClient(db).unsafe(`SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE`, [name, instanceId]));
+    const rows = await asRawClient(db).unsafe(`SELECT * FROM "kumiko_event_consumers" WHERE "name" = $1 AND "instance_id" = $2 FOR UPDATE`, [name, instanceId]);
     return rows[0];
 }
 export async function updateConsumerRebuildCursor(db, name, instanceId, lastProcessedEventId, pendingGaps) {
@@ -254,14 +254,14 @@ export async function markConsumerRebuildFailed(db, name, instanceId, errorMessa
 // so the caller can enforce a lifetime cap on automatic revivals; manual
 // restartConsumer()/enableConsumer() reset it back to 0.
 export async function rearmDeadConsumer(db, name, instanceId) {
-    const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
+    const rows = await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
        "status" = 'idle',
        "attempts" = 0,
        "last_error" = NULL,
        "rearm_count" = "rearm_count" + 1,
        "updated_at" = now()
      WHERE "name" = $1 AND "instance_id" = $2
-     RETURNING *`, [name, instanceId]));
+     RETURNING *`, [name, instanceId]);
     return rows[0];
 }
 // skipPoisonEvent's pending-gap branch: the poison is a pending id below the
@@ -269,7 +269,7 @@ export async function rearmDeadConsumer(db, name, instanceId) {
 // last_processed_event_id (advancing it here would be a regression — the
 // cursor already sits above this id).
 export async function removePendingGapReturning(db, name, instanceId, newPendingGaps) {
-    const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
+    const rows = await asRawClient(db).unsafe(`UPDATE "kumiko_event_consumers" SET
        "pending_gaps" = $1::text::jsonb,
        "status" = 'idle',
        "attempts" = 0,
@@ -278,6 +278,6 @@ export async function removePendingGapReturning(db, name, instanceId, newPending
        "last_failed_event_id" = NULL,
        "updated_at" = now()
      WHERE "name" = $2 AND "instance_id" = $3
-     RETURNING *`, [JSON.stringify(newPendingGaps), name, instanceId]));
+     RETURNING *`, [JSON.stringify(newPendingGaps), name, instanceId]);
     return rows[0];
 }

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

@@ -18,7 +18,7 @@ export async function insertRawFirstEvent(db, params) {
     ]);
 }
 export async function insertRawSubsequentEvent(db, params) {
-    const rows = (await asRawClient(db).unsafe(`INSERT INTO "kumiko_events" (
+    const rows = await asRawClient(db).unsafe(`INSERT INTO "kumiko_events" (
        aggregate_id, aggregate_type, tenant_id, version,
        type, event_version, payload, metadata, created_at, created_by
      )
@@ -41,7 +41,7 @@ export async function insertRawSubsequentEvent(db, params) {
         params.createdAt,
         params.createdBy,
         params.expectedVersion,
-    ]));
+    ]);
     return rows.length > 0;
 }
 export async function insertRawEventBatch(db, sqlValues, params) {
@@ -52,18 +52,18 @@ export async function insertRawEventBatch(db, sqlValues, params) {
      VALUES ${sqlValues}`, params);
 }
 export async function eventPredecessorExists(db, aggregateId, tenantId, version) {
-    const rows = (await asRawClient(db).unsafe(`SELECT EXISTS(
+    const rows = await asRawClient(db).unsafe(`SELECT EXISTS(
        SELECT 1 FROM "kumiko_events"
        WHERE aggregate_id = $1::uuid
          AND tenant_id = $2::uuid
          AND version = $3
-     ) AS present`, [aggregateId, tenantId, version]));
+     ) AS present`, [aggregateId, tenantId, version]);
     return rows[0]?.present === true;
 }
 export async function findExistingEventVersion(db, sqlInClause, params) {
-    const rows = (await asRawClient(db).unsafe(`SELECT aggregate_id, version FROM "kumiko_events"
+    const rows = await asRawClient(db).unsafe(`SELECT aggregate_id, version FROM "kumiko_events"
      WHERE (tenant_id, aggregate_id, version) IN (${sqlInClause})
-     LIMIT 1`, params));
+     LIMIT 1`, params);
     const row = rows[0];
     if (!row)
         return undefined;

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

@@ -7,9 +7,9 @@ import { asRawClient } from "../query.js";
 // Postgres' RETURNING clause has no DISTINCT keyword — dedupe the
 // per-event-row hits in-process instead of relying on invalid SQL.
 export async function transferEventRows(db, params) {
-    const rows = (await asRawClient(db).unsafe(`UPDATE "kumiko_events" SET "tenant_id" = $1 ` +
+    const rows = await asRawClient(db).unsafe(`UPDATE "kumiko_events" SET "tenant_id" = $1 ` +
         `WHERE "tenant_id" = $2 AND "aggregate_type" = $3 AND "aggregate_id" = ANY($4) ` +
-        `RETURNING "aggregate_id" AS id`, [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds]));
+        `RETURNING "aggregate_id" AS id`, [params.destinationTenantId, params.sourceTenantId, params.aggregateType, params.aggregateIds]);
     return [...new Set(rows.map((row) => row.id))];
 }
 // Snapshots are a pure read-performance cache (event-store/snapshot.ts) —

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

@@ -139,7 +139,7 @@ function duplicateIdempotencyKeyErrorOr(e) {
 }
 /** INSERT … SELECT … WHERE EXISTS predecessor — stays raw (typed builder can't express this). */
 export async function insertSubsequentEventRow(db, params) {
-    const rows = (await asRawClient(db).unsafe(`INSERT INTO "kumiko_events" (
+    const rows = await asRawClient(db).unsafe(`INSERT INTO "kumiko_events" (
        aggregate_id, aggregate_type, tenant_id, version,
        type, event_version, payload, metadata, created_by, created_at
      )
@@ -164,7 +164,7 @@ export async function insertSubsequentEventRow(db, params) {
         params.createdBy,
         params.expectedVersion,
         params.createdAt ?? null,
-    ]));
+    ]);
     return rows[0];
 }
 export async function selectStreamMaxVersion(db, aggregateId, tenantId) {

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

@@ -1,8 +1,8 @@
 import { asRawClient } from "../query.js";
 export async function readPiiBackfillState(db, fingerprint) {
-    const rows = (await asRawClient(db).unsafe(`SELECT "cursor_event_id"::text AS "cursor", "completed_at" IS NOT NULL AS "completed",
+    const rows = await asRawClient(db).unsafe(`SELECT "cursor_event_id"::text AS "cursor", "completed_at" IS NOT NULL AS "completed",
             "failed_event_ids"::text[] AS "failedEventIds"
-       FROM "kumiko_pii_backfill_state" WHERE "fingerprint" = $1`, [fingerprint]));
+       FROM "kumiko_pii_backfill_state" WHERE "fingerprint" = $1`, [fingerprint]);
     return rows[0] ?? null;
 }
 export async function persistPiiBackfillState(db, fingerprint, update) {

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

@@ -3,7 +3,7 @@ import { asRawClient, unsafeReadRetrying } from "../query.js";
  *  retrying an ambiguous write risks double-apply (#1358). Prefer {@link executeRawQueryRead}
  *  for SELECT-only paths. */
 export async function executeRawQuery(db, sqlText, params = []) {
-    return (await asRawClient(db).unsafe(sqlText, params));
+    return await asRawClient(db).unsafe(sqlText, params);
 }
 /** SELECT-only escape hatch with the #1163 closed-connection retry. Do not pass
  *  INSERT/UPDATE/DELETE — retry re-executes the statement. */

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

@@ -9,7 +9,7 @@ export async function truncateTablesRestartIdentity(db, tableNames) {
     await asRawClient(db).unsafe(`TRUNCATE ${quoted} RESTART IDENTITY CASCADE`);
 }
 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]));
+    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) {

package/dist/db/reference-data.js

@@ -1,11 +1,9 @@
-import { KUMIKO_COLUMNS_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { fetchOne, insertOne, updateMany } from "../db/query.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
+import { tableColumnsOf } from "./table-introspection.js";
 function hasColumn(table, field) {
-    const cols = table[KUMIKO_COLUMNS_SYMBOL];
-    if (typeof cols !== "object" || cols === null)
-        return false;
-    return field in cols;
+    const cols = tableColumnsOf(table);
+    return cols !== undefined && field in cols;
 }
 /**
  * Seed reference data at boot time.

package/dist/db/table-builder.js

@@ -1,15 +1,16 @@
 import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { toSnakeCase } from "../utils/case.js";
 import { assertUnreachable } from "../utils/index.js";
+import { columnHandleName } from "./table-introspection.js";
 export { toSnakeCase } from "../utils/case.js";
-import { bigint, boolean, decimalColumn, doublePrecision, index, instant, integer, jsonb, moneyAmount, table as pgTable, plainDate, serial, sql, text, uniqueIndex, uuid, } from "./dialect.js";
+import { bigint, boolean, decimalColumn, doublePrecision, index, instant, integer, isSqlExpression, jsonb, moneyAmount, table as pgTable, plainDate, serial, sql, text, uniqueIndex, uuid, } from "./dialect.js";
 // Partial-index predicate for soft-delete entities; table-builder and
 // entity-table-meta must render identical index definitions.
 export const SOFT_DELETE_LIVE_ROW_PREDICATE = `"is_deleted" = false`;
 // Shared by the CRUD executor and the parent-ref read-gate — a field's
 // declared column name if it has one, else its snake_case default.
 export function physicalColumnName(table, field) {
-    return table[field]?.name ?? toSnakeCase(field);
+    return columnHandleName(table, field) ?? toSnakeCase(field);
 }
 // Returns column(s) for a field. Most fields return a single entry,
 // money returns two (amount + currency).
@@ -281,7 +282,7 @@ export function declareGlobalTenancy(table) {
         ...meta,
         tenancy: "global",
     };
-    // @cast-boundary type-brand — TenancyBrand<"global"> is a phantom marker with no runtime representation.
+    // @cast-boundary phantom-brand — TenancyBrand<"global"> is a phantom marker with no runtime representation.
     return table;
 }
 export function buildEntityTable(entityName, entity, options) {
@@ -377,7 +378,8 @@ export function buildEntityTable(entityName, entity, options) {
             // entity.indexes[].where is now a SqlExpression (was drizzle SQL).
             // Pass through to the IndexBuilderWithCols.where()-API.
             if (def.where !== undefined) {
-                chain = chain.where(def.where);
+                if (isSqlExpression(def.where))
+                    chain = chain.where(def.where);
             }
             else if (def.unique === true && entity.softDelete === true) {
                 // Soft-deleted rows keep their value, so a full unique index would

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

@@ -0,0 +1,16 @@
+import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
+export declare function isEntityTableMeta(value: unknown): value is EntityTableMeta;
+export declare function asEntityTableMeta(table: unknown): EntityTableMeta | undefined;
+export declare function requireEntityTableMeta(table: unknown, tableName: string): EntityTableMeta;
+/** Physical table name from the unshadowable name symbol; undefined when absent. */
+export declare function schemaTableName(table: unknown): string | undefined;
+/** Name symbol first, then the canonical meta; "<unknown>" when neither resolves. */
+export declare function tableNameOf(table: unknown): string;
+/** Column-handle map stamped by table(); undefined for tables without one. */
+export declare function tableColumnsOf(table: unknown): Record<string, unknown> | undefined;
+/** SQL name carried by the enumerable column handle `table[field]`; undefined when the field has none. */
+export declare function columnHandleName(table: unknown, field: string): string | undefined;
+/** True when `table[field]` is defined, i.e. the table exposes a column handle (or plain value) for the field. */
+export declare function hasFieldProperty(table: unknown, field: string): boolean;
+/** SQL column name of a JS field via the column-handle map; undefined when not mapped. */
+export declare function columnSqlNameOf(table: unknown, field: string): string | undefined;