resultar 3.9.1 → 4.0.0

package/dist/agent/references/review-checklist.md

@@ -5,15 +5,18 @@ validation. Report only issues supported by the installed Resultar version and r
 
 ## Source And Scope
 
-- Confirm the installed `resultar`, request adapter, and `resultar-check` versions.
+- Confirm installed `resultar`, request adapter, and checker versions.
+- Import all synchronous, lazy `ResultTask`, and in-flight/eager `ResultAsync` helpers and types from `resultar`. Existing Result/Task/Async/tagged-error bridges remain available; migration preserves their contracts.
 - Inspect local exports, types, package README files, and runnable examples before suggesting an API.
 - Separate issues introduced by the change from pre-existing workspace or dependency problems.
 - Preserve unrelated changes in a dirty worktree.
 
 ## Failure Model
 
-- Expected failures return `Result`, `ResultAsync`, or `ResultTask`; programmer defects may still throw.
-- Application and integration boundaries prefer `StrictResult` / `StrictResultAsync`.
+- New sync failures return `Result` / `StrictResult`; new async workflows return lazy `ResultTask`
+  with concrete error and requirement types. Programmer defects may still throw.
+- `ResultAsync` / `StrictResultAsync` are the official in-flight `Result` types returned by `task.runResult()`. Legacy adapters and static orchestration helpers on `ResultAsync` remain deprecated for existing eager boundaries; migration
+  preserves their start-once and repeat-await behavior until callers move to explicit Task workflows and runners.
 - Tagged errors have stable names, useful metadata, inferred template props, and preserved causes.
 - Error unions remain concrete instead of widening early to `Error`, `unknown`, or a string.
 - `TaggedEnum` is limited to lightweight non-Error domain variants.
@@ -21,12 +24,19 @@ validation. Report only issues supported by the installed Resultar version and r
 
 ## Composition
 
-- `map` performs only infallible success transforms.
-- `mapErr` performs error-only transforms.
+- Result and Task `map` / `mapErr` perform synchronous success/error transforms. Async retains its
+  Promise-awaiting callbacks; a Task mapper returning a Promise stores it as a success value.
 - `filterOrElse` represents predicate validation.
-- `andThen` composes fallible steps; `asyncAndThen` is used for the sync-to-async bridge.
+- Task `andThen` composes Task or synchronous Result steps. `fromResult` lifts a Result, and
+  structural `fromResultAsync(factory)` defers a `PromiseLike<Result>` producer. `Result.asyncAndThen`
+  / `Result.asyncMap` (and the `.asyncAndThen` / `.asyncMap` instance methods) bridge synchronous Results into eager `ResultAsync`.
+- 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 compatibility code;
+  `ResultAsync.fromTask`, Task `toResultAsync`, and tagged `.errAsync()` remain supported.
 - `orElse` recovers the whole error channel; `catchTag` / `catchTags` recover selected domain cases.
-- `safeTry` uses `yield*` for Resultar values and contains no raw `await` or broad `try/catch`.
+- `Result.gen` / `Result.fn` and legacy `safeTry` support sync and async bodies. Modern
+  `Result.gen` returns plain success values; `safeTry` returns a final Result.
+  New async generators use `ResultTask.gen`, yielding Tasks, Results, and services.
+  No raw Promise yields, raw `await`, or broad `try/catch` bypass typed composition.
 - Returned `Result`, `ResultAsync`, and `ResultTask` values are handled or explicitly discarded by supported policy.
 - Type assertions do not narrow away possible errors.
 
@@ -34,23 +44,39 @@ validation. Report only issues supported by the installed Resultar version and r
 
 - External throws and rejections are wrapped once, close to the uncontrolled dependency.
 - Error mappers accept `unknown` and produce concrete errors with `cause`.
-- Promise factories use `tryResultAsync`; already-created promises use `fromPromise`.
-- `fromSafePromise` is used only when rejection is impossible by contract.
+- New Promise factories use `ResultTask.tryPromise({ try, catch })` and forward its signal.
+- Existing eager adapters import `tryResultAsync`, `fromPromise`, and `fromSafePromise` from
+  `resultar`, using factories for fresh work and `fromPromise` for existing Promises,
+  and `fromSafePromise` only when rejection is impossible by contract.
 - Callback integrations provide cleanup and model `AbortError` where applicable.
 - Retry policy defines bounded attempts, delay/jitter, retryable errors, and cancellation.
+- Retry configuration shared across ResultAsync and ResultTask uses `Retry.policy`, preserving
+  each execution model. Canonical predicates use zero-based context and only run with budget;
+  older Task options and eager Async options keep their distinct callback signatures and jitter behavior.
+- Task promise adapters choose `'wait'` or `'detach'` deliberately. Detachment stops waiting,
+  while the adapter owns resources acquired by underlying work after interruption.
 - Timeout scope is explicit: per attempt or across the complete retry budget.
-- `race`/`raceAll` are used for first settlement; `raceFirst` for first success.
+- `ResultAsync.race` / `raceAll` select the first `Ok`; if every task fails, return the last completed `Err`. `ResultAsync.raceFirst` selects the first completed `Result`.
+- ResultAsync races and timeouts abort pending losers without waiting for their settlement or cleanup.
+- `ResultTask.race` selects the first success; `ResultTask.raceFirst` selects the first outcome. Both await loser cleanup.
+- `Fiber.await` observes completion; `join` composes the result and `interrupt` requests cancellation.
+- `yieldEvery` / `scheduler` configure instruction scheduling, not synchronous preemption or time.
+  Tests use a deterministic scheduler when ordering across yields matters.
 - Signals reach the underlying client so cancellation is cooperative rather than cosmetic.
 - Batch concurrency is bounded when workload size or dependency capacity requires it.
 - `validateAll` is used only when collecting all independent failures is desired.
-- `withResource` cleanup is treated as best-effort; important cleanup failures are modeled in the
-  result channel.
+- Task resources use `acquireRelease` / `acquireDisposable` + `scoped` for awaited cleanup and
+  preserved release failures. Existing Async `withResource` cleanup stays best-effort; an eager
+  cleanup failure that must affect control flow is modeled as an explicit fallible step.
 
 ## Boundaries And Recovery
 
 - Domain code does not contain transport status codes, framework responses, or CLI exit behavior.
 - `matchTags` handles the complete tagged error union at the boundary.
 - `matchTagsPartial` and `matchErrorPartial` have intentional fallbacks.
+- Task `match` / `matchTags` / `matchTagsPartial` are compositional folds, followed by an explicit
+  runner at the boundary. Async instance matching remains a native Promise terminal;
+  Async static/direct/curried matching returns a composable Async value.
 - An `Error` handler exists when untagged errors can reach tagged matching.
 - Recovery is local only when the fallback is genuine domain/application policy.
 - `_unsafeUnwrap*` remains in tests; `runSync`, `runPromise`, and `unwrapOrThrow` appear only at
@@ -67,12 +93,19 @@ validation. Report only issues supported by the installed Resultar version and r
 - Numeric HTTP handlers take precedence over generic HTTP mapping where needed.
 - Retry uses a request factory and does not retry non-retryable `4xx`, JSON, or validation failures
   without explicit policy.
+- Request helpers really return eager Async. A new lazy workflow invokes them inside
+  `ResultTask.fromResultAsync((signal) => ...)` and forwards the signal to fetch; it does not capture
+  an already-started request and claim it was deferred.
 
 ## Observability And Cleanup
 
-- `Result` / `ResultAsync` observation failures are best-effort; `ResultTask.tap` / `tapError`
-  can introduce typed failures or defects.
+- `inspect` / `inspectError` / `inspectBoth` and `log` across all models are best-effort and never
+  execute returned Tasks. Deprecated Result and Async `tap` / `tapError` keep that observer contract.
+- Only Task `tap` / `tapError` / `tapCause` / `tapBoth` compose effectful side operations and can
+  introduce typed failures or defects.
 - Resource cleanup and observation use the semantics of the concrete execution model.
+- `Result.gen` / `safeTry` do not close a suspended generator on early `Err`; cleanup does not rely
+  on `finally` on that path. `ResultTask.gen` interprets yielded generator cleanup.
 - Audits, publishes, or cleanup that must succeed use `andThen`, `orElse`, or another Resultar
   boundary.
 - Logs expose stable tags and safe context without leaking redacted values.
@@ -87,8 +120,15 @@ validation. Report only issues supported by the installed Resultar version and r
 - Documentation examples compile or have a matching runnable example.
 - Core request, TypeBox, and Zod docs link to one another as alternatives/adapters.
 - API names, package links, and version claims match current source.
-- `Result.gen` returns a Result; `ResultTask.gen` returns a plain success value.
-- `runResult` rejection paths and deferred release errors are handled at the owning boundary.
+- `Result.gen` and `ResultTask.gen` return plain success values and compose fallible steps or early
+  errors via `yield*`; `safeTry` retains its final-Result contract.
+- Eager compatibility APIs exported from `resultar` preserve eagerness and legacy callback
+  semantics. Prefer canonical Task names while preserving deprecated aliases during migration.
+- Stable checker names such as `preferResultAsync` describe an existing eager-contract policy,
+  scoped deliberately; they do not override the Task default for new workflows.
+- Instance `task.runResult()`, `runPromise()`, `runExit()`, and `runFork()` use the same options,
+  service checks, and deferred release error types as their supported static forms. Prefer instance
+  runners in new recipes. `runResult` rejection paths and deferred release errors are handled at the owning boundary.
 - An intentional-discard fix is not mistaken for executing or handling a lazy task.
 
 ## Validation Order
@@ -107,16 +147,17 @@ validation. Report only issues supported by the installed Resultar version and r
   channel.
 - A broad `try/catch` surrounds an entire workflow instead of wrapping one external boundary.
 - Project-wide `try/catch` remains after the strict `noTryCatch` migration rule is enabled.
-- `map` returns another `Result` or `ResultAsync`.
+- `map` returns another Resultar container, or a Task mapper returns a Promise instead of composing
+  an asynchronous step.
 - `orElse` only replaces one error with another and should be `mapErr`.
 - A raw promise is awaited inside a Resultar workflow without a typed mapper.
-- `safeTry` contains raw `await`, plain `yield`, `try/catch`, or legacy `safeUnwrap()`.
+- `Result.gen` / `safeTry` contain raw `await`, plain `yield`, or broad `try/catch` instead of supported Result composition.
 - A Resultar value is created and ignored.
 - `_unsafeUnwrap()` appears in production code.
 - An assertion makes an error union narrower than the implementation can guarantee.
 - Tagged errors override generated constructors, mismatch class names, or omit useful causes.
 - A schema adapter returns a broad JSON type or duplicates the schema with a drifting interface.
 - A promise rather than a request factory is configured for retry.
-- Hand-written retry, timeout, or race logic duplicates a built-in ResultAsync policy.
+- Hand-written retry, timeout, or race logic duplicates the built-in policy of the chosen model.
 - A lint-only pass is described as full Resultar validation.
 - Documentation recommends an API absent from the installed package.

package/dist/agent/references/services.md

@@ -5,14 +5,19 @@ versions. The application DI helpers are `createModule`, `service`, `Service`, a
 Named factory overloads and low-level adapter access use the same `resultar-di` entry point.
 The former `/advanced` subpath has been removed; migrate existing imports to `resultar-di`.
 
+Use `ResultTask` for new asynchronous service methods and initialization. Tasks are lazy and
+nonthenable: return them directly from methods, compose them with `andThen` or `ResultTask.gen`,
+and execute them through an explicit runner (`task.runResult()`, `task.runPromise()`, `task.runExit()`, or `task.runFork()`) at the owning application or request boundary.
+`task.runResult()` returns an in-flight `ResultAsync<T, E>`. Existing methods returning eager `ResultAsync` or `StrictResultAsync` directly remain eager compatibility contracts; import in-flight constructors, eager compatibility helpers, and `ResultAsync` directly from `resultar`.
+
 - Use `ResultTask.service<Contract>()('name')` in core or `Service.require<Contract>()('name')`
   in DI to infer the literal identifier. The direct core overload remains supported; do not invent
   `Result.service`. Service requirements are represented by `R` in `ResultTask<T, E, R>`.
 - Declare class services with `Service('name', { requires: { alias: Token }, make: ({ alias }) =>
-({ ... }) })`. The readonly dependency object is inferred; `make` can return the service
+  ({ ... }) })`. The readonly dependency object is inferred; `make` can return the service
   object directly or a ResultTask. Factories remain lazy and synchronous values add no typed
   initialization errors. Promises and thenables are rejected. Use `ResultTask.gen` for
-  initialization with typed failures, additional requirements or owned resources. Without `requires`, pass a task directly as `make` and yield requirements inline or by token.
+  initialization with typed failures, additional requirements or owned resources. Without `requires`, pass a task or a zero-argument factory returning a synchronous value or ResultTask. Tasks can yield requirements inline or by token.
   Both forms support `Service<Contract>()('name', definition)`.
 - Keep provider registration explicit. `requires` does not acquire or register dependencies.
   Inline tokens resolve by name in DI or `provideServices`; core `provideService` supplies an exact
@@ -25,6 +30,9 @@ The former `/advanced` subpath has been removed; migrate existing imports to `re
   live resource from a completed scope returns a resource whose finalizer has already run.
 - Use `createHonoApp` for Hono routes. Ordinary `await` and `result.match` inside a route are valid;
   generator-specific restrictions do not apply to a route body.
+  For a Task-returning method, either run `await task.runResult().matchTags(...)` or compose `task.matchTags(...)` and return
+  `responseTask.runPromise()` from the route. For an existing Async method, awaiting it
+  still observes its eager execution; `await task` never executes a Task.
   Export `type AppHono = Hono<{ Bindings: InferRequestServices<typeof createApplication> }>`
   from `main.ts`, using `InferRequestServices` from `resultar-hono`. Separate route files import
   `AppHono` with `import type` and receive `(app: AppHono)`. Bindings follow the application
@@ -41,6 +49,12 @@ The former `/advanced` subpath has been removed; migrate existing imports to `re
   `ready()` or before the first request. Direct resources live until close and release before
   singleton dependencies; scoped/transient dependencies are rejected. A failure rolls back the
   application root, preserving cleanup causes. Hono close cancels pending startup cooperatively.
+  The low-level lifecycle sessions retain eager Async `ready` / `close` or `finish` values where
+  exposed by their installed types; these bridge an explicitly running Task and are compatibility
+  boundaries, not a recommendation to make new service methods eager.
+  Prefer `task.runResult()` (or `ResultTask.runResult(task)`) when bridging a requirement-free Task into an in-flight `ResultAsync`;
+  `ResultAsync.fromTask(task)` and static/instance `ResultTask.toResultAsync` remain supported as deprecated aliases. The inbound `ResultTask.fromResultAsync` bridge accepts structural
+  `PromiseLike<Result>` values or factories and needs no class registration.
 - Use `createHonoServices(module).middleware(keys, { locals })` to add services to an existing Hono
   router. Inline route middleware infers `c.var.services` while preserving `c.env` and native RPC
   responses. Install one services middleware per request; consume/cancel responses before `close()`.
@@ -56,9 +70,12 @@ The former `/advanced` subpath has been removed; migrate existing imports to `re
   Infer decorators with `InferAppServices` / `InferRequestServices`; augment Fastify in the application
   or use its typed `getDecorator`. Annotate module/locals callback parameters with native Fastify
   types when their inferred return values participate in selection checking.
-- Keep business logic in plain factories with async methods when sufficient. Register them using
-  `service(name, dependencies, factory)`. Map results explicitly through `matchTags` and native
-  response APIs; the framework adapters install no status table or `reply.result` helper.
+- Keep business logic in plain factories with methods returning Tasks when sufficient. Register
+  them using `service(name, dependencies, factory)`. Wrap a Promise client with `ResultTask.tryPromise`
+  and keep `map` synchronous. For an existing eager Async repository or request helper, invoke it
+  inside `ResultTask.fromResultAsync((signal) => adapter(signal))` to create a fresh operation per run.
+  Map results through compositional `matchTags`, an explicit runner, and native response APIs;
+  the framework adapters install no status table or `reply.result` helper.
 - `scope.useSingletons(keys, callback)` restricts selected services and callback tokens to the root
   lifetime. Keep its callback active while serving; it is not a free-standing resolver. Factory
   initialization stays lazy until selection; resource release remains explicit.
@@ -70,9 +87,12 @@ The former `/advanced` subpath has been removed; migrate existing imports to `re
   cannot capture scoped services or request-local data. Extracting authentication remains the
   framework adapter's responsibility.
 
-For a complete runnable pattern, see the workspace `examples/hono/` and `examples/resultar/`
+For a complete runnable pattern, see the workspace `examples/hono/` and `examples/cookbook/`
 application lifecycle examples. The distributed guide includes the checked core recipe at
 `examples/workflow.mjs`; use the published declarations to adapt companion integrations.
+Some maintained examples and installed request adapters keep eager Async methods to demonstrate
+compatibility. Preserve that behavior during an incremental migration; new Task methods require
+explicit callers/runners and cannot be substituted by a return-type annotation alone.
 
 ## Framework DI exports
 

package/dist/agent/versions.json

@@ -1,10 +1,10 @@
 {
-  "resultar-check": "3.2.0",
-  "resultar-di": "0.4.0",
-  "resultar-fastify": "0.4.0",
-  "resultar-hono": "0.4.0",
-  "resultar-request": "0.1.2",
-  "resultar-request-typebox": "0.1.2",
-  "resultar-request-zod": "0.1.2",
-  "resultar": "3.9.1"
+  "resultar-check": "4.0.0",
+  "resultar-di": "1.0.0",
+  "resultar-fastify": "1.0.0",
+  "resultar-hono": "1.0.0",
+  "resultar-request": "1.0.0",
+  "resultar-request-typebox": "1.0.0",
+  "resultar-request-zod": "1.0.0",
+  "resultar": "4.0.0"
 }