@cosmicdrift/kumiko-framework 0.378.0 → 0.380.0

package/dist/api/sse-route.js

@@ -1,5 +1,6 @@
 import { Hono } from "hono";
 import { streamSSE } from "hono/streaming";
+import { hasAccess } from "../engine/access.js";
 import { tenantChannel } from "../engine/constants.js";
 import { isAnonymousSessionUser } from "../engine/system-user.js";
 import { Routes } from "./api-constants.js";
@@ -40,6 +41,11 @@ function isEntityEventData(data) {
 // cookie is stale. A downgraded stream answers 200, so EventSource never reports the
 // session end by itself.
 const SESSION_ENDED_SSE_EVENT = "session-ended";
+// A broadcast batch legitimately queues many frames at once, so a client is dropped for
+// making no progress, not for queue depth.
+export const SSE_STALLED_CLIENT_TIMEOUT_MS = SSE_HEARTBEAT_INTERVAL_MS;
+// Memory backstop only: a client that still makes progress but queues this many frames is dropped.
+export const SSE_MAX_PENDING_WRITES_PER_CLIENT = 10_000;
 // Whitelist, never a spread: the wire frame is a signal without field
 // values even if a broker or pusher put a payload into event.data.
 function toEntitySignalWire(event, data) {
@@ -68,16 +74,26 @@ function isAddressedTo(event, userId) {
     const addressee = event.data["userId"];
     return typeof addressee === "string" && addressee === userId;
 }
-function mayReceiveEntitySignal(user, aggregateType, options) {
-    return !isAnonymousSessionUser(user) || options.anonymousLiveEntities.has(aggregateType);
+// A role-gated rule means every holder may read every row, so id and version leak nothing.
+// An openToAll rule leaves row visibility to the handler (e.g. an owner check on form drafts),
+// which the signal cannot know: such a connection only learns that the entity changed.
+function entitySignalDetail(user, aggregateType, options) {
+    if (isAnonymousSessionUser(user)) {
+        return options.anonymousLiveEntities.has(aggregateType) ? "anonymous" : "none";
+    }
+    const granting = (options.entityReadAccess.get(aggregateType) ?? []).filter((rule) => hasAccess(user, rule));
+    if (granting.length === 0)
+        return "none";
+    return granting.some((rule) => "roles" in rule) ? "identified" : "anonymous";
 }
 function decideWireFrame(event, user, options) {
     const data = event.data;
     if (isEntityEventData(data)) {
-        // skip: anonymous connections only get signals for entities an anonymous query declares
-        if (!mayReceiveEntitySignal(user, data.aggregateType, options))
+        // skip: connections only get signals for entities a query lets their roles read
+        const detail = entitySignalDetail(user, data.aggregateType, options);
+        if (detail === "none")
             return undefined;
-        const signal = isAnonymousSessionUser(user)
+        const signal = detail === "anonymous"
             ? toAnonymousEntitySignalWire(event, data)
             : toEntitySignalWire(event, data);
         return { name: data.aggregateType, data: signal };
@@ -88,6 +104,7 @@ function decideWireFrame(event, user, options) {
     return { name: event.type, data };
 }
 export function createSseRoute(broker, options) {
+    const now = options.now ?? Date.now;
     const route = new Hono();
     route.get(Routes.sse, async (c) => {
         const user = getUser(c);
@@ -116,12 +133,41 @@ export function createSseRoute(broker, options) {
                 resolveEnded();
                 void stream.close();
             };
+            let pendingWrites = 0;
+            let lastProgressAt = now();
+            const isStalled = () => pendingWrites > 0 && now() - lastProgressAt > SSE_STALLED_CLIENT_TIMEOUT_MS;
             const clientId = broker.addClient(channel, (event) => {
-                const frame = decideWireFrame(event, user, options);
-                // skip: decideWireFrame withholds frames this user must not see
-                if (!frame)
+                // skip: the stream is already being torn down
+                if (stream.aborted || stream.closed)
                     return;
-                stream.writeSSE({ event: frame.name, data: JSON.stringify(frame.data) });
+                // The broker loops over all clients synchronously: one bad client must not stop the others.
+                try {
+                    const frame = decideWireFrame(event, user, options);
+                    // skip: decideWireFrame withholds frames this user must not see
+                    if (!frame)
+                        return;
+                    if (pendingWrites >= SSE_MAX_PENDING_WRITES_PER_CLIENT || isStalled()) {
+                        // abort (not close) cancels the pending writes; close would queue behind them
+                        stream.abort();
+                        // skip: this client is gone, the frame has no audience
+                        return;
+                    }
+                    const data = JSON.stringify(frame.data);
+                    if (pendingWrites === 0)
+                        lastProgressAt = now();
+                    pendingWrites += 1;
+                    stream
+                        .writeSSE({ event: frame.name, data })
+                        .catch(closeStream)
+                        .finally(() => {
+                        pendingWrites -= 1;
+                        lastProgressAt = now();
+                    });
+                }
+                catch {
+                    // skip: an unserializable frame ends this client's stream, not the broadcast
+                    closeStream();
+                }
             }, closeStream);
             const unsubscribeAccessInvalidation = broker.subscribeAccessInvalidation(user.id, closeStream, accessInvalidationCredentialFor(user));
             const expiryTimer = scheduleTokenExpiry(tokenExpiresAtSec, closeStream);
@@ -142,6 +188,10 @@ export function createSseRoute(broker, options) {
             // header für die Layer-für-Layer-Begründung der 15s-Cadence.
             try {
                 while (!stream.closed && !stream.aborted) {
+                    if (isStalled()) {
+                        stream.abort();
+                        break;
+                    }
                     await stream.writeSSE({ event: "ping", data: "" });
                     await Promise.race([stream.sleep(SSE_HEARTBEAT_INTERVAL_MS), ended]);
                 }

package/dist/db/apply-entity-event.d.ts

@@ -1,6 +1,7 @@
+import type { ExecutorManagedRunner } from "@cosmicdrift/kumiko-types/executor-brand";
 import type { EntityDefinition } from "../engine/types/index.ts";
 import type { StoredEvent } from "../event-store/index.ts";
-import type { DbRow, DbRunner } from "./connection.ts";
+import type { DbRow } from "./connection.ts";
 import type { TableColumns } from "./dialect.ts";
 type Table = TableColumns<any>;
 export type AutoVerb = "created" | "updated" | "deleted" | "restored" | "forgotten";
@@ -17,5 +18,5 @@ export declare function parseAutoVerb(event: StoredEvent): AutoVerb | null;
 /** Idempotente Anwendung eines Auto-Events auf die Entity-Tabelle.
  *  Wird sowohl beim Live-Append (innerhalb der Write-TX) als auch beim
  *  Rebuild (innerhalb der Rebuild-TX) gerufen — identische Logik. */
-export declare function applyEntityEvent(event: StoredEvent, table: Table, entity: EntityDefinition, tx: DbRunner): Promise<ApplyResult>;
+export declare function applyEntityEvent(event: StoredEvent, table: Table, entity: EntityDefinition, tx: ExecutorManagedRunner): Promise<ApplyResult>;
 export {};

package/dist/db/apply-entity-event.js

@@ -14,7 +14,7 @@
 // (DEK erased → Wert unlesbar, bidx NULL). Load-bearing Test:
 // db/__tests__/implicit-projection-equivalence.integration.test.ts.
 //
-// Tenant isolation: applyEntityEvent expects a raw DbRunner (tx or pool), NOT
+// Tenant isolation: applyEntityEvent expects an ExecutorManagedRunner (tx or pool), NOT
 // a TenantDb wrapper. Two sources keep it safe:
 //   1. The live path reads the target row through the tenant-scoped TenantDb
 //      before writing — loadById() for update/delete/forget, db.fetchOne() for

package/dist/db/dialect.d.ts

@@ -1,3 +1,4 @@
+import type { WritableSchemaTable } from "@cosmicdrift/kumiko-types/executor-brand";
 import { type ColumnHandle, type SchemaTable } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
 import type { PgType } from "./entity-table-meta.ts";
@@ -94,7 +95,7 @@ export type ColumnMap = Record<string, ColumnBuilder<unknown>>;
 type IndexOrPk = IndexBuilderWithCols | PrimaryKeyDescriptor;
 export declare function table<TCols extends ColumnMap>(tableName: string, cols: TCols, optsFn?: (t: {
     [K in keyof TCols]: ColumnHandle;
-}) => Record<string, IndexOrPk> | ReadonlyArray<IndexOrPk>): SchemaTable;
+}) => Record<string, IndexOrPk> | ReadonlyArray<IndexOrPk>): WritableSchemaTable;
 /** Reads the `kumiko:schema:Name` symbol from a table object.
  *  Throws with `context` in the message so callers don't have to duplicate the guard. */
 export declare function extractTableName(table: unknown, context?: string): string;

package/dist/db/dialect.js

@@ -18,7 +18,7 @@
 // crashed on timestamptz writes without it (#1480).
 import { KUMIKO_COLUMNS_SYMBOL, KUMIKO_META_SYMBOL, KUMIKO_NAME_SYMBOL, } from "@cosmicdrift/kumiko-types/schema-table-types";
 import { Temporal } from "@cosmicdrift/kumiko-types/temporal";
-import { schemaTableName } from "./table-introspection.js";
+import { brandWritable, schemaTableName } from "./table-introspection.js";
 function isNumericPgType(t) {
     return t.startsWith("numeric(");
 }
@@ -376,7 +376,7 @@ export function table(tableName, cols, optsFn) {
         [KUMIKO_COLUMNS_SYMBOL]: handles,
         [KUMIKO_META_SYMBOL]: base,
     });
-    return out;
+    return brandWritable(out);
 }
 /** Reads the `kumiko:schema:Name` symbol from a table object.
  *  Throws with `context` in the message so callers don't have to duplicate the guard. */

package/dist/db/entity-table-from-registry.js

@@ -17,8 +17,6 @@ export function entityTableFromRegistry(registry, entityName, entity) {
             continue;
         if (projection.source !== entityName)
             continue;
-        // @cast-boundary projection-table — ProjectionDefinition.table is the
-        // untyped table object every projection registrar accepts.
         return projection.table;
     }
     return buildEntityTable(entityName, entity);

package/dist/db/entity-table-meta.d.ts

@@ -1,3 +1,4 @@
+import type { Writable } from "@cosmicdrift/kumiko-types/executor-brand";
 import type { EntityTenancy, TenancyBrand } from "@cosmicdrift/kumiko-types/tenancy-brand";
 import type { EntityDefinition } from "../engine/types/index.ts";
 import type { BuildEntityTableMetaOptions, EntityTableMeta, UnmanagedTableInput } from "./entity-table-meta-types.ts";
@@ -12,9 +13,10 @@ export declare function resolveTableName(entityName: string, entity: EntityDefin
  * Named `derive*` (not `build*Meta`) so it is not mistaken for the unmanaged
  * escape hatch (#1208).
  */
+export declare function deriveEntityTableMeta(entityName: string, entity: EntityDefinition, options: BuildEntityTableMetaOptions & {
+    readonly source: "unmanaged";
+}): EntityTableMeta & Writable;
 export declare function deriveEntityTableMeta(entityName: string, entity: EntityDefinition, options?: BuildEntityTableMetaOptions): EntityTableMeta;
-/** @deprecated Use {@link deriveEntityTableMeta} — the old name read as an unmanaged escape hatch (#1208). */
-export declare const buildEntityTableMeta: typeof deriveEntityTableMeta;
 export declare function assertBackingTableSuperset(entityName: string, fieldMeta: EntityTableMeta, tableMeta: EntityTableMeta): void;
 /**
  * Hand-built EntityTableMeta for direct-write stores (no entity base columns).
@@ -27,4 +29,4 @@ export declare function assertBackingTableSuperset(entityName: string, fieldMeta
  */
 export declare function defineUnmanagedTable<const T extends EntityTenancy = "tenant">(input: UnmanagedTableInput & {
     readonly tenancy?: T;
-}): EntityTableMeta & TenancyBrand<T>;
+}): EntityTableMeta & TenancyBrand<T> & Writable;

package/dist/db/entity-table-meta.js

@@ -18,6 +18,7 @@
 import { collectPiiEncryptedFields, isRecordKeyedField } from "../crypto/index.js";
 import { isSqlExpression } from "./dialect.js";
 import { READ_MODEL_PREFIX, SOFT_DELETE_LIVE_ROW_PREDICATE, toSnakeCase, toTableName, } from "./table-builder.js";
+import { brandWritable } from "./table-introspection.js";
 // Standard base columns for event-sourced read-model tables. Mirrors
 // `buildBaseColumns()` from table-builder.ts (drizzle variant).
 function fullBaseColumns(idType, softDelete) {
@@ -206,20 +207,11 @@ export function resolveTableName(entityName, entity, featureName) {
     }
     return `${featureName}_${baseName}`;
 }
-/**
- * Derive EntityTableMeta from an EntityDefinition (base columns + field DDL).
- * Defaults to `source: "managed"` (rebuildable projection). For direct-write
- * stores pass `{ source: "unmanaged" }` and use a non-`read_` table name
- * (convention: `store_*`) — or build columns by hand with `defineUnmanagedTable`.
- *
- * Named `derive*` (not `build*Meta`) so it is not mistaken for the unmanaged
- * escape hatch (#1208).
- */
 export function deriveEntityTableMeta(entityName, entity, options) {
     const tableName = resolveTableName(entityName, entity, options?.featureName);
     const source = options?.source ?? "managed";
     if (source === "unmanaged") {
-        assertUnmanagedTableName(tableName, "deriveEntityTableMeta/buildEntityTableMeta");
+        assertUnmanagedTableName(tableName, "deriveEntityTableMeta");
     }
     const idType = entity.idType ?? "uuid";
     if (source === "unmanaged" && idType === "serial") {
@@ -345,7 +337,7 @@ export function deriveEntityTableMeta(entityName, entity, options) {
         }
     }
     const piiSubjectFields = collectPiiEncryptedFields(entity);
-    return {
+    const meta = {
         tableName,
         columns,
         indexes,
@@ -353,9 +345,8 @@ export function deriveEntityTableMeta(entityName, entity, options) {
         ...(piiSubjectFields.length > 0 && { piiSubjectFields }),
         ...(entity.tenancy === "global" && { tenancy: "global" }),
     };
+    return source === "unmanaged" ? brandWritable(meta) : meta;
 }
-/** @deprecated Use {@link deriveEntityTableMeta} — the old name read as an unmanaged escape hatch (#1208). */
-export const buildEntityTableMeta = deriveEntityTableMeta;
 function sqlExpressionText(where) {
     return isSqlExpression(where) ? where.text : undefined;
 }
@@ -407,7 +398,7 @@ export function defineUnmanagedTable(input) {
             "have a tenant_id column — a global table's rows carry the system tenant, not a per-row " +
             "tenant identity.");
     }
-    return {
+    return brandWritable({
         tableName: input.tableName,
         columns: input.columns,
         indexes: input.indexes ?? [],
@@ -417,7 +408,7 @@ export function defineUnmanagedTable(input) {
         source: "unmanaged",
         ...(input.tenancy === "global" && { tenancy: "global" }),
         // @cast-boundary phantom-brand — TenancyBrand<T> is a phantom marker with no runtime representation.
-    };
+    });
 }
 function assertUnmanagedTableName(tableName, via) {
     if (tableName.startsWith("read_")) {

package/dist/db/event-store-executor-write.js

@@ -15,8 +15,13 @@ import { buildEventMetadata, entityEventName, isForeignTenantOnGlobalEntity, own
 import { isFrameworkSystemUser, isLockGuardBypassed } from "./lock-guard.js";
 import { projectionRegistryOf } from "./projection-registry-binding.js";
 import { runInSavepointIfSupported } from "./query.js";
-import { assertPersonalDataWrite, tableNameOf } from "./tenant-db.js";
+import { assertPersonalDataWrite, tableNameOf, withExecutorManagedWrites } from "./tenant-db.js";
 import { tenantDbWriteRunner } from "./tenant-db-runner.js";
+// The echoed event carries entity PII and must never reach a handler's JSON response, while
+// hooks and projections still read it by property. Non-enumerable keeps it out of spread/stringify.
+function withoutEventInJson(result) {
+    return Object.defineProperty(result, "event", { value: result.event, enumerable: false });
+}
 // Custom projections for a write that did not go through the dispatcher (hook or
 // job writing a second aggregate). Savepoint like applyEntityEvent: a throwing
 // projection fails the write and the caller's transaction rolls it back.
@@ -338,7 +343,7 @@ export function createWriteVerbs(ctx) {
             // failed INSERT back; the error still propagates and stays catchable.
             let result;
             try {
-                result = await runInSavepointIfSupported(runner, async (sp) => applyEntityEvent(event, table, entity, sp));
+                result = await runInSavepointIfSupported(withExecutorManagedWrites(runner), async (sp) => applyEntityEvent(event, table, entity, sp));
             }
             catch (e) {
                 const mapped = tryMapUniqueViolation(e, entityName);
@@ -362,7 +367,7 @@ export function createWriteVerbs(ctx) {
             await projectEntityEvent(db, runner, echoEvent);
             return {
                 isSuccess: true,
-                data: {
+                data: withoutEventInJson({
                     kind: "save",
                     id: aggregateId,
                     data: projection,
@@ -373,7 +378,7 @@ export function createWriteVerbs(ctx) {
                     // Persisted event carries ciphertext by design — the caller-facing
                     // echo must be plaintext like every other response field (#820).
                     event: echoEvent,
-                },
+                }),
             };
         },
         async update(payload, user, db, updateOptions) {
@@ -560,7 +565,7 @@ export function createWriteVerbs(ctx) {
                 // failed nested one throws 500 instead of failing cleanly.
                 let result;
                 try {
-                    result = await runInSavepointIfSupported(runner, async (sp) => applyEntityEvent(event, table, entity, sp));
+                    result = await runInSavepointIfSupported(withExecutorManagedWrites(runner), async (sp) => applyEntityEvent(event, table, entity, sp));
                 }
                 catch (e) {
                     const mapped = tryMapUniqueViolation(e, entityName);
@@ -586,7 +591,7 @@ export function createWriteVerbs(ctx) {
                 await projectEntityEvent(db, runner, echoEvent);
                 return {
                     isSuccess: true,
-                    data: {
+                    data: withoutEventInJson({
                         kind: "save",
                         id: data["id"], // @cast-boundary engine-payload
                         data,
@@ -595,7 +600,7 @@ export function createWriteVerbs(ctx) {
                         isNew: false,
                         entityName,
                         event: echoEvent,
-                    },
+                    }),
                 };
             }
             catch (e) {
@@ -688,7 +693,7 @@ export function createWriteVerbs(ctx) {
                 throw e;
             }
             // Live==Rebuild via applyEntityEvent. Savepoint like create/update.
-            const deleteResult = await runInSavepointIfSupported(runner, async (sp) => applyEntityEvent(event, table, entity, sp));
+            const deleteResult = await runInSavepointIfSupported(withExecutorManagedWrites(runner), async (sp) => applyEntityEvent(event, table, entity, sp));
             if (deleteResult.kind !== "applied") {
                 return writeFailure(new InternalError({ message: "projection delete: applyEntityEvent skipped" }));
             }
@@ -699,14 +704,14 @@ export function createWriteVerbs(ctx) {
             await projectEntityEvent(db, runner, echoEvent);
             return {
                 isSuccess: true,
-                data: {
+                data: withoutEventInJson({
                     kind: "delete",
                     id: payload.id,
                     data: existing,
                     entityName,
                     event: echoEvent,
                     ...(isLockGuardBypassed(user, options) && { lockGuardBypassed: true }),
-                },
+                }),
             };
         },
         // Hard-purge (Art. 17). Same shape as delete(), but emits `forgotten` which
@@ -772,7 +777,7 @@ export function createWriteVerbs(ctx) {
                 }
                 throw e;
             }
-            const forgetResult = await runInSavepointIfSupported(runner, async (sp) => applyEntityEvent(event, table, entity, sp));
+            const forgetResult = await runInSavepointIfSupported(withExecutorManagedWrites(runner), async (sp) => applyEntityEvent(event, table, entity, sp));
             if (forgetResult.kind !== "applied") {
                 return writeFailure(new InternalError({ message: "projection forget: applyEntityEvent skipped" }));
             }
@@ -783,14 +788,14 @@ export function createWriteVerbs(ctx) {
             await projectEntityEvent(db, runner, echoEvent);
             return {
                 isSuccess: true,
-                data: {
+                data: withoutEventInJson({
                     kind: "delete",
                     id: payload.id,
                     data: existing,
                     entityName,
                     event: echoEvent,
                     lockGuardBypassed: true,
-                },
+                }),
             };
         },
         async restore(payload, user, db, options) {
@@ -840,7 +845,7 @@ export function createWriteVerbs(ctx) {
             // Soft-delete unique indexes are partial (WHERE is_deleted = false), so a live row may have re-taken the value this restore brings back.
             let restoreResult;
             try {
-                restoreResult = await runInSavepointIfSupported(runner, async (sp) => applyEntityEvent(event, table, entity, sp));
+                restoreResult = await runInSavepointIfSupported(withExecutorManagedWrites(runner), async (sp) => applyEntityEvent(event, table, entity, sp));
             }
             catch (e) {
                 const mapped = tryMapUniqueViolation(e, entityName);
@@ -865,7 +870,7 @@ export function createWriteVerbs(ctx) {
             await projectEntityEvent(db, runner, echoEvent);
             return {
                 isSuccess: true,
-                data: {
+                data: withoutEventInJson({
                     kind: "save",
                     id: payload.id,
                     data: restoredHydrated,
@@ -874,7 +879,7 @@ export function createWriteVerbs(ctx) {
                     isNew: false,
                     entityName,
                     event: echoEvent,
-                },
+                }),
             };
         },
     };

package/dist/db/executor-managed-tables.d.ts

@@ -0,0 +1,8 @@
+import type { ExecutorManagedWriteCapability, Writable } from "@cosmicdrift/kumiko-types/executor-brand";
+import { AccessDeniedError } from "../errors/index.ts";
+export declare function markExecutorManagedTable(table: object): void;
+export declare function isExecutorManagedTable(table: unknown): boolean;
+export declare function registerExecutorManagedWriteRunner(runner: object): void;
+export declare function hasExecutorManagedWriteCapability(runner: unknown): runner is ExecutorManagedWriteCapability;
+export declare function executorManagedWriteDenied(runner: unknown, table: unknown, operation: string): AccessDeniedError | undefined;
+export declare function assertWritableTable<T extends object>(table: T): asserts table is T & Writable;

package/dist/db/executor-managed-tables.js

@@ -0,0 +1,48 @@
+import { AccessDeniedError, InternalError } from "../errors/index.js";
+import { asEntityTableMeta, tableNameOf } from "./table-introspection.js";
+const executorManagedTables = new WeakSet();
+const executorManagedWriteRunners = new WeakSet();
+export function markExecutorManagedTable(table) {
+    executorManagedTables.add(table);
+    const meta = asEntityTableMeta(table);
+    if (meta !== undefined)
+        executorManagedTables.add(meta);
+}
+export function isExecutorManagedTable(table) {
+    if (typeof table !== "object" || table === null)
+        return false;
+    if (executorManagedTables.has(table))
+        return true;
+    const meta = asEntityTableMeta(table);
+    return meta !== undefined && executorManagedTables.has(meta);
+}
+export function registerExecutorManagedWriteRunner(runner) {
+    executorManagedWriteRunners.add(runner);
+}
+// WeakSet.has never reads a property off runner, so a fail-closed guard Proxy stays untouched.
+// postgres.js clients are callable (tagged templates), so a runner can be a function.
+export function hasExecutorManagedWriteCapability(runner) {
+    if (typeof runner !== "object" && typeof runner !== "function")
+        return false;
+    return runner !== null && executorManagedWriteRunners.has(runner);
+}
+export function executorManagedWriteDenied(runner, table, operation) {
+    if (!isExecutorManagedTable(table))
+        return undefined;
+    if (hasExecutorManagedWriteCapability(runner))
+        return undefined;
+    const tableName = tableNameOf(table);
+    return new AccessDeniedError({
+        message: `${operation}(${tableName}): "${tableName}" is fed by events (r.entity / r.projection). ` +
+            "Write it through the entity executor (r.crud, ctx.write, createEventStoreExecutor) or inside a " +
+            "projection apply; a direct write drifts from the event stream and a rebuild drops or resurrects the row.",
+    });
+}
+// Unmanaged tables are the Writable ones; callers invoke this only after executorManagedWriteDenied passed without a capable runner.
+export function assertWritableTable(table) {
+    if (isExecutorManagedTable(table)) {
+        throw new InternalError({
+            message: `assertWritableTable: "${tableNameOf(table)}" is executor-managed and the runner holds no write capability.`,
+        });
+    }
+}

package/dist/db/index.d.ts

@@ -1,3 +1,4 @@
+export { applyEntityEvent } from "./apply-entity-event.ts";
 export { assertExistsIn } from "./assert-exists-in.ts";
 export { nullBlindIndexesForSubject, recordEventsOwnedExclusivelyByTenant, recordRowExistsInTenant, recordRowOwningTenantId, subjectRowExistsInTenant, } from "./blind-index-cleanup.ts";
 export { collectTableMetas } from "./collect-table-metas.ts";
@@ -14,7 +15,7 @@ export { collectReferenceFields, enrichRowWithReferences, enrichWithReferences,
 export { collectEncryptedFieldNames, configuredEntityFieldEncryption, configureEntityFieldEncryption, decryptEntityFieldValues, encryptEntityFieldValues, } from "./entity-field-encryption.ts";
 export { entityTableFromRegistry } from "./entity-table-from-registry.ts";
 export type { BuildEntityTableMetaOptions, ColumnMeta, CompositePrimaryKeyMeta, EntityTableMeta, IndexMeta, PgType, UnmanagedTableInput, } from "./entity-table-meta.ts";
-export { buildEntityTableMeta, defineUnmanagedTable, deriveEntityTableMeta, } from "./entity-table-meta.ts";
+export { defineUnmanagedTable, deriveEntityTableMeta, } from "./entity-table-meta.ts";
 export type { EntityLifecycleVerb, EventStoreExecutor, EventStoreExecutorOptions, LockGuardOption, WritePurpose, } from "./event-store-executor.ts";
 export { createEventStoreExecutor, entityEventName, WritePurposes, } from "./event-store-executor.ts";
 export { enumerateFeatureTableSources, type FeatureTableSource, } from "./feature-table-sources.ts";
@@ -24,6 +25,7 @@ export { type AppliedMigration, type ApplyResult, type BaselineResult, baselineM
 export { flattenMoney, type MoneyRead, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.ts";
 export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, type PgErrorInfo, } from "./pg-error.ts";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.ts";
+export { readDatabaseNow } from "./queries/database-now.ts";
 export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.ts";
 export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.ts";
 export type { DeleteManyBatchedOptions, DeleteManyBatchedResult, IncrementCounterOptions, InnerJoinRow, InnerJoinSpec, InsertOnConflictDoNothingOptions, JoinColumnPair, JsonTextMatch, SelectOptions, TableInfo, UpsertOnConflictOptions, WhereObject, WhereOperator, WhereValue, } from "./query.ts";
@@ -34,6 +36,6 @@ export { renderTableDdl, renderTablesDdl } from "./render-ddl.ts";
 export { diffReplayAgainstSnapshot, type ReplayedSchema, type ReplayedTable, type ReplayMismatch, replayMigrationsDir, } from "./replay-migration-sql.ts";
 export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.ts";
 export { tableExists } from "./schema-inspection.ts";
-export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityRow, type EntityTable, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.ts";
-export type { CreateTenantDbOptions, OutsideTransactionContext, TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb, } from "./tenant-db.ts";
-export { castTenantRows, createSystemDbView, createTenantDb, hasOutsideTransactionDb, requireOutsideTransactionDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.ts";
+export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, type EntityRow, type EntityTable, type ExecutorManagedRunner, type ExecutorManagedWriteCapability, physicalColumnName, toSnakeCase, toTableName, type Writable, type WritableSchemaTable, type WritableTable, } from "./table-builder.ts";
+export type { CreateTenantDbOptions, ExecutorManagedTenantDb, OutsideTransactionContext, TenantDb, TenantDbGrants, TenantDbMode, UncheckedSystemDb, } from "./tenant-db.ts";
+export { castTenantRows, createSystemDbView, createTenantDataDestroyDb, createTenantDb, hasOutsideTransactionDb, requireOutsideTransactionDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.ts";

package/dist/db/index.js

@@ -1,3 +1,4 @@
+export { applyEntityEvent } from "./apply-entity-event.js";
 export { assertExistsIn } from "./assert-exists-in.js";
 export { nullBlindIndexesForSubject, recordEventsOwnedExclusivelyByTenant, recordRowExistsInTenant, recordRowOwningTenantId, subjectRowExistsInTenant, } from "./blind-index-cleanup.js";
 export { collectTableMetas } from "./collect-table-metas.js";
@@ -9,7 +10,7 @@ export { bigint, bigserial, boolean, extractTableName, index, instant, instantTo
 export { collectReferenceFields, enrichRowWithReferences, enrichWithReferences, } from "./eagerload.js";
 export { collectEncryptedFieldNames, configuredEntityFieldEncryption, configureEntityFieldEncryption, decryptEntityFieldValues, encryptEntityFieldValues, } from "./entity-field-encryption.js";
 export { entityTableFromRegistry } from "./entity-table-from-registry.js";
-export { buildEntityTableMeta, defineUnmanagedTable, deriveEntityTableMeta, } from "./entity-table-meta.js";
+export { defineUnmanagedTable, deriveEntityTableMeta, } from "./entity-table-meta.js";
 export { createEventStoreExecutor, entityEventName, WritePurposes, } from "./event-store-executor.js";
 export { enumerateFeatureTableSources, } from "./feature-table-sources.js";
 export { flattenLocatedTimestamp, rehydrateLocatedTimestamp, } from "./located-timestamp.js";
@@ -18,6 +19,7 @@ export { baselineMigrations, fetchAppliedMigrations, loadMigrationsFromDir, Migr
 export { flattenMoney, moneyPayloadToMinorUnits, rehydrateMoney } from "./money.js";
 export { constraintOf, extractPgError, isTableAlreadyExists, isUniqueViolation, } from "./pg-error.js";
 export { acquireNamespacedAdvisoryLock } from "./queries/advisory-lock.js";
+export { readDatabaseNow } from "./queries/database-now.js";
 export { toPostgresArrayLiteral } from "./queries/postgres-array-literal.js";
 export { executeRawQuery, executeRawQueryRead } from "./queries/raw-sql.js";
 export { aggregateWhere, asEntityTableMeta, asRawClient, countWhere, deleteMany, deleteManyBatched, extractTableInfo, fetchOne, incrementCounter, insertMany, insertOnConflictDoNothing, insertOne, instantToTimestamptzParam, isTimestamptzType, requireEntityTableMeta, runInSavepoint, runInSavepointIfSupported, runnerCanBeginTransaction, selectInnerJoin, selectMany, transaction, unsafeReadRetrying, updateMany, upsertByPk, upsertOnConflict, } from "./query.js";
@@ -28,4 +30,4 @@ export { diffReplayAgainstSnapshot, replayMigrationsDir, } from "./replay-migrat
 export { findCommentedDropTables, isRetiredFrameworkTable, retiredFrameworkTables, } from "./retired-framework-tables.js";
 export { tableExists } from "./schema-inspection.js";
 export { buildBaseColumns, buildEntityTable, declareGlobalTenancy, physicalColumnName, toSnakeCase, toTableName, } from "./table-builder.js";
-export { castTenantRows, createSystemDbView, createTenantDb, hasOutsideTransactionDb, requireOutsideTransactionDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";
+export { castTenantRows, createSystemDbView, createTenantDataDestroyDb, createTenantDb, hasOutsideTransactionDb, requireOutsideTransactionDb, runInOwnTransaction, SYSTEM_SCOPE_CHECK_BRAND, scopeTenantDbToTenant, } from "./tenant-db.js";

package/dist/db/money.d.ts

@@ -12,7 +12,7 @@ export type MoneyRead = {
     readonly currency: string;
     readonly amountScaled: number;
     /**
-     * @deprecated Use `amountScaled` — this name implies ISO-4217 minor units
+     * @deprecated Removed in 0.390.0. Use `amountScaled` — this name implies ISO-4217 minor units
      * (cents), which is wrong once a currency needing a different scale than
      * the current flat MINOR_UNIT_SCALE=100 lands (e.g. JPY, 0 decimals).
      * Alias of `amountScaled`, kept until #1976/4 and #1976/5 migrate their

package/dist/db/queries/backfill-pii.js

@@ -62,7 +62,7 @@ import { quoteIdent } from "../../crypto/ciphertext-pattern.js";
 import { configuredEventPiiCatalog } from "../../crypto/event-pii.js";
 import { isLocalKeyKmsAdapter, KeyErasedError, KeyNotFoundError, } from "../../crypto/kms-adapter.js";
 import { isPlainUserOwnedField } from "../../crypto/owner-transition-rekey.js";
-import { configuredPiiSubjectKms, decryptPiiValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_ERASED_SENTINEL, piiCiphertextSubject, } from "../../crypto/pii-field-encryption.js";
+import { configuredPiiSubjectKms, decryptPiiValueForSubject, encryptPiiJsonValueForSubject, encryptPiiValueForSubject, isPiiCiphertext, PII_ERASED_SENTINEL, piiCiphertextSubject, } from "../../crypto/pii-field-encryption.js";
 import { collectPiiEncryptedFields, nonEmptyString, resolveEventSubject, resolveSubjectForField, SubjectResolutionError, } from "../../crypto/subject-resolver.js";
 import { resolveTableName } from "../entity-table-meta.js";
 import { asRawClient } from "../query.js";
@@ -343,11 +343,11 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
                     const value = section[field];
                     if (value === null || value === undefined)
                         continue;
-                    // jsonb PII is not retro-encrypted (consumer wave); a legacy string
-                    // value here would otherwise get the v2 text format into a jsonb column.
-                    if (target.entity.fields[field]?.type === "jsonb")
-                        continue;
-                    if (typeof value !== "string")
+                    // A jsonb field holds any JSON value; a string that is neither ciphertext nor the
+                    // sentinel is a plaintext scalar and gets the JSON format (the v2 text format must
+                    // not reach a jsonb column).
+                    const isJsonbField = target.entity.fields[field]?.type === "jsonb";
+                    if (!isJsonbField && typeof value !== "string")
                         continue;
                     // Already-ciphertext/sentinel fields must never enter the encrypt/erase
                     // owner resolution — an unresolvable owner on an already-handled field
@@ -374,7 +374,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
                     }
                     if (resolution.viaProjection)
                         counters.ownerFromProjection++;
-                    const outcome = await encryptField(section, field, resolution.subject);
+                    const outcome = await encryptField(section, field, resolution.subject, isJsonbField);
                     bump(outcome);
                 }
             }
@@ -405,13 +405,11 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
                 counters.erased++;
             }
         }
-        async function encryptField(section, field, subject) {
+        async function encryptField(section, field, subject, isJsonbField = false) {
             const value = section[field];
             if (value === null || value === undefined)
                 return "unchanged";
-            if (typeof value !== "string")
-                return "unchanged";
-            if (isPiiCiphertext(value) || value === PII_ERASED_SENTINEL)
+            if (!isBackfillCandidate(value, isJsonbField))
                 return "unchanged";
             if (await isForgottenSubject(subject, row.aggregate_id)) {
                 section[field] = PII_ERASED_SENTINEL;
@@ -420,7 +418,7 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
             if (options.dryRun)
                 return predictEncryptOutcome(subject);
             try {
-                section[field] = await encryptPiiValueForSubject(subjectKms, subject, value, kmsCtx, field);
+                section[field] = await encryptBackfillValue(subjectKms, subject, value, kmsCtx, field, isJsonbField);
                 return "encrypted";
             }
             catch (e) {
@@ -469,6 +467,18 @@ export async function backfillEventPiiEncryptionBatch(db, registry, options = {}
         return scanCache.destroyedTenants;
     }
 }
+// Text fields only hold strings; a jsonb field holds any JSON value, scalars included.
+// Ciphertext and the erased sentinel are already handled.
+function isBackfillCandidate(value, isJsonbField) {
+    if (typeof value === "string")
+        return !isPiiCiphertext(value) && value !== PII_ERASED_SENTINEL;
+    return isJsonbField || (typeof value === "object" && value !== null);
+}
+function encryptBackfillValue(subjectKms, subject, value, kmsCtx, field, isJsonbField) {
+    return typeof value === "string" && !isJsonbField
+        ? encryptPiiValueForSubject(subjectKms, subject, value, kmsCtx, field)
+        : encryptPiiJsonValueForSubject(subjectKms, subject, value, kmsCtx, field);
+}
 // aggregate_id is only unique per tenant: another tenant's projection row must not name the owner.
 function projectionOwnerRowOfTenant(owner, tenantId) {
     if (owner === undefined)

package/dist/db/queries/database-now.d.ts

@@ -0,0 +1,5 @@
+import type { AnyDb } from "../query.ts";
+import type { TenantDb } from "../tenant-db.ts";
+export declare function queryDatabaseNow(runner: AnyDb): Promise<Date>;
+/** Postgres clock; inside a transaction `now()` is the transaction start, so repeated reads agree. */
+export declare function readDatabaseNow(db: TenantDb): Promise<Date>;