@cosmicdrift/kumiko-framework 0.378.0 → 0.379.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/entity-table-from-registry.d.ts

@@ -1,4 +1,5 @@
+import type { ExecutorOnly } from "@cosmicdrift/kumiko-types/executor-brand";
 import type { Registry } from "../engine/index.ts";
 import type { SchemaTable } from "./dialect.ts";
 import { buildEntityTable } from "./table-builder.ts";
-export declare function entityTableFromRegistry(registry: Registry, entityName: string, entity: Parameters<typeof buildEntityTable>[1]): SchemaTable;
+export declare function entityTableFromRegistry(registry: Registry, entityName: string, entity: Parameters<typeof buildEntityTable>[1]): SchemaTable & ExecutorOnly;

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

@@ -13,8 +13,6 @@ export declare function resolveTableName(entityName: string, entity: EntityDefin
  * escape hatch (#1208).
  */
 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).

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

@@ -219,7 +219,7 @@ 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") {
@@ -354,8 +354,6 @@ export function deriveEntityTableMeta(entityName, entity, options) {
         ...(entity.tenancy === "global" && { tenancy: "global" }),
     };
 }
-/** @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;
 }

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,6 @@
+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): boolean;
+export declare function executorManagedWriteDenied(runner: unknown, table: unknown, operation: string): AccessDeniedError | undefined;

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

@@ -0,0 +1,40 @@
+import { AccessDeniedError } 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.",
+    });
+}

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";
@@ -36,4 +38,4 @@ export { findCommentedDropTables, isRetiredFrameworkTable, type RetiredFramework
 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 { 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>;

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