@effect-uai/core 0.1.0 → 0.3.0

package/src/domain/Image.ts

@@ -0,0 +1,75 @@
+import { Schema } from "effect"
+import type { MediaBase64, MediaBytes, MediaSource, MediaUrl } from "./Media.js"
+
+/**
+ * Image MIME types AI providers typically accept. The first four are the
+ * universal subset (Cohere v4, Voyage multimodal, Jina v4, Google
+ * `gemini-embedding-2`); HEIC / HEIF are Google-specific. The
+ * `(string & {})` tail keeps autocomplete on the literals while still
+ * accepting any string, so a newly-supported format works without an
+ * SDK update.
+ */
+export type ImageMimeType =
+  | "image/png"
+  | "image/jpeg"
+  | "image/webp"
+  | "image/gif"
+  | "image/heic"
+  | "image/heif"
+  // eslint-disable-next-line @typescript-eslint/ban-types
+  | (string & {})
+
+const ImageMimeTypeSchema = Schema.String as unknown as Schema.Schema<ImageMimeType>
+
+export type ImageUrlSource = MediaUrl<ImageMimeType>
+export type ImageBase64Source = MediaBase64<ImageMimeType>
+export type ImageBytesSource = MediaBytes<ImageMimeType>
+
+/**
+ * Where an image lives. Provider layers normalize across these:
+ * `bytes` becomes a base64 data URI for OpenAI / Anthropic, an
+ * `inlineData` part for Gemini, and a separate field for Cohere /
+ * Voyage. URL constraints (must be HTTPS, must be public, …) are
+ * provider-specific and validated at the layer, not in the type.
+ */
+export type ImageSource = MediaSource<ImageMimeType>
+
+export const ImageUrlSource = Schema.TaggedStruct("url", {
+  url: Schema.String,
+  mimeType: Schema.optional(ImageMimeTypeSchema),
+})
+
+export const ImageBase64Source = Schema.TaggedStruct("base64", {
+  base64: Schema.String,
+  mimeType: ImageMimeTypeSchema,
+})
+
+export const ImageBytesSource = Schema.TaggedStruct("bytes", {
+  bytes: Schema.Uint8Array,
+  mimeType: ImageMimeTypeSchema,
+})
+
+export const ImageSource: Schema.Schema<ImageSource> = Schema.Union([
+  ImageUrlSource,
+  ImageBase64Source,
+  ImageBytesSource,
+]) as unknown as Schema.Schema<ImageSource>
+
+export const imageUrl = (url: string, mimeType?: ImageMimeType): ImageUrlSource =>
+  mimeType !== undefined ? { _tag: "url", url, mimeType } : { _tag: "url", url }
+
+export const imageBase64 = (base64: string, mimeType: ImageMimeType): ImageBase64Source => ({
+  _tag: "base64",
+  base64,
+  mimeType,
+})
+
+export const imageBytes = (bytes: Uint8Array, mimeType: ImageMimeType): ImageBytesSource => ({
+  _tag: "bytes",
+  bytes,
+  mimeType,
+})
+
+export const isImageUrl = Schema.is(ImageUrlSource)
+export const isImageBase64 = Schema.is(ImageBase64Source)
+export const isImageBytes = Schema.is(ImageBytesSource)

package/src/domain/Items.ts

@@ -1,4 +1,5 @@
 import { Schema } from "effect"
+import { ImageSource } from "./Image.js"
 
 // ---------------------------------------------------------------------------
 // Content blocks (inside Message.content)
@@ -10,39 +11,13 @@ export const InputText = Schema.Struct({
 })
 export type InputText = typeof InputText.Type
 
-/**
- * Where an image lives. `url` covers HTTP(S) URLs (the model fetches
- * them); `base64` covers inline bytes embedded in the request. Provider
- * encoders dispatch on `_tag`. File-id / uploaded-asset references are
- * provider-specific and stay out of this union for now.
- */
-export const ImageUrlSource = Schema.Struct({
-  _tag: Schema.Literal("url"),
-  url: Schema.String,
-})
-export type ImageUrlSource = typeof ImageUrlSource.Type
-
-/**
- * Inline image bytes. `data` is **already base64-encoded** (matches what
- * the wire formats expect; no double-encoding needed downstream).
- * `media_type` is the MIME type, e.g. `"image/png"`.
- */
-export const ImageBase64Source = Schema.Struct({
-  _tag: Schema.Literal("base64"),
-  media_type: Schema.String,
-  data: Schema.String,
-})
-export type ImageBase64Source = typeof ImageBase64Source.Type
-
-export const ImageSource = Schema.Union([ImageUrlSource, ImageBase64Source])
-export type ImageSource = typeof ImageSource.Type
-
-export const isImageUrlSource = (s: ImageSource): s is ImageUrlSource => s._tag === "url"
-export const isImageBase64Source = (s: ImageSource): s is ImageBase64Source => s._tag === "base64"
-
 /**
  * User-provided image content block. Pair with `InputText` inside a
  * `Message.content` array to ask "what's in this image?" style questions.
+ *
+ * `source` is the cross-modality `ImageSource` from `domain/Image.ts` -
+ * url, base64, or raw bytes. Provider codecs encode bytes to whatever
+ * wire format the provider wants.
  */
 export const InputImage = Schema.Struct({
   type: Schema.Literal("input_image"),
@@ -91,11 +66,10 @@ export type FilePath = typeof FilePath.Type
 export const Annotation = Schema.Union([UrlCitation, FileCitation, ContainerFileCitation, FilePath])
 export type Annotation = typeof Annotation.Type
 
-export const isUrlCitation = (a: Annotation): a is UrlCitation => a.type === "url_citation"
-export const isFileCitation = (a: Annotation): a is FileCitation => a.type === "file_citation"
-export const isContainerFileCitation = (a: Annotation): a is ContainerFileCitation =>
-  a.type === "container_file_citation"
-export const isFilePath = (a: Annotation): a is FilePath => a.type === "file_path"
+export const isUrlCitation = Schema.is(UrlCitation)
+export const isFileCitation = Schema.is(FileCitation)
+export const isContainerFileCitation = Schema.is(ContainerFileCitation)
+export const isFilePath = Schema.is(FilePath)
 
 export const OutputText = Schema.Struct({
   type: Schema.Literal("output_text"),
@@ -183,18 +157,15 @@ export type Item = typeof Item.Type
 // Type guards
 // ---------------------------------------------------------------------------
 
-export const isInputText = (block: ContentBlock): block is InputText => block.type === "input_text"
-export const isInputImage = (block: ContentBlock): block is InputImage =>
-  block.type === "input_image"
-export const isOutputText = (block: ContentBlock): block is OutputText =>
-  block.type === "output_text"
-export const isRefusal = (block: ContentBlock): block is Refusal => block.type === "refusal"
-
-export const isMessage = (item: Item): item is Message => item.type === "message"
-export const isFunctionCall = (item: Item): item is FunctionCall => item.type === "function_call"
-export const isFunctionCallOutput = (item: Item): item is FunctionCallOutput =>
-  item.type === "function_call_output"
-export const isReasoning = (item: Item): item is Reasoning => item.type === "reasoning"
+export const isInputText = Schema.is(InputText)
+export const isInputImage = Schema.is(InputImage)
+export const isOutputText = Schema.is(OutputText)
+export const isRefusal = Schema.is(Refusal)
+
+export const isMessage = Schema.is(Message)
+export const isFunctionCall = Schema.is(FunctionCall)
+export const isFunctionCallOutput = Schema.is(FunctionCallOutput)
+export const isReasoning = Schema.is(Reasoning)
 
 // ---------------------------------------------------------------------------
 // Usage and stop reason

package/src/domain/Media.ts

@@ -0,0 +1,61 @@
+/**
+ * Cross-modality media reference shape.
+ *
+ * Every "media at rest" reference - image, audio, video, document - is one
+ * of three variants:
+ *
+ *   - `url`    : a remote address (HTTP, GCS, etc.). The model fetches it.
+ *               `mimeType` is optional - servers usually set Content-Type.
+ *               Some providers (Gemini `fileData`) want it explicit.
+ *
+ *   - `base64` : an inline base64-encoded payload. Always carries a
+ *               `mimeType` so the consumer knows how to decode.
+ *
+ *   - `bytes`  : raw `Uint8Array`. Provider layers normalize to base64 or
+ *               multipart upload at the wire boundary - users don't need
+ *               to encode themselves.
+ *
+ * Per-modality files (`Image.ts`, future `Audio.ts` / `Video.ts` /
+ * `Document.ts`) instantiate this shape with their typed MIME union to
+ * get autocomplete on common formats while keeping the structural type
+ * uniform across modalities.
+ *
+ * Streaming media (live mic feed, streaming TTS playback) is *not*
+ * modeled here. Streams carry effect parameters (`Stream<A, E, R>`) and
+ * lifecycle (Scope, cancellation) that don't apply to media at rest. The
+ * complementary type lives alongside this one as `*Stream` in each
+ * per-modality file when those modalities land.
+ *
+ * Provider-uploaded asset references (OpenAI Files `file_id`, Gemini
+ * Files API URIs, Anthropic file IDs) are also out of scope here -
+ * they're a separate union (`FileRef`) added when needed.
+ */
+
+export type MediaUrl<M extends string = string> = {
+  readonly _tag: "url"
+  readonly url: string
+  readonly mimeType?: M
+}
+
+export type MediaBase64<M extends string = string> = {
+  readonly _tag: "base64"
+  readonly base64: string
+  readonly mimeType: M
+}
+
+export type MediaBytes<M extends string = string> = {
+  readonly _tag: "bytes"
+  readonly bytes: Uint8Array
+  readonly mimeType: M
+}
+
+export type MediaSource<M extends string = string> = MediaUrl<M> | MediaBase64<M> | MediaBytes<M>
+
+export const isMediaUrl = <M extends string>(s: MediaSource<M>): s is MediaUrl<M> =>
+  s._tag === "url"
+
+export const isMediaBase64 = <M extends string>(s: MediaSource<M>): s is MediaBase64<M> =>
+  s._tag === "base64"
+
+export const isMediaBytes = <M extends string>(s: MediaSource<M>): s is MediaBytes<M> =>
+  s._tag === "bytes"

package/src/domain/Turn.ts

@@ -86,27 +86,17 @@ export const assistantMessages = (turn: Turn): ReadonlyArray<Message> =>
   turn.items.filter((i): i is Message => i.type === "message" && i.role === "assistant")
 
 /**
- * State stamped with the just-completed `Turn`. Recipes use this as the
- * intermediate value between "turn lands" and "compute next state": extend
- * `state.history` with the turn's items, and keep the assembled turn
- * around for stop-reason / usage / function-call inspection.
- *
- * Generic over the recipe's state shape - any record carrying a
- * `history: ReadonlyArray<Item>` field works.
- */
-export type Cursor<S> = S & { readonly turn: Turn }
-
-/**
- * Build a `Cursor<S>` from a state record and the just-completed turn.
- * Extends `state.history` with `turn.items` and stamps the turn.
+ * Append a completed turn and optional follow-up items to a state record's
+ * history. Recipes use this at the point where structured tool results are
+ * converted to model-facing `FunctionCallOutput`s.
  */
-export const cursor = <S extends { readonly history: ReadonlyArray<Item> }>(
+export const appendTurn = <S extends { readonly history: ReadonlyArray<Item> }>(
   state: S,
   turn: Turn,
-): Cursor<S> => ({
+  items: ReadonlyArray<Item> = [],
+): S => ({
   ...state,
-  history: [...state.history, ...turn.items],
-  turn,
+  history: [...state.history, ...turn.items, ...items],
 })
 
 // ---------------------------------------------------------------------------

package/src/embedding-model/Embedding.ts

@@ -0,0 +1,117 @@
+import type { ImageSource } from "../domain/Image.js"
+
+/**
+ * One part of a mixed text+image input. Used inside `EmbedInput.content[]`
+ * for providers that accept interleaved modalities in a single embed call
+ * (Cohere v4, Voyage multimodal, Jina v4, Google `gemini-embedding-2`).
+ */
+export type EmbedContentPart = { readonly text: string } | { readonly image: ImageSource }
+
+/**
+ * What you embed. The `string` shorthand covers the common text-only case;
+ * structured variants exist for image-only and mixed-modality inputs.
+ *
+ * Not every provider accepts every variant: text-only providers (OpenAI,
+ * Mixedbread today) handle `string` and `{ text }`; multimodal providers
+ * (Google, Jina v4, Voyage multimodal, Cohere v4) handle all four. A
+ * provider layer rejects shapes it can't encode as `AiError.InvalidRequest`.
+ */
+export type EmbedInput =
+  | string
+  | { readonly text: string }
+  | { readonly image: ImageSource }
+  | { readonly content: ReadonlyArray<EmbedContentPart> }
+
+// ---------------------------------------------------------------------------
+// Embedding representations
+//
+// The `_tag` reflects the wire form the provider returned, *not* what the
+// consumer asked for - request `encoding: "int8"` and you get back an
+// `Int8Embedding`. Math primitives are typed against the named interfaces
+// (see `Vector.ts`) so e.g. `sparseCosine` only accepts `SparseEmbedding`.
+// ---------------------------------------------------------------------------
+
+/** Dense float32 vector. The default representation across all providers. */
+export type Float32Embedding = {
+  readonly _tag: "float32"
+  readonly vector: Float32Array
+}
+
+/**
+ * Dense int8-quantized vector. ~4x smaller than float32 with minimal
+ * recall loss on most benchmarks.
+ */
+export type Int8Embedding = {
+  readonly _tag: "int8"
+  readonly vector: Int8Array
+}
+
+/**
+ * Dense binary-quantized vector. One bit per dimension, packed into bytes.
+ * ~32x smaller than float32; meaningful recall loss but useful for hot
+ * indexes paired with a float32 reranker pass.
+ */
+export type BinaryEmbedding = {
+  readonly _tag: "binary"
+  readonly vector: Uint8Array
+}
+
+/**
+ * Sparse vector. Token-keyed weights for hybrid search (dense + lexical-
+ * style sparse). The single hosted producer today is Jina's `elser-v2`
+ * model, which returns subword tokens (e.g. `"bread"`, `"##ing"`) with
+ * their relevance weights.
+ *
+ * The shape is `Record<string, number>` rather than `(indices, values)`
+ * because real hosted learned-sparse encoders (ELSER, SPLADE) emit token
+ * strings with no shared vocabulary index. Converting to integer indices
+ * would either need a vocabulary table the model doesn't expose, or
+ * lose the cross-vector matching semantics. If a provider ever exposes
+ * index-valued sparse vectors (Pinecone-style, where you bring your own
+ * vocab), add an `IndexSparseEmbedding` sibling arm with `_tag:
+ * "sparse-indexed"`.
+ *
+ * Score with `Vector.sparseCosine` — dot product over the intersection
+ * of keys, normalized by the L2 norms of both maps.
+ */
+export type SparseEmbedding = {
+  readonly _tag: "sparse"
+  readonly weights: Readonly<Record<string, number>>
+}
+
+/**
+ * Multivector / late-interaction output: one float32 vector per token.
+ * Score documents with `Vector.maxSim` (ColBERT-style: per query vector,
+ * max dot product across doc vectors, summed). Typically ~50-500 vectors
+ * per document, each shorter than a single-vector embedding (~128 dim
+ * vs ~1024).
+ *
+ * Quantized multivector forms aren't modeled for the same reason as
+ * sparse - nothing on hosted APIs ships them yet.
+ */
+export type MultivectorEmbedding = {
+  readonly _tag: "multivector"
+  readonly vectors: ReadonlyArray<Float32Array>
+}
+
+export type Embedding =
+  | Float32Embedding
+  | Int8Embedding
+  | BinaryEmbedding
+  | SparseEmbedding
+  | MultivectorEmbedding
+
+export const isFloat32 = (e: Embedding): e is Float32Embedding => e._tag === "float32"
+export const isInt8 = (e: Embedding): e is Int8Embedding => e._tag === "int8"
+export const isBinary = (e: Embedding): e is BinaryEmbedding => e._tag === "binary"
+export const isSparse = (e: Embedding): e is SparseEmbedding => e._tag === "sparse"
+export const isMultivector = (e: Embedding): e is MultivectorEmbedding => e._tag === "multivector"
+
+/**
+ * Token usage for one embed / embedMany call. One value per HTTP request,
+ * not per input vector. Most providers populate `inputTokens`; the field
+ * is optional for those that don't (or for mock layers in tests).
+ */
+export type Usage = {
+  readonly inputTokens?: number
+}

package/src/embedding-model/EmbeddingModel.ts

@@ -0,0 +1,107 @@
+import { Context, Effect } from "effect"
+import * as AiError from "../domain/AiError.js"
+import type { Embedding, EmbedInput, Usage } from "./Embedding.js"
+
+/**
+ * Output representation requested from the provider.
+ *
+ * Dense quantizations - same vector at different storage cost:
+ * - `float32` — universal default.
+ * - `int8` — ~4x smaller; minimal recall loss on most benchmarks.
+ * - `binary` — ~32x smaller; meaningful recall loss but pairs well with
+ *   a float32 reranker pass over a small candidate set.
+ *
+ * Non-dense representations:
+ * - `sparse` — learned sparse vector for hybrid (dense + lexical) search.
+ *   Currently Jina ELSER only on hosted APIs.
+ * - `multivector` — one vector per token for late-interaction (ColBERT-
+ *   style) scoring via `Vector.maxSim`. Currently Jina v4 only.
+ *
+ * Each provider's typed request narrows this to its supported set at
+ * compile time (e.g. `JinaEncoding = "float32" | "binary" | "sparse" |
+ * "multivector"`). On the generic `EmbeddingModel` path, callers can
+ * pass any `Encoding` and the provider's API will reject mismatches at
+ * runtime.
+ */
+export type Encoding = "float32" | "int8" | "binary" | "sparse" | "multivector"
+
+/**
+ * Cross-provider single-embed request. Mirrors the shape of
+ * `LanguageModel.CommonRequest`: cross-cutting fields here, vendor
+ * specifics in the provider's typed request.
+ *
+ * Provider-specific extensions (Cohere widened `task` enum, Jina LoRA
+ * tasks, Mixedbread free-form `prompt`, etc.) live in that provider's own
+ * request interface, which extends this and narrows `model` / widens
+ * `task`.
+ */
+export type CommonEmbedRequest = {
+  readonly input: EmbedInput
+  /**
+   * Model identifier. Each provider narrows this to its typed literal
+   * union, so code that yields a typed provider tag gets autocompletion.
+   */
+  readonly model: string
+  /**
+   * Retrieval-task hint. Applies to the input. OpenAI ignores this;
+   * Mixedbread doesn't have it; Cohere v3+ requires it on the wire (typed
+   * as required in `CohereEmbedRequest`). Provider-specific task enums
+   * (classification, clustering, code retrieval, …) live on the
+   * provider's own request type.
+   */
+  readonly task?: "query" | "document"
+  /**
+   * Matryoshka truncation. Default: provider's native dimension.
+   * Discrete-value providers (Cohere, Vertex `multimodalembedding@001`)
+   * narrow this to a literal union in their typed request.
+   */
+  readonly dimensions?: number
+  /**
+   * Output representation - see {@link Encoding}. Dense float32 is the
+   * default; provider layers reject unsupported values up front with
+   * `InvalidRequest`.
+   */
+  readonly encoding?: Encoding
+}
+
+/**
+ * Cross-provider batch-embed request. One `task` for the whole batch -
+ * mixed-task batches aren't a real provider feature (rerankers exist for
+ * that).
+ */
+export type CommonEmbedManyRequest = Omit<CommonEmbedRequest, "input"> & {
+  readonly inputs: ReadonlyArray<EmbedInput>
+}
+
+export type EmbedResponse = {
+  readonly embedding: Embedding
+  readonly usage: Usage
+}
+
+export type EmbedManyResponse = {
+  readonly embeddings: ReadonlyArray<Embedding>
+  readonly usage: Usage
+}
+
+export type EmbeddingModelService = {
+  readonly embed: (request: CommonEmbedRequest) => Effect.Effect<EmbedResponse, AiError.AiError>
+  readonly embedMany: (
+    request: CommonEmbedManyRequest,
+  ) => Effect.Effect<EmbedManyResponse, AiError.AiError>
+}
+
+export class EmbeddingModel extends Context.Service<EmbeddingModel, EmbeddingModelService>()(
+  "@betalyra/effect-uai/EmbeddingModel",
+) {}
+
+/** Embed a single input. */
+export const embed = (
+  request: CommonEmbedRequest,
+): Effect.Effect<EmbedResponse, AiError.AiError, EmbeddingModel> =>
+  Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embed(request))
+
+/** Embed a batch in one provider call. Same `task` for every input. */
+export const embedMany = (
+  request: CommonEmbedManyRequest,
+): Effect.Effect<EmbedManyResponse, AiError.AiError, EmbeddingModel> =>
+  Effect.flatMap(EmbeddingModel.asEffect(), (m) => m.embedMany(request))

package/src/index.ts

@@ -1,11 +1,19 @@
 export * as AiError from "./domain/AiError.js"
+export * as Image from "./domain/Image.js"
 export * as Items from "./domain/Items.js"
+export * as Media from "./domain/Media.js"
 export * as Turn from "./domain/Turn.js"
+export * as Embedding from "./embedding-model/Embedding.js"
+export * as EmbeddingModel from "./embedding-model/EmbeddingModel.js"
 export * as LanguageModel from "./language-model/LanguageModel.js"
+export * as Vector from "./math/Vector.js"
 export * as Loop from "./loop/Loop.js"
-export * as Match from "./match/Match.js"
 export * as Tool from "./tool/Tool.js"
 export * as Toolkit from "./tool/Toolkit.js"
+export * as Outcome from "./tool/Outcome.js"
+export * as ToolEvent from "./tool/ToolEvent.js"
+export * as Resolvers from "./tool/Resolvers.js"
+export * as HistoryCheck from "./tool/HistoryCheck.js"
 export * as JSONL from "./streaming/JSONL.js"
 export * as Lines from "./streaming/Lines.js"
 export * as SSE from "./streaming/SSE.js"

package/src/language-model/LanguageModel.ts

@@ -11,7 +11,7 @@ import { isTurnComplete, type Turn, type TurnEvent } from "../domain/Turn.js"
  * to a single provider (reasoning effort, prompt caching, store flags,
  * ...) lives in that provider's own request interface, which extends this.
  */
-export interface CommonRequest {
+export type CommonRequest = {
   readonly history: ReadonlyArray<Item>
   /**
    * Model identifier. Each provider narrows this to its typed literal union,
@@ -36,7 +36,7 @@ export interface CommonRequest {
   readonly structured?: StructuredFormat.StructuredFormat<unknown>
 }
 
-export interface LanguageModelService {
+export type LanguageModelService = {
   readonly streamTurn: (request: CommonRequest) => Stream.Stream<TurnEvent, AiError.AiError>
 }
 
@@ -51,23 +51,3 @@ export const streamTurn = (
   request: CommonRequest,
 ): Stream.Stream<TurnEvent, AiError.AiError, LanguageModel> =>
   Stream.unwrap(Effect.map(LanguageModel.asEffect(), (m) => m.streamTurn(request)))
-
-/**
- * Run a single turn to completion and return the assembled `Turn`.
- *
- * Implementation: drain the delta stream and pluck the terminal
- * `turn_complete` event. The provider is contractually required to emit
- * exactly one such event as the last delta.
- */
-export const turn = (request: CommonRequest): Effect.Effect<Turn, AiError.AiError, LanguageModel> =>
-  Effect.flatMap(Stream.runCollect(streamTurn(request)), (deltas) => {
-    const last = deltas[deltas.length - 1]
-    return last !== undefined && isTurnComplete(last)
-      ? Effect.succeed(last.turn)
-      : Effect.fail(
-          new AiError.Unavailable({
-            provider: "unknown",
-            raw: "Provider stream ended without a turn_complete event",
-          }),
-        )
-  })

package/src/loop/Loop.test.ts

@@ -1,6 +1,15 @@
-import { Deferred, Effect, Fiber, Ref, Stream } from "effect"
+import { Deferred, Effect, Fiber, Latch, Ref, Stream, SubscriptionRef } from "effect"
 import { describe, expect, it } from "vitest"
-import { type Event, loop, next, nextAfter, stopEvent, stopAfter, value } from "./Loop.js"
+import {
+  type Event,
+  loop,
+  loopWithState,
+  next,
+  nextAfter,
+  stopEvent,
+  stopAfter,
+  value,
+} from "./Loop.js"
 
 describe("Loop.loop", () => {
   it("threads state across iterations and emits each iteration's substream in order", async () => {
@@ -410,3 +419,106 @@ describe("Loop.loop - pull-specific stream semantics", () => {
     expect(result._tag).toBe("Failure")
   })
 })
+
+describe("Loop.loopWithState", () => {
+  it("exposes the final state in the SubscriptionRef after the stream completes", async () => {
+    const program = Effect.gen(function* () {
+      const { stream, state } = yield* loopWithState(0, (n: number) =>
+        n >= 3 ? stopAfter(Stream.fromIterable([n])) : nextAfter(Stream.fromIterable([n]), n + 1),
+      )
+      const values = yield* Stream.runCollect(stream)
+      const finalState = yield* SubscriptionRef.get(state)
+      return { values: Array.from(values), finalState }
+    })
+
+    const { values, finalState } = await Effect.runPromise(program)
+    expect(values).toEqual([0, 1, 2, 3])
+    // Last `next(state)` was `next(3)` before the iteration that emitted Stop.
+    expect(finalState).toBe(3)
+  })
+
+  it("the state ref starts at `initial` and stays there if the loop stops without advancing", async () => {
+    const program = Effect.gen(function* () {
+      const { stream, state } = yield* loopWithState({ count: 7 }, () =>
+        Stream.fromIterable([stopEvent]),
+      )
+      yield* Stream.runDrain(stream)
+      return yield* SubscriptionRef.get(state)
+    })
+
+    expect(await Effect.runPromise(program)).toEqual({ count: 7 })
+  })
+
+  it("a downstream consumer can read the live state between emitted values", async () => {
+    // Body emits one value per iteration, then advances. A `Stream.runForEach`
+    // consumer reads the ref each time a value arrives — proving the ref
+    // tracks loop state without the body needing to surface it.
+    const program = Effect.gen(function* () {
+      const { stream, state } = yield* loopWithState(0, (n: number) =>
+        n >= 3 ? stopAfter(Stream.fromIterable([n])) : nextAfter(Stream.fromIterable([n]), n + 1),
+      )
+      const seen: Array<{ value: number; stateAfter: number }> = []
+      yield* Stream.runForEach(stream, (v) =>
+        Effect.gen(function* () {
+          seen.push({ value: v, stateAfter: yield* SubscriptionRef.get(state) })
+        }),
+      )
+      return seen
+    })
+
+    // For each iter `n`, the consumer reads the ref between values: it sees
+    // the iteration's input state. The terminal iter (n=3) stops without
+    // advancing, so its read still shows 3.
+    expect(await Effect.runPromise(program)).toEqual([
+      { value: 0, stateAfter: 0 },
+      { value: 1, stateAfter: 1 },
+      { value: 2, stateAfter: 2 },
+      { value: 3, stateAfter: 3 },
+    ])
+  })
+
+  it("SubscriptionRef.changes emits every state transition to a concurrent observer", async () => {
+    const program = Effect.gen(function* () {
+      const start = yield* Latch.make(false)
+
+      // Body waits on the latch in iter 0 so the observer can subscribe first.
+      const { stream, state } = yield* loopWithState(0, (n: number) =>
+        Effect.gen(function* () {
+          if (n === 0) yield* Latch.await(start)
+          return n >= 3 ? stopAfter(Stream.empty) : nextAfter(Stream.empty, n + 1)
+        }),
+      )
+
+      // Fork the observer; take 4 distinct states (initial + 3 transitions).
+      const observerFiber = yield* Effect.forkChild(
+        SubscriptionRef.changes(state).pipe(Stream.take(4), Stream.runCollect),
+      )
+
+      // Give the observer fiber a chance to actually subscribe before the
+      // loop starts advancing the ref. Without this, the loop could finish
+      // before the observer's pubsub subscription is in place.
+      yield* Effect.sleep("10 millis")
+
+      yield* Latch.open(start)
+      yield* Stream.runDrain(stream)
+
+      return Array.from(yield* Fiber.join(observerFiber))
+    })
+
+    // initial 0, then next(1), next(2), next(3) — four distinct states.
+    expect(await Effect.runPromise(program)).toEqual([0, 1, 2, 3])
+  })
+
+  it("does not interfere with the body's value stream", async () => {
+    const program = Effect.gen(function* () {
+      const { stream } = yield* loopWithState(0, (n: number) =>
+        n >= 3
+          ? stopAfter(Stream.fromIterable([n]))
+          : nextAfter(Stream.fromIterable([n, n + 0.5]), n + 1),
+      )
+      return Array.from(yield* Stream.runCollect(stream))
+    })
+
+    expect(await Effect.runPromise(program)).toEqual([0, 0.5, 1, 1.5, 2, 2.5, 3])
+  })
+})