brass-runtime 1.16.0 → 1.17.0

package/CHANGELOG.md

@@ -0,0 +1,17 @@
+# Changelog
+
+## 1.14.0 - First Public Release Candidate
+
+- Added mature core runtime features: structured concurrency, `Cause`,
+  interruptibility, `FiberRef`, Layer 2.0, Schedule 2.0, TestRuntime, streams,
+  and runtime observability.
+- Added HTTP client/server surface with schema validation, lifecycle
+  middleware, adaptive limiter, retry, compression, health/readiness, and
+  observability hooks.
+- Added `brass-runtime/perf` with runtime A/B, soak profiling, HTTP memory lab,
+  benchmark budgets, and local perf history/baseline storage.
+- Added DX helpers: `runPromise`, `runExit`, `makeRuntime`, `defineService`,
+  `getService`, `provide`, `formatLayerError`, `formatConfigError`, and
+  `HttpServer`.
+- Added first-release recipes under `docs/recipes/` and release validation via
+  `npm run release:check`.

package/README.md

@@ -1,6 +1,7 @@
 # brass-runtime
 
-A ZIO-inspired effect runtime for TypeScript with structured concurrency, pull-based streams, and a production-grade HTTP client.
+A ZIO-inspired effect runtime for TypeScript with structured concurrency,
+runtime diagnostics, pull-based streams, and a production-grade HTTP client.
 
 Built without `Promise`/`async`/`await` as the primary semantic primitive. Effects are values — lazy, composable, and cancelable by default.
 
@@ -12,19 +13,27 @@ npm i brass-runtime
 
 ## What it does
 
-**Core runtime** — algebraic effects, fibers, scopes, scheduler, layers, semaphores, circuit breakers, metrics, tracing.
+**Runtime** — algebraic effects, fibers, scopes, scheduler, interruptibility
+regions, fiber-local refs, typed layers, semaphores, circuit breakers, rich
+`Cause<E>` failures, metrics, tracing, and an opt-in flight recorder.
 
-**Streams** — pull-based with backpressure, bounded buffers, queues, hubs, pipelines, fusion optimization.
+**Streams** — pull-based streams with backpressure, bounded buffers, hubs,
+pipelines, fusion optimization, and a small fluent DX facade.
 
-**HTTP client** — lazy/cancelable requests with a full middleware pipeline: adaptive concurrency, compression, batching, connection pre-warming, caching, deduplication, priority scheduling, and retry with backoff.
+**HTTP** — lazy/cancelable client and server primitives with typed routing,
+schema validation, health/readiness probes, adaptive concurrency, compression,
+batching, prewarm, cache, dedup, priority, retry, and observability.
 
-**Schema validation** — dependency-free runtime schemas for JSON, config, and protocol boundaries, with typed inference and path-rich validation issues.
+**Production signals** — dependency-free schemas, Prometheus/OTLP exporters,
+structured logs, W3C trace propagation, sampling, redaction, bounded exporters,
+and explicit flush/shutdown.
 
-**Observability export** — Prometheus metrics, OTLP metrics/traces/logs, structured logging, W3C trace-context propagation, request adapters, sampling, redaction, bounded exporters, and production flush/shutdown controls.
+**Performance profiler** — runtime primitives, HTTP layer comparison, memory
+retention reports, observability overhead, CLI/JSON output, and actionable
+recommendations.
 
-**WASM engine** — optional Rust/WASM-backed state machines for strict scheduling and bounded queues.
-
-**Brass Agent** — experimental CLI coding agent with workspace inspection, LLM integration, and VS Code extension.
+**Optional engine and tools** — Rust/WASM-backed state machines plus the
+experimental Brass Agent CLI/VS Code workflow.
 
 ---
 
@@ -43,12 +52,86 @@ npm i brass-runtime
 ### Run an effect
 
 ```ts
-import { Runtime, succeed } from "brass-runtime";
+import { runPromise, succeed } from "brass-runtime";
+
+const value = await runPromise(succeed(42));
+```
+
+Use `makeRuntime` when you want explicit runtime options, and `runExit` when
+you want the full `Exit`/`Cause` instead of a rejected promise.
+
+### Inspect failure causes
+
+```ts
+import { Cause, formatCause } from "brass-runtime";
+
+const cause = Cause.then(
+  Cause.fail("database unavailable"),
+  Cause.both(Cause.interrupt(), Cause.die(new Error("release failed"))),
+);
+
+console.log(formatCause(cause));
+```
+
+`Cause<E>` preserves typed failures, defects, interruptions, and sequential or
+parallel composition (`Then` / `Both`) so diagnostics can explain what happened
+without flattening every failure into a single thrown value.
+
+### Mask interruption
+
+```ts
+import { async, flatMap, succeed, uninterruptibleMask } from "brass-runtime";
+
+const effect = uninterruptibleMask((restore) =>
+  flatMap(succeed("acquired"), (resource) =>
+    restore(async((_env, cb) => {
+      setTimeout(() => cb({ _tag: "Success", value: `used:${resource}` }), 10);
+    })),
+  ),
+);
+```
+
+Use `uninterruptible(effect)` for critical regions and
+`uninterruptibleMask((restore) => ...)` when only part of the region should be
+interruptible again. Pending interruption is deferred until the protected region
+exits; restored sub-effects remain cancelable.
+
+### Fiber-local context
+
+```ts
+import { Runtime, makeFiberRef } from "brass-runtime";
 
+const requestId = makeFiberRef("anonymous");
 const runtime = Runtime.make({});
-const value = await runtime.toPromise(succeed(42));
+
+const result = await runtime.toPromise(
+  requestId.locally("req-123", requestId.get()),
+);
+```
+
+`FiberRef` values are local to the running fiber, inherited by child fibers at
+fork time, isolated from child mutations, and restored after `locally` regions
+even when the region fails or is interrupted.
+
+### Explain runtime behavior
+
+```ts
+import { Runtime, async, makeRuntimeRecorder } from "brass-runtime";
+
+const recorder = makeRuntimeRecorder({ maxEvents: 5000 });
+const runtime = new Runtime({ env: {}, hooks: recorder.hooks });
+
+await runtime.toPromise(async((_env, cb) => {
+  setTimeout(() => cb({ _tag: "Success", value: "ok" }), 10);
+}));
+
+console.log(recorder.explain());
 ```
 
+The flight recorder is opt-in and keeps a bounded ring buffer of runtime events:
+fiber start/end/suspend/resume, scopes, supervisor events, logs, spans, and
+trace context when available.
+
 ### Recommended HTTP client
 
 ```ts
@@ -75,8 +158,10 @@ console.log(http.compression?.stats());
 `makeDefaultHttpClient` is the batteries-included entrypoint: timeout,
 deduplication, priority scheduling, retry, adaptive concurrency, safe-method
 response cache, decompression, stats, `cancelAll`, and JSON/text helpers. Use
+`preset: "production"` when you want that production-ready shape explicitly,
 `preset: "balanced"` to skip the default cache, or `preset: "minimal"` for a
-cheap wire client with the same helper API.
+cheap wire client with the same helper API. `preset: "default"` remains the
+same full preset for compatibility.
 
 The HTTP stack is meant to replace the usual `fetch` wrapper plus Zod/Valibot
 glue: schemas are dependency-free, responses and request bodies are validated in
@@ -84,6 +169,70 @@ the same effect, config validation fails at construction time, and the client
 still owns cancellation, retries, compression, observability, and adaptive
 limits as one pipeline.
 
+Custom Promise clients such as Axios can be injected without making the
+consumer manage `AbortSignal` or `Async` plumbing:
+
+```ts
+import {
+  defineHttpPolicyPresets,
+  formatHttpError,
+  isRetryableHttpError,
+  makeDefaultHttpClient,
+  promiseHttpTransport,
+} from "brass-runtime/http";
+
+const transport = promiseHttpTransport()
+  .requestConfig(({ request, url }) => ({
+    url: url.toString(),
+    method: request.method,
+    headers: request.headers,
+    data: request.body,
+    responseType: "json",
+  }))
+  .send((config) => axiosInstance.request(config))
+  .json();
+
+const axiosHttp = makeDefaultHttpClient({
+  baseUrl: "https://api.example.com",
+  transport,
+});
+
+try {
+  await axiosHttp.getJson("/users/1").unsafeRunPromise();
+} catch (error) {
+  if (isRetryableHttpError(error)) {
+    console.warn("transient upstream failure");
+  }
+  console.error(formatHttpError(error));
+}
+```
+
+Brass injects the runtime `AbortSignal` into object configs before `send` and
+normalizes external failures with `toHttpError`, including Axios-like
+`response.status`, aborts, and common timeout codes.
+
+Repeated execution intent can be named once with policy presets:
+
+```ts
+const policies = defineHttpPolicyPresets({
+  readModel: {
+    lane: "read-model",
+    poolKey: "users-api",
+    priority: 2,
+    retry: { maxRetries: 2, baseDelayMs: 50 },
+  },
+});
+
+const http = makeDefaultHttpClient({
+  baseUrl: "https://api.example.com",
+  policyPresets: policies,
+});
+
+await http.getJson("/users/1", {
+  policy: { preset: "readModel", dedupKey: "users:1" },
+}).unsafeRunPromise();
+```
+
 The default adaptive limiter uses the `aggressive` preset: warmup sample floor,
 P5 baseline, error-rate signal, priority-aware queueing, jittered probes,
 proportional headroom, capped decreases, and TTL-evicted per-key state.
@@ -122,6 +271,45 @@ The same validation machinery checks runtime, HTTP, and observability configs
 at construction time, so invalid values fail with field paths like
 `$.otlp.pipeline.batchSize` instead of surfacing later as ambiguous behavior.
 
+### HTTP server
+
+```ts
+import { asyncSucceed, asyncSync, runPromise, useResource } from "brass-runtime";
+import { HttpServer, s } from "brass-runtime/http";
+
+const User = s.object({
+  id: s.nonEmptyString(),
+  name: s.nonEmptyString(),
+});
+
+const router = HttpServer.router([
+  HttpServer.route("GET", "/users/:id", {
+    params: s.object({ id: s.nonEmptyString() }),
+    response: User,
+  }, (ctx) =>
+    asyncSucceed(HttpServer.json({
+      id: ctx.params.id,
+      name: "Ada",
+    })),
+  ),
+  HttpServer.healthRoute(),
+  HttpServer.readinessRoute(),
+]);
+
+await runPromise(
+  useResource(
+    router.listen({ port: 3000 }),
+    (server) => asyncSync(() => {
+      console.log(server.url());
+    }),
+  ),
+);
+```
+
+Routes infer `:params` from the path, optional schemas validate
+params/query/body/response, middleware is effect-based, and the Node listener is
+available as a managed resource for graceful shutdown.
+
 ### Discoverable HTTP builder
 
 ```ts
@@ -131,7 +319,7 @@ declare const token: string;
 
 const http = httpClientBuilder()
   .baseUrl("https://api.example.com")
-  .balanced()
+  .production()
   .balancedLimiter({ maxLimit: 128 })
   .header("authorization", `Bearer ${token}`)
   .cache({ ttlSeconds: 30, maxEntries: 512 })
@@ -232,6 +420,7 @@ const client = baseClient.with(middleware);
 import { Runtime, asyncSucceed } from "brass-runtime/core";
 import {
   makeObservability,
+  makeOtlpOptions,
   runObservedHttpServerEffect,
   withHttpObservability,
 } from "brass-runtime/observability";
@@ -243,11 +432,7 @@ const obs = makeObservability({
   sampling: { ratio: 0.25, respectRemoteSampled: true, forceSampleOnError: true },
   redaction: {},
   cardinality: { maxValuesPerLabel: 100 },
-  otlp: {
-    metricsUrl: "http://collector:4318/v1/metrics",
-    tracesUrl: "http://collector:4318/v1/traces",
-    logsUrl: "http://collector:4318/v1/logs",
-  },
+  otlp: makeOtlpOptions({ endpoint: "http://collector:4318" }),
   flushIntervalMs: 10_000,
 });
 
@@ -270,6 +455,62 @@ HTTP client observability automatically reads adaptive limiter diagnostics when
 the wrapped client owns a limiter, exposing gauges for current limit, queue
 depth, utilization, error rate, request/completion rate, rejection rate, and
 state count.
+It also reads `req.policy` automatically: logs and span attributes include
+`preset`, `lane`, `poolKey`, `dedupKey`, `priority`, and retry overrides when present.
+Metric labels stay conservative by default; opt into stable labels with
+`withHttpObservability({ policy: { labelKeys: ["preset", "lane", "poolKey"] } })`.
+
+### Performance profiler
+
+```bash
+npm run perf
+npm run perf:json
+npm run benchmark:perf
+npm run perf:runtime:ab
+npm run perf:runtime:soak
+npm run perf:runtime:budget
+npm run perf:http:memory
+npm run perf:history
+```
+
+```ts
+import { runBrassPerformanceProfile } from "brass-runtime/perf";
+
+const report = await runBrassPerformanceProfile({
+  http: {
+    calls: 20_000,
+    concurrency: 512,
+    delayMs: 2,
+    forceGc: true,
+    variants: ["default-json", "default-json-observed"],
+  },
+});
+
+console.log(report.recommendations);
+```
+
+The profiler compares runtime primitives, runtime A/B variants, runtime-only
+soak behavior, `node:http`, Brass wire/default HTTP clients, HTTP long-run
+memory, observability overhead, history/baseline regressions, and memory deltas. Use
+[`docs/performance-profiler.md`](docs/performance-profiler.md) for focused
+commands and `node --expose-gc` runs.
+
+Perf runs can be persisted and compared locally:
+
+```bash
+npm run perf -- --profile runtime-ab --record-history --save-baseline runtime-main
+npm run perf -- --profile runtime-ab --compare-baseline runtime-main --fail-on-baseline-regression
+```
+
+### First-release recipes
+
+Copyable happy paths live in [`docs/recipes`](docs/recipes/README.md):
+
+- runtime execution
+- typed layers
+- HTTP server
+- testing
+- performance baselines
 
 ### Structured concurrency
 
@@ -289,12 +530,13 @@ await runtime.toPromise(
 ### Streams
 
 ```ts
-import { Runtime, collectStream, fromArray, mapP, via } from "brass-runtime";
+import { Runtime, Stream } from "brass-runtime";
 
 const runtime = Runtime.make({});
-const numbers = fromArray([1, 2, 3, 4, 5]);
-const doubled = via(numbers, mapP((n: number) => n * 2));
-const result = await runtime.toPromise(collectStream(doubled));
+const result = await Stream
+  .from([1, 2, 3, 4, 5])
+  .map((n) => n * 2)
+  .collect(runtime);
 // [2, 4, 6, 8, 10]
 ```
 
@@ -310,6 +552,7 @@ const result = await runtime.toPromise(collectStream(doubled));
 | `brass-runtime/http/testing` | Dependency-free mock clients, mock fetch, response factories, and effect runner helpers |
 | `brass-runtime/schema` | Dependency-free runtime schema DSL with type inference |
 | `brass-runtime/observability` | Prometheus/OTLP exporters, logs, spans, trace propagation, request adapters |
+| `brass-runtime/perf` | Runtime, HTTP, observability, memory, and baseline performance profiler |
 | `brass-runtime/agent` | Brass Agent core (experimental) |
 
 CLI: `brass-agent`
@@ -346,6 +589,8 @@ All layers emit lifecycle events, track stats, and support cancellation.
 The recommended `makeDefaultHttpClient` factory wires the default preset
 for you and accepts extra middleware, so observability can be attached with
 `middleware: [withHttpObservability(obs)]` without coupling HTTP to exporters.
+Per-request `policy` travels through that stack and is visible to observability
+without being forwarded to the host transport.
 
 ---
 
@@ -388,7 +633,14 @@ Docs: [Install](./docs/agent-install-and-configure.md) · [CLI](./docs/agent-cli
 npm test              # vitest suite
 npm run test:types    # TypeScript type checking
 npm run test:coverage # coverage with baseline gate
+npm run release:check # full release gate: types, tests, build, CJS, perf budgets
 npm run benchmark     # runtime, HTTP lifecycle, and 100k local HTTP concurrency
+npm run benchmark:runtime        # Runtime Performance Track
+npm run benchmark:runtime:budget # Runtime Performance Track regression budget
+npm run perf:runtime:ab          # Runtime A/B Performance Lab
+npm run perf:runtime:soak        # Runtime-only soak profile
+npm run perf:runtime:budget      # Runtime profiler budget
+npm run perf:http:memory         # HTTP long-run memory lab
 npm run benchmark -- http-concurrent # HTTP compare mode variants
 node --expose-gc --import tsx src/benchmarks/runner.ts http-concurrent # HTTP memory/limiter diagnostics
 npm run benchmark:adaptive
@@ -411,6 +663,8 @@ Property-based tests use `fast-check` with 100+ iterations per property. Each HT
 - [Cancellation & Interruption](./docs/cancellation.md)
 - [Observability: Hooks & Tracing](./docs/observability.md)
 - [Observability framework examples](./docs/observability-framework-examples.md)
+- [Framework integrations](./docs/framework-integrations.md)
+- [NestJS integration](./docs/frameworks/nestjs.md)
 - [Observability collector smoke](./docs/observability-collector-smoke.md)
 - [HTTP module](./docs/http.md)
 - [Production readiness](./docs/production-readiness.md)
@@ -426,10 +680,16 @@ Property-based tests use `fast-check` with 100+ iterations per property. Each HT
 
 - [x] Sync effect values via `ZIO<R, E, A>` aliases
 - [x] Algebraic async: `Async<R, E, A>`
+- [x] Rich `Cause<E>` failure trees with pretty printing
+- [x] Interruptibility regions with `uninterruptible` / `uninterruptibleMask`
+- [x] Fiber-local refs with fork inheritance and scoped restoration
+- [x] TS TestRuntime with deterministic scheduler and virtual clock
+- [x] Schedule 2.0 with drivers, runtime-clock budgets, observability, and HTTP integration
 - [x] Cooperative scheduler (observable, testable)
 - [x] Fibers with interruption & finalizers
 - [x] Structured scopes & resource safety
-- [x] Layers, semaphores, circuit breakers
+- [x] Runtime flight recorder for bounded execution traces
+- [x] Layer 2.0 typed contexts, semaphores, circuit breakers
 - [x] Metrics, tracing, runtime hooks
 - [x] Worker pools
 - [x] WASM engine (optional)
@@ -437,6 +697,7 @@ Property-based tests use `fast-check` with 100+ iterations per property. Each HT
 ### Streams
 
 - [x] Pull-based streams with backpressure
+- [x] Fluent `Stream` / `Pipeline` DX facade
 - [x] Bounded buffers, queues, hubs
 - [x] Pipelines with fusion optimization
 - [x] Stream merge, zip, broadcast
@@ -445,6 +706,9 @@ Property-based tests use `fast-check` with 100+ iterations per property. Each HT
 ### HTTP
 
 - [x] Lazy, cancelable HTTP client
+- [x] Effect-based Node HTTP server listener with resource lifecycle
+- [x] Declarative typed routing with params/query/body/response schemas
+- [x] Health/readiness routes backed by runtime health reports
 - [x] Schema-validated JSON helpers
 - [x] Discoverable builder API
 - [x] Test helper subpath