@cosmicdrift/kumiko-framework 0.334.0 → 0.336.0

package/dist/pipeline/dispatch-shared.js

@@ -11,13 +11,13 @@ import { loadAggregateWithSnapshot, saveSnapshot, } from "../event-store/snapsho
 import { upcastStoredEvent, upcastStoredEvents } from "../event-store/upcaster.js";
 import { createFileContext } from "../files/file-handle.js";
 import { DEFAULT_LOCALE, isValidLocaleTag } from "../i18n/request-locale.js";
-import { createEscapeHatchReporter, } from "../observability/escape-hatch-report.js";
-import { createMetricsHandle, createNoopMetricsHandle, createSafeMetricsHandle, emitDispatcherError, emitDispatcherHandler, getFallbackTracer, observabilityContext, } from "../observability/index.js";
+import { createEscapeHatchReporter, createMetricsHandle, createNoopMetricsHandle, createSafeMetricsHandle, emitDispatcherError, emitDispatcherHandler, getFallbackTracer, observabilityContext, } from "../observability/index.js";
 import { buildBucketKey } from "../rate-limit/index.js";
 import { createTzContext, isValidIanaTimeZone } from "../time/index.js";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
 import { appendDomainEventCore } from "./append-event-core.js";
 import { resolveAuthClaims as runAuthClaimsResolver } from "./auth-claims-resolver.js";
+import { runBatch, unwrapSingle } from "./dispatch-batch.js";
 import { executeQuery } from "./dispatch-query.js";
 import { executeWrite } from "./dispatch-write.js";
 import { dispatcherSpanAttributes, isFailedWriteResult, } from "./dispatcher-utils.js";
@@ -135,7 +135,7 @@ export function applyMemberResolutionReadOnly(handlerContext) {
         ...(handlerContext.notify && { notify: denyMemberResolutionWrite }),
     };
 }
-export async function buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks, includeDeleted) {
+export async function buildHandlerContext(ctx, type, user, origin, tx, afterCommitHooks, includeDeleted, isPostCommit) {
     const { registry, appContext: context, effectiveFeatures, jobRunner, lifecycle } = ctx;
     const isSystem = registry.isHandlerSystemScoped(type);
     // The outer dispatcher receives a DbConnection from the server/stack;
@@ -241,6 +241,13 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     // Cross-feature bridge: ctx.query/write share the current tx + afterCommitHooks sink.
     // queryAs/writeAs to anyone but the caller itself needs r.systemScope() or { escapeHatch } (system-identity-switch.ts).
     const bridgeSink = afterCommitHooks ?? [];
+    // Post-commit hooks have no transaction left, so a bare executeWrite would
+    // auto-commit event append, projections and inTransaction hooks separately
+    // and its afterCommit hooks would land in an already-flushed sink. A
+    // batch-of-one gives the write its own transaction and its own flush.
+    const writeAsUser = async (asUser, targetType, payload) => isPostCommit
+        ? unwrapSingle(await runBatch(ctx, [{ type: targetType, payload }], asUser, undefined, origin))
+        : executeWrite(ctx, targetType, payload, asUser, origin, tx, bridgeSink);
     const scheduleAfterCommit = (hook) => {
         bridgeSink.push(hook);
     };
@@ -248,7 +255,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const identitySwitch = createGatedIdentitySwitch(`handler "${type}"`, user, hasIdentitySwitchGrant, {
         // Inherits the caller's origin, so switching to SYSTEM cannot shed an anonymous root.
         queryAs: (asUser, targetType, payload) => executeQuery(ctx, targetType, payload, asUser, origin, tx), // @wrapper-known semantic-alias
-        writeAs: (asUser, targetType, payload) => executeWrite(ctx, targetType, payload, asUser, origin, tx, bridgeSink),
+        writeAs: writeAsUser,
     }, identitySwitchAudit);
     // Lazy — creates the reader (which fails closed on SYSTEM_TENANT_ID) only
     // on first actual use, not on every HandlerContext build.
@@ -289,10 +296,7 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
     const bridge = {
         query: (targetType, payload) => executeQuery(ctx, targetType, payload, user, origin, tx), // @wrapper-known semantic-alias
         queryAs: identitySwitch.queryAs,
-        write: async (targetType, payload) => {
-            const res = await executeWrite(ctx, targetType, payload, user, origin, tx, bridgeSink);
-            return res;
-        },
+        write: (targetType, payload) => writeAsUser(user, targetType, payload),
         writeAs: identitySwitch.writeAs,
         // Strict + unsafe share the same runtime — only the type-surface
         // differs. The strict signature is what's exposed to typed callers;
@@ -545,9 +549,10 @@ export async function buildHandlerContext(ctx, type, user, origin, tx, afterComm
             tenantTz = cachedTz.value;
         }
         else {
+            const generationAtRead = ctx.tenantTimezoneCache.generation();
             tenantTz = await config(TENANT_TIMEZONE_CONFIG_KEY);
             if (tx === undefined) {
-                ctx.tenantTimezoneCache.set(user.tenantId, typeof tenantTz === "string" ? tenantTz : undefined);
+                ctx.tenantTimezoneCache.setIfFresh(user.tenantId, typeof tenantTz === "string" ? tenantTz : undefined, generationAtRead);
             }
         }
     }

package/dist/pipeline/dispatch-stream.js

@@ -1,3 +1,4 @@
+import { accessInvalidationCredentialFor } from "../api/sse-broker.js";
 import { hasAccess } from "../engine/access.js";
 import { AccessDeniedError, memberResolutionReadOnlyDenied, NotFoundError, validationErrorFromZod, } from "../errors/index.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
@@ -39,13 +40,9 @@ async function* executeStreamInner(ctx, type, payload, user, origin) {
     const invalidated = new Promise((resolve) => {
         resolveInvalidated = resolve;
     });
-    const streamCredential = {
-        ...(user.sid !== undefined && { sid: user.sid }),
-        ...(user.pat?.tokenId !== undefined && { patTokenId: user.pat.tokenId }),
-    };
     const unsubscribeAccessInvalidation = ctx.sseBroker?.subscribeAccessInvalidation(user.id, () => {
         resolveInvalidated?.();
-    }, streamCredential);
+    }, accessInvalidationCredentialFor(user));
     let iterator;
     // When access is revoked mid-pull, `iterator.next()` is still in flight.
     // Awaiting `iterator.return()` in that state deadlocks async generators in

package/dist/pipeline/dispatch-write.js

@@ -97,7 +97,7 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
     if (result.kind === "save") {
         await lifecycle.runPostSave(type, result, handlerContext, HookPhases.inTransaction);
         afterCommitHooks.push(async () => {
-            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, afterCommitHooks);
+            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, true);
             await lifecycle.runPostSave(type, result, afterCommitContext, HookPhases.afterCommit);
         });
     }
@@ -105,7 +105,7 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
         await lifecycle.runPreDelete(type, result, handlerContext);
         await lifecycle.runPostDelete(type, result, handlerContext, HookPhases.inTransaction);
         afterCommitHooks.push(async () => {
-            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, afterCommitHooks);
+            const afterCommitContext = await buildHandlerContext(ctx, type, user, origin, undefined, undefined, undefined, true);
             await lifecycle.runPostDelete(type, result, afterCommitContext, HookPhases.afterCommit);
         });
     }
@@ -115,8 +115,7 @@ async function runLifecycle(ctx, type, data, handlerContext, user, origin, after
 //
 // Contract:
 //   - `tx` is the active Drizzle transaction handle, or undefined for "no
-//     surrounding transaction" — either no Postgres is configured, or the
-//     transaction already committed (afterCommit phase).
+//     surrounding transaction" — no Postgres is configured.
 //   - `afterCommitHooks` collects deferred side-effects that must only fire
 //     after the transaction commits. The caller flushes them on commit, drops
 //     them on rollback. executeWrite never fires them directly.
@@ -145,6 +144,23 @@ async function isParentRowHiddenFromCaller(ctx, parentEntityName, parentId, user
         return true;
     return hasTenantColumn(table) && visibleRow["tenantId"] !== user.tenantId;
 }
+// A custom create handler may return a partial row. The ownership check only
+// inspects the keys it is given, so a row missing the ownership-bound field
+// would be denied (rule evaluated against undefined) or skipped entirely.
+// Complete it from the stored row, read through the caller's tenant filter.
+async function completeParentRow(ctx, parentEntityName, parentEntity, parentRow, user, tx) {
+    if (Object.keys(parentEntity.fields).every((fieldName) => fieldName in parentRow)) {
+        return parentRow;
+    }
+    const table = getTable(ctx, parentEntityName);
+    const source = resolveDbSource(ctx, tx);
+    if (!table || !source || typeof parentRow["id"] !== "string")
+        return parentRow;
+    const stored = await createTenantDb(source, user.tenantId, "tenant").fetchOne(table, {
+        id: parentRow["id"],
+    });
+    return stored ? { ...stored, ...parentRow } : parentRow;
+}
 // Nested-write orchestration (v1: depth=1, create-only, hasMany-only).
 //
 // When a parent `:create` handler's payload carries values under keys
@@ -233,7 +249,8 @@ export async function executeNestedWrite(ctx, type, payload, user, origin, tx, a
     if (parentEntityName) {
         const parentEntity = registry.getEntity(parentEntityName);
         if (parentEntity) {
-            const deniedField = checkWriteFieldOwnership(parentEntity, parentRow, user);
+            const ownershipRow = await completeParentRow(ctx, parentEntityName, parentEntity, parentRow, user, tx);
+            const deniedField = checkWriteFieldOwnership(parentEntity, ownershipRow, user);
             if (deniedField) {
                 return writeFailure(new AccessDeniedError({
                     message: `nested-write: parent row ownership check failed on field "${deniedField}" of "${type}" — refusing to attach children to a parent row the caller does not own`,

package/dist/pipeline/dispatcher.js

@@ -2,8 +2,7 @@ import { runWithWriteOrigin } from "../api/request-context.js";
 import { DEPRECATED_CROSS_TENANT_SIGNAL, isDeprecatedCrossTenantHandler, } from "../engine/entity-handlers.js";
 import { TENANT_MEMBERSHIPS_QUERY } from "../engine/extension-names.js";
 import { InternalError, reraiseAsKumikoError } from "../errors/index.js";
-import { createEscapeHatchReportWindow } from "../observability/escape-hatch-report.js";
-import { getFallbackMeter, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
+import { createEscapeHatchReportWindow, getFallbackMeter, getFallbackTracer, registerStandardMetrics, } from "../observability/index.js";
 import { INTERACTIVE_SIGN_IN_POLICY, resolveActiveMembershipFn } from "./active-membership.js";
 import { runBatch, unwrapSingle } from "./dispatch-batch.js";
 import { executeQuery } from "./dispatch-query.js";

package/dist/pipeline/event-dispatcher-admin.js

@@ -1,4 +1,4 @@
-import { advanceConsumerPastEventReturning, removePendingGapReturning, selectSnapshotXmax, updateConsumerStatusReturning, } from "../db/queries/event-consumer.js";
+import { advanceConsumerPastEventReturning, removePendingGapReturning, selectConsumerForUpdate, selectSnapshotXmax, updateConsumerStatusReturning, } from "../db/queries/event-consumer.js";
 import { selectNextEventIdAfter, selectSmallestVisibleIdInRanges, } from "../db/queries/event-store.js";
 import { coerceRow, extractTableInfo, selectMany } from "../db/query.js";
 import { getEventsHighWaterMark } from "../event-store/index.js";
@@ -50,6 +50,14 @@ async function requireConsumerRow(db, name, instanceId) {
     }
     return row;
 }
+async function requireConsumerRowForUpdate(tx, name, instanceId) {
+    const raw = await selectConsumerForUpdate(tx, name, instanceId);
+    if (!raw) {
+        throw new Error(`Consumer "${name}" (instance_id="${instanceId}") has no state row — it hasn't run yet, the name is misspelled, or the instance is misspelled. ` +
+            `For per-instance consumers pass the instance_id explicitly; shared consumers use the default.`);
+    }
+    return coerceRow(raw, extractTableInfo(eventConsumerStateTable));
+}
 async function applyConsumerStatusTransition(db, name, instanceId, targetStatus) {
     const raw = await updateConsumerStatusReturning(db, name, instanceId, targetStatus);
     const updated = raw && coerceRow(raw, extractTableInfo(eventConsumerStateTable));
@@ -84,8 +92,10 @@ export async function enableConsumer(db, name, instanceId = SHARED_INSTANCE_SENT
 // event after the cursor. Single TX so concurrent dispatcher passes can't
 // double-advance. Nothing to skip → idempotent no-op.
 export async function skipPoisonEvent(db, name, instanceId = SHARED_INSTANCE_SENTINEL) {
-    const before = await requireConsumerRow(db, name, instanceId);
     return db.begin(async (tx) => {
+        // Locked read: a dispatcher turn committing new gaps between an unlocked
+        // read and the pending_gaps overwrite below would have them dropped.
+        const before = await requireConsumerRowForUpdate(tx, name, instanceId);
         const pendingGaps = before.pendingGaps;
         const failedEventId = before.lastFailedEventId;
         const failedIsPending = failedEventId !== null && pendingGaps.some((gap) => rangeContainsId(gap, failedEventId));

package/dist/pipeline/event-dispatcher-delivery.js

@@ -105,6 +105,11 @@ export async function selectConsumerCursorForUpdate(db, name, instanceId) {
 // pre-check reads pending_gaps live on every pass, so it observes that gap
 // too. In short: this can under-report idleness for one tick, never
 // over-report it.
+//
+// Observability: an idle turn opens no events.consumer.pass span (so no
+// consumer.skip_reason either, including for a disabled consumer with nothing
+// pending); the dispatcher counts it in
+// kumiko_event_consumer_pass_skipped_total{reason="idle"} instead.
 export async function selectIdleConsumerKeys(db, pairs) {
     if (pairs.length === 0)
         return new Set();

package/dist/pipeline/event-dispatcher.d.ts

@@ -31,6 +31,7 @@ export type EventDispatcher = {
     runOnce(): Promise<DispatcherPassResult>;
     ensureRegistered(): Promise<void>;
     drain(): Promise<void>;
+    withBackgroundPassesPaused<T>(fn: () => Promise<T>): Promise<T>;
     readonly consumers: readonly EventConsumer[];
 };
 export type EventDispatcherOptions = {

package/dist/pipeline/event-dispatcher.js

@@ -1,7 +1,7 @@
 import { selectSnapshotXmax, selectSnapshotXmin } from "../db/queries/event-consumer.js";
 import { SYSTEM_TENANT_ID } from "../engine/types/identifiers.js";
 import { EVENTS_PUBSUB_CHANNEL } from "../event-store/index.js";
-import { emitEventConsumerPassOutcome, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, getFallbackMeter, getFallbackTracer, } from "../observability/index.js";
+import { emitEventConsumerPassOutcome, emitEventConsumerPassSkipped, emitEventConsumerRearmExhausted, emitEventDispatcherListenConnected, getFallbackMeter, getFallbackTracer, } from "../observability/index.js";
 import { SHARED_INSTANCE_SENTINEL } from "./event-consumer-state.js";
 import { acquireConsumerState, consumerInstanceId, deliverEvents, emitLagFromTx, fetchPendingEvents, markProcessing, persistConsumerOutcome, persistConsumerPassFailure, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
 import { partitionBurntGaps, splitRangeExcludingIds, toIdRanges } from "./pending-gap-ranges.js";
@@ -132,8 +132,11 @@ export function createEventDispatcher(options) {
         // backoff-gate above already confirmed retryAtMs has elapsed, and
         // "provably nothing to deliver" is itself proof the consumer isn't
         // presently failing.
+        // No events.consumer.pass span is opened here (so no consumer.skip_reason either),
+        // which is why the skip is counted instead.
         if (idleKeys.has(key)) {
             consumerBackoff.delete(key);
+            emitEventConsumerPassSkipped(meter, { consumer: consumer.name, instanceId: consumerInstanceId(consumer, options.instanceId) }, "idle");
             return { processed: 0, failed: 0 };
         }
         // Registered before awaiting the slot — a turn queued behind the
@@ -170,6 +173,15 @@ export function createEventDispatcher(options) {
             // skip: errors already recorded per-consumer inside the pass
         })));
     }
+    let backgroundPassPauseDepth = 0;
+    function runBackgroundPass() {
+        // skip: background passes are paused
+        if (backgroundPassPauseDepth > 0)
+            return;
+        void runOnce().catch(() => {
+            // skip: per-consumer errors already recorded in the state row
+        });
+    }
     async function runOnce() {
         if (!preRegistered) {
             throw new Error("EventDispatcher.runOnce() called before start() — consumer state rows are not registered. Call start() first (production) or ensureRegistered() (tests after truncating kumiko_event_consumers).");
@@ -445,11 +457,7 @@ export function createEventDispatcher(options) {
             // any consumer that exists, including freshly-deployed ones.
             await preRegisterConsumers(db, consumers, options.instanceId);
             preRegistered = true;
-            timer = setInterval(() => {
-                void runOnce().catch(() => {
-                    // skip: per-consumer errors already recorded in the state row
-                });
-            }, pollIntervalMs);
+            timer = setInterval(runBackgroundPass, pollIntervalMs);
             // NOTIFY-based wake-up: subscribe on the same channel that
             // event-store.append fires on commit. Fires runOnce directly, no
             // polling round-trip. The timer stays on as a belt-and-braces
@@ -464,11 +472,7 @@ export function createEventDispatcher(options) {
             emitEventDispatcherListenConnected(meter, false);
             if (options.pgClient) {
                 try {
-                    const sub = await options.pgClient.listen(EVENTS_PUBSUB_CHANNEL, () => {
-                        void runOnce().catch(() => {
-                            // skip: per-consumer errors already recorded in the state row
-                        });
-                    }, () => {
+                    const sub = await options.pgClient.listen(EVENTS_PUBSUB_CHANNEL, runBackgroundPass, () => {
                         // Fires on initial connect and again when postgres.js's own
                         // re-LISTEN lands after a drop; during an outage that re-LISTEN
                         // waits in its connection backoff (measured 10-30s after the DB
@@ -517,7 +521,21 @@ export function createEventDispatcher(options) {
             await preRegisterConsumers(db, consumers, options.instanceId);
             preRegistered = true;
         },
-        drain: drainInFlightTurns,
+        async drain() {
+            await drainInFlightPasses();
+            await drainInFlightTurns();
+        },
+        async withBackgroundPassesPaused(fn) {
+            backgroundPassPauseDepth++;
+            try {
+                await drainInFlightPasses();
+                await drainInFlightTurns();
+                return await fn();
+            }
+            finally {
+                backgroundPassPauseDepth--;
+            }
+        },
         runOnce,
     };
 }

package/dist/pipeline/index.d.ts

@@ -1,5 +1,5 @@
 export type { EscapeHatchReportWindow } from "../observability/escape-hatch-report.js";
-export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, } from "../observability/escape-hatch-report.js";
+export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "../observability/escape-hatch-report.js";
 export type { ResolveAuthClaimsArgs } from "./auth-claims-resolver.js";
 export { resolveAuthClaims } from "./auth-claims-resolver.js";
 export { createCascadeDeleteHook } from "./cascade-handler.js";

package/dist/pipeline/index.js

@@ -1,4 +1,4 @@
-export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, } from "../observability/escape-hatch-report.js";
+export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "../observability/escape-hatch-report.js";
 export { resolveAuthClaims } from "./auth-claims-resolver.js";
 export { createCascadeDeleteHook } from "./cascade-handler.js";
 export { createDispatcher, dispatcherToWriteRef } from "./dispatcher.js";

package/dist/pipeline/member-read-only-transaction.js

@@ -3,21 +3,8 @@ import { asRawClient, runInSavepoint, transaction } from "../db/query.js";
 import { AccessDeniedError, InternalError, memberResolutionReadOnlyDenied, } from "../errors/index.js";
 import { resolveDbSource } from "./dispatch-shared.js";
 const PG_READ_ONLY_SQLSTATE = "25006";
-// Bun.SQL surfaces the PG SQLSTATE as `errno` (code stays "ERR_POSTGRES_SERVER_ERROR");
-// postgres.js surfaces it as `code`, possibly one `.cause` layer down (DrizzleQueryError-style wrapping).
 function isReadOnlyTransactionViolation(e) {
-    if (extractPgError(e)?.code === PG_READ_ONLY_SQLSTATE)
-        return true;
-    if (typeof e !== "object" || e === null)
-        return false;
-    // @cast-boundary error-details — Bun.SQL error shape (errno)
-    if (e.errno === PG_READ_ONLY_SQLSTATE)
-        return true;
-    // @cast-boundary error-details — Bun.SQL error shape (errno) under .cause
-    const cause = e.cause;
-    if (typeof cause !== "object" || cause === null)
-        return false;
-    return cause.errno === PG_READ_ONLY_SQLSTATE;
+    return extractPgError(e)?.code === PG_READ_ONLY_SQLSTATE;
 }
 async function runInDiscardedReadOnlySavepoint(tx, fn) {
     const discardMarker = {};

package/dist/pipeline/msp-rebuild.d.ts

@@ -8,5 +8,6 @@ export type MspRebuildDeps = {
     readonly meter?: Meter;
     readonly onMetrics?: (result: RebuildResult) => void;
     readonly markDeadOnFailure?: boolean;
+    readonly signal?: AbortSignal;
 };
 export declare function rebuildMultiStreamProjection(mspName: string, deps: MspRebuildDeps): Promise<RebuildResult>;

package/dist/pipeline/msp-rebuild.js

@@ -71,6 +71,7 @@ export async function rebuildMultiStreamProjection(mspName, deps) {
                 const events = await selectMany(tx, eventsTable, { type: [...subscribedTypes], id: { lte: horizon } }, { orderBy: { col: "id", direction: "asc" } });
                 const upcasters = registry.getEventUpcasters();
                 for (const row of events) {
+                    deps.signal?.throwIfAborted();
                     const raw = {
                         id: String(row.id),
                         aggregateId: row.aggregateId,

package/dist/pipeline/system-hooks.d.ts

@@ -1,4 +1,4 @@
-import type { SseBroker } from "../api/sse-broker.js";
+import { type SseBroker } from "../api/sse-broker.js";
 import type { EntityId, JobRunnerRef, Registry, TenantId } from "../engine/types/index.js";
 import type { SearchAdapter, SearchDocument } from "../search/types.js";
 import type { EventConsumer } from "./event-dispatcher.js";

package/dist/pipeline/system-hooks.js

@@ -1,6 +1,8 @@
+import { readNonEmptyStringArray, } from "../api/sse-broker.js";
 import { collectSearchableSubjectFields, configuredPiiSubjectKms, decryptPiiFieldValues, isPiiCiphertext, PII_ERASED_SENTINEL, } from "../crypto/index.js";
 import { createTenantDb, entityTableFromRegistry, rehydrateCompoundTypes } from "../db/index.js";
 import { tenantChannel } from "../engine/constants.js";
+import { InternalError } from "../errors/index.js";
 // --- Search Index Consumer (async, via event-dispatcher) ---
 //
 // Search-Indexierung läuft seit D.4 als async EventConsumer über den event-
@@ -187,8 +189,13 @@ async function readProjectionRowForSearch(ctx, registry, entityName, entity, ten
     // DbConnection: event-dispatcher creation is gated on it being set
     // (api/server.ts), never a HandlerContext's already-tenant-scoped TenantDb.
     const baseDb = ctx.db;
-    if (!baseDb)
-        return undefined;
+    // undefined must keep meaning "no live row" (the caller removes the index
+    // entry), so a missing db fails the event for retry instead.
+    if (!baseDb) {
+        throw new InternalError({
+            message: `search consumer: no db on the consumer context — cannot read the live row of "${entityName}" ${entityId}`,
+        });
+    }
     const table = entityTableFromRegistry(registry, entityName, entity);
     const where = { id: entityId };
     if (entity.softDelete && table["isDeleted"]) {
@@ -359,19 +366,17 @@ export async function buildSearchDocument(entityName, entityId, state, registry)
 }
 // --- SSE Broadcast (async, via event-dispatcher) ---
 //
-// SSE-Broadcast läuft seit D.3 als async EventConsumer über den event-
-// dispatcher, nicht mehr als synchroner postSave/postDelete-hook. Das hat
-// zwei Konsequenzen:
+// The SSE broadcast runs as an async EventConsumer on the event dispatcher,
+// not as a synchronous postSave/postDelete hook. Two consequences:
 //
-// 1. **Event-native Payload-Shape.** Der SSE-event spiegelt den StoredEvent:
-//    `type` ist event.type ("user.created", "unit.updated"), `data` enthält
-//    id, aggregateType, version und die event-payload — keine künstliche
-//    "system:event:<entity>:<verb>" Hülle mehr. Clients haben direkten
-//    Zugriff auf `payload.changes` + `payload.previous` (wie im event-log).
-// 2. **Eventual consistency statt Read-after-Write.** Ein SSE-Event kommt
-//    ~10–100ms nach dem HTTP-200 (abhängig von pollIntervalMs). UI-Clients
-//    die auf optimistic-update setzen merken das nicht; strictly-waiting
-//    Clients müssten poll-after-write.
+// 1. **Signal only.** The frame mirrors the StoredEvent's identity: `type` is
+//    event.type ("user.created"), `data` holds id, aggregateType, version and
+//    createdAt, never the payload. The tenant channel fans out to every member
+//    and to anonymous connections, so field values must not enter the broker
+//    or Redis; the client refetches through a query with its own access check.
+// 2. **Eventual consistency, not read-after-write.** A frame arrives roughly
+//    10 to 100 ms after the HTTP 200 (depends on pollIntervalMs). Clients that
+//    must observe their own write poll after writing.
 //
 // Tests drain deterministically via `await stack.eventDispatcher.runOnce()`,
 // or via `drainEventConsumers` for this consumer name specifically.
@@ -395,7 +400,6 @@ export function createSseBroadcastEventConsumer(sseBroker) {
                     id: event.aggregateId,
                     aggregateType: event.aggregateType,
                     version: event.version,
-                    payload: event.payload,
                     createdAt: event.createdAt,
                 },
             });
@@ -511,11 +515,6 @@ function readUserIdFromPreviousSnapshot(payload) {
     const userId = previous["userId"];
     return typeof userId === "string" && userId.length > 0 ? userId : undefined;
 }
-function readNonEmptyStringArray(value) {
-    if (!Array.isArray(value) || value.length === 0)
-        return undefined;
-    return value.every((v) => typeof v === "string") ? value : undefined;
-}
 // session-revoked's scope resolution, in order:
 //   1. streamScope === "revoked-sessions" with a non-empty sessionIds array
 //      (only the raw sessionRevoker callback sets this) → narrow "sessions"

package/dist/pipeline/tenant-timezone-cache.d.ts

@@ -10,6 +10,8 @@ export type TenantTimezoneCacheEntry = {
 export type TenantTimezoneCache = {
     get(tenantId: TenantId): TenantTimezoneCacheEntry | undefined;
     set(tenantId: TenantId, value: string | undefined): void;
+    generation(): number;
+    setIfFresh(tenantId: TenantId, value: string | undefined, generationAtRead: number): void;
     invalidate(tenantId: TenantId): void;
     clear(): void;
     size(): number;

package/dist/pipeline/tenant-timezone-cache.js

@@ -10,20 +10,27 @@ const DEFAULT_TTL_MS = 5 * 60 * 1000;
 const DEFAULT_MAX_ENTRIES = 1000;
 export function createTenantTimezoneCache(opts = {}) {
     const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
-    const maxEntries = opts.maxEntries ?? DEFAULT_MAX_ENTRIES;
+    // 0 or negative would never evict (size < max is never true) and grow unbounded.
+    const maxEntries = Math.max(1, opts.maxEntries ?? DEFAULT_MAX_ENTRIES);
     const now = opts.now ?? (() => Date.now());
     // Map insertion order doubles as LRU order: touch = delete+re-insert.
     const entries = new Map();
+    let generation = 0;
     function evictOldestIfFull() {
         // skip: cache has room, nothing to evict
         if (entries.size < maxEntries)
             return;
         const oldestKey = entries.keys().next().value;
-        // skip: defensive — only reachable if maxEntries is 0 (cache disabled) and entries is empty
+        // skip: defensive — maxEntries >= 1 guarantees a non-empty map here
         if (oldestKey === undefined)
             return;
         entries.delete(oldestKey);
     }
+    function set(tenantId, value) {
+        entries.delete(tenantId);
+        evictOldestIfFull();
+        entries.set(tenantId, { value, expiresAt: now() + ttlMs });
+    }
     return {
         get(tenantId) {
             const hit = entries.get(tenantId);
@@ -37,15 +44,22 @@ export function createTenantTimezoneCache(opts = {}) {
             entries.set(tenantId, hit);
             return { value: hit.value };
         },
-        set(tenantId, value) {
-            entries.delete(tenantId);
-            evictOldestIfFull();
-            entries.set(tenantId, { value, expiresAt: now() + ttlMs });
+        set,
+        generation() {
+            return generation;
+        },
+        setIfFresh(tenantId, value, generationAtRead) {
+            // skip: an invalidation ran since the read started, the value may be pre-write
+            if (generationAtRead !== generation)
+                return;
+            set(tenantId, value);
         },
         invalidate(tenantId) {
+            generation++;
             entries.delete(tenantId);
         },
         clear() {
+            generation++;
             entries.clear();
         },
         size() {

package/dist/pipeline/write-origin.js

@@ -49,8 +49,14 @@ export function rootWriteOrigin(registry, type, user) {
 // Owner binding is ignored (honorOwnerBinding=false): all anonymous callers share one
 // user id, so from("user:id", ...) vouches for nobody.
 const personalDataTableMaps = new WeakMap();
+const personalColumnsByEntity = new WeakMap();
 function personalColumnNames(entity) {
-    return new Set([...personalFieldNames(entity, false)].map(toSnakeCase));
+    const cached = personalColumnsByEntity.get(entity);
+    if (cached)
+        return cached;
+    const columns = new Set([...personalFieldNames(entity, false)].map(toSnakeCase));
+    personalColumnsByEntity.set(entity, columns);
+    return columns;
 }
 function buildPersonalDataTableMap(registry) {
     const map = new Map();
@@ -73,21 +79,22 @@ function personalDataTableMap(registry) {
     personalDataTableMaps.set(registry, built);
     return built;
 }
-// Names fields only, never values: the error reaches the anonymous HTTP caller.
+// The error reaches the anonymous HTTP caller, so table and column names stay out of
+// message/details (they would map the DB schema); they travel in `cause`, which the
+// serializer never sends to clients. The 4xx log line carries only status and code, so
+// `cause` is not logged today; it is only available to in-process error handling.
 export function publicIntakeRequiredError(origin, target, fields) {
     return new AccessDeniedError({
-        message: `Anonymous root handler "${origin.rootHandler}" wrote personal-data field(s) ` +
-            `${fields.map((f) => `"${f}"`).join(", ")} on "${target}"` +
+        message: `Anonymous root handler "${origin.rootHandler}" wrote personal data` +
             (origin.viaJob ? ` via job "${origin.viaJob}"` : "") +
             '. Declare access: { roles: [..., "anonymous"], personalData: "public-intake" } on ' +
             `"${origin.rootHandler}" to allow anonymous callers to write personal data.`,
         details: {
             reason: FrameworkReasons.publicIntakeRequired,
             rootHandler: origin.rootHandler,
-            target,
-            fields,
             ...(origin.viaJob !== undefined && { job: origin.viaJob }),
         },
+        cause: new Error(`personal-data field(s) ${fields.map((f) => `"${f}"`).join(", ")} written on "${target}"`),
     });
 }
 // Without an entity the table name is looked up in the registry map; tables outside it

package/dist/redis/pubsub-signal.d.ts

@@ -1,3 +1,4 @@
+import { type RedisClientOptions } from "./client.js";
 export type PubSubSignal = {
     publish(channel: string, payload: unknown): void;
     onMessage(listener: (channel: string, payload: unknown) => void): void;
@@ -7,5 +8,6 @@ export type PubSubSignalOptions = {
     readonly redisUrl: string;
     readonly channelPattern: string;
     readonly label: string;
+    readonly clientOptions?: RedisClientOptions;
 };
 export declare function createRedisPubSubSignal(opts: PubSubSignalOptions): PubSubSignal;

package/dist/redis/pubsub-signal.js

@@ -9,8 +9,8 @@ function logConnectionError(label, role) {
     };
 }
 export function createRedisPubSubSignal(opts) {
-    const publisher = createRedisClient(opts.redisUrl);
-    const subscriber = createRedisClient(opts.redisUrl);
+    const publisher = createRedisClient(opts.redisUrl, opts.clientOptions);
+    const subscriber = createRedisClient(opts.redisUrl, opts.clientOptions);
     publisher.on("error", logConnectionError(opts.label, "publisher"));
     subscriber.on("error", logConnectionError(opts.label, "subscriber"));
     const listeners = new Set();

package/dist/schema-cli.js

@@ -14,7 +14,7 @@ import { assertValidMigrationName, baselineMigrations, createDbConnection, diffR
 import { validateBoot } from "./engine/boot-validator.js";
 import { createRegistry } from "./engine/registry.js";
 import { createEventsTable } from "./event-store/index.js";
-import { queueRebuildsFromMarkers, runPendingRebuilds } from "./migrations/index.js";
+import { queueRebuildsFromMarkers, reportPendingRebuildRun, runPendingRebuilds, } from "./migrations/index.js";
 import { createEventConsumerStateTable, createProjectionStateTable } from "./pipeline/index.js";
 import { ensureTemporalPolyfill } from "./time/index.js";
 const SNAPSHOT_FILENAME = ".snapshot.json";
@@ -49,6 +49,7 @@ function nextSequenceNumber(migrationsDir) {
     }
     return max + 1;
 }
+const SCHEMA_SUBCOMMANDS = ["generate", "validate", "apply", "baseline", "status"];
 /**
  * Runs a schema-CLI subcommand. `appCwd` is the app workspace root (where
  * `kumiko/schema.ts` + `kumiko/migrations/` live). Returns a process exit code.
@@ -319,18 +320,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
                     });
                     const registry = createRegistry(options.features);
                     const rebuildRun = await runPendingRebuilds(db, registry, { thisRunTables });
-                    if (rebuildRun.rebuilt.length > 0) {
-                        out.log(`  Rebuild ${rebuildRun.rebuilt.length} Projection(s)…`);
-                        for (const r of rebuildRun.rebuilt) {
-                            out.log(`    ↻ ${r.projection} (${r.eventsProcessed} events)`);
-                        }
-                        out.log("");
-                    }
-                    if (rebuildRun.failed.length > 0) {
-                        throw new Error(`Projection rebuild failed for: ${rebuildRun.failed
-                            .map((f) => `${f.projection} (${f.error})`)
-                            .join("; ")}. Table(s) stay queued in kumiko_pending_rebuilds — retried on the next apply.`);
-                    }
+                    reportPendingRebuildRun(rebuildRun, out.log);
                 }
                 return 0;
             }
@@ -421,7 +411,7 @@ export async function runSchemaCli(argv, appCwd, out, options = {}) {
             // move on without ever running a migration.
             if (sub !== undefined) {
                 out.err(`  Unbekanntes Subcommand: "${sub}"`);
-                out.err("  Erlaubt: generate | validate | apply | baseline | status");
+                out.err(`  Erlaubt: ${SCHEMA_SUBCOMMANDS.join(" | ")}`);
                 return 1;
             }
             out.log("");