resultar 3.6.0 → 3.8.0

package/LICENSE

@@ -1,6 +1,7 @@
 MIT License
 
 Copyright (c) 2019 Giorgio Delgado
+Copyright (c) 2026 Inaiat Moraes
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/README.md

@@ -54,6 +54,7 @@ and optional TypeScript-backed diagnostics.
 - [HTTP Request Packages](#http-request-packages)
 - [API Decision Guide](#api-decision-guide)
 - [More Documentation](#more-documentation)
+- [Limitations](#limitations)
 
 ## Install
 
@@ -407,8 +408,9 @@ Prefer a factory with `tryResultAsync` when creating the promise can also throw
 ## Lazy Workflows With ResultTask
 
 `ResultTask<T, E, R>` is the lazy workflow primitive in Resultar. Creating one does not start the
-work; `runResult`, `runExit`, or `runPromise` executes it explicitly. `R` records the service tags
-still required by the workflow, so the execution boundary can require an explicit environment.
+work; `runResult`, `runExit`, or `runPromise` executes it explicitly. `R` records required service
+tags and resource scope requirements. Run boundaries supply the root scope automatically and
+require an explicit environment for any remaining service tags.
 
 Unlike `ResultAsync`, a `ResultTask` is a reusable description of work rather than an already-started
 operation. Mapping, chaining, recovery, service provision, and generator composition all remain lazy.
@@ -418,11 +420,13 @@ operation. Mapping, chaining, recovery, service provision, and generator composi
 | Create an immediate success or failure | `succeed`, `fail`, `fromResult` |
 | Defer synchronous work | `sync`, `try` |
 | Defer promise-producing work | `tryPromise` |
-| Transform or chain | `map`, `flatMap`, `andThen` |
+| Transform, observe, or chain | `map`, `mapError`, `flatMap`, `andThen`, `tap`, `tapError`, `as`, `match` |
 | Recover typed failures | `catchAll` |
 | Write a linear lazy workflow | `gen` with `yield*` |
-| Declare and provide dependencies | `service`, `provideService`, `provideServices` |
+| Declare and provide dependencies | `service`, `provideService`, `provideServices`, `provideServiceResolver` |
+| Own resources and await cleanup | `acquireRelease`, `scoped` |
 | Execute at the application boundary | `runExit`, `runResult`, `runPromise` |
+| Bridge to started promises | `fromResultAsync`, `toResultAsync`, `ResultAsync.fromTask` |
 
 ```ts
 import { ResultTask } from 'resultar'
@@ -445,9 +449,13 @@ Choose the execution boundary based on how much information the application need
 
 | Boundary | Result |
 | --- | --- |
-| `runExit(task)` | `Exit<T, E>` preserving `Success`, typed `Fail`, and unexpected `Die` causes |
-| `runResult(task)` | `Result<T, E>`; a `Die` rejects instead of entering the typed error channel |
-| `runPromise(task)` | `T`; typed failures and defects reject for integration with Promise-only APIs |
+| `runExit(task)` | Preserves `Success`, typed `Fail`, `Die`, `Interrupt`, and `Sequential` causes |
+| `runResult(task)` | Returns a single typed failure as `Err`; rejects defects, interruption, and composite causes |
+| `runPromise(task)` | Returns `T`; rejects every failure for integration with Promise-only APIs |
+
+The error type of `runExit` and `runResult` includes deferred release failures from the root scope.
+Interruption rejects with `AbortError`. A composite cause rejects with `ResultTaskCauseError`, whose
+`cause` preserves the complete tree; use `runExit` to inspect it without rejection.
 
 ```ts
 const controller = new AbortController()
@@ -470,9 +478,20 @@ const userName = loadUser('user_123')
   .catchAll((error) => ResultTask.succeed(`unavailable: ${error.message}`))
 ```
 
-`catchAll` recovers only typed failures. Runtime defects remain defects and are visible through
-`runExit`. The equivalent functional forms are `ResultTask.map`, `ResultTask.flatMap`, and
-`ResultTask.catchAll`.
+`catchAll` recovers a single typed failure. Defects and interruption bypass recovery. Composite
+causes bypass recovery as `Die(ResultTaskCauseError)` with the original tree on the error's `cause`;
+this prevents removed error types from escaping as typed failures. The equivalent functional forms
+are `ResultTask.map`, `ResultTask.flatMap`, and `ResultTask.catchAll`.
+
+For promise adapters that do not need an error mapper, pass the lazy callback directly:
+
+```ts
+const response = ResultTask.tryPromise((signal) => fetch(url, { signal }))
+// ResultTask<Response, unknown>: synchronous throws and rejections remain typed failures.
+```
+
+The callback runs only when the task executes. Use `tryPromise({ try, catch })` when you need a
+specific error type; both forms receive the runtime signal and preserve interruption semantics.
 
 Workflows can request typed services with `yield*` and receive them at the boundary. Pass the service
 type and its literal identifier so the named environment remains checked:
@@ -510,6 +529,20 @@ await ResultTask.runResult(readyWithOne)
 await ResultTask.runResult(readyWithAll)
 ```
 
+Infrastructure such as a dependency-injection adapter can resolve service tags lazily with
+`provideServiceResolver(task, { Logger: () => loggerTask })`. Each required identifier has a
+typed lazy provider. Provider errors and external requirements remain in the resulting task type;
+resource-scope requirements also remain visible. All three providers (`provideService`,
+`provideServices`, `provideServiceResolver`) support data-first and curried (`.pipe`) forms.
+A provider whose value is incompatible with the required service contract is rejected at compile
+time, including through a reused curried provider; partial providers keep the remaining
+requirements until they are satisfied at the boundary.
+
+Adapters can use `ResultTask.makeScope()` to own resources across executions. Run tasks with
+`owner.use(task)` and execute `owner.close()` after consumers finish. Failed uses roll back their
+partial acquisitions. `ResultTask.memoize(task)` shares pending and successful executions and
+allows retry after failure; its first execution supplies the environment and resource scope.
+
 `ResultTask.gen` composes tasks and services linearly. On short-circuit, generator `finally` blocks
 are closed and any yielded cleanup tasks or services are interpreted before execution completes:
 
@@ -523,9 +556,81 @@ const program = ResultTask.gen(function* () {
 })
 ```
 
-If cleanup itself fails or defects, that cleanup exit becomes the final exit. ResultTask 3.6 keeps
-execution deliberately small: it provides laziness, typed services, cooperative cancellation, and
-explicit exits, but does not yet include a scheduler, scopes, or `Fiber` runtime.
+Generator `finally` retains its existing replacement policy if its cleanup fails. Use resource
+scopes below when both the body and cleanup failure must be preserved.
+
+Generators also accept `yield* result` for plain `Result` values: `Ok` unwraps its value and
+`Err` short-circuits into `E`.
+
+### Resource scopes and application lifecycle
+
+```ts
+const connection = ResultTask.acquireRelease({
+  acquire: ResultTask.tryPromise({
+    try: (signal) => connectDatabase(signal),
+    catch: (cause) => new ConnectionError({ cause }),
+  }),
+  release: (database, exit) => ResultTask.tryPromise({
+    try: () => database.close(exit),
+    catch: (cause) => new CloseError({ cause }),
+  }),
+})
+
+const program = ResultTask.scoped(ResultTask.gen(function* () {
+  const database = yield* connection
+  return yield* ResultTask.tryPromise({
+    try: (signal) => database.query('SELECT 1', signal),
+    catch: (cause) => new QueryError({ cause }),
+  })
+}))
+
+const exit = await ResultTask.runExit(program)
+```
+
+Every run owns a root scope. `scoped` closes a child scope before the next task continues. Successful
+acquisitions register finalizers in LIFO order; every finalizer is awaited once, even after a body
+failure, defect, or interruption. Failed acquisition does not register its release. Earlier resources
+are still released if a later acquisition fails. Each finalizer receives the same region exit,
+before release failures are appended. Services provided around acquisition remain available during
+release, including services used only by the release callback.
+
+`acquireRelease` tracks deferred errors with `ResultTaskScope<ReleaseError>` in `R`. `scoped` removes
+that requirement and adds its errors to `E`; run boundaries do the same for the root scope. Service
+provision and `catchAll` before scope closure cannot erase pending release failures. To recover a
+single release failure, put `catchAll` after `scoped`.
+
+If use succeeds but release fails, the failure is returned as `Err`. If both fail, `runExit` retains
+them as `Sequential(useCause, releaseCause)`; subsequent release failures are appended in order.
+Release callbacks that throw produce defects. Resources acquired during a finalizer belong to a
+private cleanup scope, which is closed before the next finalizer starts.
+
+Cancellation is cooperative: tasks check the signal before starting, and promise operations receive
+it. Rejection after abort is classified as interruption. The runtime waits for in-flight operations
+to settle so a resource acquired during cancellation can still be registered and released. Cleanup
+uses a fresh, non-aborted signal. An operation or finalizer that never settles can therefore keep
+the run pending; there is no preemptive cancellation, scheduler, or `Fiber` runtime in this slice.
+
+For application composition, keep ordinary factories and existing `StrictResultAsync` use cases.
+Use service tags only when a program needs requirements supplied at execution. Put the **whole server
+lifetime** inside the resource scope: acquire database, session, then HTTP; wait for shutdown; drain
+HTTP, close session, then close database. Returning a server from a completed scope would return
+already-released resources. TypeScript does not enforce resource reference lifetimes.
+
+See the runnable [application lifecycle example](../../examples/resultar/src/application-lifecycle.ts)
+and its [smoke test](../../examples/resultar/scripts/lifecycle-smoke.ts). Run `pnpm run example:resultar`
+from the workspace root. Its factory and resource contracts return `ResultTask` with database,
+session, and HTTP error types. Drivers expose Promises only inside `ResultTask.tryPromise` adapters,
+which receive the runtime signal without threading it through every application interface.
+Concrete adapters must clean up partial acquisitions before returning a
+failure and implement request draining, SSE termination, and suitable deadlines.
+
+`ResultAsync.withResource` keeps its existing best-effort release behavior. Existing `ResultAsync`
+instances have already started; wrapping one does not make it lazy or automatically cancelable.
+Use `ResultTask.fromResultAsync` to run a `ResultAsync` inside a task boundary: pass a
+`(signal) => ResultAsync` factory to defer creation until execution, or an existing instance to
+capture an already-started execution. Use `ResultTask.toResultAsync(task)` — or the
+`ResultAsync.fromTask(task)` alias — to start a requirement-free task immediately on the default
+runtime and consume it as `ResultAsync`.
 
 ## Production Async Policies
 
@@ -837,8 +942,9 @@ service needs.
 | Write linear Result code | `Result.gen` (`safeTry` compatibility alias) |
 | Describe reusable lazy work | `ResultTask.succeed`, `sync`, `try`, `tryPromise` |
 | Compose or recover lazy work | `ResultTask.map`, `flatMap`, `andThen`, `catchAll`, `gen` |
-| Require or bind typed services | `ResultTask.service`, `provideService`, `provideServices` |
+| Require or bind typed services | `ResultTask.service`, `provideService`, `provideServices`, `provideServiceResolver` |
 | Execute lazy work explicitly | `ResultTask.runExit`, `runResult`, `runPromise` |
+| Bridge to started promises | `ResultTask.fromResultAsync`, `toResultAsync`, `ResultAsync.fromTask` |
 | Handle a final boundary | `match`, `matchTags`, `matchTagsPartial` |
 | Combine independent results | `zip`, `combine`, `combineWithAllErrors` |
 | Try ordered fallback candidates | `firstSuccessOf` |
@@ -856,10 +962,20 @@ The
 covers overloads, aliases, callback semantics, collection helpers, conditional helpers, tagged
 reasons, disposable results, and compatibility APIs.
 
+## Coding agents
+
+Each npm build includes `dist/llms.txt`, `dist/agent/SKILL.md`, focused references, a compiled
+core workflow example, and `dist/agent/versions.json`. Start from these installed files so the
+guide matches the package version. Companion package READMEs take precedence when their installed
+versions differ from the recorded companion versions. The online `main` guide tracks development.
+
+The guide distinguishes `Result.gen` from `ResultTask.gen`, immediate from lazy execution,
+observation from effectful `tap`, and `runResult` from the non-rejecting `runExit` boundary.
+
 ## More Documentation
 
 - [Full Resultar guide](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md)
-- [ResultTask core RFC](https://github.com/inaiat/resultar/blob/main/packages/resultar/RESULT-TASK-CORE-RFC.md)
+- [ResultTask core RFC](https://github.com/inaiat/resultar/blob/main/docs/rfcs/rfc-0001-result-task-core.md)
 - [Runnable core cookbook](https://github.com/inaiat/resultar/tree/main/examples/resultar)
 - [Catching and recovering errors](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#catching-and-recovering-errors)
 - [Safe Try](https://github.com/inaiat/resultar/blob/main/DOCUMENTATION.md#safe-try)
@@ -871,6 +987,26 @@ reasons, disposable results, and compatibility APIs.
 
 Resultar is also published on [JSR as `@inaiat/resultar`](https://jsr.io/@inaiat/resultar).
 
+## Limitations
+
+ResultTask implements the RFC 0001 lazy core, generator with services, and resource scopes. The
+following are explicitly out of scope for this slice:
+
+- No `Stream`, STM, caching, clustering, RPC, or platform layer; this is not a full Effect API port.
+- No implicit global runtime: every `run*` call creates its own root scope and signal, and simple
+  tasks need no services or configuration.
+- No fibers or structured concurrency yet: `forkChild`/`join`/`interrupt`, task `race`/`timeout`,
+  and uniform `all`/`forEach` over the task runtime are still Phase 3. The `Cause` model covers
+  `Fail`, `Die`, `Interrupt`, and `Sequential`; `Parallel` is reserved for that future work. Use the
+  `ResultAsync` race, timeout, retry, and concurrency helpers in the meantime — they keep their own
+  eager, per-helper protocols.
+- No `Schedule`, schedule-based retry, or injectable clock yet (Phase 4).
+- No `Layer` system in the core: service graphs with their own lifecycle belong to the optional
+  `resultar-di` package, and the core does not depend on it.
+- `ResultAsync` stays eager and awaitable. `fromResultAsync` on an existing instance captures an
+  already-started execution; only the factory form defers creation.
+- Validated on Node.js 24+ only; other runtimes such as Bun are unvalidated.
+
 ## License
 
 MIT

package/dist/agent/SKILL.md

@@ -0,0 +1,224 @@
+---
+name: resultar
+description: Build, review, migrate, test, and document TypeScript code using Resultar v3.7+, including Result, ResultAsync, ResultTask, StrictResult, createTaggedError, Result.gen/safeTry, request adapters, and resultar-check. Use when expected failures should become typed values, thrown or rejected work must be wrapped, Resultar pipelines or async policies need design, HTTP JSON needs TypeBox or Zod validation, Resultar diagnostics need configuration, or an existing Resultar codebase needs review or migration.
+metadata:
+  tags: [typescript, error-handling]
+  domains: [foundation]
+---
+
+# Resultar Engineering
+
+Use Resultar to keep expected failures explicit in TypeScript without introducing an application
+runtime. Produce code that preserves concrete success and error types from the domain boundary to
+the final transport, job, CLI, or integration boundary.
+
+## Start From Repository Truth
+
+1. Inspect the consuming project's `package.json`, lockfile, Resultar version, module format, and
+   TypeScript version before proposing code.
+2. Prefer the installed package types and local source over remembered APIs. The core package
+   ships this guide at `node_modules/resultar/dist/agent/SKILL.md`; check its `versions.json` before
+   using companion-package recipes. Online `main` documentation may describe a newer release.
+3. In the Resultar repository, use these sources in order:
+   - `packages/resultar/src/index.ts` for public exports.
+   - `packages/resultar/README.md` and `DOCUMENTATION.md` for current semantics and examples.
+   - `packages/check/README.md` for diagnostics.
+   - `packages/request*/README.md` and `examples/request/` for request integrations.
+4. Adapt examples when the consumer uses an older Resultar version; do not silently emit APIs
+   that are absent locally.
+
+## Choose The Execution Model
+
+| Contract | `Result` / `Result.gen` | `ResultAsync` | `ResultTask` |
+| --- | --- | --- | --- |
+| Execution | Sync values; `Result.gen` also accepts async generators | Starts immediately | Building/composing starts nothing; each `run*` executes again |
+| Generator return | `return ok(value)`; `yield*` short-circuits failures | Compose through `Result.gen` with `yield*` | `return value`; compose tasks, services and Results with `yield*` |
+| Error transform / recovery | `mapErr` / `orElse` | `mapErr` / `orElse` | `mapError` / `catchAll` |
+| `tap` / `tapError` failure | Ignored observation failure | Ignored observation failure | Returned task failures join `E`; throws/rejected Promises become `Die` |
+| Cleanup | Disposal callbacks are best-effort | `withResource` release is best-effort | `acquireRelease` + `scoped` await release and preserve failures |
+
+Use `ResultAsync` for existing Promise-shaped use cases. Choose `ResultTask` for reusable lazy
+work, typed service requirements, or owned resource lifetimes. Preserve existing eager/lazy
+contracts; converting an already-started Promise or ResultAsync cannot undo its execution.
+`ResultTask.runResult` can reject on defects, interruption, and composite causes. Use `runExit`
+when the boundary must inspect every exit without rejection. See [API details](references/api.md).
+For DI, Hono and Fastify, read [services and HTTP scopes](references/services.md).
+
+## Apply Opinionated Defaults
+
+- Return `Result<T, E>` for synchronous fallible work and `ResultAsync<T, E>` for asynchronous
+  fallible work.
+- Prefer `StrictResult<T, E extends Error>` and `StrictResultAsync<T, E extends Error>` at
+  application, service, HTTP, job, queue, CLI, and integration boundaries.
+- Return `ResultAsync` / `StrictResultAsync` directly from async services and repositories instead
+  of `Promise<T>`, `Promise<Result>` or `Promise<StrictResult>`. Map external driver failures to
+  typed errors in the repository adapter; services compose that result directly. Remove the
+  function's `async` wrapper; changing only its return annotation cannot change the runtime value.
+- Use `preferResultAsync: "error"` with `preferResultAsyncMode: "all"` to enforce these application
+  contracts. Document local rule suppressions for native framework/driver callbacks that require
+  Promise interoperability.
+- Prefer `createTaggedError` for expected domain and application failures that need stable identity,
+  metadata, causes, serialization, or exhaustive handling.
+- Keep error unions specific. Let composition widen them naturally; do not collapse them to `Error`
+  before the boundary.
+- Return `Err` for expected failures. Reserve `throw` for programmer defects, invalid library
+  arguments, or deliberate terminal/process boundaries.
+- Wrap third-party throws and promise rejections at the edge, then keep the internal flow Resultar-
+  native.
+- Avoid `T | Error`, sentinel `null`, broad `try/catch`, rejected expected failures, and unsafe casts
+  as substitutes for a Resultar error channel.
+- Keep `_unsafeUnwrap()` and `_unsafeUnwrapErr()` in tests. Use `unwrapOrThrow()` only when throwing
+  is explicitly the intended boundary behavior.
+
+## Choose The Composition Operator
+
+| Need                                      | Prefer                   |
+| ----------------------------------------- | ------------------------ |
+| Transform an `Ok` without failure         | `map`                    |
+| Transform an `Err`                        | `mapErr`                 |
+| Validate an `Ok` with a predicate         | `filterOrElse`           |
+| Continue with a sync fallible step        | `andThen`                |
+| Continue from `Result` into `ResultAsync` | `asyncAndThen`           |
+| Recover the whole error channel           | `orElse`                 |
+| Recover selected tagged errors            | `catchTag` / `catchTags` |
+| Branch directly                           | `isOk()` / `isErr()`     |
+| Convert a result at a boundary            | `match` / `matchTags`    |
+| Map selected tagged errors with fallback  | `matchTagsPartial`       |
+| Reuse a named Result combinator           | `pipe`                   |
+| Write a readable linear pipeline          | `safeTry` with `yield*`  |
+
+Use `catchTags` for partial pipeline recovery; unhandled tags stay in the error channel. Do not
+invent `partialCatchTags`. Use `matchTagsPartial` only for boundary matching with a deliberate
+fallback.
+
+## Model Tagged Errors
+
+```ts
+import { createTaggedError, ok } from "resultar";
+import type { StrictResult } from "resultar";
+
+class InvalidEmailError extends createTaggedError({
+  name: "InvalidEmailError",
+  message: "Invalid email $email",
+}) {}
+
+const validateEmail = (email: string): StrictResult<string, InvalidEmailError> =>
+  email.includes("@") ? ok(email) : InvalidEmailError.err({ email });
+```
+
+- Let message-template variables define required constructor props.
+- Preserve `cause` when converting an external failure.
+- Treat `ErrorClass.is(value)` as nominal; do not rely on spoofed `_tag` objects.
+- Use `TaggedEnum` only for lightweight tagged domain variants that do not need to be real errors.
+- Include an `Error` handler when a matched union can contain untagged errors.
+
+## Compose Async Work
+
+Wrap uncontrolled async work with the helper that matches how it is created:
+
+- Use `fromPromise(promise, toError)` for an already-created promise.
+- Use `tryResultAsync({ try, catch })` or `tryResultAsync(factory, toError)` when creating the
+  promise can throw synchronously.
+- Use `fromSafePromise` only when rejection is impossible by contract.
+- Use `fromCallback` for callback or subscription APIs with explicit cleanup.
+- Use `runPromise` only at a terminal boundary that intentionally resolves or throws.
+
+Prefer lazy Resultar policies over ad hoc timers or `Promise.race`:
+
+- Use `ResultAsync.retry` / `retryOrElse` for typed retry and fallback policy.
+- Use `timeout`, `race`, `raceAll`, or `raceFirst` for signal-aware concurrency.
+- Use mapped `forEach` for first-error batch work and mapped `validateAll` for collecting every
+  independent validation error.
+- Use `withResource` when successful acquisition must always trigger best-effort release.
+- Pass the provided abort signal into the underlying client; cancellation is cooperative.
+
+On `Result` and `ResultAsync`, use `tap`, `tapError`, and `log` for best-effort observation.
+`ResultTask.tap` and `tapError` participate in failure handling; they do not swallow failures. Use `andThen`, `orElse`, or a
+Resultar wrapper when callback failure must change control flow.
+
+## Use `Result.gen` For Linear Result Flows
+
+```ts
+const createUser = (input: CreateUserInput): StrictResultAsync<User, CreateUserError> =>
+  Result.gen(async function* () {
+    const email = yield* validateEmail(input.email);
+    const available = yield* ensureEmailAvailable(email);
+    const user = yield* insertUser({ ...input, email: available });
+
+    return ok(user);
+  });
+```
+
+- `safeTry` is the top-level alias of `Result.gen`; both have the same rules.
+- Use `yield*` for both `Result` and `ResultAsync` values.
+- Wrap raw promises before yielding them.
+- Do not use raw `await` or broad `try/catch` inside a Resultar `safeTry` workflow.
+- Prefer `yield* result` over legacy `safeUnwrap()`.
+
+## Keep Boundaries Concrete
+
+- Define request, command, and event payloads with concrete types; do not widen them to generic JSON
+  records before the use case.
+- Keep transport concerns out of domain code. Convert tagged errors to HTTP responses, CLI exit
+  codes, job outcomes, or logs at the outer boundary.
+- Use exhaustive `matchTags` when every tagged error needs a distinct mapping.
+- Use local `catchTag` / `catchTags` only when recovery belongs to domain policy.
+
+## Handle HTTP JSON Requests
+
+Use the Resultar request family instead of repeating fetch, parsing, validation, retry, and error
+mapping logic:
+
+- Use `resultar-request` with `validator` or `decode` for schema-library-agnostic boundaries.
+- Use `resultar-request-typebox` when contracts use TypeBox and preserve `Static<typeof schema>`.
+- Use `resultar-request-zod` when contracts use Zod and preserve transformed
+  `z.output<typeof schema>`.
+- Map request, HTTP, invalid-JSON, and validation failures to concrete tagged errors when they cross
+  an application boundary.
+
+Read `references/integrations.md` before implementing request adapters or diagnostics.
+
+## Validate In The Preferred Order
+
+1. Run the `resultar-check` CLI as the authoritative project and CI gate. It runs TypeScript and the
+   full Resultar rule set against the project.
+2. Configure `resultar-check lsp` as the editor's stdio language server for inline diagnostics and
+   quick fixes. It reads the same project configuration as the CLI.
+3. Use JSONL, SARIF, or JUnit output when another CI or review system needs structured diagnostics;
+   do not present those consumers as replacements for the native checker.
+4. Run the repository's native formatting, build, tests, analysis, package smoke, and example
+   workflows when available.
+
+JSONL fixes distinguish `correction` from `intentional-discard`; LSP actions carry the same
+classification in `data.kind`. Do not apply a discard just to silence the checker: `void task`
+does not execute a lazy task or handle its errors. Corrections still need compilation and tests.
+
+Treat stable `resultar/*` rule IDs as architecture feedback. Fix the typed boundary or composition
+problem instead of suppressing diagnostics broadly. Use narrow ignore patterns only for deliberate
+test, script, generated, or process-boundary exceptions.
+
+## Test And Document Behavior
+
+- Cover `Ok` and every expected `Err` path with runtime tests.
+- Cover inferred error unions, tagged-error props, narrowing, and exhaustive handlers with type
+  tests. Use `expectTypeOf` and `@ts-expect-error` where supported.
+- Use the consuming project's test runner. Use `vite-plus/test` inside this repository.
+- Test retry, timeout, cancellation, concurrency, and cleanup policies with deterministic fakes.
+- Derive documentation examples from checked source or runnable examples and keep package links
+  reciprocal when packages are alternatives or adapters.
+
+## Review Before Finishing
+
+- Run the project's Resultar CLI check after edits.
+- Confirm no Result, ResultAsync, or ResultTask value is silently discarded.
+- Confirm mapped errors preserve `cause` and useful metadata.
+- Confirm boundary handlers cover the actual error union.
+- Confirm request validation derives the downstream type instead of widening it.
+- Confirm validation claims match commands that actually passed.
+
+## Load References Selectively
+
+- Read `references/api.md` for current exports, collection helpers, and async policy semantics.
+- Read `references/patterns.md` for copyable implementation and migration patterns.
+- Read `references/integrations.md` for request adapters and the CLI/editor/lint workflow.
+- Read `references/review-checklist.md` for reviews, migrations, and final validation.

package/dist/agent/agents/openai.yaml

@@ -0,0 +1,4 @@
+interface:
+  display_name: "Resultar Engineering"
+  short_description: "Build and review typed Resultar workflows"
+  default_prompt: "Use $resultar to build or review a typed Resultar workflow."

package/dist/agent/examples/workflow.mjs

@@ -0,0 +1,21 @@
+import { createTaggedError, ok, Result, ResultTask } from 'resultar';
+export class InvalidEmailError extends createTaggedError({
+    name: 'InvalidEmailError',
+    message: 'Invalid email $email',
+}) {
+}
+export const validateEmail = (email) => {
+    const normalized = email.trim().toLowerCase();
+    return normalized.includes('@') ? ok(normalized) : InvalidEmailError.err({ email });
+};
+export const account = (email) => Result.gen(function* () {
+    const normalized = yield* validateEmail(email);
+    return ok({ email: normalized });
+});
+export const Greeting = ResultTask.service('greeting');
+// Creating this task runs no work. The boundary supplies its typed dependency.
+export const welcome = (email) => ResultTask.gen(function* () {
+    const normalized = yield* validateEmail(email);
+    const greeting = yield* Greeting;
+    return `${greeting}, ${normalized}`;
+});

package/dist/agent/examples/workflow.mts

@@ -0,0 +1,27 @@
+import { createTaggedError, ok, Result, ResultTask } from 'resultar'
+import type { StrictResult } from 'resultar'
+
+export class InvalidEmailError extends createTaggedError({
+  name: 'InvalidEmailError',
+  message: 'Invalid email $email',
+}) {}
+
+export const validateEmail = (email: string): StrictResult<string, InvalidEmailError> => {
+  const normalized = email.trim().toLowerCase()
+  return normalized.includes('@') ? ok(normalized) : InvalidEmailError.err({ email })
+}
+
+export const account = (email: string): StrictResult<{ email: string }, InvalidEmailError> =>
+  Result.gen(function* () {
+    const normalized = yield* validateEmail(email)
+    return ok({ email: normalized })
+  })
+
+export const Greeting = ResultTask.service<string, 'greeting'>('greeting')
+
+// Creating this task runs no work. The boundary supplies its typed dependency.
+export const welcome = (email: string) => ResultTask.gen(function* () {
+  const normalized = yield* validateEmail(email)
+  const greeting = yield* Greeting
+  return `${greeting}, ${normalized}`
+})