castrum 0.9.1 → 0.9.2

package/docs/ARCHITECTURE.md

@@ -31,9 +31,9 @@ The bridge between TypeScript and Rust has **two transports**, both loading the
 cdylib (built with napi-rs):
 
 - **`bun:ffi` (PRIMARY on Bun)** — `src/native/ffi.ts` `dlopen`s the addon's
-  `extern "C"` exports (`rust/ffi.rs`, 79 `castrum_*` symbols — 71 direct + 4
+  `extern "C"` exports (`rust/ffi/`, 85 `castrum_*` symbols — 77 direct + 4
   `validator_c_abi!` + 4 `compress_to_out!`, parity guarded by
-  `test/unit/features/ffi-symbol-parity.test.ts`) and Bun JIT-calls them
+  `test/unit/native/ffi-symbol-parity.test.ts`) and Bun JIT-calls them
   directly (~10-20ns crossing vs ~100-350ns N-API). A bind-time self-test guards
   correctness: on ANY failure the layer is disabled and calls fall back to napi.
   `CASTRUM_FFI_MODE=auto|ffi|napi` selects the transport (default `auto`).
@@ -83,7 +83,8 @@ shared-infra names so legacy `crate::util::*` call sites keep working.
 rust/
 ├── lib.rs                 ── Crate root: folder declarations + module map, global allocator
 ├── test_support.rs        ── shared #[cfg(test)] helpers (pack_headers, decode_packed_pairs, Rng)
-├── unit_tests.rs          ── cross-module test suite
+├── panic_safety.rs        ── #[cfg(test)] cross-parser fuzz tests (malformed input never panics)
+├── proptest_suite.rs      ── #[cfg(test)] property-based adversarial-parser tests
 │
 ├── util/                  ── Shared infrastructure (mod.rs re-exports crate::util::*)
 │   ├── bytes.rs           ── byte primitives (word-compare, hex, %XX decode, cookie_pairs)
@@ -126,9 +127,10 @@ rust/
 │   │                        (jsonschema cmp::equal; shared by jwt_verify, json_parse,
 │   │                        fast_schema enum/const/uniqueItems)
 │   ├── json_ser.rs        ── zero-alloc JSON escaping + cookie/query → JSON writers
-│   ├── json_patch_ops.rs  ── CUSTOM sonic RFC 6902 engine (Pointer ~0/~1 unescape +
-│   │                        add/remove/replace/move/copy/test incl. array `-`/bounds +
-│   │                        1==1.0; json-patch/jsonptr deps REMOVED)
+│   ├── patch/             ── CUSTOM sonic RFC 6902 engine (pointer.rs + ops.rs + engine.rs +
+│   │                        api.rs + tests.rs; Pointer ~0/~1 unescape + add/remove/replace/
+│   │                        move/copy/test incl. array `-`/bounds + 1==1.0; json-patch/jsonptr
+│   │                        deps REMOVED)
 │   ├── json_schema.rs     ── SchemaValidator napi class (fast + jsonschema fallback)
 │   └── fast_schema/       ── zero-DOM draft-07 JSON Schema fast path
 │       └── mod.rs + types.rs / cursor.rs / compile.rs / validate.rs / errors.rs / email.rs (format:"email" replica) / tests.rs
@@ -265,7 +267,7 @@ src/
 >    (`handle_request_packed`). Different wire format: success
 >    `{"ok":true,...,"requestId":...}`, errors
 >    `{"ok":false,"error":{code,message}}`, `ratelimit-*` headers. The
->    benchmark server (`bench/servers/ingress-server.ts`) uses this path and
+>    benchmark server (`bench/http/servers/ingress-server.ts`) uses this path and
 >    re-exports the pre-baked functions.
 
 ## Node.js Compatibility
@@ -458,7 +460,7 @@ Offset (bytes)
   - fast_schema enum/const/uniqueItems re-parse the doc into `sonic_rs::Value`
     and compare with `sonic_values_equal` (no `Vec<serde_json::Value>`).
   - minijinja contexts are `sonic_rs::Value` (implements `Serialize`).
-- **Custom RFC 6902 patch engine** (`json_patch_ops.rs`): no longer round-trips
+- **Custom RFC 6902 patch engine** (`rust/json/patch/`): no longer round-trips
   through the serde_json-DOM `json-patch` crate. A `Pointer` type (`~0`/`~1`
   unescape, RFC 6901) + `PatchOp` parser + applicator (add incl. array `-` and
   bounds, remove, replace, move, copy, test incl. `1 == 1.0`) runs directly on
@@ -497,7 +499,7 @@ Offset (bytes)
               └─── [cookie_parser]
               [hashing] ──── [hmac_sha256]
               [validation]
-              [json_ops] ──── [json_patch_ops]
+              [json_ops] ──── [json/patch]
               [json_schema]
               [url_codec]
               [mime_lookup]

package/docs/BENCHMARKS.md

@@ -76,17 +76,22 @@ bun run bench:http:all-heavy
 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):
-#   node bench/autocannon-stress.mjs            # dynamic 03-stress mix
-#   AC_PATH=/api/users node bench/autocannon-stress.mjs
+# 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 node bench/autocannon-stress.mjs
-#   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.
+#     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 AC_PIPELINING=10 node bench/autocannon-stress.mjs
+#   AC_INSTANCES=4 node bench/autocannon-stress.mjs
 #   (ingress/router only — they read INGRESS_REUSE_PORT=1)
 ```
 
@@ -98,8 +103,8 @@ default** (`BUN_CONFIG_MAX_HTTP_REQUESTS`, max 65,336). When a scenario's
 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=65536` for you.
-- `bench/run-bench.ts` warns if a selected scenario exceeds the effective cap.
+- 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
@@ -112,7 +117,7 @@ a sub-ms `p50` with a multi-second tail and a flat RPS wall across every server.
   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-16)
+### 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
@@ -120,33 +125,60 @@ pin at a per-core ceiling on this machine. The host is load-noisy, so use the
 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).
-> **Dated snapshot (2026-08-16 ingress-RPS pass).** The host is load-noisy;
-> the newest persisted autocannon medians under `bench/results/autocannon/*/final-*.median.md`
-> supersede these numbers run-to-run. Use the median-of-N runner below for fresh
-> comparisons.
-
-Current medians (`AC_DURATION=8 AC_RUNS=3`, 500 connections, single instance):
 
-- `GET /api/users?q=…` (query + cookies + CORS + metadata envelope):
-  **bun 45.2k, elysia 41.7k, ingress 51.5k, router 49.4k RPS** — ingress ~**+14%**
-  vs bun, with a tighter tail (p50 9ms / p99 16ms vs bun p50 10ms / p99 28ms).
+> **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 40.8k, elysia 35.1k, ingress 45.4k, router 35.1k RPS** — ingress ~**+11%**
-  vs bun. The pre-optimization ingress POST gap (≈ −24% vs bun) is closed by
-  the changes in `CHANGELOG [Unreleased]` (JS hot-path elimination + single-pass
-  body validation).
-- Per-request cost breakdown (`bun bench/ingress-cost.ts` / `ingress-cost-post.ts`,
-  min-of-5): GET `run` ~826ns (native 168ns + JS ~446ns packing + decode 60ns);
-  POST `run` ~1154ns (native ~740ns — was 808ns before the single-pass — + JS).
-  The POST body read is now **synchronous for buffered bodies**: `Bun.peek` on
-  `req.bytes()` skips the deadline race + watchdog for declared-length bodies
-  (was ~600ns of race machinery per POST).
+  **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=4` (with `AC_PIPELINING` so the
-  client can drive enough in-flight requests) scaled ingress from ~45k to
-  ~69k RPS on this machine. Only ingress/router bind with `reusePort`
-  (`INGRESS_REUSE_PORT=1`); bun/elysia do not set it. For cleanest numbers run
-  autocannon on a separate host.
+  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.
 
 ---
 
@@ -271,7 +303,7 @@ When comparing multiple frameworks, differences are expressed as:
 
 ```
 bench.ts
-  └─ Loads benchmark tasks from src/bench/tasks/ (33 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
@@ -294,14 +326,14 @@ 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. |
-| `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

package/docs/CASE_STUDY.md

@@ -42,7 +42,7 @@ as a pre-baked pipeline, and still be usable from both runtimes.
 ### 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.rs`, **79 `castrum_*` symbols** — 71 direct + 4
+`extern "C"` symbols (`rust/ffi/`, **85 `castrum_*` symbols** — 77 direct + 4
 `validator_c_abi!` + 4 `compress_to_out!`) so Bun can
 `dlopen` it directly:
 
@@ -56,7 +56,7 @@ The addon is built with napi-rs (so Node can load it), but it *also* exports
 
 ```mermaid
 flowchart LR
-    TS["TypeScript (index.ts)"] -->|"bun:ffi · 75 C-ABI symbols · ~10–20 ns"| RUST["Rust cdylib (rust/ffi.rs)"]
+    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)"]
@@ -134,18 +134,21 @@ 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):
+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` | 862.5 | 92,174 | 0 | 0 |
-| **castrum ingress** | **904.2** | **94,060** | **0** | **0** |
+| 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.
+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
 
@@ -155,7 +158,7 @@ The most instructive moment: under `11-concurrent-burst`, the ingress server
 exception, but a panic unwinding through raw `extern "C"` is undefined behaviour
 that takes the whole process down.
 
-The fix (in `rust/ffi.rs`): every fallible / allocating C-ABI export now routes
+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:
 

package/docs/ENVIRONMENT.md

@@ -4,7 +4,7 @@ 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 |
 |----------|------|---------|-------------|
@@ -57,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

package/docs/FFI_BUN_GUIDE.md

@@ -1,7 +1,7 @@
 # Writing Rust for Bun — FFI Optimization Guide
 
 > **Who this is for**: anyone (human or agent) writing or reviewing the Rust
-> `extern "C"` surface in `rust/ffi.rs` and its `bun:ffi` binding in
+> `extern "C"` surface in `rust/ffi/` and its `bun:ffi` binding in
 > `src/native/ffi.ts`. The rules below are the concrete, citable behaviors of
 > Bun's own `bun:ffi` implementation, distilled so that future generated Rust
 > code is **optimized for Bun** out of the box — correct on the first `dlopen`,
@@ -28,7 +28,9 @@ JS shim:
   in-engine … with no per-argument JavaScript shim" (`docs/runtime/ffi.mdx`,
   "Performance"). This is why the crossing is ~10–20 ns vs ~100–350 ns for a
   Node-API call, and why Bun's own bench puts `bun:ffi` at 2–6× faster than
-  Node's N-API (`bench/ffi/bun.js`, `docs/runtime/ffi.mdx`).
+  Node's N-API (upstream bench `bench/ffi/bun.js` in the Bun runtime checkout
+  `/home/adeel/poc/bun`, plus `docs/runtime/ffi.mdx`; castrum's own FFI-vs-napi
+  margin bench is `bench/ffi/ffi-margin.ts`).
 - The `#[no_mangle] extern "C"` symbols come from the **same cdylib** that
   napi-rs loads under Node — the two transports are two views of one binary.
 
@@ -168,7 +170,7 @@ string into a JS `string` at call time and returns that; `NULL` → `null`
 copies **nothing itself** — the C side must own the memory until the call
 returns.
 
-- **castrum's application**: the per-thread reused `CSTR_BUF` in `rust/ffi.rs`
+- **castrum's application**: the per-thread reused `CSTR_BUF` in `rust/ffi/`
   (`cstring_return`) is exactly right — the clone is synchronous, so reusing
   the buffer across calls is safe.
 - **Aliasing caveat**: a C function that returns a pointer *derived from a
@@ -204,7 +206,7 @@ all bound symbols are unreachable.
 ## 8. Thread-safety & per-thread caches
 
 `bun:ffi` symbols are shared across Worker threads (same dlopen'd cdylib
-mapping; verified by castrum's `bench/ffi-workers.ts` — 4 workers, no
+mapping; verified by castrum's `bench/ffi/ffi-workers.ts` — 4 workers, no
 thread-safety issue). The Rust side must therefore keep any per-call mutable
 state **thread-local**, never global:
 
@@ -267,7 +269,7 @@ These are not optional — they are what make the C-ABI surface safe on Bun (no
 napi-style unwind guard exists for raw `extern "C"`).
 
 1. **`panic_guard` every fallible/allocating core** (`std::panic::catch_unwind`
-   in `rust/ffi.rs`, `AssertUnwindSafe` for captured `&mut [u8]`). An uncaught
+   in `rust/ffi/`, `AssertUnwindSafe` for captured `&mut [u8]`). An uncaught
    panic unwinding through `extern "C"` kills the whole Bun process — this is
    what happened under `11-concurrent-burst`.
 2. **Bind-time self-test for EVERY new symbol** (`src/native/ffi/selfTest`).
@@ -307,9 +309,15 @@ that transfer directly to castrum's cdylib:
 
 ## 13. Version anchors & verification
 
-| Claim | Source (Bun 1.3.14 checkout) |
+The behavioral claims above are verified against the Rust-based Bun source
+checkout at `/home/adeel/poc/bun` (LATEST file: 1.3.14; `package.json` tracks
+the 1.4 development line). The decision matrix and ADR-0003 measure against
+the installed **Bun 1.4.0** runtime — both anchors describe the same
+Rust-based runtime family. Castrum's own measurements live in `bench/`.
+
+| Claim | Source (Bun checkout `/home/adeel/poc/bun`) |
 |---|---|
-| JIT-to-direct-native-call, 2–6× vs NAPI | `docs/runtime/ffi.mdx` → Performance; `bench/ffi/bun.js` |
+| JIT-to-direct-native-call, 2–6× vs NAPI | `docs/runtime/ffi.mdx` → Performance; `bench/ffi/bun.js` (upstream) |
 | `FFIType` numeric tags (`buffer`=20, `buffer_length`=21, `u64_fast`=16) | `src/js/bun/ffi.ts`; static asserts in `src/jsc/bindings/JSCFFIBridge.cpp` |
 | `buffer`/`buffer_length` atomic snapshot, arg-only | `packages/bun-types/ffi.d.ts`; `src/runtime/ffi/ffi_body.rs::reject_cc_unsupported_types_error` |
 | Pointers are `number`; BigInt converted to number | `docs/runtime/ffi.mdx` → Pointers |
@@ -320,8 +328,8 @@ that transfer directly to castrum's cdylib:
 **Verify after any FFI change**:
 
 ```bash
-nm -D --defined-only <addon> | grep -c castrum_   # = 79
+nm -D --defined-only <addon> | grep -c castrum_   # = 85
 bun run bench:http:smoke                           # after touching decoders/handlers
-bun test test/unit/features/ffi.test.ts            # FFI↔napi parity + self-test
-bun test test/unit/features/ffi-symbol-parity.test.ts
+bun test test/unit/native/ffi.test.ts            # FFI↔napi parity + self-test
+bun test test/unit/native/ffi-symbol-parity.test.ts
 ```

package/docs/GETTING_STARTED.md

@@ -60,8 +60,10 @@ Everything is **synchronous** — there is no async/await in the FFI surface.
 > transport — see `rust.transport()` / `rust.ffiActive()`); Node and any
 > `CASTRUM_FFI_MODE=napi` fall back to the napi addon. Since Phase 6 the
 > compiled-once instances are NOT napi-only — their hot per-call ops route
-> through the C-ABI via opaque-`usize` handles. Still napi-only:
-> `rust.batch.*` / `rust.packed.*`, `text.*`, and the DOM `jsonParse`.
+> through the C-ABI via opaque-`usize` handles. `rust.text.*`
+> (`mimeFromExtension`, `wsAcceptKey`, `validateEmail`/`validateUuid`/…) and
+> the DOM `jsonParse` are FFI-first today; still napi-only:
+> `rust.batch.*` and `rust.packed.*`.
 
 > **Tip**: `rust` is a singleton created with sensible defaults. If you need
 > isolated state (own rayon threads, own HMAC cache), call
@@ -86,8 +88,7 @@ loader.run("jsonPatch", docs, patches);           // paired ops (companion array
 loader.schema(validator)(docs);                   // schema bitset (+ .count())
 ```
 
-See the README "Higher-order data loader" section for the full op table and
-`createLoader` options.
+See docs/API.md — [Higher-order data loader](API.md#higher-order-data-loader-loader--createloader) — for the full op table and `createLoader` options.
 
 ## 3. Stand up an HTTP server (the ingress pipeline)
 

package/docs/HOW_TO_ADD_AN_OP.md

@@ -0,0 +1,180 @@
+# HOW TO ADD AN OP (runbook)
+
+This is the single runbook for adding a new native operation to `castrum` end
+to end. It consolidates the six places a new op must be wired, so a contributor
+(or AI agent) knows exactly what to touch and in what order. "Op" = a
+performance-critical primitive (`crc32`, `hmacSha256`, `jsonValid`,
+`gzipCompress`, `validateEmail`, …) exposed through the native addon.
+
+The golden rule: **a new op must be reachable from the public `rust.*` surface,
+bound on BOTH transports (bun:ffi primary + napi fallback), pinned by a
+bind-time self-test, and listed in the op-selection metadata** — or the parity
+guards fail.
+
+---
+
+## 0. The six wiring points at a glance
+
+| # | File | What you add |
+|---|------|--------------|
+| 1 | `rust/<domain>/<module>.rs` (+ `mod.rs`) | The pure-Rust core (no napi types — unit-testable) |
+| 2 | `rust/ffi/<domain>.rs` (+ `rust/ffi/util.rs`) | The `#[no_mangle] extern "C"` export (`panic_guard`, correct ABI) |
+| 3 | `src/native/ffi.ts` + `src/native/ffi/types.ts` + `src/native/ffi/build/<domain>.ts` | The `bun:ffi` dlopen map entry + `BunFFI` method + per-domain self-test check |
+| 4 | `src/rust-ffi/scalar/<area>.ts` (or `text`/`batch`/`packed`) | The public `rust.*` wrapper |
+| 5 | `src/selection.json` + `src/shared/proven.ts` + `src/selection.ts` | The baked op-selection / delegation metadata |
+| 6 | `test/unit/native/ffi.test.ts` + `test/unit/contract/wiring.test.ts` | The parity tests |
+
+Follow the numbered sections below. When you're done, the parity gates
+(§7) are your safety net.
+
+---
+
+## 1. Add a new Rust module (the core)
+
+Create the pure-Rust core in its domain folder, e.g. `rust/crypto/hmac_sha256.rs`.
+Keep **napi types out of the core** — internal signatures use `&[u8]` /
+`&str` / `Result<_, String>` so it stays unit-testable with plain `cargo test`.
+
+```rust
+/// Compute an FNV-1a 64-bit hash of `input`.
+#[inline]
+pub fn fnv1a64_bytes(input: &[u8]) -> u64 { /* ... */ }
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+    #[test]
+    fn standard_vectors() { /* ... */ }
+}
+```
+
+- Register the module in `rust/lib.rs` (the module map comment) and in the
+  folder's `mod.rs` re-exports.
+- Ship `#[cfg(test)] mod tests` in the SAME file (cross-module tests live in
+  `rust/panic_safety.rs` / `rust/proptest_suite.rs`; shared helpers in
+  `rust/test_support.rs`).
+- If it needs a napi-visible class or batch, add a thin `api.rs` boundary in
+  the module folder (name it `api`, **not** `napi` — that collides with the
+  `napi` crate under `use super::*`).
+
+## 2. Expose it over the C ABI (bun:ffi primary)
+
+Add the `#[no_mangle] extern "C"` export in `rust/ffi/<domain>.rs`. Every
+fallible / allocating export **must** route its core through `panic_guard`
+(defined in `rust/ffi/util.rs`) so an uncaught panic can't unwind through
+`extern "C"` and kill the process.
+
+Rules (see `docs/FFI_BUN_GUIDE.md` for the full contract):
+- Keep signatures **scalar + `(ptr,len)`** — no struct-by-value, no variadics.
+- Null-check pointers and opaque handles (return `0` / `null` instead of
+  dereferencing).
+- Byte-count returns MUST use `u64_fast` (`U64_FAST` in ffi.ts); opaque handles
+  pass as `usize`/number.
+- String ARGS come in as `*const c_char` (bun:ffi `cstring`); use
+  `CStr::from_ptr(header).to_bytes()`.
+- String RETURNS use `cstring_return` (per-thread `CSTR_BUF`, cloned at call
+  time — never return a pointer into JS-owned memory).
+- **Variable-size outputs**: return the EXACT required byte count on a
+  too-small buffer (0 = real error) so JS allocates once and retries at most
+  once.
+
+```rust
+/// FNV-1a 64-bit hash → u64.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_fnv1a64(data: *const u8, len: usize) -> u64 {
+    if data.is_null() { return 0; }
+    panic_guard(
+        || crate::crypto::hashing::fnv1a64_bytes(std::slice::from_raw_parts(data, len)),
+        0,
+    )
+}
+```
+
+- A `#[no_mangle]` symbol emits regardless of module path — no re-export needed
+  for the C ABI itself (re-exports are only needed for unit tests to reach the
+  item).
+
+## 3. Bind it on the bun:ffi path (transport core + build folder)
+
+`src/native/ffi.ts` owns the `dlopen` symbol map (`bind()`). Add your symbol
+key (the EXACT `castrum_*` name) to that map with its ABI spec.
+
+Then add the ergonomic method where it belongs in the decomposed bind surface:
+- `src/native/ffi/build/codecs.ts` — hashing / codec / crypto / auth
+- `src/native/ffi/build/compress.ts` — gzip/brotli + jsonPatch
+- `src/native/ffi/build/parse.ts` — packed parsers + media-type/http-date/accept
+- `src/native/ffi/build/instances.ts` — opaque-handle evals (schema/jwt/template/route/ingress)
+
+Add the method signature to the `BunFFI` interface in
+`src/native/ffi/types.ts` (use a `Raw2..Raw12` / `RawCStr` signature for the
+raw symbol, or add a new one if the arity doesn't fit).
+
+**Add the self-test next to the binding**: each `build/*.ts` file exports a
+`selfTest<Domain>` function; add a known-good vector check for your method
+there. `src/native/ffi/selftest.ts` is a thin aggregator that ANDs all four
+domain self-tests — a new symbol is bound **and** self-tested in one file.
+
+## 4. Expose it on the public `rust.*` surface
+
+`src/rust-ffi/scalar/<area>.ts` (or `text.ts` / `batch/` / `packed.ts`) builds
+the public wrapper. The wrapper normalizes the string-vs-bytes return
+divergence (`toBytes`/`toText` — `src/shared/bytes.ts`), adds the pooled
+`*Into` variants where hot, and (optionally) delegates to Bun built-ins when
+`isBun()` via `src/runtime/builtins.ts` (`BUILTIN_OPS`).
+
+Add a JSDoc block (`@param`/`@returns`/`@example`) — `bun run check:jsdoc`
+enforces a 95% floor on exported symbols.
+
+## 5. Op-selection metadata (baked)
+
+- `src/selection.json` — the machine-readable selection row for the op
+  (native/js/bun winner). Generated by `scripts/select-native.ts --write`.
+- **GOTCHA**: `select-native.ts`'s `OPS` array is the source of truth for what
+  stays in `selection.json`. ANY op with a baked native/js decision MUST be
+  listed there (or as a `skip+pinned` entry) or `--write` DELETES it from the
+  selection. If you add an op to `rust/selection.rs`, add it to `OPS` too.
+- `src/shared/proven.ts` — `PROVEN_SELECTION` (PURE DATA) maps each op to its
+  proven winner (`native` / `js` / `bun`). Add/update the entry.
+- `src/selection.ts` — `BUN_WINS` delegation registry (which ops delegate to
+  Bun built-ins under Bun). Keep `src/runtime/builtins.ts` `BUILTIN_OPS` in
+  sync.
+
+## 6. Parity tests
+
+- `test/unit/native/ffi.test.ts` — pin the ffi-vs-napi byte-parity for the new
+  op (the transport self-test only guards bind-time vectors; this pins real
+  parity against a live napi instance).
+- `test/unit/contract/wiring.test.ts` — verifies each baked `PROVEN_SELECTION`
+  winner is actually wired (`opImpl(op)` agrees, `builtins.has(op)` matches,
+  native/js entries match the addon's embedded `selection.json`).
+- `test/unit/native/ffi-symbol-parity.test.ts` — scans `rust/ffi/` for every
+  `castrum_*` symbol and asserts it's bound in the ffi.ts map AND exercised by
+  the self-test. New symbol not bound → this fails.
+
+## 7. Run the gates
+
+```sh
+cargo test                                  # Rust cores + C-ABI tests
+bun test                                    # TS suite (incl. the parity tests)
+bunx tsc --noEmit && bunx tsc --noEmit -p tsconfig.test.json
+bun run lint                                # Biome
+bun run check:jsdoc                         # ≥95% JSDoc on exported symbols
+bun run check:clean                         # module headers, runtime seam, purity, doc links
+bun run check:version                       # package.json ↔ Cargo.toml ↔ CHANGELOG
+bun run bench:http:smoke                    # if you touched the ingress path
+bun run bench:startup                       # if you touched the transport/loader
+```
+
+---
+
+## Checklist
+
+- [ ] Pure-Rust core in the right domain folder with `#[cfg(test)] mod tests`
+- [ ] `#[no_mangle] extern "C"` export with `panic_guard` + null checks +
+      correct `u64_fast`/cstring ABI
+- [ ] Symbol in the `ffi.ts` dlopen map + `BunFFI` interface method
+- [ ] Per-domain `selfTest*` vector in the same `ffi/build/*.ts` file
+- [ ] Public `rust.*` wrapper with JSDoc (+ `*Into` pooled variant if hot)
+- [ ] `selection.json` + `PROVEN_SELECTION` + `BUILTIN_OPS` (if delegating)
+- [ ] `ffi.test.ts` + `wiring.test.ts` parity coverage
+- [ ] All §7 gates green

package/docs/INGRESS-ROUTER.md

@@ -38,6 +38,7 @@ wire route factories over that route's compiled handler:
 | `cookies` | GET read (cookies-style) handler |
 | `delete` | DELETE read-style handler |
 | `responder` | JS responder route (`methods`, `readBody`, `terminalStyle`) |
+| `native` | LEAN native-stack responder route: the route-wire v3 per-route stack (`createNativeRoute`) runs ONLY the plan's stages (parseQuery/parseCookies/requireJsonBody/validateBody) in ONE native call — no CORS/rate-limit/security/IP/metadata envelope. The responder builds the 2xx from the decoded snapshot. Measured ~580ns cheaper per request than the full-pipeline responder on a parseQuery+parseCookies route, and **+34% RPS at the HTTP level** on the bench server's `/api/native` vs `/api/users` (server-bound config). |
 | `raw` | Raw `Request → Response` handler served OUTSIDE the pipeline (health/metrics probes) |
 | `maxBodyBytes` / `bodyTimeoutMs` | Per-route write/echo overrides |
 
@@ -76,6 +77,6 @@ const router = createIngressRouter({
 const server = Bun.serve({ routes: router.routes }) // or router.fetch
 ```
 
-The benchmark server `bench/servers/router-server.ts` uses this API (same route
+The benchmark server `bench/http/servers/router-server.ts` uses this API (same route
 surface as `ingress-server.ts` but per-route compiled). Cost breakdown:
-`bun bench/router-cost.ts` (`bun run bench:router`).
+`bun bench/cost/router-cost.ts` (`bun run bench:router`).