@cosmicdrift/kumiko-framework 0.387.0 → 0.388.0

package/dist/db/reference-data.js

@@ -37,7 +37,12 @@ export async function seedReferenceData(defs, registry, db) {
             const keyValue = row[upsertKey];
             if (keyValue === undefined)
                 continue;
-            const existing = await fetchOne(db, table, { [upsertKey]: keyValue });
+            // Soft-deleted rows are invisible to executor.update, so treat them as missing and re-create.
+            const existing = await fetchOne(db, table, {
+                [upsertKey]: keyValue,
+                tenantId: SYSTEM_TENANT_ID,
+                ...(entity.softDelete && { isDeleted: false }),
+            });
             if (existing) {
                 const changes = {};
                 for (const [field, value] of Object.entries(row)) {

package/dist/db/table-builder.js

@@ -1,6 +1,5 @@
 import { KUMIKO_META_SYMBOL } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { toSnakeCase } from "../utils/case.js";
-import { assertUnreachable } from "../utils/index.js";
 import { markExecutorManagedTable } from "./executor-managed-tables.js";
 import { columnHandleName } from "./table-introspection.js";
 export { toSnakeCase } from "../utils/case.js";
@@ -13,172 +12,120 @@ export const SOFT_DELETE_LIVE_ROW_PREDICATE = `"is_deleted" = false`;
 export function physicalColumnName(table, field) {
     return columnHandleName(table, field) ?? toSnakeCase(field);
 }
-// Returns column(s) for a field. Most fields return a single entry,
-// money returns two (amount + currency).
-//
-// `required: true` on a FieldDefinition always maps to .notNull() in the
-// database column. Previously this applied only to reference fields, while
-// text/select/number/etc. remained silently nullable even when the API
-// validator enforced required. That forced hand-written PgTable definitions
-// to add .notNull(), causing duplicate definitions and schema drift. Now
-// r.entity is the single source of truth.
-function fieldToColumns(name, field, entity) {
-    const snakeName = toSnakeCase(name);
-    switch (field.type) {
-        case "text":
-        case "longText": {
-            // Both map to PG `text` (unbounded). The difference exists only in the
-            // type layer: longText has no sortable/searchable/filterable support.
-            // The order default() before notNull() matters: the column builder
-            // chains both; without default(), the generated SQL has no DEFAULT
-            // clause, which breaks ALTER TABLE ADD COLUMN on existing rows.
-            // longText currently has no default field in its type, but checking
-            // `field.default !== undefined` is defensive.
-            const base = text(snakeName);
-            const withDefault = "default" in field && field.default !== undefined ? base.default(field.default) : base;
-            const mainCol = { [name]: field.required ? withDefault.notNull() : withDefault };
-            // lookupable → nullable HMAC blind-index column (kept in lockstep with
-            // fieldToColumnMeta in entity-table-meta.ts).
-            if (field.type === "text" && field.lookupable === true) {
-                return { ...mainCol, [`${name}Bidx`]: text(`${snakeName}_bidx`) };
-            }
-            return mainCol;
-        }
-        case "boolean":
-            return {
-                [name]: field.default !== undefined
-                    ? boolean(snakeName).default(field.default).notNull()
-                    : field.required
-                        ? boolean(snakeName).notNull()
-                        : boolean(snakeName),
-            };
-        case "select": {
-            // Pass default() through because entity-table-meta renders declared
-            // defaults. This builder must stay in lockstep; otherwise the metadata
-            // on the buildEntityTable object describes a different column than the
-            // migration.
-            const base = text(snakeName);
-            const col = field.default !== undefined ? base.default(field.default) : base;
-            return { [name]: field.required ? col.notNull() : col };
-        }
-        case "multiSelect":
-            // jsonb string array with default `[]`, always NOT NULL.
-            //
-            // The `required` flag on MultiSelectFieldDef is intentionally ignored:
-            // with default `[]`, the field is structurally never null (an insert
-            // without a value produces an empty array, not NULL). Read-side code
-            // therefore needs no null check; this is an API guarantee. Code that
-            // needs actual null (meaning the field has never been set) should use
-            // a separate status field or an optional-typed reference instead of a
-            // multi-select.
-            return { [name]: jsonb(snakeName).default([]).notNull() };
-        case "number": {
-            const base = field.integer === true ? integer(snakeName) : doublePrecision(snakeName);
-            const col = field.default !== undefined ? base.default(field.default) : base;
-            return { [name]: field.required ? col.notNull() : col };
-        }
-        case "decimal": {
-            const base = decimalColumn(snakeName, field.precision, field.scale);
-            const col = field.default !== undefined ? base.default(field.default) : base;
-            return { [name]: field.required ? col.notNull() : col };
-        }
-        case "bigInt": {
-            // 64-bit integer for audit counters, byte sizes, and cumulative sums.
-            // mode:"number" produces a JS `number` (safe up to 2^53 ≈ 9 PB) rather
-            // than JS `bigint`, making it JSON-serializable and frontend-friendly.
-            // Values above 2^53 should use a text field with a custom codec.
-            const base = bigint(snakeName, { mode: "number" });
-            const col = field.default !== undefined ? base.default(field.default) : base;
-            return { [name]: field.required ? col.notNull() : col };
-        }
-        case "reference":
-            // FK-style UUID column. Multi-mode stores UUIDs as a jsonb string array;
-            // single-mode remains a conventional UUID column (NOT NULL only when
-            // required).
-            if (field.multiple === true) {
-                return { [name]: jsonb(snakeName).default([]).notNull() };
-            }
-            return {
-                [name]: field.required ? uuid(snakeName).notNull() : uuid(snakeName),
-            };
-        case "money":
-            // BIGINT stores the integer minor unit (cents for EUR, yen for JPY —
-            // the currency column identifies which). INTEGER would cap at about
-            // 21 M EUR, which is too low for B2B invoices, property values, or
-            // balance aggregates. BIGINT safely handles up to about 90 trillion
-            // EUR in JS.
-            // Currency always has a default, so it is structurally .notNull().
-            return {
-                [name]: field.required ? moneyAmount(snakeName).notNull() : moneyAmount(snakeName),
-                [`${name}Currency`]: text(`${snakeName}_currency`)
-                    .default(entity.defaultCurrency ?? "EUR")
-                    .notNull(),
-            };
-        case "embedded":
-            // jsonb with default `{}`, always NOT NULL, analogous to multiSelect.
-            // `required` is intentionally ignored because the default makes the
-            // field structurally never null. To make embedded data optional (so
-            // the field can be omitted entirely), model it with a wrapper field
-            // and boolean flag or a discriminated union.
-            // multiple → the value is a list of rows, so the empty default is `[]`.
-            return field.multiple === true
-                ? { [name]: jsonb(snakeName).default([]).notNull() }
-                : { [name]: jsonb(snakeName).default({}).notNull() };
-        case "jsonb":
-            // Free-form jsonb — keys are not schema-validated. Default `{}`, NOT NULL
-            // (analogous to embedded). Use case: the host entity's custom-fields
-            // bundle in the `customFields` column, whose keys are tenant-defined.
-            return { [name]: jsonb(snakeName).default({}).notNull() };
-        case "date": {
-            // Real PG `date` — no time-of-day, no timezone. Temporal.PlainDate
-            // end-to-end (see plainDate() in dialect.ts). Was aliased on instant()
-            // = TIMESTAMPTZ (TZ-dependent round-trip).
-            const col = plainDate(snakeName);
-            return { [name]: field.required ? col.notNull() : col };
-        }
-        case "timestamp": {
-            // UTC instant — stored as TIMESTAMPTZ in PG and read/written as
-            // Temporal.Instant through the instant() customType (see dialect.ts).
-            // Callers use only Temporal.Instant, never JS Date. Comparisons
-            // (lte/gt/orderBy) also accept Instants directly, so no .toString()
-            // cast is needed.
-            const col = instant(snakeName);
-            return { [name]: field.required ? col.notNull() : col };
-        }
-        case "tz": {
-            // IANA time-zone name as TEXT — validated through the Zod schema in the
-            // validator step. Snake-case convention: `pickup_tz`.
-            const col = text(snakeName);
-            return { [name]: field.required ? col.notNull() : col };
-        }
-        case "locatedTimestamp": {
-            // Two columns form an atomic pair: <name>_utc TIMESTAMPTZ + <name>_tz TEXT.
-            // _utc is instant() (Temporal.Instant), and _tz is text (IANA name).
-            // The executor wires automatic conversion (at+tz → utc on insert;
-            // utc+tz → at on read). required propagates to both columns.
-            const utc = instant(`${snakeName}_utc`);
-            const tz = text(`${snakeName}_tz`);
-            return {
-                [`${name}Utc`]: field.required ? utc.notNull() : utc,
-                [`${name}Tz`]: field.required ? tz.notNull() : tz,
-            };
-        }
-        case "file":
-        case "image": {
-            // Single file: stores fileRefId as UUID — must match fileRefsTable.id
-            // (uuid column). Anything narrower (integer, text length-limited) would
-            // silently truncate or type-coerce at INSERT time and the FK reference
-            // would be unusable.
-            const col = uuid(snakeName);
-            return { [name]: field.required ? col.notNull() : col };
-        }
-        case "files":
-        case "images":
-            // Ordered fileRef UUID array, same shape as multiSelect: never null.
-            return { [name]: jsonb(snakeName).default([]).notNull() };
-        default:
-            assertUnreachable(field, "field type");
+// `required: true` maps to NOT NULL for every field type, so r.entity stays the
+// single source of truth and hand-written tables never add .notNull() on top.
+function notNullWhenRequired(column, required) {
+    return required ? column.notNull() : column;
+}
+// Without a DEFAULT clause ALTER TABLE ADD COLUMN breaks on existing rows, and
+// entity-table-meta renders declared defaults too, so both builders stay in lockstep.
+function withDeclaredDefault(column, value) {
+    return value !== undefined ? column.default(value) : column;
+}
+// longText differs from text only in the type layer (no sortable/searchable/filterable).
+function textColumns(name, snakeName, field) {
+    const declaredDefault = "default" in field ? field.default : undefined;
+    const mainCol = {
+        [name]: notNullWhenRequired(withDeclaredDefault(text(snakeName), declaredDefault), field.required),
+    };
+    // Nullable HMAC blind-index column, in lockstep with fieldToColumnMeta in entity-table-meta.ts.
+    if (field.type === "text" && field.lookupable === true) {
+        return { ...mainCol, [`${name}Bidx`]: text(`${snakeName}_bidx`) };
     }
+    return mainCol;
+}
+function booleanColumns(name, snakeName, field) {
+    if (field.default !== undefined) {
+        return { [name]: boolean(snakeName).default(field.default).notNull() };
+    }
+    return { [name]: notNullWhenRequired(boolean(snakeName), field.required) };
+}
+function numberColumns(name, snakeName, field) {
+    const base = field.integer === true ? integer(snakeName) : doublePrecision(snakeName);
+    return { [name]: notNullWhenRequired(withDeclaredDefault(base, field.default), field.required) };
+}
+function referenceColumns(name, snakeName, field) {
+    if (field.multiple === true)
+        return { [name]: emptyJsonbArray(snakeName) };
+    return { [name]: notNullWhenRequired(uuid(snakeName), field.required) };
+}
+// BIGINT minor units: INTEGER would cap at about 21 M EUR. The currency column
+// always has a default, so it is structurally NOT NULL.
+function moneyColumns(name, snakeName, field, entity) {
+    return {
+        [name]: notNullWhenRequired(moneyAmount(snakeName), field.required),
+        [`${name}Currency`]: text(`${snakeName}_currency`)
+            .default(entity.defaultCurrency ?? "EUR")
+            .notNull(),
+    };
+}
+// <name>_utc + <name>_tz form an atomic pair the executor converts on write and
+// read, so `required` propagates to both columns.
+function locatedTimestampColumns(name, snakeName, field) {
+    return {
+        [`${name}Utc`]: notNullWhenRequired(instant(`${snakeName}_utc`), field.required),
+        [`${name}Tz`]: notNullWhenRequired(text(`${snakeName}_tz`), field.required),
+    };
+}
+// The `[]` default makes the column structurally never null, so `required` is
+// intentionally ignored and read-side code needs no null check.
+function emptyJsonbArray(snakeName) {
+    return jsonb(snakeName).default([]).notNull();
+}
+// Same reasoning as emptyJsonbArray; optional embedded data needs a wrapper field.
+function emptyJsonbObject(snakeName) {
+    return jsonb(snakeName).default({}).notNull();
+}
+function singleColumnNotNullWhenRequired(column) {
+    return (name, snakeName, field) => ({
+        [name]: notNullWhenRequired(column(snakeName), field.required),
+    });
+}
+// Each entry has a type-level twin in ColumnsForField and a meta-level twin in
+// fieldToColumnMeta (entity-table-meta.ts).
+const COLUMN_EMITTERS = {
+    text: textColumns,
+    longText: textColumns,
+    boolean: booleanColumns,
+    select: (name, snakeName, field) => ({
+        [name]: notNullWhenRequired(withDeclaredDefault(text(snakeName), field.default), field.required),
+    }),
+    multiSelect: (name, snakeName) => ({ [name]: emptyJsonbArray(snakeName) }),
+    number: numberColumns,
+    decimal: (name, snakeName, field) => ({
+        [name]: notNullWhenRequired(withDeclaredDefault(decimalColumn(snakeName, field.precision, field.scale), field.default), field.required),
+    }),
+    // mode "number" keeps the value JSON-serializable (safe up to 2^53).
+    bigInt: (name, snakeName, field) => ({
+        [name]: notNullWhenRequired(withDeclaredDefault(bigint(snakeName, { mode: "number" }), field.default), field.required),
+    }),
+    reference: referenceColumns,
+    money: moneyColumns,
+    embedded: (name, snakeName, field) => ({
+        [name]: field.multiple === true ? emptyJsonbArray(snakeName) : emptyJsonbObject(snakeName),
+    }),
+    jsonb: (name, snakeName) => ({ [name]: emptyJsonbObject(snakeName) }),
+    date: singleColumnNotNullWhenRequired(plainDate),
+    timestamp: singleColumnNotNullWhenRequired(instant),
+    tz: singleColumnNotNullWhenRequired(text),
+    locatedTimestamp: locatedTimestampColumns,
+    // Must match fileRefsTable.id (uuid); anything narrower breaks the reference.
+    file: singleColumnNotNullWhenRequired(uuid),
+    image: singleColumnNotNullWhenRequired(uuid),
+    files: (name, snakeName) => ({ [name]: emptyJsonbArray(snakeName) }),
+    images: (name, snakeName) => ({ [name]: emptyJsonbArray(snakeName) }),
+};
+function emitFieldColumns(type, name, field, entity) {
+    // A type from untyped input must not reach an Object.prototype member.
+    if (!Object.hasOwn(COLUMN_EMITTERS, type)) {
+        throw new Error(`[Kumiko] unhandled field type: ${String(field)}`);
+    }
+    const emit = COLUMN_EMITTERS[type];
+    return emit(name, toSnakeCase(name), field, entity);
+}
+// Most fields return one column; money and locatedTimestamp return two.
+function fieldToColumns(name, field, entity) {
+    return emitFieldColumns(field.type, name, field, entity);
 }
 // Accepts both camelCase (`tenantMembership`) and kebab-case (`tenant-membership`)
 // entity / field names. Implementation lives in utils/case — re-exported here

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

@@ -0,0 +1,10 @@
+import type { TableLike } from "./query.ts";
+export type TableInfo = {
+    readonly name: string;
+    readonly columnOf: (field: string) => string;
+    readonly pgTypeOf: (column: string) => string | undefined;
+    readonly bigintJsModeOf: (column: string) => "number" | "bigint" | undefined;
+    readonly fieldOf: (column: string) => string;
+    readonly hasColumn: (fieldOrColumn: string) => boolean;
+};
+export declare function extractTableInfo(table: TableLike): TableInfo;

package/dist/db/table-info.js

@@ -0,0 +1,45 @@
+import { camelCase as envCamelCase } from "../env/index.js";
+import { toSnakeCase } from "./table-builder.js";
+import { asEntityTableMeta } from "./table-introspection.js";
+// Idempotent snake_case → camelCase. `env.camelCase` always lowercases first
+// (designed for SHOUT_CASE input) — for already-camelCase keys (mock rows
+// in tests, projection-aliased columns) it would silently produce "tenantid"
+// instead of leaving "tenantId" alone. Guard with an underscore check so
+// the conversion only fires when the key is actually snake-shaped.
+function snakeToCamel(key) {
+    if (!key.includes("_"))
+        return key;
+    return envCamelCase(key);
+}
+export function extractTableInfo(table) {
+    const meta = asEntityTableMeta(table);
+    if (!meta) {
+        throw new Error("extractTableInfo: table is not a kumiko EntityTableMeta — " +
+            "build it via buildEntityTable / deriveEntityTableMeta / table().");
+    }
+    const colByField = new Map();
+    const fieldByCol = new Map();
+    const typeByCol = new Map();
+    const bigintModeByCol = new Map();
+    for (const c of meta.columns) {
+        typeByCol.set(c.name, c.pgType);
+        if (c.bigintJsMode !== undefined)
+            bigintModeByCol.set(c.name, c.bigintJsMode);
+        // EntityTableMeta column names are snake_case. Map snake → snake AND
+        // derive a camelCase JS field-name so result rows can be renamed back
+        // to the API shape (`aggregate_id` → `aggregateId`).
+        colByField.set(c.name, c.name);
+        const camel = snakeToCamel(c.name);
+        if (camel !== c.name)
+            colByField.set(camel, c.name);
+        fieldByCol.set(c.name, camel === c.name ? c.name : camel);
+    }
+    return {
+        name: meta.tableName,
+        columnOf: (field) => colByField.get(field) ?? toSnakeCase(field),
+        pgTypeOf: (col) => typeByCol.get(col),
+        bigintJsModeOf: (col) => bigintModeByCol.get(col),
+        fieldOf: (col) => fieldByCol.get(col) ?? snakeToCamel(col),
+        hasColumn: (fieldOrColumn) => colByField.has(fieldOrColumn) || fieldByCol.has(fieldOrColumn),
+    };
+}

package/dist/db/temporal-value-guards.d.ts

@@ -0,0 +1,6 @@
+import type { Temporal } from "@cosmicdrift/kumiko-types/temporal";
+export declare function isTemporalInstant(v: unknown): v is Temporal.Instant;
+export declare function isTemporalPlainDate(v: unknown): v is Temporal.PlainDate;
+export declare function isTemporalPlainDateTimeLike(v: unknown): v is {
+    toPlainDate(): Temporal.PlainDate;
+};

package/dist/db/temporal-value-guards.js

@@ -0,0 +1,15 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+export function isTemporalInstant(v) {
+    return propertyOf(v, Symbol.toStringTag) === "Temporal.Instant";
+}
+export function isTemporalPlainDate(v) {
+    return propertyOf(v, Symbol.toStringTag) === "Temporal.PlainDate";
+}
+export function isTemporalPlainDateTimeLike(v) {
+    const tag = propertyOf(v, Symbol.toStringTag);
+    return ((tag === "Temporal.PlainDateTime" || tag === "Temporal.ZonedDateTime") &&
+        typeof v === "object" &&
+        v !== null &&
+        "toPlainDate" in v &&
+        typeof v.toPlainDate === "function");
+}

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

@@ -6,5 +6,6 @@ export declare function isDbRunner(value: unknown): value is DbRunner;
 export declare function bindTenantDbRunner(tenantDb: TenantDb, runner: DbRunner): void;
 export declare function tenantDbRunner(tenantDb: TenantDb): DbRunner;
 export declare function denyTenantDbWrites(tenantDb: TenantDb, reason: string): void;
+export declare function tenantDbWritesDeniedReason(tenantDb: TenantDb): string | undefined;
 export declare function tenantDbWritesDeniedError(operation: string, reason: string): InternalError;
 export declare function tenantDbWriteRunner(tenantDb: TenantDb, operation: string): DbRunner;

package/dist/db/tenant-db-runner.js

@@ -26,6 +26,9 @@ const writesDeniedReasons = new WeakMap();
 export function denyTenantDbWrites(tenantDb, reason) {
     writesDeniedReasons.set(tenantDb, reason);
 }
+export function tenantDbWritesDeniedReason(tenantDb) {
+    return writesDeniedReasons.get(tenantDb);
+}
 export function tenantDbWritesDeniedError(operation, reason) {
     return new InternalError({
         message: `${operation}: writes are not available ${reason}; run the write through ctx.write so it gets its own transaction`,

package/dist/db/tenant-db.js

@@ -10,7 +10,7 @@ import { bindProjectionRegistry, projectionRegistryOf } from "./projection-regis
 import { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
 import { queryDatabaseNow } from "./queries/database-now.js";
 import { hasFieldProperty, tableNameOf } from "./table-introspection.js";
-import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, } from "./tenant-db-runner.js";
+import { bindTenantDbRunner, denyTenantDbWrites, tenantDbRunner, tenantDbWritesDeniedError, tenantDbWritesDeniedReason, } from "./tenant-db-runner.js";
 export { SYSTEM_SCOPE_CHECK_BRAND, } from "@cosmicdrift/kumiko-types/tenant-db-types";
 const declaredUnsafeRawRunners = new WeakMap();
 // The CRUD executor writes through tenantDbRunner, not insertOne, so it asks the
@@ -105,9 +105,7 @@ export function assertPersonalDataWrite(db, tableName, keys, entity) {
 }
 // Framework-private (not re-exported from db/index.ts): same grant check + audit as unsafeRaw, for engine forwarding.
 export function unsafeRawForDeclaredStep(holder, reason) {
-    if (reason.trim().length === 0) {
-        throw new Error("unsafeRawForDeclaredStep requires a non-empty reason");
-    }
+    assertReason("unsafeRawForDeclaredStep", reason);
     const runner = declaredUnsafeRawRunners.get(holder);
     if (!runner) {
         throw new InternalError({
@@ -257,7 +255,13 @@ export function createSystemDbView(db, dbOutsideTransaction, report = fallbackEs
 // same connection/transaction. For code that must run caller-supplied callbacks (e.g. config
 // validators) without handing them a cross-tenant view.
 export function scopeTenantDbToTenant(db, tenantId) {
-    return createTenantDb({ db: tenantDbRunner(db), tenantId, mode: "tenant" });
+    const writesDeniedReason = tenantDbWritesDeniedReason(db);
+    return createTenantDb({
+        db: tenantDbRunner(db),
+        tenantId,
+        mode: "tenant",
+        ...(writesDeniedReason !== undefined && { grants: { writesDeniedReason } }),
+    });
 }
 // @cast-boundary tenant-db-row
 export function castTenantRows(rows) {
@@ -268,6 +272,18 @@ export { tableNameOf };
 function hasGrant(decl) {
     return decl !== undefined && decl.reason.trim().length > 0;
 }
+// Tenant ids left over when the caller excludes some via ne/notIn; undefined for other operator forms.
+function tenantIdsAfterExclusion(requested, allowed) {
+    if (!isPlainObject(requested))
+        return undefined;
+    if ("ne" in requested)
+        return allowed.filter((t) => t !== requested["ne"]);
+    if (Array.isArray(requested["notIn"])) {
+        const excluded = requested["notIn"];
+        return allowed.filter((t) => !excluded.includes(t));
+    }
+    return undefined;
+}
 // Tenant ids a where.tenantId filter asks for; undefined for operator forms
 // that cannot narrow to a tenant list (ne, like, ...).
 export function requestedTenantIds(requested) {
@@ -429,7 +445,13 @@ function buildTenantDb(options) {
         const allowed = [tenantId, SYSTEM_TENANT_ID];
         const requested = where?.["tenantId"];
         if (requested !== undefined) {
-            const requestedList = requestedTenantIds(requested) ?? [];
+            const requestedList = requestedTenantIds(requested);
+            // An explicit exclusion or empty list must keep excluding, never widen to the full scope.
+            if (requestedList === undefined) {
+                return { ...where, tenantId: tenantIdsAfterExclusion(requested, allowed) ?? allowed };
+            }
+            if (requestedList.length === 0)
+                return { ...where, tenantId: [] };
             const narrowed = requestedList.filter((t) => typeof t === "string" && allowed.includes(t));
             return { ...where, tenantId: narrowed.length > 0 ? narrowed : allowed };
         }
@@ -464,6 +486,14 @@ function buildTenantDb(options) {
     function globalWriteReason() {
         return grants?.globalWrites?.reason ?? "";
     }
+    // The table is the audit target: process-level dedup would otherwise collapse a cron's
+    // writes to several global tables into one audit entry.
+    function reportGlobalWrite(table) {
+        report("global-write", globalWriteReason(), {
+            id: tableNameOf(table),
+            tenantId: tenantId ?? SYSTEM_TENANT_ID,
+        });
+    }
     function personalDataDenied(table, keys) {
         if (!personalDataGate)
             return undefined;
@@ -535,7 +565,7 @@ function buildTenantDb(options) {
                     personalDataDenied(table, Object.keys(values));
                 if (denied)
                     return Promise.reject(denied);
-                report("global-write", globalWriteReason());
+                reportGlobalWrite(table);
                 return withDbSpan("insert", table, async () => insertRow(table, values));
             },
             updateMany(set, where) {
@@ -549,7 +579,7 @@ function buildTenantDb(options) {
                 if (!where || Object.keys(where).length === 0) {
                     return Promise.reject(new Error("db.global().updateMany without where would mass-update every tenant's rows. Pass at least one where condition."));
                 }
-                report("global-write", globalWriteReason());
+                reportGlobalWrite(table);
                 return withDbSpan("update", table, async () => updateRows(table, set, where));
             },
             deleteMany(where) {
@@ -561,7 +591,7 @@ function buildTenantDb(options) {
                 if (!where || Object.keys(where).length === 0) {
                     return Promise.reject(new Error("db.global().deleteMany without where would mass-delete every tenant's rows. Pass at least one where condition."));
                 }
-                report("global-write", globalWriteReason());
+                reportGlobalWrite(table);
                 return withDbSpan("delete", table, async () => {
                     await deleteRows(table, where);
                 });

package/dist/db/where-clause.d.ts

@@ -0,0 +1,6 @@
+import type { WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
+import type { TableInfo } from "./table-info.ts";
+export declare function buildWhereClause(info: TableInfo, where: WhereObject, startIndex: number, qualifier?: string): {
+    sqlText: string;
+    values: unknown[];
+};