@cosmicdrift/kumiko-framework 0.378.0 → 0.380.0

package/dist/db/queries/database-now.js

@@ -0,0 +1,12 @@
+import { executeRawQueryRead } from "./raw-sql.js";
+// Called by createTenantDb with its inner runner; keeps raw SQL out of consumers.
+export async function queryDatabaseNow(runner) {
+    const [row] = await executeRawQueryRead(runner, "SELECT now() AS now");
+    if (!row)
+        throw new Error("SELECT now() returned no row");
+    return row.now;
+}
+/** Postgres clock; inside a transaction `now()` is the transaction start, so repeated reads agree. */
+export function readDatabaseNow(db) {
+    return db.databaseNow();
+}

package/dist/db/queries/event-store-orphan-rows.d.ts

@@ -0,0 +1,8 @@
+import type { TenantId } from "../../engine/types/index.ts";
+import { type AnyDb } from "../query.ts";
+export type DeleteRowsWithoutReplayableStreamArgs = {
+    readonly table: unknown;
+    readonly ids: readonly string[];
+    readonly tenantId?: TenantId;
+};
+export declare function deleteRowsWithoutReplayableStream(db: AnyDb, args: DeleteRowsWithoutReplayableStreamArgs): Promise<readonly string[]>;

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

@@ -0,0 +1,32 @@
+import { asRawClient } from "../query.js";
+import { tableNameOf } from "../table-introspection.js";
+import { isBoundTenantDb, tenantDbWriteRunner } from "../tenant-db-runner.js";
+import { toPostgresArrayLiteral } from "./postgres-array-literal.js";
+import { quoteTableIdent } from "./table-ops.js";
+// Deletes only rows a projection rebuild would not recreate: the row's stream has no events, or is archived.
+// One statement, so a stream cannot gain events between check and delete.
+export async function deleteRowsWithoutReplayableStream(db, args) {
+    if (args.ids.length === 0)
+        return [];
+    const tenantBound = isBoundTenantDb(db);
+    const tenantId = tenantBound ? db.tenantId : args.tenantId;
+    const runner = tenantBound ? tenantDbWriteRunner(db, "deleteRowsWithoutReplayableStream") : db;
+    const params = [toPostgresArrayLiteral(args.ids)];
+    let tenantFilter = "";
+    if (tenantId !== undefined) {
+        params.push(tenantId);
+        tenantFilter = `AND t."tenant_id" = $2`;
+    }
+    const rows = await asRawClient(runner).unsafe(`DELETE FROM ${quoteTableIdent(tableNameOf(args.table))} t
+     WHERE t."id" = ANY($1::uuid[]) ${tenantFilter}
+       AND NOT EXISTS (
+         SELECT 1 FROM "kumiko_events" e
+          WHERE e."tenant_id" = t."tenant_id" AND e."aggregate_id" = t."id"
+            AND NOT EXISTS (
+              SELECT 1 FROM "kumiko_archived_streams" a
+               WHERE a."tenant_id" = e."tenant_id" AND a."aggregate_id" = e."aggregate_id"
+            )
+       )
+     RETURNING t."id"`, params);
+    return rows.map((row) => row.id);
+}

package/dist/db/query.d.ts

@@ -1,9 +1,9 @@
 import type { AggregateRow, AggregateSpec } from "@cosmicdrift/kumiko-types/aggregate-types";
 import type { DbRunner, DbTx } from "@cosmicdrift/kumiko-types/db-connection";
+import type { ExecutorManagedRunner, ExecutorManagedWriteCapability, WritableTable } from "@cosmicdrift/kumiko-types/executor-brand";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { SelectOptions, WhereObject } from "@cosmicdrift/kumiko-types/where-clause-types";
 import type { EntityTableMeta } from "./entity-table-meta.ts";
-import { type NotExecutorOnly } from "./table-builder.ts";
 import { asEntityTableMeta, requireEntityTableMeta } from "./table-introspection.ts";
 export { asEntityTableMeta, requireEntityTableMeta };
 export type ReservedClient = {
@@ -23,12 +23,14 @@ export type RawClientWithBegin = RawClient & {
 export declare function hasBegin(client: RawClient): client is RawClientWithBegin;
 export declare function asRawClient(db: unknown): RawClient;
 export declare function runnerCanBeginTransaction(db: unknown): boolean;
+export declare function runInSavepoint<T>(tx: ExecutorManagedRunner, fn: (sp: ExecutorManagedRunner) => Promise<T>): Promise<T>;
 export declare function runInSavepoint<T>(tx: unknown, fn: (sp: unknown) => Promise<T>): Promise<T>;
+export declare function runInSavepointIfSupported<T>(db: ExecutorManagedRunner, fn: (sp: ExecutorManagedRunner) => Promise<T>): Promise<T>;
 export declare function runInSavepointIfSupported<T>(db: unknown, fn: (sp: DbRunner) => Promise<T>): Promise<T>;
 export type AnyDb = DbRunner | unknown;
+type AnyRow = any;
 export type { JsonTextMatch, OrderByClause, SelectOptions, WhereObject, WhereOperator, WhereValue, } from "@cosmicdrift/kumiko-types/where-clause-types";
 type TableLike = EntityTableMeta | any;
-type WritableTable = EntityTableMeta & NotExecutorOnly;
 export type TableInfo = {
     readonly name: string;
     readonly columnOf: (field: string) => string;
@@ -43,8 +45,8 @@ export declare function instantToTimestamptzParam(instant: Temporal.Instant): st
 export declare function isClosedConnectionError(err: unknown): boolean;
 export declare function describeClosedConnectionFailure(raw: unknown, err: unknown, attempts: number): Record<string, unknown> | undefined;
 export declare function unsafeReadRetrying<TRow>(db: AnyDb, sqlText: string, params: readonly unknown[]): Promise<readonly TRow[]>;
-export declare function selectMany<TRow = any>(db: AnyDb, table: TableLike, where?: WhereObject, options?: SelectOptions): Promise<readonly TRow[]>;
-export declare function fetchOne<TRow = any>(db: AnyDb, table: TableLike, where: WhereObject): Promise<TRow | undefined>;
+export declare function selectMany<TRow = AnyRow>(db: AnyDb, table: TableLike, where?: WhereObject, options?: SelectOptions): Promise<readonly TRow[]>;
+export declare function fetchOne<TRow = AnyRow>(db: AnyDb, table: TableLike, where: WhereObject): Promise<TRow | undefined>;
 export type JoinColumnPair = {
     readonly left: string;
     readonly right: string;
@@ -65,10 +67,14 @@ export type InnerJoinRow<TLeft, TRight> = {
     readonly right: TRight;
 };
 export declare function selectInnerJoin<TLeft = Record<string, unknown>, TRight = Record<string, unknown>>(db: AnyDb, spec: InnerJoinSpec): Promise<readonly InnerJoinRow<TLeft, TRight>[]>;
-export declare function insertMany<TRow = any>(db: AnyDb, table: WritableTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<readonly TRow[]>;
-export declare function insertOne<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>): Promise<TRow | undefined>;
-export declare function updateMany<TRow = any>(db: AnyDb, table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly TRow[]>;
+export declare function insertMany<TRow = AnyRow>(db: AnyDb, table: WritableTable, rows: ReadonlyArray<Record<string, unknown>>): Promise<readonly TRow[]>;
+export declare function insertMany<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, rows: ReadonlyArray<Record<string, unknown>>): Promise<readonly TRow[]>;
+export declare function insertOne<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>): Promise<TRow | undefined>;
+export declare function insertOne<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>): Promise<TRow | undefined>;
+export declare function updateMany<TRow = AnyRow>(db: AnyDb, table: WritableTable, set: Record<string, unknown>, where: WhereObject): Promise<readonly TRow[]>;
+export declare function updateMany<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, set: Record<string, unknown>, where: WhereObject): Promise<readonly TRow[]>;
 export declare function deleteMany(db: AnyDb, table: WritableTable, where: WhereObject): Promise<number>;
+export declare function deleteMany(db: ExecutorManagedWriteCapability, table: EntityTableMeta, where: WhereObject): Promise<number>;
 export declare function resolveConflictColumns(table: TableLike, info: TableInfo, conflictKeys: readonly string[] | undefined): readonly string[];
 export type UpsertOnConflictOptions = {
     readonly conflictKeys: readonly string[];
@@ -88,18 +94,23 @@ export type DeleteManyBatchedResult = {
 export declare function countWhere(db: AnyDb, table: TableLike, where?: WhereObject): Promise<number>;
 export declare function isTimestamptzType(pgType: string | undefined): boolean;
 export declare function aggregateWhere(db: AnyDb, table: TableLike, spec: AggregateSpec, where?: WhereObject): Promise<readonly AggregateRow[]>;
-export declare function upsertOnConflict<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
-export declare function upsertByPk<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+export declare function upsertOnConflict<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
+export declare function upsertOnConflict<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, options: UpsertOnConflictOptions): Promise<TRow | undefined>;
+export declare function upsertByPk<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
+export declare function upsertByPk<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, updateOnConflict?: Record<string, unknown>): Promise<TRow | undefined>;
 export type InsertOnConflictDoNothingOptions = {
     readonly conflictKeys?: readonly string[];
 };
-export declare function insertOnConflictDoNothing<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
+export declare function insertOnConflictDoNothing<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
+export declare function insertOnConflictDoNothing<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, options?: InsertOnConflictDoNothingOptions): Promise<TRow | undefined>;
 export type IncrementCounterOptions = {
     readonly conflictKeys?: readonly string[];
     /** Extra SET clauses on conflict (e.g. lastUpdatedAt: sql\`NOW()\`). */
     readonly set?: Record<string, unknown>;
 };
-export declare function incrementCounter<TRow = any>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, increments: Record<string, number>, options?: IncrementCounterOptions): Promise<TRow | undefined>;
+export declare function incrementCounter<TRow = AnyRow>(db: AnyDb, table: WritableTable, values: Record<string, unknown>, increments: Record<string, number>, options?: IncrementCounterOptions): Promise<TRow | undefined>;
+export declare function incrementCounter<TRow = AnyRow>(db: ExecutorManagedWriteCapability, table: EntityTableMeta, values: Record<string, unknown>, increments: Record<string, number>, options?: IncrementCounterOptions): Promise<TRow | undefined>;
 export declare function deleteManyBatched(db: AnyDb, table: WritableTable, where: WhereObject, options: DeleteManyBatchedOptions): Promise<DeleteManyBatchedResult>;
+export declare function deleteManyBatched(db: ExecutorManagedWriteCapability, table: EntityTableMeta, where: WhereObject, options: DeleteManyBatchedOptions): Promise<DeleteManyBatchedResult>;
 export declare function transaction<T>(db: AnyDb, fn: (tx: DbTx) => Promise<T>): Promise<T>;
 export declare function runInNewTransaction<T>(db: unknown, fn: (tx: DbRunner) => Promise<T>): Promise<T>;

package/dist/db/query.js

@@ -24,6 +24,7 @@ import { InternalError } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/index.js";
 import { parseJsonSafe } from "../utils/safe-json.js";
 import { SQL_EXPR_BRAND } from "./dialect.js";
+import { executorManagedWriteDenied } from "./executor-managed-tables.js";
 import { extractPgError } from "./pg-error.js";
 import { toSnakeCase } from "./table-builder.js";
 import { asEntityTableMeta, requireEntityTableMeta } from "./table-introspection.js";
@@ -77,42 +78,27 @@ export function asRawClient(db) {
 export function runnerCanBeginTransaction(db) {
     return hasBegin(asRawClient(db));
 }
-// postgres.js rejects the WHOLE begin() when any statement inside
-// it errored — even if the JS error was caught (the driver tracks per-block
-// query failures). Error confinement therefore must go through the driver's
-// own savepoint(), not manual SAVEPOINT statements. The callback receives
-// the savepoint-scoped tx; run every confined statement on THAT handle.
+function savepointRunnerOf(sp) {
+    // @cast-boundary db-runner savepoint handle → TRunner at the single seam (boundRunner re-wraps savepoint handles with the caller's capability)
+    return sp;
+}
 export async function runInSavepoint(tx, fn) {
     const raw = asRawClient(tx);
     if (typeof raw.savepoint !== "function") {
         throw new Error("runInSavepoint: transaction handle has no savepoint() — pass the driver tx (postgres.js TransactionSql).");
     }
-    return raw.savepoint(fn);
+    return raw.savepoint((sp) => fn(savepointRunnerOf(sp)));
 }
-// Same error-confinement as runInSavepoint, but for call sites that don't
-// know whether `db` is a bare pool connection or an active transaction
-// (e.g. the CRUD executor, invoked both from a dispatcher tx and directly
-// against the pool by seeds/tests). A pool connection has no savepoint() —
-// and doesn't need one, since each statement there is its own auto-committed
-// unit and a failed statement can't poison anything downstream.
-//
-// `.savepoint` being present isn't proof the transaction is still open: a
-// committed TransactionSql-shaped db still exposes `.savepoint`, and calling
-// it fails with PG 25P01 ("no active sql transaction") since there's no
-// BEGIN left to nest into. That is now a programming error, not something
-// to paper over by re-running `fn` without the savepoint's isolation.
 export async function runInSavepointIfSupported(db, fn) {
     const raw = asRawClient(db);
-    // @cast-boundary db-runner savepoint handle → DbRunner at the single seam
-    const asRunner = (sp) => sp;
     if (typeof raw.savepoint !== "function")
-        return fn(asRunner(db));
+        return fn(savepointRunnerOf(db));
     // An error from inside fn must never be remapped, even if it carries a closed-connection code.
     let fnStarted = false;
     try {
         return await raw.savepoint((sp) => {
             fnStarted = true;
-            return fn(asRunner(sp));
+            return fn(savepointRunnerOf(sp));
         });
     }
     catch (e) {
@@ -869,7 +855,6 @@ function selectColumnList(info, fields) {
     })
         .join(", ");
 }
-// biome-ignore lint/suspicious/noExplicitAny: opt-in default loosens row type for unannotated test fixtures
 export async function selectMany(db, table, where, options) {
     const scoped = tenantDbDelegate(db);
     if (scoped) {
@@ -904,7 +889,6 @@ export async function selectMany(db, table, where, options) {
     const raw = await unsafeReadRetrying(db, sqlText, values);
     return coerceRows(raw, info);
 }
-// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function fetchOne(db, table, where) {
     const rows = await selectMany(db, table, where, { limit: 1 });
     return rows[0];
@@ -979,14 +963,13 @@ export async function selectInnerJoin(db, spec) {
         };
     });
 }
-// Bulk INSERT — same shape as insertOne but takes an array of rows and
-// produces one multi-VALUES statement. Mirrors drizzle's
-// `db.insert(t).values(rows[])`. Empty input is a no-op.
-// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function insertMany(db, table, rows) {
     if (rows.length === 0)
         return [];
     assertNotTenantScoped(db, "insertMany");
+    const managedDenied = executorManagedWriteDenied(db, table, "insertMany");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     // Use the column-set from the first row; assume all rows share keys.
     const firstRow = rows[0];
@@ -1022,12 +1005,14 @@ export async function insertMany(db, table, rows) {
     });
     return coerceRows(raw, info);
 }
-// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function insertOne(db, table, values) {
     const scoped = tenantDbDelegate(db);
     if (scoped) {
         return scoped.insertOne(table, values);
     }
+    const managedDenied = executorManagedWriteDenied(db, table, "insertOne");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const entries = Object.entries(values)
         .filter(([k]) => info.hasColumn(k))
@@ -1058,12 +1043,14 @@ export async function insertOne(db, table, values) {
         return undefined;
     return coerceRow(first, info);
 }
-// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function updateMany(db, table, set, where) {
     const scoped = tenantDbDelegate(db);
     if (scoped) {
         return scoped.updateMany(table, set, where);
     }
+    const managedDenied = executorManagedWriteDenied(db, table, "updateMany");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const setEntries = Object.entries(set).map(([k, v]) => {
         const col = info.columnOf(k);
@@ -1103,6 +1090,9 @@ export async function deleteMany(db, table, where) {
     if (scoped) {
         return scoped.deleteMany(table, where);
     }
+    const managedDenied = executorManagedWriteDenied(db, table, "deleteMany");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const w = buildWhereClause(info, where, 1);
     let sqlText = `DELETE FROM ${quoteIdent(info.name)}`;
@@ -1277,9 +1267,15 @@ export async function aggregateWhere(db, table, spec, where = {}) {
         };
     });
 }
-// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
-export async function upsertOnConflict(db, table, values, options) {
+export function upsertOnConflict(db, table, values, options) {
+    return upsertOnConflictChecked(db, table, values, options);
+}
+// upsertByPk shares this body; the checks inside gate the write, so it needs no overload pair.
+async function upsertOnConflictChecked(db, table, values, options) {
     assertNotTenantScoped(db, "upsertOnConflict");
+    const managedDenied = executorManagedWriteDenied(db, table, "upsertOnConflict");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const entries = insertEntries(info, values);
     const conflictCols = resolveConflictColumns(table, info, options.conflictKeys);
@@ -1321,19 +1317,23 @@ export async function upsertOnConflict(db, table, values, options) {
         return undefined;
     return coerceRow(first, info);
 }
-// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function upsertByPk(db, table, values, updateOnConflict) {
+    const managedDenied = executorManagedWriteDenied(db, table, "upsertByPk");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const conflictKeys = resolveConflictColumns(table, info, undefined);
     const fieldKeys = conflictKeys.map((col) => info.fieldOf(col));
-    return upsertOnConflict(db, table, values, {
+    return upsertOnConflictChecked(db, table, values, {
         conflictKeys: fieldKeys,
         ...(updateOnConflict !== undefined ? { update: updateOnConflict } : {}),
     });
 }
-// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function insertOnConflictDoNothing(db, table, values, options) {
     assertNotTenantScoped(db, "insertOnConflictDoNothing");
+    const managedDenied = executorManagedWriteDenied(db, table, "insertOnConflictDoNothing");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const entries = insertEntries(info, values);
     const conflictCols = resolveConflictColumns(table, info, options?.conflictKeys);
@@ -1349,9 +1349,11 @@ export async function insertOnConflictDoNothing(db, table, values, options) {
         return undefined;
     return coerceRow(first, info);
 }
-// biome-ignore lint/suspicious/noExplicitAny: see selectMany default
 export async function incrementCounter(db, table, values, increments, options = {}) {
     assertNotTenantScoped(db, "incrementCounter");
+    const managedDenied = executorManagedWriteDenied(db, table, "incrementCounter");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const entries = insertEntries(info, values);
     const conflictCols = resolveConflictColumns(table, info, options.conflictKeys);
@@ -1402,6 +1404,9 @@ export async function incrementCounter(db, table, values, increments, options =
     return coerceRow(first, info);
 }
 export async function deleteManyBatched(db, table, where, options) {
+    const managedDenied = executorManagedWriteDenied(db, table, "deleteManyBatched");
+    if (managedDenied)
+        throw managedDenied;
     const info = extractTableInfo(table);
     const w = buildWhereClause(info, where, 1);
     if (!w.sqlText) {

package/dist/db/reference-data.d.ts

@@ -1,14 +1,15 @@
+import type { Registry } from "../engine/index.ts";
 import type { ReferenceDataDef } from "../engine/types/index.ts";
 import type { DbConnection } from "./connection.ts";
-import type { TableColumns } from "./dialect.ts";
-type Table = TableColumns<any>;
 /**
  * Seed reference data at boot time.
  * For each ReferenceDataDef: upsert rows (insert missing, update changed, never delete).
  * Upsert key defaults to the first field in the data object.
+ *
+ * Rows go through the entity's event-store executor as the system user in the
+ * SYSTEM_TENANT_ID stream, so the seed is replayable on a projection rebuild.
  */
-export declare function seedReferenceData(defs: readonly ReferenceDataDef[], tables: ReadonlyMap<string, Table>, db: DbConnection): Promise<{
+export declare function seedReferenceData(defs: readonly ReferenceDataDef[], registry: Registry, db: DbConnection): Promise<{
     inserted: number;
     updated: number;
 }>;
-export {};

package/dist/db/reference-data.js

@@ -1,21 +1,26 @@
-import { fetchOne, insertOne, updateMany } from "../db/query.js";
+import { fetchOne } from "../db/query.js";
+import { createSystemUser } from "../engine/system-user.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/index.js";
-import { tableColumnsOf } from "./table-introspection.js";
-function hasColumn(table, field) {
-    const cols = tableColumnsOf(table);
-    return cols !== undefined && field in cols;
-}
+import { reraiseAsKumikoError } from "../errors/index.js";
+import { entityTableFromRegistry } from "./entity-table-from-registry.js";
+import { createEventStoreExecutor } from "./event-store-executor.js";
+import { createTenantDb } from "./tenant-db.js";
 /**
  * Seed reference data at boot time.
  * For each ReferenceDataDef: upsert rows (insert missing, update changed, never delete).
  * Upsert key defaults to the first field in the data object.
+ *
+ * Rows go through the entity's event-store executor as the system user in the
+ * SYSTEM_TENANT_ID stream, so the seed is replayable on a projection rebuild.
  */
-export async function seedReferenceData(defs, tables, db) {
+export async function seedReferenceData(defs, registry, db) {
     let inserted = 0;
     let updated = 0;
+    const by = createSystemUser(SYSTEM_TENANT_ID);
+    const tdb = createTenantDb({ db, tenantId: SYSTEM_TENANT_ID, mode: "system" });
     for (const def of defs) {
-        const table = tables.get(def.entityName);
-        if (!table)
+        const entity = registry.getEntity(def.entityName);
+        if (!entity)
             continue;
         if (def.data.length === 0)
             continue;
@@ -26,11 +31,13 @@ export async function seedReferenceData(defs, tables, db) {
         if (!firstKey)
             continue;
         const upsertKey = def.upsertKey ?? firstKey;
+        const table = entityTableFromRegistry(registry, def.entityName, entity);
+        const executor = createEventStoreExecutor(table, entity, { entityName: def.entityName });
         for (const row of def.data) {
             const keyValue = row[upsertKey];
             if (keyValue === undefined)
                 continue;
-            const existing = (await fetchOne(db, table, { [upsertKey]: keyValue }));
+            const existing = await fetchOne(db, table, { [upsertKey]: keyValue });
             if (existing) {
                 const changes = {};
                 for (const [field, value] of Object.entries(row)) {
@@ -41,21 +48,16 @@ export async function seedReferenceData(defs, tables, db) {
                     }
                 }
                 if (Object.keys(changes).length > 0) {
-                    await updateMany(db, table, changes, { [upsertKey]: keyValue });
+                    const result = await executor.update({ id: existing.id, version: existing.version, changes }, by, tdb);
+                    if (!result.isSuccess)
+                        throw reraiseAsKumikoError(result.error);
                     updated++;
                 }
             }
             else {
-                // Only add framework columns if the table actually has them.
-                // Drizzle used to filter extra fields silently; bunInsertOne doesn't.
-                const values = { ...row };
-                if (hasColumn(table, "tenantId"))
-                    values["tenantId"] = SYSTEM_TENANT_ID;
-                if (hasColumn(table, "version"))
-                    values["version"] = 1;
-                if (hasColumn(table, "insertedAt"))
-                    values["insertedAt"] = Temporal.Now.instant();
-                await insertOne(db, table, values);
+                const result = await executor.create({ ...row, tenantId: SYSTEM_TENANT_ID }, by, tdb);
+                if (!result.isSuccess)
+                    throw reraiseAsKumikoError(result.error);
                 inserted++;
             }
         }

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

@@ -1,5 +1,4 @@
 /// <reference types="temporal-polyfill/global" preserve="true" />
-import type { ExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 import type { TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import type { EntityDefinition, EntityRelations, FieldDefinition, FieldsMap } from "../engine/types/index.ts";
 import type { Table } from "./event-store-executor-context.ts";
@@ -194,11 +193,11 @@ type Flatten<T> = {
 /** The row `executor.list()` / `executor.detail()` return for entity `E`. A wide
  *  `EntityDefinition` (fields without literal keys) yields `Record<string, unknown>`. */
 export type EntityRow<E extends EntityDefinition = EntityDefinition> = string extends keyof E["fields"] ? Record<string, unknown> : Flatten<RowOfColumns<BaseColumnsType<E>> & SoftDeleteRow<E> & RowForFields<E["fields"]>>;
-export type { ExecutorOnly, NotExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
+export type { ExecutorManagedRunner, ExecutorManagedWriteCapability, Writable, WritableSchemaTable, WritableTable, } from "@cosmicdrift/kumiko-types/executor-brand";
 export type { EntityTenancy, TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 type EntityTableTenancy<E extends EntityDefinition> = [NonNullable<E["tenancy"]>] extends [never] ? "tenant" : [NonNullable<E["tenancy"]>] extends ["global"] ? "global" : "tenant";
 export type EntityTable<E extends EntityDefinition = EntityDefinition> = TableColumns<// biome-ignore lint/suspicious/noExplicitAny: drizzle's internal table-config stays generic; we layer typed columns on top via the intersection below.
-any> & BaseColumnsType<E> & SoftDeleteColumnsType & ColumnsForEntity<E["fields"]> & ExecutorOnly & TenancyBrand<EntityTableTenancy<E>>;
+any> & BaseColumnsType<E> & SoftDeleteColumnsType & ColumnsForEntity<E["fields"]> & TenancyBrand<EntityTableTenancy<E>>;
 export declare function buildBaseColumns(softDelete: boolean, idType?: "serial" | "uuid"): {
     id: ColumnBuilder<string> | ColumnBuilder<number>;
     tenantId: ColumnBuilder<string>;

package/dist/db/table-builder.js

@@ -1,6 +1,7 @@
 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";
 import { bigint, boolean, decimalColumn, doublePrecision, index, instant, integer, isSqlExpression, jsonb, moneyAmount, table as pgTable, plainDate, serial, sql, text, uniqueIndex, uuid, } from "./dialect.js";
@@ -420,5 +421,6 @@ export function buildEntityTable(entityName, entity, options) {
         return indexes;
     });
     stampEntityTableMeta(built, entity);
+    markExecutorManagedTable(built);
     return built;
 }

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

@@ -1,4 +1,5 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
+import type { Writable } from "@cosmicdrift/kumiko-types/executor-brand";
 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;
@@ -14,3 +15,4 @@ export declare function columnHandleName(table: unknown, field: string): string
 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;
+export declare function brandWritable<T extends EntityTableMeta>(table: T): T & Writable;

package/dist/db/table-introspection.js

@@ -74,3 +74,7 @@ export function columnSqlNameOf(table, field) {
     const name = handle["name"];
     return typeof name === "string" ? name : undefined;
 }
+export function brandWritable(table) {
+    // @cast-boundary phantom-brand — Writable is a phantom marker with no runtime representation.
+    return table;
+}

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

@@ -1,6 +1,8 @@
 import type { TenantDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { InternalError } from "../errors/index.ts";
 import type { DbRunner } from "./connection.ts";
+export declare function isBoundTenantDb(value: unknown): value is TenantDb;
+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;

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

@@ -1,5 +1,12 @@
+import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { InternalError } from "../errors/index.js";
 const tenantDbRunners = new WeakMap();
+export function isBoundTenantDb(value) {
+    return typeof value === "object" && value !== null && tenantDbRunners.has(value);
+}
+export function isDbRunner(value) {
+    return typeof propertyOf(value, "unsafe") === "function";
+}
 export function bindTenantDbRunner(tenantDb, runner) {
     tenantDbRunners.set(tenantDb, runner);
 }

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

@@ -1,7 +1,8 @@
 import type { EntityTableMeta } from "@cosmicdrift/kumiko-types/entity-table-meta-types";
+import type { ExecutorManagedRunner } from "@cosmicdrift/kumiko-types/executor-brand";
 import type { EscapeHatchDeclaration, EscapeHatchReporter, EscapeHatchTarget } from "@cosmicdrift/kumiko-types/handlers";
 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 { type ExecutorManagedTenantDb, type TenantDb, type TenantDbMode, type UncheckedSystemDb } from "@cosmicdrift/kumiko-types/tenant-db-types";
 import { asRawClient } from "../db/query.ts";
 import type { EntityDefinition } from "../engine/types/fields.ts";
 import { type TenantId } from "../engine/types/identifiers.ts";
@@ -10,7 +11,9 @@ import { type Meter, type Tracer } from "../observability/index.ts";
 import type { DbRunner } from "./connection.ts";
 import { tableNameOf } from "./table-introspection.ts";
 type Table = SchemaTable;
-export { SYSTEM_SCOPE_CHECK_BRAND, type TenantDb, type TenantDbMode, type UncheckedSystemDb, } from "@cosmicdrift/kumiko-types/tenant-db-types";
+export { type ExecutorManagedTenantDb, SYSTEM_SCOPE_CHECK_BRAND, type TenantDb, type TenantDbMode, type UncheckedSystemDb, } from "@cosmicdrift/kumiko-types/tenant-db-types";
+export declare function withExecutorManagedWrites(runner: DbRunner): ExecutorManagedRunner;
+export declare function withoutExecutorManagedWrites(runner: DbRunner): DbRunner;
 export declare function assertPersonalDataWrite(db: TenantDb, tableName: string, keys: readonly string[], entity: EntityDefinition): void;
 export declare function unsafeRawForDeclaredStep(holder: TenantDb | UncheckedSystemDb, reason: string): DbRunner;
 export declare function withSystemDbUnsafeRawGrant(systemDb: UncheckedSystemDb, grant: EscapeHatchDeclaration | undefined, deniedCallerLabel: string): UncheckedSystemDb;
@@ -53,6 +56,10 @@ export type CreateTenantDbOptions = {
     readonly signal?: AbortSignal;
     readonly grants?: TenantDbGrants;
 };
+export declare function createTenantDb(options: CreateTenantDbOptions & {
+    readonly db: ExecutorManagedRunner;
+}): ExecutorManagedTenantDb;
 export declare function createTenantDb(options: CreateTenantDbOptions): TenantDb;
+export declare function createTenantDataDestroyDb(options: Omit<CreateTenantDbOptions, "mode">): ExecutorManagedTenantDb;
 export declare function createProjectingTenantDb(db: DbRunner, tenantId: TenantId, projectionRegistry: Registry | undefined): TenantDb;
 export { asRawClient };