@effect-uai/core 0.14.0 → 0.16.0

package/src/streaming/Settle.ts

@@ -0,0 +1,196 @@
+/**
+ * Acting on a pause in a stream of arrivals.
+ *
+ * A chat user types three lines then stops; a transcriber emits token deltas
+ * then goes quiet. Both want a resetting window: every arrival pushes the
+ * deadline out. Effect's `groupedWithin` measures a fixed window from the first
+ * element of a batch and `debounce` drops all but the last element, so neither
+ * expresses this.
+ *
+ * `settleBurst` withholds elements until a burst ends; `onQuiet` holds nothing
+ * back and only adds an event once things go still.
+ */
+import {
+  Array as Arr,
+  Cause,
+  Clock,
+  Deferred,
+  Duration,
+  Effect,
+  Function,
+  Option,
+  Pull,
+  Queue,
+  Ref,
+  Result,
+  Stream,
+} from "effect"
+
+/** Buffer between a source stream and the batcher. 64 matches the realtime adapters. */
+const DEFAULT_CAPACITY = 64
+
+/**
+ * Block for the first item, then keep taking while the next one lands within
+ * `settle` of the previous. The window resets on every arrival, so a burst
+ * becomes one batch and a lone message followed by silence returns at once.
+ *
+ * A take that loses to the window is interrupted before it removes anything,
+ * so late arrivals stay queued for the next drain. The queue is the caller's:
+ * it owns the backpressure strategy.
+ */
+export const drainBurst = <A, E>(
+  queue: Queue.Dequeue<A, E>,
+  settle: Duration.Input,
+): Effect.Effect<Arr.NonEmptyReadonlyArray<A>, E> => {
+  const settled = (
+    batch: Arr.NonEmptyReadonlyArray<A>,
+  ): Effect.Effect<Arr.NonEmptyReadonlyArray<A>, E> =>
+    Queue.take(queue).pipe(
+      Effect.timeoutOption(settle),
+      Effect.flatMap(
+        Option.match({
+          onNone: () => Effect.succeed(batch),
+          onSome: (item) => settled(Arr.append(batch, item)),
+        }),
+      ),
+      // A queue that ends mid-burst yields the batch in hand. Interrupts and
+      // real failures still propagate.
+      Effect.catchCause((cause) =>
+        Pull.isDoneCause(cause) ? Effect.succeed(batch) : Effect.failCause(cause),
+      ),
+    )
+  return Effect.flatMap(Queue.take(queue), (first) => settled([first]))
+}
+
+export type SettleBurstOptions = {
+  /** Elements buffered ahead of the batcher. A full buffer suspends the source. */
+  readonly capacity?: number
+}
+
+/**
+ * `drainBurst` over a stream: one array per burst, nothing while a burst is
+ * still growing.
+ *
+ * Detecting a pause means reading ahead of the consumer, so this buffers by
+ * construction. The buffer is bounded, so a slow consumer suspends the source
+ * instead of growing memory.
+ */
+export const settleBurst: {
+  (
+    settle: Duration.Input,
+    options?: SettleBurstOptions,
+  ): <A, E, R>(self: Stream.Stream<A, E, R>) => Stream.Stream<ReadonlyArray<A>, E, R>
+  <A, E, R>(
+    self: Stream.Stream<A, E, R>,
+    settle: Duration.Input,
+    options?: SettleBurstOptions,
+  ): Stream.Stream<ReadonlyArray<A>, E, R>
+} = Function.dual(
+  (args) => Stream.isStream(args[0]),
+  <A, E, R>(
+    self: Stream.Stream<A, E, R>,
+    settle: Duration.Input,
+    options?: SettleBurstOptions,
+  ): Stream.Stream<ReadonlyArray<A>, E, R> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        // `Cause.Done` as the failure type is what makes `Queue.end` available;
+        // `Queue.shutdown` would clear items still waiting to be batched.
+        const queue = yield* Queue.bounded<A, E | Cause.Done>(options?.capacity ?? DEFAULT_CAPACITY)
+        yield* Stream.runForEach(self, (a) => Queue.offer(queue, a)).pipe(
+          // A failing source must reach the consumer. Ending the queue instead
+          // would present the failure as a clean end of stream.
+          Effect.matchCauseEffect({
+            onFailure: (cause) =>
+              Cause.hasFails(cause) ? Queue.failCause(queue, cause) : Queue.end(queue),
+            onSuccess: () => Queue.end(queue),
+          }),
+          Effect.forkScoped,
+        )
+        return Stream.fromPull(
+          Effect.succeed(Effect.map(drainBurst(queue, settle), (batch) => [batch] as const)),
+        )
+      }),
+    ),
+)
+
+/**
+ * Pass every element through the moment it arrives, and emit whatever `emit`
+ * yields once nothing has arrived for `settle`. At most one emission per quiet
+ * period: the next element re-arms it.
+ *
+ * Nothing is held back, so this suits live output that wants a boundary marker
+ * rather than batching. Ends with the source.
+ */
+export const onQuiet: {
+  <B>(
+    settle: Duration.Input,
+    emit: Effect.Effect<Option.Option<B>>,
+  ): <A, E, R>(self: Stream.Stream<A, E, R>) => Stream.Stream<A | B, E, R>
+  <A, E, R, B>(
+    self: Stream.Stream<A, E, R>,
+    settle: Duration.Input,
+    emit: Effect.Effect<Option.Option<B>>,
+  ): Stream.Stream<A | B, E, R>
+} = Function.dual(
+  3,
+  <A, E, R, B>(
+    self: Stream.Stream<A, E, R>,
+    settle: Duration.Input,
+    emit: Effect.Effect<Option.Option<B>>,
+  ): Stream.Stream<A | B, E, R> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const settleMs = Duration.toMillis(settle)
+        const lastAt = yield* Ref.make(0)
+        // Opened by the first arrival after each emission. An idle stream never
+        // wakes the metronome at all.
+        const gate = yield* Ref.make(yield* Deferred.make<void>())
+
+        const source = self.pipe(
+          Stream.tap(() =>
+            Effect.gen(function* () {
+              // Stamp before opening: the metronome re-reads the stamp after it
+              // swaps the gate, so an arrival that races the swap still counts.
+              const now = yield* Clock.currentTimeMillis
+              yield* Ref.set(lastAt, now)
+              const open = yield* Ref.get(gate)
+              yield* Deferred.succeed(open, undefined)
+            }),
+          ),
+        )
+
+        const quietFor = Effect.map(
+          Effect.all([Clock.currentTimeMillis, Ref.get(lastAt)]),
+          ([now, last]) => now - last,
+        )
+
+        // Waits for the gate, then sleeps out whatever is left of the window.
+        // Never polls, whether the source is busy or idle.
+        const tick = Effect.gen(function* () {
+          yield* Effect.flatMap(Ref.get(gate), Deferred.await)
+          const elapsed = yield* quietFor
+          if (elapsed < settleMs) {
+            yield* Effect.sleep(Duration.millis(settleMs - elapsed))
+            return Option.none<B>()
+          }
+          const next = yield* Deferred.make<void>()
+          yield* Ref.set(gate, next)
+          // An arrival between the check and the swap opened the old gate, so
+          // carry it over rather than sleeping through the burst it started.
+          if ((yield* quietFor) < settleMs) {
+            yield* Deferred.succeed(next, undefined)
+            return Option.none<B>()
+          }
+          return yield* emit
+        })
+
+        const metronome = Stream.fromEffect(tick).pipe(
+          Stream.forever,
+          Stream.filterMap((o) => (Option.isSome(o) ? Result.succeed(o.value) : Result.failVoid)),
+        )
+
+        return source.pipe(Stream.merge(metronome, { haltStrategy: "left" }))
+      }),
+    ),
+)

package/src/streaming/WebSocketSession.test.ts

@@ -0,0 +1,52 @@
+import { describe, it } from "@effect/vitest"
+import * as Socket from "effect/unstable/socket/Socket"
+import { expect } from "vitest"
+import * as AiError from "../domain/AiError.js"
+import { toAiError } from "./WebSocketSession.js"
+
+const KEY = "AIzaSyEXAMPLEKEY"
+const URL = `wss://generativelanguage.googleapis.com/ws/BidiGenerateContent?key=${KEY}`
+
+/**
+ * What Bun hands the `error` listener when the upgrade is rejected: the whole
+ * socket URL, in prose, on a prototype getter. Node and Deno say less, but the
+ * adapter cannot know which runtime it is on.
+ */
+class BunErrorEvent {
+  get message(): string {
+    return `WebSocket connection to '${URL}' failed: Connection ended`
+  }
+}
+
+/** Deno names the status but not the URL, also on a prototype getter. */
+class DenoErrorEvent {
+  constructor(private readonly detail: string) {}
+  get message(): string {
+    return `NetworkError: failed to connect to WebSocket: ${this.detail}`
+  }
+}
+
+const openFailure = (cause: unknown) =>
+  new Socket.SocketError({ reason: new Socket.SocketOpenError({ kind: "Unknown", cause }) })
+
+describe("WebSocketSession errors", () => {
+  it("keeps the key out of the error a rejected upgrade produces", () => {
+    const error = toAiError("google")(openFailure(new BunErrorEvent()))
+
+    expect(JSON.stringify(error)).not.toContain(KEY)
+    expect(AiError.describe(error)).not.toContain(KEY)
+    // The host is still there: an error that says nothing is its own problem.
+    expect(JSON.stringify(error)).toContain("generativelanguage.googleapis.com")
+  })
+
+  it("reads the rejected status out of the prose, wherever the runtime put it", () => {
+    // Deno's wording. The status is the only hint a rejected upgrade gives.
+    const forbidden = toAiError("google")(
+      openFailure(new DenoErrorEvent("Invalid status code: 403")),
+    )
+    const ended = toAiError("google")(openFailure(new BunErrorEvent()))
+
+    expect(forbidden._tag).toBe("AuthFailed")
+    expect(ended._tag).toBe("Unavailable")
+  })
+})

package/src/streaming/WebSocketSession.ts

@@ -0,0 +1,132 @@
+/**
+ * One JSON-over-WebSocket session: connect, read decoded frames off a queue,
+ * write frames back.
+ *
+ * For duplex protocols where the caller drives the conversation frame by
+ * frame. The stream-shaped adapters (realtime STT and TTS) still carry their
+ * own copies of this.
+ */
+import {
+  Cause,
+  type Duration,
+  Effect,
+  Match,
+  Option,
+  Predicate,
+  Queue,
+  Schema,
+  type Scope,
+} from "effect"
+import * as Socket from "effect/unstable/socket/Socket"
+import * as AiError from "../domain/AiError.js"
+import * as JSONL from "./JSONL.js"
+
+export type WebSocketSession<A> = {
+  /** Fails `Unavailable` once the socket is closed. */
+  readonly send: (frame: string) => Effect.Effect<void, AiError.AiError>
+  /** Ends when the socket closes cleanly, fails when it does not. */
+  readonly frames: Queue.Dequeue<A, AiError.AiError | Cause.Done>
+}
+
+export type OpenOptions<A, I> = {
+  readonly url: string
+  readonly provider: string
+  /** Frames that do not decode are dropped, and logged at debug level. */
+  readonly schema: Schema.Codec<A, I>
+  readonly openTimeout?: Duration.Input
+  readonly capacity?: number
+}
+
+/**
+ * The cause of a failed open is a DOM `ErrorEvent`, not an `Error`, and its
+ * `message` is a prototype getter, so a structural decode does not see it.
+ */
+const describeCause = (cause: unknown): string =>
+  Predicate.hasProperty(cause, "message") && Predicate.isString(cause.message)
+    ? cause.message
+    : String(cause)
+
+/**
+ * Some wires authenticate with a key in the query string, and some runtimes
+ * name the socket URL in their open error (Bun does). Everything taken off a
+ * socket error goes through this.
+ */
+export const redactUrl = (text: string): string =>
+  text.replace(/(\b(?:wss?|https?):\/\/[^\s"']*?)\?[^\s"']*/gi, "$1?<redacted>")
+
+const detailOf = Match.type<Socket.SocketError["reason"]>().pipe(
+  Match.tag("SocketCloseError", (reason) => reason.message),
+  Match.orElse((reason) => describeCause(reason.cause)),
+)
+
+/** Never the `SocketError` itself: callers print `raw` with `Cause.pretty`. */
+const rawOf = (error: Socket.SocketError): string =>
+  redactUrl(`${error.reason._tag}: ${detailOf(error.reason)}`)
+
+/** A rejected WS upgrade surfaces only as prose, so the status is read from it. */
+const isAuthRejection = (text: string): boolean => /\b40[13]\b/.test(text)
+
+export const toAiError =
+  (provider: string) =>
+  (error: Socket.SocketError): AiError.AiError => {
+    const raw = rawOf(error)
+    return Match.value(error.reason).pipe(
+      Match.tag("SocketOpenError", (reason) =>
+        Match.value(reason.kind).pipe(
+          Match.when("Timeout", (): AiError.AiError => new AiError.Timeout({ provider, raw })),
+          Match.orElse((): AiError.AiError =>
+            isAuthRejection(describeCause(reason.cause))
+              ? new AiError.AuthFailed({ provider, subtype: "auth", raw })
+              : new AiError.Unavailable({ provider, raw }),
+          ),
+        ),
+      ),
+      Match.orElse((): AiError.AiError => new AiError.Unavailable({ provider, raw })),
+    )
+  }
+
+/**
+ * Connect for the lifetime of the surrounding `Scope`. The reader runs in a
+ * forked fiber; a dirty close reaches the consumer as a failed queue rather
+ * than a clean end.
+ */
+export const open = <A, I>(
+  options: OpenOptions<A, I>,
+): Effect.Effect<WebSocketSession<A>, AiError.AiError, Scope.Scope | Socket.WebSocketConstructor> =>
+  Effect.gen(function* () {
+    const asAiError = toAiError(options.provider)
+    const decode = Schema.decodeUnknownEffect(options.schema)
+    const socket = yield* Socket.makeWebSocket(options.url, {
+      // Effect's Socket treats every close code as an error by default.
+      closeCodeIsError: (code) => code !== 1000 && code !== 1001 && code !== 1005,
+      ...(options.openTimeout !== undefined && { openTimeout: options.openTimeout }),
+    })
+    const frames = yield* Queue.bounded<A, AiError.AiError | Cause.Done>(options.capacity ?? 64)
+    const write = yield* socket.writer
+
+    const onFrame = (raw: string) =>
+      Effect.gen(function* () {
+        const json = yield* JSONL.parseSafe(raw)
+        if (json === undefined) return
+        const decoded = yield* decode(json).pipe(Effect.option)
+        if (Option.isNone(decoded)) {
+          yield* Effect.logDebug(`[${options.provider}] dropped frame`, { frame: json })
+          return
+        }
+        yield* Queue.offer(frames, decoded.value)
+      })
+
+    yield* socket.runString(onFrame).pipe(
+      Effect.mapError(asAiError),
+      // `Queue.end` on a clean close so the consumer drains what is queued;
+      // a failure must not arrive looking like the end of the conversation.
+      Effect.matchCauseEffect({
+        onFailure: (cause) =>
+          Cause.hasFails(cause) ? Queue.failCause(frames, cause) : Queue.end(frames),
+        onSuccess: () => Queue.end(frames),
+      }),
+      Effect.forkScoped,
+    )
+
+    return { send: (frame: string) => write(frame).pipe(Effect.mapError(asAiError)), frames }
+  })

package/src/testing/FakeWebSocket.ts

@@ -0,0 +1,120 @@
+/**
+ * An in-memory WebSocket for testing socket adapters without a server.
+ *
+ * Provide `layer` in place of the real `Socket.WebSocketConstructor` and the
+ * adapter runs end to end: its own connect, handshake, decode and teardown.
+ * The test plays the other end with `reply`, `push`, `close` and `sent`.
+ *
+ * Client frames land on a queue, so the scripted server is a forked fiber and
+ * `reply` is a real Effect. What stays imperative is the listener table the
+ * shim registers, since `Socket.makeWebSocket` drives it with plain callbacks.
+ * The shim is a plain object, so nothing here touches a platform global.
+ */
+import { Effect, Layer, Queue, Ref, type Scope, Stream } from "effect"
+import * as Socket from "effect/unstable/socket/Socket"
+
+export type FakeWebSocketServer = {
+  /** Every frame the client has sent, JSON-parsed, oldest first. */
+  readonly sent: Effect.Effect<ReadonlyArray<unknown>>
+  /** Deliver one frame to the client. */
+  readonly push: (frame: unknown) => Effect.Effect<void>
+  /** Close the socket. 1000, 1001 and 1005 are the clean codes. */
+  readonly close: (code?: number) => Effect.Effect<void>
+  /** Hand this to an adapter that takes a socket constructor directly. */
+  readonly connect: Socket.WebSocketConstructor["Service"]
+  /** Provide this in place of the real constructor. */
+  readonly layer: Layer.Layer<Socket.WebSocketConstructor>
+}
+
+export type FakeWebSocketOptions = {
+  /** Pushed once the client subscribes, for a protocol whose server speaks first. */
+  readonly greeting?: ReadonlyArray<unknown>
+  /** How the server answers each client frame. */
+  readonly reply?: (frame: unknown) => Effect.Effect<ReadonlyArray<unknown>>
+}
+
+type Listener = (event: any) => void
+
+const OPEN = 1
+const CLOSED = 3
+
+/** Run after the current call unwinds, so the client is never re-entered. */
+const soon = (run: () => void): void => void Promise.resolve().then(run)
+
+export const make = (
+  options?: FakeWebSocketOptions,
+): Effect.Effect<FakeWebSocketServer, never, Scope.Scope> =>
+  Effect.gen(function* () {
+    const inbound = yield* Queue.unbounded<unknown>()
+    const sent = yield* Ref.make<ReadonlyArray<unknown>>([])
+
+    const wiring = {
+      listeners: {} as Record<string, ReadonlyArray<Listener>>,
+      readyState: OPEN,
+      greeted: false,
+    }
+
+    const emit = (type: string, event: unknown): void =>
+      (wiring.listeners[type] ?? []).forEach((listener) => listener(event))
+
+    const deliverSync = (frames: ReadonlyArray<unknown>): void =>
+      frames.forEach((f) => emit("message", { data: JSON.stringify(f) }))
+
+    const deliver = (frames: ReadonlyArray<unknown>): Effect.Effect<void> =>
+      Effect.sync(() => deliverSync(frames))
+
+    const shutdown = (code: number): void => {
+      if (wiring.readyState === CLOSED) return
+      wiring.readyState = CLOSED
+      emit("close", { code, reason: "" })
+    }
+
+    // The scripted server. Answers land on their own turn, like a real one.
+    yield* Stream.fromQueue(inbound).pipe(
+      Stream.runForEach((frame) =>
+        Effect.gen(function* () {
+          yield* Ref.update(sent, (frames) => [...frames, frame])
+          const answer = yield* options?.reply?.(frame) ?? Effect.succeed([])
+          yield* deliver(answer)
+        }),
+      ),
+      Effect.forkScoped,
+    )
+
+    const socket = {
+      get readyState() {
+        return wiring.readyState
+      },
+      addEventListener: (type: string, fn: Listener): void => {
+        wiring.listeners = {
+          ...wiring.listeners,
+          [type]: [...(wiring.listeners[type] ?? []), fn],
+        }
+        // The greeting waits for a subscriber before it lands.
+        if (type === "message" && !wiring.greeted) {
+          wiring.greeted = true
+          soon(() => deliverSync(options?.greeting ?? []))
+        }
+      },
+      removeEventListener: (type: string, fn: Listener): void => {
+        wiring.listeners = {
+          ...wiring.listeners,
+          [type]: (wiring.listeners[type] ?? []).filter((l) => l !== fn),
+        }
+      },
+      // Safe from a synchronous callback, and no runtime needed.
+      send: (data: string): void => void Queue.offerUnsafe(inbound, JSON.parse(data)),
+      close: (code = 1000): void => shutdown(code),
+    }
+
+    const connect: Socket.WebSocketConstructor["Service"] = () =>
+      socket as unknown as globalThis.WebSocket
+
+    return {
+      sent: Ref.get(sent),
+      push: (frame) => deliver([frame]),
+      close: (code = 1000) => Effect.sync(() => shutdown(code)),
+      connect,
+      layer: Layer.succeed(Socket.WebSocketConstructor, connect),
+    }
+  })

package/src/testing/MockMessenger.ts

@@ -0,0 +1,147 @@
+import { Array as Arr, Data, Effect, Layer, Option, Ref, Stream } from "effect"
+import {
+  type ConversationRef,
+  CurrentConversation,
+  type InboundEvent,
+  MessageId,
+  type MessageRef,
+  Messenger,
+  type MessengerLimits,
+  type MessengerService,
+  type Outbound,
+} from "../messenger/Messenger.js"
+import {
+  type StreamViaEditsOptions,
+  splitForLimit,
+  streamViaEdits,
+} from "../messenger/MessengerAdapter.js"
+import * as MessengerError from "../messenger/MessengerError.js"
+
+// ---------------------------------------------------------------------------
+// Call log
+// ---------------------------------------------------------------------------
+
+/**
+ * One entry per outbound call. `Post` is logged once even when the text was
+ * long enough to split, so a caller that rolled over on its own is
+ * distinguishable from one that leaned on `post` to do it.
+ */
+export type Call = Data.TaggedEnum<{
+  Post: { readonly conversation: ConversationRef; readonly message: Outbound }
+  Edit: { readonly message: MessageRef; readonly next: Outbound }
+  React: { readonly message: MessageRef; readonly emoji: string }
+  TypingStart: { readonly conversation: ConversationRef }
+  TypingStop: { readonly conversation: ConversationRef }
+}>
+
+export const Call = Data.taggedEnum<Call>()
+
+export type MockMessengerRecorder = {
+  readonly calls: ReadonlyArray<Call>
+}
+
+// ---------------------------------------------------------------------------
+// Script
+// ---------------------------------------------------------------------------
+
+export type MockMessengerScript = {
+  /** Inbound events to replay. Empty by default. */
+  readonly events?: Stream.Stream<InboundEvent, MessengerError.MessengerError>
+  readonly limits?: MessengerLimits
+  /**
+   * Failures handed back one per `post` / `edit` call, in order; `undefined`
+   * entries succeed, and everything past the end succeeds.
+   */
+  readonly failures?: ReadonlyArray<MessengerError.MessengerError | undefined>
+  /** Passed through to `streamViaEdits`, which backs `stream`. */
+  readonly streamOptions?: StreamViaEditsOptions
+}
+
+const defaultLimits: MessengerLimits = { maxText: 4096, maxCaption: 1024 }
+
+const bodyText = (msg: Outbound): Option.Option<string> =>
+  msg.body._tag === "Text" ? Option.some(msg.body.text) : Option.none()
+
+// ---------------------------------------------------------------------------
+// Service builder
+// ---------------------------------------------------------------------------
+
+const buildService = (
+  script: MockMessengerScript,
+  record: (call: Call) => Effect.Effect<void>,
+  cursor: Ref.Ref<number>,
+  minted: Ref.Ref<number>,
+): MessengerService => {
+  const limits = script.limits ?? defaultLimits
+
+  const nextFailure = Ref.getAndUpdate(cursor, (n) => n + 1).pipe(
+    Effect.flatMap((i) =>
+      Option.match(Option.fromNullishOr((script.failures ?? [])[i]), {
+        onNone: () => Effect.void,
+        onSome: Effect.fail<MessengerError.MessengerError>,
+      }),
+    ),
+  )
+
+  const mint = Ref.updateAndGet(minted, (n) => n + 1).pipe(Effect.map((n) => MessageId(`m${n}`)))
+
+  const post: MessengerService["post"] = (msg) =>
+    Effect.gen(function* () {
+      const conversation = yield* CurrentConversation
+      yield* record(Call.Post({ conversation, message: msg }))
+      yield* nextFailure
+      // One id per chunk, mirroring an adapter that splits at the ceiling.
+      const chunks = Option.match(bodyText(msg), {
+        onNone: () => 1,
+        onSome: (t) => splitForLimit(t, limits.maxText).length,
+      })
+      return yield* Effect.map(
+        Effect.forEach(Arr.range(1, chunks), () => mint),
+        Arr.lastNonEmpty,
+      )
+    })
+
+  const edit: MessengerService["edit"] = (msg, next) =>
+    record(Call.Edit({ message: msg, next })).pipe(Effect.andThen(nextFailure))
+
+  return {
+    events: script.events ?? Stream.empty,
+    post,
+    edit,
+    react: (msg, emoji) => record(Call.React({ message: msg, emoji })),
+    typing: Effect.gen(function* () {
+      const conversation = yield* CurrentConversation
+      yield* record(Call.TypingStart({ conversation }))
+      yield* Effect.addFinalizer(() => record(Call.TypingStop({ conversation })))
+    }),
+    stream: streamViaEdits({ post, edit, limits }, script.streamOptions),
+    limits,
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+const makeUnsafe = (script: MockMessengerScript) => {
+  const calls = Ref.makeUnsafe<ReadonlyArray<Call>>([])
+  const service = buildService(
+    script,
+    (call) => Ref.update(calls, Arr.append(call)),
+    Ref.makeUnsafe(0),
+    Ref.makeUnsafe(0),
+  )
+  return {
+    service,
+    recorder: Ref.get(calls).pipe(Effect.map((c): MockMessengerRecorder => ({ calls: c }))),
+  }
+}
+
+/** Layer registering the mock against the `Messenger` tag, plus its recorder. */
+export const layer = (script: MockMessengerScript = {}) => {
+  const { service, recorder } = makeUnsafe(script)
+  return { layer: Layer.succeed(Messenger, service), recorder }
+}
+
+/** Bare service value + recorder. Use with `Effect.provideService`. */
+export const make = (script: MockMessengerScript = {}) => makeUnsafe(script)