@effect-uai/core 0.5.1 → 0.6.0

package/dist/loop/Loop.mjs

@@ -6,10 +6,10 @@ import { Array, Cause, Channel, Data, Effect, Exit, Function, Match, Option, Ref
 /**
 * Pull-based `loop` for state-threaded sub-streams.
 *
-* Each iteration runs a body that returns a `Stream<Event<A, S>>`. The body
+* Each iteration runs a body that returns a `Stream<Step<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
+* `Loop.next(state)` (continue with new state) or `Loop.stop()` (terminate).
+* The loop unwraps `Value` steps 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
@@ -17,98 +17,44 @@ import { Array, Cause, Channel, Data, Effect, Exit, Function, Match, Option, Ref
 * scoped resources, and backpressure stay aligned with normal Stream
 * semantics.
 *
-* Convention: a `Next` or `Stop` event is the terminal element of a body's
+* Convention: a `Next` or `Stop` step 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.
+* (their producing side effects may already have run). The `Loop.next` /
+* `Loop.stop` helpers each emit a single terminal step, so concatenate
+* your values before them (`values.pipe(Stream.concat(Loop.next(state)))`).
 */
 var Loop_exports = /* @__PURE__ */ __exportAll({
 	loop: () => loop,
-	loopFrom: () => loopFrom,
+	loopOver: () => loopOver,
 	loopWithState: () => loopWithState,
 	next: () => next,
-	nextAfter: () => nextAfter,
-	nextAfterFold: () => nextAfterFold,
 	onTurnComplete: () => onTurnComplete,
 	stop: () => stop,
-	stopAfter: () => stopAfter,
-	stopEvent: () => stopEvent,
-	stopWith: () => stopWith,
-	stopWithAfter: () => stopWithAfter,
 	value: () => value
 });
-const Event = Data.taggedEnum();
+const Step = Data.taggedEnum();
 /** Wrap a value so it flows through the loop to downstream consumers. */
-const value = (a) => Event.Value({ value: a });
-/** End the current iteration and continue with a new state. */
-const next = (state) => Event.Next({ state });
+const value = (a) => Step.Value({ value: a });
 /**
-* The terminal `Stop` event with no carried state. Use `stop` (the Stream)
-* to end a loop body without communicating a final state.
+* End the current iteration and continue with a new state. Emits a single
+* terminal `Next` step as a one-element stream, so it slots directly into a
+* loop body or after a run of values: `values.pipe(Stream.concat(next(s)))`.
 */
-const stopEvent = Event.Stop();
+const next = (state) => Stream.succeed(Step.Next({ state }));
 /**
-* Terminal event that ends the loop AND carries a final state. For
-* `loopFrom` this is the natural "this input is done, here's the state to
-* carry forward to the next input" signal — symmetric with `next(s)` but
-* ending the inner loop instead of continuing it. For `loopWithState` the
-* carried state is written to the `SubscriptionRef` before the loop ends.
+* End the loop. Called with no argument it emits a bare `Stop`; called with
+* a state it emits `StopWith(state)` — `loopOver` threads that final state
+* to the next input and `loopWithState` writes it to its `SubscriptionRef`
+* before the loop ends. Either way it returns a single-element stream, so
+* return it directly from a loop body.
 */
-const stopWith = (state) => Event.StopWith({ state });
+const stop = (state) => Stream.succeed(state === void 0 ? Step.Stop() : Step.StopWith({ state }));
 /**
-* 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.
-*/
-const stop = 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."
-*
-* Dual: data-first `nextAfter(stream, state)` and data-last
-* `stream.pipe(nextAfter(state))` both work.
-*/
-const nextAfter = Function.dual(2, (stream, state) => 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."
-*
-* Unary on the stream — already pipe-compatible via `stream.pipe(stopAfter)`.
-*/
-const stopAfter = (stream) => Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopEvent]));
-/**
-* Pipe a raw `Stream<A>` into the loop's emit shape, then terminate with
-* `stopWith(state)`. The natural "emit final outputs, advance state, end
-* this input's inner loop" shape for `loopFrom`.
-*
-* Dual: data-first `stopWithAfter(stream, state)` and data-last
-* `stream.pipe(stopWithAfter(state))` both work.
-*/
-const stopWithAfter = Function.dual(2, (stream, state) => Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopWith(state)])));
-/**
-* 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.continueWith` to collect tool
-* results and build next state without exposing a Ref to recipes.
-*
-* Dual: data-first `nextAfterFold(stream, initial, reduce, build)` and
-* data-last `stream.pipe(nextAfterFold(initial, reduce, build))` both work.
-*/
-const nextAfterFold = Function.dual(4, (stream, initial, reduce, build) => 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));
-})));
-/**
-* Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.
+* Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Step<TurnEvent | A, S>>`.
 * Each delta passes through as `value(delta)` (including the terminal
 * `TurnComplete`, 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
+* steps (typically tool outputs followed by `next(state)` or `stop()`) is
 * concatenated.
 *
 * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on
@@ -134,22 +80,22 @@ const onTurnComplete = Function.dual(2, (deltas, then) => Stream.unwrap(Effect.g
 const isNonEmpty = (array) => array.length > 0;
 const closeBody = (current, exit) => Scope.close(current.scope, exit);
 /**
-* Walk a chunk of `Event<A, S>` until a terminal `Next` or `Stop` is found.
+* Walk a chunk of `Step<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
+* step. Anything in the chunk after the terminal is discarded - its
 * producing side effects may have run, but downstream never sees it.
 */
 const partitionChunk = (chunk) => {
-	const [valueEvents, rest] = Array.span(chunk, (e) => e._tag === "Value");
+	const [valueSteps, rest] = Array.span(chunk, (e) => e._tag === "Value");
 	return {
-		values: valueEvents.map((e) => e.value),
+		values: valueSteps.map((e) => e.value),
 		decision: Array.head(rest)
 	};
 };
 /**
 * 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
+* a `Stream<Step<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)`
@@ -198,31 +144,31 @@ const loop = Function.dual(2, (initial, body) => Stream.scoped(Stream.fromPull(E
 * stream, runs an inner seed-driven `loop` whose body is
 * `(s) => body(s, item)`. State is threaded across input items.
 *
-* **Per-input semantics — the body emits standard `Event<A, S>`:**
+* **Per-input semantics — the body emits standard `Step<A, S>`:**
 *   - `value(a)`: emit `a` downstream
 *   - `next(s)`: re-run the body with the SAME input and new state `s`
 *     (multi-turn within one input — e.g. multiple model turns + tool
 *     calls for one document)
-*   - `stop`: end this input's inner loop, advance to the next input
+*   - `stop()`: end this input's inner loop, advance to the next input
 *     (state preserved)
-*   - body stream ending without a decision: same as `stop` (advance)
+*   - body stream ending without a decision: same as `stop()` (advance)
 *
 * **Outer termination:** the input stream ending. To halt programmatically
 * from within, end the input stream upstream (`Stream.takeWhile`, a
-* `SubscriptionRef` gate, etc.). Reserving `stop` for per-item
+* `SubscriptionRef` gate, etc.). Reserving `stop()` for per-item
 * advancement is what makes the common "stream of documents, multi-turn
 * conversation per document" shape readable.
 *
-* Dual: data-first `loopFrom(input, initial, body)` and data-last
-* `input.pipe(loopFrom(initial, body))` both work.
+* Dual: data-first `loopOver(input, initial, body)` and data-last
+* `input.pipe(loopOver(initial, body))` both work.
 */
-const loopFrom = Function.dual(3, (input, initial, body) => Stream.unwrap(Effect.gen(function* () {
+const loopOver = Function.dual(3, (input, initial, body) => Stream.unwrap(Effect.gen(function* () {
 	const stateRef = yield* Ref.make(initial);
 	return input.pipe(Stream.flatMap((item) => Stream.unwrap(Effect.gen(function* () {
 		const state = yield* Ref.get(stateRef);
 		const wrappedBody = (s) => {
 			const result = body(s, item);
-			return (Effect.isEffect(result) ? Stream.unwrap(result) : result).pipe(Stream.tap((event) => Match.value(event).pipe(Match.tags({
+			return (Effect.isEffect(result) ? Stream.unwrap(result) : result).pipe(Stream.tap((step) => Match.value(step).pipe(Match.tags({
 				Next: (e) => Ref.set(stateRef, e.state),
 				StopWith: (e) => Ref.set(stateRef, e.state)
 			}), Match.orElse(() => Effect.void))));
@@ -235,7 +181,7 @@ const loopFrom = Function.dual(3, (input, initial, body) => Stream.unwrap(Effect
 * alongside the value stream.
 *
 * Allocates one `SubscriptionRef<S>` seeded with `initial`, then runs the
-* loop with a wrapped body that taps every `Next(s)` event into the ref
+* loop with a wrapped body that taps every `Next(s)` step into the ref
 * before forwarding it. The caller decides how to consume both channels:
 *
 *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`
@@ -252,7 +198,7 @@ const loopFrom = Function.dual(3, (input, initial, body) => Stream.unwrap(Effect
 */
 const loopWithState = (initial, body) => Effect.gen(function* () {
 	const stateRef = yield* SubscriptionRef.make(initial);
-	const tap = (stream) => stream.pipe(Stream.tap((event) => Match.value(event).pipe(Match.tags({
+	const tap = (stream) => stream.pipe(Stream.tap((step) => Match.value(step).pipe(Match.tags({
 		Next: (e) => SubscriptionRef.set(stateRef, e.state),
 		StopWith: (e) => SubscriptionRef.set(stateRef, e.state)
 	}), Match.orElse(() => Effect.void))));
@@ -266,6 +212,6 @@ const loopWithState = (initial, body) => Effect.gen(function* () {
 	};
 });
 //#endregion
-export { loop, loopFrom, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, stopWith, stopWithAfter, Loop_exports as t, value };
+export { loop, loopOver, loopWithState, next, onTurnComplete, stop, Loop_exports as t, value };
 
 //# sourceMappingURL=Loop.mjs.map

package/dist/loop/Loop.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"Loop.mjs","names":["Arr"],"sources":["../../src/loop/Loop.ts"],"sourcesContent":["/**\n * Pull-based `loop` for state-threaded sub-streams.\n *\n * Each iteration runs a body that returns a `Stream<Event<A, S>>`. The body\n * emits values via `Loop.value(a)` and signals iteration control via\n * `Loop.next(state)` (continue with new state) or `Loop.stop` (terminate).\n * The loop unwraps `Value` events back to `A` for downstream consumers, so\n * the resulting stream is a plain `Stream<A>`.\n *\n * The next body stream is only pulled when downstream pulls the outer\n * stream - no producer fiber, no queue buffering. Cancellation, failures,\n * scoped resources, and backpressure stay aligned with normal Stream\n * semantics.\n *\n * Convention: a `Next` or `Stop` event is the terminal element of a body's\n * iteration. Values emitted in the same chunk after one are discarded\n * (their producing side effects may already have run). Prefer the\n * `Loop.nextAfter` / `Loop.stopAfter` helpers to terminate cleanly.\n */\nimport {\n  Array as Arr,\n  Cause,\n  Channel,\n  Data,\n  Effect,\n  Exit,\n  Function,\n  Match,\n  Option,\n  Ref,\n  Result,\n  Scope,\n  Stream,\n  SubscriptionRef,\n} from \"effect\"\nimport { IncompleteTurn } from \"../domain/AiError.js\"\nimport { isTurnComplete, type Turn, type TurnEvent } from \"../domain/Turn.js\"\n\n// ---------------------------------------------------------------------------\n// Event type - the body's emit shape\n// ---------------------------------------------------------------------------\n\n/**\n * The tagged union a body emits per pull. `Value` carries a payload that\n * flows downstream. `Next` ends the current iteration and continues with a\n * new state. `Stop` ends the loop entirely with no carried state.\n * `StopWith` also ends the loop but carries a final state that `loopFrom`\n * will thread to the next input and `loopWithState` will write to its\n * `SubscriptionRef` before the loop ends. Plain `loop` has no next\n * iteration to apply it to and treats `StopWith` like `Stop`.\n *\n * `Stop` is intentionally `{}` so the bare `stopEvent` / `stop` helpers\n * don't constrain `S` from a body's stream type — every body has a `Stop`\n * variant in its union, and forcing `S` to flow through it would break\n * inference whenever the body never uses `next` / `stopWith`.\n */\nexport type Event<A, S> = Data.TaggedEnum<{\n  Value: { readonly value: A }\n  Next: { readonly state: S }\n  Stop: {}\n  StopWith: { readonly state: S }\n}>\n\ninterface EventDef extends Data.TaggedEnum.WithGenerics<2> {\n  readonly taggedEnum: Event<this[\"A\"], this[\"B\"]>\n}\n\nconst Event = Data.taggedEnum<EventDef>()\n\n/** Wrap a value so it flows through the loop to downstream consumers. */\nexport const value = <A>(a: A): Event<A, never> => Event.Value({ value: a })\n\n/** End the current iteration and continue with a new state. */\nexport const next = <S>(state: S): Event<never, S> => Event.Next({ state })\n\n/**\n * The terminal `Stop` event with no carried state. Use `stop` (the Stream)\n * to end a loop body without communicating a final state.\n */\nexport const stopEvent: Event<never, never> = Event.Stop()\n\n/**\n * Terminal event that ends the loop AND carries a final state. For\n * `loopFrom` this is the natural \"this input is done, here's the state to\n * carry forward to the next input\" signal — symmetric with `next(s)` but\n * ending the inner loop instead of continuing it. For `loopWithState` the\n * carried state is written to the `SubscriptionRef` before the loop ends.\n */\nexport const stopWith = <S>(state: S): Event<never, S> => Event.StopWith({ state })\n\n/**\n * A single-element stream that ends the loop. Return this from a body when\n * there's nothing else to emit; equivalent to `stopAfter(Stream.empty)` but\n * named for the common case.\n */\nexport const stop: Stream.Stream<Event<never, never>> = Stream.succeed(stopEvent)\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the\n * iteration with `next(state)`. Common shape for \"stream this turn's\n * deltas, then continue with updated history.\"\n *\n * Dual: data-first `nextAfter(stream, state)` and data-last\n * `stream.pipe(nextAfter(state))` both work.\n */\nexport const nextAfter: {\n  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>\n  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R>\n} = Function.dual(\n  2,\n  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R> =>\n    Stream.concat(Stream.map(stream, value), Stream.fromIterable([next(state)])),\n)\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate the\n * loop. Common shape for \"stream this turn's deltas, then we're done.\"\n *\n * Unary on the stream — already pipe-compatible via `stream.pipe(stopAfter)`.\n */\nexport const stopAfter = <A, E, R>(\n  stream: Stream.Stream<A, E, R>,\n): Stream.Stream<Event<A, never>, E, R> =>\n  Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopEvent]))\n\n/**\n * Pipe a raw `Stream<A>` into the loop's emit shape, then terminate with\n * `stopWith(state)`. The natural \"emit final outputs, advance state, end\n * this input's inner loop\" shape for `loopFrom`.\n *\n * Dual: data-first `stopWithAfter(stream, state)` and data-last\n * `stream.pipe(stopWithAfter(state))` both work.\n */\nexport const stopWithAfter: {\n  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>\n  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R>\n} = Function.dual(\n  2,\n  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R> =>\n    Stream.concat(Stream.map(stream, value), Stream.fromIterable([stopWith(state)])),\n)\n\n/**\n * General `nextAfter` variant: drain `stream` to the consumer, fold elements\n * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.\n *\n * Subsumes `nextAfter` when state is constant (`reduce: (s, _) => s`,\n * `build: (s) => s`). Used by `Toolkit.continueWith` to collect tool\n * results and build next state without exposing a Ref to recipes.\n *\n * Dual: data-first `nextAfterFold(stream, initial, reduce, build)` and\n * data-last `stream.pipe(nextAfterFold(initial, reduce, build))` both work.\n */\nexport const nextAfterFold: {\n  <A, B, S>(\n    initial: B,\n    reduce: (acc: B, a: A) => B,\n    build: (b: B) => S,\n  ): <E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>\n  <A, B, S, E, R>(\n    stream: Stream.Stream<A, E, R>,\n    initial: B,\n    reduce: (acc: B, a: A) => B,\n    build: (b: B) => S,\n  ): Stream.Stream<Event<A, S>, E, R>\n} = Function.dual(\n  4,\n  <A, B, S, E, R>(\n    stream: Stream.Stream<A, E, R>,\n    initial: B,\n    reduce: (acc: B, a: A) => B,\n    build: (b: B) => S,\n  ): Stream.Stream<Event<A, S>, E, R> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const ref = yield* Ref.make(initial)\n        const tapped = stream.pipe(\n          Stream.tap((a) => Ref.update(ref, (acc) => reduce(acc, a))),\n          Stream.map(value),\n        )\n        const continuation = Stream.fromEffect(\n          Ref.get(ref).pipe(Effect.map((acc) => next(build(acc)))),\n        )\n        return tapped.pipe(Stream.concat(continuation))\n      }),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// onTurnComplete - turn-aware stream operator for loop bodies\n// ---------------------------------------------------------------------------\n\n/**\n * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Event<TurnEvent | A, S>>`.\n * Each delta passes through as `value(delta)` (including the terminal\n * `TurnComplete`, so the consumer sees turn boundaries naturally). Once\n * the terminal arrives, `then(turn)` runs and its returned stream of loop\n * events (typically tool outputs followed by `next(state)` or `stop`) is\n * concatenated.\n *\n * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on\n * the raw delta stream cover anything an `emit`-style callback would do.\n *\n * If the upstream ends without a `TurnComplete`, the resulting stream\n * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if\n * you want to recover.\n *\n * Dual: data-first `onTurnComplete(deltas, then)` and data-last\n * `deltas.pipe(onTurnComplete(then))` both work.\n */\nexport const onTurnComplete: {\n  <S, A, E2 = never, R2 = never>(\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,\n  ): <E, R>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n  ) => Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>\n  <S, A, E, R, E2 = never, R2 = never>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,\n  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>\n} = Function.dual(\n  2,\n  <S, A, E, R, E2, R2>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>,\n  ): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const turnRef = yield* Ref.make<Option.Option<Turn>>(Option.none())\n\n        const events: Stream.Stream<Event<TurnEvent, S>, E, R> = deltas.pipe(\n          Stream.tap((delta) =>\n            isTurnComplete(delta) ? Ref.set(turnRef, Option.some(delta.turn)) : Effect.void,\n          ),\n          Stream.map(value),\n        )\n\n        const continuation = Stream.unwrap(\n          Effect.gen(function* () {\n            const opt = yield* Ref.get(turnRef)\n            if (Option.isNone(opt)) return yield* new IncompleteTurn({})\n            return yield* then(opt.value)\n          }),\n        )\n\n        return Stream.concat(events, continuation)\n      }),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst isNonEmpty = <A>(array: ReadonlyArray<A>): array is readonly [A, ...Array<A>] =>\n  array.length > 0\n\ntype CurrentBody<S, A, E, R> = {\n  readonly scope: Scope.Closeable\n  readonly pull: Effect.Effect<ReadonlyArray<Event<A, S>>, E | Cause.Done<void>, R>\n}\n\nconst closeBody = <S, A, E, R>(\n  current: CurrentBody<S, A, E, R>,\n  exit: Exit.Exit<unknown, unknown>,\n) => Scope.close(current.scope, exit)\n\n/**\n * Walk a chunk of `Event<A, S>` until a terminal `Next` or `Stop` is found.\n * Returns the unwrapped values seen so far and (optionally) the terminal\n * event. Anything in the chunk after the terminal is discarded - its\n * producing side effects may have run, but downstream never sees it.\n */\nconst partitionChunk = <A, S>(\n  chunk: ReadonlyArray<Event<A, S>>,\n): {\n  readonly values: ReadonlyArray<A>\n  readonly decision: Option.Option<Event<A, S>>\n} => {\n  const [valueEvents, rest] = Arr.span(\n    chunk,\n    (e): e is Event<A, S> & { _tag: \"Value\" } => e._tag === \"Value\",\n  )\n  return {\n    values: valueEvents.map((e) => e.value),\n    decision: Arr.head(rest),\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\ntype LoopBody<S, A, E, R> = (\n  state: S,\n) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>\n\n/**\n * Drive a state-threaded loop body. Each iteration runs `body(state)` to get\n * a `Stream<Event<A, S>>`; values flow downstream, `next(s)` continues with\n * a new state, `stop` ends the loop. See the file header for the full\n * pull-based execution model.\n *\n * Dual: data-first `loop(initial, body)` and data-last `loop(body)(initial)`\n * (or `pipe(initial, loop(body))`) both work.\n */\nexport const loop: {\n  <S, A, E, R>(body: LoopBody<S, A, E, R>): (initial: S) => Stream.Stream<A, E, R>\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R>\n} = Function.dual(\n  2,\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R> =>\n    Stream.scoped(\n      Stream.fromPull(\n        Effect.gen(function* () {\n          const outerScope = yield* Effect.scope\n          let state = initial\n          let current: CurrentBody<S, A, E, R> | undefined\n          let done = false\n\n          const closeActive = (\n            active: CurrentBody<S, A, E, R>,\n            exit: Exit.Exit<unknown, unknown>,\n          ) => {\n            const isActive = current === active\n            if (isActive) current = undefined\n            // Scope.close is idempotent. Multiple paths can race to close the\n            // active body during cancellation/failure, so closing twice is safe.\n            return closeBody(active, exit)\n          }\n\n          yield* Scope.addFinalizerExit(outerScope, (exit) =>\n            current === undefined ? Effect.void : closeActive(current, exit),\n          )\n\n          const pull = Effect.gen(function* () {\n            while (true) {\n              if (done) return yield* Cause.done()\n\n              if (current === undefined) {\n                const result = body(state)\n                const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result\n                const bodyScope = yield* Scope.fork(outerScope)\n                const bodyPull = yield* Channel.toPullScoped(\n                  Stream.toChannel(stream),\n                  bodyScope,\n                ).pipe(Effect.onError((cause) => Scope.close(bodyScope, Exit.failCause(cause))))\n                current = { scope: bodyScope, pull: bodyPull }\n              }\n\n              const active = current\n              const chunk = yield* active.pull.pipe(\n                Effect.catchIf(Cause.isDone, () =>\n                  closeActive(active, Exit.void).pipe(\n                    Effect.as(undefined as ReadonlyArray<Event<A, S>> | undefined),\n                  ),\n                ),\n                Effect.onError((cause) => closeActive(active, Exit.failCause(cause))),\n              )\n\n              if (chunk === undefined) {\n                done = true\n                return yield* Cause.done()\n              }\n\n              const { values, decision } = partitionChunk(chunk)\n\n              if (Option.isSome(decision)) {\n                yield* closeActive(active, Exit.void)\n                if (decision.value._tag === \"Stop\" || decision.value._tag === \"StopWith\") {\n                  // `loop` has no next iteration to apply StopWith's state to;\n                  // the state lands in `loopFrom`'s outer ref or\n                  // `loopWithState`'s SubscriptionRef via their taps.\n                  done = true\n                } else if (decision.value._tag === \"Next\") {\n                  state = decision.value.state\n                }\n              }\n\n              // Emit the values seen so far if any. Chunks from a Stream pull\n              // are non-empty, so when `decision` is `None` every event was\n              // a `Value` and `values` is non-empty here. With a decision and\n              // no preceding values, fall through to the next iteration.\n              if (isNonEmpty(values)) return values\n            }\n          })\n\n          return pull\n        }),\n      ),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// loopFrom - stream-driven sibling of loop. One input item runs a full\n// multi-turn inner loop.\n// ---------------------------------------------------------------------------\n\ntype LoopFromBody<S, I, A, E, R> = (\n  state: S,\n  input: I,\n) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>\n\n/**\n * Input-driven sibling of `loop`. For each item pulled from the input\n * stream, runs an inner seed-driven `loop` whose body is\n * `(s) => body(s, item)`. State is threaded across input items.\n *\n * **Per-input semantics — the body emits standard `Event<A, S>`:**\n *   - `value(a)`: emit `a` downstream\n *   - `next(s)`: re-run the body with the SAME input and new state `s`\n *     (multi-turn within one input — e.g. multiple model turns + tool\n *     calls for one document)\n *   - `stop`: end this input's inner loop, advance to the next input\n *     (state preserved)\n *   - body stream ending without a decision: same as `stop` (advance)\n *\n * **Outer termination:** the input stream ending. To halt programmatically\n * from within, end the input stream upstream (`Stream.takeWhile`, a\n * `SubscriptionRef` gate, etc.). Reserving `stop` for per-item\n * advancement is what makes the common \"stream of documents, multi-turn\n * conversation per document\" shape readable.\n *\n * Dual: data-first `loopFrom(input, initial, body)` and data-last\n * `input.pipe(loopFrom(initial, body))` both work.\n */\nexport const loopFrom: {\n  <S, I, A, E, R>(\n    initial: S,\n    body: LoopFromBody<S, I, A, E, R>,\n  ): <EI, RI>(input: Stream.Stream<I, EI, RI>) => Stream.Stream<A, E | EI, R | RI>\n  <S, I, A, E, R, EI, RI>(\n    input: Stream.Stream<I, EI, RI>,\n    initial: S,\n    body: LoopFromBody<S, I, A, E, R>,\n  ): Stream.Stream<A, E | EI, R | RI>\n} = Function.dual(\n  3,\n  <S, I, A, E, R, EI, RI>(\n    input: Stream.Stream<I, EI, RI>,\n    initial: S,\n    body: LoopFromBody<S, I, A, E, R>,\n  ): Stream.Stream<A, E | EI, R | RI> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const stateRef = yield* Ref.make<S>(initial)\n        return input.pipe(\n          Stream.flatMap((item) =>\n            Stream.unwrap(\n              Effect.gen(function* () {\n                const state = yield* Ref.get(stateRef)\n                // Capture Next states (and stopWith's final state) into the\n                // outer ref so the LAST state seen in this input's inner\n                // loop is what the next input starts from.\n                const wrappedBody = (s: S) => {\n                  const result = body(s, item)\n                  const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result\n                  return stream.pipe(\n                    Stream.tap((event) =>\n                      Match.value(event).pipe(\n                        Match.tags({\n                          Next: (e) => Ref.set(stateRef, e.state),\n                          StopWith: (e) => Ref.set(stateRef, e.state),\n                        }),\n                        Match.orElse(() => Effect.void),\n                      ),\n                    ),\n                  )\n                }\n                return loop(state, wrappedBody)\n              }),\n            ),\n          ),\n        )\n      }),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// loopWithState - same body protocol, plus a live state observable.\n// ---------------------------------------------------------------------------\n\n/**\n * Like `loop`, but exposes the current loop state as a `SubscriptionRef`\n * alongside the value stream.\n *\n * Allocates one `SubscriptionRef<S>` seeded with `initial`, then runs the\n * loop with a wrapped body that taps every `Next(s)` event into the ref\n * before forwarding it. The caller decides how to consume both channels:\n *\n *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`\n *     - the ref holds the state from the last `Next` (or `initial` if the\n *     loop ended without advancing).\n *   - **Live transitions**: `SubscriptionRef.changes(state)` is a\n *     `Stream<S>` of every state observed; subscribe alongside the value\n *     stream.\n *   - **Mid-iteration peek**: `SubscriptionRef.get(state)` at any time.\n *\n * The returned stream and ref are independent of each other - the ref\n * lives outside the stream's scope, so reading it after the stream\n * completes is safe.\n */\nexport const loopWithState = <S, A, E, R>(\n  initial: S,\n  body: LoopBody<S, A, E, R>,\n): Effect.Effect<{\n  readonly stream: Stream.Stream<A, E, R>\n  readonly state: SubscriptionRef.SubscriptionRef<S>\n}> =>\n  Effect.gen(function* () {\n    const stateRef = yield* SubscriptionRef.make(initial)\n\n    const tap = (stream: Stream.Stream<Event<A, S>, E, R>): Stream.Stream<Event<A, S>, E, R> =>\n      stream.pipe(\n        Stream.tap((event) =>\n          Match.value(event).pipe(\n            Match.tags({\n              Next: (e) => SubscriptionRef.set(stateRef, e.state),\n              StopWith: (e) => SubscriptionRef.set(stateRef, e.state),\n            }),\n            Match.orElse(() => Effect.void),\n          ),\n        ),\n      )\n\n    const wrappedBody: LoopBody<S, A, E, R> = (s) => {\n      const result = body(s)\n      return Effect.isEffect(result) ? Effect.map(result, tap) : tap(result)\n    }\n\n    return {\n      stream: loop(initial, wrappedBody),\n      state: stateRef,\n    }\n  })\n"],"mappings":"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"}
+{"version":3,"file":"Loop.mjs","names":["Arr"],"sources":["../../src/loop/Loop.ts"],"sourcesContent":["/**\n * Pull-based `loop` for state-threaded sub-streams.\n *\n * Each iteration runs a body that returns a `Stream<Step<A, S>>`. The body\n * emits values via `Loop.value(a)` and signals iteration control via\n * `Loop.next(state)` (continue with new state) or `Loop.stop()` (terminate).\n * The loop unwraps `Value` steps back to `A` for downstream consumers, so\n * the resulting stream is a plain `Stream<A>`.\n *\n * The next body stream is only pulled when downstream pulls the outer\n * stream - no producer fiber, no queue buffering. Cancellation, failures,\n * scoped resources, and backpressure stay aligned with normal Stream\n * semantics.\n *\n * Convention: a `Next` or `Stop` step is the terminal element of a body's\n * iteration. Values emitted in the same chunk after one are discarded\n * (their producing side effects may already have run). The `Loop.next` /\n * `Loop.stop` helpers each emit a single terminal step, so concatenate\n * your values before them (`values.pipe(Stream.concat(Loop.next(state)))`).\n */\nimport {\n  Array as Arr,\n  Cause,\n  Channel,\n  Data,\n  Effect,\n  Exit,\n  Function,\n  Match,\n  Option,\n  Ref,\n  Scope,\n  Stream,\n  SubscriptionRef,\n} from \"effect\"\nimport { IncompleteTurn } from \"../domain/AiError.js\"\nimport { isTurnComplete, type Turn, type TurnEvent } from \"../domain/Turn.js\"\n\n// ---------------------------------------------------------------------------\n// Step type - the body's emit shape\n// ---------------------------------------------------------------------------\n\n/**\n * The tagged union a body emits per pull. `Value` carries a payload that\n * flows downstream. `Next` ends the current iteration and continues with a\n * new state. `Stop` ends the loop entirely with no carried state.\n * `StopWith` also ends the loop but carries a final state that `loopOver`\n * will thread to the next input and `loopWithState` will write to its\n * `SubscriptionRef` before the loop ends. Plain `loop` has no next\n * iteration to apply it to and treats `StopWith` like `Stop`.\n *\n * `Stop` is intentionally `{}` so the bare `stop()` helper doesn't\n * constrain `S` from a body's stream type — every body has a `Stop`\n * variant in its union, and forcing `S` to flow through it would break\n * inference whenever the body never uses `next` / `stop(state)`.\n */\nexport type Step<A, S> = Data.TaggedEnum<{\n  Value: { readonly value: A }\n  Next: { readonly state: S }\n  Stop: {}\n  StopWith: { readonly state: S }\n}>\n\ninterface StepDef extends Data.TaggedEnum.WithGenerics<2> {\n  readonly taggedEnum: Step<this[\"A\"], this[\"B\"]>\n}\n\nconst Step = Data.taggedEnum<StepDef>()\n\n/** Wrap a value so it flows through the loop to downstream consumers. */\nexport const value = <A>(a: A): Step<A, never> => Step.Value({ value: a })\n\n/**\n * End the current iteration and continue with a new state. Emits a single\n * terminal `Next` step as a one-element stream, so it slots directly into a\n * loop body or after a run of values: `values.pipe(Stream.concat(next(s)))`.\n */\nexport const next = <S>(state: S): Stream.Stream<Step<never, S>> =>\n  Stream.succeed(Step.Next({ state }))\n\n/**\n * End the loop. Called with no argument it emits a bare `Stop`; called with\n * a state it emits `StopWith(state)` — `loopOver` threads that final state\n * to the next input and `loopWithState` writes it to its `SubscriptionRef`\n * before the loop ends. Either way it returns a single-element stream, so\n * return it directly from a loop body.\n */\nexport const stop = <S = never>(state?: S): Stream.Stream<Step<never, S>> =>\n  Stream.succeed<Step<never, S>>(state === undefined ? Step.Stop() : Step.StopWith({ state }))\n\n// ---------------------------------------------------------------------------\n// onTurnComplete - turn-aware stream operator for loop bodies\n// ---------------------------------------------------------------------------\n\n/**\n * Lift a provider's `Stream<TurnEvent>` into a loop body's `Stream<Step<TurnEvent | A, S>>`.\n * Each delta passes through as `value(delta)` (including the terminal\n * `TurnComplete`, so the consumer sees turn boundaries naturally). Once\n * the terminal arrives, `then(turn)` runs and its returned stream of loop\n * steps (typically tool outputs followed by `next(state)` or `stop()`) is\n * concatenated.\n *\n * Pre-pipe transforms (`Stream.tap` / `Stream.map` / `Stream.filter`) on\n * the raw delta stream cover anything an `emit`-style callback would do.\n *\n * If the upstream ends without a `TurnComplete`, the resulting stream\n * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if\n * you want to recover.\n *\n * Dual: data-first `onTurnComplete(deltas, then)` and data-last\n * `deltas.pipe(onTurnComplete(then))` both work.\n */\nexport const onTurnComplete: {\n  <S, A, E2 = never, R2 = never>(\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,\n  ): <E, R>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n  ) => Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>\n  <S, A, E, R, E2 = never, R2 = never>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,\n  ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>\n} = Function.dual(\n  2,\n  <S, A, E, R, E2, R2>(\n    deltas: Stream.Stream<TurnEvent, E, R>,\n    then: (turn: Turn) => Effect.Effect<Stream.Stream<Step<A, S>, E2, R2>, E2, R2>,\n  ): Stream.Stream<Step<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const turnRef = yield* Ref.make<Option.Option<Turn>>(Option.none())\n\n        const events: Stream.Stream<Step<TurnEvent, S>, E, R> = deltas.pipe(\n          Stream.tap((delta) =>\n            isTurnComplete(delta) ? Ref.set(turnRef, Option.some(delta.turn)) : Effect.void,\n          ),\n          Stream.map(value),\n        )\n\n        const continuation = Stream.unwrap(\n          Effect.gen(function* () {\n            const opt = yield* Ref.get(turnRef)\n            if (Option.isNone(opt)) return yield* new IncompleteTurn({})\n            return yield* then(opt.value)\n          }),\n        )\n\n        return Stream.concat(events, continuation)\n      }),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// Internal helpers\n// ---------------------------------------------------------------------------\n\nconst isNonEmpty = <A>(array: ReadonlyArray<A>): array is readonly [A, ...Array<A>] =>\n  array.length > 0\n\ntype CurrentBody<S, A, E, R> = {\n  readonly scope: Scope.Closeable\n  readonly pull: Effect.Effect<ReadonlyArray<Step<A, S>>, E | Cause.Done<void>, R>\n}\n\nconst closeBody = <S, A, E, R>(\n  current: CurrentBody<S, A, E, R>,\n  exit: Exit.Exit<unknown, unknown>,\n) => Scope.close(current.scope, exit)\n\n/**\n * Walk a chunk of `Step<A, S>` until a terminal `Next` or `Stop` is found.\n * Returns the unwrapped values seen so far and (optionally) the terminal\n * step. Anything in the chunk after the terminal is discarded - its\n * producing side effects may have run, but downstream never sees it.\n */\nconst partitionChunk = <A, S>(\n  chunk: ReadonlyArray<Step<A, S>>,\n): {\n  readonly values: ReadonlyArray<A>\n  readonly decision: Option.Option<Step<A, S>>\n} => {\n  const [valueSteps, rest] = Arr.span(\n    chunk,\n    (e): e is Step<A, S> & { _tag: \"Value\" } => e._tag === \"Value\",\n  )\n  return {\n    values: valueSteps.map((e) => e.value),\n    decision: Arr.head(rest),\n  }\n}\n\n// ---------------------------------------------------------------------------\n// Public API\n// ---------------------------------------------------------------------------\n\ntype LoopBody<S, A, E, R> = (\n  state: S,\n) => Stream.Stream<Step<A, S>, E, R> | Effect.Effect<Stream.Stream<Step<A, S>, E, R>, E, R>\n\n/**\n * Drive a state-threaded loop body. Each iteration runs `body(state)` to get\n * a `Stream<Step<A, S>>`; values flow downstream, `next(s)` continues with\n * a new state, `stop()` ends the loop. See the file header for the full\n * pull-based execution model.\n *\n * Dual: data-first `loop(initial, body)` and data-last `loop(body)(initial)`\n * (or `pipe(initial, loop(body))`) both work.\n */\nexport const loop: {\n  <S, A, E, R>(body: LoopBody<S, A, E, R>): (initial: S) => Stream.Stream<A, E, R>\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R>\n} = Function.dual(\n  2,\n  <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>): Stream.Stream<A, E, R> =>\n    Stream.scoped(\n      Stream.fromPull(\n        Effect.gen(function* () {\n          const outerScope = yield* Effect.scope\n          let state = initial\n          let current: CurrentBody<S, A, E, R> | undefined\n          let done = false\n\n          const closeActive = (\n            active: CurrentBody<S, A, E, R>,\n            exit: Exit.Exit<unknown, unknown>,\n          ) => {\n            const isActive = current === active\n            if (isActive) current = undefined\n            // Scope.close is idempotent. Multiple paths can race to close the\n            // active body during cancellation/failure, so closing twice is safe.\n            return closeBody(active, exit)\n          }\n\n          yield* Scope.addFinalizerExit(outerScope, (exit) =>\n            current === undefined ? Effect.void : closeActive(current, exit),\n          )\n\n          const pull = Effect.gen(function* () {\n            while (true) {\n              if (done) return yield* Cause.done()\n\n              if (current === undefined) {\n                const result = body(state)\n                const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result\n                const bodyScope = yield* Scope.fork(outerScope)\n                const bodyPull = yield* Channel.toPullScoped(\n                  Stream.toChannel(stream),\n                  bodyScope,\n                ).pipe(Effect.onError((cause) => Scope.close(bodyScope, Exit.failCause(cause))))\n                current = { scope: bodyScope, pull: bodyPull }\n              }\n\n              const active = current\n              const chunk = yield* active.pull.pipe(\n                Effect.catchIf(Cause.isDone, () =>\n                  closeActive(active, Exit.void).pipe(\n                    Effect.as(undefined as ReadonlyArray<Step<A, S>> | undefined),\n                  ),\n                ),\n                Effect.onError((cause) => closeActive(active, Exit.failCause(cause))),\n              )\n\n              if (chunk === undefined) {\n                done = true\n                return yield* Cause.done()\n              }\n\n              const { values, decision } = partitionChunk(chunk)\n\n              if (Option.isSome(decision)) {\n                yield* closeActive(active, Exit.void)\n                if (decision.value._tag === \"Stop\" || decision.value._tag === \"StopWith\") {\n                  // `loop` has no next iteration to apply StopWith's state to;\n                  // the state lands in `loopOver`'s outer ref or\n                  // `loopWithState`'s SubscriptionRef via their taps.\n                  done = true\n                } else if (decision.value._tag === \"Next\") {\n                  state = decision.value.state\n                }\n              }\n\n              // Emit the values seen so far if any. Chunks from a Stream pull\n              // are non-empty, so when `decision` is `None` every step was\n              // a `Value` and `values` is non-empty here. With a decision and\n              // no preceding values, fall through to the next iteration.\n              if (isNonEmpty(values)) return values\n            }\n          })\n\n          return pull\n        }),\n      ),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// loopOver - stream-driven sibling of loop. One input item runs a full\n// multi-turn inner loop.\n// ---------------------------------------------------------------------------\n\ntype LoopOverBody<S, I, A, E, R> = (\n  state: S,\n  input: I,\n) => Stream.Stream<Step<A, S>, E, R> | Effect.Effect<Stream.Stream<Step<A, S>, E, R>, E, R>\n\n/**\n * Input-driven sibling of `loop`. For each item pulled from the input\n * stream, runs an inner seed-driven `loop` whose body is\n * `(s) => body(s, item)`. State is threaded across input items.\n *\n * **Per-input semantics — the body emits standard `Step<A, S>`:**\n *   - `value(a)`: emit `a` downstream\n *   - `next(s)`: re-run the body with the SAME input and new state `s`\n *     (multi-turn within one input — e.g. multiple model turns + tool\n *     calls for one document)\n *   - `stop()`: end this input's inner loop, advance to the next input\n *     (state preserved)\n *   - body stream ending without a decision: same as `stop()` (advance)\n *\n * **Outer termination:** the input stream ending. To halt programmatically\n * from within, end the input stream upstream (`Stream.takeWhile`, a\n * `SubscriptionRef` gate, etc.). Reserving `stop()` for per-item\n * advancement is what makes the common \"stream of documents, multi-turn\n * conversation per document\" shape readable.\n *\n * Dual: data-first `loopOver(input, initial, body)` and data-last\n * `input.pipe(loopOver(initial, body))` both work.\n */\nexport const loopOver: {\n  <S, I, A, E, R>(\n    initial: S,\n    body: LoopOverBody<S, I, A, E, R>,\n  ): <EI, RI>(input: Stream.Stream<I, EI, RI>) => Stream.Stream<A, E | EI, R | RI>\n  <S, I, A, E, R, EI, RI>(\n    input: Stream.Stream<I, EI, RI>,\n    initial: S,\n    body: LoopOverBody<S, I, A, E, R>,\n  ): Stream.Stream<A, E | EI, R | RI>\n} = Function.dual(\n  3,\n  <S, I, A, E, R, EI, RI>(\n    input: Stream.Stream<I, EI, RI>,\n    initial: S,\n    body: LoopOverBody<S, I, A, E, R>,\n  ): Stream.Stream<A, E | EI, R | RI> =>\n    Stream.unwrap(\n      Effect.gen(function* () {\n        const stateRef = yield* Ref.make<S>(initial)\n        return input.pipe(\n          Stream.flatMap((item) =>\n            Stream.unwrap(\n              Effect.gen(function* () {\n                const state = yield* Ref.get(stateRef)\n                // Capture Next states (and stop(state)'s final state) into the\n                // outer ref so the LAST state seen in this input's inner\n                // loop is what the next input starts from.\n                const wrappedBody = (s: S) => {\n                  const result = body(s, item)\n                  const stream = Effect.isEffect(result) ? Stream.unwrap(result) : result\n                  return stream.pipe(\n                    Stream.tap((step) =>\n                      Match.value(step).pipe(\n                        Match.tags({\n                          Next: (e) => Ref.set(stateRef, e.state),\n                          StopWith: (e) => Ref.set(stateRef, e.state),\n                        }),\n                        Match.orElse(() => Effect.void),\n                      ),\n                    ),\n                  )\n                }\n                return loop(state, wrappedBody)\n              }),\n            ),\n          ),\n        )\n      }),\n    ),\n)\n\n// ---------------------------------------------------------------------------\n// loopWithState - same body protocol, plus a live state observable.\n// ---------------------------------------------------------------------------\n\n/**\n * Like `loop`, but exposes the current loop state as a `SubscriptionRef`\n * alongside the value stream.\n *\n * Allocates one `SubscriptionRef<S>` seeded with `initial`, then runs the\n * loop with a wrapped body that taps every `Next(s)` step into the ref\n * before forwarding it. The caller decides how to consume both channels:\n *\n *   - **Final state**: drain the stream, then `SubscriptionRef.get(state)`\n *     - the ref holds the state from the last `Next` (or `initial` if the\n *     loop ended without advancing).\n *   - **Live transitions**: `SubscriptionRef.changes(state)` is a\n *     `Stream<S>` of every state observed; subscribe alongside the value\n *     stream.\n *   - **Mid-iteration peek**: `SubscriptionRef.get(state)` at any time.\n *\n * The returned stream and ref are independent of each other - the ref\n * lives outside the stream's scope, so reading it after the stream\n * completes is safe.\n */\nexport const loopWithState = <S, A, E, R>(\n  initial: S,\n  body: LoopBody<S, A, E, R>,\n): Effect.Effect<{\n  readonly stream: Stream.Stream<A, E, R>\n  readonly state: SubscriptionRef.SubscriptionRef<S>\n}> =>\n  Effect.gen(function* () {\n    const stateRef = yield* SubscriptionRef.make(initial)\n\n    const tap = (stream: Stream.Stream<Step<A, S>, E, R>): Stream.Stream<Step<A, S>, E, R> =>\n      stream.pipe(\n        Stream.tap((step) =>\n          Match.value(step).pipe(\n            Match.tags({\n              Next: (e) => SubscriptionRef.set(stateRef, e.state),\n              StopWith: (e) => SubscriptionRef.set(stateRef, e.state),\n            }),\n            Match.orElse(() => Effect.void),\n          ),\n        ),\n      )\n\n    const wrappedBody: LoopBody<S, A, E, R> = (s) => {\n      const result = body(s)\n      return Effect.isEffect(result) ? Effect.map(result, tap) : tap(result)\n    }\n\n    return {\n      stream: loop(initial, wrappedBody),\n      state: stateRef,\n    }\n  })\n"],"mappings":"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"}