@cosmicdrift/kumiko-framework 0.385.0 → 0.387.0

package/dist/pipeline/append-event-core.js

@@ -1,3 +1,4 @@
+import { isPlainObject } from "@cosmicdrift/kumiko-types/type-guards";
 import { requestContext } from "../api/request-context.js";
 import { SYSTEM_EVENT_PREFIX } from "../crypto/system-event-pii.js";
 import { qnScope, toKebab } from "../engine/qualified-name.js";
@@ -6,6 +7,14 @@ import { isStreamArchived } from "../event-store/archive.js";
 import { ArchivedStreamError } from "../event-store/errors.js";
 import { append, getStreamVersion } from "../event-store/event-store.js";
 import { runProjectionsForEvent } from "./projections-runner.js";
+function requirePayloadObject(payload, eventType) {
+    if (!isPlainObject(payload)) {
+        throw new InternalError({
+            message: `appendEvent("${eventType}"): payload must be an object, got ${Array.isArray(payload) ? "array" : typeof payload}`,
+        });
+    }
+    return payload;
+}
 export async function appendDomainEventCore(deps, args) {
     const isSystemEvent = args.type.startsWith(SYSTEM_EVENT_PREFIX);
     const eventDef = deps.registry.getEvent(args.type);
@@ -42,10 +51,10 @@ export async function appendDomainEventCore(deps, args) {
         const parsed = eventDef.schema.safeParse(args.payload ?? {});
         if (!parsed.success)
             throw validationErrorFromZod(parsed.error);
-        validatedPayload = parsed.data;
+        validatedPayload = requirePayloadObject(parsed.data, args.type);
     }
     else {
-        validatedPayload = (args.payload ?? {});
+        validatedPayload = requirePayloadObject(args.payload ?? {}, args.type);
     }
     // Archive guard: block writes on archived streams. Without this an append
     // would produce an "invisible" row that loadAggregate filters out by default

package/dist/pipeline/cascade-handler.d.ts

@@ -1,6 +1,6 @@
 import type { TableColumns } from "../db/dialect.ts";
 import type { PreDeleteHookFn, Registry } from "../engine/types/index.ts";
 import type { SystemHookDef } from "./lifecycle-pipeline.ts";
-type TableMap = ReadonlyMap<string, TableColumns<any>>;
+type TableMap = ReadonlyMap<string, TableColumns>;
 export declare function createCascadeDeleteHook(registry: Registry, tables: TableMap): SystemHookDef<PreDeleteHookFn>;
 export {};

package/dist/pipeline/dispatch-batch.js

@@ -3,7 +3,7 @@ import { transaction } from "../db/query.js";
 import { InternalError, toWriteErrorInfo, UnprocessableError, writeFailure, } from "../errors/index.js";
 import { createFallbackLogger } from "../logging/utils.js";
 import { parseJsonSafe } from "../utils/safe-json.js";
-import { resolveDbSource } from "./dispatch-shared.js";
+import { resolveAppPoolDb } from "./dispatch-shared.js";
 import { executeNestedWrite, executeWrite } from "./dispatch-write.js";
 import { BatchRollback, isLifecycleResult, wrapToKumiko, } from "./dispatcher-utils.js";
 import { reserveBeforeTransaction, runAsCommand, } from "./pre-transaction-reservations.js";
@@ -209,7 +209,7 @@ async function runBatchBody(ctx, commands, user, requestId, inheritedOrigin) {
     }
     // batch() opens its own outer transaction — needs the top-level
     // connection's `.begin()` (TransactionSql exposes only `.savepoint()`).
-    const db = resolveDbSource(ctx, undefined);
+    const db = resolveAppPoolDb(ctx);
     if (!db || runsWithoutTransaction) {
         // Without a DB connection (or for a perCommand handler, whose writes open their own transactions)
         // there is no transaction to open. Fall back to

package/dist/pipeline/dispatch-query.js

@@ -1,4 +1,4 @@
-import { propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
+import { isPlainObject, propertyOf } from "@cosmicdrift/kumiko-types/type-guards";
 import { hasAccess } from "../engine/access.js";
 import { tenantOverrideDenied } from "../engine/cross-tenant.js";
 import { filterReadFields } from "../engine/field-access.js";
@@ -60,16 +60,16 @@ async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user
     const { registry } = ctx;
     const handlerContext = await buildHandlerContext(ctx, type, user, origin, tx, undefined, includeDeleted, undefined, outerNotifySink);
     let result = await handler.handler({ type, payload, user }, handlerContext);
-    // postQuery-Hooks: fire BEFORE field-access-filter so hooks see raw data
-    // and can merge custom-fields/computed-counts/tags/etc. Each hook is
-    // responsible for its own field-access on values it adds (the filter
-    // below only knows the entity's stammfields).
+    // postQuery hooks run BEFORE field-access filtering so they see raw data and can
+    // merge custom fields, computed counts, tags, and similar values. Each hook is
+    // responsible for applying field access to values it adds; the filter below
+    // only knows the entity's standard fields.
     //
-    // Two firing-pfade kombiniert in dieser Reihenfolge:
+    // Two hook scopes run in this order:
     //   1. Handler-keyed hooks via r.hook({ type: "postQuery", target: "ns:query:list", handler })
-    //      — feuern nur für genau diesen handler
+    //      — run only for that handler
     //   2. Entity-keyed hooks via r.entityHook("postQuery", "property", fn)
-    //      — feuern für ALLE query-handlers des entity
+    //      — run for all query handlers of the entity
     const entityName = registry.getHandlerEntity(type);
     // Handler-keyed postQuery hooks fire for any query (incl. entity-less
     // standalone queries like "ns:dashboard"). Entity-keyed hooks only apply
@@ -87,7 +87,7 @@ async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user
             }
             result = rows;
         }
-        else if (Array.isArray(result.rows)) {
+        else if (isPlainObject(result) && Array.isArray(result["rows"])) {
             // @cast-boundary engine-payload
             const r = result;
             let rows = r.rows;
@@ -121,7 +121,7 @@ async function runQueryHandler(ctx, type, handler, payload, includeDeleted, user
         }
         else {
             const resultAsDbRow = result; // @cast-boundary engine-payload
-            if (Array.isArray(resultAsDbRow.rows)) {
+            if (Array.isArray(resultAsDbRow["rows"])) {
                 // generic handler-result shape narrow
                 const r = result; // @cast-boundary engine-payload
                 result = {

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

@@ -52,6 +52,7 @@ export type DispatchContext = {
 };
 export declare const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10000;
 export declare function resolveDbSource(ctx: DispatchContext, tx: DbTx | undefined): DbConnection | DbTx | undefined;
+export declare function resolveAppPoolDb(ctx: DispatchContext): DbConnection | undefined;
 export declare function isMemberResolutionPrincipal(user: SessionUser): boolean;
 export declare function applyMemberResolutionReadOnly(handlerContext: HandlerContext): HandlerContext;
 export declare function perCommandNestedDenied(targetType: string): InternalError;

package/dist/pipeline/dispatch-shared.js

@@ -1,5 +1,6 @@
-import { escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
-import { requestContext, runWithOrigin } from "../api/request-context.js";
+import { crossTenantReadsGrantFor, escapeHatchFor } from "@cosmicdrift/kumiko-types/handlers";
+import { isAgentToolCallScope, requestContext, runWithOrigin } from "../api/request-context.js";
+import { createHandlerCrossTenantReads } from "../db/cross-tenant-reads.js";
 import { runInSavepoint, selectMany } from "../db/query.js";
 import { createTenantDb, createUncheckedSystemDb, hasTenantColumn, } from "../db/tenant-db.js";
 import { createDerivativesContext } from "../derivatives/derivatives-context.js";
@@ -41,13 +42,13 @@ export { TENANT_TIMEZONE_CONFIG_KEY };
 export const CONFIG_WRITE_SET_TYPE = "config:write:set";
 export const CONFIG_WRITE_RESET_TYPE = "config:write:reset";
 export const DEFAULT_MEMBER_READ_TIMEOUT_MS = 10_000;
-// Narrowing-helper: AppContext.db ist DbConnection|TenantDb|undefined. Die
-// dispatch-Pfade brauchen DbConnection (oder DbTx aus Caller-Scope) für
-// appendEvent/projection-writes; TenantDb-Branch wird hier ausgeschlossen.
+// Narrowing helper: AppContext.db is DbConnection|TenantDb|undefined. The
+// dispatch paths need DbConnection (or DbTx from the caller scope) for
+// appendEvent/projection writes; the TenantDb branch is excluded here.
 export function resolveDbSource(ctx, tx) {
     return tx ?? resolveAppPoolDb(ctx);
 }
-function resolveAppPoolDb(ctx) {
+export function resolveAppPoolDb(ctx) {
     return ctx.appContext.db; // @cast-boundary db-operator
 }
 // ctx.appendEvent — append a domain event onto a specific aggregate stream
@@ -186,6 +187,7 @@ export function applyMemberResolutionReadOnly(handlerContext) {
         // A read as a member gets no system-scope DB, preSave pipeline or file storage.
         runPreSave: undefined,
         systemDb: undefined,
+        crossTenantReads: undefined,
         files: undefined,
         derivatives: undefined,
         ...(handlerContext.jobRunner && { jobRunner: denyingJobRunnerProxy() }),
@@ -326,6 +328,28 @@ readOnlyForTenant = false) {
     const systemDb = isSystem && db
         ? createUncheckedSystemDb(db, rawDbOutsideTransaction, reportEscapeHatch)
         : undefined;
+    // An agent tool call runs with the user's session but feeds the LLM context, so
+    // cross-tenant rows must never reach it, even when unsafeRaw implies the grant.
+    const crossTenantReadsReason = isAgentToolCallScope()
+        ? undefined
+        : crossTenantReadsGrantFor(handlerEscapeHatch)?.reason;
+    const crossTenantReads = dbSource && crossTenantReadsReason !== undefined
+        ? createHandlerCrossTenantReads({
+            db: dbSource,
+            tenantId: user.tenantId,
+            tracer: context.tracer,
+            meter: context.meter,
+            signal: reqCtx?.signal,
+            reason: crossTenantReadsReason,
+            report: reportEscapeHatch,
+            grants: {
+                report: reportEscapeHatch,
+                memberReadOnly: isMemberResolutionPrincipal(user),
+                personalDataGate: buildPersonalDataGate(registry, origin),
+                projectionRegistry: registry,
+            },
+        })
+        : undefined;
     // Exposed as ctx.db below — the internal `db` above stays the real,
     // working TenantDb for this function's own use (config/derivatives
     // accessors, systemDb construction).
@@ -468,8 +492,8 @@ readOnlyForTenant = false) {
     const meter = context.meter;
     const metrics = meter && featureName ? createMetricsHandle(meter, featureName) : createNoopMetricsHandle();
     // ctx.metricsFor(featureName) — shared/library code binds to a feature
-    // name of its own choosing instead of the dispatching handler's
-    // (framework#1844). Unregistered names no-op rather than throw.
+    // name of its own choosing instead of the dispatching handler's.
+    // Unregistered names no-op rather than throw.
     const metricsFor = createMetricsForFactory(meter);
     // A failed inner write has already appended its event and projections when a later
     // step (e.g. an inTransaction hook) fails, and the outer handler may swallow the
@@ -795,7 +819,7 @@ readOnlyForTenant = false) {
     // (context.geoTzProvider) feeds ctx.tz.fromCoordinates / fromAddress.
     //
     // Resolving this via `config()` is a config-table SELECT on every single
-    // dispatch (fw#2462) — ctx.tenantTimezoneCache memoizes it per tenant.
+    // dispatch — ctx.tenantTimezoneCache memoizes it per tenant.
     // dispatch-write.ts invalidates on config:write:set/reset for this key.
     // Only populate from a tx-free read (tx === undefined): a write-path
     // lookup runs inside the caller's own open transaction, and caching a
@@ -835,8 +859,8 @@ readOnlyForTenant = false) {
     });
     // ctx.locale — request-layer signal (X-Locale header → Accept-Language,
     // resolved once at the HTTP boundary by request-id-middleware.ts) wins;
-    // then SessionUser.locale (set at login, see fw#2333 — stale until
-    // re-login, same tradeoff as ctx.tz.user); falls back to the app's
+    // then SessionUser.locale (set at login — stale until re-login, same
+    // tradeoff as ctx.tz.user); falls back to the app's
     // boot-configured defaultLocale, then DEFAULT_LOCALE. Mirrors ctx.tz's
     // Request → Session → Boot-Default chain above.
     const safeUserLocale = user.locale !== undefined && isValidLocaleTag(user.locale) ? user.locale : undefined;
@@ -855,6 +879,7 @@ readOnlyForTenant = false) {
         db: exposedDb,
         dbOutsideTransaction,
         ...(systemDb && { systemDb }),
+        ...(crossTenantReads && { crossTenantReads }),
         log,
         notify,
         ...(config && { config }),
@@ -864,8 +889,7 @@ readOnlyForTenant = false) {
         ...(derivatives && { derivatives }),
         // preSave hooks need `changes`/`previous`/`isNew`, which only exist once
         // a handler actually starts building its write — bound here so entity
-        // CRUD handlers (entity-handlers.ts) can forward it to the executor
-        // (kumiko-framework#1672).
+        // CRUD handlers (entity-handlers.ts) can forward it to the executor.
         ...(lifecycle && {
             runPreSave: (handlerName, changes, previous, isNew) => lifecycle.runPreSave(handlerName, changes, previous, isNew, context),
         }),
@@ -886,11 +910,10 @@ readOnlyForTenant = false) {
         // Lets write handlers call ctx.jobRunner.dispatch(...) directly, same
         // as a follow-up job would (test-stack.ts wires the matching runner).
         ...(jobRunner && { jobRunner }),
-        // ctx.user als Convenience-Alias auf event.user. Der typisch-
-        // intuitive Pfad „der Context kennt seinen User" — ohne den
-        // schreiben Handler `event.user.tenantId` und brechen sich die
-        // Finger an typo-resistenten ctx.user-Patterns. Identisch zum
-        // event.user-Wert; Identity-Switches nutzen weiterhin queryAs/writeAs.
+        // ctx.user as a convenience alias for event.user. The intuitive path—"the
+        // context knows its user"—lets handlers avoid writing `event.user.tenantId`
+        // and reduces errors in ctx.user access patterns. It is identical to
+        // event.user; identity switches still use queryAs/writeAs.
         user,
         _tenantId: user.tenantId,
         ...(hasLiveCommitSink && { scheduleAfterCommit }),
@@ -945,7 +968,7 @@ export async function runHandlerInstrumented(ctx, type, operation, user, inner)
             attributes: dispatcherSpanAttributes(type, operation, user, registry.getHandlerFeature(type)),
         }, async (span) => {
             try {
-                // #3043 — everything the handler writes, including entity-executor
+                // Everything the handler writes, including entity-executor
                 // writes below it, is attributed to this handler.
                 const result = await runWithOrigin({
                     handler: type,

package/dist/pipeline/dispatch-stream.js

@@ -53,7 +53,7 @@ async function* executeStreamInner(ctx, type, payload, user, origin, options) {
     // When access is revoked mid-pull, `iterator.next()` is still in flight.
     // Awaiting `iterator.return()` in that state deadlocks async generators in
     // Bun (overlapping next+return). Track abandonment so finally skips the
-    // await; close is fire-and-forget instead (#1563).
+    // await; close is fire-and-forget instead.
     let abandonedForInvalidation = false;
     try {
         const handlerContext = await buildHandlerContext(ctx, type, user, origin);

package/dist/pipeline/dispatch-write.js

@@ -54,7 +54,7 @@ function isConfigWriteResult(data) {
         return false;
     return typeof data.key === "string";
 }
-// fw#2462: dispatch-shared.ts caches the resolved tenant:config:timezone
+// dispatch-shared.ts caches the resolved tenant:config:timezone
 // value per tenant. A successful write to that key must drop the stale
 // entry — tenant/user scope only affects the writing tenant, system scope
 // changes the fallback every tenant without an override reads, so the
@@ -252,8 +252,8 @@ export async function executeNestedWrite(ctx, type, payload, user, origin, tx, a
     // enumerates columns generically WOULD see `tasks`; no such subscriber
     // exists today. If you add one that iterates `Object.keys(save.data)`,
     // filter by `entity.fields` membership to stay correct.
-    // handler-Result.data ist generic über alle Entity-Handler; nested-
-    // write inspiziert die shape strukturell.
+    // handler-Result.data is generic across all entity handlers; nested-
+    // write inspects the shape structurally.
     const parentWrapper = parentResult.data; // @cast-boundary engine-payload
     const parentRow = (parentWrapper["data"] ?? parentWrapper); // @cast-boundary engine-payload
     const parentId = parentRow["id"];

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

@@ -5,7 +5,7 @@ export type FailedWriteResult = Extract<WriteResult, {
 }>;
 export declare function isFailedWriteResult(result: unknown): result is FailedWriteResult;
 export declare function isLifecycleResult(data: unknown): data is LifecycleResult;
-export declare function isWriteResultShape(result: unknown): boolean;
+export declare function isWriteResultShape(result: unknown): result is WriteResult;
 export declare function describeShape(result: unknown): string;
 export declare function dispatcherSpanAttributes(type: string, operation: "query" | "write" | "stream", user: SessionUser, feature: string | undefined): Record<string, string | number | boolean>;
 export type AfterCommitHook = () => Promise<void>;

package/dist/pipeline/dispatcher-utils.js

@@ -56,7 +56,7 @@ export function extractNestedSpecs(parentType, payload, registry) {
     if (!entityName)
         return null;
     const relations = registry.getRelations(entityName);
-    const source = payload; // @cast-boundary engine-payload — generic dispatch über alle Entity-Types
+    const source = payload; // @cast-boundary engine-payload — generic dispatch across all entity types
     const clean = { ...source };
     const specs = [];
     const typeIssues = [];

package/dist/pipeline/event-consumer-state.js

@@ -4,7 +4,7 @@ import { tableExists } from "../db/schema-inspection.js";
 import { unsafePushTables } from "../db/table-push.js";
 // Reserved sentinel used in the instance_id column for consumers whose
 // delivery is "shared" — i.e. one cursor across all dispatcher instances
-// (the default, pre-Welle-2.7 behaviour). Per-instance consumers store
+// (the default behaviour). Per-instance consumers store
 // the concrete instanceId. Postgres PK columns can't be NULL and
 // `NULL = NULL` is UNKNOWN in SQL — a nullable instance_id would break
 // both uniqueness and PK constraints. The boot-validator refuses to
@@ -62,7 +62,7 @@ export async function createEventConsumerStateTable(db) {
         // no need to pre-check columnNamesOf first. Two instances booting
         // concurrently against the same DB (this table is explicitly
         // multi-instance) both ALTER, neither crashes on "column already
-        // exists" (#1362).
+        // exists".
         await alterTableAddColumn(db, "kumiko_event_consumers", "rearm_count", "integer", " DEFAULT 0", " NOT NULL", 
         /* ifNotExists */ true);
         await alterTableAddColumn(db, "kumiko_event_consumers", "pending_gaps", "jsonb", " DEFAULT '[]'::jsonb", " NOT NULL", 

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

@@ -239,7 +239,7 @@ export async function deliverEvents(consumer, events, context, maxAttempts, stat
 // turn (see applyBatch for why). requestId falls back to a fresh id
 // because the dispatcher runs outside any HTTP request (background poll),
 // and a stable log-correlation handle is still useful for debugging.
-// #3043 — an event this apply writes is attributed to the consumer, not
+// An event this apply writes is attributed to the consumer, not
 // to whatever wrote the triggering event; causationId already links back.
 function buildConsumerRequestScope(consumer, causationSource) {
     const correlationId = causationSource.metadata.correlationId ?? requestContext.generateId();

package/dist/pipeline/event-dispatcher.js

@@ -2,6 +2,7 @@ import { extractPgError } from "../db/pg-error.js";
 import { recordConsumerPassFailure, 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 { createFallbackLogger } from "../logging/utils.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, preRegisterConsumers, selectIdleConsumerKeys, } from "./event-dispatcher-delivery.js";
@@ -52,15 +53,9 @@ export function createEventDispatcher(options) {
     }
     const tracer = options.tracer ?? getFallbackTracer();
     const meter = options.meter ?? getFallbackMeter();
-    // A standalone dispatcher has no logger on its context; console.error keeps the failure in pod logs.
-    const logDispatcherError = (message) => {
-        if (context.log) {
-            context.log.error(message);
-        }
-        else {
-            console.error(message);
-        }
-    };
+    // A standalone dispatcher has no logger on its context; the fallback keeps the failure in pod logs.
+    const dispatcherLog = createFallbackLogger("event-dispatcher", context.log);
+    const logDispatcherError = (message) => dispatcherLog.error(message);
     // Tracks which (consumer, instanceId) pairs already fired
     // kumiko_event_consumer_rearm_exhausted_total, so a consumer stuck dead
     // across many poll passes emits the ops-signal once, not every pass
@@ -79,7 +74,7 @@ export function createEventDispatcher(options) {
         if (count <= PENDING_GAPS_WARN_THRESHOLD || reportedLargeGapSets.has(key))
             return;
         reportedLargeGapSets.add(key);
-        logDispatcherError(`[event-dispatcher] ${consumerName} tracks ${count} pending gap ranges (> ${PENDING_GAPS_WARN_THRESHOLD}); ` +
+        logDispatcherError(`${consumerName} tracks ${count} pending gap ranges (> ${PENDING_GAPS_WARN_THRESHOLD}); ` +
             `a long-running write transaction is probably holding back the snapshot xmin`);
     };
     // Per-(consumer, instanceId) backoff after a thrown pass (see the catch in
@@ -245,13 +240,13 @@ export function createEventDispatcher(options) {
         // consumers see the same disabled-set even if an operator flips a
         // toggle mid-pass, so "this event batch" decisions stay consistent.
         //
-        // Sprint-8a tier-composition: per-tenant resolver per-pass-konsultiert
-        // mit SYSTEM_TENANT_ID. Async-events sind tier-agnostic — wenn ein
-        // Tenant downgrade'd, sollen seine queued events trotzdem verarbeitet
-        // werden (events sind immutable, projection ist eventually-consistent).
-        // Tier-cuts wirken request-time im sync-dispatcher + lifecycle-pipeline,
-        // nicht im async-replay. App-level resolver entscheidet was er bei
-        // SYSTEM_TENANT_ID returnt (typisch: union-of-all-tier-features).
+        // Tier composition: the per-tenant resolver is consulted once per pass
+        // with SYSTEM_TENANT_ID. Async events are tier-agnostic — if a tenant is
+        // downgraded, its queued events are still processed (events are immutable,
+        // and the projection is eventually consistent).
+        // Tier cuts apply at request time in the sync dispatcher and lifecycle
+        // pipeline, not during async replay. The app-level resolver decides what
+        // it returns for SYSTEM_TENANT_ID (typically: the union of all tier features).
         const effective = context.effectiveFeatures?.(SYSTEM_TENANT_ID);
         // Lock-free pre-check, once per pass: which consumers are provably idle
         // (no locking, no xid, no WAL — see selectIdleConsumerKeys). Read
@@ -275,13 +270,7 @@ export function createEventDispatcher(options) {
             if (idlePreCheckErrorLogged) {
                 idlePreCheckErrorLogged = false;
                 emitEventDispatcherListenConnected(meter, listenSubscribed);
-                const recoveredMsg = "[event-dispatcher] idle pre-check recovered, database reachable again";
-                if (context.log) {
-                    context.log.info(recoveredMsg);
-                }
-                else {
-                    console.log(recoveredMsg);
-                }
+                dispatcherLog.info("idle pre-check recovered, database reachable again");
             }
         }
         catch (e) {
@@ -297,7 +286,7 @@ export function createEventDispatcher(options) {
                 if (isConnectionLossError(e))
                     emitEventDispatcherListenConnected(meter, false);
                 const msg = e instanceof Error ? e.message : String(e);
-                const logMsg = `[event-dispatcher] idle pre-check failed, falling back to per-consumer locking every tick until it recovers: ${msg}`;
+                const logMsg = `idle pre-check failed, falling back to per-consumer locking every tick until it recovers: ${msg}`;
                 logDispatcherError(logMsg);
             }
         }
@@ -438,7 +427,7 @@ export function createEventDispatcher(options) {
             // callers and at-least-once-with-duplicate-delivery on the next pass;
             // neither is what we want, so ops needs to see it.
             const msg = e instanceof Error ? e.message : String(e);
-            logDispatcherError(`[event-dispatcher] ${consumer.name} pass failed: ${msg}`);
+            logDispatcherError(`${consumer.name} pass failed: ${msg}`);
             span.setStatus("error", msg);
             // The whole pass rolled back, so markProcessing/persistConsumerOutcome
             // never committed — attempts/last_error are stuck at their pre-pass
@@ -452,7 +441,7 @@ export function createEventDispatcher(options) {
             }
             catch (persistErr) {
                 const persistMsg = persistErr instanceof Error ? persistErr.message : String(persistErr);
-                const failureMsg = `[event-dispatcher] ${consumer.name} failed to persist pass-failure state: ${persistMsg}`;
+                const failureMsg = `${consumer.name} failed to persist pass-failure state: ${persistMsg}`;
                 logDispatcherError(failureMsg);
             }
             // Escalate the backoff so this consumer isn't retried on the very
@@ -519,7 +508,7 @@ export function createEventDispatcher(options) {
                 catch (e) {
                     emitEventDispatcherListenConnected(meter, false);
                     const msg = e instanceof Error ? e.message : String(e);
-                    context.log?.error(`[event-dispatcher] pg LISTEN failed: ${msg}`);
+                    dispatcherLog.error("pg LISTEN failed", { err: msg });
                 }
             }
         },

package/dist/pipeline/irreversible-operation-gate.js

@@ -46,7 +46,7 @@ export function assertIrreversibleOperationAllowed(operation) {
 // Fields flagged readAsInstruction: true have their write payload presence checked here — the
 // same reasoning as assertIrreversibleOperationAllowed, but the irreversible property belongs to
 // the target field, not the verb. Presence in the payload (not a value comparison against the
-// loaded row) is the deliberate fail-closed choice — see kumiko-framework#3358.
+// loaded row) is the deliberate fail-closed choice.
 export function assertInstructionFieldWriteAllowed(entityName, verb, writtenFieldNames, instructionFieldNames) {
     const fields = writtenFieldNames.filter((name) => instructionFieldNames.includes(name));
     // skip: the write touches no readAsInstruction field.

package/dist/pipeline/lifecycle-pipeline.js

@@ -5,17 +5,17 @@ function resolveTracer(context) {
     return context.tracer ?? getFallbackTracer();
 }
 /**
- * Resolve effective-feature set for the active context's tenant.
+ * Resolves the effective feature set for the active context's tenant.
  *
- * `_tenantId` wird vom dispatcher beim HandlerContext-Bau aus `user.tenantId`
- * gespiegelt. Bei legacy-callsites ohne user (system-jobs, boot-time
- * pipeline) ist es undefined — `effectiveFeatures(undefined)` wäre type-
- * unsafe; wir return undefined und behandeln das als "all features on"
- * (registry filterhooks akzeptieren undefined als "skip filter").
+ * `_tenantId` is copied from `user.tenantId` when the dispatcher builds the
+ * HandlerContext. Legacy call sites without a user (system jobs, boot-time
+ * pipeline) leave it undefined; `effectiveFeatures(undefined)` is type-unsafe,
+ * so this returns undefined and treats that as "all features on" (registry
+ * filter hooks accept undefined to skip filtering).
  *
- * Single source — die 4 lifecycle-hook-callsites (preSave, postSave,
- * preDelete, postDelete) rufen alle hier durch, damit der tenant-
- * scoping-Pfad nie inkonsistent ist.
+ * This is the single path used by all four lifecycle-hook call sites
+ * (preSave, postSave, preDelete, postDelete), keeping tenant scoping
+ * consistent.
  */
 function currentEffectiveFeatures(context) {
     if (context._tenantId === undefined)

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

@@ -63,9 +63,7 @@ export async function runInMemberReadOnlyTransaction(ctx, tx, fn) {
             });
         }
         // Savepoint even on the pool path: Postgres rejects a READ WRITE reset (SQLSTATE 25001) inside a subtransaction.
-        return await transaction(pool, (outer) => 
-        // @cast-boundary driver begin() handle — structurally a DbTx, same shape runInSavepoint's caller relies on
-        runInDiscardedReadOnlySavepoint(outer, timeoutMs, true, fn));
+        return await transaction(pool, (outer) => runInDiscardedReadOnlySavepoint(outer, timeoutMs, true, fn));
     }
     catch (e) {
         if (e instanceof AccessDeniedError)

package/dist/pipeline/msp-rebuild.js

@@ -159,7 +159,7 @@ async function replayMultiStreamProjectionIntoShadow(mspName, deps) {
         durationMs: Date.now() - startedAt,
         // countColumnDrift is single-table (public.<t> vs kumiko_rebuild.<t>) and
         // not wired into the multi-stream rebuild path — MSPs don't run the
-        // implicit-projection ghost-row guard either. #916 scope is single-table.
+        // implicit-projection ghost-row guard either. The scope is single-table.
         columnDriftCount: 0,
     };
     if (deps.meter) {

package/dist/pipeline/projection-rebuild.js

@@ -5,8 +5,10 @@ import { withoutStatementTimeout } from "../db/statement-timeout.js";
 import { withExecutorManagedWrites } from "../db/tenant-db.js";
 import { eventsTable, getEventsHighWaterMark, upcastStoredEvent, } from "../event-store/index.js";
 import { createRebuildDeadLetterTable, recordRebuildDeadLetters, } from "../event-store/rebuild-dead-letter.js";
+import { createFallbackLogger } from "../logging/utils.js";
 import { emitProjectionRebuild } from "../observability/standard-metrics.js";
 import { projectionStateTable } from "./projection-state.js";
+const log = createFallbackLogger("kumiko:projection-rebuild");
 // Events replayed per catch-up batch. Each batch is a fresh READ COMMITTED
 // SELECT, so a batch shorter than this means the currently-committed tail is
 // drained.
@@ -32,7 +34,7 @@ function rowToStoredEvent(row) {
         createdBy: row.createdBy,
     };
 }
-// Ops-facing log line for countColumnDrift's result. No-op when clean. #916.
+// Ops-facing log line for countColumnDrift's result. No-op when clean.
 function warnOnColumnDrift(projectionName, tableName, drift) {
     // skip: no drift found — nothing to warn about
     if (drift.rowCount === 0)
@@ -41,7 +43,7 @@ function warnOnColumnDrift(projectionName, tableName, drift) {
     const countLabel = sampledIds.size < drift.rowCount
         ? `${drift.rowCount} (sample truncated)`
         : String(drift.rowCount);
-    console.warn(`projection-rebuild "${projectionName}": ${countLabel} live row(s) in "${tableName}" have ` +
+    log.warn(`projection "${projectionName}": ${countLabel} live row(s) in "${tableName}" have ` +
         `column values that differ from the freshly-replayed shadow (sample: ${drift.sample.join(", ")}). ` +
         "Not blocking — replay wins on swap. Likely cause: a legacy direct-write predating the row's " +
         "event history (#494), or a sensitive custom field pending #972. Investigate if unexpected.");
@@ -71,7 +73,7 @@ async function replayProjectionIntoShadow(projectionName, deps) {
     let lastProcessedEventId = 0n;
     const skipApplyErrors = deps.errorPolicy?.skipApplyErrors === true;
     // Quarantined events, collected in memory and written once after the
-    // replay settles — the #443 full-re-replay path would otherwise duplicate
+    // replay settles — the full-re-replay path would otherwise duplicate
     // the dead-letter rows.
     let skipped = [];
     // One chronological batch of events after lastProcessedEventId, applied into
@@ -145,7 +147,7 @@ async function replayProjectionIntoShadow(projectionName, deps) {
                 // Fence the live table, then drain the final delta. Once ACCESS
                 // EXCLUSIVE is held no concurrent apply can commit a new event, so this
                 // loop terminates and the shadow ends up reflecting every committed
-                // event — closing Phase 1's write-loss window for single-pod rebuilds.
+                // event — closing the write-loss window for single-pod rebuilds.
                 await fenceLiveTable(tx, meta.tableName, fenceLockTimeoutMs);
                 while ((await drainBatch(tx)) === REBUILD_BATCH_SIZE) {
                     // keep draining full batches; a short batch ends the loop
@@ -153,7 +155,7 @@ async function replayProjectionIntoShadow(projectionName, deps) {
                 // Fenced → the subscribed-event set is final (every live apply blocks
                 // on the live-table lock). If fewer events were applied than exist, a
                 // lower-id event committed late during the unlocked phase and the
-                // id-cursor leapt past it (#443). Rebuild the shadow from scratch and
+                // id-cursor leapt past it. Rebuild the shadow from scratch and
                 // replay the whole log under the fence: a fresh shadow means no
                 // double-apply (the rejected "re-drain into a populated shadow" hazard),
                 // and the full-replay cost is paid only on this rare detected path.
@@ -184,12 +186,12 @@ async function replayProjectionIntoShadow(projectionName, deps) {
             }
             // Guard the swap: abort if the process has no blind-index key configured
             // but the live table already has populated bidx columns — the rebuild
-            // would otherwise silently null them out (fw#3091). Applies to every
+            // would otherwise silently null them out. Applies to every
             // projection, not just implicit ones: the shadow always gets a fresh
             // computeBlindIndexValues() pass regardless of projection kind.
             await assertNoBlindIndexLoss(tx, meta.tableName, meta, projectionName);
             // Guard the swap: abort if the live table holds a row no event can
-            // reconstruct (#498 ghost — direct-inserted without a .created event),
+            // reconstruct (ghost — direct-inserted without a .created event),
             // which the swap would silently drop. Implicit projections only.
             if (projection.isImplicit === true) {
                 await assertNoUnreachableLiveRows(tx, projectionName, meta.tableName, sourcesList, projection.extraSourceRowIds);
@@ -249,11 +251,10 @@ export async function getProjectionState(db, projectionName) {
 // The registry is the source-of-truth for which projections exist; the
 // state table holds per-projection rebuild info and may be sparse.
 //
-// Implicit-Projections (auto-registered pro r.entity, eine pro entity)
-// werden default ausgefiltert — sie sind als rebuild-Ziele weiter mit
-// `<feature>:projection:<entity>-entity` adressierbar, aber in `kumiko
-// project list` würden sie das Bild dominieren ohne Mehrwert. Mit
-// `{ includeImplicit: true }` opt-in einschalten.
+// Implicit projections (auto-registered by r.entity, one per entity) are filtered
+// out by default. They stay addressable as rebuild targets via
+// `<feature>:projection:<entity>-entity`, but would dominate `kumiko project list`
+// without adding information. Opt in with `{ includeImplicit: true }`.
 export async function listProjectionsWithState(db, registry, options = {}) {
     const projections = registry.getAllProjections();
     const stateRows = await selectMany(db, projectionStateTable);