resultar 3.7.0 → 3.8.0

package/dist/agent/references/integrations.md

@@ -0,0 +1,264 @@
+# Resultar Requests And Validation Tooling
+
+Use this reference for HTTP JSON integrations and Resultar-specific diagnostics. Verify package
+versions and local README files before copying an example.
+
+## Contents
+
+- [Choose A Request Package](#choose-a-request-package)
+- [Use The Schema-Agnostic Core](#use-the-schema-agnostic-core)
+- [Use The TypeBox Adapter](#use-the-typebox-adapter)
+- [Use The Zod Adapter](#use-the-zod-adapter)
+- [Map Request Errors](#map-request-errors)
+- [Apply Retry Correctly](#apply-retry-correctly)
+- [Validate In The Preferred Order](#validate-in-the-preferred-order)
+- [Configure The Native Checker](#configure-the-native-checker)
+- [Act On Diagnostics](#act-on-diagnostics)
+- [Discover Repository Commands](#discover-repository-commands)
+
+## Choose A Request Package
+
+| Contract style                   | Package                    | Success type                 |
+| -------------------------------- | -------------------------- | ---------------------------- |
+| Custom type guard or decoder     | `resultar-request`         | Type guard or decoder output |
+| TypeBox schema                   | `resultar-request-typebox` | `Static<typeof schema>`      |
+| Zod schema, including transforms | `resultar-request-zod`     | `z.output<typeof schema>`    |
+
+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.
+
+Keep request payloads concrete. Do not widen a known response contract to `JsonRecord`,
+`Record<string, unknown>`, or `unknown` after validation.
+
+## Use The Schema-Agnostic Core
+
+Use a type guard when validation does not transform the payload:
+
+```ts
+import { requestJson } from "resultar-request";
+
+type User = { readonly email: string; readonly id: string };
+
+const isUser = (value: unknown): value is User =>
+  typeof value === "object" &&
+  value !== null &&
+  "email" in value &&
+  typeof value.email === "string" &&
+  "id" in value &&
+  typeof value.id === "string";
+
+const user = requestJson({
+  request: () => fetch(`https://example.com/users/${userId}`),
+  validator: isUser,
+});
+```
+
+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.
+
+## Use The TypeBox Adapter
+
+```ts
+import { createTaggedError } from "resultar";
+import {
+  requestJson as requestJsonTypeBox,
+  type RequestJsonMapError,
+} from "resultar-request-typebox";
+import { Type, type Static } from "typebox";
+
+const userSchema = Type.Object(
+  {
+    email: Type.String(),
+    id: Type.String(),
+    plan: Type.Union([Type.Literal("free"), Type.Literal("team")]),
+  },
+  { additionalProperties: false },
+);
+
+type User = Static<typeof userSchema>;
+
+class UserApiError extends createTaggedError({
+  name: "UserApiError",
+  message: "User API $reason: $detail",
+}) {}
+
+const mapUserError = {
+  404: ({ statusCode }) => new UserApiError({ detail: `HTTP ${statusCode}`, reason: "not-found" }),
+  http: ({ statusCode }) => new UserApiError({ detail: `HTTP ${statusCode}`, reason: "http" }),
+  invalidJson: ({ cause }) =>
+    new UserApiError({ cause, detail: cause.message, reason: "invalid-json" }),
+  request: ({ cause }) => new UserApiError({ cause, detail: cause.message, reason: "request" }),
+  validation: ({ errors }) =>
+    new UserApiError({ detail: `${errors.length} validation issue(s)`, reason: "validation" }),
+} satisfies RequestJsonMapError;
+
+const user = requestJsonTypeBox({
+  request: () => fetch(`https://example.com/users/${userId}`),
+  schema: userSchema,
+  mapError: mapUserError,
+  retry: { times: 2, delayMs: ({ nextAttempt }) => nextAttempt * 100, jittered: 0.2 },
+});
+```
+
+The success channel is `User`, derived from `Static<typeof userSchema>`. Keep the named adapter
+alias when a file uses more than one request helper or when the schema library should be obvious at
+the call site.
+
+## Use The Zod Adapter
+
+```ts
+import { createTaggedError } from "resultar";
+import { requestJson as requestJsonZod, type RequestJsonMapError } from "resultar-request-zod";
+import { z } from "zod";
+
+const userSchema = z
+  .object({ email: z.string().email(), id: z.string(), seats: z.number().int().nonnegative() })
+  .transform((user) => ({
+    ...user,
+    email: user.email.toLowerCase(),
+    seatLabel: `${user.seats} seats`,
+  }));
+
+type User = z.output<typeof userSchema>;
+
+class UserApiError extends createTaggedError({
+  name: "UserApiError",
+  message: "User API $reason: $detail",
+}) {}
+
+const mapUserError = {
+  404: ({ statusCode }) => new UserApiError({ detail: `HTTP ${statusCode}`, reason: "not-found" }),
+  http: ({ statusCode }) => new UserApiError({ detail: `HTTP ${statusCode}`, reason: "http" }),
+  invalidJson: ({ cause }) =>
+    new UserApiError({ cause, detail: cause.message, reason: "invalid-json" }),
+  request: ({ cause }) => new UserApiError({ cause, detail: cause.message, reason: "request" }),
+  validation: ({ errors }) =>
+    new UserApiError({ detail: `${errors.length} validation issue(s)`, reason: "validation" }),
+} satisfies RequestJsonMapError;
+
+const user = requestJsonZod({
+  request: () => fetch(`https://example.com/users/${userId}`),
+  schema: userSchema,
+  mapError: mapUserError,
+  retry: { times: 2, delayMs: ({ nextAttempt }) => nextAttempt * 100, jittered: 0.2 },
+});
+```
+
+Use `z.output`, not `z.input` or an independently maintained interface, because Zod transforms can
+change the success type.
+
+## Map Request Errors
+
+Without `mapError`, request helpers return the package's `RequestError` union. Use that union for
+infrastructure-local code. At an application boundary, use `mapError` to convert these categories
+to concrete tagged errors:
+
+- request creation, network, or fetch failure;
+- status-specific HTTP failure, with numeric handlers taking precedence over `http`;
+- invalid JSON;
+- response validation or decode failure.
+
+Preserve `cause` for request and JSON failures and preserve status, URL, validation details, and
+other safe context needed for diagnosis. Do not map every category to a message-only `Error`.
+
+## Apply Retry Correctly
+
+```ts
+const user = requestJsonZod({
+  request: () => fetch(`https://example.com/users/${userId}`),
+  schema: userSchema,
+  retry: { times: 2, delayMs: ({ nextAttempt }) => nextAttempt * 100, jittered: 0.2 },
+});
+```
+
+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`
+automatically forwards policy cancellation. Supply an external fetch signal through the request
+closure when the caller owns separate cancellation.
+
+## Validate In The Preferred Order
+
+1. Run the native `resultar-check` CLI as the authoritative local and CI gate. It uses TypeScript-Go
+   to run compiler diagnostics and all Resultar rules over the same project.
+2. Run the repository's formatter, build, tests, static analysis, package smoke tests, and runnable
+   examples.
+
+The Go analyzer is the single implementation of Resultar diagnostics.
+
+## Configure The Native Checker
+
+Install Resultar Check. A separate TypeScript installation is not required:
+
+```sh
+pnpm add -D resultar-check
+pnpm exec resultar-check
+```
+
+Add the checker configuration marker to `tsconfig.json` and tune rules only when project policy
+requires it:
+
+```json
+{
+  "$schema": "./node_modules/resultar-check/schema.json",
+  "compilerOptions": {
+    "plugins": [
+      {
+        "name": "resultar-check",
+        "noDiscard": "error",
+        "noUnsafeAwait": "error",
+        "preferAndThen": "error",
+        "preferMapErr": "error",
+        "unsafeResultTypeAssertion": "error"
+      }
+    ]
+  }
+}
+```
+
+The `plugins` entry is consumed by the native CLI and stdio LSP server; it does not install an editor
+extension. Start `resultar-check lsp` from the editor's language-server configuration. Findings use
+rule IDs such as `resultar/no-discard`; pass `--format json` (or `--json`) when machine-readable JSON
+Lines output is needed.
+
+Read `packages/check/README.md` for all rules, severities, modes, and command-line flags. Use narrow
+`ignoreFilePatterns` only for deliberate tests, scripts, generated files, or terminal process boundaries.
+
+## Act On Diagnostics
+
+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;
+- replace error-only recovery with `mapErr`;
+- replace project-wide `try/catch` with `tryResult` or `tryResultAsync` when `noTryCatch` is enabled;
+- wrap raw promise awaits in Resultar contexts;
+- use `yield*` and avoid `try/catch` inside `Result.gen` / `safeTry`;
+- preserve the inferred error channel instead of asserting it away.
+
+## Discover Repository Commands
+
+Inspect `package.json` scripts instead of assuming a package manager or command. In the Resultar
+repository, the relevant root commands currently include:
+
+```sh
+pnpm fmt:check
+pnpm build
+pnpm check
+pnpm test
+pnpm analyze
+pnpm smoke:package
+pnpm test:examples
+pnpm test:agents
+```
+
+Run the narrowest useful command while iterating, then the complete relevant validation set before
+claiming completion. Report pre-existing dependency, lockfile, or environment blockers separately
+from failures introduced by the skill work.

package/dist/agent/references/patterns.md

@@ -0,0 +1,246 @@
+# Resultar Implementation Patterns
+
+Use these patterns as starting points, then align names and types with the consuming domain.
+
+## Contents
+
+- [Model A Domain Failure](#model-a-domain-failure)
+- [Compose Sync And Async Steps](#compose-sync-and-async-steps)
+- [Write A Linear Workflow](#write-a-linear-workflow)
+- [Wrap External Work](#wrap-external-work)
+- [Apply Retry And Timeout Policy](#apply-retry-and-timeout-policy)
+- [Process Batches](#process-batches)
+- [Acquire And Release Resources](#acquire-and-release-resources)
+- [Recover Locally And Match At Boundaries](#recover-locally-and-match-at-boundaries)
+- [Add Observability](#add-observability)
+- [Migrate Incrementally](#migrate-incrementally)
+- [Test Runtime And Type Behavior](#test-runtime-and-type-behavior)
+
+## Model A Domain Failure
+
+```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.trim().toLowerCase()) : InvalidEmailError.err({ email });
+```
+
+Use real tagged errors when the failure crosses a service, HTTP, job, queue, CLI, or integration
+boundary. Keep strings, enums, or `TaggedEnum` variants for intentionally local flows.
+
+## Compose Sync And Async Steps
+
+```ts
+type CreateUserError = InvalidEmailError | UserAlreadyExistsError | SaveUserError;
+
+const createUser = (input: CreateUserInput): StrictResultAsync<User, CreateUserError> =>
+  validateEmail(input.email)
+    .asyncAndThen(ensureEmailAvailable)
+    .andThen((email) => saveUser({ ...input, email }));
+```
+
+- Use `map` only for an infallible value transform.
+- Use `filterOrElse` for predicate validation.
+- Use `andThen` when the next operation can fail.
+- Use `asyncAndThen` only for the sync-to-async bridge.
+- 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 email = yield* validateEmail(input.email);
+    yield* ensureEmailAvailable(email);
+    const user = yield* saveUser({ ...input, email });
+
+    return ok(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.
+
+## Wrap External Work
+
+```ts
+class ProfileApiError extends createTaggedError({
+  name: "ProfileApiError",
+  message: "Profile API failed for $userId",
+}) {}
+
+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 }),
+  );
+```
+
+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.
+
+For callback or subscription APIs, use `fromCallback` 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();
+  },
+});
+```
+
+Check the installed `ResultAsyncFromCallbackOptions` type for exact client integration details.
+
+## 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 }),
+  },
+);
+```
+
+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.
+
+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.
+
+## Process Batches
+
+Stop at the first error with bounded concurrency:
+
+```ts
+const saved = ResultAsync.forEach(rows, saveRow, { concurrency: 8 });
+```
+
+Collect all independent errors instead:
+
+```ts
+const validated = ResultAsync.validateAll(rows, validateRow, { concurrency: 8 });
+```
+
+Use `{ discard: true }` with `forEach` when successful values are intentionally unused. Do not
+silently discard the returned `ResultAsync` itself.
+
+## Acquire And Release Resources
+
+```ts
+const imported = ResultAsync.withResource({
+  acquire: (signal) => openImportSession({ signal }),
+  use: (session, signal) => importRows(session, rows, { signal }),
+  release: (session) => session.close(),
+});
+```
+
+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.
+
+## Recover Locally And Match At Boundaries
+
+Recover only where the fallback is part of application policy:
+
+```ts
+const profile = loadProfile(userId).catchTags({
+  ProfileNotFoundError: () => ok(defaultProfile),
+  ProfileDisabledError: () => ok(disabledProfile),
+});
+```
+
+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 }), {
+  InvalidEmailError: (error) => ({ body: error.toJSON(), statusCode: 400 }),
+  UserAlreadyExistsError: (error) => ({ body: error.toJSON(), statusCode: 409 }),
+  SaveUserError: (error) => ({ body: error.toJSON(), statusCode: 500 }),
+});
+```
+
+Use `matchTagsPartial` only when a shared fallback is intentional. Keep HTTP status codes out of
+domain functions.
+
+## 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 }))
+  .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.
+
+## 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`.
+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.
+
+Avoid converting the whole codebase in one unsafe cast. A wrapper at an integration seam lets the
+typed error channel spread in reviewable steps.
+
+## Test Runtime And Type Behavior
+
+```ts
+import { equal, ok as assert } from "node:assert";
+import { describe, expectTypeOf, it } from "vite-plus/test";
+
+describe("validateEmail", () => {
+  it("returns a typed tagged error", () => {
+    const result = validateEmail("invalid");
+
+    assert(result.isErr());
+    equal(result.error._tag, "InvalidEmailError");
+    expectTypeOf(result.error).toEqualTypeOf<InvalidEmailError>();
+  });
+});
+```
+
+Test every expected error path, not just `Ok`. Add type tests for inferred unions, required tagged
+error props, narrowing, and exhaustive handlers. Use deterministic fake clocks, signals, and
+clients for retry, timeout, cancellation, race, concurrency, and cleanup tests.

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

@@ -0,0 +1,122 @@
+# Resultar Review And Migration Checklist
+
+Use this checklist for implementation reviews, migrations, documentation changes, and final
+validation. Report only issues supported by the installed Resultar version and repository evidence.
+
+## Source And Scope
+
+- Confirm the installed `resultar`, request adapter, and `resultar-check` versions.
+- 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`.
+- 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.
+- Sensitive metadata is redacted when serialization or logging could expose it.
+
+## Composition
+
+- `map` performs only infallible success transforms.
+- `mapErr` performs error-only transforms.
+- `filterOrElse` represents predicate validation.
+- `andThen` composes fallible steps; `asyncAndThen` is used for the sync-to-async bridge.
+- `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`.
+- Returned `Result`, `ResultAsync`, and `ResultTask` values are handled or explicitly discarded by supported policy.
+- Type assertions do not narrow away possible errors.
+
+## Async Boundaries And Policy
+
+- 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.
+- Callback integrations provide cleanup and model `AbortError` where applicable.
+- Retry policy defines bounded attempts, delay/jitter, retryable errors, and cancellation.
+- Timeout scope is explicit: per attempt or across the complete retry budget.
+- `race`/`raceAll` are used for first settlement; `raceFirst` for first success.
+- 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.
+
+## 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.
+- 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
+  deliberate terminal boundaries.
+
+## HTTP Requests
+
+- `resultar-request` is used for a custom guard/decoder; TypeBox and Zod use their dedicated
+  adapters.
+- TypeBox success types derive from `Static<typeof schema>`.
+- Zod success types derive from `z.output<typeof schema>` so transforms are preserved.
+- Validated values are not widened back to `JsonRecord`, `Record<string, unknown>`, or `unknown`.
+- Error mapping distinguishes request, HTTP, invalid-JSON, and validation failures.
+- 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.
+
+## Observability And Cleanup
+
+- `Result` / `ResultAsync` observation failures are best-effort; `ResultTask.tap` / `tapError`
+  can introduce typed failures or defects.
+- Resource cleanup and observation use the semantics of the concrete execution model.
+- 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.
+
+## Tests And Documentation
+
+- Runtime tests cover `Ok` and every expected `Err` branch.
+- Type tests cover inferred error unions, required tagged-error props, narrowing, and exhaustive
+  handlers.
+- Retry, timeout, cancellation, races, concurrency, and cleanup use deterministic fakes.
+- Tests use the repository's actual runner; this repository uses `vite-plus/test`.
+- 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.
+- An intentional-discard fix is not mistaken for executing or handling a lazy task.
+
+## Validation Order
+
+1. Run the `resultar-check` CLI as the authoritative project check.
+2. Confirm the `resultar-check lsp` stdio server emits Resultar diagnostics and quick fixes in the
+   editor.
+3. Use JSONL, SARIF, or JUnit output when a CI/review system needs structured diagnostics; keep the
+   native CLI as the authoritative check.
+4. Run formatting, build, tests, analysis, package smoke tests, and example workflows that apply.
+5. Report exactly which commands passed, failed, or were blocked.
+
+## Review Red Flags
+
+- `T | Error`, sentinel `null`, message strings, or thrown expected failures replace a Resultar
+  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`.
+- `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()`.
+- 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.
+- 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

@@ -0,0 +1,39 @@
+# Typed services and HTTP scopes
+
+Read the installed `resultar-di/README.md`, `resultar-hono/README.md` and `resultar-fastify/README.md` for the exact companion
+versions. The primary DI exports are `createModule`, `service`, and `resource`; class tokens and
+named factory overloads belong to `resultar-di/advanced`.
+
+- Register a service token with `.singleton(Token)`, `.scoped(Token)`, or `.transient(Token)`.
+  Dependency objects are inferred from tokens. Use `service(name, task)` for asynchronous
+  initialization; an async function passed as an ordinary factory is a defect in the contract.
+- Keep a server's serving-and-waiting task inside its owning `use` / ResultTask scope. Returning a
+  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.
+- 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()`.
+- Use `createFastifyPlugin({ services, bindings, appBindings?, locals? })` for native Fastify routes.
+  `app.services` contains the selected startup singletons; `request.services` is available from
+  `preHandler` through response completion. Register authentication providing locals earlier.
+  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.
+- `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.
+- `scope.fetch`, `services.http`, and `createHonoApp` keep the request scope open until the Response
+  body ends, fails, or is canceled. Tests must consume or cancel response bodies before shutdown.
+- Stop and drain the server, finish/cancel persistent streams, then await application close.
+  Handle typed release errors; defects and composite causes may reject `close()`.
+- Supply authenticated request locals through the appropriate per-request integration. A singleton
+  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/`
+application lifecycle examples. The distributed guide includes the checked core recipe at
+`examples/workflow.mjs`; use the published declarations to adapt companion integrations.

package/dist/agent/versions.json

@@ -0,0 +1,10 @@
+{
+  "resultar-check": "3.2.0",
+  "resultar-di": "0.2.0",
+  "resultar-fastify": "0.2.0",
+  "resultar-hono": "0.2.0",
+  "resultar-request": "0.1.2",
+  "resultar-request-typebox": "0.1.2",
+  "resultar-request-zod": "0.1.2",
+  "resultar": "3.8.0"
+}