@cosmicdrift/kumiko-framework 0.387.0 → 0.389.0

package/dist/db/reference-data.js

@@ -2,8 +2,10 @@ import { fetchOne } from "../db/query.js";
 import { createSystemUser } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
 import { reraiseAsKumikoError } from "../errors/index.js";
+import { getStreamVersion } from "../event-store/event-store.js";
 import { entityTableFromRegistry } from "./entity-table-from-registry.js";
 import { createEventStoreExecutor } from "./event-store-executor.js";
+import { deleteRowsWithoutReplayableStream } from "./queries/event-store-orphan-rows.js";
 import { createTenantDb } from "./tenant-db.js";
 /**
  * Seed reference data at boot time.
@@ -37,7 +39,22 @@ 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 existingRow = await fetchOne(db, table, {
+                [upsertKey]: keyValue,
+                tenantId: SYSTEM_TENANT_ID,
+                ...(entity.softDelete && { isDeleted: false }),
+            });
+            // Rows seeded before reference data went through the executor have no events: update would
+            // hit a stream-version conflict and a rebuild would drop them. Drop the row and re-create
+            // it under the same id so its stream starts now.
+            let existing = existingRow;
+            let recreateId;
+            if (existingRow && (await getStreamVersion(db, existingRow.id, SYSTEM_TENANT_ID)) === 0) {
+                await deleteRowsWithoutReplayableStream(tdb, { table, ids: [existingRow.id] });
+                existing = undefined;
+                recreateId = existingRow.id;
+            }
             if (existing) {
                 const changes = {};
                 for (const [field, value] of Object.entries(row)) {
@@ -55,7 +72,7 @@ export async function seedReferenceData(defs, registry, db) {
                 }
             }
             else {
-                const result = await executor.create({ ...row, tenantId: SYSTEM_TENANT_ID }, by, tdb);
+                const result = await executor.create({ ...row, ...(recreateId && { id: recreateId }), tenantId: SYSTEM_TENANT_ID }, by, tdb);
                 if (!result.isSuccess)
                     throw reraiseAsKumikoError(result.error);
                 inserted++;

package/dist/db/statement-timeout.js

@@ -4,7 +4,8 @@ const UNBOUNDED_POOL_CLOSE_TIMEOUT_SECONDS = 5;
 // PII backfill and projection rebuilds legitimately run longer. The cap is a connect-time session
 // setting, so the run gets its own short-lived pool with the same options minus the cap: one shared
 // connection would deadlock code that holds a lock in a tx while its DDL runs on another connection.
-// Handles not created by createDbConnection (tx, savepoint, siblings) are passed through.
+// Handles not created by createDbConnection (tx, savepoint, siblings, gated runner proxies) are passed through
+// unchanged and keep the cap; a caller holding such a runner lifts it itself (SET LOCAL in its own transaction).
 export async function withoutStatementTimeout(db, run) {
     const unbounded = openUnboundedSiblingPool(db);
     if (unbounded === undefined)

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-upsert.d.ts

@@ -0,0 +1,5 @@
+import type { TenantDbMode, TenantDbUpsertOptions } from "@cosmicdrift/kumiko-types/tenant-db-types";
+import { AccessDeniedError } from "../errors/index.ts";
+import { type AnyDb, type TableLike } from "./query.ts";
+export declare function upsertTableDenied(table: TableLike, mode: TenantDbMode): AccessDeniedError | undefined;
+export declare function upsertTenantRow<TRow>(db: AnyDb, table: TableLike, values: Record<string, unknown>, options: TenantDbUpsertOptions): Promise<TRow | undefined>;

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

@@ -0,0 +1,91 @@
+import { quoteIdent } from "../crypto/ciphertext-pattern.js";
+import { AccessDeniedError } from "../errors/index.js";
+import { isExecutorManagedTable } from "./executor-managed-tables.js";
+import { buildInsertSql, coerceRow, conflictUpdateParts, insertEntries, unsafeLoggingClosedConnection, } from "./query.js";
+import { extractTableInfo } from "./table-info.js";
+import { asEntityTableMeta, tableNameOf } from "./table-introspection.js";
+const TENANT_COLUMN = "tenant_id";
+// Upsert is never allowed on event-fed tables (even with the write capability) and has no tenant-mode meaning for "global" ones.
+export function upsertTableDenied(table, mode) {
+    if (isExecutorManagedTable(table)) {
+        return new AccessDeniedError({
+            message: `ctx.db.upsert(${tableNameOf(table)}): table is fed by events; upsert is not supported on it.`,
+        });
+    }
+    if (mode === "tenant" && asEntityTableMeta(table)?.tenancy === "global") {
+        return new AccessDeniedError({
+            message: `ctx.db.upsert(${tableNameOf(table)}): "global" table rows must carry SYSTEM_TENANT_ID; ` +
+                "use db.global(table) with escapeHatch instead.",
+        });
+    }
+    return undefined;
+}
+function sameColumnSet(a, b) {
+    return a.length === b.length && new Set(a).size === a.length && a.every((c) => b.includes(c));
+}
+function declaredUniqueColumnSets(meta) {
+    const sets = meta.indexes
+        .filter((i) => i.unique === true && i.whereSql === undefined && i.needsManualWhere !== true)
+        .map((i) => i.columns);
+    if (meta.compositePrimaryKey)
+        sets.push(meta.compositePrimaryKey.columns);
+    const primaryKeyColumns = meta.columns.filter((c) => c.primaryKey).map((c) => c.name);
+    if (primaryKeyColumns.length > 0)
+        sets.push(primaryKeyColumns);
+    return sets;
+}
+function primaryKeyColumnsOf(meta) {
+    return [
+        ...meta.columns.filter((c) => c.primaryKey).map((c) => c.name),
+        ...(meta.compositePrimaryKey?.columns ?? []),
+    ];
+}
+function assertTenantSafeConflictTarget(tableName, meta, conflictCols) {
+    if (conflictCols.length === 0 || !conflictCols.includes(TENANT_COLUMN)) {
+        throw new Error(`tenantDb.upsert(${tableName}): conflictTarget must include "tenantId" — a target without it ` +
+            "could match, and overwrite, another tenant's row.");
+    }
+    if (!declaredUniqueColumnSets(meta).some((set) => sameColumnSet(set, conflictCols))) {
+        throw new Error(`tenantDb.upsert(${tableName}): conflictTarget (${conflictCols.join(", ")}) matches no ` +
+            "declared unique index (without a WHERE clause) or primary key.");
+    }
+}
+// Handles a tenant's own row only: values carry the tenant already, and the DO UPDATE guard
+// compares against the tenant being inserted, so a conflict on another tenant's row updates nothing.
+export async function upsertTenantRow(db, table, values, options) {
+    const info = extractTableInfo(table);
+    const meta = asEntityTableMeta(table);
+    if (!info.hasColumn("tenantId")) {
+        throw new Error(`tenantDb.upsert(${info.name}): table has no tenant column — use the free upsertOnConflict ` +
+            "helper on an unsafeRaw runner instead.");
+    }
+    if (!meta) {
+        throw new Error(`tenantDb.upsert(${info.name}): needs an EntityTableMeta table (declared unique indexes and primary key), got a table without meta.`);
+    }
+    const conflictCols = options.conflictTarget.map((field) => info.columnOf(field));
+    assertTenantSafeConflictTarget(info.name, meta, conflictCols);
+    if (options.update &&
+        Object.keys(options.update).some((f) => info.columnOf(f) === TENANT_COLUMN)) {
+        throw new Error(`tenantDb.upsert(${info.name}): update must not set "tenantId" — it would move the row into another tenant.`);
+    }
+    const entries = insertEntries(info, values);
+    if (!entries.some((e) => e.col === TENANT_COLUMN)) {
+        throw new Error(`tenantDb.upsert(${info.name}): values carry no tenantId.`);
+    }
+    const { sqlPrefix, params } = buildInsertSql(info, entries);
+    const skipCols = new Set([...conflictCols, ...primaryKeyColumnsOf(meta), TENANT_COLUMN]);
+    const setParts = conflictUpdateParts(info, entries, options.update, skipCols, params);
+    if (setParts.length === 0) {
+        throw new Error(`tenantDb.upsert(${info.name}): nothing to update on conflict`);
+    }
+    const tenantRef = quoteIdent(TENANT_COLUMN);
+    const sqlText = `${sqlPrefix} ON CONFLICT (${conflictCols.map((c) => quoteIdent(c)).join(", ")}) ` +
+        `DO UPDATE SET ${setParts.join(", ")} ` +
+        `WHERE ${quoteIdent(info.name)}.${tenantRef} = EXCLUDED.${tenantRef} RETURNING *`;
+    const rows = await unsafeLoggingClosedConnection(db, sqlText, params, {
+        operation: "tenantDb.upsert",
+        table: info.name,
+    });
+    const first = rows[0];
+    return first ? coerceRow(first, info) : undefined;
+}