effect 4.1.1 → 4.1.2

package/src/JsonSchema.ts

@@ -506,9 +506,23 @@ export function fromSchemaOpenApi3_0(schema: JsonSchema): Document<"draft-2020-1
  * @since 4.0.0
  */
 export function toDocumentDraft07(document: Document<"draft-2020-12">): Document<"draft-07"> {
+  return toDocumentDraft07WithDefinitionsPath(document)
+}
+
+/**
+ * Converts to Draft-07 with definitions located at `definitionsPath`, such as
+ * `["components", "schemas"]` after {@link toMultiDocumentComponents}, so
+ * references into them stay in place. Defaults to `$defs` → `definitions`.
+ *
+ * @internal
+ */
+export function toDocumentDraft07WithDefinitionsPath(
+  document: Document<"draft-2020-12">,
+  definitionsPath?: ReadonlyArray<string>
+): Document<"draft-07"> {
   return {
     dialect: "draft-07",
-    ...convertDocument(document, draft07Adapter)
+    ...convertDocument(document, draft07Adapter, undefined, definitionsPath)
   }
 }
 
@@ -620,6 +634,25 @@ export function toDocumentDraft04(document: Document<"draft-2020-12">): Document
  * @since 4.0.0
  */
 export function toMultiDocumentOpenApi3_1(multiDocument: MultiDocument<"draft-2020-12">): MultiDocument<"openapi-3.1"> {
+  return {
+    dialect: "openapi-3.1",
+    ...toMultiDocumentComponents(multiDocument, {
+      target: "OpenAPI 3.1",
+      checkSchema(schema) {
+        rejectKeywordCollisions(schema, OPEN_API_31_TARGET_COLLISIONS, "OpenAPI 3.1", "Draft 2020-12")
+      }
+    })
+  }
+}
+
+/** @internal */
+export function toMultiDocumentComponents(
+  multiDocument: Pick<MultiDocument<"draft-2020-12">, "schemas" | "definitions">,
+  options: {
+    readonly target: string
+    readonly checkSchema?: ((schema: JsonSchema) => void) | undefined
+  }
+): Pick<MultiDocument<"draft-2020-12">, "schemas" | "definitions"> {
   const definitionKeys = Object.keys(multiDocument.definitions)
   const keyMap = new Map<string, string>()
   const usedKeys = new Set(definitionKeys.filter((key) => VALID_OPEN_API_COMPONENTS_SCHEMAS_KEY_REGEXP.test(key)))
@@ -649,7 +682,7 @@ export function toMultiDocumentOpenApi3_1(multiDocument: MultiDocument<"draft-20
     const isRootResource = createsResource(schema.$id)
     const localDefinitions = Predicate.isObject(schema.$defs) ? schema.$defs : undefined
     return transformSchema(schema, (schema, inEmbeddedResource) => {
-      rejectKeywordCollisions(schema, OPEN_API_31_TARGET_COLLISIONS, "OpenAPI 3.1", "Draft 2020-12")
+      options.checkSchema?.(schema)
       rewriteSchemaRef(schema, (reference, keyword) => {
         const path = reference.startsWith("#") ? parseUriFragment(reference) : undefined
         if (path === undefined || path[0] !== "$defs" || path.length < 2) return reference
@@ -661,7 +694,7 @@ export function toMultiDocumentOpenApi3_1(multiDocument: MultiDocument<"draft-20
             Object.hasOwn(multiDocument.definitions, key) &&
             (localDefinitions === undefined || !Object.hasOwn(localDefinitions, key))
           ) {
-            unsupported(keyword, "OpenAPI 3.1", "a schema resource cannot reference the shared definitions pool")
+            unsupported(keyword, options.target, "a schema resource cannot reference the shared definitions pool")
           }
           return reference
         }
@@ -673,7 +706,7 @@ export function toMultiDocumentOpenApi3_1(multiDocument: MultiDocument<"draft-20
   }
 
   const schemas = multiDocument.schemas.map((schema) => rewrite(schema, true)) as unknown as MultiDocument<
-    "openapi-3.1"
+    "draft-2020-12"
   >["schemas"]
   const definitions: Definitions = {}
   for (const key of definitionKeys) {
@@ -685,7 +718,6 @@ export function toMultiDocumentOpenApi3_1(multiDocument: MultiDocument<"draft-20
   }
 
   return {
-    dialect: "openapi-3.1",
     schemas,
     definitions
   }
@@ -957,13 +989,19 @@ function convertSchema(root: JsonSchema, adapter: Adapter, options?: ConverterOp
 function convertDocument(
   document: Document<"draft-2020-12">,
   adapter: Adapter,
-  options?: ConverterOptions
+  options?: ConverterOptions,
+  definitionsPath?: Path
 ): { readonly schema: JsonSchema; readonly definitions: Definitions } {
   return runConverter(adapter, { ...options, trackIds: true }, (convert) => ({
     schema: convert(document.schema) as JsonSchema,
     definitions: mapObject(
       document.definitions,
-      (definition, key) => convert(definition, ["$defs", key], ["definitions", key]) as JsonSchema
+      (definition, key) =>
+        convert(
+          definition,
+          [...(definitionsPath ?? ["$defs"]), key],
+          [...(definitionsPath ?? ["definitions"]), key]
+        ) as JsonSchema
     ) as Definitions
   }))
 }

package/src/MutableRef.ts

@@ -12,7 +12,6 @@
  */
 import * as Equal from "./Equal.ts"
 import * as Dual from "./Function.ts"
-import * as Hash from "./Hash.ts"
 import { type Inspectable, toJson } from "./Inspectable.ts"
 import { PipeInspectableProto } from "./internal/core.ts"
 import type { Pipeable } from "./Pipeable.ts"
@@ -75,15 +74,9 @@ export interface MutableRef<out T> extends Pipeable, Inspectable {
   current: T
 }
 
-const MutableRefProto: Omit<MutableRef<unknown>, "current"> & Equal.Equal = {
+const MutableRefProto: Omit<MutableRef<unknown>, "current"> = {
   [TypeId]: TypeId,
   ...PipeInspectableProto,
-  [Equal.symbol](that: unknown): boolean {
-    return this === that
-  },
-  [Hash.symbol](): number {
-    return Hash.random(this)
-  },
   toJSON<A>(this: MutableRef<A>) {
     return {
       _id: "MutableRef",

package/src/Ref.ts

@@ -12,9 +12,7 @@
  * @since 2.0.0
  */
 import * as Effect from "./Effect.ts"
-import * as Equal from "./Equal.ts"
 import { dual, identity } from "./Function.ts"
-import * as Hash from "./Hash.ts"
 import { PipeInspectableProto } from "./internal/core.ts"
 import * as MutableRef from "./MutableRef.ts"
 import type * as Option from "./Option.ts"
@@ -112,12 +110,6 @@ const RefProto = {
     _A: identity
   },
   ...PipeInspectableProto,
-  [Equal.symbol](that: unknown): boolean {
-    return this === that
-  },
-  [Hash.symbol](): number {
-    return Hash.random(this)
-  },
   toJSON(this: Ref<any>) {
     return {
       _id: "Ref",

package/src/Schedule.ts

@@ -889,7 +889,8 @@ export const cron: {
       return Cause.done(Duration.zero)
     }
     return effect.sync(() => {
-      const next = Cron.next(cron, now).getTime()
+      let next = Cron.next(cron, now).getTime()
+      if (Duration.isZero(Duration.millis(next - now))) next = Cron.next(cron, next).getTime()
       const duration = Duration.millis(next - now)
       return [duration, duration]
     })
@@ -1157,7 +1158,7 @@ export const fixed = (interval: Duration.Input): Schedule<number> => {
         }
         const runningBehind = meta.now > (lastRun + window)
         const boundary = window - ((meta.now - start) % window)
-        const delay = runningBehind ? 0 : boundary === 0 ? window : boundary
+        const delay = runningBehind ? 0 : Duration.isZero(Duration.millis(boundary)) ? window : boundary
         lastRun = runningBehind ? meta.now : meta.now + delay
         return [meta.attempt - 1, Duration.millis(delay)] as const
       })
@@ -1901,10 +1902,11 @@ export {
 export const windowed = (interval: Duration.Input): Schedule<number> => {
   const window = Duration.toMillis(Duration.fromInputUnsafe(interval))
   return fromStepWithMetadata(effect.succeed((meta) =>
-    effect.sync(() => [
-      meta.attempt - 1,
-      window === 0 ? Duration.zero : Duration.millis(window - (meta.elapsed % window))
-    ])
+    effect.sync(() => {
+      if (window === 0) return [meta.attempt - 1, Duration.zero] as const
+      const delay = Duration.millis(window - (meta.elapsed % window))
+      return [meta.attempt - 1, Duration.isZero(delay) ? Duration.millis(window) : delay] as const
+    })
   ))
 }
 

package/src/Stream.ts

@@ -15245,12 +15245,13 @@ export const groupAdjacentBy: {
           return loop
         })
       )
-      let done = false
-      return Pull.catchDone(Effect.suspend(() => done ? Cause.done() : loop), () => {
-        done = true
-        const out = group
+      let cause: Cause.Cause<E | Cause.Done> | undefined
+      return Effect.catchCause(Effect.suspend(() => cause ? Effect.failCause(cause) : loop), (cause_) => {
+        cause = cause_
+        if (group === undefined) return Effect.failCause(cause_)
+        const out = Arr.of([currentKey, group] as const)
         group = undefined
-        return out && Arr.isArrayNonEmpty(out) ? Effect.succeed(Arr.of([currentKey, out])) : Cause.done()
+        return Effect.succeed(out)
       })
     })))
 

package/src/ai/McpServer.ts

@@ -737,23 +737,48 @@ class MiddlewareImpl {
   }
 }
 
-// The innermost middleware comes first.
+// The innermost middleware comes first. Each stack keeps its own order, and
+// where that leaves the order open, stacks provided further outside, which come
+// first in the context, run further outside. Stacks that order the same
+// middleware both ways have no common order, so insertion order decides.
 const getMiddleware = (context: Context.Context<never>): ReadonlyArray<AnyMiddlewareFn> => {
-  const stacks: Array<ReadonlyArray<AnyMiddlewareFn>> = []
-  let maxLength = 0
-  for (const [key, value] of context.mapUnsafe) {
-    if (key.startsWith(middlewareKeyPrefix)) {
-      stacks.push(value)
-      maxLength = Math.max(maxLength, value.length)
+  // The middleware directly inside each middleware, and how many of those
+  // directly outside it are still unplaced.
+  const inners = new Map<AnyMiddlewareFn, Array<AnyMiddlewareFn>>()
+  const unplacedOuters = new Map<AnyMiddlewareFn, number>()
+  for (const [key, stack] of context.mapUnsafe) {
+    if (!key.startsWith(middlewareKeyPrefix)) continue
+    for (let i = stack.length - 1; i >= 0; i--) {
+      const fn = stack[i]
+      if (!inners.has(fn)) {
+        inners.set(fn, [])
+        unplacedOuters.set(fn, 0)
+      }
+      const outer = stack[i + 1]
+      if (outer !== undefined && outer !== fn) {
+        inners.get(outer)!.push(fn)
+        unplacedOuters.set(fn, unplacedOuters.get(fn)! + 1)
+      }
     }
   }
-  const unique = new Set<AnyMiddlewareFn>()
-  for (let i = maxLength - 1; i >= 0; i--) {
-    for (const stack of stacks) {
-      if (i < stack.length) unique.add(stack[i])
+  // Repeatedly places the first middleware with nothing left to place outside it.
+  const outermostFirst: Array<AnyMiddlewareFn> = []
+  while (unplacedOuters.size > 0) {
+    let next = unplacedOuters.keys().next().value!
+    for (const [fn, count] of unplacedOuters) {
+      if (count === 0) {
+        next = fn
+        break
+      }
+    }
+    unplacedOuters.delete(next)
+    outermostFirst.push(next)
+    for (const fn of inners.get(next)!) {
+      const count = unplacedOuters.get(fn)
+      if (count !== undefined) unplacedOuters.set(fn, count - 1)
     }
   }
-  return Arr.fromIterable(unique).reverse()
+  return outermostFirst.reverse()
 }
 
 const isMcpError = (error: unknown): error is McpErrorBase =>
@@ -2099,7 +2124,7 @@ const runWithRuntime = Effect.fnUntraced(function*(
             const selectedProtocol = clientState?.protocol ?? runtime.protocols[0]
             const profile = reverseKey?.profile ?? clientState?.profile ?? {
               protocolVersion: selectedProtocol.protocolVersion,
-              clientCapabilities: {},
+              clientCapabilities: new McpSchema.ClientCapabilities({}),
               clientInfo: { name: "unknown", version: "unknown" }
             }
             return RcMap.get(
@@ -3081,40 +3106,40 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
     const annotations = tool.annotations
     const toolMeta = Context.getOrUndefined(annotations, Tool.Meta)
     const isDeclaredFailure = Schema.is(tool.failureSchema)
-    const encodeFailure = Schema.encodeUnknownEffect(tool.failureSchema) as (
-      error: unknown
-    ) => Effect.Effect<unknown, Schema.SchemaError, Tool.HandlerServices<Tools[keyof Tools]>>
-    const declaredFailureResult = (error: unknown) =>
-      error instanceof Error && error.message !== ""
-        ? Effect.succeed(toolErrorResult(error.message))
-        : Effect.map(encodeFailure(error), (encoded) =>
-          new CallToolResult({ isError: true, content: toolResultContent(encoded) }))
-    // `structuredContent` must be JSON and match the advertised `outputSchema`, which is derived from the JSON codec.
-    // The Toolkit has already encoded the result, so only the JSON conversion of its encoded form runs here.
-    const encodeStructured = Schema.encodeUnknownEffect(Schema.toCodecJson(Schema.toEncoded(tool.successSchema))) as (
-      result: unknown
-    ) => Effect.Effect<unknown, Schema.SchemaError, Tool.HandlerServices<Tools[keyof Tools]>>
-    const successResult = (result: unknown) =>
-      encodeStructured(result).pipe(
-        Effect.mapError((cause) =>
+    // MCP content is JSON, so results and declared failures go through their JSON codec.
+    const encodeJson = (schema: Schema.Constraint) => {
+      const encode = Schema.encodeUnknownEffect(Schema.toCodecJson(schema)) as (
+        value: unknown
+      ) => Effect.Effect<unknown, Schema.SchemaError, Tool.HandlerServices<Tools[keyof Tools]>>
+      return (toolResult: unknown) =>
+        Effect.mapError(encode(toolResult), (cause) =>
           AiError.make({
             module: "McpServer",
             method: "registerToolkit",
             reason: new AiError.ToolResultEncodingError({
               toolName: tool.name,
-              toolResult: result,
+              toolResult,
               description: cause.message
             })
-          })
-        ),
-        Effect.map((structuredContent) =>
-          new CallToolResult({
-            isError: false,
-            structuredContent,
-            content: toolResultContent(structuredContent)
-          })
-        )
-      )
+          }))
+    }
+    const encodeFailure = encodeJson(tool.failureSchema)
+    // Successes and "return"-mode failures arrive already encoded by the Toolkit; only their JSON conversion runs here.
+    const encodeReturnedFailure = encodeJson(Schema.toEncoded(tool.failureSchema))
+    const encodeStructured = encodeJson(Schema.toEncoded(tool.successSchema))
+    const failureResult = (encoded: unknown) =>
+      new CallToolResult({ isError: true, content: toolResultContent(encoded) })
+    const declaredFailureResult = (error: unknown) =>
+      error instanceof Error && error.message !== ""
+        ? Effect.succeed(toolErrorResult(error.message))
+        : Effect.map(encodeFailure(error), failureResult)
+    const successResult = (result: unknown) =>
+      Effect.map(encodeStructured(result), (structuredContent) =>
+        new CallToolResult({
+          isError: false,
+          structuredContent,
+          content: toolResultContent(structuredContent)
+        }))
     const handleCause = (cause: Cause.Cause<unknown>) => {
       const failure = Cause.findFail(cause)
       if (Result.isSuccess(failure)) {
@@ -3183,9 +3208,7 @@ export const registerToolkit: <Tools extends Record<string, Tool.Any>>(
             }
             // Declared failures return their encoded payload; anything else is classified by origin.
             return result.failureOrigin === "handler"
-              ? Effect.succeed(
-                new CallToolResult({ isError: true, content: toolResultContent(result.encodedResult) })
-              )
+              ? Effect.map(encodeReturnedFailure(result.encodedResult), failureResult)
               : Effect.failCause(Cause.annotate(
                 Cause.fail(result.result),
                 Context.make(Toolkit.FailureOrigin, result.failureOrigin ?? "result")

package/src/ai/internal/mcpProtocol/v2026_07_28.ts

@@ -203,13 +203,12 @@ const projectContent = Match.type<PublicMcpSchema.ContentBlock>().pipe(
   Match.exhaustive
 )
 
-const projectResource = (resource: PublicMcpSchema.Resource) =>
-  McpProtocol.transcode(PublicMcpSchema.Resource, McpSchema.Resource, resource)
+// Registrations may be plain objects, so encode with the wire struct.
+const projectResource = (resource: PublicMcpSchema.Resource) => Schema.encodeEffect(McpSchema.Resource)(resource)
 const projectResourceTemplate = (resourceTemplate: PublicMcpSchema.ResourceTemplate) =>
-  McpProtocol.transcode(PublicMcpSchema.ResourceTemplate, McpSchema.ResourceTemplate, resourceTemplate)
+  Schema.encodeEffect(McpSchema.ResourceTemplate)(resourceTemplate)
 
-const projectPrompt = (prompt: PublicMcpSchema.Prompt) =>
-  McpProtocol.transcode(PublicMcpSchema.Prompt, McpSchema.Prompt, prompt)
+const projectPrompt = (prompt: PublicMcpSchema.Prompt) => Schema.encodeEffect(McpSchema.Prompt)(prompt)
 
 const projectTool = (tool: PublicMcpSchema.Tool) => McpProtocol.transcode(PublicMcpSchema.Tool, McpSchema.Tool, tool)
 

package/src/ai/internal/structured-output.ts

@@ -38,11 +38,17 @@ export function resolveReference($ref: string, definitions: JsonSchema.Definitio
 export function resolveTopLevelReference(
   document: JsonSchema.Document<"draft-2020-12">
 ): JsonSchema.Document<"draft-2020-12"> {
-  if (typeof document.schema.$ref !== "string") return document
-  return {
-    ...document,
-    schema: resolveReference(document.schema.$ref, document.definitions)
+  let schema = document.schema
+  if (typeof schema.$ref !== "string") return document
+  const visited = new Set<string>()
+  while (typeof schema.$ref === "string") {
+    if (visited.has(schema.$ref)) {
+      throw new Error(`Circular reference ${JSON.stringify(schema.$ref)}`)
+    }
+    visited.add(schema.$ref)
+    schema = resolveReference(schema.$ref, document.definitions)
   }
+  return { ...document, schema }
 }
 
 /**

package/src/cluster/ClusterWorkflowEngine.ts

@@ -267,7 +267,11 @@ export const make = Effect.gen(function*() {
         id: activityPrimaryKey(options.activity.name, options.attempt)
       })
       if (Option.isNone(requestId)) return
-      yield* sharding.reset(requestId.value)
+      // Reset only the Suspended reply this runner saw. If another runner has
+      // stored a newer reply, storage skips the reset and the caller reads it.
+      const reply = yield* replyForRequestId(requestId.value)
+      if (Option.isNone(reply) || !isSuspendedReply(reply.value)) return
+      yield* sharding.reset(requestId.value, { expectedReplyId: Snowflake.Snowflake(reply.value.id) })
     },
     Effect.retry({
       times: 3,
@@ -344,7 +348,7 @@ export const make = Effect.gen(function*() {
     }
     const reply = yield* replyForRequestId(requestId.value)
     if (Option.isNone(reply)) return
-    yield* sharding.reset(requestId.value)
+    yield* sharding.reset(requestId.value, { expectedReplyId: Snowflake.Snowflake(reply.value.id) })
   }, Effect.scoped)
 
   // Subscribe to the run's next reply before reading storage, so a reply
@@ -865,7 +869,7 @@ export const make = Effect.gen(function*() {
         }
         const workflow = workflows.get(workflowName)
         if (workflow) {
-          return yield* Effect.orDie(sendDiscard({
+          return yield* retryPersistence(sendDiscard({
             rpc: DeferredRpc,
             address: entityAddressFor({
               workflow,
@@ -879,7 +883,7 @@ export const make = Effect.gen(function*() {
           }))
         }
         const client = yield* RcMap.get(clientsPartial, workflowName)
-        return yield* Effect.orDie(
+        return yield* retryPersistence(
           client(executionId).deferred({
             name: deferredName,
             exit
@@ -890,27 +894,24 @@ export const make = Effect.gen(function*() {
     ),
 
     scheduleClock(workflow, options) {
-      return DateTime.now.pipe(
-        Effect.flatMap((now) =>
-          sendDiscard({
-            rpc: ClockRpc,
-            address: entityAddressFor({
-              workflow,
-              entityType: ClockEntity.type,
-              executionId: options.executionId
-            }),
-            payload: {
-              name: options.clock.name,
-              workflowName: workflow._tag,
-              wakeUp: DateTime.mapEpochMillis(
-                DateTime.addDuration(now, options.clock.duration),
-                Math.ceil
-              )
-            }
-          })
-        ),
-        Effect.orDie
-      )
+      // Compute the deadline once, so a retried save keeps the original wake-up.
+      return Effect.flatMap(DateTime.now, (now) =>
+        retryPersistence(sendDiscard({
+          rpc: ClockRpc,
+          address: entityAddressFor({
+            workflow,
+            entityType: ClockEntity.type,
+            executionId: options.executionId
+          }),
+          payload: {
+            name: options.clock.name,
+            workflowName: workflow._tag,
+            wakeUp: DateTime.mapEpochMillis(
+              DateTime.addDuration(now, options.clock.duration),
+              Math.ceil
+            )
+          }
+        })))
     }
   })
 
@@ -922,9 +923,9 @@ const retryPolicy = Schedule.min([
   Schedule.spaced("1 minute")
 ])
 
-// A transient storage failure must not become the workflow result. Requests
-// are saved under a primary key, so a retry after a lost acknowledgement is
-// deduplicated instead of running the activity again.
+// A transient storage failure must not become the workflow result. Activity,
+// clock and deferred requests are saved under a primary key, so a retry after
+// a lost acknowledgement is deduplicated instead of stored twice.
 const retryPersistence = <A, E extends { readonly _tag: string }, R>(effect: Effect.Effect<A, E, R>) =>
   effect.pipe(
     Effect.retry({ schedule: retryPolicy, while: (e) => e._tag === "PersistenceError" }),

package/src/cluster/Entity.ts

@@ -148,7 +148,20 @@ export interface Entity<
       readonly concurrency?: number | "unbounded" | undefined
       readonly mailboxCapacity?: number | "unbounded" | undefined
       readonly mailboxMetrics?: boolean | undefined
+      /**
+       * When `true`, a handler defect fails only its request instead of
+       * restarting the entity and replaying its in-flight requests.
+       */
       readonly disableFatalDefects?: boolean | undefined
+      /**
+       * Schedule for restarting an entity after a defect and for retrying failed
+       * handler construction.
+       *
+       * Backoff is tracked per entity and resets once a request completes.
+       * When the policy ends, the default (500 ms growing by 1.5x, capped at 10
+       * seconds) continues, so restarts never stop; use `disableFatalDefects` to
+       * avoid them.
+       */
       readonly defectRetryPolicy?: Schedule.Schedule<any, unknown> | undefined
       readonly spanAttributes?: Record<string, string> | undefined
     }
@@ -193,7 +206,20 @@ export interface Entity<
       readonly maxIdleTime?: Duration.Input | undefined
       readonly mailboxCapacity?: number | "unbounded" | undefined
       readonly mailboxMetrics?: boolean | undefined
+      /**
+       * When `true`, a handler defect fails only its request instead of
+       * restarting the entity and replaying its in-flight requests.
+       */
       readonly disableFatalDefects?: boolean | undefined
+      /**
+       * Schedule for restarting an entity after a defect and for retrying failed
+       * handler construction.
+       *
+       * Backoff is tracked per entity and resets once a request completes.
+       * When the policy ends, the default (500 ms growing by 1.5x, capped at 10
+       * seconds) continues, so restarts never stop; use `disableFatalDefects` to
+       * avoid them.
+       */
       readonly defectRetryPolicy?: Schedule.Schedule<any, unknown> | undefined
       readonly spanAttributes?: Record<string, string> | undefined
     }
@@ -290,7 +316,20 @@ const Proto = {
       readonly concurrency?: number | "unbounded" | undefined
       readonly mailboxCapacity?: number | "unbounded" | undefined
       readonly mailboxMetrics?: boolean | undefined
+      /**
+       * When `true`, a handler defect fails only its request instead of
+       * restarting the entity and replaying its in-flight requests.
+       */
       readonly disableFatalDefects?: boolean | undefined
+      /**
+       * Schedule for restarting an entity after a defect and for retrying failed
+       * handler construction.
+       *
+       * Backoff is tracked per entity and resets once a request completes.
+       * When the policy ends, the default (500 ms growing by 1.5x, capped at 10
+       * seconds) continues, so restarts never stop; use `disableFatalDefects` to
+       * avoid them.
+       */
       readonly defectRetryPolicy?: Schedule.Schedule<any, unknown> | undefined
       readonly spanAttributes?: Record<string, string> | undefined
     }
@@ -339,7 +378,20 @@ const Proto = {
       readonly maxIdleTime?: Duration.Input | undefined
       readonly mailboxCapacity?: number | "unbounded" | undefined
       readonly mailboxMetrics?: boolean | undefined
+      /**
+       * When `true`, a handler defect fails only its request instead of
+       * restarting the entity and replaying its in-flight requests.
+       */
       readonly disableFatalDefects?: boolean | undefined
+      /**
+       * Schedule for restarting an entity after a defect and for retrying failed
+       * handler construction.
+       *
+       * Backoff is tracked per entity and resets once a request completes.
+       * When the policy ends, the default (500 ms growing by 1.5x, capped at 10
+       * seconds) continues, so restarts never stop; use `disableFatalDefects` to
+       * avoid them.
+       */
       readonly defectRetryPolicy?: Schedule.Schedule<any, unknown> | undefined
       readonly spanAttributes?: Record<string, string> | undefined
     }

package/src/cluster/MessageStorage.ts

@@ -30,6 +30,7 @@ import * as DeliverAt from "./DeliverAt.ts"
 import type { EntityAddress } from "./EntityAddress.ts"
 import * as Envelope from "./Envelope.ts"
 import * as ClusterAbandon from "./internal/clusterAbandon.ts"
+import { TransactionNotifications } from "./internal/transactionNotifications.ts"
 import * as Message from "./Message.ts"
 import * as Reply from "./Reply.ts"
 import * as ShardId from "./ShardId.ts"
@@ -223,8 +224,8 @@ export class MessageStorage extends Context.Service<MessageStorage, {
   /**
    * Wraps requests in storage transactions.
    *
-   * `WithExit` replies saved in a transaction notify callers after the outermost
-   * commit; stream chunks notify immediately. Replies saved in a failed
+   * `WithExit` replies and discarded sends saved in a transaction notify after
+   * the outermost commit; stream chunks notify immediately. Replies saved in a failed
    * transaction must be discarded. The wrapper may fail only with the wrapped
    * effect's own failure or a defect.
    */
@@ -532,10 +533,6 @@ export type EncodedRepliesOptions<A> = {
   readonly cursor: Option.Option<A>
 }
 
-const TransactionNotifications = Context.Reference<
-  Array<Effect.Effect<void, PersistenceError | MalformedMessage>> | undefined
->("effect/cluster/MessageStorage/TransactionNotifications", { defaultValue: () => undefined })
-
 /**
  * Wraps a concrete message storage implementation with reply-handler management.
  *

package/src/cluster/Runners.ts

@@ -32,6 +32,7 @@ import type { MalformedMessage, PersistenceError } from "./ClusterError.ts"
 import { AlreadyProcessingMessage, EntityNotAssignedToRunner, MailboxFull, RunnerUnavailable } from "./ClusterError.ts"
 import { Persisted } from "./ClusterSchema.ts"
 import * as Envelope from "./Envelope.ts"
+import { TransactionNotifications } from "./internal/transactionNotifications.ts"
 import * as Message from "./Message.ts"
 import * as MessageStorage from "./MessageStorage.ts"
 import * as Reply from "./Reply.ts"
@@ -180,6 +181,19 @@ export const make: (
 
   const requestIdRewrites = new Map<Snowflake.Snowflake, Snowflake.Snowflake>()
 
+  // A message saved in a transaction is invisible to readers until the commit,
+  // so its wake-up waits for the commit. A failure then can no longer be
+  // returned and is dropped; the next storage poll delivers the message.
+  const notifyAfterCommit = <E>(message: Message.Outgoing<any>, notify: Effect.Effect<void, E>) => {
+    const rpc = message.rpc as any as Rpc.AnyWithProps
+    if (!Context.get(rpc.annotations, Persisted)) return notify
+    return TransactionNotifications.use((notifications) =>
+      notifications === undefined ? notify : Effect.sync(() => {
+        notifications.push(Effect.ignore(notify))
+      })
+    )
+  }
+
   function notifyWith<E>(
     message: Message.Outgoing<any>,
     afterPersist: (message: Message.Outgoing<any>, isDuplicate: boolean) => Effect.Effect<void, E>
@@ -471,7 +485,7 @@ export const make: (
       const { discard, message } = options_
       return notifyWith(message, (message, duplicate) => {
         if (discard || message._tag === "OutgoingEnvelope") {
-          return options.notify(options_)
+          return notifyAfterCommit(message, options.notify(options_))
         } else if (!duplicate && Option.isSome(options_.address)) {
           return Effect.catch(
             options.send({
@@ -499,7 +513,7 @@ export const make: (
       }
       return notifyWith(message, (message) => {
         if (options.discard || message._tag === "OutgoingEnvelope") {
-          return notifyEntity(message)
+          return notifyAfterCommit(message, notifyEntity(message))
         }
         return Effect.andThen(
           notifyEntity(message),