@cosmicdrift/kumiko-framework 0.377.0 → 0.379.0

package/dist/api/server.js

@@ -1,6 +1,6 @@
 import { Hono } from "hono";
 import { ROLES } from "../auth/roles.js";
-import { createProjectingTenantDb } from "../db/tenant-db.js";
+import { createProjectingTenantDb, withExecutorManagedWrites } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
 import { buildAppSchema } from "../engine/build-app-schema.js";
 import { EXT_FILE_PROVIDER, EXT_PRINCIPAL_STATUS } from "../engine/extension-names.js";
@@ -35,6 +35,7 @@ import { authMiddleware, getAuthTokenExpiry, getUser, } from "./auth-middleware.
 import { assertSessionCallbacksPaired, createAuthRoutes, } from "./auth-routes.js";
 import { assertValidTrustedProxyHops, clientIpSourceFromHonoContext, createClientIpResolver, } from "./client-ip.js";
 import { csrfMiddleware } from "./csrf-middleware.js";
+import { collectEntityReadAccess } from "./entity-read-access.js";
 import { ExtraRouteEntries, ExtraRouteRejection, } from "./extra-route.js";
 import { computeStrongEtag, etagMatches } from "./http-cache.js";
 import { createJwtHelper } from "./jwt.js";
@@ -392,9 +393,10 @@ export function buildServer(options) {
             const mspFiles = fileProviderResolver
                 ? createTenantFileContext(fileProviderResolver, event.tenantId)
                 : undefined;
+            const mspDb = withExecutorManagedWrites(baseDb);
             const applyCtx = createMultiStreamApplyContext({
                 registry: options.registry,
-                db: baseDb,
+                db: mspDb,
                 tenantId: event.tenantId,
                 userId: event.metadata.userId,
                 ...(mspOwner && { callerFeature: mspOwner }),
@@ -410,7 +412,7 @@ export function buildServer(options) {
                     }),
                 }),
             });
-            await applyFn(event, baseDb, applyCtx);
+            await applyFn(event, mspDb, applyCtx);
             // Keep ctx reachable to satisfy the EventConsumerHandler signature.
             void ctx;
         },
@@ -480,6 +482,10 @@ export function buildServer(options) {
     if (options.metrics) {
         registerMetricsRoute(app, observability.meter, options.metrics);
     }
+    else if (process.env["NODE_ENV"] === "production") {
+        console.warn("[kumiko:boot] /metrics is off: no `metrics` option, so nothing is measured or scraped. " +
+            "Set PROMETHEUS_METRICS_TOKEN (min 32 chars) and spread resolveObservabilityWiring(token) into the server options.");
+    }
     app.use("/api/*", requestIdMiddleware({
         resolver: clientIpResolver,
         ...(options.errorDocs && { errorDocs: options.errorDocs }),
@@ -662,6 +668,7 @@ export function buildServer(options) {
     }));
     app.route("/api", createSseRoute(sseBroker, {
         anonymousLiveEntities: collectAnonymousLiveEntities(options.registry),
+        entityReadAccess: collectEntityReadAccess(options.registry),
     }));
     // GET /api/schema — the only way a client obtains the AppSchema. Behind
     // jwtGuard (NON_PUBLIC_API_PATHS), so anonymousAccess's synthesised user

package/dist/api/sse-route.d.ts

@@ -1,4 +1,5 @@
 import { Hono } from "hono";
+import type { AccessRule } from "../engine/types/index.ts";
 import { type SseBroker } from "./sse-broker.ts";
 /**
  * Heartbeat-Cadence für SSE-Streams.
@@ -21,7 +22,11 @@ import { type SseBroker } from "./sse-broker.ts";
  * gegen versehentliches Hochsetzen.
  */
 export declare const SSE_HEARTBEAT_INTERVAL_MS = 15000;
+export declare const SSE_STALLED_CLIENT_TIMEOUT_MS = 15000;
+export declare const SSE_MAX_PENDING_WRITES_PER_CLIENT = 10000;
 export type SseRouteOptions = {
     readonly anonymousLiveEntities: ReadonlySet<string>;
+    readonly entityReadAccess: ReadonlyMap<string, readonly AccessRule[]>;
+    readonly now?: () => number;
 };
 export declare function createSseRoute(broker: SseBroker, options: SseRouteOptions): Hono<import("hono/types").BlankEnv, import("hono/types").BlankSchema, "/">;

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

@@ -1,5 +1,6 @@
+import { toMinorUnits } from "../engine/minor-units.ts";
 import type { EntityDefinition } from "../engine/types/index.ts";
-export declare function toMinorUnits(amount: number): number;
+export { toMinorUnits };
 export declare function moneyPayloadToMinorUnits(raw: unknown): number | undefined;
 export declare function flattenMoney(payload: Record<string, unknown>, entity: EntityDefinition): Record<string, unknown>;
 /** Shape of a single rehydrated money field — {amount major, currency,
@@ -11,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/money.js

@@ -30,15 +30,10 @@
 // Anders als locatedTimestamp behalten wir den Field-Namen `<name>` als
 // amount-Spalte (Legacy DB-Convention für Money — `SUM(buying_price)` bleibt
 // idiomatisch). `<name>Currency` ist die zusätzliche Spalte.
+import { MINOR_UNIT_SCALE, toMinorUnits } from "../engine/minor-units.js";
 import { DEFAULT_CURRENCIES } from "../engine/types/index.js";
 const FRAMEWORK_DEFAULT_CURRENCY = DEFAULT_CURRENCIES[0]; // "EUR"
-// 2 decimal places (cents) — covers every currently-supported currency
-// (EUR/USD/GBP/...). No ISO-4217 minor-unit table yet (JPY=0, BHD=3) —
-// upgrade path once a currency needing a different scale actually lands.
-const MINOR_UNIT_SCALE = 100;
-export function toMinorUnits(amount) {
-    return Math.round(amount * MINOR_UNIT_SCALE);
-}
+export { toMinorUnits };
 function toMajorUnits(amountScaled) {
     return amountScaled / MINOR_UNIT_SCALE;
 }

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[]>;