resultar 3.10.0 → 4.0.0

package/dist/agent/references/integrations.md

@@ -7,6 +7,7 @@ versions and local README files before copying an example.
 
 - [Choose A Request Package](#choose-a-request-package)
 - [Use The Schema-Agnostic Core](#use-the-schema-agnostic-core)
+- [Compose Requests In Tasks](#compose-requests-in-tasks)
 - [Use The TypeBox Adapter](#use-the-typebox-adapter)
 - [Use The Zod Adapter](#use-the-zod-adapter)
 - [Map Request Errors](#map-request-errors)
@@ -27,6 +28,10 @@ versions and local README files before copying an example.
 All three share the same transport implementation. The adapters add schema validation and re-export
 the public `resultar-request` types. Install only the core and schema adapter the service needs.
 
+Their `requestJson` helpers return eager `ResultAsync` from `resultar`. Import in-flight constructors, helpers, or types from `resultar` in application code.
+Calling a helper starts its request; the examples below document that real API. New workflows can
+compose these adapters lazily through the Task factory bridge without changing the request contract.
+
 Keep request payloads concrete. Do not widen a known response contract to `JsonRecord`,
 `Record<string, unknown>`, or `unknown` after validation.
 
@@ -56,6 +61,36 @@ const user = requestJson({
 Use `decode` when validation also normalizes or transforms the response. The decoder must make
 success and validation failure explicit; check the installed package types for the exact shape.
 
+## Compose Requests In Tasks
+
+Create the eager helper inside `fromResultAsync`, forwarding the Task signal to fetch:
+
+```ts
+import { ResultTask } from "resultar";
+import { requestJson } from "resultar-request";
+
+const loadUser = (userId: string) =>
+  ResultTask.fromResultAsync((signal) =>
+    requestJson({
+      request: () => fetch(`https://example.com/users/${userId}`, { signal }),
+      validator: isUser,
+    }),
+  );
+
+const userId = await loadUser("user-1")
+  .map((user) => user.id)
+  .runPromise();
+```
+
+This reuses the `isUser` guard above and infers `ResultTask<User, RequestError>`. Each run creates
+a fresh eager request. The same bridge works with the TypeBox and Zod helpers. Keep `map`
+synchronous, use `andThen` for another async Task, and compose `match` / `matchTags` before the
+runner when turning the response into a transport value. Use `runExit` when the boundary must
+inspect interruption, defects, and composite cleanup causes as well as typed errors.
+
+Passing `requestJson(...)` directly to `fromResultAsync` captures an already-started request;
+it cannot make that execution lazy or repeatable.
+
 ## Use The TypeBox Adapter
 
 ```ts
@@ -174,9 +209,9 @@ const user = requestJsonZod({
 The default policy retries request failures and HTTP `5xx`, but not `4xx`, invalid JSON, or
 validation failures. Retry requires a request factory; an already-created promise cannot be
 restarted. Ensure each attempt receives a fresh request. The current request retry configuration
-does not expose ResultAsync's internal retry signal, so do not claim that `requestJson`
+does not expose the eager Async policy's internal retry signal, so do not claim that `requestJson`
 automatically forwards policy cancellation. Supply an external fetch signal through the request
-closure when the caller owns separate cancellation.
+closure when the caller owns cancellation, including the signal supplied by a Task bridge.
 
 ## Validate In The Preferred Order
 
@@ -245,15 +280,20 @@ When an agent encounters a diagnostic, fix the architecture first:
 - handle, compose, return, or intentionally discard a returned Resultar value; a discard does not
   run a lazy task and must not be applied just to silence diagnostics;
 - replace nested `Result` from `map` with `andThen`;
-- replace `Promise<Result>` / `Promise<StrictResult>` contracts with `ResultAsync` /
-  `StrictResultAsync` and return composed operations directly (`prefer-result-async`);
-- enable `preferResultAsyncMode: "all"` with `preferResultAsync: "error"` to also catch raw
-  `Promise<T>` repository/service contracts and inferred returns; map driver errors in adapters
-  and document local suppressions for required native framework or conversion callbacks;
+- for existing eager contracts, replace `Promise<Result>` / `Promise<StrictResult>` with
+  `ResultAsync` / `StrictResultAsync` and return composed operations directly
+  (`prefer-result-async`); the rule name remains stable for that contract;
+- scope `preferResultAsync` to an intentional eager-boundary migration. Its `"all"` mode also
+  catches raw `Promise<T>` contracts and inferred returns. It does not make Task and Async
+  interchangeable or prescribe Async for new services. A new Task contract needs a factory,
+  Task composition, and explicit callers/runners; document native framework conversion boundaries;
 - replace error-only recovery with `mapErr`;
-- replace project-wide `try/catch` with `tryResult` or `tryResultAsync` when `noTryCatch` is enabled;
+- replace project-wide `try/catch` with a narrow adapter when `noTryCatch` is enabled: `tryResult`
+  for sync work, `ResultTask.tryPromise` for new lazy work, or `tryResultAsync` for eager compatibility;
 - wrap raw promise awaits in Resultar contexts;
-- use `yield*` and avoid `try/catch` inside `Result.gen` / `safeTry`;
+- use `yield*` in generators. Modern `Result.gen` / `Result.fn` return plain success values; deprecated
+  `safeTry` returns a final Result. Both support sync and async bodies (with async bodies returning eager `ResultAsync`). Use `ResultTask.gen`
+  for new lazy async work and bridge eager helpers inside it explicitly;
 - preserve inferred error and task requirements channels instead of asserting them away;
 - remove obsolete suppression entries without suppressing their diagnostic broadly.
 

package/dist/agent/references/patterns.md

@@ -1,6 +1,8 @@
 # Resultar Implementation Patterns
 
-Use these patterns as starting points, then align names and types with the consuming domain.
+Use these v4 patterns as starting points, then align names and types with the consuming domain.
+New async recipes use lazy, nonthenable `ResultTask` from `resultar`. Use `ResultAsync` for
+in-flight Results and preserve eager `ResultAsync` boundaries (and compatibility helpers exported from `resultar`) where callers require eager execution.
 
 ## Contents
 
@@ -14,6 +16,7 @@ Use these patterns as starting points, then align names and types with the consu
 - [Recover Locally And Match At Boundaries](#recover-locally-and-match-at-boundaries)
 - [Add Observability](#add-observability)
 - [Migrate Incrementally](#migrate-incrementally)
+- [Preserve An Eager Compatibility Contract](#preserve-an-eager-compatibility-contract)
 - [Test Runtime And Type Behavior](#test-runtime-and-type-behavior)
 
 ## Model A Domain Failure
@@ -39,33 +42,43 @@ boundary. Keep strings, enums, or `TaggedEnum` variants for intentionally local
 ```ts
 type CreateUserError = InvalidEmailError | UserAlreadyExistsError | SaveUserError;
 
-const createUser = (input: CreateUserInput): StrictResultAsync<User, CreateUserError> =>
-  validateEmail(input.email)
-    .asyncAndThen(ensureEmailAvailable)
+const createUser = (input: CreateUserInput): ResultTask<User, CreateUserError> =>
+  ResultTask.fromResult(validateEmail(input.email))
+    .andThen(ensureEmailAvailable)
     .andThen((email) => saveUser({ ...input, email }));
 ```
 
-- Use `map` only for an infallible value transform.
+- `ensureEmailAvailable` and `saveUser` return Tasks. Use `map` only for a synchronous value transform;
+  `ResultTask.map(asyncCallback)` stores a Promise as the success value.
 - Use `filterOrElse` for predicate validation.
 - Use `andThen` when the next operation can fail.
-- Use `asyncAndThen` only for the sync-to-async bridge.
+- Use `ResultTask.fromResult` to enter a lazy workflow from a synchronous Result.
+  `Result.asyncAndThen(result, callback)` (or `.asyncAndThen(callback)`) bridges into the eager `ResultAsync` compatibility model.
 - Keep each function's error type narrow and allow the final union to be inferred.
 
 ## Write A Linear Workflow
 
 ```ts
-const createUser = (input: CreateUserInput): StrictResultAsync<User, CreateUserError> =>
-  Result.gen(async function* () {
+const createUser = (input: CreateUserInput): ResultTask<User, CreateUserError> =>
+  ResultTask.gen(function* () {
     const email = yield* validateEmail(input.email);
     yield* ensureEmailAvailable(email);
     const user = yield* saveUser({ ...input, email });
 
-    return ok(user);
+    return user;
   });
 ```
 
-Use `yield*` for every fallible Resultar step. Wrap an uncontrolled promise with
-`tryResultAsync` before yielding it. Do not mix raw `await` or broad `try/catch` into the generator.
+Use `yield*` for every fallible step and return the plain success value. This generator can compose
+Tasks, synchronous Results, and service tags. Wrap uncontrolled Promise factories with
+`ResultTask.tryPromise`; adapt an eager adapter inside `ResultTask.fromResultAsync(factory)`.
+`return yield* finalStep()` executes the last step; `return finalStep()` leaves its Task as a value.
+Execute the workflow explicitly at its boundary.
+
+For a wholly synchronous linear flow, use `Result.gen(function* () { ... })` with the same
+plain-value return convention. `Result.gen` / `Result.fn` also support eager async bodies;
+`safeTry` supports both forms with final-Result returns. The legacy `safeTry` contract returns a
+final Result; it is not an alias of modern plain-value `Result.gen`.
 
 ## Wrap External Work
 
@@ -77,35 +90,39 @@ class ProfileApiError extends createTaggedError({
 
 type LoadProfileOptions = {
   readonly attempt?: number;
-  readonly signal?: AbortSignal;
 };
 
 const loadProfile = (
   userId: string,
   options: LoadProfileOptions = {},
-): StrictResultAsync<Profile, ProfileApiError> =>
-  tryResultAsync(
-    () => profileClient.load(userId, options),
-    (cause) => new ProfileApiError({ cause, userId }),
-  );
+): ResultTask<Profile, ProfileApiError> =>
+  ResultTask.tryPromise({
+    try: (signal) => profileClient.load(userId, { ...options, signal }),
+    catch: (cause) => new ProfileApiError({ cause, userId }),
+  });
 ```
 
-Prefer a promise factory because creating the promise may throw synchronously. Use
-`fromPromise(existingPromise, mapper)` only when the promise already exists, and use
-`fromSafePromise` only when non-rejection is guaranteed by contract.
+The Promise factory runs on each Task execution, catching both synchronous throws and rejections.
+Pass its signal into the client. Building a Task around an already-created Promise cannot defer or
+repeat that Promise's work.
 
-For callback or subscription APIs, use `fromCallback` and return cleanup from `subscribe`:
+Deprecated `fromCallback` returns eager `ResultAsync`. Invoke it inside a Task factory and return
+cleanup from `subscribe`:
 
 ```ts
-const message = fromCallback<Message, SubscriptionError>({
-  catch: (cause) => new SubscriptionError({ cause, topic }),
-  signal,
-  subscribe: ({ resolve, reject }) => {
-    const subscription = client.subscribe(topic, resolve, reject);
-
-    return () => subscription.close();
-  },
-});
+import { fromCallback } from "resultar";
+
+const message = ResultTask.fromResultAsync((signal) =>
+  fromCallback<Message, SubscriptionError>({
+    catch: (cause) => new SubscriptionError({ cause, topic }),
+    signal,
+    subscribe: ({ resolve, reject }) => {
+      const subscription = client.subscribe(topic, resolve, reject);
+
+      return () => subscription.close();
+    },
+  }),
+);
 ```
 
 Check the installed `ResultAsyncFromCallbackOptions` type for exact client integration details.
@@ -113,72 +130,135 @@ Check the installed `ResultAsyncFromCallbackOptions` type for exact client integ
 ## Apply Retry And Timeout Policy
 
 ```ts
-const profile = ResultAsync.timeout(
-  (signal) =>
-    ResultAsync.retry(
-      (attempt, retrySignal) => loadProfile(userId, { attempt, signal: retrySignal }),
-      {
-        times: 2,
-        delayMs: ({ nextAttempt }) => nextAttempt * 100,
-        jittered: 0.2,
-        while: (error) => error._tag === "ProfileApiError",
-        signal,
-      },
-    ),
-  {
-    timeoutMs: 1_500,
-    onTimeout: () => new ProfileTimeoutError({ timeoutMs: 1_500, userId }),
-  },
-);
+const profile = loadProfile(userId)
+  .retry(
+    Retry.policy<ProfileApiError>({
+      times: 2,
+      delayMs: ({ nextAttempt }) => nextAttempt * 100,
+      jittered: 0.2,
+      while: (error) => error._tag === "ProfileApiError",
+    }),
+  )
+  .timeout(1_500, () => new ProfileTimeoutError({ timeoutMs: 1_500, userId }));
 ```
 
 Forward the supplied signal into the underlying operation. Confirm whether the desired timeout
 covers each attempt or the complete retry budget, then nest the policies accordingly. Use
-`retryOrElse` only when fallback after exhaustion is domain policy.
+`orElse` after retry only when fallback after exhaustion is domain policy. `retryOrElse` remains an
+Async compatibility helper; it is not a Task method.
+
+For a policy reused across Task workflows and an existing eager contract, construct the portable
+contract explicitly:
+
+```ts
+import { ResultAsync, Retry } from "resultar";
+
+const retryPolicy = Retry.policy({
+  times: 2,
+  delayMs: 100,
+  backoff: 2,
+  jittered: 0.2,
+});
+
+const lazy = loadProfile(userId).retry(retryPolicy);
+// Existing eager adapter; loadProfileAsync still returns an eager ResultAsync.
+const eager = ResultAsync.retry(
+  (attempt, signal) => loadProfileAsync(userId, { attempt, signal }),
+  { ...retryPolicy, signal: requestSignal },
+);
+```
+
+Both use zero-based context in `delayMs`, `while`, and `onRetry` callbacks; `times` counts retries
+after the initial attempt. With `times: 2`, the first failure has two retries remaining. Canonical
+`while` is called only when another retry can run, and `onRetry` is awaited but best-effort. Reuse
+shares configuration, not progress. Task's older options remain supported: its callback retry index
+is one-based and `jittered: true` samples between zero and the delay. Eager Async options have their
+own callback arguments and jitter behavior; use the portable policy when sharing configuration.
+
+For a task adapter, choose how interruption handles an uncooperative promise:
+
+```ts
+const read = ResultTask.tryPromise({
+  try: (signal) => client.read(signal),
+  catch: (cause) => new ReadError({ cause }),
+  interruption: "detach",
+});
+```
+
+The default is `"wait"`. `"detach"` allows interruption to finish without waiting for the promise,
+while registered scope finalizers are still awaited. It does not stop the client. Keep resource
+acquisition on `"wait"` when its completion must precede release; a detached adapter owns anything
+it acquires after the task has stopped waiting.
+
+At execution, configure cooperative yields when a long instruction chain must share the event loop:
+
+```ts
+const exit = await lazy.runExit({ yieldEvery: 256 });
+```
+
+The default is 2048 instructions with `Scheduler.live`. A custom `TaskScheduler` receives the
+execution signal in `yield(signal)`. `Infinity` disables automatic yields. This does not interrupt
+a synchronous client callback midway; it is separate from `clock` and retry timing.
 
 Choose races deliberately:
 
-- `race` / `raceAll`: first settled `Ok` or `Err` wins.
-- `raceFirst`: first `Ok` wins; both must fail before an `Err` is returned.
-- `raceWith`: winner-specific logic needs access to the still-running task.
+- `ResultTask.race(left, right)`: first success wins; if both fail, preserve their causes in `Parallel`.
+- `ResultTask.raceFirst(left, right)`: first completed outcome wins.
+
+Task races and timeouts own their children and await loser cleanup. Existing Async `race` /
+`raceAll` return the first `Ok` or the last completed `Err` if all fail; `raceFirst` returns the first
+Result, and `raceWith` exposes a handle for custom policy. Those eager races and timeouts abort
+pending losers without waiting for their settlement or cleanup.
+
+For a scope-owned child, use `Fiber.await(child)` to observe its full Exit without requesting
+interruption. Use `Fiber.join(child)` to compose its result, and `Fiber.interrupt(child)` to request
+cancellation and await cleanup. Keep the parent scope open until child consumers finish.
 
 ## Process Batches
 
 Stop at the first error with bounded concurrency:
 
 ```ts
-const saved = ResultAsync.forEach(rows, saveRow, { concurrency: 8 });
+const saved = ResultTask.forEach(rows, saveRow, { concurrency: 8 });
 ```
 
 Collect all independent errors instead:
 
 ```ts
-const validated = ResultAsync.validateAll(rows, validateRow, { concurrency: 8 });
+const validated = ResultTask.validateAll(rows, validateRow, { concurrency: 8 });
 ```
 
-Use `{ discard: true }` with `forEach` when successful values are intentionally unused. Do not
-silently discard the returned `ResultAsync` itself.
+The mappers return Tasks; lift a synchronous validation with `ResultTask.fromResult` when needed.
+Use `.asVoid()` on the returned Task when its successful array is intentionally unused; the
+`{ discard: true }` option belongs to Result and Async collections. The Task still needs composition
+or an explicit runner; discarding it does not run the batch.
 
 ## Acquire And Release Resources
 
 ```ts
-const imported = ResultAsync.withResource({
-  acquire: (signal) => openImportSession({ signal }),
-  use: (session, signal) => importRows(session, rows, { signal }),
-  release: (session) => session.close(),
-});
+const imported = ResultTask.scoped(
+  ResultTask.gen(function* () {
+    const session = yield* ResultTask.acquireRelease({
+      acquire: openImportSession(),
+      release: (resource) => resource.close(),
+    });
+
+    return yield* importRows(session, rows);
+  }),
+);
 ```
 
-Release runs after every successful acquire path, but release failures are best-effort. If cleanup
-failure must affect the returned result, include that operation in `use` or otherwise model it as a
-typed Resultar step.
+Here `openImportSession`, `resource.close`, and `importRows` return Tasks. Release runs once after
+successful acquisition, is awaited on every exit, and preserves failures. The scope folds deferred
+release errors into the workflow's error channel. Use `acquireDisposable` for native disposables,
+or `ensuring(finalizer)` for unconditional Task cleanup that does not acquire a resource.
 
 ## Recover Locally And Match At Boundaries
 
 Recover only where the fallback is part of application policy:
 
 ```ts
-const profile = loadProfile(userId).catchTags({
+const profile = findProfile(userId).catchTags({
   ProfileNotFoundError: () => ok(defaultProfile),
   ProfileDisabledError: () => ok(disabledProfile),
 });
@@ -187,36 +267,40 @@ const profile = loadProfile(userId).catchTags({
 Unhandled tags remain in the error channel. At the HTTP boundary, map the complete union:
 
 ```ts
-const response = await createUser(input).matchTags((user) => ({ body: user, statusCode: 201 }), {
+const responseTask = createUser(input).matchTags((user) => ({ body: user, statusCode: 201 }), {
   InvalidEmailError: (error) => ({ body: error.toJSON(), statusCode: 400 }),
   UserAlreadyExistsError: (error) => ({ body: error.toJSON(), statusCode: 409 }),
   SaveUserError: (error) => ({ body: error.toJSON(), statusCode: 500 }),
 });
+
+const response = await responseTask.runPromise();
 ```
 
 Use `matchTagsPartial` only when a shared fallback is intentional. Keep HTTP status codes out of
-domain functions.
+domain functions. Task matching is a lazy fold, so it remains composable until the runner.
+`runExit` is the boundary to choose when defects, interruption, or composite causes also need inspection.
 
 ## Add Observability
 
 ```ts
 const observed = loadProfile(userId)
-  .tap((profile) => metrics.increment("profile.loaded", { userId: profile.userId }))
-  .tapError((error) => metrics.increment("profile.failed", { tag: error._tag }))
+  .inspect((profile) => metrics.increment("profile.loaded", { userId: profile.userId }))
+  .inspectError((error) => metrics.increment("profile.failed", { tag: error._tag }))
   .log((profile, error) => logger.info({ error, profile }, "profile result"));
 ```
 
-These `ResultAsync` callbacks are best-effort and cannot change the result.
-`ResultTask.tap` and `tapError` instead propagate returned task failures and turn callback
-throws or rejected Promises into defects. Use `andThen` or `orElse` when a
-logging, auditing, publishing, or cleanup failure must affect control flow.
+`inspect`, `inspectError`, `inspectBoth`, and `log` are best-effort across `Result`, `ResultAsync`, and `ResultTask`: observer failures are ignored, returned tasks are not executed, and the original result is preserved.
+Deprecated `Result` and `ResultAsync` `tap` / `tapError` retain their best-effort behavior.
+Only `ResultTask` `tap`, `tapError`, `tapCause`, and `tapBoth` compose effectful side operations:
+they propagate returned Task failures and turn callback throws or rejected Promises into defects.
+Use Task `tap`, `andThen`, or `orElse` when auditing, publishing, or cleanup must affect control flow.
 
 ## Migrate Incrementally
 
 1. Identify the outermost throwing or rejecting dependency.
 2. Create concrete tagged errors for expected domain and infrastructure failures.
-3. Wrap throws and rejections at that edge with `tryResult` or `tryResultAsync`.
-4. Change callers to compose with `map`, `andThen`, `asyncAndThen`, and `mapErr`.
+3. Wrap synchronous throws with `tryResult` and new async work with `ResultTask.tryPromise`.
+4. Return Tasks directly from lazy services and compose with `map`, `andThen`, and `mapErr`.
 5. Move transport conversion to one boundary matcher.
 6. Replace broad error types and unsafe casts with inferred unions.
 7. Enable `resultar-check` rules and remove narrow temporary exceptions.
@@ -224,6 +308,80 @@ logging, auditing, publishing, or cleanup failure must affect control flow.
 Avoid converting the whole codebase in one unsafe cast. A wrapper at an integration seam lets the
 typed error channel spread in reviewable steps.
 
+## Preserve An Eager Compatibility Contract
+
+`ResultAsync<T, E>` and `StrictResultAsync<T, E>` are the official in-flight `Result` types
+(`PromiseLike<Result<T, E>>`), returned by `task.runResult()` / `ResultTask.runResult(task)`.
+Import eager compatibility constructors or static orchestration helpers from `resultar` when
+existing callers depend on starting once at construction or awaiting the same execution:
+
+```ts
+import { ResultAsync, tryResultAsync } from "resultar";
+import type { StrictResultAsync } from "resultar";
+
+const loadProfileAsync = (userId: string): StrictResultAsync<Profile, ProfileApiError> =>
+  tryResultAsync({
+    try: () => profileClient.load(userId),
+    catch: (cause) => new ProfileApiError({ cause, userId }),
+  });
+
+const loadProfileTask = (userId: string): ResultTask<Profile, ProfileApiError> =>
+  ResultTask.fromResultAsync(() => loadProfileAsync(userId));
+
+// A caller receives one eagerly started ResultAsync execution via runResult().
+const existingCaller = loadProfileTask(userId).runResult();
+```
+
+Use `fromPromise` for an already-created Promise and `fromSafePromise` only when rejection is
+impossible by contract. Async `map` / `mapErr` still await Promise-returning callbacks; `andThen`
+accepts Result or Async. `Result.asyncMap` and `Result.asyncAndThen` (and their instance methods) bridge synchronous Results into eager `ResultAsync`:
+
+```ts
+import { Result, ok, okAsync } from "resultar";
+
+const eagerMapped = Result.asyncMap(ok(20), async (value) => value + 1);
+const eagerChained = Result.asyncAndThen(ok(20), (value) => okAsync(value + 1));
+```
+
+Both static helpers also accept curried calls for `pipe`. All eager constructors and helpers, including
+`errAsync`, are available from `resultar`. Prefer
+`task.runResult()` (or `ResultTask.runResult(task)`) when bridging a requirement-free Task into an
+in-flight `ResultAsync`, and `errAsync(new DomainError(props))` in eager recipes;
+`DomainError.errAsync(props)`, `ResultAsync.fromTask(task)`, and static/instance `ResultTask.toResultAsync` remain callable as compatibility aliases.
+Async instance `match` / `matchTags` / `matchTagsPartial` return native Promises; static/curried
+forms return composable Async values. Task matching returns a Task.
+
+The eager compatibility surface keeps deprecated `retry` / `retryOrElse`, `timeout`, races, collections, and control flow.
+Use Async factories for retries, and retain `withResource({ acquire, use, release })` where its
+best-effort release is the existing contract. A cleanup failure that must affect that eager result
+needs an explicit fallible step. These policies and deprecated observer methods are documented in
+[the compatibility API reference](api.md#eager-async-compatibility-policies).
+
+`Result.gen` / `Result.fn` support eager async bodies, and `safeTry` supports legacy
+async final-Result bodies:
+
+```ts
+import { Result, ok, safeTry } from "resultar";
+
+const eagerWorkflow = Result.gen(async function* () {
+  const profile = yield* loadProfileAsync(userId);
+  return profile;
+});
+
+const reusableEager = Result.fn(async function* (id: string) {
+  return yield* loadProfileAsync(id);
+});
+
+const legacyEager = safeTry(async function* () {
+  const profile = yield* loadProfileAsync(userId);
+  return ok(profile);
+});
+```
+
+Do not change legacy `safeTry` generators to return plain values: their final value is a Result.
+Modern `Result.gen` retains plain-value returns. New synchronous generators use `Result.gen`;
+new lazy workflows use `ResultTask.gen`. Migrate a service to Task by changing creation, composition, runners, and callers together.
+
 ## Test Runtime And Type Behavior
 
 ```ts