castrum 0.9.0 → 0.9.2

package/docs/BENCHMARKS.md

@@ -29,55 +29,14 @@ The benchmark system compares the Rust implementations against pure JavaScript/B
 bun bench.ts
 ```
 
-### Performance-proven surface & auto-annotated JSDoc
-
-The CPU benchmark persists a machine-readable report to `bench/results/cpu/latest.json`
-(+ timestamped snapshots). Three commands consume it; `bun run check:docs` runs all
-three as the one-stop "informed decision" pipeline:
-
-| Command | What it does |
-|---------|--------------|
-| `bun run check` | Runs the CPU benchmark and writes `bench/results/cpu/latest.json` (report-only — **never mutates source**). |
-| `bun run check:annotate` | Rewrites the `@performance` / `@deprecated` / `@remarks` JSDoc on the public `rust.*` declarations (`src/rust-ffi/scalar/interface.ts`, `batch.ts`, `client.ts`) from the report. Idempotent — generated lines carry the `[check:annotate]` marker; hand-written JSDoc is preserved. `--dry-run` previews changes. |
-| `bun run check:proven` | Audits the `PROVEN_SURFACE` registry against the report and flags `REGRESSION`, `PARITY-DRIFT`, and `PROMOTABLE`. `--fail` exits 1 on regressions. |
-| `bun run check:docs` | `check` + `check:annotate` + `check:proven` — the full pipeline. |
-
-**Automatic annotation (opt-in):** `CASTRUM_BENCH_ANNOTATE=1 bun run check`
-auto-runs the annotator right after the benchmark, so the JSDoc always reflects
-the latest run. It is opt-in because it mutates tracked source files.
-
-**How the annotations work (data-driven):**
-
-- Each function's **score** is embedded in the `@performance` line, e.g.
-  `JSON valid: ~3.2x faster than the JS baseline (8/8 tasks won)` or
-  `CRC32: ~4.1x slower than the JS baseline (2/3 tasks failed)`. A function's
-  benchmark set is the canonical comparison plus all its `_`-suffixed variants
-  (`_large`, `_batch`, `_concurrent_*`, `_stress`, pooled `_into` overloads)
-  that no other registry entry claims.
-- Task bands (see `src/shared/bench-classify.ts`): **won** = `ratio >= 1`
-  (Rust at least as fast), **failed** = `ratio < 1 / 1.35` (clear loss), the
-  middle is a **tie** that counts toward neither.
-- `@deprecated` is **hybrid**:
-  - A clear **majority** of a function's benchmarks failing in the latest run
-    auto-deprecates it even when the static registry says `proven`/`parity` — a
-    `@remarks Auto-deprecated: N/M benchmarks failed ...` note records the drift.
-  - A single good run **never** removes an existing `@deprecated` (static
-    classifications reflect the shipped release build, not one local run). A
-    majority win on a static `not-competitive` function only adds a
-    `@remarks Promotion candidate ...` note.
-- Classifications are **build-dependent** (debug/SIMD builds distort ratios). The
-  annotator warns when the report carries no `buildFlavor`; confirm on a release
-  build (`bun run build`) or local perf build (`bun run build:perf`).
-
 ### Bun built-ins diagnostic set ("don't reinvent the wheel")
 
 `bun run check` also races castrum ops against **Bun's native built-ins**
 (`Bun.hash`, `Bun.password`, `Bun.CryptoHasher`, `Bun.gzipSync`,
 `Bun.randomUUIDv7`) as a diagnostic set:
 
-- Task names use the **`diag:`** prefix (not `native:`/`rust:`) so
-  `check-proven`'s aggregation (which matches `PROVEN_SURFACE` rustTask names
-  and their `_`-suffixed variants) never picks them up — they are informational.
+- Task names use the **`diag:`** prefix (not `native:`/`rust:`) so they stay out
+  of the shipped-op `native:`/`rust:` comparisons — they are informational.
 - Sources: `src/baseline/tasks/bun-builtins.ts` (Bun-only baselines, guarded
   with `typeof Bun` so the module still loads under Node),
   `src/bench/tasks/bun-builtins.ts`, comparisons in `src/bench/comparisons.ts`.
@@ -112,8 +71,115 @@ bun run bench:http:bun-only  # Run only raw Bun vs baseline
 
 # Run all heavy scenarios
 bun run bench:http:all-heavy
+
+# Max-throughput cross-check (autocannon — no Bun fetch cap)
+bun run bench:http:ac          # all servers, 03-stress weighted mix
+bun run bench:http:stress:ac   # 03-stress mix only
+
+# Single-path static comparison (fastest, most stable signal — SERVER-BOUND
+# by default with AC_CONNECTIONS=2000; use this for ceiling comparisons):
+#   AC_PATH=/api/users AC_RUNS=3 node bench/autocannon-stress.mjs
+#   AC_PATH=/api/users AC_METHOD=POST AC_BODY='{"id":1,"name":"x"}' \
+#     AC_CONTENT_TYPE=application/json AC_RUNS=3 \
+#     node bench/autocannon-stress.mjs
+#   # median-of-N (see §Single-core): run-major interleaving — every server is
+#   # measured once per round, so the median compares servers over the same
+#   # load windows on a noisy host.
+#
+# The DYNAMIC 03-stress mix (default, no AC_PATH) is CLIENT-bound (~47k here —
+# autocannon's setupRequest generation is the cap, identical across servers);
+# use it only for shape/behavior validation, not ceiling comparisons.
+#
+# Multi-core scaling (SO_REUSEPORT — the way to exceed the single-core ceiling):
+#   AC_INSTANCES=4 node bench/autocannon-stress.mjs
+#   (ingress/router only — they read INGRESS_REUSE_PORT=1)
 ```
 
+### Bun `fetch()` concurrency cap (read this before interpreting HTTP results)
+
+Bun's `fetch()` limits the number of **simultaneous** requests to **256 by
+default** (`BUN_CONFIG_MAX_HTTP_REQUESTS`, max 65,336). When a scenario's
+`maxConcurrent` exceeds that cap, the excess requests queue **FIFO client-side**
+and the run measures the *generator*, not the server — the classic signature is
+a sub-ms `p50` with a multi-second tail and a flat RPS wall across every server.
+
+- All `bench:http:*` scripts set `BUN_CONFIG_MAX_HTTP_REQUESTS=65535` for you.
+- `bench/http/run-bench.ts` warns if a selected scenario exceeds the effective cap.
+- For **max-throughput** server comparisons use **autocannon**
+  (`bench/autocannon-stress.mjs`, run with `node`): it has no such cap, uses a
+  real socket pool, scales across worker threads, and reports RPS + latency
+  percentiles natively. It replicates the `03-stress` weighted flow mix
+  (50% GET /api/users?q=…&page=…, 30% POST /api/users, 20% GET /health).
+- **Two autocannon gotchas** (both fixed in the runner):
+  1. `requestGenerator` is CLI-ONLY — the library silently ignores it (every
+     request then goes to `GET /` → 404 → "0 2xx"). The runner uses the
+     library's `requests: [{ setupRequest }]` API instead.
+  2. `result.workers` is a count (`opts.workers`), not an array — the report no
+     longer treats it as a per-worker array.
+
+### Single-core ceiling & multi-core scaling (measured 2026-08-21)
+
+All four servers are **single-process `Bun.serve`** (one event loop), so they
+pin at a per-core ceiling on this machine. The host is load-noisy, so use the
+**median-of-N** runner (`AC_RUNS=N`, default 1) with **run-major interleaving** —
+every server is visited once per round, so a single slow window affects all
+servers' run-`i` equally and the median compares servers over the same load
+windows (the old server-major order biased later servers into noisier windows).
+
+> **Methodology (2026-08-21 — replaces the 2026-08-16 snapshot).** Two
+> measurement traps were identified and the numbers below use the config that
+> avoids both:
+>
+> 1. **The dynamic `setupRequest` mix is CLIENT-bound, not server-bound.** The
+>    03-stress weighted mix caps every server at ~47k RPS on this host because
+>    autocannon's per-request `setupRequest` (random string generation + JSON
+>    stringify) is the bottleneck — all four servers report the identical
+>    ~47k. **Use static-path runs** (`AC_PATH=…`, `AC_METHOD=…`, `AC_BODY=…`)
+>    for ceiling comparisons; the mix only validates shape/behavior.
+> 2. **`AC_PIPELINING>1` is a client/transport artifact under GET here.**
+>    With pipelining 10, even raw Bun collapses to ~8.6k on `GET /health`
+>    (autocannon pipelining + Bun's HTTP/1.1 handling), while the same server
+>    does 52k at pipelining 1 — so pipelining does NOT expose the ceiling on
+>    this stack. The server-bound config is **`AC_PIPELINING=1` + enough
+>    connections** (≥2000 on this host) to drive the event loop.
+>
+> The server-bound snapshot below is **static-path, `AC_CONNECTIONS=2000`,
+> `AC_PIPELINING=1`, `AC_RUNS=3`** (median-of-3), single instance.
+
+Current medians (static path, 2000 connections, pipelining 1, single instance):
+
+- `GET /api/users?q=testquery&page=1` (query + cookies + CORS + metadata
+  envelope): **bun 52.5k, elysia 52.4k, ingress 95.9k, router 95.8k RPS** —
+  ingress/router ~**+83% vs bun**, with a tighter tail (router p99.9 195ms vs
+  bun 800ms).
+- `POST /api/users` (JSON body, fast-path schema validation):
+  **bun 49.5k, elysia 49.5k, ingress 95.8k, router 93.5k RPS** — ~**+89–94%
+  vs bun**. The pre-optimization ingress POST gap (≈ −24% vs bun, 2026-08-16)
+  is long closed; the current gap is a large WIN (JS hot-path elimination +
+  single-pass body validation + copy-mode response default).
+- **Response mode matters more than any remaining pipeline cost**: copy mode
+  (default) vs zero-copy on `POST /api/users`: **66.4k vs 45.1k RPS (+47%)** —
+  per-request `ReadableStream` construction is the cost, not the native body
+  write. Both servers default to copy mode; `INGRESS_ZERO_COPY=1` opts back in
+  for large-payload deployments.
+- Per-request cost breakdown (`bun bench/cost/router-cost.ts` +
+  `router-minimal-breakdown.ts`, min-of-5): the router's minimal route `run()`
+  is ~310ns (native pruned pipeline ~115ns + response/run machinery ~150ns +
+  refresh 25ns + rid 12ns + header gather 4ns). A `syncResponder` experiment
+  that threaded a known-sync hint through `run()` was REVERTED as **slower**
+  (−6 to −94ns across 3 runs) — the per-request `assertSyncCallback` +
+  `instanceof Response` checks are already JIT-inlined and free on JSC; the
+  extra param/branch deoptimized the shared hot function. Conclusion: the
+  `run()` machinery is NOT real overhead.
+- **To exceed the single-core ceiling**, run multiple server processes on the
+  same port via SO_REUSEPORT: `AC_INSTANCES=N` (ingress/router only — they read
+  `INGRESS_REUSE_PORT=1`; bun/elysia do not set it). On this noisy host the
+  scaling signal is unreliable (4 instances: 52.8k median with one run at
+  91.9k; 8 instances: 48.5k — the load-noise band swallows the gain), so for
+  clean multi-core numbers run autocannon on a separate host. The mechanism
+  (N event loops sharing the accept queue) is the documented way to exceed the
+  single-process ceiling.
+
 ---
 
 ## HTTP Benchmark Scenarios
@@ -134,7 +200,9 @@ Each scenario targets a specific performance aspect:
 ### 03-stress
 - **Goal**: Ramp to maximum throughput
 - **Duration**: ~100 seconds (5 × 20s ramp phases)
-- **Concurrency**: up to 10,000
+- **Concurrency**: up to 2,000 (higher on a single machine only deepens the
+  client-side fetch queue — the generator can't drive 10k usefully; see the
+  Bun fetch-cap note above. For true max-throughput use `bench:http:ac`.)
 
 ### 04-spike
 - **Goal**: Burst resilience (baseline → spike → recovery)
@@ -235,7 +303,7 @@ When comparing multiple frameworks, differences are expressed as:
 
 ```
 bench.ts
-  └─ Loads benchmark tasks from src/bench/tasks/ (30 tasks)
+  └─ Loads benchmark tasks from src/bench/tasks/ (34 tasks)
        ├── hashing.ts       Compare Rust fnv1a64 vs JS TextEncoder + hash
        ├── validation.ts    Compare Rust validation vs validator library
        ├── json.ts          Compare Rust sonic-rs vs JSON.parse
@@ -258,19 +326,19 @@ Each task runs:
 | Env / flag | Effect |
 |------------|--------|
 | `CASTRUM_BENCH_BATCH_SIZE` | Batch size for sub-µs operations (default `64`). Batching amortizes the timer/measurement overhead for very fast ops. |
-| `CASTRUM_BENCH_ANNOTATE=1` | After `bun run check`, auto-rewrite the `rust.*` JSDoc annotations from the fresh report (see "Performance-proven surface & auto-annotated JSDoc"). |
-| `HTTP_NO_SHAPE=1` | The HTTP load generator (`bench/load.ts`) skips response-shape `JSON.parse` for pure-throughput runs. |
+| `HTTP_NO_SHAPE=1` | The HTTP load generator (`bench/http/load.ts`) skips response-shape `JSON.parse` for pure-throughput runs. |
 
 ---
 
 ## HTTP Server Architecture
 
 ```
-bench/servers/
+bench/http/servers/
 ├── bun-server.ts       # Raw Bun.serve with manual routing
 ├── elysia-server.ts    # Elysia framework
 ├── ingress-server.ts   # Ingress (this project) optimized handler
-└── shared.ts           # Shared route handlers
+├── router-server.ts    # Ingress per-route compiled-router variant (createIngressRouter)
+└── shared.ts           # Shared route handlers, PORTS, env helpers
 ```
 
 Each server implements the same routes for fair comparison:

package/docs/CASE_STUDY.md

@@ -0,0 +1,243 @@
+# Case study — building a Rust-accelerated HTTP pipeline for Bun
+
+**castrum** is a hybrid TypeScript + Rust package that gives Bun servers native
+speed for the work that actually costs CPU — request validation, parsing,
+hashing, crypto, and a full HTTP ingress pipeline — behind a small, flat API.
+This document tells the story of how it was built and measured, what the
+benchmarks actually showed, and the lessons that generalise to any
+"should I write this in Rust?" decision.
+
+All figures below come from the reports in `bench/results/` (generated on a
+release addon, baseline CPU, Bun 1.4.0). They're **representative**, not
+advertised as universal — re-run `bun run check` / `bun run bench:http` on your
+own hardware before trusting them for your numbers.
+
+---
+
+## 1. Background: the problem
+
+Bun is already very fast. The gap that motivated castrum was not "Bun is slow"
+but three specific frictions:
+
+1. **CPU-bound request work runs in JavaScript.** JSON validity checking, email
+   / UUID / IP validation, query & cookie parsing, hashing, and schema
+   validation are pure CPU. In JS they compete with the event loop; the moment
+   a request needs several of them, tail latency climbs.
+2. **Production HTTP servers need a lot of "plumbing" middleware.** CORS,
+   rate limiting, body-size guards, schema validation, security headers,
+   request IDs, metrics. Hand-wiring these into `Bun.serve` is repetitive and
+   error-prone; pulling in a framework drags in a dependency graph.
+3. **Bun and Node want different integration stories.** The same logic should
+   run on Bun (the primary target, zero startup cost) and Node ≥ 20.3 (a
+   compiled ESM entry) without two implementations.
+
+The hypothesis: a **hybrid** design — ergonomic TypeScript on top of one Rust
+cdylib — could remove the CPU cost from the event loop, package the middleware
+as a pre-baked pipeline, and still be usable from both runtimes.
+
+---
+
+## 2. The approach
+
+### 2.1 One cdylib, two transports
+
+The addon is built with napi-rs (so Node can load it), but it *also* exports
+`extern "C"` symbols (`rust/ffi/`, **85 `castrum_*` symbols** — 77 direct + 4
+`validator_c_abi!` + 4 `compress_to_out!`) so Bun can
+`dlopen` it directly:
+
+- **`bun:ffi` (primary on Bun)** — Bun JIT-calls the C-ABI exports at
+  ~10–20 ns per crossing, roughly an order of magnitude cheaper than a NAPI
+  call. A **bind-time self-test** verifies every symbol and the ingress layout
+  blob; on *any* failure the layer disables itself and calls fall back to NAPI.
+- **NAPI (fallback)** — used under Node, when `CASTRUM_FFI_MODE=napi`, or when
+  the self-test fails. It's the safety net that keeps the same code working on
+  both runtimes.
+
+```mermaid
+flowchart LR
+    TS["TypeScript (index.ts)"] -->|"bun:ffi · 85 C-ABI symbols · ~10–20 ns"| RUST["Rust cdylib (rust/ffi/)"]
+    TS -.->|"NAPI fallback (Node / self-test failure)"| RUST
+    RUST --> PIPELINE["8-stage ingress pipeline"]
+    TS --> PACKED["Packed, length-prefixed buffers (zero-copy)"]
+    PACKED --> RUST
+```
+
+### 2.2 Zero-copy, zero-alloc request handling
+
+Instead of marshalling objects, the hot path **packs** the request frame
+(method kind, URL, client IP, request ID, headers) into a shared `Uint8Array`,
+Rust parses it and writes a decision into a **single output buffer**, and TS
+decodes only the fields it needs. Hot paths allocate nothing per request;
+pooled output buffers (with an adaptive-estimate size heuristic) are reused.
+
+### 2.3 The ingress pipeline as a product, not a library
+
+The 8-stage pipeline (trust/IP → HTTPS → CORS → rate limit → body guard →
+JSON/schema → serialize cookies/query → write output) ships twice:
+`createIngressServer` wraps it in a `Bun.serve` route table, and the same
+handlers run over `node:http` via `createIngressServerNode`.
+
+> **Two wire formats on purpose.** The low-level fast path emits
+> `{"error":{...}}` with `x-ratelimit-*`; the pre-baked server emits
+> `{"ok":true,...,"requestId":...}` with `ratelimit-*`. They are a **contract**
+> the load generator validates — unifying them would break the benchmark
+> baseline. (Recorded in `docs/adr/0001-two-wire-formats.md`.)
+
+---
+
+## 3. Results
+
+### 3.1 Startup & first call (the "is it instant?" test)
+
+From `bench/results/startup/latest.json` (Bun 1.4.0, 15 iterations):
+
+| Metric | p50 | p95 |
+|--------|-----|-----|
+| Import the package (raw `index.ts`, no build step) | ~90 ms | ~112 ms |
+| First `rust.crc32` call (ffi transport already warm) | ~0.04 ms | ~0.08 ms |
+| First ingress pipeline call (addon loaded) | ~2.6 ms | ~5.3 ms |
+
+The important number is the first-*call* cost: the cdylib is lazy-loaded, so
+the import itself doesn't pay a native-init penalty.
+
+### 3.2 CPU: where Rust wins, and where it doesn't
+
+The CPU benchmark races every `rust.*` op against a pure-JS baseline **and**
+Bun's built-ins (`docs/bun-builtins-decision-matrix.md`, release addon,
+2026-08-11). Ratio > 1 = Bun is faster.
+
+| Op | Bun built-in | Ratio | Verdict |
+|----|--------------|-------|---------|
+| `passwordHash` (argon2id) | `Bun.password.hashSync` | **0.55** (rust 1.83×) | **keep rust** |
+| `passwordVerify` (argon2id) | `Bun.password.verifySync` | **0.53** (rust 1.88×) | **keep rust** |
+| `passwordVerifyBcrypt` | `Bun.password.verifySync` | **0.67** (rust 1.49×) | **keep rust** |
+| `pbkdf2Sha256` | `node:crypto.pbkdf2Sync` | 0.93 (parity) | keep rust |
+| `fnv1a64` | `Bun.hash` (wyhash) | 1.06 | parity |
+| `hmacSha256` | `Bun.CryptoHasher` | 1.1–1.4 | mild Bun win |
+| `randomToken` | `Bun.randomUUIDv7` | 1.62 | **Bun wins** |
+| `gzipDecompress` | `Bun.gunzipSync` | 1.38 | Bun wins* |
+| `gzipCompress` | `Bun.gzipSync` | 2.02 | **Bun wins** |
+| `crc32` | `Bun.hash.crc32` | 2.8–8.4 | **Bun wins** |
+| `xxh3` | `Bun.hash.xxHash3` | 4.15 | **Bun wins** |
+| brotli / zero-DOM JSON / parsers | *no sync Bun equivalent* | — | keep rust |
+
+\* `gzipDecompress` deliberately stays native: the Rust path enforces a **64 MiB
+decompression-bomb cap** that `Bun.gunzipSync` lacks.
+
+**The honest takeaway:** "native is faster" is *not* automatic. The runtime
+adapter's `builtins` registry (`src/runtime/builtins.ts`) delegates the ops
+where a Bun built-in wins (e.g. `rust.xxh3` loses 4× to `Bun.hash.xxHash3`),
+while argon2id and the zero-DOM JSON path stay native. A consumer-facing selection
+surface (`opImpl` / `isNativeOp` / `opDecision`) lets frameworks bind each op to
+native or JS **once at load time** instead of per call.
+
+### 3.3 HTTP: the pipeline holds up under load
+
+From `bench/results/*/03-stress.bench.md` (ramp to 10k concurrent, ~104 s;
+numbers below are the latest run, 2026-08-21 — re-run
+`bun run bench:http:stress` to refresh):
+
+| Server | Achieved RPS | Total requests | Unexpected errors | Shape failures |
+|--------|-------------|----------------|-------------------|----------------|
+| raw `Bun.serve` | 929.26 | 96,362 | 0 | 0 |
+| **castrum ingress** | **928.65** | **96,369** | **0** | **0** |
+
+Under extreme concurrency both saturate and show long tail latencies (p99 ~18 s
+on this machine) — that's the load generator over-driving the box, not a bug.
+The meaningful result is that adding the full pipeline (CORS + rate limit +
+body guard + schema + security headers + request IDs) costs **no correctness
+and no measurable throughput** versus a hand-rolled raw server (the two are at
+parity, within noise).
+
+### 3.4 The bug that almost killed the server: C-ABI panics
+
+The most instructive moment: under `11-concurrent-burst`, the ingress server
+**died at ~2.5 s and stayed down** (91% network errors). Root cause: the `bun:ffi`
+`extern "C"` exports had no panic guard. A panic in a napi call becomes a JS
+exception, but a panic unwinding through raw `extern "C"` is undefined behaviour
+that takes the whole process down.
+
+The fix (in `rust/ffi/`): every fallible / allocating C-ABI export now routes
+its core through `panic_guard` (`catch_unwind`) and reports a sentinel instead
+of panicking. After the fix, the same scenario completes cleanly:
+
+| Scenario (post-fix) | Requests | Network errors | Unexpected errors |
+|---------------------|----------|----------------|-------------------|
+| `11-concurrent-burst` | 30,211 | 0 | 0 |
+
+**Lesson:** if you expose a raw C ABI to a host runtime, you own the unwind
+boundary. Never assume a panic can't escape — contain it explicitly, and make
+your bind-time self-test exercise the fallible paths.
+
+### 3.5 Correctness as a first-class gate
+
+The HTTP smoke scenario (`01-smoke`) is a **wire-format guard**, not a
+throughput test: it verifies `ok === true` + `requestId` on success and
+`error.code` / `error.message` on failure for every response. Across the
+scenarios, `shape_failures` and `unexpected_statuses` are 0 — the two wire
+formats are validated every CI run, so a change to the response shape breaks
+the benchmark, not prod.
+
+---
+
+## 4. Engineering decisions & lessons
+
+1. **Two transports, one binary.** Build with napi-rs (portability), export
+   `extern "C"` (speed on Bun), and let a **bind-time self-test** pick the safe
+   path automatically. Never let a transport failure be silent.
+2. **Benchmark against the built-in, not just the baseline.** Bun's `Bun.hash.*`,
+   `Bun.gzipSync`, `Bun.CryptoHasher`, and `Bun.randomUUIDv7` beat an FFI
+   crossing on several ops. The rule that emerged: **keep Rust where it wins or
+   where Bun has no synchronous equivalent; delegate where Bun wins.** Don't
+   reinvent the wheel — `docs/adr/0003-bun-builtins-delegation.md`.
+3. **"Native" is not a synonym for "fast".** The `builtins` registry delegates
+   where Bun wins. Let data, not enthusiasm, decide.
+4. **A wire format is a contract.** Two deliberately-different formats are
+   pinned by tests and the load generator. If you change the shape, you change
+   the benchmark.
+5. **Contain the C ABI.** A panic across `extern "C"` is a crash. Route every
+   fallible export through a guard and cover it in the self-test.
+6. **Zero-copy is a discipline.** Packed buffers, pooled outputs, lazy decode —
+   every allocation you remove from the hot path is tail latency you never pay.
+7. **Be honest about scope.** The rate limiter is **per-process, not
+   distributed**; proxy trust is **off by default** (spoof-proof); the
+   decompression bomb cap is **64 MiB**. Documenting the boundaries is as
+   important as the speed.
+
+---
+
+## 5. Reproduce it yourself
+
+```bash
+bun install
+bun run build              # release addon (baseline CPU — what ships)
+
+bun run check              # CPU benchmark → bench/results/cpu/latest.json
+bun run bench:startup      # import + first-call timing
+bun run bench:http:smoke   # HTTP wire-format guard
+bun run bench:http         # all HTTP scenarios (bun / elysia / ingress)
+```
+
+See [`BENCHMARKS.md`](./BENCHMARKS.md) for scenario descriptions and how to read
+the reports.
+
+---
+
+## 6. When this pattern applies (and when it doesn't)
+
+The hybrid TS + Rust + FFI pattern paid off here because the workload was
+**CPU-bound, synchronous, and high-volume**. Reach for it when:
+
+- Request handling spends measurable time in validation/parsing/hashing.
+- You want a pre-baked HTTP pipeline (CORS, rate limit, schema, security
+  headers) without a heavy middleware graph.
+- You must support both Bun and Node from one codebase.
+
+Don't reach for it when:
+
+- The bottleneck is I/O or the database, not CPU — Rust won't help.
+- You only need a handful of ops that Bun's built-ins already win (use
+  `Bun.hash.crc32`, `Bun.gzipSync`, `Bun.randomUUIDv7` directly).
+- You can't ship/ build a native `.node` in your deployment (no Rust toolchain
+  in CI, or a locked-down runtime that forbids native addons).

package/docs/ENVIRONMENT.md

@@ -4,13 +4,15 @@ This document lists every environment variable read by the package and its
 example servers. All values are read once at module load; invalid values are
 warned about and replaced with the documented default.
 
-## Ingress server (`bench/servers/ingress-server.ts`)
+## Ingress server (`bench/http/servers/ingress-server.ts`)
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
 | `INGRESS_TRUST_PROXY` | bool | `false` | **Opt-in.** When `true`, honors `X-Forwarded-For` / `X-Real-IP` for client-IP resolution. Keep **off** unless the server sits behind a trusted edge that strips these headers, otherwise clients can spoof arbitrary IPs for IP-based rate limiting. |
 | `INGRESS_REQUEST_ID_HEADER` | bool | `false` | Emit an `x-request-id` response header per request. The request ID is always generated internally; this only controls whether it is echoed to clients. |
-| `INGRESS_UNSAFE_ZERO_COPY` | bool | `false` | Enable zero-copy response bodies. **Not recommended** unless per-response output buffers are implemented; leave off for safety (bodies are copied by default). |
+| `INGRESS_ZERO_COPY` | bool | `false` | Enable zero-copy response bodies (legacy alias `INGRESS_UNSAFE_ZERO_COPY` still honored). **Not recommended** unless per-response output buffers are implemented; leave off for safety (bodies are copied by default). |
+| `INGRESS_ZERO_COPY_MAX_IN_FLIGHT` | int | `128` | Max pooled output buffers kept in flight for zero-copy responses (min `1`). |
+| `INGRESS_ZERO_COPY_TIMEOUT_MS` | int | `1000` | Timeout before a zero-copy pooled buffer is force-released (min `0`). |
 | `INGRESS_OUTPUT_BUF_BYTES` | int | `131072` | Size of the Rust output buffer (min `65536`). If cookies + query + metadata JSON exceed this, `FLAG_BODY_TRUNCATED` is set and the request fails closed. |
 | `INGRESS_SECURITY_HEADERS` | bool | `true` | Emit the precomputed security headers (CSP, HSTS, X-Frame-Options, etc.). Disable only behind an edge that already sets them. |
 | `INGRESS_REUSE_PORT` | bool | `false` | Enable `SO_REUSEPORT` for multi-process deployments (spawn N processes, each with a distinct `INGRESS_WORKER_ID`). |
@@ -27,9 +29,9 @@ for false; anything else is warned about and falls back to the default.
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
-| `CASTRUM_RAYON_THREADS` / `RUST_RAYON_THREADS` (legacy `RUST_BENCH_RAYON_THREADS`) | int | `max(1, cores-1)` | Rayon thread pool size. The pool is process-wide and initialized **once** — the first use wins. With lazy init, call `rust.configure({ rayonThreads })` (or set this env) before the first batch operation. |
-| `CASTRUM_MAX_RAYON_THREADS` (legacy `RUST_BENCH_MAX_RAYON_THREADS`) | int | `cores` | Hard cap on rayon threads (native). |
-| `CASTRUM_PIN_CORES` (legacy `RUST_BENCH_PIN_CORES`) | (presence) | — | When set (Linux), pin rayon worker threads to distinct cores. |
+| `CASTRUM_RAYON_THREADS` | int | `max(1, cores-1)` | Rayon thread pool size. The pool is process-wide and initialized **once** — the first use wins. With lazy init, call `rust.configure({ rayonThreads })` (or set this env) before the first batch operation. |
+| `CASTRUM_MAX_RAYON_THREADS` | int | `cores` | Hard cap on rayon threads (native). |
+| `CASTRUM_PIN_CORES` | (presence) | — | When set (Linux), pin rayon worker threads to distinct cores. |
 
 ## Native transport selection (`src/native/ffi.ts`)
 
@@ -40,13 +42,13 @@ whether the ffi transport is live.
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
-| `CASTRUM_FFI_MODE` (legacy `RUST_FFI_MODE`) | string | `auto` | Native transport selection: `auto` (default) — use `bun:ffi` on Bun, silently fall back to napi on bind/self-test failure (and always on Node); `ffi` — force `bun:ffi` on Bun and THROW if it cannot bind or the self-test fails (for benches/CI that must run the primary transport; invalid on Node); `napi` — never bind, every call goes through the napi addon (exercises the fallback on Bun). |
+| `CASTRUM_FFI_MODE` | string | `auto` | Native transport selection: `auto` (default) — use `bun:ffi` on Bun, silently fall back to napi on bind/self-test failure (and always on Node); `ffi` — force `bun:ffi` on Bun and THROW if it cannot bind or the self-test fails (for benches/CI that must run the primary transport; invalid on Node); `napi` — never bind, every call goes through the napi addon (exercises the fallback on Bun). |
 
 ## Native addon loader (`src/native/loader.ts`)
 
 | Variable | Type | Default | Description |
 |----------|------|---------|-------------|
-| `CASTRUM_DEBUG` (legacy `RUST_BENCH_DEBUG`) | (presence) | — | Log the resolved addon path and exported keys at load time. |
+| `CASTRUM_DEBUG` | (presence) | — | Log the resolved addon path and exported keys at load time. |
 | `CASTRUM_NATIVE_LIBRARY_PATH` / `NAPI_RS_NATIVE_LIBRARY_PATH` | path | — | Explicit path (file or directory) to the native `.node` artifact, overriding normal resolution. Useful for bundled/electron layouts. |
 
 ## Library logging (`src/shared/log.ts`)
@@ -55,6 +57,21 @@ whether the ffi transport is live.
 |----------|------|---------|-------------|
 | `CASTRUM_LOG_LEVEL` | string | `info` | Threshold for the built-in structured logger (`debug`/`info`/`warn`/`error`/`silent`). Enabled per handler via the `structuredLog: true` runtime option; emits one JSON line per request/error to stderr (`{ts, level, event, requestId, method, path, status, durationMs, ...}`). |
 
+## Benchmark controls (`bench/`, `src/bench/`)
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `CASTRUM_BENCH_BATCH_SIZE` | int | `64` | Fast-op batch size for the CPU bench's measurement loop (`src/bench/measure.ts`); for methodology experiments. |
+| `CASTRUM_BENCH_FFI` | bool | — | When `1`, the CPU bench treats an unavailable FFI transport as a hard failure instead of a warning (`src/bench/run.ts`). |
+| `CASTRUM_FFI_LOAD_MS` | int | `400` | Per-window duration (ms) of the `ffi-all` load-run (`bench/ffi/ffi-all.ts`). |
+| `CASTRUM_FFI_LOAD_WINDOWS` | int | `4` | Number of load windows in `ffi-all` (`bench/ffi/ffi-all.ts`). |
+
+## Publishing (`scripts/prepublish.mjs`, `publish-manual.mjs`)
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `CASTRUM_PUBLISH_ALLOW_PARTIAL` | bool | — | When `1`, `prepublishOnly` ships a tarball containing only the locally-built platforms instead of failing on the full `napi.targets` set. Set automatically by `bun run publish:manual`; **never** set it for a normal `npm publish`.
+
 ## Security guidance
 
 - **Proxy trust**: `trustProxy: true` is deprecated — it trusts EVERY hop of