brass-runtime 1.15.0 → 1.16.1

package/docs/ai/PUBLIC_API.md

@@ -0,0 +1,336 @@
+# Public API
+
+This file tracks the package surface that users can import.
+
+## Package exports
+
+Defined in `package.json`:
+
+- `brass-runtime` -> `dist/index.*`
+- `brass-runtime/core` -> `dist/core/index.*`
+- `brass-runtime/http` -> `dist/http/index.*`
+- `brass-runtime/http/testing` -> `dist/http/testing.*`
+- `brass-runtime/schema` -> `dist/schema/index.*`
+- `brass-runtime/observability` -> `dist/observability/index.*`
+- `brass-runtime/perf` -> `dist/perf/index.*`
+- `brass-runtime/agent` -> `dist/agent/index.*`
+- `brass-runtime/package.json`
+- `brass-runtime/wasm/pkg/brass_runtime_wasm_engine.js`
+- `brass-runtime/wasm/pkg/brass_runtime_wasm_engine_bg.wasm`
+
+CLI:
+
+- `brass-agent` -> `dist/agent/cli/main.cjs`
+- `brass-perf` -> `dist/perf/cli.cjs`
+
+Bundle entries are defined in `tsup.config.ts`. Package files include `dist`,
+`wasm/pkg`, `README.md`, `CHANGELOG.md`, `docs`, `LICENSE`, and `package.json`.
+
+## Root export: `brass-runtime`
+
+Source: `src/index.ts`
+
+The root export is compatibility-first. New public APIs should prefer a named
+subpath when they belong to an optional subsystem (`brass-runtime/http`,
+`brass-runtime/agent`, future stream/runtime subpaths) instead of widening the
+root surface by default.
+
+Primary categories:
+
+- effect/core types: `Async`, `ZIO`, `Exit`, `Cause`, `Option`, cancel types
+- runtime execution: `Runtime`, `makeRuntime`, `runPromise`, `runExit`,
+  `runEffect`, `fork`, `toPromise`, scheduler/fiber/scope
+- resources and structured concurrency helpers: `Resource`, `managed`,
+  `Supervisor`, `makeSupervisor`, `joinSupervised`
+- interruptibility helpers: `uninterruptible`, `interruptible`,
+  `uninterruptibleMask`
+- semaphore, circuit breaker, `Ref`, `FiberRef`, declarative `Schedule`,
+  `ScheduleDriver`, Schedule 2.0 combinators/observers, shutdown, TS
+  `TestRuntime`, `TestScheduler`, `TestClock`, and testing helpers
+- Layer 2.0 dependency graph helpers: `Layer`, `LayerContext`,
+  `ServiceTag`, `makeServiceTag`, `layerValue`, `layerEffect`,
+  `defineService`, `getService`, `formatLayerError`, `buildLayer`,
+  `makeLayerScope`, `provide`, and `provideLayerContext`
+- worker pool, tracing, metrics, runtime observability hooks/events
+- typed errors
+- runtime engines and capabilities
+- streams, buffers, queues, hubs, pipelines, chunks, operators, and root-level
+  `Stream` / `Pipeline` DX facades
+
+When adding a root export:
+
+- Check whether it belongs in core or a subpath.
+- Avoid exporting test/benchmark/internal implementation details.
+- Add or update docs/examples when the export is user-facing.
+- Keep `Cause<E>` compatible with typed failures, defects, interruptions, and
+  composed `Then` / `Both` failure trees.
+
+## Core export: `brass-runtime/core`
+
+Source: `src/core/index.ts`
+
+This is the preferred stable core surface for new imports. It intentionally
+exports effect/runtime/resource/layer/schedule/observability helpers without
+the lower-level engine, scheduler queue, ring-buffer, and WASM bridge internals
+that remain available from the root export for compatibility.
+
+Observability helpers include `RuntimeHooks`, `RuntimeEvent`,
+`RuntimeEventRecord`, `EventBus`, `makeRuntimeRecorder`, `consoleJsonLogger`,
+`RuntimeRegistry`, `dumpAllFibers`, and `InMemoryTracer`. Core also exposes
+`Resource`, `makeResource`, `resourceAll`, `Schedule` constructors/combinators,
+`Schedule.driver` / `makeScheduleDriver`, runtime-clock-aware schedule runners,
+supervisor APIs, `makeRuntime` / `runPromise` / `runExit`, and Layer 2.0
+primitives for typed service tags, immutable contexts, scoped memoized builds,
+missing-service formatting, and idempotent release.
+
+## HTTP export: `brass-runtime/http`
+
+Source: `src/http/index.ts`
+
+Recommended API order:
+
+- `makeDefaultHttpClient` for the one-stop default client with JSON/text
+  helpers, lifecycle presets (`production`, `default`, `balanced`, `minimal`),
+  compression, stats, cache controls, `cancelAll`, and middleware integration.
+- `makeHttpRouter`, `route` / `httpRoute`, and `makeNodeHttpServerResource`
+  for the first-party HTTP server MVP: Node adapter, simple router,
+  effect-based middleware, schema validation, observability, runtime
+  health/readiness probes, typed path params, and managed `.listen()`
+  lifecycle.
+- `HttpServer` for the discoverable server DX object: routes, router, listen,
+  resource, JSON/text/empty responses, health/readiness routes, and simple
+  middleware helpers.
+- `httpClient` for day-to-day typed text/JSON calls.
+- `s` / `schema` and `validatedJson` for dependency-free HTTP JSON
+  validation with typed validation errors.
+- `httpClientBuilder` / `makeHttpClientBuilder` for a discoverable builder
+  API over the default client presets and lifecycle layers.
+- `adaptiveLimiterPresets` / `makeAdaptiveLimiterConfig` for documented
+  `conservative`, `balanced`, and `aggressive` adaptive concurrency baselines.
+- `makeHttpClient` / `makeLifecycleClient` for cache, deduplication, priority
+  queues, retry, lifecycle events, stats, and bulk cancellation.
+- `makeHttp` / `makeHttpStream` for low-level wire behavior and middleware
+  authors.
+- `HttpTransport`, `HttpStreamTransport`, `makeFetchTransport`, and
+  `makeFetchStreamTransport` for replacing the default fetch-backed transport
+  with an effect-based backend such as Axios, undici, or test doubles.
+- `makePromiseHttpTransport`, `promiseHttpTransport`, and
+  `normalizeHttpHeaders` for adapting Promise-based clients without writing
+  `Async.async` / `Cause.fail` plumbing in consuming projects; the fluent
+  builder supports `requestConfig(...).send(...).json()` for
+  Axios/Fetch-shaped responses with automatic `AbortSignal` injection.
+- `toHttpError`, `isAbortHttpError`, `isTimeoutHttpError`,
+  `isFetchHttpError`, `httpErrorStatus`, `isRetryableHttpStatus`, and
+  `isRetryableHttpError` for normalizing external client failures
+  (including Axios-like `response.status`, aborts, and timeout codes) and
+  deciding retryability.
+- `HttpRequestPolicy`, `HttpRequestPolicyRef`, `HttpPolicyPresets`,
+  `ResolveHttpRequestPolicyOptions`, `defineHttpPolicyPresets`, `httpPolicy`,
+  `getHttpRequestPolicy`, `withHttpRequestPolicy`, and `withHttpPolicyPresets`
+  for structured
+  per-request execution knobs (`preset`, `priority`, `dedupKey`, `retry`,
+  `poolKey`, `lane`) while preserving legacy top-level request fields.
+- `DefaultHttpClientConfig.policyPresets` for resolving `policy: "name"` and
+  `policy: { preset: "name", ...overrides }` before lifecycle middleware.
+- `httpClientWithMeta` for metadata-oriented compatibility helpers.
+
+Primary categories:
+
+- low-level HTTP client and request/response types
+- effect-based transport boundary with fetch as the default implementation
+- structured per-request policy shared by transport, retry, deduplication,
+  priority scheduling, pool/circuit-breaker keying, and DX request helpers
+- ergonomic HTTP client helpers
+- HTTP server router, Node adapter, response helpers, and server resources
+- HTTP runtime probe helpers: `makeRuntimeHealthRoute` and
+  `makeRuntimeReadinessRoute`
+- production HTTP client presets (`minimal`, `balanced`, `default`)
+- dependency-free schema validation for JSON responses
+- builder API for default HTTP client configuration
+- adaptive limiter presets, diagnostics, and public config helper
+- pool, circuit breaker, tracing, validation
+- lifecycle cache/dedup/priority/stats APIs
+- retry middleware
+- retry middleware accepts an optional declarative `Schedule` for retry delays
+  while preserving `Retry-After`, max retries, elapsed-budget behavior, and
+  `onScheduleDecision` observability through the Schedule 2.0 driver
+- response and request compression middleware
+- request batching middleware
+- connection pre-warming utilities and middleware
+
+## HTTP testing export: `brass-runtime/http/testing`
+
+Source: `src/http/testing.ts`
+
+Dependency-free helpers for users' test suites:
+
+- `makeMockHttpClient`, `makeSequenceHttpClient`
+- `makeHttpResponse`, `makeTextHttpResponse`, `makeJsonHttpResponse`
+- `runHttpEffect`
+- `installMockFetch`, `withMockFetch`
+- `makeFetchResponse`, `makeJsonFetchResponse`
+
+## Schema export: `brass-runtime/schema`
+
+Source: `src/schema/index.ts`
+
+Dependency-free validation DSL shared by HTTP and any future package area that
+needs runtime data validation:
+
+- `s` / `schema` / `Schema`
+- `Schema`, `InferSchema`, `SchemaResult`, `SchemaIssue`
+- primitive/object/array/record/union/literal/enum/custom schemas
+- shortcuts: `email`, `url`, `uuid`, `int`, `positive`, `nonEmptyString`, `dateIso`
+- `optional`, `nullable`, `refine`, `transform`
+- `formatIssues`, `validateValue`, `parseConfig`, `formatConfigError`,
+  `isConfigValidationError`
+- `SchemaValidationException`, `ConfigValidationError`
+
+When changing HTTP API:
+
+- Keep wire/content/meta separation clear.
+- Keep lazy execution and cancellation semantics.
+- `postJson(..., body, { bodySchema })` should infer the request body type from
+  `bodySchema` and validate it before network I/O.
+- Public error helpers live in `src/http/errors.ts` and are exported from
+  `brass-runtime/http`.
+- `AdaptiveLimiter` exposes per-key TTL eviction, explicit warmup,
+  `probeJitterRatio`, slow-start recovery, `headroomStrategy`,
+  `baselineStrategy`, `decreaseCooldownSamples`, limit-change `history(key)`,
+  weighted windows via `windowDecayFactor`, multi-signal error gradients via
+  `errorWeight`, priority queue/load-shedding knobs, `PoolRejected.retryAfterMs`
+  backoff hints, `markCircuitOpen(key)`, diagnostics (`keys`, `snapshot`,
+  `dump`) with utilization/throughput/error rate, and `destroy()`/`shutdown()`.
+- `AdaptiveLimiterConfig.preset` accepts `conservative`, `balanced`, and
+  `aggressive`; caller overrides apply on top of the selected preset.
+- Update `docs/http.md` and `src/http/README.md` for user-visible behavior.
+- Add focused tests under `src/http/__tests__`.
+
+## Observability export: `brass-runtime/observability`
+
+Source: `src/observability/index.ts`
+
+This is the preferred production export surface for taking runtime signals out
+of process without adding mandatory vendor dependencies.
+
+Primary categories:
+
+- Prometheus text formatting and registry exporters for `MetricsRegistry`
+- OTLP JSON/HTTP exporters for metrics and spans
+- runtime metrics sink for `EventBus.subscribeHooks`
+- structured log sink plus effect-level logging helpers
+- `withSpan` and `spanEvent` for trace spans across effect composition
+- `makeObservability` production preset with `flush()` and `shutdown()`
+- `withHttpObservability` middleware for HTTP client metrics, logs, spans, and
+  W3C `traceparent` injection, including request-policy context in logs/spans
+  and opt-in policy metric labels
+- `HTTP_OBSERVABILITY_CONTRACT` for stable dashboard metric names, label names,
+  span attribute names, and structured log message names
+- adaptive limiter gauges and HTTP span attributes when the wrapped client
+  exposes an owned limiter
+- W3C trace-context helpers (`parseTraceparent`, `extractTraceContext`,
+  `formatTraceparent`, `injectTraceContext`) plus request adapters for seeding
+  runtime traces from incoming headers
+- production hardening helpers for exporter pipelines, sampling, redaction,
+  metric-cardinality limiting, environment presets, no-op setup, and inbound
+  adapters for Fetch/Node/Express/Fastify-style request objects
+- OTLP log export, server-side HTTP request metrics/spans, span retention
+  pruning, single-flight flush behavior, collector smoke script, and
+  observability benchmark budgets
+- runtime health helpers: `makeRuntimeHealth`, `runtimeHealth`, `readiness`,
+  and `healthToHttpResponse` for runtime/fiber/scope/scheduler plus registered
+  circuit breaker/adaptive limiter health
+- runtime supervisor events are counted by runtime metrics sinks and are
+  available to structured log/tracing sinks via `RuntimeHooks`
+
+When changing observability API:
+
+- Keep exporters dependency-free and backend-neutral.
+- Do not let sink/exporter failures affect effect semantics.
+- Keep high-cardinality labels opt-in.
+- Add tests under `src/observability/__tests__`.
+
+## Performance export: `brass-runtime/perf`
+
+Source: `src/perf/index.ts`
+
+This is the built-in performance profiling surface for runtime and HTTP work.
+It is intentionally a separate subpath because it depends on runtime, HTTP, and
+observability modules.
+
+Primary categories:
+
+- `makePerfRecorder` and `summarizePerfEvents` for low-overhead local
+  measurement with a bounded ring buffer.
+- `captureMemorySnapshot`, `diffMemorySnapshots`, and
+  `profileMemoryRetention` for heap/rss/external memory reports with optional
+  forced GC.
+- `profileRuntimePrimitives` for sampled runtime primitive throughput.
+- `diagnoseRuntimeProfile` for hot primitive, fiber pressure, and hook/recorder
+  diagnostics.
+- `profileRuntimeAb` / `formatRuntimeAbReport` for runtime-only baseline vs
+  candidate comparisons.
+- `profileRuntimeSoak` / `formatRuntimeSoakReport` for repeated runtime-only
+  soak profiles.
+- `runRuntimePerfBudget` for CI-friendly runtime profiler budgets.
+- `profileHttpLayers` for local HTTP layer comparison across `node:http`, wire
+  client, default presets, adaptive limiter, and observability.
+- `profileHttpMemoryLab` / `formatHttpMemoryLabReport` for long-run HTTP
+  memory comparisons with heap/rss totals, heap per 10k requests, GC signal,
+  and per-variant verdicts.
+- `createPerfHistoryEntry`, `recordPerfHistoryRun`, `readPerfHistory`,
+  `savePerfBaseline`, `loadPerfBaseline`, `comparePerfToBaseline`, and
+  `formatPerfBaselineComparison` for local JSONL perf history and named
+  baseline regression checks.
+- `recommendPerformance` for heuristic warnings and next actions.
+- `runBrassPerformanceProfile` and `formatPerformanceReport` for the complete
+  report used by `npm run perf`, `npm run perf:json`, `npm run benchmark:perf`,
+  `npm run perf:history`, and the `brass-perf` binary.
+
+When changing performance API:
+
+- Keep profiler defaults small enough for local iteration.
+- Keep long, stable regression checks in `src/benchmarks` and budget scripts.
+- Do not make core depend on HTTP or observability.
+- Prefer JSON-friendly report shapes.
+
+## Agent export: `brass-runtime/agent`
+
+Source: `src/agent/index.ts`
+
+Primary categories:
+
+- agent state, reducer, decisions, events, config
+- project commands/profile/context discovery
+- patch quality, rollback safety, redaction, language, batch
+- permissions, approvals, policy, retry, timeout, patch tools
+- node services for shell, filesystem, patching, config, workspace discovery
+- LLM adapters
+
+When changing agent API:
+
+- Preserve boundaries in `docs/agent-boundaries.md`.
+- Keep CLI/node adapters separate from pure core logic.
+- Update relevant `docs/agent-*.md` files.
+
+## Generated outputs
+
+Do not edit these directly during normal source changes:
+
+- `dist`
+- `coverage`
+- `wasm/pkg`
+
+Regenerate them with build/test commands when the task requires generated
+artifacts.
+
+## Compatibility checklist
+
+For public API changes:
+
+- Is the export intentional?
+- Does the package export map expose it?
+- Do both CJS and ESM builds work?
+- Do type declarations include it?
+- Are README/docs examples still correct?
+- Is the change semver-relevant?

package/docs/ai/VALIDATION_MATRIX.md

@@ -0,0 +1,67 @@
+# Validation Matrix
+
+Use this to choose the smallest useful validation set for a change.
+
+## Baseline
+
+Run these for normal code changes:
+
+```bash
+npm run test:types
+npm test
+```
+
+## Full package confidence
+
+Run this before release, package export work, or broad refactors:
+
+```bash
+npm run check:full
+npm run validate:cjs
+```
+
+Notes:
+
+- `npm run build` and `npm run check:full` require `wasm-pack`.
+- `npm run check` includes coverage and is slower than the baseline.
+
+## By changed area
+
+| Changed area | Useful commands | Also inspect |
+| --- | --- | --- |
+| `src/core/types` | `npm run test:types`; `npm test -- src/core/types src/core/runtime/__tests__/flatmap` | `docs/ai/INVARIANTS.md`; `docs/ARCHITECTURE.md` |
+| `src/core/runtime` | `npm run test:types`; `npm test -- src/core/runtime/__tests__` | engine parity tests; scheduler/fiber/scope/resource/supervisor invariants |
+| `src/core/runtime/engine` | `npm run test:types`; `npm test -- src/core/runtime/__tests__/engine` | `docs/wasm-fiber-engine.md`; TS/WASM parity |
+| `src/observability` | `npm run test:types`; `npm test -- src/observability/__tests__ src/core/runtime/__tests__/eventBus.test.ts` | `docs/observability.md`; `docs/ai/PUBLIC_API.md` |
+| `src/perf` | `npm run test:types`; `npm test -- src/perf/__tests__`; `npm run perf -- --profile runtime`; `npm run perf:history -- --profile runtime`; `npm run perf:runtime:ab`; `npm run perf:runtime:soak`; `npm run perf:runtime:budget`; `npm run perf:http:memory -- --calls 1000 --concurrency 64 --warmup 0 --variants default-json,default-json-observed`; optional `node --expose-gc --import tsx src/perf/cli.ts --profile http-memory --calls 1000 --concurrency 64 --force-gc` | `docs/performance-profiler.md`; `docs/ai/PUBLIC_API.md` |
+| `src/examples/observability*` | `npm run example:observability:express`; `npm run example:observability:fastify`; `npm run example:observability:nest` after installing optional framework deps | `docs/observability-framework-examples.md` |
+| observability collector smoke | `npm run build:ts`; `docker compose -f docker-compose.observability.yml up`; `npm run smoke:observability:collector` | `docs/observability-collector-smoke.md`; `docs/otel-collector-smoke.yaml` |
+| `src/core/stream` | `npm run test:types`; `npm test -- src/core/stream/__tests__` | stream ordering, backpressure, cancellation |
+| `src/http/client.ts`, `src/http/httpClient.ts` | `npm run test:types`; `npm test -- src/http/__tests__/http` | `docs/http.md`; `src/http/README.md` |
+| `src/http/server.ts` | `npm run test:types`; `npm test -- src/http/__tests__/server.test.ts src/observability/__tests__/productionObservability.test.ts` | `docs/http.md`; `src/http/README.md`; `docs/observability.md` |
+| `src/http/batching.ts`, `src/http/prewarm.ts` | `npm run test:types`; `npm test -- src/http/__tests__/batching.test.ts src/http/__tests__/prewarm.test.ts` | batching encoder/decoder shape; cancellation before flush |
+| `src/http/retry` | `npm run test:types`; `npm test -- src/http/__tests__/retry` | retry budgets, aborts, pool interaction |
+| `src/http/lifecycle` | `npm run test:types`; `npm test -- src/http/__tests__/cacheKey src/http/__tests__/dedup src/http/__tests__/lifecycleClient src/http/__tests__/lruCache src/http/__tests__/priority src/http/__tests__/responseCache src/http/__tests__/stats src/http/__tests__/middleware` | `src/http/lifecycle/README.md` |
+| `src/http/compression` | `npm run test:types`; `npm test -- src/http/__tests__/compression.test.ts` | content/header semantics and environment support |
+| `src/agent` | `npm run test:types`; `npm run agent:test:smoke` | `docs/agent-boundaries.md`; config/policy docs |
+| `extensions/vscode-brass-agent` | extension build/test command if present; `npm run agent:vscode:package` | VS Code install/clean docs |
+| `crates/brass-runtime-wasm-engine` | `npm run build:wasm`; `npm test -- src/core/runtime/__tests__/engine src/core/runtime/__tests__/scheduler` | Rust code, generated bridge shape |
+| `package.json`, `tsup.config.ts`, exports | `npm run build`; `npm run validate:cjs`; `npm run test:types` | `docs/ai/PUBLIC_API.md`; `README.md` install examples |
+| release candidate | `npm run release:check`; optional GC-aware `node --expose-gc --import tsx src/perf/cli.ts --profile http-memory --calls 100000 --concurrency 512 --delay-ms 2 --force-gc` | `docs/release.md`; `CHANGELOG.md`; `docs/recipes/` |
+| docs only | link/path review; optional `npm run context` | `docs/README.md`; public API examples |
+| benchmarks | `npm run benchmark`; `npm run benchmark:json`; `npm run benchmark:runtime`; `npm run benchmark:runtime:budget`; `npm run benchmark:http:budget`; `npm run benchmark:observability`; `npm run benchmark:observability:budget`; `npm run benchmark:perf`; `npm run perf:runtime:budget`; related tests | benchmark thresholds, warnings, profiler output, and heap-per-suspended-fiber details |
+
+## Property tests
+
+Prefer property tests when changing:
+
+- algebra laws (`flatMap`, `map`, reassociation)
+- schedulers, queues, ring buffers, caches
+- stream ordering/backpressure behavior
+- retry/lifecycle policies with many combinations
+
+## Test naming conventions
+
+- Deterministic unit tests use `*.test.ts`.
+- Property tests use `*.pbt.test.ts` or `*.property.test.ts`.
+- Keep tests under the owning module's `__tests__` directory.

package/docs/api-polish.md

@@ -0,0 +1,37 @@
+# API Polish Notes
+
+First-release DX pass.
+
+## Public API audit
+
+- Kept existing exports for compatibility.
+- Added small aliases/helpers instead of renaming established APIs.
+- Kept optional subsystems on subpaths: `http`, `schema`, `observability`,
+  `perf`, and `agent`.
+- Added a public API release snapshot test for the most important first-release
+  symbols.
+
+## Happy paths
+
+- Runtime: `runPromise`, `runExit`, `makeRuntime`.
+- Layers: `defineService`, `getService`, `provide`, `provideContext`,
+  `formatLayerError`.
+- HTTP server: `HttpServer` discoverability object over route/router/listen
+  and response helpers.
+- Config/schema: `formatConfigError`, `isConfigValidationError`.
+- Performance: `perf:history`, named baselines, and release recipes.
+
+## Type inference
+
+Type tests cover:
+
+- HTTP client request/response schema inference.
+- HTTP server path param and schema override inference.
+- Schema `InferSchema`.
+- Layer service tags and provide aliases.
+- Runtime `runPromise` / `runExit` return types.
+
+## Release posture
+
+The first-release gate is `npm run release:check`. A GC-aware HTTP memory lab is
+still recommended manually on the release machine before publishing.

package/docs/cancellation.md

@@ -0,0 +1,162 @@
+# 🛑 Cancellation & Interruption
+
+This document explains **how cancellation works** in `brass-runtime`, what `Interrupted` means, and which rules `Async` effects must follow to be truly cancellable.
+
+> TL;DR: if an `Async` blocks on external work (timers, fetch, streams, sockets), it **must be cancellable**. Cancellation propagates through **Scope** and via **Fiber.interrupt()**.
+
+---
+
+## Vocabulary
+
+- **Fiber**: cooperative unit of execution (similar to a “green thread”).
+- **Scope**: lifetime container that **owns fibers** and **finalizers**.
+- **Interrupted**: cancellation signal. A *value* in the error channel (not a thrown JS exception).
+- **Finalizer**: action executed when a scope closes (success, failure, or interruption).
+
+---
+
+## Semantic rules
+
+### 1) What triggers interruption?
+
+A fiber can be interrupted by:
+
+- `fiber.interrupt()`
+- `scope.close(...)` (interrupts all child fibers registered in that scope)
+- closing a parent scope (propagates to subscopes)
+
+### 2) How do you observe interruption?
+
+Interruption is observed as:
+
+- an `Exit` with `_tag: "Failure"` and `error: { _tag: "Interrupted" }`.
+
+### 3) When does work actually stop?
+
+Cancellation is **cooperative**:
+
+- CPU-only work is interrupted at **checkpoints** (between interpreter steps).
+- IO/timers/promises are interrupted **only if** the underlying `Async` supports cancellation (next section).
+
+---
+
+## Cancellable Async: the contract
+
+An `Async<R, E, A>` that performs IO must be able to “detach” that IO when interrupted:
+
+- **Timers**: `clearTimeout`, `clearInterval`
+- **Fetch**: `AbortController` / `AbortSignal`
+- **Streams**: `reader.cancel()`, `controller.abort()`, etc.
+
+### Recommended primitive: `fromPromiseAbortable`
+
+If your runtime provides `fromPromiseAbortable`, use it as the canonical way to wrap `Promise` + `AbortSignal` APIs.
+
+Example: cancellable `sleep(ms)`
+
+```ts
+import type { Async } from "../core/types/asyncEffect";
+import type { Interrupted } from "../core/runtime/fiber";
+import { fromPromiseAbortable } from "../core/runtime/runtime";
+
+export function sleep(ms: number): Async<unknown, Interrupted, void> {
+  return fromPromiseAbortable<Interrupted, void>(
+    (signal) =>
+      new Promise<void>((resolve, reject) => {
+        const id = setTimeout(resolve, ms);
+
+        const onAbort = () => {
+          clearTimeout(id);
+          reject({ _tag: "Interrupted" } satisfies Interrupted);
+        };
+
+        if (signal.aborted) return onAbort();
+        signal.addEventListener("abort", onAbort, { once: true });
+      }),
+    (e) =>
+      typeof e === "object" && e !== null && (e as any)._tag === "Interrupted"
+        ? (e as Interrupted)
+        : ({ _tag: "Interrupted" } as Interrupted)
+  );
+}
+```
+
+---
+
+## Scope: finalizers and closing
+
+### What does `scope.close()` do?
+
+A `Scope` typically:
+
+1) Marks the scope as closed
+2) Interrupts child fibers registered in this scope
+3) Runs finalizers (LIFO order)
+4) Prevents new forks in this scope (depending on your implementation)
+
+### Finalizers are guaranteed
+
+A finalizer runs even when the scope closes due to:
+
+- success
+- failure
+- interruption
+
+This is the foundation of resource safety (ZIO-style):
+
+- acquire
+- use
+- release
+
+---
+
+## Recommended deterministic test
+
+This demonstrates that closing a scope interrupts timers:
+
+```ts
+import { Runtime } from "../core/runtime/runtime";
+import { withScope } from "../core/runtime/scope";
+import type { Exit } from "../core/types/effect";
+
+const runtime = new Runtime({ env: {} });
+
+withScope(runtime, (scope) => {
+  const f = scope.fork(sleep(10_000));
+
+  setTimeout(() => scope.close(), 50);
+
+  f.join((ex: Exit<any, any>) => {
+    console.log("fiber exit:", ex); // -> Failure(Interrupted)
+  });
+});
+```
+
+If the timer does not stop, verify:
+
+- the runtime actually propagates cancellation to `fromPromiseAbortable`
+- combinators are composing cancellation (e.g. `asyncFlatMap` / `asyncFold`)
+
+---
+
+## Common anti-patterns
+
+### ❌ “sleep” implemented only with setTimeout (no cancellation)
+If you don’t clear the timer on interrupt, the fiber can still complete with success after a scope closes.
+
+### ❌ Creating “detached” scopes inside combinators
+Avoid `new Scope(runtime)` inside operators when it breaks the parent/child relationship.
+Prefer `parentScope.subScope()` or a “current scope” inherited by the fiber.
+
+### ❌ Mixing HTTP “Abort” and runtime “Interrupted” without a rule
+At the HTTP layer it’s fine to map interruption to `{ _tag: "Abort" }`, but document that convention.
+
+---
+
+## Implementation checklist
+
+- [ ] `Scope.close()` interrupts child fibers
+- [ ] `Fiber.interrupt()` results in `Exit.Failure(Interrupted)`
+- [ ] `fromPromiseAbortable` is aborted when the fiber is interrupted
+- [ ] combinators (`asyncFlatMap`, `asyncFold`, etc.) compose cancellation
+- [ ] finalizers always run (Success / Failure / Interrupted)

package/docs/coverage.md

@@ -0,0 +1,46 @@
+# Coverage
+
+Coverage is measured with Vitest and the V8 provider.
+
+## Commands
+
+```bash
+npm run test:coverage:report
+```
+
+Builds the text, HTML, JSON, JSON summary, and LCOV reports without enforcing
+thresholds. Open `coverage/index.html` for the browsable report.
+
+```bash
+npm run test:coverage
+```
+
+Runs the same report with the current honest baseline gate. This should pass in
+normal development and should only move upward when new tests improve real
+coverage.
+
+The baseline gate is per executable file: 90% statements, 90% functions, and
+90% lines. Pure re-export barrels and type-only compile checks are excluded
+from the coverage gate because V8 reports them as 0% despite having no runtime
+behavior to exercise.
+
+```bash
+npm run test:coverage:100
+```
+
+Runs the strict target gate: 100% statements, branches, functions, and lines per
+file. This is intentionally separate until the uncovered modules have tests.
+
+## Current Baseline
+
+The current full-report baseline is:
+
+| Metric | Coverage |
+| --- | ---: |
+| Statements | 95.06% |
+| Branches | 86.98% |
+| Functions | 97.31% |
+| Lines | 97.10% |
+
+Do not raise or exclude coverage to make the number look better. Prefer focused
+tests for uncovered behavior, then raise the baseline.