@cosmicdrift/kumiko-framework 0.362.0 → 0.363.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.d.ts

@@ -56,5 +56,5 @@ export type PendingIdRange = {
     readonly from: bigint;
     readonly to: bigint;
 };
-export declare function selectPendingAndNewEventRows(db: AnyDb, cursor: bigint, pendingRanges: readonly PendingIdRange[], batchSize: number): Promise<ReadonlyArray<Record<string, unknown>>>;
+export declare function selectPendingAndNewEventRows<TRow = Record<string, unknown>>(db: AnyDb, cursor: bigint, pendingRanges: readonly PendingIdRange[], batchSize: number): Promise<ReadonlyArray<TRow>>;
 export declare function selectSmallestVisibleIdInRanges(db: AnyDb, pendingRanges: readonly PendingIdRange[]): Promise<bigint | null>;

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/projection-rebuild.d.ts

@@ -1,6 +1,6 @@
 import type { AnyDb } from "../query.js";
 export declare function markProjectionRebuilding(db: AnyDb, projectionName: string): Promise<void>;
-export declare function selectEventsForProjectionRebuildBatch(db: AnyDb, aggregateTypes: readonly string[], eventTypes: readonly string[], afterId: bigint, limit: number): Promise<ReadonlyArray<Record<string, unknown>>>;
+export declare function selectEventsForProjectionRebuildBatch<TRow = Record<string, unknown>>(db: AnyDb, aggregateTypes: readonly string[], eventTypes: readonly string[], afterId: bigint, limit: number): Promise<ReadonlyArray<TRow>>;
 export declare function countSubscribedEvents(db: AnyDb, aggregateTypes: readonly string[], eventTypes: readonly string[]): Promise<bigint>;
 export declare function finalizeProjectionRebuild(db: AnyDb, projectionName: string, lastProcessedEventId: bigint): Promise<void>;
 export declare function markProjectionRebuildFailed(db: AnyDb, projectionName: string, errorMessage: string): Promise<void>;

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;

package/dist/db/table-introspection.js

@@ -0,0 +1,76 @@
+import { KUMIKO_COLUMNS_SYMBOL, KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
+// table() spreads column handles onto the table object as enumerable props, so
+// an entity field named `source`/`columns`/`tableName`/… shadows the matching
+// meta key. The symbol-keyed slots are the only collision-safe source; plain
+// metas (deriveEntityTableMeta / defineUnmanagedTable) carry no handle spread
+// and are unshadowable by their structural shape.
+export function isEntityTableMeta(value) {
+    return (typeof value === "object" &&
+        value !== null &&
+        "tableName" in value &&
+        typeof value.tableName === "string" &&
+        "columns" in value &&
+        Array.isArray(value.columns) &&
+        "indexes" in value &&
+        Array.isArray(value.indexes) &&
+        "source" in value &&
+        (value.source === "managed" || value.source === "unmanaged"));
+}
+export function asEntityTableMeta(table) {
+    if (typeof table !== "object" || table === null)
+        return undefined;
+    if (KUMIKO_META_SYMBOL in table && isEntityTableMeta(table[KUMIKO_META_SYMBOL])) {
+        return table[KUMIKO_META_SYMBOL];
+    }
+    return isEntityTableMeta(table) ? table : undefined;
+}
+export function requireEntityTableMeta(table, tableName) {
+    const meta = asEntityTableMeta(table);
+    if (!meta) {
+        throw new Error(`${tableName}: table carries no EntityTableMeta — built via table()?`);
+    }
+    return meta;
+}
+/** Physical table name from the unshadowable name symbol; undefined when absent. */
+export function schemaTableName(table) {
+    if (typeof table !== "object" || table === null || !(KUMIKO_NAME_SYMBOL in table)) {
+        return undefined;
+    }
+    const name = table[KUMIKO_NAME_SYMBOL];
+    return typeof name === "string" ? name : undefined;
+}
+/** Name symbol first, then the canonical meta; "<unknown>" when neither resolves. */
+export function tableNameOf(table) {
+    return schemaTableName(table) ?? asEntityTableMeta(table)?.tableName ?? "<unknown>";
+}
+/** Column-handle map stamped by table(); undefined for tables without one. */
+export function tableColumnsOf(table) {
+    if (typeof table !== "object" || table === null || !(KUMIKO_COLUMNS_SYMBOL in table)) {
+        return undefined;
+    }
+    const columns = table[KUMIKO_COLUMNS_SYMBOL];
+    return isPlainObject(columns) ? columns : undefined;
+}
+/** SQL name carried by the enumerable column handle `table[field]`; undefined when the field has none. */
+export function columnHandleName(table, field) {
+    if (!isPlainObject(table))
+        return undefined;
+    const handle = table[field];
+    if (!isPlainObject(handle))
+        return undefined;
+    const name = handle["name"];
+    return typeof name === "string" ? name : undefined;
+}
+/** True when `table[field]` is defined, i.e. the table exposes a column handle (or plain value) for the field. */
+export function hasFieldProperty(table, field) {
+    return isPlainObject(table) && table[field] !== undefined;
+}
+/** SQL column name of a JS field via the column-handle map; undefined when not mapped. */
+export function columnSqlNameOf(table, field) {
+    const handle = tableColumnsOf(table)?.[field];
+    if (!isPlainObject(handle))
+        return undefined;
+    const name = handle["name"];
+    return typeof name === "string" ? name : undefined;
+}

package/dist/db/tenant-db.d.ts

@@ -1,6 +1,6 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
 import type { EscapeHatchDeclaration, EscapeHatchReporter, EscapeHatchTarget } from "@cosmicdrift/kumiko-types/handlers";
-import { type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
+import type { SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { type TenantDb, type TenantDbMode, type UncheckedSystemDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { asRawClient } from "../db/query.js";
 import type { EntityDefinition } from "../engine/types/fields.js";
@@ -8,6 +8,7 @@ import { type TenantId } from "../engine/types/identifiers.js";
 import type { Registry } from "../engine/types/index.js";
 import { type Meter, type Tracer } from "../observability/index.js";
 import type { DbRunner } from "./connection.js";
+import { tableNameOf } from "./table-introspection.js";
 type Table = SchemaTable;
 export { SYSTEM_SCOPE_CHECK_BRAND, type TenantDb, type TenantDbMode, type UncheckedSystemDb, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 export declare function assertPersonalDataWrite(db: TenantDb, tableName: string, keys: readonly string[], entity: EntityDefinition): void;
@@ -16,7 +17,7 @@ export declare function withSystemDbUnsafeRawGrant(systemDb: UncheckedSystemDb,
 export declare function createUncheckedSystemDb(db: TenantDb, dbOutsideTransaction?: TenantDb, report?: EscapeHatchReporter): UncheckedSystemDb;
 export declare function createSystemDbView(db: TenantDb, dbOutsideTransaction?: TenantDb, report?: EscapeHatchReporter): UncheckedSystemDb;
 export declare function castTenantRows<T>(rows: readonly Record<string, unknown>[]): readonly T[];
-export declare function tableNameOf(table: Table | EntityTableMeta): string;
+export { tableNameOf };
 export declare function hasTenantColumn(table: Table | EntityTableMeta): boolean;
 export type TenantDbGrants = {
     readonly globalWrites?: EscapeHatchDeclaration;

package/dist/db/tenant-db.js

@@ -1,10 +1,10 @@
-import { KUMIKO_NAME_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { asEntityTableMeta, asRawClient, aggregateWhere as bunAggregateWhere, countWhere as bunCountWhere, deleteMany as bunDeleteMany, fetchOne as bunFetchOne, insertOne as bunInsertOne, selectMany as bunSelectMany, updateMany as bunUpdateMany, runInNewTransaction, } from "../db/query.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
 import { emitDbQuery, fallbackEscapeHatchReporter, registerStandardMetrics, } from "../observability/index.js";
 import { bindProjectionRegistry, projectionRegistryOf } from "./projection-registry-binding.js";
+import { hasFieldProperty, tableNameOf } from "./table-introspection.js";
 import { bindTenantDbRunner, tenantDbRunner } from "./tenant-db-runner.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 const declaredUnsafeRawRunners = new WeakMap();
@@ -53,7 +53,6 @@ function boundRunner(runner, gate, projectionRegistry) {
             }
             return value.bind(target);
         },
-        // @cast-boundary proxy-erasure — Proxy<object> re-tags as the wrapped DbRunner shape.
     });
     if (gate)
         runnerPersonalDataGates.set(proxy, gate);
@@ -225,12 +224,7 @@ export function createSystemDbView(db, dbOutsideTransaction, report = fallbackEs
 export function castTenantRows(rows) {
     return rows;
 }
-export function tableNameOf(table) {
-    const sym = table[KUMIKO_NAME_SYMBOL];
-    if (typeof sym === "string")
-        return sym;
-    return asEntityTableMeta(table)?.tableName ?? "<unknown>";
-}
+export { tableNameOf };
 // A grant is only real when its reason is non-empty — `{ reason: "" }` must not silently unlock it.
 function hasGrant(decl) {
     return decl !== undefined && decl.reason.trim().length > 0;
@@ -247,7 +241,7 @@ export function hasTenantColumn(table) {
     const meta = asEntityTableMeta(table);
     if (meta)
         return meta.columns.some((c) => c.name === "tenant_id");
-    return table["tenantId"] !== undefined;
+    return hasFieldProperty(table, "tenantId");
 }
 const unsafeRawRebinders = new WeakMap();
 // Rebinds tenantDb's unsafeRaw grant (e.g. a hook's own escapeHatch); inputs not built by
@@ -475,7 +469,7 @@ export function createTenantDb(db, tenantId, mode = "tenant", tracer, meter, sig
                 report("global-write", globalWriteReason());
                 return withDbSpan("delete", table, async () => bunDeleteMany(db, table, where));
             },
-            // @cast-boundary type-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
+            // @cast-boundary phantom-brand — GlobalWrites is only present in the type when TTable is not ExecutorOnly; the object above always carries the methods.
         };
     }
     function grantedUnsafeRawRunner(declaredStepReason) {

package/dist/derivatives/variant-key.js

@@ -1,4 +1,5 @@
 import { createHash } from "node:crypto";
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 // Deterministic JSON: object keys sorted (recursively), `undefined` values
 // dropped, arrays keep their order. Two specs that are semantically equal
 // (same keys, different insertion order; explicit `undefined` vs. omitted)
@@ -7,7 +8,7 @@ export function canonicalJson(value) {
     if (Array.isArray(value)) {
         return `[${value.map((entry) => canonicalJson(entry)).join(",")}]`;
     }
-    if (value !== null && typeof value === "object") {
+    if (isPlainObject(value)) {
         const entries = Object.entries(value)
             .filter(([, v]) => v !== undefined)
             .sort(([a], [b]) => (a < b ? -1 : a > b ? 1 : 0));

package/dist/engine/boot-validator/entity-list-screens.js

@@ -15,7 +15,7 @@ function hasFilterableFields(feature, entityName) {
     const entity = entities[entityName];
     if (!entity)
         return false;
-    return Object.values(entity.fields).some((raw) => raw.filterable === true);
+    return Object.values(entity.fields).some((raw) => "filterable" in raw && raw.filterable === true);
 }
 function hasEntityEditDetail(feature, entityName) {
     return Object.values(feature.screens).some((s) => s.type === "entityEdit" && s.entity === entityName);

package/dist/engine/boot-validator/pii-retention.js

@@ -48,7 +48,7 @@ function validateWriteOnlyField(featureName, entityName, fieldName, field) {
     const where = `[Feature ${featureName}] Field "${fieldName}" on entity "${entityName}"`;
     if (field.type === "embedded") {
         for (const [subName, subField] of Object.entries(field.schema)) {
-            if (subField.writeOnly === true) {
+            if ("writeOnly" in subField && subField.writeOnly === true) {
                 // @cast-boundary schema-walk
                 throw new Error(`${where} declares writeOnly on embedded sub-field "${subName}" — writeOnly is only supported on top-level text fields.`);
             }

package/dist/engine/boot-validator/screens.js

@@ -6,6 +6,7 @@
 import { resolveActionIcon } from "@cosmicdrift/kumiko-types/action-icon";
 import { NO_WIDGET_FIELD_TYPES, optionsQueryFieldRefs, SELECT_OPTION_TONES, } from "@cosmicdrift/kumiko-types/fields";
 import { NAV_ICON_KEYS } from "@cosmicdrift/kumiko-types/nav-icon";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { rowMetaFieldNames } from "../../db/table-builder.js";
 import { REFERENCE_LOOKUP_SOURCES } from "../../ui-types/list-row-meta.js";
 import { isEncryptedAtRest } from "../config-helpers.js";
@@ -275,7 +276,7 @@ function validateWizardLayout(featureName, screenId, screenType, layout, feature
 // for an unregistered key instead of crashing — this check makes the same
 // gap fail loudly at boot instead of silently at render.
 function isRegisteredIcon(icon) {
-    return NAV_ICON_KEYS.includes(icon);
+    return isOneOf(NAV_ICON_KEYS, icon);
 }
 export function validateActionHasIcon(featureName, screenId, screenType, context, action) {
     const resolved = resolveActionIcon(action.id, action.icon);

package/dist/engine/changeset-changes.js

@@ -1,6 +1,6 @@
-import { validateChangelog } from "./feature-changelog.js";
+import { isOneOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { CHANGELOG_TYPES, validateChangelog } from "./feature-changelog.js";
 const BLOCK_RE = /<!--\s*kumiko-changes\s*\n([\s\S]*?)\n\s*-->/g;
-const TYPE_VALUES = new Set(["breaking", "improvement", "fix"]);
 const KEY_RE = /^(feature|type|title|detail|migration|codemod|manualAfterCodemod):(?:\s(.*))?$/;
 function requiredField(fields, field, source) {
     const value = fields.get(field)?.trim();
@@ -95,7 +95,7 @@ function parseManualAfterCodemod(fields, source) {
 function buildChange(fields, prose, source) {
     const feature = requiredField(fields, "feature", source);
     const rawType = requiredField(fields, "type", source);
-    if (!TYPE_VALUES.has(rawType)) {
+    if (!isOneOf(CHANGELOG_TYPES, rawType)) {
         throw new Error(`${source}: kumiko-changes type must be breaking, improvement, or fix`);
     }
     const { title, detail } = resolveTitleAndDetail(fields, prose, source);

package/dist/engine/define-handler.js

@@ -1,4 +1,5 @@
 import { ENTITY_CONVENTION_QUERY_BRAND } from "@cosmicdrift/kumiko-types/handlers";
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { runPipeline } from "./run-pipeline.js";
 export function defineWriteHandler(def, 
 // R6: a phantom rest-param. When the inferred response `TData` carries a
@@ -88,14 +89,10 @@ export function defineQueryHandler(def,
 // brand through into the stored registry entry.
 export const PAGED_QUERY_HANDLER_BRAND = "__kumikoPagedQueryHandler";
 export function isPagedQueryHandler(def) {
-    // @cast-boundary brand-probe — reading an internal marker key off an
-    // otherwise-typed handler definition; the property may legitimately be
-    // absent, which is exactly the case this function distinguishes.
-    return def[PAGED_QUERY_HANDLER_BRAND] === true;
+    return propertyOf(def, PAGED_QUERY_HANDLER_BRAND) === true;
 }
 export function isEntityConventionQueryHandler(def) {
-    // @cast-boundary brand-probe — same shape as isPagedQueryHandler above.
-    return def[ENTITY_CONVENTION_QUERY_BRAND] === true;
+    return propertyOf(def, ENTITY_CONVENTION_QUERY_BRAND) === true;
 }
 // A projectionList screen's query must resolve to { rows, nextCursor, total? }
 // (CursorResult<T>) — the renderer used to read rowsQuery.data?.rows and

package/dist/engine/embedded-derived.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 /** Computes a derived cell from its source values. Missing/non-numeric
  *  sources: "multiply" with any missing source → undefined; "sum"/"subtract"
  *  treat missing as 0 only when at least one source is present — if every
@@ -6,9 +7,13 @@
  *  to the target sub-field's declared precision afterward. */
 export function computeDerivedCellValue(op, values) {
     if (op === "multiply") {
-        if (values.some((value) => value === undefined))
-            return undefined;
-        return values.reduce((product, value) => product * value, 1);
+        let product = 1;
+        for (const value of values) {
+            if (value === undefined)
+                return undefined;
+            product *= value;
+        }
+        return product;
     }
     if (values.every((value) => value === undefined))
         return undefined;
@@ -58,10 +63,9 @@ function roundHalfAwayFromZero(value, decimals) {
  *  it's written back, so a fractional product lands on a value the target
  *  type can actually represent. */
 export function withDerivedCells(row, derived, schema) {
-    if (typeof row !== "object" || row === null || Array.isArray(row))
+    if (!isPlainObject(row))
         return row;
-    const source = row;
-    const copy = { ...source };
+    const copy = { ...row };
     for (const [cellName, def] of Object.entries(derived)) {
         const sourceValues = def.from.map((sourceField) => {
             const value = copy[sourceField];

package/dist/engine/extensions/escape-hatch-usage.js

@@ -3,9 +3,10 @@
 // validation (feature-ui-extensions.ts's useExtension) already rejects an
 // empty reason, but options stays `Record<string, unknown>`, so orchestrators
 // re-narrow at read time instead of trusting the shape.
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 export function extensionUsageEscapeHatchReason(usage) {
     const escapeHatch = usage.options?.["escapeHatch"];
-    if (typeof escapeHatch !== "object" || escapeHatch === null)
+    if (!isPlainObject(escapeHatch))
         return undefined;
     const { reason, grants } = escapeHatch;
     if (Array.isArray(grants) && !grants.includes("unsafeRaw"))