@effect-uai/core 0.4.0 → 0.5.1

package/dist/index.d.mts

@@ -1,15 +1,15 @@
-import { n as AiError_d_exports } from "./AiError-csR8Bhxx.mjs";
+import { n as AiError_d_exports } from "./AiError-CAX_48RU.mjs";
 import { a as Media_d_exports } from "./Media-D_CpcM1Z.mjs";
 import { o as Audio_d_exports } from "./Audio-BfCTGnH3.mjs";
-import { o as Image_d_exports } from "./Image-DxyXqzAM.mjs";
-import { f as Items_d_exports } from "./Items-Hg5AsYxl.mjs";
+import { o as Image_d_exports } from "./Image-HNmMpMTh.mjs";
+import { f as Items_d_exports } from "./Items-BH8xUkoR.mjs";
 import { t as Music_d_exports } from "./domain/Music.mjs";
 import { t as Transcript_d_exports } from "./domain/Transcript.mjs";
-import { a as StructuredFormat_d_exports } from "./StructuredFormat-Cl41C56K.mjs";
-import { a as Turn_d_exports } from "./Turn-7geUcKsf.mjs";
+import { a as StructuredFormat_d_exports } from "./StructuredFormat-BbN4dosH.mjs";
+import { a as Turn_d_exports } from "./Turn-0CwCAyVe.mjs";
 import { t as Embedding_d_exports } from "./embedding-model/Embedding.mjs";
 import { t as EmbeddingModel_d_exports } from "./embedding-model/EmbeddingModel.mjs";
-import { l as Tool_d_exports } from "./Tool-B8B5qVEy.mjs";
+import { l as Tool_d_exports } from "./Tool-87ViKCCO.mjs";
 import { t as LanguageModel_d_exports } from "./language-model/LanguageModel.mjs";
 import { t as MusicGenerator_d_exports } from "./music-generator/MusicGenerator.mjs";
 import { t as SpeechSynthesizer_d_exports } from "./speech-synthesizer/SpeechSynthesizer.mjs";

package/dist/language-model/LanguageModel.d.mts

@@ -1,13 +1,15 @@
-import { t as AiError } from "../AiError-csR8Bhxx.mjs";
-import { d as Item } from "../Items-Hg5AsYxl.mjs";
-import { i as StructuredFormat } from "../StructuredFormat-Cl41C56K.mjs";
-import { i as TurnEvent } from "../Turn-7geUcKsf.mjs";
-import { o as ToolDescriptor } from "../Tool-B8B5qVEy.mjs";
-import { Context, Stream } from "effect";
+import { d as RateLimited, l as IncompleteTurn, m as Unavailable, p as Timeout, t as AiError } from "../AiError-CAX_48RU.mjs";
+import { d as Item } from "../Items-BH8xUkoR.mjs";
+import { i as StructuredFormat } from "../StructuredFormat-BbN4dosH.mjs";
+import { i as TurnEvent, r as Turn } from "../Turn-0CwCAyVe.mjs";
+import { o as ToolDescriptor } from "../Tool-87ViKCCO.mjs";
+import { Context, Effect, Schedule, Stream } from "effect";
+import * as _$effect_Types0 from "effect/Types";
+import * as _$effect_Cause0 from "effect/Cause";
 
 //#region src/language-model/LanguageModel.d.ts
 declare namespace LanguageModel_d_exports {
-  export { CommonRequest, LanguageModel, LanguageModelService, streamTurn };
+  export { CommonRequest, LanguageModel, LanguageModelService, Retryable, retry, streamTurn, turn };
 }
 /**
  * Cross-provider request shape. Every call carries its own `history` and
@@ -47,6 +49,26 @@ declare class LanguageModel extends LanguageModel_base {}
  * Stream the deltas of a single turn.
  */
 declare const streamTurn: (request: CommonRequest) => Stream.Stream<TurnEvent, AiError, LanguageModel>;
+/**
+ * Drain `streamTurn` and return the assembled `Turn` from the terminal
+ * `TurnComplete` event. Fails with `IncompleteTurn` if the stream ends
+ * without one. Derived from `streamTurn`; providers get it for free.
+ */
+declare const turn: (request: CommonRequest) => Effect.Effect<Turn, AiError | IncompleteTurn, LanguageModel>;
+declare const Retryable_base: new <A extends Record<string, any> = {}>(args: _$effect_Types0.VoidIfEmpty<{ readonly [P in keyof A as P extends "_tag" ? never : P]: A[P] }>) => _$effect_Cause0.YieldableError & {
+  readonly _tag: "RetryableAi";
+} & Readonly<A>;
+/** Internal wrapper around the retryable subset of `AiError`. */
+declare class Retryable extends Retryable_base<{
+  readonly cause: RateLimited | Unavailable | Timeout;
+}> {}
+/**
+ * Retry a stream of `AiError` on the retryable subset
+ * (`RateLimited | Unavailable | Timeout`). Other failures bypass the
+ * schedule and propagate unchanged. Like all `Stream.retry`, the entire
+ * stream re-runs — deltas before the failure replay on the next attempt.
+ */
+declare const retry: <Out>(schedule: Schedule.Schedule<Out, Retryable>) => <A, R>(stream: Stream.Stream<A, AiError, R>) => Stream.Stream<A, AiError, R>;
 //#endregion
-export { CommonRequest, LanguageModel, LanguageModelService, streamTurn, LanguageModel_d_exports as t };
+export { CommonRequest, LanguageModel, LanguageModelService, Retryable, retry, streamTurn, LanguageModel_d_exports as t, turn };
 //# sourceMappingURL=LanguageModel.d.mts.map

package/dist/language-model/LanguageModel.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"LanguageModel.d.mts","names":[],"sources":["../../src/language-model/LanguageModel.ts"],"mappings":";;;;;;;;;;;;;;;;;KAaY,aAAA;EAAA,SACD,OAAA,EAAS,aAAA,CAAc,IAAA;;AADlC;;;WAMW,KAAA;EAAA,SACA,KAAA,GAAQ,aAAA,CAAc,cAAA;EAAA,SACtB,UAAA;IAAA,SAIM,IAAA;IAAA,SAA2B,IAAA;EAAA;EAAA,SACjC,WAAA;EAAA,SACA,IAAA;EAAA,SACA,eAAA;EAduB;;;;;;EAAA,SAqBvB,UAAA,GAAa,gBAAA;AAAA;AAAA,KAGZ,oBAAA;EAAA,SACD,UAAA,GAAa,OAAA,EAAS,aAAA,KAAkB,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA;AAAA;AAAA,cAC3E,kBAAA;cAEY,aAAA,SAAsB,kBAAA;;;AAJnC;cAWa,UAAA,GACX,OAAA,EAAS,aAAA,KACR,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA,EAAiB,aAAA"}
+{"version":3,"file":"LanguageModel.d.mts","names":[],"sources":["../../src/language-model/LanguageModel.ts"],"mappings":";;;;;;;;;;;;;;;;;;;KAaY,aAAA;EAAA,SACD,OAAA,EAAS,aAAA,CAAc,IAAA;;;;;WAKvB,KAAA;EAAA,SACA,KAAA,GAAQ,aAAA,CAAc,cAAA;EAAA,SACtB,UAAA;IAAA,SAIM,IAAA;IAAA,SAA2B,IAAA;EAAA;EAAA,SACjC,WAAA;EAAA,SACA,IAAA;EAAA,SACA,eAAA;EAOa;;;;;;EAAA,SAAb,UAAA,GAAa,gBAAA;AAAA;AAAA,KAGZ,oBAAA;EAAA,SACD,UAAA,GAAa,OAAA,EAAS,aAAA,KAAkB,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA;AAAA;AAAA,cAC3E,kBAAA;cAEY,aAAA,SAAsB,kBAAA;;;;cAOtB,UAAA,GACX,OAAA,EAAS,aAAA,KACR,MAAA,CAAO,MAAA,CAAO,SAAA,EAAW,OAAA,EAAiB,aAAA;;;;AAb7C;;cAqBa,IAAA,GACX,OAAA,EAAS,aAAA,KACR,MAAA,CAAO,MAAA,CAAO,IAAA,EAAM,OAAA,GAAkB,cAAA,EAAwB,aAAA;AAAA,cAW9D,cAAA;;;;cAOU,SAAA,SAAkB,cAAA;EAAA,SACpB,KAAA,EAAO,WAAA,GAAsB,WAAA,GAAsB,OAAA;AAAA;;;;;;;cAoBjD,KAAA,QACL,QAAA,EAAU,QAAA,CAAS,QAAA,CAAS,GAAA,EAAK,SAAA,aAChC,MAAA,EAAQ,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,OAAA,EAAiB,CAAA,MAAK,MAAA,CAAO,MAAA,CAAO,CAAA,EAAG,OAAA,EAAiB,CAAA"}

package/dist/language-model/LanguageModel.mjs

@@ -1,16 +1,46 @@
 import { n as __exportAll } from "../chunk-uyGKjUfl.mjs";
-import { Context, Effect, Stream } from "effect";
+import { IncompleteTurn } from "../domain/AiError.mjs";
+import { isTurnComplete } from "../domain/Turn.mjs";
+import { Array, Context, Data, Effect, Option, Stream } from "effect";
 //#region src/language-model/LanguageModel.ts
 var LanguageModel_exports = /* @__PURE__ */ __exportAll({
 	LanguageModel: () => LanguageModel,
-	streamTurn: () => streamTurn
+	Retryable: () => Retryable,
+	retry: () => retry,
+	streamTurn: () => streamTurn,
+	turn: () => turn
 });
 var LanguageModel = class extends Context.Service()("@betalyra/effect-uai/LanguageModel") {};
 /**
 * Stream the deltas of a single turn.
 */
 const streamTurn = (request) => Stream.unwrap(Effect.map(LanguageModel.asEffect(), (m) => m.streamTurn(request)));
+/**
+* Drain `streamTurn` and return the assembled `Turn` from the terminal
+* `TurnComplete` event. Fails with `IncompleteTurn` if the stream ends
+* without one. Derived from `streamTurn`; providers get it for free.
+*/
+const turn = (request) => streamTurn(request).pipe(Stream.runCollect, Effect.flatMap((events) => Array.findLast(events, isTurnComplete).pipe(Option.match({
+	onNone: () => Effect.fail(new IncompleteTurn({})),
+	onSome: (e) => Effect.succeed(e.turn)
+}))));
+/** Internal wrapper around the retryable subset of `AiError`. */
+var Retryable = class extends Data.TaggedError("RetryableAi") {};
+const isRetryable = (e) => e._tag === "RateLimited" || e._tag === "Unavailable" || e._tag === "Timeout";
+/**
+* Retry a stream of `AiError` on the retryable subset
+* (`RateLimited | Unavailable | Timeout`). Other failures bypass the
+* schedule and propagate unchanged. Like all `Stream.retry`, the entire
+* stream re-runs — deltas before the failure replay on the next attempt.
+*/
+const retry = (schedule) => (stream) => stream.pipe(Stream.map((value) => ({
+	_tag: "Item",
+	value
+})), Stream.catchIf(isRetryable, (cause) => Stream.fail(new Retryable({ cause })), (cause) => Stream.succeed({
+	_tag: "Terminal",
+	cause
+})), Stream.retry(schedule), Stream.catchTag("RetryableAi", (e) => Stream.fail(e.cause)), Stream.flatMap((item) => item._tag === "Item" ? Stream.succeed(item.value) : Stream.fail(item.cause)));
 //#endregion
-export { LanguageModel, streamTurn, LanguageModel_exports as t };
+export { LanguageModel, Retryable, retry, streamTurn, LanguageModel_exports as t, turn };
 
 //# sourceMappingURL=LanguageModel.mjs.map

package/dist/language-model/LanguageModel.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"LanguageModel.mjs","names":[],"sources":["../../src/language-model/LanguageModel.ts"],"sourcesContent":["import { Context, Effect, Stream } from \"effect\"\nimport * as AiError from \"../domain/AiError.js\"\nimport type { Item } from \"../domain/Items.js\"\nimport type * as StructuredFormat from \"../structured-format/StructuredFormat.js\"\nimport type { ToolDescriptor } from \"../tool/Tool.js\"\nimport { isTurnComplete, type Turn, type TurnEvent } from \"../domain/Turn.js\"\n\n/**\n * Cross-provider request shape. Every call carries its own `history` and\n * `model` - models are not bound at layer construction. Anything specific\n * to a single provider (reasoning effort, prompt caching, store flags,\n * ...) lives in that provider's own request interface, which extends this.\n */\nexport type CommonRequest = {\n  readonly history: ReadonlyArray<Item>\n  /**\n   * Model identifier. Each provider narrows this to its typed literal union,\n   * so code that yields a typed provider tag gets autocompletion.\n   */\n  readonly model: string\n  readonly tools?: ReadonlyArray<ToolDescriptor>\n  readonly toolChoice?:\n    | \"auto\"\n    | \"required\"\n    | \"none\"\n    | { readonly type: \"function\"; readonly name: string }\n  readonly temperature?: number\n  readonly topP?: number\n  readonly maxOutputTokens?: number\n  /**\n   * Schema-bound JSON output. The provider constrains the wire to match the\n   * schema; pair with `Turn.toStructured` for runtime validation. Supported\n   * across all current providers (OpenAI Responses json_schema, Anthropic\n   * `output_config`, Gemini `responseJsonSchema`).\n   */\n  readonly structured?: StructuredFormat.StructuredFormat<unknown>\n}\n\nexport type LanguageModelService = {\n  readonly streamTurn: (request: CommonRequest) => Stream.Stream<TurnEvent, AiError.AiError>\n}\n\nexport class LanguageModel extends Context.Service<LanguageModel, LanguageModelService>()(\n  \"@betalyra/effect-uai/LanguageModel\",\n) {}\n\n/**\n * Stream the deltas of a single turn.\n */\nexport const streamTurn = (\n  request: CommonRequest,\n): Stream.Stream<TurnEvent, AiError.AiError, LanguageModel> =>\n  Stream.unwrap(Effect.map(LanguageModel.asEffect(), (m) => m.streamTurn(request)))\n"],"mappings":";;;;;;;AA0CA,IAAa,gBAAb,cAAmC,QAAQ,SAA8C,CACvF,qCACD,CAAC;;;;AAKF,MAAa,cACX,YAEA,OAAO,OAAO,OAAO,IAAI,cAAc,UAAU,GAAG,MAAM,EAAE,WAAW,QAAQ,CAAC,CAAC"}
+{"version":3,"file":"LanguageModel.mjs","names":["Arr","AiError.IncompleteTurn"],"sources":["../../src/language-model/LanguageModel.ts"],"sourcesContent":["import { Array as Arr, Context, Data, Effect, Option, type Schedule, Stream } from \"effect\"\nimport * as AiError from \"../domain/AiError.js\"\nimport type { Item } from \"../domain/Items.js\"\nimport type * as StructuredFormat from \"../structured-format/StructuredFormat.js\"\nimport type { ToolDescriptor } from \"../tool/Tool.js\"\nimport { isTurnComplete, type Turn, type TurnEvent } from \"../domain/Turn.js\"\n\n/**\n * Cross-provider request shape. Every call carries its own `history` and\n * `model` - models are not bound at layer construction. Anything specific\n * to a single provider (reasoning effort, prompt caching, store flags,\n * ...) lives in that provider's own request interface, which extends this.\n */\nexport type CommonRequest = {\n  readonly history: ReadonlyArray<Item>\n  /**\n   * Model identifier. Each provider narrows this to its typed literal union,\n   * so code that yields a typed provider tag gets autocompletion.\n   */\n  readonly model: string\n  readonly tools?: ReadonlyArray<ToolDescriptor>\n  readonly toolChoice?:\n    | \"auto\"\n    | \"required\"\n    | \"none\"\n    | { readonly type: \"function\"; readonly name: string }\n  readonly temperature?: number\n  readonly topP?: number\n  readonly maxOutputTokens?: number\n  /**\n   * Schema-bound JSON output. The provider constrains the wire to match the\n   * schema; pair with `Turn.toStructured` for runtime validation. Supported\n   * across all current providers (OpenAI Responses json_schema, Anthropic\n   * `output_config`, Gemini `responseJsonSchema`).\n   */\n  readonly structured?: StructuredFormat.StructuredFormat<unknown>\n}\n\nexport type LanguageModelService = {\n  readonly streamTurn: (request: CommonRequest) => Stream.Stream<TurnEvent, AiError.AiError>\n}\n\nexport class LanguageModel extends Context.Service<LanguageModel, LanguageModelService>()(\n  \"@betalyra/effect-uai/LanguageModel\",\n) {}\n\n/**\n * Stream the deltas of a single turn.\n */\nexport const streamTurn = (\n  request: CommonRequest,\n): Stream.Stream<TurnEvent, AiError.AiError, LanguageModel> =>\n  Stream.unwrap(Effect.map(LanguageModel.asEffect(), (m) => m.streamTurn(request)))\n\n/**\n * Drain `streamTurn` and return the assembled `Turn` from the terminal\n * `TurnComplete` event. Fails with `IncompleteTurn` if the stream ends\n * without one. Derived from `streamTurn`; providers get it for free.\n */\nexport const turn = (\n  request: CommonRequest,\n): Effect.Effect<Turn, AiError.AiError | AiError.IncompleteTurn, LanguageModel> =>\n  streamTurn(request).pipe(\n    Stream.runCollect,\n    Effect.flatMap((events) =>\n      Arr.findLast(events, isTurnComplete).pipe(\n        Option.match({\n          onNone: () => Effect.fail(new AiError.IncompleteTurn({})),\n          onSome: (e) => Effect.succeed(e.turn),\n        }),\n      ),\n    ),\n  )\n\n// ---------------------------------------------------------------------------\n// retry — retry the retryable subset of AiError, let other failures escape\n// ---------------------------------------------------------------------------\n\n/** Internal wrapper around the retryable subset of `AiError`. */\nexport class Retryable extends Data.TaggedError(\"RetryableAi\")<{\n  readonly cause: AiError.RateLimited | AiError.Unavailable | AiError.Timeout\n}> {}\n\nconst isRetryable = (\n  e: AiError.AiError,\n): e is AiError.RateLimited | AiError.Unavailable | AiError.Timeout =>\n  e._tag === \"RateLimited\" || e._tag === \"Unavailable\" || e._tag === \"Timeout\"\n\n// Lift events to Items, non-retryable failures to Terminal values (escape\n// retry), retryable failures to wrapped errors (only thing retry sees).\ntype Lifted<A> =\n  | { readonly _tag: \"Item\"; readonly value: A }\n  | { readonly _tag: \"Terminal\"; readonly cause: AiError.AiError }\n\n/**\n * Retry a stream of `AiError` on the retryable subset\n * (`RateLimited | Unavailable | Timeout`). Other failures bypass the\n * schedule and propagate unchanged. Like all `Stream.retry`, the entire\n * stream re-runs — deltas before the failure replay on the next attempt.\n */\nexport const retry =\n  <Out>(schedule: Schedule.Schedule<Out, Retryable>) =>\n  <A, R>(stream: Stream.Stream<A, AiError.AiError, R>): Stream.Stream<A, AiError.AiError, R> =>\n    stream.pipe(\n      Stream.map((value): Lifted<A> => ({ _tag: \"Item\", value })),\n      Stream.catchIf(\n        isRetryable,\n        (cause) => Stream.fail(new Retryable({ cause })),\n        (cause) => Stream.succeed<Lifted<A>>({ _tag: \"Terminal\", cause }),\n      ),\n      Stream.retry(schedule),\n      Stream.catchTag(\"RetryableAi\", (e) => Stream.fail<AiError.AiError>(e.cause)),\n      Stream.flatMap((item) =>\n        item._tag === \"Item\" ? Stream.succeed(item.value) : Stream.fail(item.cause),\n      ),\n    )\n"],"mappings":";;;;;;;;;;;;AA0CA,IAAa,gBAAb,cAAmC,QAAQ,SAA8C,CACvF,qCACD,CAAC;;;;AAKF,MAAa,cACX,YAEA,OAAO,OAAO,OAAO,IAAI,cAAc,UAAU,GAAG,MAAM,EAAE,WAAW,QAAQ,CAAC,CAAC;;;;;;AAOnF,MAAa,QACX,YAEA,WAAW,QAAQ,CAAC,KAClB,OAAO,YACP,OAAO,SAAS,WACdA,MAAI,SAAS,QAAQ,eAAe,CAAC,KACnC,OAAO,MAAM;CACX,cAAc,OAAO,KAAK,IAAIC,eAAuB,EAAE,CAAC,CAAC;CACzD,SAAS,MAAM,OAAO,QAAQ,EAAE,KAAK;CACtC,CAAC,CACH,CACF,CACF;;AAOH,IAAa,YAAb,cAA+B,KAAK,YAAY,cAAc,CAE3D;AAEH,MAAM,eACJ,MAEA,EAAE,SAAS,iBAAiB,EAAE,SAAS,iBAAiB,EAAE,SAAS;;;;;;;AAcrE,MAAa,SACL,cACC,WACL,OAAO,KACL,OAAO,KAAK,WAAsB;CAAE,MAAM;CAAQ;CAAO,EAAE,EAC3D,OAAO,QACL,cACC,UAAU,OAAO,KAAK,IAAI,UAAU,EAAE,OAAO,CAAC,CAAC,GAC/C,UAAU,OAAO,QAAmB;CAAE,MAAM;CAAY;CAAO,CAAC,CAClE,EACD,OAAO,MAAM,SAAS,EACtB,OAAO,SAAS,gBAAgB,MAAM,OAAO,KAAsB,EAAE,MAAM,CAAC,EAC5E,OAAO,SAAS,SACd,KAAK,SAAS,SAAS,OAAO,QAAQ,KAAK,MAAM,GAAG,OAAO,KAAK,KAAK,MAAM,CAC5E,CACF"}

package/dist/language-model/LanguageModel.test.d.mts

@@ -0,0 +1 @@
+export { };

package/dist/language-model/LanguageModel.test.mjs

@@ -0,0 +1,143 @@
+import { ContentFiltered, IncompleteTurn, RateLimited, Timeout, Unavailable } from "../domain/AiError.mjs";
+import { assistantText, userText } from "../domain/Items.mjs";
+import { TurnEvent } from "../domain/Turn.mjs";
+import { LanguageModel, retry, turn } from "./LanguageModel.mjs";
+import { i as it, n as globalExpect, r as describe } from "../dist-DV5ISja1.mjs";
+import { layer } from "../testing/MockProvider.mjs";
+import { Cause, Effect, Exit, Layer, Option, Ref, Schedule, Stream } from "effect";
+//#region src/language-model/LanguageModel.test.ts
+const oneTextTurn = (text) => ({
+	items: [assistantText(text)],
+	usage: {
+		input_tokens: 1,
+		output_tokens: 1
+	},
+	stop_reason: "stop"
+});
+describe("LanguageModel.turn", () => {
+	it("returns the assembled Turn from the terminal TurnComplete event", async () => {
+		const expected = oneTextTurn("hello world");
+		const program = turn({
+			history: [userText("hi")],
+			model: "mock"
+		});
+		globalExpect(await Effect.runPromise(program.pipe(Effect.provide(layer([expected]))))).toEqual(expected);
+	});
+	it("fails with IncompleteTurn when the stream ends without TurnComplete", async () => {
+		const broken = Layer.succeed(LanguageModel, { streamTurn: () => Stream.fromIterable([TurnEvent.TextDelta({ text: "partial" })]) });
+		const program = turn({
+			history: [userText("hi")],
+			model: "mock"
+		});
+		const exit = await Effect.runPromise(Effect.exit(program.pipe(Effect.provide(broken))));
+		globalExpect(Exit.isFailure(exit)).toBe(true);
+		if (Exit.isFailure(exit)) {
+			const failure = Cause.findErrorOption(exit.cause);
+			globalExpect(Option.isSome(failure)).toBe(true);
+			if (Option.isSome(failure)) globalExpect(failure.value).toBeInstanceOf(IncompleteTurn);
+		}
+	});
+	it("propagates an AiError raised by streamTurn", async () => {
+		const rateLimited = new RateLimited({
+			provider: "mock",
+			raw: null
+		});
+		const failing = Layer.succeed(LanguageModel, { streamTurn: () => Stream.fail(rateLimited) });
+		const program = turn({
+			history: [],
+			model: "mock"
+		});
+		const exit = await Effect.runPromise(Effect.exit(program.pipe(Effect.provide(failing))));
+		globalExpect(Exit.isFailure(exit)).toBe(true);
+		if (Exit.isFailure(exit)) globalExpect(Cause.findErrorOption(exit.cause)).toEqual(Option.some(rateLimited));
+	});
+	it("returns the LAST TurnComplete when the stream contains multiple (defensive)", async () => {
+		const first = oneTextTurn("first");
+		const second = oneTextTurn("second");
+		const weird = Layer.succeed(LanguageModel, { streamTurn: () => Stream.fromIterable([TurnEvent.TurnComplete({ turn: first }), TurnEvent.TurnComplete({ turn: second })]) });
+		const program = turn({
+			history: [],
+			model: "mock"
+		});
+		globalExpect(await Effect.runPromise(program.pipe(Effect.provide(weird)))).toEqual(second);
+	});
+});
+describe("LanguageModel.retry", () => {
+	const textDelta = (text) => TurnEvent.TextDelta({ text });
+	const textTurn = (text) => ({
+		items: [assistantText(text)],
+		usage: {
+			input_tokens: 0,
+			output_tokens: 0
+		},
+		stop_reason: "stop"
+	});
+	const completeEvent = (text) => TurnEvent.TurnComplete({ turn: textTurn(text) });
+	const attemptStream = (attempts, plan) => Stream.unwrap(Ref.getAndUpdate(attempts, (n) => n + 1).pipe(Effect.map((n) => plan[Math.min(n, plan.length - 1)])));
+	it("retries on RateLimited and yields the success on the next attempt", async () => {
+		const program = Effect.gen(function* () {
+			const attempts = yield* Ref.make(0);
+			const stream = attemptStream(attempts, [Stream.fail(new RateLimited({
+				provider: "mock",
+				raw: null
+			})), Stream.fromIterable([textDelta("ok"), completeEvent("ok")])]).pipe(retry(Schedule.recurs(3)));
+			const events = yield* Stream.runCollect(stream);
+			const count = yield* Ref.get(attempts);
+			return {
+				events: Array.from(events),
+				count
+			};
+		});
+		const { events, count } = await Effect.runPromise(program);
+		globalExpect(count).toBe(2);
+		globalExpect(events.map((e) => e._tag)).toEqual(["TextDelta", "TurnComplete"]);
+	});
+	it("surfaces the underlying retryable failure when retries are exhausted", async () => {
+		const cause = new Unavailable({
+			provider: "mock",
+			raw: null
+		});
+		const stream = Stream.fail(cause).pipe(retry(Schedule.recurs(2)));
+		const exit = await Effect.runPromise(Effect.exit(Stream.runCollect(stream)));
+		globalExpect(Exit.isFailure(exit)).toBe(true);
+		if (Exit.isFailure(exit)) globalExpect(Cause.findErrorOption(exit.cause)).toEqual(Option.some(cause));
+	});
+	it("bypasses retry for non-retryable AiError (ContentFiltered)", async () => {
+		const program = Effect.gen(function* () {
+			const attempts = yield* Ref.make(0);
+			const cause = new ContentFiltered({
+				provider: "mock",
+				raw: null
+			});
+			const stream = attemptStream(attempts, [Stream.fail(cause)]).pipe(retry(Schedule.recurs(5)));
+			return {
+				exit: yield* Effect.exit(Stream.runCollect(stream)),
+				count: yield* Ref.get(attempts),
+				cause
+			};
+		});
+		const { exit, count, cause } = await Effect.runPromise(program);
+		globalExpect(count).toBe(1);
+		globalExpect(Exit.isFailure(exit)).toBe(true);
+		if (Exit.isFailure(exit)) globalExpect(Cause.findErrorOption(exit.cause)).toEqual(Option.some(cause));
+	});
+	it("preserves deltas emitted before a retryable failure (and replays on retry)", async () => {
+		const program = Effect.gen(function* () {
+			const stream = attemptStream(yield* Ref.make(0), [Stream.concat(Stream.succeed(textDelta("partial")), Stream.fail(new Timeout({
+				provider: "mock",
+				raw: null
+			}))), Stream.fromIterable([textDelta("partial"), completeEvent("done")])]).pipe(retry(Schedule.recurs(1)));
+			const events = yield* Stream.runCollect(stream);
+			return Array.from(events);
+		});
+		globalExpect((await Effect.runPromise(program)).map((e) => e._tag)).toEqual([
+			"TextDelta",
+			"TextDelta",
+			"TurnComplete"
+		]);
+	});
+});
+//#endregion
+export {};
+
+//# sourceMappingURL=LanguageModel.test.mjs.map

package/dist/language-model/LanguageModel.test.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"LanguageModel.test.mjs","names":["Items.assistantText","Items.userText","MockProvider.layer","AiError.IncompleteTurn","AiError.RateLimited","AiError.Unavailable","AiError.ContentFiltered","AiError.Timeout"],"sources":["../../src/language-model/LanguageModel.test.ts"],"sourcesContent":["import { Cause, Effect, Exit, Layer, Option, Ref, Schedule, Stream } from \"effect\"\nimport { describe, expect, it } from \"vitest\"\nimport * as AiError from \"../domain/AiError.js\"\nimport * as Items from \"../domain/Items.js\"\nimport { type Turn, TurnEvent } from \"../domain/Turn.js\"\nimport { LanguageModel, retry, turn } from \"./LanguageModel.js\"\nimport * as MockProvider from \"../testing/MockProvider.js\"\n\nconst oneTextTurn = (text: string): Turn => ({\n  items: [Items.assistantText(text)],\n  usage: { input_tokens: 1, output_tokens: 1 },\n  stop_reason: \"stop\",\n})\n\ndescribe(\"LanguageModel.turn\", () => {\n  it(\"returns the assembled Turn from the terminal TurnComplete event\", async () => {\n    const expected = oneTextTurn(\"hello world\")\n    const program = turn({ history: [Items.userText(\"hi\")], model: \"mock\" })\n\n    const result = await Effect.runPromise(\n      program.pipe(Effect.provide(MockProvider.layer([expected]))),\n    )\n\n    expect(result).toEqual(expected)\n  })\n\n  it(\"fails with IncompleteTurn when the stream ends without TurnComplete\", async () => {\n    // Custom service whose stream emits a single TextDelta and then ends.\n    const broken = Layer.succeed(LanguageModel, {\n      streamTurn: () => Stream.fromIterable<TurnEvent>([TurnEvent.TextDelta({ text: \"partial\" })]),\n    })\n\n    const program = turn({ history: [Items.userText(\"hi\")], model: \"mock\" })\n    const exit = await Effect.runPromise(Effect.exit(program.pipe(Effect.provide(broken))))\n\n    expect(Exit.isFailure(exit)).toBe(true)\n    if (Exit.isFailure(exit)) {\n      const failure = Cause.findErrorOption(exit.cause)\n      expect(Option.isSome(failure)).toBe(true)\n      if (Option.isSome(failure)) {\n        expect(failure.value).toBeInstanceOf(AiError.IncompleteTurn)\n      }\n    }\n  })\n\n  it(\"propagates an AiError raised by streamTurn\", async () => {\n    const rateLimited = new AiError.RateLimited({ provider: \"mock\", raw: null })\n    const failing = Layer.succeed(LanguageModel, {\n      streamTurn: () => Stream.fail<AiError.AiError>(rateLimited),\n    })\n\n    const program = turn({ history: [], model: \"mock\" })\n    const exit = await Effect.runPromise(Effect.exit(program.pipe(Effect.provide(failing))))\n\n    expect(Exit.isFailure(exit)).toBe(true)\n    if (Exit.isFailure(exit)) {\n      expect(Cause.findErrorOption(exit.cause)).toEqual(Option.some(rateLimited))\n    }\n  })\n\n  it(\"returns the LAST TurnComplete when the stream contains multiple (defensive)\", async () => {\n    // A misbehaving provider might emit two TurnComplete events; turn\n    // should pick the last one (the most recent assembled Turn).\n    const first = oneTextTurn(\"first\")\n    const second = oneTextTurn(\"second\")\n    const weird = Layer.succeed(LanguageModel, {\n      streamTurn: () =>\n        Stream.fromIterable<TurnEvent>([\n          TurnEvent.TurnComplete({ turn: first }),\n          TurnEvent.TurnComplete({ turn: second }),\n        ]),\n    })\n\n    const program = turn({ history: [], model: \"mock\" })\n    const result = await Effect.runPromise(program.pipe(Effect.provide(weird)))\n\n    expect(result).toEqual(second)\n  })\n})\n\ndescribe(\"LanguageModel.retry\", () => {\n  const textDelta = (text: string): TurnEvent => TurnEvent.TextDelta({ text })\n  const textTurn = (text: string): Turn => ({\n    items: [Items.assistantText(text)],\n    usage: { input_tokens: 0, output_tokens: 0 },\n    stop_reason: \"stop\",\n  })\n  const completeEvent = (text: string): TurnEvent =>\n    TurnEvent.TurnComplete({ turn: textTurn(text) })\n\n  // Builds a stream that emits a failure or success based on attempt counter.\n  // Each call to the returned Effect produces a fresh attempt stream.\n  const attemptStream = (\n    attempts: Ref.Ref<number>,\n    plan: ReadonlyArray<Stream.Stream<TurnEvent, AiError.AiError>>,\n  ): Stream.Stream<TurnEvent, AiError.AiError> =>\n    Stream.unwrap(\n      Ref.getAndUpdate(attempts, (n) => n + 1).pipe(\n        Effect.map((n) => plan[Math.min(n, plan.length - 1)]!),\n      ),\n    )\n\n  it(\"retries on RateLimited and yields the success on the next attempt\", async () => {\n    const program = Effect.gen(function* () {\n      const attempts = yield* Ref.make(0)\n      const stream = attemptStream(attempts, [\n        Stream.fail(new AiError.RateLimited({ provider: \"mock\", raw: null })),\n        Stream.fromIterable([textDelta(\"ok\"), completeEvent(\"ok\")]),\n      ]).pipe(retry(Schedule.recurs(3)))\n      const events = yield* Stream.runCollect(stream)\n      const count = yield* Ref.get(attempts)\n      return { events: Array.from(events), count }\n    })\n\n    const { events, count } = await Effect.runPromise(program)\n    expect(count).toBe(2)\n    expect(events.map((e) => e._tag)).toEqual([\"TextDelta\", \"TurnComplete\"])\n  })\n\n  it(\"surfaces the underlying retryable failure when retries are exhausted\", async () => {\n    const cause = new AiError.Unavailable({ provider: \"mock\", raw: null })\n    const stream = Stream.fail<AiError.AiError>(cause).pipe(retry(Schedule.recurs(2)))\n\n    const exit = await Effect.runPromise(Effect.exit(Stream.runCollect(stream)))\n    expect(Exit.isFailure(exit)).toBe(true)\n    if (Exit.isFailure(exit)) {\n      expect(Cause.findErrorOption(exit.cause)).toEqual(Option.some(cause))\n    }\n  })\n\n  it(\"bypasses retry for non-retryable AiError (ContentFiltered)\", async () => {\n    const program = Effect.gen(function* () {\n      const attempts = yield* Ref.make(0)\n      const cause = new AiError.ContentFiltered({ provider: \"mock\", raw: null })\n      const stream = attemptStream(attempts, [Stream.fail(cause)]).pipe(retry(Schedule.recurs(5)))\n      const exit = yield* Effect.exit(Stream.runCollect(stream))\n      const count = yield* Ref.get(attempts)\n      return { exit, count, cause }\n    })\n\n    const { exit, count, cause } = await Effect.runPromise(program)\n    expect(count).toBe(1) // no retry happened\n    expect(Exit.isFailure(exit)).toBe(true)\n    if (Exit.isFailure(exit)) {\n      expect(Cause.findErrorOption(exit.cause)).toEqual(Option.some(cause))\n    }\n  })\n\n  it(\"preserves deltas emitted before a retryable failure (and replays on retry)\", async () => {\n    // Documents the 'replays on retry' caveat in the JSDoc — first attempt\n    // emits a delta then fails; second attempt is a clean success. Consumer\n    // sees the first delta twice (once from the failed attempt, once from\n    // the replay).\n    const program = Effect.gen(function* () {\n      const attempts = yield* Ref.make(0)\n      const stream = attemptStream(attempts, [\n        Stream.concat(\n          Stream.succeed<TurnEvent>(textDelta(\"partial\")),\n          Stream.fail(new AiError.Timeout({ provider: \"mock\", raw: null })),\n        ),\n        Stream.fromIterable([textDelta(\"partial\"), completeEvent(\"done\")]),\n      ]).pipe(retry(Schedule.recurs(1)))\n      const events = yield* Stream.runCollect(stream)\n      return Array.from(events)\n    })\n\n    const events = await Effect.runPromise(program)\n    expect(events.map((e) => e._tag)).toEqual([\"TextDelta\", \"TextDelta\", \"TurnComplete\"])\n  })\n})\n"],"mappings":"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"}

package/dist/loop/Loop.d.mts

@@ -1,15 +1,24 @@
-import { l as IncompleteTurn } from "../AiError-csR8Bhxx.mjs";
-import { i as TurnEvent, r as Turn } from "../Turn-7geUcKsf.mjs";
+import { l as IncompleteTurn } from "../AiError-CAX_48RU.mjs";
+import { i as TurnEvent, r as Turn } from "../Turn-0CwCAyVe.mjs";
 import { Data, Effect, Stream, SubscriptionRef } from "effect";
 
 //#region src/loop/Loop.d.ts
 declare namespace Loop_d_exports {
-  export { Event, loop, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, value };
+  export { Event, loop, loopFrom, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, stopWith, stopWithAfter, value };
 }
 /**
  * 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.
+ * new state. `Stop` ends the loop entirely with no carried state.
+ * `StopWith` also ends the loop but carries a final state that `loopFrom`
+ * will thread to the next input and `loopWithState` will write to its
+ * `SubscriptionRef` before the loop ends. Plain `loop` has no next
+ * iteration to apply it to and treats `StopWith` like `Stop`.
+ *
+ * `Stop` is intentionally `{}` so the bare `stopEvent` / `stop` helpers
+ * don't constrain `S` from a body's stream type — every body has a `Stop`
+ * variant in its union, and forcing `S` to flow through it would break
+ * inference whenever the body never uses `next` / `stopWith`.
  */
 type Event<A, S> = Data.TaggedEnum<{
   Value: {
@@ -19,13 +28,27 @@ type Event<A, S> = Data.TaggedEnum<{
     readonly state: S;
   };
   Stop: {};
+  StopWith: {
+    readonly state: S;
+  };
 }>;
 /** Wrap a value so it flows through the loop to downstream consumers. */
 declare const value: <A>(a: A) => Event<A, never>;
 /** End the current iteration and continue with a new state. */
 declare const next: <S>(state: S) => Event<never, S>;
-/** The terminal `Stop` event. Use `stop` (the Stream) to end a loop body. */
+/**
+ * The terminal `Stop` event with no carried state. Use `stop` (the Stream)
+ * to end a loop body without communicating a final state.
+ */
 declare const stopEvent: Event<never, never>;
+/**
+ * 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.
+ */
+declare const stopWith: <S>(state: S) => Event<never, S>;
 /**
  * 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
@@ -36,13 +59,33 @@ declare const stop: Stream.Stream<Event<never, never>>;
  * 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.
  */
-declare const nextAfter: <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S) => Stream.Stream<Event<A, S>, E, R>;
+declare const nextAfter: {
+  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>;
+  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R>;
+};
 /**
  * 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)`.
  */
 declare const stopAfter: <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, never>, E, R>;
+/**
+ * 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.
+ */
+declare const stopWithAfter: {
+  <S>(state: S): <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>;
+  <S, A, E, R>(stream: Stream.Stream<A, E, R>, state: S): Stream.Stream<Event<A, S>, E, R>;
+};
 /**
  * General `nextAfter` variant: drain `stream` to the consumer, fold elements
  * into an accumulator, and at end-of-stream emit one `next(build(finalAcc))`.
@@ -50,12 +93,18 @@ declare const stopAfter: <A, E, R>(stream: Stream.Stream<A, E, R>) => Stream.Str
  * 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.
  */
-declare 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>;
+declare const nextAfterFold: {
+  <A, B, S>(initial: B, reduce: (acc: B, a: A) => B, build: (b: B) => S): <E, R>(stream: Stream.Stream<A, E, R>) => Stream.Stream<Event<A, S>, E, R>;
+  <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>;
+};
 /**
  * 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
+ * `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
  * concatenated.
@@ -63,11 +112,17 @@ declare const nextAfterFold: <A, B, S, E, R>(stream: Stream.Stream<A, E, R>, ini
  * 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
+ * If the upstream ends without a `TurnComplete`, the resulting stream
  * fails with `AiError.IncompleteTurn`. Catch it via `Stream.catchTag` if
  * you want to recover.
+ *
+ * Dual: data-first `onTurnComplete(deltas, then)` and data-last
+ * `deltas.pipe(onTurnComplete(then))` both work.
  */
-declare const onTurnComplete: <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>;
+declare const onTurnComplete: {
+  <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>;
+  <S, A, E, R, E2 = never, R2 = never>(deltas: Stream.Stream<TurnEvent, E, R>, then: (turn: Turn) => Effect.Effect<Stream.Stream<Event<A, S>, E2, R2>, E2, R2>): Stream.Stream<Event<TurnEvent | A, S>, E | E2 | IncompleteTurn, R | R2>;
+};
 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
@@ -82,6 +137,34 @@ declare 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>;
 };
+type LoopFromBody<S, I, A, E, R> = (state: S, input: I) => Stream.Stream<Event<A, S>, E, R> | Effect.Effect<Stream.Stream<Event<A, S>, E, R>, E, R>;
+/**
+ * Input-driven sibling of `loop`. For each item pulled from the input
+ * 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>`:**
+ *   - `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
+ *     (state preserved)
+ *   - 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
+ * 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.
+ */
+declare const loopFrom: {
+  <S, I, A, E, R>(initial: S, body: LoopFromBody<S, I, A, E, R>): <EI, RI>(input: Stream.Stream<I, EI, RI>) => Stream.Stream<A, E | EI, R | RI>;
+  <S, I, A, E, R, EI, RI>(input: Stream.Stream<I, EI, RI>, initial: S, body: LoopFromBody<S, I, A, E, R>): Stream.Stream<A, E | EI, R | RI>;
+};
 /**
  * Like `loop`, but exposes the current loop state as a `SubscriptionRef`
  * alongside the value stream.
@@ -107,5 +190,5 @@ declare const loopWithState: <S, A, E, R>(initial: S, body: LoopBody<S, A, E, R>
   readonly state: SubscriptionRef.SubscriptionRef<S>;
 }>;
 //#endregion
-export { Event, loop, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, Loop_d_exports as t, value };
+export { Event, loop, loopFrom, loopWithState, next, nextAfter, nextAfterFold, onTurnComplete, stop, stopAfter, stopEvent, stopWith, stopWithAfter, Loop_d_exports as t, value };
 //# sourceMappingURL=Loop.d.mts.map

package/dist/loop/Loop.d.mts.map

@@ -1 +1 @@
-{"version":3,"file":"Loop.d.mts","names":[],"sources":["../../src/loop/Loop.ts"],"mappings":"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"}
+{"version":3,"file":"Loop.d.mts","names":[],"sources":["../../src/loop/Loop.ts"],"mappings":"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"}