@cosmicdrift/kumiko-framework 0.333.0 → 0.335.0

package/dist/migrations/index.js

@@ -1,7 +1,7 @@
 // Drizzle-free gate (kumiko/migrations system) — the canonical boot-gate.
 export { assertKumikoSchemaCurrent, detectKumikoDrift, formatKumikoDriftReport, SchemaDriftError, } from "./kumiko-drift.js";
 // Persistente Pending-Rebuild-Queue (survives Rebuild-Failures + Crashes).
-export { createPendingRebuildsTable, enqueueProjectionRebuild, listPendingRebuilds, PROJECTION_REBUILD_JOB, pendingRebuildsTable, queueRebuildsFromMarkers, rebuildProjectionOrMultiStream, runPendingRebuilds, } from "./pending-rebuilds.js";
+export { createPendingRebuildsTable, enqueueProjectionRebuild, listPendingRebuilds, PROJECTION_REBUILD_JOB, pendingRebuildsTable, queueRebuildsFromMarkers, rebuildProjectionOrMultiStream, reportPendingRebuildRun, runPendingRebuilds, } from "./pending-rebuilds.js";
 // Boot-time backfill: re-encrypts plaintext events after a PII annotation was added.
 export { createPiiBackfillStateTable, piiAnnotationFingerprint, piiBackfillStateTable, runPiiEventBackfill, } from "./pii-event-backfill.js";
 // tableName → projection-name, für den app-seitigen Projection-Rebuild.

package/dist/migrations/pending-rebuilds.d.ts

@@ -57,6 +57,10 @@ export declare function rebuildProjectionOrMultiStream(name: string, deps: {
         readonly skipApplyErrors?: boolean;
     };
 }): Promise<RebuildResult>;
+/** Logs a finished queue drain and throws when any projection failed; the
+ *  failed tables stay queued. Shared by every `schema apply` entry point so the
+ *  report and the error text cannot drift apart. */
+export declare function reportPendingRebuildRun(run: PendingRebuildRun, log: (line: string) => void): void;
 /** Arbeitet die persistierte Queue ab: mappt Tabellen auf Projektionen,
  *  rebuildet jede betroffene Projektion und räumt ihre Tabellen erst nach
  *  ERFOLG aus der Queue. Fehlgeschlagene bleiben pending — der nächste

package/dist/migrations/pending-rebuilds.js

@@ -71,7 +71,12 @@ export async function clearPendingRebuilds(db, rows) {
 export async function rebuildProjectionOrMultiStream(name, deps) {
     const { db, registry, signal, errorPolicy } = deps;
     if (registry.getAllMultiStreamProjections().has(name)) {
-        return rebuildMultiStreamProjection(name, { db, registry, markDeadOnFailure: false });
+        return rebuildMultiStreamProjection(name, {
+            db,
+            registry,
+            markDeadOnFailure: false,
+            ...(signal && { signal }),
+        });
     }
     return rebuildProjection(name, {
         db,
@@ -80,6 +85,23 @@ export async function rebuildProjectionOrMultiStream(name, deps) {
         ...(errorPolicy && { errorPolicy }),
     });
 }
+/** Logs a finished queue drain and throws when any projection failed; the
+ *  failed tables stay queued. Shared by every `schema apply` entry point so the
+ *  report and the error text cannot drift apart. */
+export function reportPendingRebuildRun(run, log) {
+    if (run.rebuilt.length > 0) {
+        log(`  Rebuild ${run.rebuilt.length} Projection(s)…`);
+        for (const r of run.rebuilt) {
+            log(`    ↻ ${r.projection} (${r.eventsProcessed} events)`);
+        }
+        log("");
+    }
+    if (run.failed.length > 0) {
+        throw new Error(`Projection rebuild failed for: ${run.failed
+            .map((f) => `${f.projection} (${f.error})`)
+            .join("; ")}. Table(s) stay queued in kumiko_pending_rebuilds — retried on the next apply.`);
+    }
+}
 /** Arbeitet die persistierte Queue ab: mappt Tabellen auf Projektionen,
  *  rebuildet jede betroffene Projektion und räumt ihre Tabellen erst nach
  *  ERFOLG aus der Queue. Fehlgeschlagene bleiben pending — der nächste

package/dist/observability/escape-hatch-report.d.ts

@@ -20,4 +20,5 @@ export declare function createEscapeHatchReporter(opts: {
     readonly log?: Logger;
     readonly window?: EscapeHatchReportWindow;
 }): EscapeHatchReporter;
+export declare const UNATTRIBUTED_ACTOR = "system";
 export declare function fallbackEscapeHatchReporter(tenantId: TenantId): EscapeHatchReporter;

package/dist/observability/escape-hatch-report.js

@@ -83,6 +83,9 @@ export function createEscapeHatchReporter(opts) {
         reportEscapeHatchUse({ handler: opts.handler, kind, reason, tenantId: opts.tenantId, actor: opts.actor, target }, { sink: opts.sink, log: opts.log });
     };
 }
+// Actor for escape-hatch uses whose caller did not thread one through. Stays
+// "system" so audit events persisted before the constant existed remain valid.
+export const UNATTRIBUTED_ACTOR = "system";
 export function fallbackEscapeHatchReporter(tenantId) {
     return createEscapeHatchReporter({
         handler: "<unattributed>",

package/dist/observability/index.d.ts

@@ -1,5 +1,6 @@
 export { type ConsoleProviderOptions, createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
+export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, type EscapeHatchReportWindow, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";

package/dist/observability/index.js

@@ -1,6 +1,7 @@
 // Public surface of the observability module.
 export { createConsoleProvider } from "./console-provider.js";
 export { observabilityContext } from "./context.js";
+export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, UNATTRIBUTED_ACTOR, } from "./escape-hatch-report.js";
 export { getFallbackMeter, getFallbackProvider, getFallbackTracer } from "./fallback.js";
 export { generateSpanId, generateTraceId } from "./ids.js";
 export { buildMetricName, validateLabelKey, validateMetricName, } from "./metric-validator.js";

package/dist/pipeline/dispatch-batch.js

@@ -7,6 +7,7 @@ import { resolveDbSource } from "./dispatch-shared.js";
 import { executeNestedWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
 import { effectiveWriteOrigin, isPersonalDataGated, rootWriteOrigin } from "./write-origin.js";
+import { maskBatchResultForClient } from "./write-result-masking.js";
 // afterCommit hooks fire in flushAfterCommit, outside the command's scope.
 function rewrapHooksWithOrigin(afterCommitHooks, fromIndex, origin) {
     for (let i = fromIndex; i < afterCommitHooks.length; i++) {
@@ -51,20 +52,24 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
             idempotencyToken = checked.token;
         }
     }
+    // Hooks already ran on the plaintext results; what is returned and cached
+    // for retries must not carry writeOnly values.
+    const maskForClient = (result) => maskBatchResultForClient(ctx.registry, commands, result);
     // Cache the result under requestId so retries get the same answer. Only a
     // provably rolled-back 5xx releases the lock instead (releaseOrFinalize).
     const finalize = async (result) => {
+        const masked = maskForClient(result);
         if (requestId && idempotency && idempotencyToken) {
-            await idempotency.store(user.tenantId, user.id, requestId, idempotencyToken, result);
+            await idempotency.store(user.tenantId, user.id, requestId, idempotencyToken, masked);
         }
-        return result;
+        return masked;
     };
     // Never for the no-tx fallback: without a rollback, a re-run would repeat
     // the side effects of the commands that already ran.
     const releaseOrFinalize = async (result, isRetryableRollback) => {
         if (isRetryableRollback && requestId && idempotency && idempotencyToken) {
             await idempotency.release(user.tenantId, user.id, requestId, idempotencyToken);
-            return result;
+            return maskForClient(result);
         }
         return finalize(result);
     };

package/dist/pipeline/dispatch-query.d.ts

@@ -1,4 +1,4 @@
 import type { DbTx } from "../db/connection.js";
 import type { SessionUser } from "../engine/types/index.js";
-import type { DispatchContext, WriteOrigin } from "./dispatch-shared.js";
+import { type DispatchContext, type WriteOrigin } from "./dispatch-shared.js";
 export declare function executeQuery(ctx: DispatchContext, type: string, payload: unknown, user: SessionUser, origin: WriteOrigin, tx?: DbTx): Promise<unknown>;

package/dist/pipeline/dispatch-query.js

@@ -2,7 +2,7 @@ import { hasAccess } from "../engine/access.js";
 import { filterReadFields } from "../engine/field-access.js";
 import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors/index.js";
 import { assertNoSecretLeak } from "../secrets/index.js";
-import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, runHandlerInstrumented, } from "./dispatch-shared.js";
+import { buildHandlerContext, enforceRateLimit, ensureFeatureEnabled, isMemberResolutionPrincipal, runHandlerInstrumented, } from "./dispatch-shared.js";
 import { runInMemberReadOnlyTransaction } from "./member-read-only-transaction.js";
 // Standalone query execution — used by the public dispatcher.query() and
 // by ctx.query/ctx.queryAs inside handlers. Runs the handler, applies
@@ -51,7 +51,7 @@ async function executeQueryInner(ctx, type, payload, user, origin, tx) {
         parsed.data !== null &&
         parsed.data["includeDeleted"] === true; // @cast-boundary validated-payload
     // A resolved member (ctx.queryAsMember) runs in a Postgres READ ONLY transaction, not just the ctx surface below.
-    return user.origin === "member-resolution"
+    return isMemberResolutionPrincipal(user)
         ? runInMemberReadOnlyTransaction(ctx, tx, (readOnlyTx) => runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, readOnlyTx))
         : runQueryHandler(ctx, type, handler, parsed.data, includeDeleted, user, origin, tx);
 }

package/dist/pipeline/dispatch-shared.d.ts

@@ -6,8 +6,7 @@ import type { EffectiveFeaturesResolver } from "../engine/tier-resolver-extensio
 import type { TenantId } from "../engine/types/identifiers.js";
 import type { AppContext, HandlerContext, JobRunnerRef, RateLimitDeclaration, Registry, SessionUser, WriteResult } from "../engine/types/index.js";
 import { type WriteErrorInfo } from "../errors/index.js";
-import { type EscapeHatchReportWindow } from "../observability/escape-hatch-report.js";
-import { type getFallbackMeter, getFallbackTracer } from "../observability/index.js";
+import { type EscapeHatchReportWindow, type getFallbackMeter, getFallbackTracer } from "../observability/index.js";
 import { type AfterCommitHook } from "./dispatcher-utils.js";
 import type { IdempotencyGuard } from "./idempotency.js";
 import type { LifecycleHooks } from "./lifecycle-pipeline.js";
@@ -49,7 +48,7 @@ export type DispatchContext = {
 export declare function resolveDbSource(ctx: DispatchContext, tx: DbTx | undefined): DbConnection | DbTx | undefined;
 export declare function isMemberResolutionPrincipal(user: SessionUser): boolean;
 export declare function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext;
-export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, tx?: DbTx, afterCommitHooks?: AfterCommitHook[], includeDeleted?: boolean): Promise<HandlerContext>;
+export declare function buildHandlerContext(ctx: DispatchContext, type: string, user: SessionUser, origin: WriteOrigin, tx?: DbTx, afterCommitHooks?: AfterCommitHook[], includeDeleted?: boolean, isPostCommit?: boolean): Promise<HandlerContext>;
 export declare function runHandlerInstrumented<T>(ctx: DispatchContext, type: string, operation: "query" | "write" | "stream", user: SessionUser, inner: () => Promise<T>): Promise<T>;
 export declare function runStreamInstrumented<T>(ctx: DispatchContext, type: string, user: SessionUser, inner: () => AsyncGenerator<T>): AsyncGenerator<T>;
 export declare function checkFeatureEnabled(ctx: DispatchContext, qualifiedHandler: string, tenantId: TenantId): Promise<import("../errors/index.js").FeatureDisabledError | undefined>;

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

@@ -5,7 +5,7 @@ import { createTenantDb, hasTenantColumn } from "../db/tenant-db.js";
 import { tenantDbRunner } from "../db/tenant-db-runner.js";
 import { hasAccess } from "../engine/access.js";
 import { ConfigScopes } from "../engine/constants.js";
-import { checkWriteFieldOwnership, checkWriteFieldRoles } from "../engine/field-access.js";
+import { checkWriteFieldOwnership, checkWriteFieldRoles, maskWriteOnlyFields, } from "../engine/field-access.js";
 import { defineTransitions, guardTransition } from "../engine/state-machine.js";
 import { HookPhases } from "../engine/types/index.js";
 import { runValidation } from "../engine/validation.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`,
@@ -262,7 +279,10 @@ export async function executeNestedWrite(ctx, type, payload, user, origin, tx, a
             }
             const subWrapper = subResult.data; // @cast-boundary engine-payload
             const subRow = (subWrapper["data"] ?? subWrapper); // @cast-boundary engine-payload
-            subRows.push(subRow);
+            const subEntityName = registry.getHandlerEntity(spec.subType);
+            const subEntity = subEntityName ? registry.getEntity(subEntityName) : undefined;
+            // parentRow is returned to the client; the child's own SaveContext keeps the plaintext.
+            subRows.push(subEntity ? maskWriteOnlyFields(subEntity, subRow) : subRow);
         }
         parentRow[spec.key] = subRows;
     }

package/dist/pipeline/dispatcher-utils.js

@@ -4,8 +4,11 @@ import { VersionConflictError as EventStoreVersionConflictError } from "../event
 export function isFailedWriteResult(result) {
     return (!!result && typeof result === "object" && "isSuccess" in result && result.isSuccess === false);
 }
+const LIFECYCLE_KINDS = ["save", "delete"];
 export function isLifecycleResult(data) {
-    return !!data && typeof data === "object" && "kind" in data;
+    if (!data || typeof data !== "object" || !("kind" in data))
+        return false;
+    return LIFECYCLE_KINDS.some((kind) => kind === data.kind);
 }
 export function isWriteResultShape(result) {
     return (!!result &&

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.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

@@ -170,6 +170,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 +454,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 +469,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 +518,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"]) {
@@ -511,11 +518,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;