@cosmicdrift/kumiko-framework 0.158.2 → 0.160.0

package/src/pipeline/__tests__/lifecycle-pipeline.test.ts

@@ -4,6 +4,7 @@ import {
   createEntity,
   createRegistry,
   createTextField,
+  type DeleteContext,
   defineFeature,
   type PostSaveHookFn,
   type PreSaveHookFn,
@@ -528,3 +529,210 @@ describe("buildEventId — dedup key construction", () => {
     expect(buildEventId("handler", { id: 0 }, "phase")).toBeNull();
   });
 });
+
+// --- PreDelete / PostDelete pipeline ---
+
+const deletectx: DeleteContext = {
+  kind: "delete",
+  id: 1,
+  data: { email: "test@test.de" },
+  entityName: "user",
+};
+
+describe("runPreDelete", () => {
+  test("runs feature + entity + system hooks, all inTransaction (throw on error)", async () => {
+    const calls: string[] = [];
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("preDelete", "user", async () => {
+        calls.push("handler");
+      });
+      r.hook("preDelete", { allOf: "user" }, async () => {
+        calls.push("entity");
+      });
+    });
+    const registry = createRegistry([feature]);
+    const systemHooks: SystemHooks = {
+      preDelete: [
+        {
+          name: "sys",
+          priority: 1000,
+          fn: async () => {
+            calls.push("system");
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    await pipeline.runPreDelete("test:write:user", deletectx, {});
+    expect(calls).toEqual(["handler", "entity", "system"]);
+  });
+
+  test("a hook throwing aborts the delete (rejects, not swallowed)", async () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("preDelete", "user", async () => {
+        throw new Error("blocked-delete");
+      });
+    });
+    const registry = createRegistry([feature]);
+    const pipeline = createLifecycleHooks(registry);
+    await expect(pipeline.runPreDelete("test:write:user", deletectx, {})).rejects.toThrow(
+      "blocked-delete",
+    );
+  });
+
+  test("system hook with a non-inTransaction phase is skipped", async () => {
+    const registry = makeRegistry();
+    const calls: string[] = [];
+    const systemHooks: SystemHooks = {
+      preDelete: [
+        {
+          name: "sys",
+          priority: 1000,
+          phase: "afterCommit",
+          fn: async () => {
+            calls.push("system");
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    await pipeline.runPreDelete("test:write:user", deletectx, {});
+    expect(calls).toEqual([]);
+  });
+});
+
+describe("runPostDelete", () => {
+  test("runs feature then system hooks (best-effort by default phase)", async () => {
+    const calls: string[] = [];
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook("postDelete", "user", async () => {
+        calls.push("feature");
+      });
+    });
+    const registry = createRegistry([feature]);
+    const systemHooks: SystemHooks = {
+      postDelete: [
+        {
+          name: "sys",
+          priority: 1000,
+          fn: async () => {
+            calls.push("system");
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(registry, systemHooks);
+    await pipeline.runPostDelete("test:write:user", deletectx, {});
+    expect(calls).toEqual(["feature", "system"]);
+  });
+
+  test("inTransaction phase: hook errors throw", async () => {
+    const feature = defineFeature("test", (r) => {
+      r.entity("user", createEntity({ table: "Users", fields: { email: createTextField() } }));
+      r.writeHandler("user", z.object({}), async () => ({ isSuccess: true as const, data: null }), {
+        access: { openToAll: true },
+      });
+      r.hook(
+        "postDelete",
+        "user",
+        async () => {
+          throw new Error("postDelete-inTx-boom");
+        },
+        { phase: "inTransaction" },
+      );
+    });
+    const registry = createRegistry([feature]);
+    const pipeline = createLifecycleHooks(registry);
+    await expect(
+      pipeline.runPostDelete("test:write:user", deletectx, {}, "inTransaction"),
+    ).rejects.toThrow("postDelete-inTx-boom");
+  });
+});
+
+// --- Batch hooks ---
+
+describe("runPostSaveBatch / runPostDeleteBatch", () => {
+  test("no batch hooks registered → resolves without throwing", async () => {
+    const pipeline = createLifecycleHooks(makeRegistry());
+    await expect(pipeline.runPostSaveBatch([savectx], {})).resolves.toBeUndefined();
+    await expect(pipeline.runPostDeleteBatch([deletectx], {})).resolves.toBeUndefined();
+    // Should not throw — nothing registered.
+  });
+
+  test("runPostSaveBatch runs all system hooks concurrently with the batch payload", async () => {
+    const seen: (readonly SaveContext[])[] = [];
+    const systemHooks: SystemHooks = {
+      postSaveBatch: [
+        {
+          name: "a",
+          priority: 1000,
+          fn: async (results) => {
+            seen.push(results);
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(makeRegistry(), systemHooks);
+    await pipeline.runPostSaveBatch([savectx], {});
+    expect(seen).toEqual([[savectx]]);
+  });
+
+  test("runPostDeleteBatch runs all system hooks with the batch payload", async () => {
+    const seen: (readonly DeleteContext[])[] = [];
+    const systemHooks: SystemHooks = {
+      postDeleteBatch: [
+        {
+          name: "a",
+          priority: 1000,
+          fn: async (payloads) => {
+            seen.push(payloads);
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(makeRegistry(), systemHooks);
+    await pipeline.runPostDeleteBatch([deletectx], {});
+    expect(seen).toEqual([[deletectx]]);
+  });
+
+  test("one batch hook throwing doesn't stop the others (Promise.allSettled) — logged, never thrown", async () => {
+    const consoleSpy = spyOn(console, "error").mockImplementation(() => {});
+    const calls: string[] = [];
+    const systemHooks: SystemHooks = {
+      postSaveBatch: [
+        {
+          name: "failing",
+          priority: 1000,
+          fn: async () => {
+            throw new Error("batch-hook-boom");
+          },
+        },
+        {
+          name: "ok",
+          priority: 1001,
+          fn: async () => {
+            calls.push("ok-ran");
+          },
+        },
+      ],
+    };
+    const pipeline = createLifecycleHooks(makeRegistry(), systemHooks);
+    // Must not throw.
+    await pipeline.runPostSaveBatch([savectx], {});
+    expect(calls).toEqual(["ok-ran"]);
+    expect(consoleSpy).toHaveBeenCalled();
+    consoleSpy.mockRestore();
+  });
+});

package/src/pipeline/dispatch-shared.ts

@@ -484,8 +484,18 @@ export function buildHandlerContext(
     // When the feature-toggles or tier-engine feature isn't wired (no
     // effectiveFeatures callback), always returns true — apps without
     // tier-cuts treat all features on.
-    hasFeature: (featureName: string): boolean =>
-      effectiveFeatures ? effectiveFeatures(user.tenantId).has(featureName) : true,
+    //
+    // Falls back to the live trialGate when the sync set says the feature
+    // is off — the sync set never contains trial-tier features (time-
+    // derived, can't boot-cache), so without this a trial tenant checking
+    // a companion feature's toggle would silently read `false` even though
+    // the dispatch gate already lets trial-tier handlers run.
+    hasFeature: async (featureName: string): Promise<boolean> => {
+      if (!effectiveFeatures) return true;
+      if (effectiveFeatures(user.tenantId).has(featureName)) return true;
+      if (!effectiveFeatures.trialGate) return false;
+      return effectiveFeatures.trialGate(user.tenantId, featureName);
+    },
   };
 
   // Registry is always the dispatcher's registry — injecting it here lets
@@ -549,7 +559,7 @@ export function buildHandlerContext(
 export async function runHandlerInstrumented<T>(
   ctx: DispatchContext,
   type: string,
-  operation: "query" | "write",
+  operation: "query" | "write" | "stream",
   user: SessionUser,
   inner: () => Promise<T>,
 ): Promise<T> {
@@ -599,6 +609,44 @@ export async function runHandlerInstrumented<T>(
   }
 }
 
+// Generator-native counterpart to runHandlerInstrumented — a stream's
+// lifetime spans every `for await` pull the caller makes, so the span
+// can't be scoped via withSpan's single-callback shape. startSpan/end
+// bracket the whole yield* instead; metrics land in the same finally
+// path so success/failure/throw all hit one emit, like the Promise path.
+export async function* runStreamInstrumented<T>(
+  ctx: DispatchContext,
+  type: string,
+  user: SessionUser,
+  inner: () => AsyncGenerator<T>,
+): AsyncGenerator<T> {
+  const { tracer: dispatcherTracer, meter: dispatcherMeter, registry } = ctx;
+  const start = performance.now();
+  let success = true;
+  let errorClass: string | undefined;
+  const span = dispatcherTracer.startSpan("kumiko.dispatcher.handler", {
+    attributes: dispatcherSpanAttributes(type, "stream", user, registry.getHandlerFeature(type)),
+  });
+  try {
+    yield* inner();
+  } catch (error) {
+    success = false;
+    errorClass = error instanceof Error && error.name ? error.name : "UnknownError";
+    span.setStatus("error", errorClass);
+    throw error;
+  } finally {
+    span.end();
+    if (!success && errorClass) {
+      emitDispatcherError(dispatcherMeter, { handler: type, errorClass });
+    }
+    emitDispatcherHandler(
+      dispatcherMeter,
+      { handler: type, success },
+      (performance.now() - start) / 1000,
+    );
+  }
+}
+
 // Feature-toggle gate. Returns the error to fold into a WriteFailure in the
 // write path, or throws for the query path (where throws flow through the
 // same outer instrumentation wrapper as other dispatcher errors).

package/src/pipeline/dispatch-stream.ts

@@ -0,0 +1,74 @@
+import type { DbTx } from "../db/connection";
+import { hasAccess } from "../engine/access";
+import type { SessionUser } from "../engine/types";
+import { AccessDeniedError, NotFoundError, validationErrorFromZod } from "../errors";
+import { assertNoSecretLeak } from "../secrets";
+import {
+  buildHandlerContext,
+  type DispatchContext,
+  enforceRateLimit,
+  ensureFeatureEnabled,
+  runStreamInstrumented,
+} from "./dispatch-shared";
+
+// Standalone stream execution — used by the public dispatcher.stream().
+// Chunk-by-chunk analog of executeQuery: same gate order (feature → rate-
+// limit → access → validation → handler), but yields incrementally instead
+// of returning a single response. streamHandler never entity-maps (unlike
+// write/queryHandler — see feature-entity-handlers.ts), so there's no
+// field-access filter or postQuery-hook stage to run here.
+export async function* executeStream(
+  ctx: DispatchContext,
+  type: string,
+  payload: unknown,
+  user: SessionUser,
+  tx?: DbTx,
+): AsyncGenerator<unknown> {
+  yield* runStreamInstrumented(ctx, type, user, () =>
+    executeStreamInner(ctx, type, payload, user, tx),
+  );
+}
+
+async function* executeStreamInner(
+  ctx: DispatchContext,
+  type: string,
+  payload: unknown,
+  user: SessionUser,
+  tx?: DbTx,
+): AsyncGenerator<unknown> {
+  const { registry } = ctx;
+  const handler = registry.getStreamHandler(type);
+  if (!handler) throw new NotFoundError("handler", type);
+
+  await ensureFeatureEnabled(ctx, type, user.tenantId);
+
+  if (handler.rateLimit !== undefined) {
+    await enforceRateLimit(ctx, handler.rateLimit, type, user);
+  }
+
+  if (!hasAccess(user, handler.access)) {
+    throw new AccessDeniedError({
+      message: `access denied for ${type}`,
+      details: { handler: type },
+    });
+  }
+
+  const parsed = handler.schema.safeParse(payload);
+  if (!parsed.success) {
+    throw validationErrorFromZod(parsed.error);
+  }
+
+  const handlerContext = buildHandlerContext(ctx, type, user, tx);
+  const chunks = handler.handler({ type, payload: parsed.data, user }, handlerContext);
+
+  // Consumer-driven pull (for await) is the backpressure mechanism — the
+  // handler generator only advances once the caller reads the previous
+  // chunk, no explicit buffering/throttling needed on either side.
+  for await (const chunk of chunks) {
+    // Re-checked per chunk, not just at stream-start: a feature disabled
+    // mid-stream must cut an already-open stream, not just block new ones.
+    await ensureFeatureEnabled(ctx, type, user.tenantId);
+    assertNoSecretLeak(chunk);
+    yield chunk;
+  }
+}

package/src/pipeline/dispatcher-utils.ts

@@ -38,7 +38,7 @@ export function describeShape(result: unknown): string {
 
 export function dispatcherSpanAttributes(
   type: string,
-  operation: "query" | "write",
+  operation: "query" | "write" | "stream",
   user: SessionUser,
   feature: string | undefined,
 ) {

package/src/pipeline/dispatcher.ts

@@ -8,6 +8,7 @@ import { runBatch, unwrapSingle } from "./dispatch-batch";
 import { executeQuery } from "./dispatch-query";
 import type { BatchCommand, BatchResult, DispatchContext } from "./dispatch-shared";
 import { resolveAuthClaimsFn } from "./dispatch-shared";
+import { executeStream } from "./dispatch-stream";
 import { type HandlerType, resolveType } from "./dispatcher-utils";
 import type { IdempotencyGuard } from "./idempotency";
 import type { LifecycleHooks } from "./lifecycle-pipeline";
@@ -52,6 +53,10 @@ export type Dispatcher = {
     requestId?: string,
   ): Promise<WriteResult>;
   query(type: HandlerType, payload: unknown, user: SessionUser): Promise<unknown>;
+  // AsyncGenerator, not Promise — gates (feature/rate-limit/access/
+  // validation) fire on the consumer's first `.next()` pull, not on this
+  // call, since they live inside the underlying async function*.
+  stream(type: HandlerType, payload: unknown, user: SessionUser): AsyncGenerator<unknown>;
   command(type: HandlerType, payload: unknown, user: SessionUser): Promise<void>;
   // Atomic multi-command write: all commands run in a single DB transaction.
   // On any failure, the transaction rolls back and afterCommit hooks do NOT fire.
@@ -114,6 +119,8 @@ export function createDispatcher(
 
     query: (typeOrRef, payload, user) => executeQuery(ctx, resolveType(typeOrRef), payload, user),
 
+    stream: (typeOrRef, payload, user) => executeStream(ctx, resolveType(typeOrRef), payload, user),
+
     async command(typeOrRef, payload, user) {
       const type = resolveType(typeOrRef);
       const batchResult = await runBatch(ctx, [{ type, payload }], user);

package/src/pipeline/entity-cache.ts

@@ -1,3 +1,4 @@
+import type { EntityCache } from "@cosmicdrift/kumiko-types/entity-cache";
 import type Redis from "ioredis";
 import type { EntityId, TenantId } from "../engine/types/identifiers";
 import { RedisKeys } from "./redis-keys";
@@ -23,39 +24,7 @@ function parseCached(raw: string): Record<string, unknown> | null {
   }
 }
 
-export type EntityCache = {
-  /** Get a single cached entity. Returns null on miss. */
-  get(
-    tenantId: TenantId,
-    entityName: string,
-    id: EntityId,
-  ): Promise<Record<string, unknown> | null>;
-
-  /** Get multiple cached entities. Returns a Map of id → data (misses are absent). */
-  mget(
-    tenantId: TenantId,
-    entityName: string,
-    ids: readonly EntityId[],
-  ): Promise<Map<EntityId, Record<string, unknown>>>;
-
-  /** Cache a single entity. */
-  set(
-    tenantId: TenantId,
-    entityName: string,
-    id: EntityId,
-    data: Record<string, unknown>,
-  ): Promise<void>;
-
-  /** Cache multiple entities at once. */
-  mset(
-    tenantId: TenantId,
-    entityName: string,
-    entries: ReadonlyArray<{ id: EntityId; data: Record<string, unknown> }>,
-  ): Promise<void>;
-
-  /** Invalidate a single cached entity. */
-  del(tenantId: TenantId, entityName: string, id: EntityId): Promise<void>;
-};
+export type { EntityCache } from "@cosmicdrift/kumiko-types/entity-cache";
 
 export type EntityCacheOptions = {
   ttlSeconds?: number;

package/src/pipeline/event-consumer-state.ts

@@ -10,7 +10,8 @@ import {
   sql,
   text,
 } from "../db/dialect";
-import { tableExists } from "../db/schema-inspection";
+import { alterTableAddColumn } from "../db/queries/test-stack";
+import { columnNamesOf, tableExists } from "../db/schema-inspection";
 import { unsafePushTables } from "../stack";
 
 // Reserved sentinel used in the instance_id column for consumers whose
@@ -72,6 +73,14 @@ export const eventConsumerStateTable = pgTable(
       .default(sql`0`),
     status: text("status").notNull().default("idle"),
     attempts: integer("attempts").notNull().default(0),
+    // Counts automatic dead→idle revivals since the last delivery that
+    // advanced the cursor (event-dispatcher.ts's cooldown re-arm, see
+    // acquireConsumerState). A poison event never advances the cursor, so
+    // this climbs to maxRearmCount and then stays dead permanently. A
+    // successful delivery resets it to 0 (proof the consumer isn't
+    // poisoned), as does a manual restartConsumer()/enableConsumer()/
+    // skipPoisonEvent() — an operator vouching the consumer is healthy.
+    rearmCount: integer("rearm_count").notNull().default(0),
     lastError: text("last_error"),
     updatedAt: instant("updated_at", { precision: 3 }).notNull().default(sql`now()`),
   },
@@ -99,7 +108,23 @@ export type ConsumerStatus = (typeof ConsumerStatuses)[keyof typeof ConsumerStat
 //
 // guard:dup-ok — intentionale Parallele zu createProjectionStateTable; symmetrische State-Tabellen by design
 export async function createEventConsumerStateTable(db: DbConnection): Promise<void> {
-  // skip: table already exists — bootstrap is called from multiple paths
-  if (await tableExists(db, "public.kumiko_event_consumers")) return;
+  // skip: table already exists — bootstrap is called from multiple paths.
+  // Still check for columns added after the table's first deploy (e.g.
+  // rearm_count) so an older DB catches up without a dedicated migration.
+  if (await tableExists(db, "public.kumiko_event_consumers")) {
+    const cols = await columnNamesOf(db, "kumiko_event_consumers");
+    if (!cols.has("rearm_count")) {
+      await alterTableAddColumn(
+        db,
+        "kumiko_event_consumers",
+        "rearm_count",
+        "integer",
+        " DEFAULT 0",
+        " NOT NULL",
+      );
+    }
+    // skip: table (+ any missing column) is already up to date
+    return;
+  }
   await unsafePushTables(db, { kumikoEventConsumers: eventConsumerStateTable });
 }

package/src/pipeline/event-dispatcher-admin.ts

@@ -34,6 +34,7 @@ function normalizeConsumerState(row: ConsumerStateRowShape): ConsumerRecoverySta
     status: row.status,
     lastProcessedEventId: row.lastProcessedEventId,
     attempts: row.attempts,
+    rearmCount: row.rearmCount,
     lastError: row.lastError,
     updatedAt: row.updatedAt,
   };
@@ -45,6 +46,7 @@ export type ConsumerRecoveryState = {
   readonly status: string;
   readonly lastProcessedEventId: bigint;
   readonly attempts: number;
+  readonly rearmCount: number;
   readonly lastError: string | null;
   readonly updatedAt: Temporal.Instant;
 };
@@ -170,6 +172,7 @@ export async function getConsumerState(
   readonly status: string;
   readonly lastProcessedEventId: bigint;
   readonly attempts: number;
+  readonly rearmCount: number;
   readonly lastError: string | null;
   readonly updatedAt: Temporal.Instant;
 } | null> {
@@ -184,6 +187,7 @@ export async function getConsumerState(
     status: row.status,
     lastProcessedEventId: row.lastProcessedEventId,
     attempts: row.attempts,
+    rearmCount: row.rearmCount,
     lastError: row.lastError,
     updatedAt: row.updatedAt,
   };

package/src/pipeline/event-dispatcher-delivery.ts

@@ -3,6 +3,7 @@ import type { DbConnection, DbTx } from "../db/connection";
 import {
   insertConsumerIfAbsent,
   markConsumerProcessing,
+  rearmDeadConsumer,
   selectConsumerForUpdateSkipLocked,
   updateConsumerDeliveryOutcome,
 } from "../db/queries/event-consumer";
@@ -38,12 +39,13 @@ export type ConsumerStateRowShape = {
   readonly lastProcessedEventId: bigint;
   readonly status: string;
   readonly attempts: number;
+  readonly rearmCount: number;
   readonly lastError: string | null;
   readonly updatedAt: Temporal.Instant;
 };
 export type ConsumerStateRow = ConsumerStateRowShape;
 
-type StoredEventRow = {
+export type StoredEventRow = {
   readonly id: bigint;
   readonly aggregateId: string;
   readonly aggregateType: string;
@@ -80,6 +82,8 @@ export async function acquireConsumerState(
   tx: DbTx,
   name: string,
   instanceId: string,
+  rearmCooldownMs: number,
+  maxRearmCount: number,
 ): Promise<AcquireOutcome> {
   const rawState = await selectConsumerForUpdateSkipLocked(tx, name, instanceId);
 
@@ -100,7 +104,28 @@ export async function acquireConsumerState(
   }
 
   if (state.status === ConsumerStatuses.disabled) return { state: null, skip: "disabled" };
-  if (state.status === ConsumerStatuses.dead) return { state: null, skip: "dead" };
+  if (state.status === ConsumerStatuses.dead) {
+    // Bounded auto-revival: a transient failure (e.g. a Meilisearch blip)
+    // shouldn't need an operator to notice and run restartConsumer() once
+    // the cause is long gone. Cooldown since the last write (the death or
+    // a prior re-arm) gates the retry; maxRearmCount stops a poison event
+    // from looping forever (re-arm → same event fails → dead → re-arm →
+    // ...) — after the cap it stays dead until a human intervenes.
+    const cooldownDeadline = Temporal.Now.instant().subtract({ milliseconds: rearmCooldownMs });
+    const cooldownElapsed = Temporal.Instant.compare(state.updatedAt, cooldownDeadline) <= 0;
+    if (cooldownElapsed && state.rearmCount < maxRearmCount) {
+      const rearmed = await rearmDeadConsumer(tx, name, instanceId);
+      const rearmedState =
+        rearmed &&
+        (coerceRow(rearmed, extractTableInfo(eventConsumerStateTable)) as ConsumerStateRow);
+      if (rearmedState) return { state: rearmedState, skip: null };
+    }
+    // ponytail: no log/metric fires when the rearm budget is exhausted here
+    // (the exact "braucht manuellen Eingriff" moment) — queryable via
+    // getConsumerState but silent otherwise. Add an emitDispatcherError-style
+    // signal if ops needs a push instead of a dead+lag poll.
+    return { state: null, skip: "dead" };
+  }
   return { state, skip: null };
 }
 
@@ -183,6 +208,7 @@ export async function deliverEvents(
   let attempts = state.attempts;
   let lastError: string | null = state.lastError ?? null;
   let deadLettered = false;
+  const effectiveMaxAttempts = consumer.errorPolicy?.maxAttempts ?? maxAttempts;
   let processed = 0;
   let failed = 0;
 
@@ -231,7 +257,7 @@ export async function deliverEvents(
       attempts += 1;
       lastError = errMessage;
       failed += 1;
-      if (attempts >= maxAttempts) deadLettered = true;
+      if (attempts >= effectiveMaxAttempts) deadLettered = true;
       break;
     }
   }

package/src/pipeline/event-dispatcher.ts

@@ -66,6 +66,11 @@ export type EventConsumerHandler = (event: StoredEvent, ctx: AppContext) => Prom
 // the EventConsumer (see api/server.ts MSP wiring).
 export type EventConsumerErrorPolicy = {
   readonly skipApplyErrors?: boolean;
+  // Per-consumer override of EventDispatcherOptions.maxAttempts. A consumer
+  // that depends on infra which may still be provisioning at boot (search
+  // adapter, external APIs) needs more retry headroom than the dispatcher-
+  // wide default before it gets dead-lettered.
+  readonly maxAttempts?: number;
 };
 
 export type EventConsumer = {
@@ -129,6 +134,17 @@ export type EventDispatcherOptions = {
   readonly batchSize?: number;
   readonly pollIntervalMs?: number;
   readonly maxAttempts?: number;
+  // Bounded auto-revival of a "dead" consumer. A dead consumer whose last
+  // write is older than rearmCooldownMs gets reset to idle and retried.
+  // rearmCount tracks re-arms since the last delivery that actually
+  // advanced the cursor — a poison event never advances it, so it climbs
+  // 1→maxRearmCount and then stays dead permanently; a transient failure
+  // that later delivers successfully resets it back to 0, so an unrelated
+  // future outage gets its own fresh budget. restartConsumer()/
+  // enableConsumer()/skipPoisonEvent() also reset it (an operator vouching
+  // the consumer is healthy again).
+  readonly rearmCooldownMs?: number;
+  readonly maxRearmCount?: number;
   readonly tracer?: Tracer;
   readonly meter?: Meter;
   // Identifies THIS dispatcher process in the consumer-state table. Used as
@@ -150,6 +166,8 @@ export type EventDispatcherOptions = {
 const DEFAULT_BATCH_SIZE = 200;
 const DEFAULT_POLL_MS = 100;
 const DEFAULT_MAX_ATTEMPTS = 10;
+const DEFAULT_REARM_COOLDOWN_MS = 5 * 60_000;
+const DEFAULT_MAX_REARM_COUNT = 3;
 
 export function createEventDispatcher(options: EventDispatcherOptions): EventDispatcher {
   const {
@@ -159,6 +177,8 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
     batchSize = DEFAULT_BATCH_SIZE,
     pollIntervalMs = DEFAULT_POLL_MS,
     maxAttempts = DEFAULT_MAX_ATTEMPTS,
+    rearmCooldownMs = DEFAULT_REARM_COOLDOWN_MS,
+    maxRearmCount = DEFAULT_MAX_REARM_COUNT,
   } = options;
 
   // Fail-fast on misconfigured per-instance wiring. Catching this at
@@ -273,7 +293,13 @@ export function createEventDispatcher(options: EventDispatcherOptions): EventDis
 
     try {
       await db.begin(async (tx: DbTx) => {
-        const acquired = await acquireConsumerState(tx, consumer.name, instanceId);
+        const acquired = await acquireConsumerState(
+          tx,
+          consumer.name,
+          instanceId,
+          rearmCooldownMs,
+          maxRearmCount,
+        );
         // skip: another instance holds the lock, or the consumer is
         // disabled/dead. Nothing to deliver this pass.
         if (acquired.skip !== null) {