@qlever-llc/trellis 0.10.22 → 0.11.0-rc.1

package/src/trellis.ts

@@ -68,6 +68,7 @@ import {
   AuthError,
   BUILTIN_RPC_ERRORS,
   getBuiltinRpcError,
+  SchemaValidationError,
   type StoreError,
   TransferError,
   TransportError,
@@ -248,14 +249,14 @@ function classifyRequestTransportFailure(args: {
 function encodeRuntimeSchema(
   schema: unknown,
   data: unknown,
-): Result<string, ValidationError | UnexpectedError> {
+): Result<string, SchemaValidationError | ValidationError | UnexpectedError> {
   return encodeSchema(schema as never, data);
 }
 
 function parseRuntimeSchema(
   schema: unknown,
   data: JsonValue,
-): Result<unknown, ValidationError | UnexpectedError> {
+): Result<unknown, SchemaValidationError | ValidationError | UnexpectedError> {
   return parseUnknownSchema(
     schema as Parameters<typeof parseUnknownSchema>[0],
     data,
@@ -479,24 +480,79 @@ type RequestErrorOf<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> =
 type HandlerErrorOf<TA extends AnyTrellisAPI, M extends MethodsOf<TA>> =
   | MethodDeclaredErrorOf<TA, M>
   | TrellisErrorInstance;
-type EventOf<TA extends AnyTrellisAPI, E extends EventsOf<TA>> =
+
+type OperationDescriptorOf<
+  TA extends AnyTrellisAPI,
+  O extends OperationsOf<TA>,
+> = TA["operations"][O] extends {
+  input: infer TInput;
+  progress?: infer TProgress;
+  output?: infer TOutput;
+  errors?: infer TErrors;
+  runtimeErrors?: infer TRuntimeErrors;
+  declaredErrorTypes?: infer TDeclaredErrorTypes;
+} ? {
+    input: TInput;
+    progress?: TProgress;
+    output?: TOutput;
+    errors?: TErrors;
+    runtimeErrors?: TRuntimeErrors;
+    declaredErrorTypes?: TDeclaredErrorTypes;
+  } & TA["operations"][O]
+  : never;
+
+type OperationDeclaredErrorOf<
+  TA extends AnyTrellisAPI,
+  O extends OperationsOf<TA>,
+> = OperationDescriptorOf<TA, O> extends {
+  errors?: infer TErrors;
+  runtimeErrors?: infer TRuntimeErrors;
+} ? DeclaredBuiltinErrorOf<TErrors> | DeclaredRuntimeErrorOf<TRuntimeErrors>
+  : never;
+
+export type OperationHandlerErrorOf<
+  TA extends AnyTrellisAPI,
+  O extends OperationsOf<TA>,
+> = OperationDeclaredErrorOf<TA, O> | TrellisErrorInstance;
+type EventMessageOf<TA extends AnyTrellisAPI, E extends EventsOf<TA>> =
   TA["events"][E] extends EventDesc<infer TEvent> ? InferSchemaType<TEvent>
     : never;
+type EventOf<TA extends AnyTrellisAPI, E extends EventsOf<TA>> = EventMessageOf<
+  TA,
+  E
+>;
 type EventDescriptorOf<TA extends AnyTrellisAPI, E extends EventsOf<TA>> =
   TA["events"][E] extends EventDesc<infer TEvent>
     ? EventDesc<TEvent> & TA["events"][E]
     : never;
-type EventPayloadOf<TA extends AnyTrellisAPI, E extends EventsOf<TA>> = Omit<
-  EventOf<TA, E>,
-  "header"
->;
+type EventPayloadOf<TA extends AnyTrellisAPI, E extends EventsOf<TA>> =
+  & EventOf<TA, E>
+  & Record<string, unknown>;
+/** Runtime metadata assigned to every Trellis event message. */
+export type TrellisEventHeader = Readonly<{
+  /** Stable event id used for event identity and JetStream de-duplication. */
+  id: string;
+  /** Event creation time in ISO-8601 format. */
+  time: string;
+}>;
+/** Event body plus Trellis runtime event metadata. */
+export type TrellisEventMessage<
+  TBody extends Record<string, unknown> = Record<string, unknown>,
+> = Readonly<{
+  /** User-authored contract event body. */
+  body: Readonly<TBody>;
+  /** Runtime metadata assigned by Trellis. */
+  header: TrellisEventHeader;
+}>;
 /** A fully encoded event whose subject, payload, and headers are stable. */
 export type PreparedTrellisEvent<
   TPayload extends Record<string, unknown> = Record<string, unknown>,
 > = Readonly<{
   event: string;
   subject: string;
-  payload: Readonly<TPayload & { header: { id: string; time: string } }>;
+  /** Runtime event metadata assigned when the event was prepared. */
+  header: TrellisEventHeader;
+  payload: Readonly<TPayload>;
   encodedPayload: string;
   headers: Readonly<Record<string, string>>;
 }>;
@@ -521,17 +577,21 @@ export type OperationInputOf<
 export type OperationProgressOf<
   TA extends AnyTrellisAPI,
   O extends OperationsOf<TA>,
-> = TA["operations"][O] extends { progress: infer TProgress }
+> = TA["operations"][O] extends { progress?: infer TProgress }
   ? TProgress extends undefined ? unknown
   : InferSchemaType<NonNullable<TProgress>>
   : unknown;
 export type OperationOutputOf<
   TA extends AnyTrellisAPI,
   O extends OperationsOf<TA>,
-> = TA["operations"][O] extends { output: infer TOutput }
+> = TA["operations"][O] extends { output?: infer TOutput }
   ? TOutput extends undefined ? unknown : InferSchemaType<NonNullable<TOutput>>
   : unknown;
-export type OperationRuntimeHandle<TProgress = unknown, TOutput = unknown> = {
+export type OperationRuntimeHandle<
+  TProgress,
+  TOutput,
+  TError extends BaseError,
+> = {
   id: string;
   started(): AsyncResult<RuntimeOperationSnapshot, BaseError>;
   progress(
@@ -541,7 +601,7 @@ export type OperationRuntimeHandle<TProgress = unknown, TOutput = unknown> = {
     value: TOutput,
   ): AsyncResult<RuntimeOperationSnapshot, BaseError>;
   fail(
-    error: BaseError,
+    error: TError,
   ): AsyncResult<RuntimeOperationSnapshot, BaseError>;
   cancel(): AsyncResult<RuntimeOperationSnapshot, BaseError>;
   attach(
@@ -567,8 +627,12 @@ export function isOperationDeferred(
   return !!value && typeof value === "object" &&
     "kind" in value && value.kind === "deferred";
 }
-export type AcceptedOperation<TProgress = unknown, TOutput = unknown> =
-  & OperationRuntimeHandle<TProgress, TOutput>
+export type AcceptedOperation<
+  TProgress,
+  TOutput,
+  TError extends BaseError,
+> =
+  & OperationRuntimeHandle<TProgress, TOutput, TError>
   & {
     ref: OperationRefData;
     snapshot: RuntimeOperationSnapshot & {
@@ -679,33 +743,44 @@ export type StateFacade<TState extends RuntimeStateStores> = {
 };
 export type OperationHandlerContext<
   TInput,
-  TProgress = unknown,
-  TOutput = unknown,
-  TTransfer = undefined,
+  TProgress,
+  TOutput,
+  TTransfer,
+  TError extends BaseError,
 > = {
   input: TInput;
-  op: OperationRuntimeHandle<TProgress, TOutput>;
+  op: OperationRuntimeHandle<TProgress, TOutput, TError>;
   caller: SessionCaller;
 } & (TTransfer extends undefined ? {} : { transfer: TTransfer });
 export type OperationRegistration<
   TInput,
-  TProgress = unknown,
-  TOutput = unknown,
-  TTransfer = undefined,
+  TProgress,
+  TOutput,
+  TTransfer,
+  TError extends BaseError,
 > = {
   accept(args: {
     sessionKey: string;
-  }): AsyncResult<AcceptedOperation<TProgress, TOutput>, UnexpectedError>;
+  }): AsyncResult<
+    AcceptedOperation<TProgress, TOutput, TError>,
+    UnexpectedError
+  >;
   /**
    * Loads an existing operation by id and returns a service-side control handle.
    * The operation must belong to this service and registration name.
    */
   control(
     operationId: string,
-  ): AsyncResult<OperationRuntimeHandle<TProgress, TOutput>, BaseError>;
+  ): AsyncResult<OperationRuntimeHandle<TProgress, TOutput, TError>, BaseError>;
   handle(
     handler: (
-      context: OperationHandlerContext<TInput, TProgress, TOutput, TTransfer>,
+      context: OperationHandlerContext<
+        TInput,
+        TProgress,
+        TOutput,
+        TTransfer,
+        TError
+      >,
     ) => unknown | Promise<unknown>,
   ): Promise<void>;
 };
@@ -724,7 +799,8 @@ export type OperationSurface<
     OperationInputOf<TA, O>,
     OperationProgressOf<TA, O>,
     OperationOutputOf<TA, O>,
-    OperationTransferContextOf<TA, O>
+    OperationTransferContextOf<TA, O>,
+    OperationHandlerErrorOf<TA, O>
   >
   : OperationInvoker<TA["operations"][O] & RuntimeOperationDesc>;
 
@@ -1088,26 +1164,18 @@ export type EventListenerContext = {
 };
 
 function createEventListenerContext(args: {
-  payload: unknown;
   subject: string;
   mode: "durable" | "ephemeral";
   group?: string;
   message: object;
 }): EventListenerContext {
-  const header = typeof args.payload === "object" && args.payload !== null
-    ? Reflect.get(args.payload, "header")
-    : undefined;
-  const id = typeof header === "object" && header !== null
-    ? Reflect.get(header, "id")
-    : undefined;
-  const time = typeof header === "object" && header !== null
-    ? Reflect.get(header, "time")
-    : undefined;
+  const messageId = readMessageHeader(args.message, "Nats-Msg-Id");
+  const messageTime = readMessageHeader(args.message, "Trellis-Event-Time");
   const sequence = Reflect.get(args.message, "seq");
 
   return {
-    id: typeof id === "string" ? id : "",
-    time: new Date(typeof time === "string" ? time : 0),
+    id: messageId ?? "",
+    time: new Date(messageTime ?? 0),
     subject: args.subject,
     mode: args.mode,
     ...(args.group ? { group: args.group } : {}),
@@ -1115,6 +1183,15 @@ function createEventListenerContext(args: {
   };
 }
 
+function readMessageHeader(message: object, key: string): string | undefined {
+  const headers = Reflect.get(message, "headers");
+  if (typeof headers !== "object" || headers === null) return undefined;
+  const get = Reflect.get(headers, "get");
+  if (typeof get !== "function") return undefined;
+  const value = get.call(headers, key);
+  return typeof value === "string" ? value : undefined;
+}
+
 type RuntimeEventConsumers = {
   metadata?: RuntimeEventConsumerGroups;
   bindings?: Record<string, EventConsumerResourceBinding>;
@@ -1129,6 +1206,12 @@ type RuntimeEventConsumerGroups = Readonly<
   Record<string, RuntimeEventConsumerGroup>
 >;
 
+/** @internal Hook used by Trellis-owned integration tests for durable event interleavings. */
+export type TrellisDurableEventConsumerBeforeReadinessCheckHook = (args: {
+  group: string;
+  subject: string;
+}) => void | Promise<void>;
+
 function eventConsumerGroupEvents(group: RuntimeEventConsumerGroup): string[] {
   const events = new Set<string>();
   for (const groupEvents of Object.values(group.uses ?? {})) {
@@ -1138,11 +1221,29 @@ function eventConsumerGroupEvents(group: RuntimeEventConsumerGroup): string[] {
   return [...events].sort();
 }
 
+function isConsumerNotFoundError(error: unknown): boolean {
+  return error instanceof Error && (
+    error.name === "ConsumerNotFoundError" ||
+    error.message.includes("consumer not found")
+  );
+}
+
 type TrellisInternalOpts<TA extends AnyTrellisAPI> = TrellisOpts<TA> & {
   eventConsumers?: RuntimeEventConsumers;
+  durableEventConsumerBeforeReadinessCheck?:
+    TrellisDurableEventConsumerBeforeReadinessCheckHook;
 };
 
-let pendingInternalEventConsumers: RuntimeEventConsumers | undefined;
+const internalEventConsumers = Symbol("trellis.internal.eventConsumers");
+const internalDurableEventConsumerBeforeReadinessCheck = Symbol(
+  "trellis.internal.durableEventConsumerBeforeReadinessCheck",
+);
+
+type InternalizedTrellisOpts<TA extends AnyTrellisAPI> = TrellisOpts<TA> & {
+  [internalEventConsumers]?: RuntimeEventConsumers;
+  [internalDurableEventConsumerBeforeReadinessCheck]?:
+    TrellisDurableEventConsumerBeforeReadinessCheckHook;
+};
 
 /**
  * Creates a Trellis runtime with bootstrap-resolved bindings.
@@ -1159,13 +1260,18 @@ export function createTrellisInternal<
   auth: TrellisAuth,
   opts?: TrellisInternalOpts<TA>,
 ): Trellis<TA, TMode, TState> {
-  const { eventConsumers, ...publicOpts } = opts ?? {};
-  pendingInternalEventConsumers = eventConsumers;
-  try {
-    return new Trellis<TA, TMode, TState>(name, nats, auth, publicOpts);
-  } finally {
-    pendingInternalEventConsumers = undefined;
-  }
+  const {
+    durableEventConsumerBeforeReadinessCheck,
+    eventConsumers,
+    ...publicOpts
+  } = opts ?? {};
+  const internalOpts: InternalizedTrellisOpts<TA> = {
+    ...publicOpts,
+    [internalEventConsumers]: eventConsumers,
+    [internalDurableEventConsumerBeforeReadinessCheck]:
+      durableEventConsumerBeforeReadinessCheck,
+  };
+  return new Trellis<TA, TMode, TState>(name, nats, auth, internalOpts);
 }
 
 type DurableEventRegistration<TA extends AnyTrellisAPI> = {
@@ -1199,7 +1305,12 @@ export type FeedHandlerContext<TInput, TEvent> = {
   input: TInput;
   caller: SessionCaller;
   signal: AbortSignal;
-  emit(event: TEvent): AsyncResult<void, ValidationError | UnexpectedError>;
+  emit(
+    event: TEvent,
+  ): AsyncResult<
+    void,
+    SchemaValidationError | ValidationError | UnexpectedError
+  >;
 };
 
 export type FeedRegistration<TInput, TEvent> = {
@@ -1357,6 +1468,8 @@ type EventCallback<TMessage> = {
 export type RpcHandlerContext = {
   caller: SessionCaller;
   sessionKey: string;
+  requestId?: string;
+  traceId?: string;
 };
 
 export type HandlerTrellis<
@@ -1383,6 +1496,8 @@ export type HandlerTrellis<
   publishPrepared(
     event: PreparedTrellisEvent,
   ): AsyncResult<void, UnexpectedError>;
+  /** Stops durable event listener loops owned by this handler runtime. */
+  stopEventListeners(): void;
 };
 
 function surfaceGroupName(key: string): string {
@@ -1528,30 +1643,18 @@ export type ConnectedTrellisClient<TContract> = Simplify<
   >
 >;
 
-export type HandlerArgs<
+export type HandlerFn<
   TMountApi extends AnyTrellisAPI,
   M extends MethodsOf<TMountApi>,
   TOutboundApi extends AnyTrellisAPI = TMountApi,
   TTrellis = HandlerTrellis<TOutboundApi>,
-> = {
+> = (args: {
   input: MethodInputOf<TMountApi, M>;
   context: RpcHandlerContext;
   client: TTrellis;
-};
-
-export type HandlerFn<
-  TMountApi extends AnyTrellisAPI,
-  M extends MethodsOf<TMountApi>,
-  TOutboundApi extends AnyTrellisAPI = TMountApi,
-  TTrellis = HandlerTrellis<TOutboundApi>,
-> = (args: HandlerArgs<TMountApi, M, TOutboundApi, TTrellis>) => MaybePromise<
+}) => MaybePromise<
   Result<MethodOutputOf<TMountApi, M>, HandlerErrorOf<TMountApi, M>>
 >;
-export type RpcHandlerFn<
-  TA extends AnyTrellisAPI,
-  M extends RpcMethodNameOf<TA>,
-> = HandlerFn<TA, M, TA>;
-export type TrellisFor<TContract> = HandlerTrellisForContract<TContract>;
 
 const DEFAULT_STATE_LIST_LIMIT = 100;
 
@@ -1624,7 +1727,25 @@ function validateStateValue(
   schema: unknown,
   value: JsonValue,
 ): Result<unknown, ValidationError | UnexpectedError> {
-  return parseRuntimeSchema(schema, value);
+  const result = parseRuntimeSchema(schema, value);
+  // State validation is an internal path; collapse SchemaValidationError
+  // into ValidationError to keep internal error types narrow.
+  if (result.isOk()) {
+    return result as Result<unknown, ValidationError | UnexpectedError>;
+  }
+  const resultError = result.error;
+  if (resultError instanceof SchemaValidationError) {
+    return Result.err(
+      new ValidationError({
+        errors: resultError.issues.map((i) => ({
+          path: i.path,
+          message: i.message,
+        })),
+        cause: resultError.cause,
+      }),
+    ) as Result<unknown, ValidationError | UnexpectedError>;
+  }
+  return result as Result<unknown, ValidationError | UnexpectedError>;
 }
 
 function validateStateGetResult<TStore extends RuntimeStateStoreShape>(
@@ -1821,22 +1942,6 @@ function validateStateListResult(
   return Result.ok({ ...result, entries });
 }
 
-export type RpcArgs<
-  TContract,
-  M extends RpcMethodNameOf<OwnedApiFor<TContract>>,
-> = HandlerArgs<
-  OwnedApiFor<TContract>,
-  M,
-  TrellisApiFor<TContract>,
-  HandlerTrellisForContract<TContract>
->;
-export type RpcResult<
-  TContract,
-  M extends RpcMethodNameOf<OwnedApiFor<TContract>>,
-> = Result<
-  RpcOutputOf<OwnedApiFor<TContract>, M>,
-  RpcHandlerErrorOf<OwnedApiFor<TContract>, M>
->;
 export type RpcRequestErrorOf<
   TA extends AnyTrellisAPI,
   M extends RpcMethodNameOf<TA>,
@@ -1854,13 +1959,6 @@ export type EventPayload<
   TContract,
   E extends EventName<TContract>,
 > = EventPayloadOf<OwnedApiFor<TContract>, E>;
-export type EventHandler<
-  TContract,
-  E extends EventName<TContract>,
-> = (
-  event: EventType<TContract, E>,
-  context: EventListenerContext,
-) => MaybeAsync<void, BaseError>;
 
 type DeepRecord<T> = {
   [k: string]: T | DeepRecord<T>;
@@ -2054,7 +2152,10 @@ export class Trellis<
   #onSessionNotFound?: () => MaybePromise<void>;
   #operationStore?: Promise<TypedKV<typeof DurableOperationRecordSchema>>;
   #eventConsumers: RuntimeEventConsumers;
+  #durableEventConsumerBeforeReadinessCheck?:
+    TrellisDurableEventConsumerBeforeReadinessCheckHook;
   #durableEventLoops = new Map<string, DurableEventConsumerLoop<TA>>();
+  #durableEventListenersStopped = false;
 
   constructor(
     name: string, // Must be unique for a service
@@ -2062,6 +2163,7 @@ export class Trellis<
     auth: TrellisAuth,
     opts?: TrellisOpts<TA>,
   ) {
+    const internalOpts = opts as InternalizedTrellisOpts<TA> | undefined;
     const api = opts?.api;
 
     this.name = name;
@@ -2080,7 +2182,9 @@ export class Trellis<
     this.#noResponderRetryMs = opts?.noResponderRetry?.baseDelayMs ??
       DEFAULT_NO_RESPONDER_RETRY_MS;
     this.#onSessionNotFound = opts?.onSessionNotFound;
-    this.#eventConsumers = pendingInternalEventConsumers ?? {};
+    this.#eventConsumers = internalOpts?.[internalEventConsumers] ?? {};
+    this.#durableEventConsumerBeforeReadinessCheck = internalOpts
+      ?.[internalDurableEventConsumerBeforeReadinessCheck];
     this.connection = opts?.connection ??
       new TrellisConnection({ kind: "client" });
 
@@ -2323,6 +2427,7 @@ export class Trellis<
       prepare: (event, data) => this.prepare(event, data),
       publish: (event, data) => this.publish(event, data),
       publishPrepared: (event) => this.publishPrepared(event),
+      stopEventListeners: () => this.stopEventListeners(),
     };
   }
 
@@ -3439,6 +3544,10 @@ export class Trellis<
 
         let caller: SessionCaller;
         const callerSessionKey = msg.headers?.get("session-key") ?? "";
+        const handlerRequestIdFromHeader = msg.headers?.get("request-id") ?? "";
+        const handlerTraceIdFromHeader = traceIdFromTraceparent(
+          msg.headers?.get("traceparent"),
+        );
 
         const authRequired = ctx.authRequired ?? true;
         if (!authRequired) {
@@ -3709,6 +3818,8 @@ export class Trellis<
               context: {
                 caller,
                 sessionKey: callerSessionKey,
+                requestId: handlerRequestIdFromHeader || undefined,
+                traceId: handlerTraceIdFromHeader || undefined,
               },
               client: handlerTrellis,
             }),
@@ -3954,10 +4065,7 @@ export class Trellis<
         id: ulid(),
         time: new Date().toISOString(),
       };
-      const payload = Object.freeze({
-        ...data,
-        header: Object.freeze(header),
-      });
+      const payload = Object.freeze({ ...data });
       const msg = encodeSchema(ctx.event, payload).take();
       if (isErr(msg)) {
         logger.error({ err: msg.error }, "Failed to encode event.");
@@ -3973,6 +4081,7 @@ export class Trellis<
 
       const headers = natsHeaders();
       headers.set("Nats-Msg-Id", header.id);
+      headers.set("Trellis-Event-Time", header.time);
       injectTraceContext(createNatsHeaderCarrier(headers));
 
       const headerRecord: Record<string, string> = {};
@@ -3983,6 +4092,7 @@ export class Trellis<
       return ok(Object.freeze({
         event: event.toString(),
         subject,
+        header: Object.freeze(header),
         payload,
         encodedPayload: msg,
         headers: Object.freeze(headerRecord),
@@ -4074,7 +4184,7 @@ export class Trellis<
         if (isErr(subject)) return subject;
 
         if (opts?.mode === "ephemeral") {
-          return this.#startEphemeralEvent(
+          return await this.#startEphemeralEvent(
             eventName,
             ctx,
             subject,
@@ -4118,20 +4228,36 @@ export class Trellis<
     })());
   }
 
-  #startEphemeralEvent(
+  async #startEphemeralEvent(
     event: EventsOf<TA>,
     ctx: EventDescriptorOf<TA, EventsOf<TA>>,
     subject: string,
     fn: EventCallback<EventOf<TA, EventsOf<TA>>>,
     signal?: AbortSignal,
-  ): Result<void, ValidationError | UnexpectedError> {
-    const sub = this.nats.subscribe(subject);
-    if (signal) {
-      if (signal.aborted) {
+  ): Promise<Result<void, ValidationError | UnexpectedError>> {
+    let sub: ReturnType<NatsConnection["subscribe"]> | undefined;
+    try {
+      sub = this.nats.subscribe(subject);
+      if (signal) {
+        if (signal.aborted) {
+          sub.unsubscribe();
+          return ok(undefined);
+        }
+        signal.addEventListener("abort", () => sub?.unsubscribe(), {
+          once: true,
+        });
+      }
+      await this.nats.flush();
+    } catch (cause) {
+      if (sub) {
         sub.unsubscribe();
-        return ok(undefined);
       }
-      signal.addEventListener("abort", () => sub.unsubscribe(), { once: true });
+      return err(
+        new UnexpectedError({
+          cause,
+          context: { event: String(event), subject },
+        }),
+      );
     }
 
     const task = AsyncResult.try(async () => {
@@ -4199,7 +4325,6 @@ export class Trellis<
       const result = await Promise.resolve(args.fn(
         args.payload as EventOf<TA, EventsOf<TA>>,
         createEventListenerContext({
-          payload: args.payload,
           subject: args.message.subject,
           mode: args.mode,
           ...(args.group ? { group: args.group } : {}),
@@ -4301,7 +4426,7 @@ export class Trellis<
     fn: EventCallback<EventOf<TA, EventsOf<TA>>>;
     signal?: AbortSignal;
   }): void {
-    if (args.signal?.aborted) return;
+    if (args.signal?.aborted || this.#durableEventListenersStopped) return;
 
     const loop = this.#durableEventLoops.get(args.group) ?? {
       registrations: [],
@@ -4331,7 +4456,10 @@ export class Trellis<
     group: string,
     loop: DurableEventConsumerLoop<TA>,
   ): void {
-    if (loop.started || !this.#durableEventConsumerGroupReady(group, loop)) {
+    if (
+      this.#durableEventListenersStopped || loop.started ||
+      !this.#durableEventConsumerGroupReady(group, loop)
+    ) {
       return;
     }
     loop.started = true;
@@ -4378,10 +4506,29 @@ export class Trellis<
           return await jsm.consumers.info(binding.stream, binding.consumerName);
         });
         const info = infoResult.take();
-        if (isErr(info)) return info;
+        if (isErr(info)) {
+          if (
+            this.#durableEventListenersStopped ||
+            !this.#durableEventConsumerGroupReady(group, loop)
+          ) {
+            return ok(undefined);
+          }
+          if (isConsumerNotFoundError(info.error.cause)) {
+            this.#log.debug(
+              { group, stream: binding.stream, consumer: binding.consumerName },
+              "Durable event consumer is not available yet; retrying",
+            );
+            await sleep(25);
+            return ok(undefined);
+          }
+          return info;
+        }
 
         const consumer = this.js.consumers.getConsumerFromInfo(info);
-        while (this.#durableEventConsumerGroupReady(group, loop)) {
+        while (
+          !this.#durableEventListenersStopped &&
+          this.#durableEventConsumerGroupReady(group, loop)
+        ) {
           const messages = await consumer.fetch({
             max_messages: 1,
             expires: 30_000,
@@ -4394,10 +4541,28 @@ export class Trellis<
           await this.#handleDurableEventConsumer(group, loop, messages)
             .orThrow();
         }
+      } catch (cause) {
+        if (
+          this.#durableEventListenersStopped ||
+          !this.#durableEventConsumerGroupReady(group, loop)
+        ) {
+          return ok(undefined);
+        }
+        if (isConsumerNotFoundError(cause)) {
+          this.#log.debug(
+            { group, stream: binding.stream, consumer: binding.consumerName },
+            "Durable event consumer is not available yet; retrying",
+          );
+          await sleep(25);
+          return ok(undefined);
+        }
+        return err(new UnexpectedError({ cause, context: { group } }));
       } finally {
         loop.started = false;
         loop.messages = undefined;
-        this.#startDurableEventConsumer(group, loop);
+        if (!this.#durableEventListenersStopped) {
+          this.#startDurableEventConsumer(group, loop);
+        }
       }
       return ok(undefined);
     })());
@@ -4452,6 +4617,10 @@ export class Trellis<
   ): AsyncResult<void, ValidationError | UnexpectedError> {
     return AsyncResult.try(async () => {
       for await (const msg of messages) {
+        await this.#durableEventConsumerBeforeReadinessCheck?.({
+          group,
+          subject: msg.subject,
+        });
         if (!this.#durableEventConsumerGroupReady(group, loop)) {
           messages.stop();
           break;
@@ -4531,7 +4700,10 @@ export class Trellis<
     event: EventsOf<TA>,
     ctx: EventDescriptorOf<TA, EventsOf<TA>>,
     msg: Pick<Msg, "json" | "subject">,
-  ): Result<unknown, ValidationError | UnexpectedError> {
+  ): Result<
+    unknown,
+    SchemaValidationError | ValidationError | UnexpectedError
+  > {
     const jsonData = Result.try<JsonValue>(() => msg.json());
     const json = jsonData.take();
     if (isErr(json)) {
@@ -4549,6 +4721,15 @@ export class Trellis<
     return this.#tasks.wait();
   }
 
+  /** Stops durable event listener loops without closing the underlying transport. */
+  stopEventListeners(): void {
+    this.#durableEventListenersStopped = true;
+    for (const loop of this.#durableEventLoops.values()) {
+      loop.registrations.splice(0, loop.registrations.length);
+      loop.messages?.stop();
+    }
+  }
+
   // FIXME: If are validating things twice in most cases...
   template(
     subject: string,