@effect-uai/core 0.1.0

package/src/loop/Loop.ts

@@ -0,0 +1,295 @@
+/**
+ * Pull-based `loop` for state-threaded sub-streams.
+ *
+ * Each iteration runs a body that returns a `Stream<Event<A, S>>`. The body
+ * emits values via `Loop.value(a)` and signals iteration control via
+ * `Loop.next(state)` (continue with new state) or `Loop.stop` (terminate).
+ * The loop unwraps `Value` events back to `A` for downstream consumers, so
+ * the resulting stream is a plain `Stream<A>`.
+ *
+ * The next body stream is only pulled when downstream pulls the outer
+ * stream - no producer fiber, no queue buffering. Cancellation, failures,
+ * scoped resources, and backpressure stay aligned with normal Stream
+ * semantics.
+ *
+ * Convention: a `Next` or `Stop` event is the terminal element of a body's
+ * iteration. Values emitted in the same chunk after one are discarded
+ * (their producing side effects may already have run). Prefer the
+ * `Loop.nextAfter` / `Loop.stopAfter` helpers to terminate cleanly.
+ */
+import { Cause, Channel, Data, Effect, Exit, Function, Option, Ref, Scope, Stream } from "effect"
+import { IncompleteTurn } from "../domain/AiError.js"
+import { isTurnComplete, type Turn, type TurnEvent } from "../domain/Turn.js"
+
+// ---------------------------------------------------------------------------
+// Event type - the body's emit shape
+// ---------------------------------------------------------------------------
+
+/**
+ * The tagged union a body emits per pull. `Value` carries a payload that
+ * flows downstream. `Next` ends the current iteration and continues with a
+ * new state. `Stop` ends the loop entirely.
+ */
+export type Event<A, S> = Data.TaggedEnum<{
+  Value: { readonly value: A }
+  Next: { readonly state: S }
+  Stop: {}
+}>
+
+interface EventDef extends Data.TaggedEnum.WithGenerics<2> {
+  readonly taggedEnum: Event<this["A"], this["B"]>
+}
+
+const Event = Data.taggedEnum<EventDef>()
+
+/** Wrap a value so it flows through the loop to downstream consumers. */
+export const value = <A>(a: A): Event<A, never> => Event.Value({ value: a })
+
+/** End the current iteration and continue with a new state. */
+export const next = <S>(state: S): Event<never, S> => Event.Next({ state })
+
+/** The terminal `Stop` event. Use `stop` (the Stream) to end a loop body. */
+export const stopEvent: Event<never, never> = Event.Stop()
+
+/**
+ * A single-element stream that ends the loop. Return this from a body when
+ * there's nothing else to emit; equivalent to `stopAfter(Stream.empty)` but
+ * named for the common case.
+ */
+export const stop: Stream.Stream<Event<never, never>> = Stream.succeed(stopEvent)
+
+/**
+ * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the
+ * iteration with `next(state)`. Common shape for "stream this turn's
+ * deltas, then continue with updated history."
+ */
+export const nextAfter = <S, A, E, R>(
+  stream: Stream.Stream<A, E, R>,
+  state: S,
+): Stream.Stream<Event<A, S>, E, R> =>
+  Stream.concat(Stream.map(stream, value), Stream.fromIterable([next(state)]))
+
+/**
+ * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the
+ * loop. Common shape for "stream this turn's deltas, then we're done."
+ */
+export const stopAfter = <A, E, R>(
+  stream: Stream.Stream<A, E, R>,
+): Stream.Stream<Event<A, never>, E, R> =>
+  Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopEvent]))
+
+/**
+ * General `nextAfter` variant: drain `stream` to the consumer, fold elements
+ * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.
+ *
+ * Subsumes `nextAfter` when state is constant (`reduce: (s, _) => s`,
+ * `build: (s) => s`). Used by `Toolkit.nextStateFrom` to collect tool
+ * results and build next state without exposing a Ref to recipes.
+ */
+export const nextAfterFold = <A, B, S, E, R>(
+  stream: Stream.Stream<A, E, R>,
+  initial: B,
+  reduce: (acc: B, a: A) => B,
+  build: (b: B) => S,
+): Stream.Stream<Event<A, S>, E, R> =>
+  Stream.unwrap(
+    Effect.gen(function* () {
+      const ref = yield* Ref.make(initial)
+      const tapped = stream.pipe(
+        Stream.tap((a) => Ref.update(ref, (acc) => reduce(acc, a))),
+        Stream.map(value),
+      )
+      const continuation = Stream.fromEffect(
+        Ref.get(ref).pipe(Effect.map((acc) => next(build(acc)))),
+      )
+      return tapped.pipe(Stream.concat(continuation))
+    }),
+  )
+
+// ---------------------------------------------------------------------------
+// streamUntilComplete - turn-aware stream operator for loop bodies
+// ---------------------------------------------------------------------------
+
+/**
+ * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.
+ * Each delta passes through as `value(delta)` (including the terminal
+ * `turn_complete`, so the consumer sees turn boundaries naturally). Once
+ * the terminal arrives, `then(turn)` runs and its returned stream of loop
+ * events (typically tool outputs followed by `next(state)` or `stop`) is
+ * concatenated.
+ *
+ * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on
+ * the raw delta stream cover anything an `emit`-style callback would do.
+ *
+ * If the upstream ends without a `turn_complete`, the resulting stream
+ * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if
+ * you want to recover.
+ */
+export const streamUntilComplete =
+  <S, A, E2 = never, R2 = never>(
+    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,
+  ) =>
+  <E, R>(
+    deltas: Stream.Stream<TurnEvent, E, R>,
+  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>
+    Stream.unwrap(
+      Effect.gen(function* () {
+        const turnRef = yield* Ref.make<Option.Option<Turn>>(Option.none())
+
+        const events: Stream.Stream<Event<TurnEvent, S>, E, R> = deltas.pipe(
+          Stream.tap((delta) =>
+            isTurnComplete(delta) ? Ref.set(turnRef, Option.some(delta.turn)) : Effect.void,
+          ),
+          Stream.map(value),
+        )
+
+        const continuation = Stream.unwrap(
+          Effect.gen(function* () {
+            const opt = yield* Ref.get(turnRef)
+            if (Option.isNone(opt)) return yield* Effect.fail(new IncompleteTurn({}))
+            return yield* then(opt.value)
+          }),
+        )
+
+        return Stream.concat(events, continuation)
+      }),
+    )
+
+// ---------------------------------------------------------------------------
+// Internal helpers
+// ---------------------------------------------------------------------------
+
+const isNonEmpty = <A>(array: ReadonlyArray<A>): array is readonly [A, ...Array<A>] =>
+  array.length > 0
+
+interface CurrentBody<S, A, E, R> {
+  readonly scope: Scope.Closeable
+  readonly pull: Effect.Effect<ReadonlyArray<Event<A, S>>, E | Cause.Done<void>, R>
+}
+
+const closeBody = <S, A, E, R>(
+  current: CurrentBody<S, A, E, R>,
+  exit: Exit.Exit<unknown, unknown>,
+) => Scope.close(current.scope, exit)
+
+/**
+ * Walk a chunk of `Event<A, S>` until a terminal `Next` or `Stop` is found.
+ * Returns the unwrapped values seen so far and (optionally) the terminal
+ * event. Anything in the chunk after the terminal is discarded - its
+ * producing side effects may have run, but downstream never sees it.
+ */
+const partitionChunk = <A, S>(
+  chunk: ReadonlyArray<Event<A, S>>,
+): { readonly values: Array<A>; readonly decision: Event<A, S> | undefined } => {
+  const values: Array<A> = []
+  for (let i = 0; i < chunk.length; i++) {
+    const event = chunk[i]!
+    if (event._tag === "Value") {
+      values.push(event.value)
+    } else {
+      return { values, decision: event }
+    }
+  }
+  return { values, decision: undefined }
+}
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+type LoopBody<S, A, E, R> = (
+  state: S,
+) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>
+
+/**
+ * Drive a state-threaded loop body. Each iteration runs `body(state)` to get
+ * a `Stream<Event<A, S>>`; values flow downstream, `next(s)` continues with
+ * a new state, `stop` ends the loop. See the file header for the full
+ * pull-based execution model.
+ *
+ * Dual: data-first `loop(initial, body)` and data-last `loop(body)(initial)`
+ * (or `pipe(initial, loop(body))`) both work.
+ */
+export const loop: {
+  <S, A, E, R>(body: LoopBody<S, A, E, R>): (initial: S) => Stream.Stream<A, E, R>
+  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R>
+} = Function.dual(
+  2,
+  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R> =>
+    Stream.scoped(
+      Stream.fromPull(
+        Effect.gen(function* () {
+          const outerScope = yield* Effect.scope
+          let state = initial
+          let current: CurrentBody<S, A, E, R> | undefined
+          let done = false
+
+          const closeActive = (
+            active: CurrentBody<S, A, E, R>,
+            exit: Exit.Exit<unknown, unknown>,
+          ) => {
+            const isActive = current === active
+            if (isActive) current = undefined
+            // Scope.close is idempotent. Multiple paths can race to close the
+            // active body during cancellation/failure, so closing twice is safe.
+            return closeBody(active, exit)
+          }
+
+          yield* Scope.addFinalizerExit(outerScope, (exit) =>
+            current === undefined ? Effect.void : closeActive(current, exit),
+          )
+
+          const pull = Effect.gen(function* () {
+            while (true) {
+              if (done) return yield* Cause.done()
+
+              if (current === undefined) {
+                const result = body(state)
+                const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result
+                const bodyScope = yield* Scope.fork(outerScope)
+                const bodyPull = yield* Channel.toPullScoped(
+                  Stream.toChannel(stream),
+                  bodyScope,
+                ).pipe(Effect.onError((cause) => Scope.close(bodyScope, Exit.failCause(cause))))
+                current = { scope: bodyScope, pull: bodyPull }
+              }
+
+              const active = current
+              const chunk = yield* active.pull.pipe(
+                Effect.catchIf(Cause.isDone, () =>
+                  closeActive(active, Exit.void).pipe(
+                    Effect.as(undefined as ReadonlyArray<Event<A, S>> | undefined),
+                  ),
+                ),
+                Effect.onError((cause) => closeActive(active, Exit.failCause(cause))),
+              )
+
+              if (chunk === undefined) {
+                done = true
+                return yield* Cause.done()
+              }
+
+              const { values, decision } = partitionChunk(chunk)
+
+              if (decision !== undefined) {
+                yield* closeActive(active, Exit.void)
+                if (decision._tag === "Stop") {
+                  done = true
+                } else if (decision._tag === "Next") {
+                  state = decision.state
+                }
+              }
+
+              // Emit the values seen so far if any. Chunks from a Stream pull
+              // are non-empty, so when `decision === undefined` every event was
+              // a `Value` and `values` is non-empty here. With a decision and
+              // no preceding values, fall through to the next iteration.
+              if (isNonEmpty(values)) return values
+            }
+          })
+
+          return pull
+        }),
+      ),
+    ),
+)

package/src/match/Match.ts

@@ -0,0 +1,9 @@
+import { Match } from "effect"
+
+/**
+ * Dispatch on the `type` discriminator of a tagged union. Equivalent to
+ * `Match.discriminator("type")`, exposed as a named helper because the
+ * `type` field is the framework's convention for `Item`, `TurnEvent`,
+ * `ContentBlock`, and most provider wire types.
+ */
+export const matchType = Match.discriminator("type")

package/src/observability/Metrics.ts

@@ -0,0 +1,87 @@
+import { Clock, Duration, Effect, Option, Stream } from "effect"
+
+/**
+ * Annotate every event in a stream with the elapsed `Duration` since the
+ * stream started consuming. The first event reports its time-from-start,
+ * which is also the conventional "time to first ____" metric.
+ */
+export const withElapsed = <A, E, R>(
+  self: Stream.Stream<A, E, R>,
+): Stream.Stream<{ readonly value: A; readonly elapsed: Duration.Duration }, E, R> =>
+  Stream.unwrap(
+    Effect.map(Clock.currentTimeMillis, (start) =>
+      self.pipe(
+        Stream.mapEffect((value) =>
+          Effect.map(Clock.currentTimeMillis, (now) => ({
+            value,
+            elapsed: Duration.millis(now - start),
+          })),
+        ),
+      ),
+    ),
+  )
+
+/**
+ * Compute the elapsed time until the first event matching the predicate.
+ * Returns `Option.none()` if the stream completes without one.
+ *
+ * Consumes the stream. To track this *alongside* live consumption, use
+ * `Stream.broadcast` to fan the source out and run `timeToFirst` on one
+ * branch.
+ */
+export const timeToFirst =
+  <A>(predicate: (a: A) => boolean) =>
+  <E, R>(self: Stream.Stream<A, E, R>): Effect.Effect<Option.Option<Duration.Duration>, E, R> =>
+    withElapsed(self).pipe(
+      Stream.filter(({ value }) => predicate(value)),
+      Stream.runHead,
+      Effect.map(Option.map(({ elapsed }) => elapsed)),
+    )
+
+export interface RatePoint<A> {
+  readonly value: A
+  readonly total: number
+  readonly ratePerSecond: number
+  readonly elapsed: Duration.Duration
+}
+
+/**
+ * Annotate every event with a running total and a rolling rate per second,
+ * computed from a user-supplied weight function.
+ *
+ * The weight is the unit you care about - bytes, tokens, error count, etc.
+ * For tokens-per-second on `TurnEvent`, pass:
+ *
+ *   `(d) => d.type === "text_delta" ? countTokens(d.text) : 0`
+ *
+ * Use any tokenizer you like; the library does not ship one.
+ */
+export const withRate =
+  <A>(weight: (a: A) => number) =>
+  <E, R>(self: Stream.Stream<A, E, R>): Stream.Stream<RatePoint<A>, E, R> =>
+    Stream.unwrap(
+      Effect.map(Clock.currentTimeMillis, (start) =>
+        self.pipe(
+          Stream.mapAccumEffect(
+            () => ({ total: 0 }),
+            (acc, value) =>
+              Effect.map(Clock.currentTimeMillis, (now) => {
+                const total = acc.total + weight(value)
+                const elapsedMs = now - start
+                const ratePerSecond = elapsedMs > 0 ? (total / elapsedMs) * 1000 : 0
+                return [
+                  { total },
+                  [
+                    {
+                      value,
+                      total,
+                      ratePerSecond,
+                      elapsed: Duration.millis(elapsedMs),
+                    } satisfies RatePoint<A>,
+                  ],
+                ] as const
+              }),
+          ),
+        ),
+      ),
+    )

package/src/streaming/JSONL.test.ts

@@ -0,0 +1,85 @@
+import { Effect, Result, Schema, Stream } from "effect"
+import { describe, expect, it } from "vitest"
+import * as JSONL from "./JSONL.js"
+
+const enc = new TextEncoder()
+const bytesOf = (...chunks: ReadonlyArray<string>) =>
+  Stream.fromIterable(chunks.map((c) => enc.encode(c)))
+
+const collect = <A, E>(s: Stream.Stream<A, E>) => Effect.runPromise(Stream.runCollect(s))
+
+const collectResult = <A, E>(s: Stream.Stream<A, E>) =>
+  Effect.runPromise(Effect.result(Stream.runCollect(s)))
+
+const Patch = Schema.Struct({ op: Schema.String, value: Schema.Number })
+
+describe("JSONL.fromBytes", () => {
+  it("emits one string per line", async () => {
+    const out = await collect(JSONL.fromBytes(bytesOf("a\nb\nc\n")))
+    expect(out).toEqual(["a", "b", "c"])
+  })
+
+  it("buffers lines across chunk boundaries", async () => {
+    const out = await collect(JSONL.fromBytes(bytesOf("ab", "c\nde", "f\n")))
+    expect(out).toEqual(["abc", "def"])
+  })
+
+  it("flushes a trailing line without a final newline", async () => {
+    const out = await collect(JSONL.fromBytes(bytesOf("a\nb")))
+    expect(out).toEqual(["a", "b"])
+  })
+
+  it("ignores blank lines", async () => {
+    const out = await collect(JSONL.fromBytes(bytesOf("a\n\n\nb\n")))
+    expect(out).toEqual(["a", "b"])
+  })
+})
+
+describe("JSONL.parse", () => {
+  it("decodes well-formed JSON lines through a Schema", async () => {
+    const out = await collect(
+      bytesOf(`{"op":"add","value":1}\n{"op":"sub","value":2}\n`).pipe(
+        JSONL.fromBytes,
+        JSONL.parse(Patch),
+      ),
+    )
+    expect(out).toEqual([
+      { op: "add", value: 1 },
+      { op: "sub", value: 2 },
+    ])
+  })
+
+  it("fails with JsonParseError on malformed JSON", async () => {
+    const result = await collectResult(
+      bytesOf(`{"op":"add","value":1}\nNOT_JSON\n`).pipe(JSONL.fromBytes, JSONL.parse(Patch)),
+    )
+    expect(Result.isFailure(result)).toBe(true)
+    if (Result.isFailure(result)) {
+      expect(result.failure._tag).toBe("JsonParseError")
+      expect(result.failure.line).toBe("NOT_JSON")
+    }
+  })
+
+  it("fails with JsonParseError on schema mismatch", async () => {
+    const result = await collectResult(
+      bytesOf(`{"op":"add","value":"not a number"}\n`).pipe(JSONL.fromBytes, JSONL.parse(Patch)),
+    )
+    expect(Result.isFailure(result)).toBe(true)
+    if (Result.isFailure(result)) {
+      expect(result.failure._tag).toBe("JsonParseError")
+    }
+  })
+})
+
+describe("JSONL round-trip", () => {
+  it("toBytes then fromBytes/parse recovers the values", async () => {
+    const values = [
+      { op: "a", value: 1 },
+      { op: "b", value: 2 },
+    ]
+    const out = await collect(
+      Stream.fromIterable(values).pipe(JSONL.toBytes(Patch), JSONL.fromBytes, JSONL.parse(Patch)),
+    )
+    expect(out).toEqual(values)
+  })
+})

package/src/streaming/JSONL.ts

@@ -0,0 +1,96 @@
+import { Data, Effect, Schema, Stream } from "effect"
+
+export class JsonParseError extends Data.TaggedError("JsonParseError")<{
+  readonly line: string
+  readonly cause: unknown
+}> {}
+
+// ---------------------------------------------------------------------------
+// Generic stream helpers (kept module-local; see SSE.ts for the same shape).
+// ---------------------------------------------------------------------------
+
+const decodeText = <E, R>(self: Stream.Stream<Uint8Array, E, R>): Stream.Stream<string, E, R> =>
+  self.pipe(
+    Stream.mapAccum(
+      (): TextDecoder => new TextDecoder("utf-8"),
+      (decoder, chunk: Uint8Array) => [decoder, [decoder.decode(chunk, { stream: true })]] as const,
+      {
+        onHalt: (decoder: TextDecoder) => {
+          const tail = decoder.decode()
+          return tail.length > 0 ? [tail] : []
+        },
+      },
+    ),
+  )
+
+const splitOn =
+  (separator: string) =>
+  <E, R>(self: Stream.Stream<string, E, R>): Stream.Stream<string, E, R> =>
+    self.pipe(
+      Stream.mapAccum(
+        (): string => "",
+        (buffer, chunk: string) => {
+          const parts = (buffer + chunk).split(separator)
+          const tail = parts[parts.length - 1] ?? ""
+          return [tail, parts.slice(0, -1)] as const
+        },
+        { onHalt: (tail: string) => (tail.length > 0 ? [tail] : []) },
+      ),
+    )
+
+// ---------------------------------------------------------------------------
+// Public API
+// ---------------------------------------------------------------------------
+
+/**
+ * Decode a `Stream<Uint8Array>` into a `Stream<string>` of newline-delimited
+ * lines. Empty lines are skipped. Buffers across chunk boundaries.
+ */
+export const fromBytes = <E, R>(
+  self: Stream.Stream<Uint8Array, E, R>,
+): Stream.Stream<string, E, R> =>
+  self.pipe(
+    decodeText,
+    Stream.map((s) => s.replace(/\r/g, "")),
+    splitOn("\n"),
+    Stream.filter((line) => line.length > 0),
+  )
+
+/**
+ * Validate each JSONL line against a Schema. JSON parse errors and Schema
+ * decode errors both surface as a `JsonParseError` so callers can `catchTag`
+ * uniformly.
+ */
+export const parse =
+  <A, I>(schema: Schema.Codec<A, I>) =>
+  <E, R>(self: Stream.Stream<string, E, R>): Stream.Stream<A, JsonParseError | E, R> =>
+    self.pipe(
+      Stream.mapEffect((line) =>
+        Effect.try({
+          try: () => JSON.parse(line) as unknown,
+          catch: (cause) => new JsonParseError({ line, cause }),
+        }).pipe(
+          Effect.flatMap((value) =>
+            Schema.decodeUnknownEffect(schema)(value).pipe(
+              Effect.mapError((cause) => new JsonParseError({ line, cause })),
+            ),
+          ),
+        ),
+      ),
+    )
+
+const encoder = new TextEncoder()
+
+/**
+ * Serialize a stream of values to JSONL bytes. Encodes each value via
+ * `Schema.encodeUnknownSync`. Each line ends with `\n`.
+ */
+export const toBytes =
+  <A, I>(schema: Schema.Codec<A, I>) =>
+  <E, R>(self: Stream.Stream<A, E, R>): Stream.Stream<Uint8Array, E, R> =>
+    self.pipe(
+      Stream.map((value) => {
+        const encoded = Schema.encodeUnknownSync(schema)(value)
+        return encoder.encode(JSON.stringify(encoded) + "\n")
+      }),
+    )

package/src/streaming/Lines.ts

@@ -0,0 +1,34 @@
+import { Stream } from "effect"
+
+/**
+ * Split a string stream on `\n`, emitting one line per element. Buffers
+ * partial chunks until a newline arrives, and flushes any non-newline
+ * tail at stream end - so streams that don't terminate with `\n`
+ * (typical of LLM token streams) still get their last line. Empty lines
+ * are dropped, `\r` is stripped (handles `\r\n` endings).
+ *
+ * Intended use: feed text deltas from a model that has been prompted to
+ * emit JSONL (or any other newline-delimited format), then parse /
+ * validate each emitted line.
+ */
+export const lines = <E, R>(self: Stream.Stream<string, E, R>): Stream.Stream<string, E, R> =>
+  linesStrict(Stream.concat(self, Stream.make("\n")))
+
+/**
+ * Like `lines`, but only emits lines that were terminated by `\n`. Any
+ * partial trailing content is dropped at stream end. Use when you want
+ * strict "complete-line-or-nothing" semantics.
+ */
+export const linesStrict = <E, R>(self: Stream.Stream<string, E, R>): Stream.Stream<string, E, R> =>
+  self.pipe(
+    Stream.mapAccum(
+      (): string => "",
+      (buffer, chunk: string) => {
+        const combined = buffer + chunk
+        const parts = combined.split("\n")
+        const tail = parts.pop() ?? ""
+        return [tail, parts.map((line) => line.replace(/\r/g, ""))] as const
+      },
+    ),
+    Stream.filter((line) => line.trim().length > 0),
+  )

package/src/streaming/SSE.test.ts

@@ -0,0 +1,72 @@
+import { Effect, Stream } from "effect"
+import { describe, expect, it } from "vitest"
+import * as SSE from "./SSE.js"
+
+const enc = new TextEncoder()
+const bytesOf = (...chunks: ReadonlyArray<string>) =>
+  Stream.fromIterable(chunks.map((c) => enc.encode(c)))
+
+const collect = <A, E>(s: Stream.Stream<A, E>) => Effect.runPromise(Stream.runCollect(s))
+
+describe("SSE.fromBytes", () => {
+  it("parses a single complete event", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf("event: foo\ndata: hello\n\n")))
+    expect(out).toEqual([{ event: "foo", data: "hello" }])
+  })
+
+  it("joins multiple data lines with \\n", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf("data: line1\ndata: line2\ndata: line3\n\n")))
+    expect(out).toEqual([{ data: "line1\nline2\nline3" }])
+  })
+
+  it("handles events split across chunk boundaries", async () => {
+    const out = await collect(
+      SSE.fromBytes(bytesOf("event: split\nda", "ta: hi\n", "\nevent: next\ndata: x\n\n")),
+    )
+    expect(out).toEqual([
+      { event: "split", data: "hi" },
+      { event: "next", data: "x" },
+    ])
+  })
+
+  it("handles CRLF line endings", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf("event: a\r\ndata: b\r\n\r\n")))
+    expect(out).toEqual([{ event: "a", data: "b" }])
+  })
+
+  it("preserves id and skips comment lines", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf(": ping\nid: 42\ndata: x\n\n")))
+    expect(out).toEqual([{ id: "42", data: "x" }])
+  })
+
+  it("flushes a trailing event without a closing blank line", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf("data: tail")))
+    expect(out).toEqual([{ data: "tail" }])
+  })
+
+  it("ignores empty blocks between events", async () => {
+    const out = await collect(SSE.fromBytes(bytesOf("data: a\n\n\n\ndata: b\n\n")))
+    expect(out).toEqual([{ data: "a" }, { data: "b" }])
+  })
+
+  it("handles a UTF-8 multi-byte char split across chunks", async () => {
+    // "🦑" is 0xF0 0x9F 0xA6 0x91. Split between bytes 2 and 3.
+    const squidBytes = enc.encode("data: 🦑\n\n")
+    const a = squidBytes.slice(0, 8) // "data: " + first 2 bytes of squid
+    const b = squidBytes.slice(8) // remaining squid bytes + "\n\n"
+    const out = await collect(SSE.fromBytes(Stream.fromIterable([a, b])))
+    expect(out).toEqual([{ data: "🦑" }])
+  })
+})
+
+describe("SSE.toBytes round-trip", () => {
+  it("re-parses what it serializes", async () => {
+    const events: ReadonlyArray<SSE.Event> = [
+      { event: "a", data: "hello" },
+      { data: "multi\nline" },
+      { event: "b", id: "7", data: "x" },
+    ]
+    const reparsed = await collect(Stream.fromIterable(events).pipe(SSE.toBytes, SSE.fromBytes))
+    expect(reparsed).toEqual(events)
+  })
+})