@cosmicdrift/kumiko-framework 0.327.0 → 0.328.1

package/src/pipeline/system-hooks.ts

@@ -1,695 +0,0 @@
-import type { AccessInvalidationScope, SseBroker } from "../api/sse-broker";
-import {
-  collectSearchableSubjectFields,
-  configuredPiiSubjectKms,
-  decryptPiiFieldValues,
-  isPiiCiphertext,
-  PII_ERASED_SENTINEL,
-} from "../crypto";
-import { createTenantDb, entityTableFromRegistry, rehydrateCompoundTypes } from "../db";
-import type { DbConnection, DbRow } from "../db/connection";
-import { tenantChannel } from "../engine/constants";
-import type {
-  AppContext,
-  EntityDefinition,
-  EntityId,
-  JobRunnerRef,
-  Registry,
-  SessionUser,
-  TenantId,
-} from "../engine/types";
-import type { StoredEvent } from "../event-store";
-import type { SearchAdapter, SearchDocument } from "../search/types";
-import type { EventConsumer } from "./event-dispatcher";
-
-// --- 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";
-
-// #3227 — one resolved search operation for a single event: either the
-// document to (re-)index or the entityType/entityId to remove. A
-// discriminated union so the batch collapse step (last op per key wins)
-// doesn't need to special-case index vs remove.
-export type SearchOperation =
-  | { readonly kind: "index"; readonly tenantId: TenantId; readonly doc: SearchDocument }
-  | {
-      readonly kind: "remove";
-      readonly tenantId: TenantId;
-      readonly entityType: string;
-      readonly entityId: EntityId;
-    };
-
-// 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: StoredEvent,
-  ctx: AppContext,
-  registry: Registry,
-): Promise<SearchOperation | undefined> {
-  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: Record<string, unknown>;
-  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: SearchAdapter,
-  op: SearchOperation,
-): Promise<void> {
-  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: SearchOperation): string {
-  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)}`;
-}
-
-type SearchOperationsByTenant = Map<
-  TenantId,
-  { toIndex: SearchDocument[]; toRemove: { entityType: string; entityId: 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: readonly StoredEvent[],
-  ctx: AppContext,
-  registry: Registry,
-): Promise<SearchOperationsByTenant> {
-  const byKey = new Map<string, SearchOperation>();
-  for (const event of events) {
-    const op = await resolveSearchOperation(event, ctx, registry);
-    if (!op) continue;
-    byKey.set(searchOperationKey(op), op);
-  }
-
-  const perTenant: SearchOperationsByTenant = 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: SearchAdapter,
-  tenantId: TenantId,
-  bucket: { toIndex: SearchDocument[]; toRemove: { entityType: string; entityId: EntityId }[] },
-): Promise<void> {
-  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: SearchAdapter,
-  registry: Registry,
-): EventConsumer {
-  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: AppContext,
-  registry: Registry,
-  entityName: string,
-  entity: EntityDefinition,
-  tenantId: TenantId,
-  entityId: EntityId,
-): Promise<Record<string, unknown> | undefined> {
-  // @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 as DbConnection | undefined;
-  if (!baseDb) return undefined;
-  const table = entityTableFromRegistry(registry, entityName, entity);
-  const where: Record<string, unknown> = { 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: string,
-  state: Record<string, unknown>,
-  registry: Registry,
-): Promise<Record<string, unknown>> {
-  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: string,
-  state: Record<string, unknown>,
-  registry: Registry,
-): boolean {
-  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: Record<string, unknown>,
-  verb: "created" | "updated" | "restored",
-): Record<string, unknown> {
-  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"] as Record<string, unknown> | undefined) ?? {}; // @cast-boundary engine-payload
-    const changes = (payload["changes"] as Record<string, unknown> | undefined) ?? {}; // @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"] as Record<string, unknown> | undefined) ?? {}; // @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<Registry, Set<string>>();
-function warnOncePerKeyCollision(
-  registry: Registry,
-  entityName: string,
-  key: string,
-  isBaseField: boolean,
-): void {
-  let warned = warnedKeyCollisionsByRegistry.get(registry);
-  if (!warned) {
-    warned = new Set<string>();
-    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: string,
-  entityId: EntityId,
-  state: Record<string, unknown>,
-  registry: Registry,
-): Promise<SearchDocument | null> {
-  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<string>();
-  for (const [fname, fdef] of Object.entries(entity.fields)) {
-    if (fdef.type === "embedded") embeddedFields.add(fname);
-  }
-
-  const fields: Record<string, unknown> = {};
-  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): row is DbRow => 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 as DbRow)[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: SseBroker): EventConsumer {
-  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: JobRunnerRef,
-  registry: Registry,
-): EventConsumer {
-  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: SessionUser = {
-        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: Record<string, unknown>): string | undefined {
-  const previous = payload["previous"];
-  if (typeof previous !== "object" || previous === null) return undefined;
-  const userId = (previous as Record<string, unknown>)["userId"];
-  return typeof userId === "string" && userId.length > 0 ? userId : undefined;
-}
-
-function readNonEmptyStringArray(value: unknown): string[] | undefined {
-  if (!Array.isArray(value) || value.length === 0) return undefined;
-  return value.every((v): v is string => 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: Record<string, unknown>): AccessInvalidationScope {
-  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: Record<string, unknown>): AccessInvalidationScope {
-  const tokenIds = readNonEmptyStringArray(payload["tokenIds"]);
-  return tokenIds ? { kind: "pat-tokens", tokenIds } : { kind: "user" };
-}
-
-export function createAccessInvalidationEventConsumer(sseBroker: SseBroker): EventConsumer {
-  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);
-      }
-    },
-  };
-}