brass-runtime 1.16.0 → 1.17.0

package/docs/performance-profiler.md

@@ -0,0 +1,199 @@
+# Brass Performance Profiler
+
+`brass-runtime/perf` is the built-in profiling surface for runtime and HTTP
+performance work. It is intentionally dependency-free and runs against a local
+Node HTTP server so it can be used in CI, during local optimization, and before
+changing runtime internals.
+
+## Run it
+
+```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
+```
+
+For memory-sensitive runs, expose GC:
+
+```bash
+node --expose-gc --import tsx src/perf/cli.ts --force-gc
+node --expose-gc --import tsx src/perf/cli.ts --profile http-memory --calls 100000 --concurrency 512 --delay-ms 2 --force-gc
+```
+
+Focused examples:
+
+```bash
+npm run perf -- --profile runtime --runtime-iterations 10000
+npm run perf -- --profile runtime-ab --baseline fiber-only --candidate default
+npm run perf -- --profile runtime-soak --rounds 10 --runtime-iterations 100000
+npm run perf -- --profile http --calls 20000 --concurrency 512 --delay-ms 2 --force-gc
+npm run perf -- --profile http --variants default-json,default-json-observed --json
+npm run perf -- --profile http-memory --calls 20000 --concurrency 512 --rounds 2 --force-gc
+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
+```
+
+Environment variables mirror the CLI flags:
+
+- `BRASS_PERF_PROFILE=all|runtime|http`
+- `BRASS_PERF_CALLS`
+- `BRASS_PERF_CONCURRENCY`
+- `BRASS_PERF_DELAY_MS`
+- `BRASS_PERF_WARMUP_CALLS`
+- `BRASS_PERF_VARIANTS`
+- `BRASS_PERF_RUNTIME_ITERATIONS`
+- `BRASS_PERF_RUNTIME_CHAIN_DEPTH`
+- `BRASS_PERF_RUNTIME_VARIANT`
+- `BRASS_PERF_BASELINE`
+- `BRASS_PERF_CANDIDATE`
+- `BRASS_PERF_ROUNDS`
+- `BRASS_PERF_FORCE_GC=true`
+- `BRASS_PERF_JSON=true`
+- `BRASS_PERF_RECORD_HISTORY=true`
+- `BRASS_PERF_HISTORY_DIR`
+- `BRASS_PERF_SAVE_BASELINE`
+- `BRASS_PERF_COMPARE_BASELINE`
+- `BRASS_PERF_FAIL_ON_BASELINE_REGRESSION=true`
+
+## Import it
+
+```ts
+import {
+  comparePerfToBaseline,
+  formatPerformanceReport,
+  loadPerfBaseline,
+  profileHttpLayers,
+  profileRuntimePrimitives,
+  runBrassPerformanceProfile,
+  savePerfBaseline,
+  createPerfHistoryEntry,
+} 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(formatPerformanceReport(report));
+
+const entry = createPerfHistoryEntry("all", report);
+await savePerfBaseline("daily-main", entry);
+const baseline = await loadPerfBaseline("daily-main");
+if (baseline) {
+  console.log(comparePerfToBaseline(entry, baseline));
+}
+```
+
+## What it measures
+
+Runtime profile:
+
+- top-level `asyncSucceed`
+- top-level `asyncFail`
+- top-level `asyncSync`
+- deep `flatMap` chains
+- `FiberRef` update/get chains
+- fibers started per primitive
+- ns/op and operations per second
+
+Runtime A/B profile:
+
+- `fiber-only` baseline for forced fiber execution
+- `default` candidate with native top-level fast path for no-hooks/no-lane
+  `Succeed`, `Fail`, `Sync`, synchronous continuations, `FiberRef` locals, and
+  synchronous/asynchronous callback effects
+- `active-hooks` to measure EventBus overhead
+- `recorder` to measure bounded flight recorder overhead
+- `wide-scheduler` to measure larger single-lane queue settings
+
+Runtime soak profile:
+
+- repeated runtime-only rounds
+- throughput trend from first to last round
+- heap/rss trend across rounds
+- hottest primitive per round
+
+HTTP layer profile:
+
+- `node-http-text`
+- `wire-raw`
+- `default-minimal-json`
+- `default-balanced-no-adaptive-json`
+- `default-balanced-json`
+- `default-json`
+- `default-json-observed`
+
+Each HTTP variant reports throughput, latency percentiles, client/server
+in-flight peaks, queue depth, adaptive limiter state when present, span
+retention when observability is enabled, and memory deltas.
+
+HTTP long-run memory lab:
+
+- defaults to `forceGc: true`, so use `node --expose-gc` for the strongest
+  retained-memory signal
+- compares node transport, wire raw, minimal, balanced without adaptive,
+  balanced, default, and default+observability variants
+- reports heap/rss totals, max p99, mean throughput, errors, and
+  `heapDeltaPer10kRequestsMb`
+- highlights whether memory is `ok`, `watch`, `critical`, or `unknown-gc`
+- compares default+observability against default for heap/10k and throughput
+
+Memory profile:
+
+- before/after snapshots
+- heap/rss/external/array-buffer deltas
+- GC availability
+- optional forced GC via `--force-gc`
+
+## History and baselines
+
+Perf history is local and dependency-free:
+
+- history appends compact JSONL entries to `.brass/perf-history/runs.jsonl`
+- baselines are stored under `.brass/perf-history/baselines/*.json`
+- entries keep normalized metrics rather than full reports by default
+- `--record-history` writes the current run
+- `--save-baseline NAME` stores the current run as a named baseline
+- `--compare-baseline NAME` compares matching metrics by name/tags
+- `--fail-on-baseline-regression` turns a failed baseline comparison into a
+  non-zero CLI exit code
+
+Thresholds are intentionally simple:
+
+- throughput and ops/s are higher-is-better
+- latency, heap/rss, ns/op, and errors are lower-is-better
+- `--baseline-max-regression-percent` defaults to `10`
+- `--baseline-max-heap-regression-percent` defaults to `25`
+- `--baseline-warn-at-ratio` defaults to `0.5`
+
+## Recommendations
+
+`recommendPerformance` turns raw numbers into actionable warnings:
+
+- default client throughput compared to `node:http`
+- observability overhead compared to unobserved default client
+- retained heap per HTTP variant and full profile
+- queueing and adaptive limiter pressure
+- high HTTP p99 latency
+- runtime primitives below local thresholds
+
+These recommendations are heuristics, not release gates. Use the focused
+benchmark budgets for stable regression checks:
+
+```bash
+npm run perf:runtime:budget
+npm run perf:http:memory
+npm run benchmark:runtime:budget
+npm run benchmark:http:budget
+npm run benchmark:observability:budget
+```

package/docs/production-readiness.md

@@ -0,0 +1,73 @@
+# Production Readiness
+
+This checklist is the release gate for using `brass-runtime` in production-like
+services.
+
+## HTTP Defaults
+
+Use `makeDefaultHttpClient` for application clients. The `default` preset enables
+timeout, deduplication, priority scheduling, retry, conservative adaptive
+concurrency, safe-method cache, compression, stats, cache controls, and
+`cancelAll`.
+
+The adaptive limiter is intentionally conservative in presets:
+
+- `minSamples` prevents cold-start latency from changing limits too early.
+- `decreaseThreshold` creates a deadband for normal latency jitter.
+- `maxDecreaseRatio` caps one-step decreases so a noisy sample cannot collapse
+  concurrency.
+- Presets avoid `minLimit: 1`; use that only when a caller explicitly wants a
+  nearly-closed circuit under pressure.
+
+When debugging throughput, compare requested concurrency with
+`serverMaxInFlight`, `adaptiveFinalLimit`, and `adaptiveMaxQueueDepth` before
+assuming a memory leak.
+
+## Validation
+
+Baseline gate:
+
+```bash
+npm run test:types
+npm test
+```
+
+Public package gate:
+
+```bash
+npm run build
+npm run validate:cjs
+```
+
+Benchmark gates:
+
+```bash
+npm run benchmark:observability:budget
+npm run benchmark:http:budget
+npm run benchmark:adaptive
+```
+
+Soak gate:
+
+```bash
+npm run benchmark:http:soak
+npm run benchmark:adaptive:soak
+BRASS_HTTP_BENCH_CALLS=100000 node --expose-gc --import tsx src/benchmarks/runner.ts http-concurrent
+```
+
+Treat sustained positive `heapDeltaMb` after explicit GC as leak evidence. Treat
+RSS-only growth as a signal to investigate, not proof of a leak.
+
+## Operational Notes
+
+- Attach HTTP observability with `middleware: [withHttpObservability(obs)]`.
+- HTTP observability records adaptive limiter gauges when the wrapped client
+  owns a limiter; keep the optional limiter key label disabled unless keys are
+  low-cardinality.
+- Always call `observability.shutdown()` during service shutdown.
+- Call HTTP `shutdown()` as part of graceful shutdown when using default or
+  adaptive-limiter clients so queue/TTL timers and waiters are cleaned up.
+- Keep exporter queues bounded and use `flush()` before process exit.
+- Prefer local benchmark servers over public demo APIs for repeatable numbers.
+- Keep benchmark budgets advisory in developer machines and mandatory in CI once
+  the CI hardware profile is stable.

package/docs/recipes/README.md

@@ -0,0 +1,12 @@
+# Brass Recipes
+
+Copyable happy paths for the first release.
+
+- [Runtime](./runtime.md)
+- [Layers](./layers.md)
+- [HTTP server](./http-server.md)
+- [Testing](./testing.md)
+- [Performance](./performance.md)
+
+These recipes use the public exports a new user should reach for first. Deeper
+guides still live under `docs/guides/`.

package/docs/recipes/http-server.md

@@ -0,0 +1,45 @@
+# HTTP Server Recipe
+
+Use `HttpServer` for the discoverable happy path: define routes, build a
+router, and manage the Node listener as a resource.
+
+```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 routes = [
+  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(),
+];
+
+const router = HttpServer.router(routes, {
+  middleware: [HttpServer.middleware.header("x-powered-by", "brass-runtime")],
+});
+
+await runPromise(
+  useResource(
+    router.listen({ port: 3000 }),
+    (server) => asyncSync(() => {
+      console.log(server.url());
+    }),
+  ),
+);
+```
+
+Validation failures are returned as JSON responses. Handler failures are mapped
+to server error responses by the router, while listener failures use typed
+`NodeHttpServerError` values.

package/docs/recipes/layers.md

@@ -0,0 +1,44 @@
+# Layers Recipe
+
+Use `defineService` for typed service tags, `Layer.effect` or `Layer.value` to
+provide them, and `provideContext` to run a program with a scoped dependency
+graph.
+
+```ts
+import {
+  Layer,
+  LayerContext,
+  asyncSucceed,
+  defineService,
+  provideContext,
+  runPromise,
+} from "brass-runtime";
+
+type Config = { readonly baseUrl: string };
+type Repo = { readonly findUser: (id: string) => string };
+
+const Config = defineService<Config>("Config");
+const Repo = defineService<Repo>("Repo");
+
+const ConfigLayer = Layer.value(Config, { baseUrl: "https://api.example.com" });
+
+const RepoLayer = Layer.effect(Repo, (ctx: LayerContext) => {
+  const config = ctx.unsafeGet(Config);
+  return asyncSucceed({
+    findUser: (id) => `${config.baseUrl}/users/${id}`,
+  });
+});
+
+const AppLayer = Layer.compose(ConfigLayer, RepoLayer);
+
+const userUrl = await runPromise(
+  provideContext(AppLayer, (ctx) =>
+    asyncSucceed(ctx.unsafeGet(Repo).findUser("u1")),
+  ),
+);
+
+console.log(userUrl);
+```
+
+Missing services throw `MissingLayerServiceError`; use `formatLayerError` when
+surfacing the message.

package/docs/recipes/performance.md

@@ -0,0 +1,47 @@
+# Performance Recipe
+
+Use the profiler before and after runtime, HTTP, scheduler, layer, schedule, or
+observability changes.
+
+```bash
+npm run perf -- --profile runtime-ab
+npm run perf -- --profile runtime-soak
+npm run perf:http:memory -- --calls 1000 --concurrency 64 --variants default-json,default-json-observed
+```
+
+Save a local baseline when the machine is stable:
+
+```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
+```
+
+For memory-sensitive HTTP work, expose GC:
+
+```bash
+node --expose-gc --import tsx src/perf/cli.ts --profile http-memory --calls 100000 --concurrency 512 --delay-ms 2 --force-gc
+```
+
+Programmatic API:
+
+```ts
+import {
+  comparePerfToBaseline,
+  createPerfHistoryEntry,
+  loadPerfBaseline,
+  runBrassPerformanceProfile,
+  savePerfBaseline,
+} from "brass-runtime/perf";
+
+const report = await runBrassPerformanceProfile({ http: false });
+const entry = createPerfHistoryEntry("runtime", report);
+await savePerfBaseline("runtime-main", entry);
+
+const baseline = await loadPerfBaseline("runtime-main");
+if (baseline) {
+  console.log(comparePerfToBaseline(entry, baseline));
+}
+```
+
+Treat non-GC heap deltas as allocator churn until a GC-aware run confirms
+retained memory.

package/docs/recipes/runtime.md

@@ -0,0 +1,41 @@
+# Runtime Recipe
+
+Use `runPromise` for the short path and `runExit` when you want the complete
+`Exit`/`Cause` value.
+
+```ts
+import { asyncFlatMap, asyncSucceed, runExit, runPromise } from "brass-runtime";
+
+const program = asyncFlatMap(asyncSucceed(41), (n) => asyncSucceed(n + 1));
+
+const value = await runPromise(program);
+const exit = await runExit(program);
+
+console.log(value); // 42
+console.log(exit);
+```
+
+Use `makeRuntime` when the app owns runtime configuration.
+
+```ts
+import { makeRuntime, asyncSync } from "brass-runtime";
+
+const runtime = makeRuntime({ config: { port: 3000 } }, { inferLane: false });
+
+const port = await runtime.toPromise(
+  asyncSync((env: { config: { port: number } }) => env.config.port),
+);
+```
+
+If you care about typed failures, prefer `runExit` at the boundary and format
+the cause in logs or HTTP responses.
+
+```ts
+import { Cause, asyncFail, runExit } from "brass-runtime";
+
+const exit = await runExit(asyncFail({ _tag: "NotFound", id: "u1" }));
+
+if (exit._tag === "Failure") {
+  console.error(Cause.pretty(exit.cause));
+}
+```

package/docs/recipes/testing.md

@@ -0,0 +1,41 @@
+# Testing Recipe
+
+Use `makeTestRuntime` for deterministic clocks and scheduler control.
+
+```ts
+import { asyncFlatMap, asyncSucceed, sleep, timeout } from "brass-runtime";
+import { makeTestRuntime } from "brass-runtime";
+
+const test = makeTestRuntime();
+
+const program = asyncFlatMap(sleep(1000), () => asyncSucceed("done"));
+
+const result = test.run(program);
+await test.advance(1000);
+
+console.log(await result); // done
+```
+
+Use HTTP testing helpers for client code without touching the network.
+
+```ts
+import {
+  makeJsonHttpResponse,
+  makeMockHttpClient,
+  runHttpEffect,
+} from "brass-runtime/http/testing";
+
+const client = makeMockHttpClient((req) =>
+  makeJsonHttpResponse({ ok: true, url: req.url }),
+);
+
+const response = await runHttpEffect(client({ method: "GET", url: "/health" }));
+console.log(response.status);
+```
+
+For typed failures, assert on `Exit` instead of catching thrown values.
+
+```ts
+const exit = await test.runExit(timeout(asyncSucceed("ok"), 1));
+console.log(exit._tag);
+```

package/docs/release.md

@@ -0,0 +1,53 @@
+# First Release Checklist
+
+This is the release gate for the first public `brass-runtime` release.
+
+## Release command
+
+```bash
+npm run release:check
+```
+
+`release:check` covers:
+
+- TypeScript API/type checks.
+- Full Vitest suite.
+- TS bundle build.
+- CJS compatibility validation.
+- Runtime profiler budget.
+- Runtime benchmark budget.
+- HTTP benchmark budget.
+- Observability benchmark budget.
+
+## Manual release notes
+
+Before publishing:
+
+- Review `README.md` and `docs/recipes/`.
+- Run a GC-aware HTTP memory lab on the release machine:
+
+```bash
+node --expose-gc --import tsx src/perf/cli.ts --profile http-memory --calls 100000 --concurrency 512 --delay-ms 2 --force-gc
+```
+
+- Save a local perf baseline:
+
+```bash
+npm run perf -- --profile runtime-ab --record-history --save-baseline first-release-runtime
+npm run perf -- --profile http-memory --calls 20000 --concurrency 512 --record-history --save-baseline first-release-http-memory
+```
+
+- Confirm `npm pack --dry-run` includes only package files expected by
+  `package.json`.
+
+## First-release scope
+
+- Core runtime, fibers, scopes, `Cause`, interruptibility, `FiberRef`.
+- Layer 2.0 and Schedule 2.0.
+- Streams and pipelines.
+- HTTP client/server, schema validation, lifecycle middleware.
+- Observability and runtime health/readiness.
+- Performance profiler, budgets, history, and baselines.
+- Brass Agent CLI/library surface.
+
+Do not publish `.brass/perf-history`; it is intentionally local evidence.

package/docs/wasm-bounded-queues.md

@@ -0,0 +1,44 @@
+# WASM bounded queues / ring buffers
+
+`brass-runtime` now has an engine-selectable bounded ring buffer abstraction.
+
+The public queue API remains backward compatible:
+
+```ts
+bounded<number>(1024, "backpressure");
+```
+
+You can force the ring storage engine when benchmarking:
+
+```ts
+bounded<number>(1024, "backpressure", { engine: "wasm" });
+bounded<number>(1024, "sliding", { engine: "wasm" });
+bounded<number>(1024, "dropping", { engine: "wasm" });
+```
+
+Or use the lower-level ring buffer factory:
+
+```ts
+import { makeBoundedRingBuffer } from "brass-runtime";
+
+const ring = makeBoundedRingBuffer<number>(1024, 1024, { engine: "wasm" });
+ring.push(1);
+ring.shift();
+```
+
+## Engine semantics
+
+- `engine: "js"`: always uses the TypeScript `RingBuffer`.
+- `engine: "wasm"`: requires `wasm/pkg` to expose `BrassWasmRingBuffer`; throws if the WASM package was not rebuilt.
+- `engine: "auto"`: uses WASM when available, otherwise falls back to the JS ring buffer.
+
+## Performance note
+
+This is intentionally selective. WASM helps most when the queue is hot, bounded, and dominated by ring-buffer state management. If every operation crosses the JS/WASM boundary with large object payloads, JS can still win. Benchmark both modes before making WASM the default in production.
+
+After changing Rust, rebuild the package:
+
+```bash
+npm run build:wasm
+npm run build
+```

package/docs/wasm-engine-observability-benchmarks.md

@@ -0,0 +1,85 @@
+# WASM engine observability and benchmarks
+
+This layer makes `auto` observable instead of implicit.
+
+```ts
+type EngineStats<T> = {
+  engine: "js" | "wasm";
+  data: T;
+  fallbackUsed: boolean;
+};
+```
+
+## Capability detection
+
+```ts
+import { runtimeCapabilities } from "brass-runtime";
+
+console.log(runtimeCapabilities());
+```
+
+Returns:
+
+```ts
+{
+  wasmAvailable: boolean;
+  wasmFiberEngine: boolean;
+  wasmRingBuffer: boolean;
+  wasmScheduler: boolean;
+  wasmFiberRegistry: boolean;
+  wasmStreamChunks: boolean;
+}
+```
+
+## Runtime stats
+
+```ts
+const runtime = Runtime.makeWithEngine({}, "auto");
+console.log(runtime.capabilities());
+console.log(runtime.stats());
+```
+
+`runtime.stats()` now returns `EngineStats<FiberEngineStats>`.
+
+## Scheduler stats
+
+```ts
+const scheduler = new Scheduler({ engine: "auto" });
+console.log(scheduler.stats());
+```
+
+`fallbackUsed: true` means `auto` selected JS because the corresponding WASM capability was not available.
+
+## Ring buffer stats
+
+```ts
+const q = makeBoundedRingBuffer<number>(1024, 1024, { engine: "auto" });
+q.push(1);
+q.shift();
+console.log(q.stats());
+```
+
+## Stream chunk stats
+
+```ts
+const chunker = makeStreamChunker<number>(256, { engine: "auto" });
+console.log(chunker.stats());
+```
+
+## Benchmarks
+
+Run:
+
+```bash
+npm run build:wasm
+npm run benchmark wasm-engines
+```
+
+JSON output:
+
+```bash
+npm run build:wasm
+npm run benchmark:json wasm-engines
+```
+
+The benchmark report includes the runtime capability snapshot, so results can be compared against whether WASM was actually available.