@cosmicdrift/kumiko-framework 0.361.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/access-declarations.js

@@ -67,16 +67,25 @@ function validateEscapeHatchReason(feature, kind, handlerName, escapeHatch) {
         }
     }
 }
-function validatePersonalDataOnlyOnWrite(feature, kind, handlerName, access) {
-    // skip: write handlers may declare personalData, or it wasn't declared here
-    if (kind === "write" || declaredPersonalData(access) === undefined)
+function validatePersonalDataSupportedForKind(feature, kind, handlerName, access) {
+    // skip: nothing declared
+    if (declaredPersonalData(access) === undefined)
         return;
-    const property = "openToAll" in access ? "openToAll.personalData" : "access.personalData";
-    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
-        `${property} — it only applies to write handlers, whose input is ` +
-        "checked for personal-data fields.");
+    // skip: write handlers accept every personalData declaration
+    if (kind === "write")
+        return;
+    const isOpenToAll = "openToAll" in access;
+    // skip: query handlers may declare access.personalData, its value is validated separately
+    if (kind === "query" && !isOpenToAll)
+        return;
+    const property = isOpenToAll ? "openToAll.personalData" : "access.personalData";
+    const onlyAllowed = kind === "query"
+        ? 'only access.personalData: "public-intake" applies to query handlers, which write ' +
+            "personal data through nested writes of an anonymous request."
+        : "it only applies to write handlers, whose input is checked for personal-data fields.";
+    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ${property} — ${onlyAllowed}`);
 }
-function validatePersonalDataValue(feature, handlerName, access) {
+function validatePersonalDataValue(feature, kind, handlerName, access) {
     const declared = declaredPersonalData(access);
     // skip: nothing declared
     if (declared === undefined)
@@ -85,17 +94,17 @@ function validatePersonalDataValue(feature, handlerName, access) {
         // skip: the one supported value on openToAll
         if (declared === "tenant-members")
             return;
-        throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" declares an unknown ` +
+        throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an unknown ` +
             `openToAll.personalData ${JSON.stringify(declared)} — the only supported value is "tenant-members".`);
     }
     if (declared !== "public-intake") {
-        throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" declares an unknown ` +
+        throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares an unknown ` +
             `access.personalData ${JSON.stringify(declared)} — the only supported value is "public-intake".`);
     }
     // skip: roles include "anonymous", which personalData: "public-intake" requires
     if (accessAllowsAnonymous(access))
         return;
-    throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" declares ` +
+    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
         'access.personalData: "public-intake" but its roles do not include ' +
         `"${ANONYMOUS_ROLE}" — personalData: "public-intake" only applies to handlers ` +
         "that allow anonymous callers.");
@@ -150,14 +159,14 @@ function validateAnonymousPersonalData(feature, handlerName, handler) {
 }
 // The rateLimit is the only protection of a public-intake handler, so the
 // generic anonymous opt-out (rateLimit: { disabled: true }) must not apply.
-function validatePublicIntakeRateLimit(feature, handlerName, handler) {
-    // skip: not a public-intake handler, or its rateLimit is active
+function validatePublicIntakeRateLimit(feature, kind, handlerName, handler) {
+    // skip: not a public-intake handler
     if (declaredPersonalData(handler.access) !== "public-intake")
         return;
     // skip: rateLimit is active
     if (!isRateLimitDisabled(handler.rateLimit))
         return;
-    throw new Error(`[Feature ${feature.name}] write handler "${handlerName}" declares ` +
+    throw new Error(`[Feature ${feature.name}] ${kind} handler "${handlerName}" declares ` +
         'access.personalData: "public-intake" with rateLimit: { disabled: true } — the rateLimit ' +
         'is the only protection for anonymous personal-data writes. Declare rateLimit: { per: "ip" ' +
         'or "ip+handler", ... } instead.');
@@ -166,19 +175,21 @@ export function validateAccessDeclarations(feature) {
     for (const [handlerName, handler] of Object.entries(feature.writeHandlers)) {
         validateOpenToAllReason(feature, "write", handlerName, handler.access);
         validateEscapeHatchReason(feature, "write", handlerName, handler.escapeHatch);
-        validatePersonalDataValue(feature, handlerName, handler.access);
+        validatePersonalDataValue(feature, "write", handlerName, handler.access);
         validateOpenToAllPersonalData(feature, handlerName, handler);
         validateAnonymousPersonalData(feature, handlerName, handler);
-        validatePublicIntakeRateLimit(feature, handlerName, handler);
+        validatePublicIntakeRateLimit(feature, "write", handlerName, handler);
     }
     for (const [handlerName, handler] of Object.entries(feature.queryHandlers)) {
         validateOpenToAllReason(feature, "query", handlerName, handler.access);
         validateEscapeHatchReason(feature, "query", handlerName, handler.escapeHatch);
-        validatePersonalDataOnlyOnWrite(feature, "query", handlerName, handler.access);
+        validatePersonalDataSupportedForKind(feature, "query", handlerName, handler.access);
+        validatePersonalDataValue(feature, "query", handlerName, handler.access);
+        validatePublicIntakeRateLimit(feature, "query", handlerName, handler);
     }
     for (const [handlerName, handler] of Object.entries(feature.streamHandlers)) {
         validateOpenToAllReason(feature, "stream", handlerName, handler.access);
         validateEscapeHatchReason(feature, "stream", handlerName, handler.escapeHatch);
-        validatePersonalDataOnlyOnWrite(feature, "stream", handlerName, handler.access);
+        validatePersonalDataSupportedForKind(feature, "stream", handlerName, handler.access);
     }
 }

package/dist/engine/boot-validator/card-meta-overflow.js

@@ -1,4 +1,4 @@
-import { CARD_META_MAX, cardColumnRoles } from "../../ui-types/card-column-roles.js";
+import { CARD_META_MAX, cardColumnRoles, cardFileDisplayKind, } from "../../ui-types/card-column-roles.js";
 import { LIST_ROW_META_COLUMNS } from "../../ui-types/list-row-meta.js";
 import { parseRefTarget } from "../parse-ref-target.js";
 import { normalizeListColumn } from "../screen-helpers.js";
@@ -19,11 +19,14 @@ function resolveColumnType(spec, storedType, entity) {
 function countOverflow(feature, screen, location, columns, storedTypeOf, entity) {
     const cardColumns = columns.map((spec) => {
         const col = normalizeListColumn(spec);
+        const type = resolveColumnType(spec, storedTypeOf(col.field), entity);
+        const fileKind = cardFileDisplayKind(type, col.renderer);
         return {
             field: col.field,
-            type: resolveColumnType(spec, storedTypeOf(col.field), entity),
+            type,
             renderer: col.renderer,
             hideOnNarrow: col.hideOnNarrow,
+            ...(fileKind !== undefined && { fileDisplay: { kind: fileKind } }),
         };
     });
     const { meta } = cardColumnRoles(cardColumns);

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);