@cosmicdrift/kumiko-framework 0.328.0 → 0.328.1

package/dist/pipeline/idempotency.js

@@ -0,0 +1,115 @@
+import { InternalError } from "../errors/index.js";
+import { generateId } from "../utils/index.js";
+import { RedisKeys } from "./redis-keys.js";
+// Sentinel prefix stored under the key while the handler is running. Each
+// acquisition appends a unique token so store() can later prove it still
+// owns the lock it started with (see storeScript below) instead of blindly
+// overwriting whatever is currently there.
+const PENDING_PREFIX = "__pending__:";
+export function createIdempotencyGuard(redis, options = {}) {
+    const ttl = options.ttlSeconds ?? 300;
+    // Max time a single handler is allowed to hold the in-progress lock before
+    // a parallel retry is allowed to try again. Short enough that a crashed
+    // handler doesn't permanently block retries, long enough to cover normal
+    // batch durations.
+    const pendingTtl = options.pendingTtlSeconds ?? 30;
+    // Must stay comfortably above pendingTtl: a wait shorter than the lock's
+    // own TTL makes a retry give up and re-run the handler while the original
+    // call is still legitimately in flight — the exact case this lock exists
+    // to prevent. Clamped rather than trusted so a misconfigured explicit
+    // option can't reintroduce that inversion.
+    const waitTimeoutMs = Math.max(options.waitTimeoutMs ?? 35_000, pendingTtl * 1000 + 5_000);
+    const pollIntervalMs = options.pollIntervalMs ?? 50;
+    const prefix = RedisKeys.idempotency;
+    // Atomic compare-and-swap: only persist the result if the key still holds
+    // the exact pending token this run acquired. If a parallel retry reclaimed
+    // an expired lock in the meantime, this is a no-op — the reclaiming run
+    // owns the key now and will persist the authoritative result itself.
+    const storeScript = `
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+      redis.call("set", KEYS[1], ARGV[2], "EX", ARGV[3])
+      return 1
+    else
+      return 0
+    end
+  `;
+    // Same CAS guard as storeScript: only clear the lock if we still own it.
+    // A stale token (lock already reclaimed by a new owner) is a no-op.
+    const releaseScript = `
+    if redis.call("get", KEYS[1]) == ARGV[1] then
+      return redis.call("del", KEYS[1])
+    else
+      return 0
+    end
+  `;
+    async function tryAcquire(key) {
+        const token = `${PENDING_PREFIX}${generateId()}`;
+        const acquired = await redis.set(key, token, "EX", pendingTtl, "NX");
+        return acquired === "OK" ? token : null;
+    }
+    return {
+        // Returns:
+        //   { status: "acquired", token } — caller owns the in-progress lock,
+        //     proceed to run the handler and then call store() with this token.
+        //   { status: "cached", result }  — serialized result from a concurrent
+        //     or prior request; do not run the handler.
+        //
+        // The old behaviour (pure GET + SET-NX-store) let two parallel requests
+        // both see a cache miss, both execute side-effects, and only one persist
+        // the result. This version uses a pending-marker lock so the second caller
+        // waits for the first to finish and reuses its result.
+        async check(tenantId, userId, requestId) {
+            const key = `${prefix}${tenantId}:${userId}:${requestId}`;
+            const token = await tryAcquire(key);
+            if (token)
+                return { status: "acquired", token };
+            // Lost the race. Poll until the lock holder stores a result, or the
+            // lock expires (handler crashed) and we can try again.
+            const deadline = Date.now() + waitTimeoutMs;
+            while (Date.now() < deadline) {
+                const value = await redis.get(key);
+                if (value === null || value.startsWith(PENDING_PREFIX)) {
+                    if (value === null) {
+                        // Lock expired before a result was stored — try to claim it
+                        // ourselves and proceed as the new owner.
+                        const reclaimed = await tryAcquire(key);
+                        if (reclaimed)
+                            return { status: "acquired", token: reclaimed };
+                    }
+                    await new Promise((resolve) => setTimeout(resolve, pollIntervalMs));
+                    continue;
+                }
+                return { status: "cached", result: value };
+            }
+            // Gave up waiting. By construction waitTimeoutMs > pendingTtl, so the
+            // lock must have expired already — make one last claim attempt rather
+            // than silently reporting ownership we never acquired (that would
+            // reintroduce the double-execute bug). If even that loses the race,
+            // fail loudly instead of running the handler a second time.
+            const finalValue = await redis.get(key);
+            if (finalValue !== null && !finalValue.startsWith(PENDING_PREFIX)) {
+                return { status: "cached", result: finalValue };
+            }
+            const lastResort = await tryAcquire(key);
+            if (lastResort)
+                return { status: "acquired", token: lastResort };
+            throw new InternalError({
+                message: `idempotency lock contention: gave up waiting for requestId ${requestId}`,
+            });
+        },
+        async store(tenantId, userId, requestId, token, result) {
+            const key = `${prefix}${tenantId}:${userId}:${requestId}`;
+            // @cast-boundary db-operator — Lua EVAL return type is untyped in ioredis
+            const written = (await redis.eval(storeScript, 1, key, token, JSON.stringify(result), String(ttl)));
+            // written === 0 means another process reclaimed this key after our
+            // lock expired and is (or already did) persist its own result —
+            // silently skipping here is the fix: the old code did an unconditional
+            // SET and could stomp that fresher result with our stale one.
+            void written;
+        },
+        async release(tenantId, userId, requestId, token) {
+            const key = `${prefix}${tenantId}:${userId}:${requestId}`;
+            await redis.eval(releaseScript, 1, key, token);
+        },
+    };
+}

package/dist/pipeline/index.d.ts

@@ -0,0 +1,34 @@
+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 type { ResolveAuthClaimsArgs } from "./auth-claims-resolver.js";
+export { resolveAuthClaims } from "./auth-claims-resolver.js";
+export { createCascadeDeleteHook } from "./cascade-handler.js";
+export type { Dispatcher } from "./dispatcher.js";
+export { createDispatcher, dispatcherToWriteRef } from "./dispatcher.js";
+export type { DistributedLock } from "./distributed-lock.js";
+export { createDistributedLock } from "./distributed-lock.js";
+export type { EntityCache, EntityCacheOptions } from "./entity-cache.js";
+export { createEntityCache } from "./entity-cache.js";
+export type { ConsumerStatus, PendingGapEntry } from "./event-consumer-state.js";
+export { ConsumerStatuses, createEventConsumerStateTable, eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";
+export type { EventDedup } from "./event-dedup.js";
+export { createEventDedup } from "./event-dedup.js";
+export type { ConsumerProgress, ConsumerRecoveryState, DispatcherPassResult, EventConsumer, EventConsumerBatchHandler, EventConsumerHandler, EventDispatcher, EventDispatcherOptions, } from "./event-dispatcher.js";
+export { createEventDispatcher, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher.js";
+export type { ConsumerCursor } from "./event-dispatcher-delivery.js";
+export { selectConsumerCursorForUpdate } from "./event-dispatcher-delivery.js";
+export type { PruneEventsOptions, PruneEventsResult } from "./event-retention.js";
+export { ConsumerLagError, pruneEvents } from "./event-retention.js";
+export type { IdempotencyGuard } from "./idempotency.js";
+export { createIdempotencyGuard } from "./idempotency.js";
+export { assertInstructionFieldWriteAllowed, assertIrreversibleOperationAllowed, isIrreversibleEntityVerb, } from "./irreversible-operation-gate.js";
+export type { LifecycleHooks, SystemHookDef, SystemHooks } from "./lifecycle-pipeline.js";
+export { createLifecycleHooks } from "./lifecycle-pipeline.js";
+export type { MspRebuildDeps } from "./msp-rebuild.js";
+export { rebuildMultiStreamProjection } from "./msp-rebuild.js";
+export type { ProjectionProgress, RebuildResult } from "./projection-rebuild.js";
+export { getAllProjectionProgress, getProjectionState, listProjectionsWithState, rebuildProjection, } from "./projection-rebuild.js";
+export type { ProjectionStatus } from "./projection-state.js";
+export { createProjectionStateTable, ProjectionStatuses, projectionStateTable, } from "./projection-state.js";
+export { runProjectionsForEvent } from "./projections-runner.js";
+export { ACCESS_INVALIDATION_CONSUMER_NAME, createAccessInvalidationEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, SEARCH_CONSUMER_NAME, SSE_BROADCAST_CONSUMER_NAME, } from "./system-hooks.js";

package/dist/pipeline/index.js

@@ -0,0 +1,19 @@
+export { createEscapeHatchReporter, createEscapeHatchReportWindow, ESCAPE_HATCH_USED_SIGNAL, fallbackEscapeHatchReporter, reportEscapeHatchUse, } 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";
+export { createDistributedLock } from "./distributed-lock.js";
+export { createEntityCache } from "./entity-cache.js";
+export { ConsumerStatuses, createEventConsumerStateTable, eventConsumerStateTable, SHARED_INSTANCE_SENTINEL, } from "./event-consumer-state.js";
+export { createEventDedup } from "./event-dedup.js";
+export { createEventDispatcher, disableConsumer, enableConsumer, getAllConsumerProgress, getConsumerState, listConsumersWithState, restartConsumer, skipPoisonEvent, } from "./event-dispatcher.js";
+export { selectConsumerCursorForUpdate } from "./event-dispatcher-delivery.js";
+export { ConsumerLagError, pruneEvents } from "./event-retention.js";
+export { createIdempotencyGuard } from "./idempotency.js";
+export { assertInstructionFieldWriteAllowed, assertIrreversibleOperationAllowed, isIrreversibleEntityVerb, } from "./irreversible-operation-gate.js";
+export { createLifecycleHooks } from "./lifecycle-pipeline.js";
+export { rebuildMultiStreamProjection } from "./msp-rebuild.js";
+export { getAllProjectionProgress, getProjectionState, listProjectionsWithState, rebuildProjection, } from "./projection-rebuild.js";
+export { createProjectionStateTable, ProjectionStatuses, projectionStateTable, } from "./projection-state.js";
+export { runProjectionsForEvent } from "./projections-runner.js";
+export { ACCESS_INVALIDATION_CONSUMER_NAME, createAccessInvalidationEventConsumer, createSearchEventConsumer, createSseBroadcastEventConsumer, SEARCH_CONSUMER_NAME, SSE_BROADCAST_CONSUMER_NAME, } from "./system-hooks.js";

package/dist/pipeline/irreversible-operation-gate.d.ts

@@ -0,0 +1,4 @@
+import type { EntityDefinition } from "../engine/types/index.js";
+export declare function isIrreversibleEntityVerb(verb: "delete" | "forget", entity: EntityDefinition): boolean;
+export declare function assertIrreversibleOperationAllowed(operation: string): void;
+export declare function assertInstructionFieldWriteAllowed(entityName: string, verb: "create" | "update", writtenFieldNames: readonly string[], instructionFieldNames: readonly string[]): void;

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

@@ -0,0 +1,57 @@
+import { requestContext } from "../api/request-context.js";
+import { AccessDeniedError, FrameworkReasons } from "../errors/index.js";
+// forget hard-purges regardless of softDelete; delete is only irreversible
+// when the entity has no soft-delete recovery path.
+export function isIrreversibleEntityVerb(verb, entity) {
+    return verb === "forget" || !entity.softDelete;
+}
+// The gate reads the directly dispatched entry handler; a write dispatched inside a deferred
+// context (afterCommit hook, job, consumer) gets its own entryHandler and is gated too. Direct
+// executor/KMS calls without one stay ungated in exactly three cases: deleting derived data
+// rebuildable from a reversible source (document-ingest-foundation's forget-extract-with-file-ref
+// consumer, re-created on fileRef.restored), pipelines started by a risk "high" handler or a
+// cron scan (forget cleanup, retention, tenant destroy), and the step-dispatcher erasing the
+// per-dispatch record key once the outcome is recorded. A deferred context can't return the
+// reason to the agent synchronously, so the gate sits at the primitives.
+function assertEntryHandlerHighRisk(args) {
+    const entryHandler = requestContext.get()?.entryHandler;
+    // skip: no entry handler (see above) or the entry handler already resolves "high".
+    if (!entryHandler || entryHandler.risk === "high")
+        return;
+    throw new AccessDeniedError({
+        message: args.buildMessage(entryHandler),
+        details: {
+            reason: args.reason,
+            handler: entryHandler.qn,
+            resolvedRisk: entryHandler.risk,
+            ...args.details,
+        },
+    });
+}
+export function assertIrreversibleOperationAllowed(operation) {
+    assertEntryHandlerHighRisk({
+        reason: FrameworkReasons.irreversibleOperationRequiresHighRisk,
+        buildMessage: (entryHandler) => `Handler "${entryHandler.qn}" performs an irreversible ${operation} but resolves agent risk ` +
+            `"${entryHandler.risk}" — declare agent: { risk: "high" } on "${entryHandler.qn}". The ` +
+            "directly called handler must carry it; delegating via ctx.write/writeAs does not.",
+        details: { 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.
+export function assertInstructionFieldWriteAllowed(entityName, verb, writtenFieldNames, instructionFieldNames) {
+    const fields = writtenFieldNames.filter((name) => instructionFieldNames.includes(name));
+    // skip: the write touches no readAsInstruction field.
+    if (fields.length === 0)
+        return;
+    assertEntryHandlerHighRisk({
+        reason: FrameworkReasons.instructionFieldWriteRequiresHighRisk,
+        buildMessage: (entryHandler) => `Handler "${entryHandler.qn}" ${verb}s "${entityName}" field(s) ${fields.join(", ")} ` +
+            `flagged readAsInstruction: true but resolves agent risk "${entryHandler.risk}" — declare ` +
+            `agent: { risk: "high" } on "${entryHandler.qn}". The directly called handler must carry ` +
+            "it; delegating via ctx.write/writeAs does not.",
+        details: { entityName, verb, fields },
+    });
+}

package/dist/pipeline/lifecycle-pipeline.d.ts

@@ -0,0 +1,29 @@
+import type { AppContext, DeleteContext, HookPhase, PostDeleteBatchHookFn, PostDeleteHookFn, PostSaveBatchHookFn, PostSaveHookFn, PreDeleteHookFn, PreSaveHookFn, Registry, SaveContext } from "../engine/types/index.js";
+import type { EventDedup } from "./event-dedup.js";
+export type SystemHookDef<TFn> = {
+    readonly name: string;
+    readonly priority: number;
+    readonly fn: TFn;
+    readonly phase?: HookPhase;
+};
+export type SystemHooks = {
+    readonly preSave?: readonly SystemHookDef<PreSaveHookFn>[];
+    readonly postSave?: readonly SystemHookDef<PostSaveHookFn>[];
+    readonly postSaveBatch?: readonly SystemHookDef<PostSaveBatchHookFn>[];
+    readonly preDelete?: readonly SystemHookDef<PreDeleteHookFn>[];
+    readonly postDelete?: readonly SystemHookDef<PostDeleteHookFn>[];
+    readonly postDeleteBatch?: readonly SystemHookDef<PostDeleteBatchHookFn>[];
+};
+export type LifecycleHooks = {
+    runPreSave(handlerName: string, changes: Record<string, unknown>, previous: Readonly<Record<string, unknown>>, isNew: boolean, context: AppContext): Promise<Record<string, unknown>>;
+    runPostSave(handlerName: string, result: SaveContext, context: AppContext, phase?: HookPhase): Promise<void>;
+    runPreDelete(handlerName: string, payload: DeleteContext, context: AppContext): Promise<void>;
+    runPostDelete(handlerName: string, payload: DeleteContext, context: AppContext, phase?: HookPhase): Promise<void>;
+    runPostSaveBatch(results: readonly SaveContext[], context: AppContext): Promise<void>;
+    runPostDeleteBatch(payloads: readonly DeleteContext[], context: AppContext): Promise<void>;
+};
+export type LifecycleOptions = {
+    eventDedup?: EventDedup;
+};
+export declare function createLifecycleHooks(registry: Registry, systemHooks?: SystemHooks, options?: LifecycleOptions): LifecycleHooks;
+export declare function buildEventId(handlerName: string, payload: unknown, phase: string): string | null;

package/dist/pipeline/lifecycle-pipeline.js

@@ -0,0 +1,266 @@
+import { HookPhases } from "../engine/types/index.js";
+import { createFallbackLogger } from "../logging/utils.js";
+import { getFallbackTracer } from "../observability/index.js";
+function resolveTracer(context) {
+    return context.tracer ?? getFallbackTracer();
+}
+/**
+ * Resolve 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").
+ *
+ * Single source — die 4 lifecycle-hook-callsites (preSave, postSave,
+ * preDelete, postDelete) rufen alle hier durch, damit der tenant-
+ * scoping-Pfad nie inkonsistent ist.
+ */
+function currentEffectiveFeatures(context) {
+    if (context._tenantId === undefined)
+        return undefined;
+    return context.effectiveFeatures?.(context._tenantId);
+}
+export function createLifecycleHooks(registry, systemHooks = {}, options = {}) {
+    const { eventDedup } = options;
+    function sortByPriority(hooks) {
+        return [...hooks].sort((a, b) => a.priority - b.priority);
+    }
+    // Shared hook execution: runs handler hooks → entity hooks → system hooks.
+    //
+    // Error handling depends on hookPhase:
+    //   - inTransaction: errors THROW (roll back transaction)
+    //   - afterCommit: errors are collected + logged (best-effort)
+    //
+    // Event dedup is only applied in afterCommit phase, because:
+    //   - the key must not be consumed if the transaction later rolls back
+    //   - in-tx hooks run once per commit, dedup there is redundant
+    async function runHookSet(opts) {
+        const throwOnError = opts.hookPhase === HookPhases.inTransaction;
+        // Event dedup: only in afterCommit (see comment above).
+        //
+        // SEMANTICS: pre-claim dedup = "at-most-once". tryAcquire is called before
+        // the hook runs, so if the hook crashes mid-execution, the retry sees
+        // `acquired=false` and skips the rest. This is the right trade-off for
+        // best-effort side-effects like Search Index, SSE broadcast, Audit — a
+        // missed hook is preferable to a duplicate notification. Features that
+        // need at-least-once semantics must not rely on this path; use
+        // ctx.appendEvent + r.multiStreamProjection instead, which the
+        // event-dispatcher retries until the consumer advances.
+        if (eventDedup && opts.hookPhase === HookPhases.afterCommit) {
+            const eventId = buildEventId(opts.handlerName, opts.payload, opts.phaseLabel);
+            if (eventId) {
+                const acquired = await eventDedup.tryAcquire(eventId);
+                if (!acquired) {
+                    opts.context.log?.debug(`${opts.phaseLabel}: skipping ${opts.handlerName} — event ${eventId} already processed (dedup)`);
+                    return;
+                }
+            }
+            else {
+                // Missing id on a save/delete payload is unexpected — CrudExecutor
+                // always returns one. Log so we can spot framework/feature bugs where
+                // a handler emits a non-standard LifecycleResult and accidentally
+                // bypasses dedup.
+                opts.context.log?.warn(`${opts.phaseLabel}: ${opts.handlerName} has no dedup id (payload missing \`id\`) — hook may run multiple times on retry`);
+            }
+        }
+        const errors = [];
+        const tracer = resolveTracer(opts.context);
+        // Common span attributes — populated per-hook below with source/name.
+        const baseAttrs = {
+            "kumiko.hook_type": opts.phaseLabel,
+            "kumiko.hook_phase": opts.hookPhase,
+            "kumiko.handler": opts.handlerName,
+        };
+        for (const hook of opts.getHandlerHooks(opts.handlerName)) {
+            try {
+                await tracer.withSpan("kumiko.pipeline.hook", { attributes: { ...baseAttrs, "kumiko.hook_source": "handler" } }, () => hook(opts.payload, opts.context));
+            }
+            catch (e) {
+                if (throwOnError)
+                    throw e;
+                errors.push({ name: `handler:${opts.handlerName}`, error: e });
+            }
+        }
+        // Shared runner for entity + system hook sets. In afterCommit phase they
+        // run in parallel (independent side-effects, errors are collected); in
+        // inTransaction phase they run sequentially (hooks share ctx.db and each
+        // writes must be observable to subsequent ones). `itemAttrs` lets the
+        // caller attach per-hook span attributes (e.g. the hook name).
+        async function runHooks(items, itemAttrs, errorName, invoke) {
+            // skip: no hooks to run for this phase/handler combo
+            if (items.length === 0)
+                return;
+            const withSpan = (item) => tracer.withSpan("kumiko.pipeline.hook", { attributes: { ...baseAttrs, ...itemAttrs(item) } }, () => invoke(item));
+            if (opts.hookPhase === HookPhases.afterCommit) {
+                const outcomes = await Promise.allSettled(items.map(withSpan));
+                for (let i = 0; i < outcomes.length; i++) {
+                    const outcome = outcomes[i];
+                    if (outcome?.status === "rejected") {
+                        if (throwOnError)
+                            throw outcome.reason;
+                        const item = items[i];
+                        if (item !== undefined)
+                            errors.push({ name: errorName(item), error: outcome.reason });
+                    }
+                }
+            }
+            else {
+                for (const item of items) {
+                    try {
+                        await withSpan(item);
+                    }
+                    catch (e) {
+                        if (throwOnError)
+                            throw e;
+                        errors.push({ name: errorName(item), error: e });
+                    }
+                }
+            }
+        }
+        if (opts.entityName) {
+            const entityName = opts.entityName;
+            await runHooks(opts.getEntityHooks(entityName), () => ({ "kumiko.hook_source": "entity", "kumiko.entity": entityName }), () => `entity:${entityName}`, (hook) => hook(opts.payload, opts.context));
+        }
+        if (opts.systemHookDefs) {
+            const applicable = sortByPriority(opts.systemHookDefs).filter((h) => (h.phase ?? HookPhases.afterCommit) === opts.hookPhase);
+            await runHooks(applicable, (h) => ({ "kumiko.hook_source": "system", "kumiko.hook_name": h.name }), (h) => h.name, (h) => h.fn(opts.payload, opts.context));
+        }
+        if (errors.length > 0) {
+            const logError = createFallbackLogger("lifecycle", opts.context.log);
+            const msg = `${opts.phaseLabel} errors for ${opts.handlerName}`;
+            logError.error(msg, { details: errors.map((e) => `${e.name}: ${e.error}`) });
+        }
+    }
+    return {
+        async runPreSave(handlerName, changes, previous, isNew, context) {
+            let currentChanges = changes;
+            const hookContext = { ...context, previous, isNew };
+            const eff = currentEffectiveFeatures(context);
+            for (const hook of registry.getPreSaveHooks(handlerName, eff)) {
+                currentChanges = await hook(currentChanges, hookContext);
+            }
+            if (systemHooks.preSave) {
+                for (const sysHook of sortByPriority(systemHooks.preSave)) {
+                    currentChanges = await sysHook.fn(currentChanges, hookContext);
+                }
+            }
+            return currentChanges;
+        },
+        async runPostSave(handlerName, result, context, phase = HookPhases.afterCommit) {
+            const eff = currentEffectiveFeatures(context);
+            await runHookSet({
+                handlerName,
+                payload: result,
+                context,
+                entityName: result.entityName,
+                getHandlerHooks: (n) => registry.getPostSaveHooks(n, phase, eff), // @wrapper-known semantic-alias
+                getEntityHooks: (n) => registry.getEntityPostSaveHooks(n, phase, eff), // @wrapper-known semantic-alias
+                systemHookDefs: systemHooks.postSave,
+                phaseLabel: `postSave:${phase}`,
+                hookPhase: phase,
+            });
+        },
+        async runPreDelete(handlerName, payload, context) {
+            // preDelete hooks run in-transaction and throw on failure (not best-effort).
+            // They're used to check invariants before delete, so phase filter is "inTransaction".
+            const eff = currentEffectiveFeatures(context);
+            for (const hook of registry.getPreDeleteHooks(handlerName, HookPhases.inTransaction, eff)) {
+                await hook(payload, context);
+            }
+            if (payload.entityName) {
+                for (const hook of registry.getEntityPreDeleteHooks(payload.entityName, HookPhases.inTransaction, eff)) {
+                    await hook(payload, context);
+                }
+            }
+            if (systemHooks.preDelete) {
+                for (const sysHook of sortByPriority(systemHooks.preDelete)) {
+                    const sysHookPhase = sysHook.phase ?? HookPhases.inTransaction;
+                    if (sysHookPhase !== HookPhases.inTransaction)
+                        continue;
+                    await sysHook.fn(payload, context);
+                }
+            }
+        },
+        async runPostDelete(handlerName, payload, context, phase = HookPhases.afterCommit) {
+            const eff = currentEffectiveFeatures(context);
+            await runHookSet({
+                handlerName,
+                payload,
+                context,
+                entityName: payload.entityName,
+                getHandlerHooks: (n) => registry.getPostDeleteHooks(n, phase, eff), // @wrapper-known semantic-alias
+                getEntityHooks: (n) => registry.getEntityPostDeleteHooks(n, phase, eff), // @wrapper-known semantic-alias
+                systemHookDefs: systemHooks.postDelete,
+                phaseLabel: `postDelete:${phase}`,
+                hookPhase: phase,
+            });
+        },
+        async runPostSaveBatch(results, context) {
+            await runBatchHooks({
+                hooks: systemHooks.postSaveBatch,
+                payload: results,
+                context,
+                phaseLabel: "postSaveBatch",
+            });
+        },
+        async runPostDeleteBatch(payloads, context) {
+            await runBatchHooks({
+                hooks: systemHooks.postDeleteBatch,
+                payload: payloads,
+                context,
+                phaseLabel: "postDeleteBatch",
+            });
+        },
+    };
+    // Runs batch hooks in parallel. Errors are logged but never rethrown —
+    // batch hooks fire after commit, so there's nothing to roll back.
+    async function runBatchHooks(opts) {
+        // skip: no batch hooks registered for this phase
+        if (!opts.hooks || opts.hooks.length === 0)
+            return;
+        const tracer = resolveTracer(opts.context);
+        const baseAttrs = { "kumiko.hook_type": opts.phaseLabel };
+        const outcomes = await Promise.allSettled(sortByPriority(opts.hooks).map((sysHook) => tracer.withSpan("kumiko.pipeline.hook", {
+            attributes: {
+                ...baseAttrs,
+                "kumiko.hook_source": "system",
+                "kumiko.hook_name": sysHook.name,
+            },
+        }, () => sysHook.fn(opts.payload, opts.context))));
+        const failures = outcomes
+            .map((o, i) => ({ outcome: o, name: opts.hooks?.[i]?.name ?? "unknown" }))
+            .filter((x) => x.outcome.status === "rejected");
+        // skip: all batch hooks succeeded, nothing to log
+        if (failures.length === 0)
+            return;
+        const logError = createFallbackLogger("lifecycle", opts.context.log);
+        const msg = `${opts.phaseLabel} errors`;
+        logError.error(msg, { details: failures.map((f) => `${f.name}: ${f.outcome.reason}`) });
+    }
+}
+// Build a unique eventId from handler + entity identity + version + phase.
+// version makes it unique per write (incremented on every update).
+// Exported for unit tests — the warn-log path (null return) is otherwise
+// unreachable through the normal LifecycleResult flow.
+export function buildEventId(handlerName, payload, phase) {
+    if (!payload || typeof payload !== "object")
+        return null;
+    const p = payload;
+    // Aggregate IDs are UUIDs (string) in this framework; legacy int-ids round-
+    // trip cleanly through String(). Anything else (undefined, null, object)
+    // means the payload doesn't carry a dedup-able identity. Also treat id=0
+    // and id="" as absent: serial PKs start at 1 and an empty string is never
+    // a valid aggregate id — safer to skip dedup than to collide on a sentinel.
+    const rawId = p["id"];
+    if (rawId === undefined || rawId === null)
+        return null;
+    if (typeof rawId !== "string" && typeof rawId !== "number")
+        return null;
+    if (rawId === 0 || rawId === "")
+        return null;
+    const data = p["data"]; // @cast-boundary engine-payload
+    const version = data?.["version"]; // @cast-boundary engine-payload
+    return `${handlerName}:${rawId}:${version ?? 0}:${phase}`;
+}

package/dist/pipeline/member-read-only-transaction.d.ts

@@ -0,0 +1,3 @@
+import type { DbTx } from "../db/connection.js";
+import { type DispatchContext } from "./dispatch-shared.js";
+export declare function runInMemberReadOnlyTransaction<T>(ctx: DispatchContext, tx: DbTx | undefined, fn: (readOnlyTx: DbTx) => Promise<T>): Promise<T>;

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

@@ -0,0 +1,68 @@
+import { extractPgError } from "../db/pg-error.js";
+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;
+}
+async function runInDiscardedReadOnlySavepoint(tx, fn) {
+    const discardMarker = {};
+    const settled = {};
+    try {
+        await runInSavepoint(tx, async (sp) => {
+            // kumiko-lint-ignore raw-sql transaction characteristic, no query helper
+            await asRawClient(sp).unsafe("SET TRANSACTION READ ONLY");
+            // @cast-boundary driver savepoint handle — structurally a DbTx, same shape runInSavepoint's caller relies on
+            settled.outcome = { value: await fn(sp) };
+            // Always discarded: RELEASE SAVEPOINT would leave the outer tx read-only too.
+            throw discardMarker;
+        });
+    }
+    catch (e) {
+        if (e !== discardMarker)
+            throw e;
+    }
+    if (!settled.outcome) {
+        throw new InternalError({
+            message: "runInDiscardedReadOnlySavepoint: savepoint ended without settling — this is a bug.",
+        });
+    }
+    return settled.outcome.value;
+}
+export async function runInMemberReadOnlyTransaction(ctx, tx, fn) {
+    try {
+        if (tx)
+            return await runInDiscardedReadOnlySavepoint(tx, fn);
+        const pool = resolveDbSource(ctx, undefined);
+        if (!pool) {
+            throw new InternalError({
+                message: "ctx.queryAsMember requires a database connection — none is configured.",
+            });
+        }
+        // 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, fn));
+    }
+    catch (e) {
+        if (e instanceof AccessDeniedError)
+            throw e;
+        if (isReadOnlyTransactionViolation(e))
+            throw memberResolutionReadOnlyDenied(e);
+        throw e;
+    }
+}

package/dist/pipeline/member-reader.d.ts

@@ -0,0 +1,7 @@
+import type { DbTx } from "../db/connection.js";
+import type { TenantId } from "../engine/types/identifiers.js";
+import type { MemberReader } from "../engine/types/index.js";
+import { type ActiveMembershipPolicy } from "./active-membership.js";
+import { type DispatchContext } from "./dispatch-shared.js";
+export declare const BACKGROUND_READ_POLICY: ActiveMembershipPolicy;
+export declare function createMemberReaderFn(ctx: DispatchContext, tenantId: TenantId, tx?: DbTx): MemberReader;