@cosmicdrift/kumiko-framework 0.328.0 → 0.329.0

package/dist/pipeline/system-hooks.js

@@ -0,0 +1,590 @@
+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";
+// --- Search Index Consumer (async, via event-dispatcher) ---
+//
+// Search-Indexierung läuft seit D.4 als async EventConsumer über den event-
+// dispatcher, nicht mehr als synchroner postSave/postDelete-hook. Das
+// spiegelt Marten's ISubscription-Pattern: ein einziger async Pfad für alle
+// non-inline side-effects.
+//
+// Event → Search-Op Mapping:
+//
+//   <entity>.created     → index(tenantId, doc)   // state = event.payload
+//   <entity>.updated     → index(tenantId, doc)   // state = { ...previous, ...changes }
+//   <entity>.restored    → index(tenantId, doc)   // state = event.payload.previous
+//   <entity>.deleted     → remove(tenantId, type, id)
+//   <entity>.forgotten   → remove(tenantId, type, id)
+//   <entity>.<named>     → index or remove, state read from the live
+//                          projection row (#2765) — a named domain event
+//                          carries only a payload slice, not the full
+//                          entity, so there's no fixed shape to reconstruct
+//                          state from the way created/updated/restored do.
+//                          Only queried when the entity declares searchable
+//                          fields/extensions; no row (hard/soft-deleted) →
+//                          remove, same as the deleted branch.
+//
+// Sensitive fields never reach this consumer for created/updated/restored —
+// event-store-executor.ts strips them before they land in the event log.
+// The projection-row path (named events) reads them from the live table
+// instead, so the same sensitive+searchable boot-guard (entity-handler.ts)
+// keeps them out there too.
+//
+// batchHandler collapses a turn's events to one search-op per
+// (tenantId, entityType, entityId) and issues one indexBatch/removeBatch
+// call per tenant instead of one round-trip per event; handler stays the
+// per-event fallback the dispatcher falls back to when a batch throws.
+export const SEARCH_CONSUMER_NAME = "system:consumer:search";
+// Resolves what one event implies for the search index, without touching
+// the adapter — same decision tree the old per-event handler ran inline.
+async function resolveSearchOperation(event, ctx, registry) {
+    const entityName = event.aggregateType;
+    const verb = event.type.split(".").pop();
+    const tenantId = event.tenantId;
+    // skip: delete/forgotten remove the index entry — reconstruct only
+    // makes sense for created/updated/restored (field data in payload).
+    if (verb === "deleted" || verb === "forgotten") {
+        return { kind: "remove", tenantId, entityType: entityName, entityId: event.aggregateId };
+    }
+    let state;
+    if (verb === "created" || verb === "updated" || verb === "restored") {
+        state = reconstructStateForSearch(event.payload, verb);
+    }
+    else {
+        // #2765 — named domain event: no fixed payload shape to reconstruct
+        // state from. Only worth a projection read when the entity actually
+        // declared searchable fields/extensions — same check
+        // buildSearchDocument makes below, done here first so a non-
+        // searchable entity's named events stay a no-op like before.
+        const entity = registry.getEntity(entityName);
+        const isSearchable = entity !== undefined &&
+            (registry.getSearchableFields(entityName).length > 0 ||
+                registry.getSearchPayloadExtensions(entityName).length > 0);
+        // skip: entity declares no searchable fields/extensions — nothing to
+        // index, stays a no-op with no extra query, same as before #2765.
+        if (!entity || !isSearchable)
+            return undefined;
+        const row = await readProjectionRowForSearch(ctx, registry, entityName, entity, tenantId, event.aggregateId);
+        // skip: no live row (hard-deleted stream, or soft-deleted) — same
+        // outcome as the deleted/forgotten branch above.
+        if (!row) {
+            return { kind: "remove", tenantId, entityType: entityName, entityId: event.aggregateId };
+        }
+        state = row;
+    }
+    state = await decryptSearchableSubjectFields(entityName, state, registry);
+    // skip: erased subject — drop the doc so a rebuild cannot resurrect plaintext.
+    if (hasErasedSearchableSubjectField(entityName, state, registry)) {
+        return { kind: "remove", tenantId, entityType: entityName, entityId: event.aggregateId };
+    }
+    const doc = await buildSearchDocument(entityName, event.aggregateId, state, registry);
+    // skip: entity isn't searchable (no searchable fields declared)
+    if (!doc)
+        return undefined;
+    return { kind: "index", tenantId, doc };
+}
+async function applySearchOperation(searchAdapter, op) {
+    if (op.kind === "index") {
+        await searchAdapter.index(op.tenantId, op.doc);
+    }
+    else {
+        await searchAdapter.remove(op.tenantId, op.entityType, op.entityId);
+    }
+}
+// Collapse key for one search op — same (tenant, entity) target as the old
+// per-event index()/remove() calls addressed, index and remove share the
+// key so a later op in the same turn always overwrites an earlier one
+// (update-then-delete ⇒ remove wins, delete-then-restore ⇒ index wins).
+function searchOperationKey(op) {
+    const entityType = op.kind === "index" ? op.doc.entityType : op.entityType;
+    const entityId = op.kind === "index" ? op.doc.entityId : op.entityId;
+    return `${op.tenantId}\u0000${entityType}\u0000${String(entityId)}`;
+}
+// Resolves every event's op sequentially (the named-event path does DB
+// reads, so resolving in parallel would fan out uncapped concurrent
+// queries for one turn) and collapses to the last op per
+// (tenantId, entityType, entityId) — update-then-delete ⇒ remove wins,
+// delete-then-restore ⇒ index wins.
+async function resolveSearchOperationsByTenant(events, ctx, registry) {
+    const byKey = new Map();
+    for (const event of events) {
+        const op = await resolveSearchOperation(event, ctx, registry);
+        if (!op)
+            continue;
+        byKey.set(searchOperationKey(op), op);
+    }
+    const perTenant = new Map();
+    for (const op of byKey.values()) {
+        let bucket = perTenant.get(op.tenantId);
+        if (!bucket) {
+            bucket = { toIndex: [], toRemove: [] };
+            perTenant.set(op.tenantId, bucket);
+        }
+        if (op.kind === "index")
+            bucket.toIndex.push(op.doc);
+        else
+            bucket.toRemove.push({ entityType: op.entityType, entityId: op.entityId });
+    }
+    return perTenant;
+}
+// Flushes one tenant's collapsed ops — indexBatch/removeBatch when the
+// adapter implements them, otherwise falls back to looping the single-doc
+// methods for that group. Keys were already made disjoint by the collapse
+// in resolveSearchOperationsByTenant, so index-vs-remove order here
+// doesn't matter.
+async function flushSearchOperationsForTenant(searchAdapter, tenantId, bucket) {
+    if (bucket.toIndex.length > 0) {
+        if (searchAdapter.indexBatch) {
+            await searchAdapter.indexBatch(tenantId, bucket.toIndex);
+        }
+        else {
+            for (const doc of bucket.toIndex)
+                await searchAdapter.index(tenantId, doc);
+        }
+    }
+    if (bucket.toRemove.length > 0) {
+        if (searchAdapter.removeBatch) {
+            await searchAdapter.removeBatch(tenantId, bucket.toRemove);
+        }
+        else {
+            for (const item of bucket.toRemove) {
+                await searchAdapter.remove(tenantId, item.entityType, item.entityId);
+            }
+        }
+    }
+}
+export function createSearchEventConsumer(searchAdapter, registry) {
+    return {
+        name: SEARCH_CONSUMER_NAME,
+        // ponytail: count-based maxAttempts, not real backoff — retries hammer
+        // the search adapter every pollIntervalMs during an outage instead of
+        // spacing out. 1200 attempts * 100ms default poll ~= 2min budget for a
+        // still-provisioning Meilisearch to come up at boot (was 10 = ~1s,
+        // killing the consumer near-instantly). Upgrade path: time-based
+        // dead-lettering in event-dispatcher-delivery.ts if 2min isn't enough.
+        errorPolicy: { maxAttempts: 1200 },
+        handler: async (event, ctx) => {
+            const op = await resolveSearchOperation(event, ctx, registry);
+            if (op)
+                await applySearchOperation(searchAdapter, op);
+        },
+        batchHandler: async (events, ctx) => {
+            const perTenant = await resolveSearchOperationsByTenant(events, ctx, registry);
+            for (const [tenantId, bucket] of perTenant) {
+                await flushSearchOperationsForTenant(searchAdapter, tenantId, bucket);
+            }
+        },
+    };
+}
+// #2765 — reads the live projection row for a named domain event, tenant-
+// scoped through createTenantDb the same way MultiStreamProjection appliers
+// scope their apply()-writes (see api/server.ts), on the table the registry
+// actually booted (entityTableFromRegistry) rather than one freshly derived
+// from the entity definition alone. undefined means "no live row" — a hard
+// delete or a soft-delete — which the caller treats as a remove.
+async function readProjectionRowForSearch(ctx, registry, entityName, entity, tenantId, entityId) {
+    // @cast-boundary engine-bridge — consumer ctx.db is always the outer
+    // 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;
+    const table = entityTableFromRegistry(registry, entityName, entity);
+    const where = { id: entityId };
+    if (entity.softDelete && table["isDeleted"]) {
+        where["isDeleted"] = false;
+    }
+    const row = await createTenantDb(baseDb, tenantId).fetchOne(table, where);
+    if (!row)
+        return undefined;
+    return rehydrateCompoundTypes(row, entity);
+}
+// #1610 — subject-annotated searchable fields are ciphertext in the event
+// payload; decrypt into the derived index only. No KMS → omit ciphertext
+// values rather than indexing blobs.
+export async function decryptSearchableSubjectFields(entityName, state, registry) {
+    const entity = registry.getEntity(entityName);
+    if (!entity)
+        return state;
+    const fields = collectSearchableSubjectFields(entity);
+    if (fields.length === 0)
+        return state;
+    const kms = configuredPiiSubjectKms();
+    if (!kms) {
+        const out = { ...state };
+        for (const name of fields) {
+            if (isPiiCiphertext(out[name]))
+                delete out[name];
+        }
+        return out;
+    }
+    try {
+        return await decryptPiiFieldValues(state, fields, kms, {
+            requestId: "system:consumer:search",
+        });
+    }
+    catch (err) {
+        console.warn(`[kumiko:search] decryptSearchableSubjectFields failed for "${entityName}" — ` +
+            `dropping ciphertext fields for this document instead of wedging the consumer.`, err);
+        const out = { ...state };
+        for (const name of fields) {
+            if (isPiiCiphertext(out[name]))
+                delete out[name];
+        }
+        return out;
+    }
+}
+export function hasErasedSearchableSubjectField(entityName, state, registry) {
+    const entity = registry.getEntity(entityName);
+    if (!entity)
+        return false;
+    return collectSearchableSubjectFields(entity).some((name) => state[name] === PII_ERASED_SENTINEL);
+}
+// Rebuild the entity-state a search index needs from the event-payload alone.
+// Three shapes to handle — see event-store-executor.ts for the emitter side.
+function reconstructStateForSearch(payload, verb) {
+    if (verb === "created") {
+        // create: payload IS the entity (minus sensitive fields, already
+        // stripped by event-store-executor)
+        return payload;
+    }
+    if (verb === "updated") {
+        // update: payload = { changes, previous }. Merge to get the new state
+        // the index should reflect. Sensitive fields already filtered out.
+        const previous = payload["previous"] ?? {}; // @cast-boundary engine-payload
+        const changes = payload["changes"] ?? {}; // @cast-boundary engine-payload
+        return { ...previous, ...changes };
+    }
+    // restored: payload = { previous }. The restored entity is whatever the
+    // field-values were at delete time — restore copies them back verbatim.
+    return payload["previous"] ?? {}; // @cast-boundary engine-payload
+}
+// buildSearchDocument runs per save — without dedup a colliding contributor
+// key would spam one warn line per write on the hotpath. Scoped per registry
+// (not module-global) so each app/test instance dedups independently: a
+// process-wide Set would silence the warning for every later registry once any
+// registry hit a given collision, and would leak dedup-state across tests.
+const warnedKeyCollisionsByRegistry = new WeakMap();
+function warnOncePerKeyCollision(registry, entityName, key, isBaseField) {
+    let warned = warnedKeyCollisionsByRegistry.get(registry);
+    if (!warned) {
+        warned = new Set();
+        warnedKeyCollisionsByRegistry.set(registry, warned);
+    }
+    const dedupKey = `${entityName}:${key}`;
+    // skip: already warned for this entity:key collision — dedup the hotpath
+    if (warned.has(dedupKey))
+        return;
+    warned.add(dedupKey);
+    const collidesWith = isBaseField ? `base field "${key}"` : `earlier contributor key "${key}"`;
+    console.warn(`[kumiko:search] searchPayloadExtension on "${entityName}" tried to overwrite ` +
+        `${collidesWith} — keeping the first value. Rename the contributor key.`);
+}
+// Build a SearchDocument from raw field-state. Parallel to the old
+// buildSearchDocument that took a SaveContext — same selector logic, just
+// a different input shape.
+export async function buildSearchDocument(entityName, entityId, state, registry) {
+    const entity = registry.getEntity(entityName);
+    if (!entity)
+        return null;
+    const searchableFields = registry.getSearchableFields(entityName);
+    const extensions = registry.getSearchPayloadExtensions(entityName);
+    // Skip-Guard: kein indexable payload UND keine Extensions → kein doc.
+    // Extensions können auch ohne searchable-Stammfields den index befüllen
+    // (z.B. customFields-only-indexierung), daher muss die check beide
+    // berücksichtigen.
+    if (searchableFields.length === 0 && extensions.length === 0)
+        return null;
+    const embeddedFields = new Set();
+    for (const [fname, fdef] of Object.entries(entity.fields)) {
+        if (fdef.type === "embedded")
+            embeddedFields.add(fname);
+    }
+    const fields = {};
+    for (const f of searchableFields) {
+        const underscoreIdx = f.indexOf("_");
+        if (underscoreIdx > 0) {
+            const parentKey = f.slice(0, underscoreIdx);
+            if (embeddedFields.has(parentKey)) {
+                const subKey = f.slice(underscoreIdx + 1);
+                const parent = state[parentKey];
+                // A list-embedded parent contributes one indexed value per row —
+                // Meilisearch indexes a string array as a searchable multi-value.
+                if (Array.isArray(parent)) {
+                    const values = parent
+                        .filter((row) => Boolean(row) && typeof row === "object")
+                        .map((row) => row[subKey])
+                        .filter((value) => value !== undefined);
+                    if (values.length > 0)
+                        fields[f] = values;
+                }
+                else if (parent && typeof parent === "object") {
+                    const value = parent[subKey];
+                    if (value !== undefined)
+                        fields[f] = value;
+                }
+                continue;
+            }
+        }
+        if (state[f] !== undefined) {
+            fields[f] = state[f];
+        }
+    }
+    // F3 — Search-Payload-Extensions: contributors merge flat fields into the
+    // search-doc (customFields-bundle / tags / computed-counts / etc.).
+    // Sequential await — extensions are expected sync or sub-millisecond async;
+    // sequential keeps the path simple and deterministic.
+    //
+    // Precedence is base-fields-win: a contributor key that collides with a
+    // searchable Stammfield is dropped (not silently merged over the real value)
+    // and warned. A jsonb custom-field that happens to share a Stammfield name
+    // must not shadow the indexed Stammfield.
+    const baseFieldKeys = new Set(Object.keys(fields));
+    for (const contribute of extensions) {
+        const contributed = await contribute({ entityName, entityId, state });
+        for (const [key, value] of Object.entries(contributed)) {
+            if (Object.hasOwn(fields, key)) {
+                warnOncePerKeyCollision(registry, entityName, key, baseFieldKeys.has(key));
+                continue;
+            }
+            fields[key] = value;
+        }
+    }
+    return {
+        entityType: entityName,
+        entityId,
+        weight: entity.searchWeight ?? 1,
+        fields,
+    };
+}
+// --- SSE Broadcast (async, via event-dispatcher) ---
+//
+// SSE-Broadcast läuft seit D.3 als async EventConsumer über den event-
+// dispatcher, nicht mehr als synchroner postSave/postDelete-hook. Das hat
+// zwei Konsequenzen:
+//
+// 1. **Event-native Payload-Shape.** Der SSE-event spiegelt den StoredEvent:
+//    `type` ist event.type ("user.created", "unit.updated"), `data` enthält
+//    id, aggregateType, version und die event-payload — keine künstliche
+//    "system:event:<entity>:<verb>" Hülle mehr. Clients haben direkten
+//    Zugriff auf `payload.changes` + `payload.previous` (wie im event-log).
+// 2. **Eventual consistency statt Read-after-Write.** Ein SSE-Event kommt
+//    ~10–100ms nach dem HTTP-200 (abhängig von pollIntervalMs). UI-Clients
+//    die auf optimistic-update setzen merken das nicht; strictly-waiting
+//    Clients müssten poll-after-write.
+//
+// Tests drain deterministically via `await stack.eventDispatcher.runOnce()`,
+// or via `drainEventConsumers` for this consumer name specifically.
+export const SSE_BROADCAST_CONSUMER_NAME = "system:consumer:sse-broadcast";
+export function createSseBroadcastEventConsumer(sseBroker) {
+    return {
+        name: SSE_BROADCAST_CONSUMER_NAME,
+        // Shared delivery: one cursor reads every event exactly once (fw#2625).
+        // Fanout to every process's own SSE clients happens below, through
+        // sseBroker.pushToChannel — a Redis-backed broker (the default once
+        // REDIS_URL is set) republishes across replicas, so every pod's
+        // clients still see the event without each pod needing its own cursor.
+        delivery: "shared",
+        // History is meaningless here — an SSE push for a client that didn't
+        // exist yet has no audience to replay it to.
+        startFrom: "now",
+        handler: async (event) => {
+            sseBroker.pushToChannel(tenantChannel(event.tenantId), {
+                type: event.type,
+                data: {
+                    id: event.aggregateId,
+                    aggregateType: event.aggregateType,
+                    version: event.version,
+                    payload: event.payload,
+                    createdAt: event.createdAt,
+                },
+            });
+        },
+    };
+}
+// --- Job-Trigger Consumer (async, via event-dispatcher) ---
+//
+// r.job's `trigger.on` historically only fired via the synchronous
+// write-handler dispatch path (dispatch-write.ts's afterCommitHooks calling
+// jobRunner.handleEvent). Events appended any other way — an
+// r.multiStreamProjection's ctx.unsafeAppendEvent, or a raw
+// event-store-executor write (e.g. `files`' fileRef.created) — never
+// reached it, so a job could never trigger on an r.defineEvent-registered
+// event (kumiko-framework#1505).
+//
+// This consumer closes that gap the same way search/SSE do: read every
+// committed event off the shared cursor and re-check job triggers. It is
+// scoped EXACTLY to the gap — the write/query-handler-QN skip below is
+// defense-in-depth: no stored event's `type` is a handler QN today (entity
+// events are "entity.verb"; ctx.appendEvent enforces defineEvent-only
+// ownership), but if that ever changes, this consumer must not re-fire a
+// trigger the synchronous dispatch-write.ts path already handled.
+//
+// Delivery is at-least-once (cursor semantics) where the synchronous path
+// is effectively once — job handlers reached via an r.defineEvent trigger
+// must be idempotent (same expectation r.multiStreamProjection applies
+// already carry).
+export const JOB_TRIGGER_CONSUMER_NAME = "system:consumer:job-trigger";
+export function createJobTriggerEventConsumer(jobRunner, registry) {
+    return {
+        name: JOB_TRIGGER_CONSUMER_NAME,
+        handler: async (event) => {
+            // skip: write/query-handler QN — already dispatched synchronously by
+            // dispatch-write.ts's afterCommitHooks. Re-firing here would
+            // double-enqueue every existing handler-triggered job.
+            if (registry.getWriteHandler(event.type) || registry.getQueryHandler(event.type))
+                return;
+            // skip: no r.defineEvent registered under this type — nothing this
+            // consumer is responsible for.
+            if (!registry.getEvent(event.type))
+                return;
+            const user = {
+                id: event.metadata.userId,
+                tenantId: event.tenantId,
+                roles: [],
+            };
+            await jobRunner.handleEvent(event.type, event.payload, user, {
+                id: event.id,
+                headers: event.metadata.headers ?? {},
+            });
+        },
+    };
+}
+// --- Access-Invalidation Consumer (async, via event-dispatcher) ---
+//
+// #1524 (Design), #1558 (channel + stream subscribe), #1559 (session-revoke
+// emits an event). This consumer is the last leg: it watches for the two
+// event types that can make an already-issued JWT stale mid-stream and
+// pushes an invalidation through sseBroker.publishAccessInvalidation, which
+// dispatch-stream.ts's subscribeAccessInvalidation listener turns into an
+// AccessDeniedError thrown into the open stream.
+//
+// Event types are literal strings, not imports — this package (framework)
+// cannot depend on bundled-features (sessions, tenant own these events),
+// mirrors the es-ops-seed precedent (literal QNs, no subpath import).
+//
+//   "sessions:event:session-revoked" — payload.userId direct (own aggregate,
+//     see bundled-features/sessions/session-revoked-event.ts). Fired for
+//     self-service revoke, the privileged cross-tenant revoke-all-for-user
+//     (SYSTEM_TENANT_ID-anchored DSGVO Art.18 freeze), and the raw
+//     sessionRevoker callback (logout / tenant-switch — the only source
+//     that also sets payload.streamScope, see readSessionRevokedScope below).
+//     fetchPendingEvents has no tenant predicate, so the SYSTEM_TENANT_ID-
+//     anchored event reaches this consumer the same as any other — routing
+//     is purely on payload.userId, never on event.tenantId.
+//   "personal-access-tokens:event:pat-revoked" — payload.userId direct (own
+//     aggregate, see bundled-features/personal-access-tokens/pat-revoked-event.ts).
+//     Fired by both the self-service revoke handler and
+//     revokeAllPatTokensForUser (password-change / MFA-toggle / DSGVO
+//     forget-subject). Always scoped to payload.tokenIds — a PAT revoke
+//     never touches another credential's stream.
+//   "tenant-membership.updated" / "tenant-membership.deleted" — role change
+//     or member removal. userId isn't in payload.changes (update only
+//     carries the changed fields, e.g. { roles }) so it's read from
+//     payload.previous, the full pre-write entity snapshot written by
+//     createEventStoreExecutor. tenantMembershipEntity declares no
+//     encrypted/PII fields, so previous.userId is plaintext — no KMS
+//     decrypt step (see kumiko-framework#1560 PR discussion; the issue's
+//     original handoff assumed encryption that doesn't apply here).
+//
+// Over-invalidation (e.g. tenant-membership.updated fired by something
+// other than a role change) is fail-safe: the stream closes, the client
+// reconnects and re-authorizes. No opt-out/allowlist — #1524 chose
+// global-by-default specifically so this can't be silently disabled per
+// handler.
+//
+// Scope note: entityEventName also emits "tenant-membership.forgotten" (DSGVO
+// erasure) and ".restored" — .restored re-grants access so ignoring it is
+// correct, .forgotten is not currently produced by any user-data-rights
+// pipeline for memberships but would be revocation-relevant if it ever is.
+// Out of #1560's stated scope (session-revoke + role/membership change),
+// tracked rather than handled speculatively here.
+export const ACCESS_INVALIDATION_CONSUMER_NAME = "system:consumer:access-invalidation";
+const SESSION_REVOKED_EVENT_TYPE = "sessions:event:session-revoked";
+const PAT_REVOKED_EVENT_TYPE = "personal-access-tokens:event:pat-revoked";
+const TENANT_MEMBERSHIP_UPDATED_EVENT_TYPE = "tenant-membership.updated";
+const TENANT_MEMBERSHIP_DELETED_EVENT_TYPE = "tenant-membership.deleted";
+function readUserIdFromPreviousSnapshot(payload) {
+    const previous = payload["previous"];
+    if (typeof previous !== "object" || previous === null)
+        return undefined;
+    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"
+//      scope, closes exactly those sids.
+//   2. Otherwise, a non-empty keptSessionId ("revoke all others") → spares
+//      that one sid, same as before streamScope existed.
+//   3. Otherwise → userwide. Events appended before streamScope existed have
+//      neither field and fall straight through to this same userwide default
+//      they always had — a replay is unaffected.
+function readSessionRevokedScope(payload) {
+    if (payload["streamScope"] === "revoked-sessions") {
+        const sessionIds = readNonEmptyStringArray(payload["sessionIds"]);
+        if (sessionIds)
+            return { kind: "sessions", sessionIds };
+    }
+    const keptSessionId = payload["keptSessionId"];
+    if (typeof keptSessionId === "string" && keptSessionId.length > 0) {
+        return { kind: "all-except-session", keptSessionId };
+    }
+    return { kind: "user" };
+}
+// pat-revoked is always narrow — a PAT revoke never has a reason to close
+// another credential's stream. Malformed tokenIds fail closed to userwide
+// rather than silently dropping the invalidation.
+function readPatRevokedScope(payload) {
+    const tokenIds = readNonEmptyStringArray(payload["tokenIds"]);
+    return tokenIds ? { kind: "pat-tokens", tokenIds } : { kind: "user" };
+}
+export function createAccessInvalidationEventConsumer(sseBroker) {
+    return {
+        name: ACCESS_INVALIDATION_CONSUMER_NAME,
+        // Shared delivery, same reasoning as SSE broadcast (fw#2625): one
+        // cursor reads every event once and calls sseBroker.publishAccessInvalidation
+        // below, which a Redis-backed broker republishes to every replica's
+        // subscribeAccessInvalidation listeners — no per-instance cursor needed
+        // to reach every process's open streams for that user.
+        delivery: "shared",
+        // A revocation for a session/membership from before this instance
+        // existed has nothing to invalidate — replaying it would be a no-op at
+        // best and a spurious stream-close at worst.
+        startFrom: "now",
+        handler: async (event) => {
+            if (event.type === SESSION_REVOKED_EVENT_TYPE) {
+                const userId = event.payload["userId"];
+                // skip: malformed session-revoked payload — fail open on this one
+                // event rather than dead-lettering the whole consumer (halt-on-
+                // poison would otherwise permanently stop access-invalidation for
+                // every user behind one bad row).
+                if (typeof userId !== "string" || userId.length === 0)
+                    return;
+                sseBroker.publishAccessInvalidation(userId, readSessionRevokedScope(event.payload));
+            }
+            if (event.type === PAT_REVOKED_EVENT_TYPE) {
+                const userId = event.payload["userId"];
+                // skip: malformed pat-revoked payload — same fail-open reasoning as
+                // session-revoked above.
+                if (typeof userId !== "string" || userId.length === 0)
+                    return;
+                sseBroker.publishAccessInvalidation(userId, readPatRevokedScope(event.payload));
+            }
+            if (event.type === TENANT_MEMBERSHIP_UPDATED_EVENT_TYPE ||
+                event.type === TENANT_MEMBERSHIP_DELETED_EVENT_TYPE) {
+                const userId = readUserIdFromPreviousSnapshot(event.payload);
+                // skip: previous snapshot missing/malformed userId — same fail-open
+                // reasoning as above.
+                if (userId === undefined)
+                    return;
+                sseBroker.publishAccessInvalidation(userId);
+            }
+        },
+    };
+}

package/dist/pipeline/system-identity-switch.d.ts

@@ -0,0 +1,30 @@
+import type { TenantId } from "../engine/types/identifiers.js";
+import type { ActiveMembershipResult, EscapeHatchDeclaration, EscapeHatchReporter, HandlerContext, LifecycleHookFn, MemberReader, SessionUser, WriteResult } from "../engine/types/index.js";
+import { AccessDeniedError } from "../errors/index.js";
+export type QueryAsFn = (user: SessionUser, qn: string, payload: unknown) => Promise<unknown>;
+export type WriteAsFn = (user: SessionUser, qn: string, payload: unknown) => Promise<WriteResult>;
+export type ResolveActiveMembershipFn = (userId: string, tenantId: TenantId) => Promise<ActiveMembershipResult>;
+export type ProjectionReader = HandlerContext["queryProjection"];
+export type IdentitySwitch = {
+    readonly queryAs: QueryAsFn;
+    readonly writeAs: WriteAsFn;
+};
+export type IdentitySwitchAudit = {
+    readonly reason: string | undefined;
+    readonly report: EscapeHatchReporter;
+};
+export declare function isSystemIdentity(user: SessionUser): boolean;
+export declare function isSelfDelegation(caller: SessionUser, asUser: SessionUser): boolean;
+export declare function isIdentitySwitchAllowed(caller: SessionUser | undefined, asUser: SessionUser, hasGrant: boolean): boolean;
+export declare function systemIdentitySwitchDenied(callerLabel: string): AccessDeniedError;
+export declare function identitySwitchDenied(callerLabel: string, asUser: SessionUser): AccessDeniedError;
+export declare function unsafeAllTenantsDenied(callerLabel: string): AccessDeniedError;
+type MemberReaderAudit = IdentitySwitchAudit & {
+    readonly tenantId: TenantId;
+};
+export declare function createGatedIdentitySwitch(callerLabel: string, caller: SessionUser | undefined, hasGrant: boolean, ungated: IdentitySwitch, audit?: IdentitySwitchAudit): IdentitySwitch;
+export declare function createGatedMemberReader(callerLabel: string, allowSystemIdentity: boolean, ungated: MemberReader, audit?: MemberReaderAudit): MemberReader;
+export declare function createGatedProjectionReader(callerLabel: string, hasGrant: boolean, ungated: ProjectionReader, audit?: IdentitySwitchAudit): ProjectionReader;
+export declare function withHookEscapeHatchGrant<TContext extends object>(context: TContext, callerLabel: string, escapeHatch: EscapeHatchDeclaration | undefined): TContext;
+export declare function bindHookEscapeHatchGrant(fn: LifecycleHookFn, label: string, escapeHatch: EscapeHatchDeclaration | undefined): LifecycleHookFn;
+export {};