castrum 0.9.0 → 0.9.2

package/docs/INGRESS-ROUTER.md

@@ -0,0 +1,82 @@
+# `createIngressRouter` — per-route compiled ingress
+
+`createIngressRouter` (`src/ingress/router.ts`) compiles a **route table into
+dedicated native ingress instances** — one `IngressInner` per route, pruned to
+exactly that route's stages. It is the "one super solution" over the existing
+ingress core for servers with heterogeneous routes.
+
+## Why per-route compilation
+
+The plain `createIngressHandler` (see [`INGRESS.md`](./INGRESS.md)) serves every
+path from ONE global `IngressInner` configured with a **superset** of options. A
+router compiles each route's `options` into its OWN handler:
+
+- The native pipeline prunes to that route's stages (`parseCookies`,
+  `parseQuery`, `schema`, `cors`, `rateLimit`, `limits`, `requireJsonBody`…).
+- `buildHeaderPlan` produces a **per-route header plan** — routes that need no
+  headers gather ZERO headers.
+- All routes share the SAME wire format (the existing packed
+  `handle_request_packed`), the shared process-wide rate-limiter budgets, and
+  optional `warmOnCreate` pre-warming.
+
+The per-route native-compile idea is ALSO exposed standalone as the native route
+stack (`rust/ingress/native_route.rs` + the `castrum_route_*` / napi `Route`
+surface consumed by `@ignex/native`) — see [`NATIVE-ROUTE.md`](./NATIVE-ROUTE.md).
+
+## API
+
+### `RouterRouteSpec`
+
+Per-route spec: `options` (per-route `IngressHandlerOptions`), plus flags that
+wire route factories over that route's compiled handler:
+
+| Flag | Routes wired |
+|------|--------------|
+| `read` | GET + HEAD read handler |
+| `write` | POST/PUT/PATCH JSON-write handler |
+| `echo` | POST echo 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 |
+
+### `createIngressRouter(options)` → `IngressRouter`
+
+- `routes: Record<string, RouterRouteSpec>` — the route table (required).
+- `runtime?: BakedIngressRuntime` — shared hooks applied to every compiled route.
+- `getIp`, `copyBody`, `terminalStyle` — shared defaults.
+- `warmOnCreate?: boolean` — pre-warm every compiled route at construction.
+
+`IngressRouter` exposes:
+
+- `routeHandlers` — per-path compiled handlers.
+- `routes` — path → method → handler map (compatible with `Bun.serve({ routes })`
+  and `createIngressServerNode`).
+- `match(pathname)` — path matcher (`:param` / `*` dynamic routes).
+- `fetch(req, srv?)` — fetch-style dispatcher.
+- `prewarm()` — JIT-warm all compiled routes.
+
+## Example
+
+```ts
+const router = createIngressRouter({
+  warmOnCreate: true,
+  runtime: ingressMetrics?.runtime,
+  routes: {
+    '/health': { read: true, options: { parseCookies: false, parseQuery: false } },
+    '/api/users': {
+      read: true,
+      write: true,
+      options: { parseCookies: true, parseQuery: true, schema: USER_SCHEMA_BYTES },
+    },
+    '/metrics': { raw: metricsHandler(ingressMetrics) },
+  },
+})
+const server = Bun.serve({ routes: router.routes }) // or router.fetch
+```
+
+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/cost/router-cost.ts` (`bun run bench:router`).

package/docs/INGRESS.md

@@ -83,7 +83,7 @@ provides ready-made route handlers, response builders, and a `Bun.serve`
 builder — no need to hand-build responses, header templates, or error bodies.
 
 All of these are exported from the package root and are **re-exported from the
-benchmark server** (`bench/servers/ingress-server.ts`), which itself is built
+benchmark server** (`bench/http/servers/ingress-server.ts`), which itself is built
 entirely from them:
 
 ```ts
@@ -106,7 +106,7 @@ createIngressServer({
 });
 ```
 
-> **Wire format** (a contract — `bench/load.ts` depends on it):
+> **Wire format** (a contract — `bench/http/load.ts` depends on it):
 > - Success (with `emitMetadataJson: true` — the bench enables it): the body is
 >   Rust-generated `{"ok":true,"requestId":"...",...}`. With the DEFAULT
 >   `emitMetadataJson: false` the success body is **empty** (lean reads) — serve
@@ -138,6 +138,9 @@ native options as `createIngressFast` (`trustProxy`, `https`,
 | `onResponse` | `(req, result, status, requestId) => void` | — | Hook invoked after a `Response` is produced (metrics/logging) |
 | `onError` | `(req, requestId, error) => void` | — | Hook invoked when the native pipeline fails (silent 500s are otherwise invisible) |
 | `structuredLog` | `boolean` | `false` | Emit one JSON line per request/error (gated by `CASTRUM_LOG_LEVEL`) |
+| `logger` | `StructuredLogger` | — | Custom structured logger (custom stream/extra fields); implies `structuredLog: true` |
+| `maxInFlight` | `number` | `0` (unlimited) | Hard cap on concurrently borrowed zero-copy output buffers (`BufferPool.maxInFlight`); exceeding it fails requests with 500 instead of allocating unbounded temporaries |
+| `zeroCopyTimeoutMs` | `number` | `0` (disabled) | Abandonment guard (ms) for zero-copy responses: unread/cancelled bodies release their pooled buffer and close the stream |
 
 Returns an `OptimizedIngressHandler`:
 
@@ -219,8 +222,9 @@ interface BakedServer {
 
 ### `createIngressServerNode(options)` — Node.js adapter
 
-Bun remains the primary server target; `createIngressServer` is Bun-only. For
-Node.js consumers, `createIngressServerNode` serves the SAME pre-baked route
+Bun remains the primary server target. The public `createIngressServer` is
+runtime-adaptive (Bun.serve on Bun, `node:http` on Node); for pinned Node
+consumers `createIngressServerNode` serves the SAME pre-baked route
 handlers over `node:http` (sharing `buildRouteHandlers`). It returns a
 `NodeIngressServer` (`BakedServer` plus an async `ready: Promise<number>` that
 resolves to the bound port — use it with `port: 0`).
@@ -287,7 +291,7 @@ rendering).
 > (`createIngressServer`) and Node (`createIngressServerNode`). Raw handlers
 > are served for GET only and skip the ingress pipeline / OPTIONS preflight.
 > See `examples/basic-server.ts` and the bench ingress server
-> (`bench/servers/ingress-server.ts`), which wire `/metrics` + `/healthz`
+> (`bench/http/servers/ingress-server.ts`), which wire `/metrics` + `/healthz`
 > `/readyz` `/livez` end-to-end.
 
 **Tracing** — W3C trace-context helpers: `parseTraceParent(header)`,
@@ -518,6 +522,7 @@ interface SyncIngressHandler {
 
 | Code | HTTP Status | Description |
 |------|-------------|-------------|
+| `ERR_CODE_REQUEST_TIMEOUT` (-1) | 408 | Body-read deadline exceeded on a write/echo route (`bodyTimeoutMs`, default 30 s) |
 | `ERR_CODE_NONE` (0) | 200 / varies | No error |
 | `ERR_CODE_CORS_PREFLIGHT` (1) | 403 / 204 | CORS preflight rejected (or allowed → 204) |
 | `ERR_CODE_RATE_LIMITED` (2) | 429 | Rate limit exceeded |
@@ -741,5 +746,4 @@ async function* tick() {
   }
 }
 return sseResponse(tick());
-```
-}
+```

package/docs/NATIVE-ROUTE.md

@@ -0,0 +1,77 @@
+# Native route stack — the `@ignex/native` wire (route-wire v3)
+
+`rust/ingress/native_route.rs` exposes the **per-route native stack**: a route
+descriptor compiles once into a pre-baked `NativeRoute`, then each request runs
+ONE native call. It is the LIVE external wire consumed by `@ignex/native`'s
+`createNativeRoute` — a `castrum` consumer that compiles routes natively.
+
+> **History**: the old `rust/route.rs` was dead external-project wire (a THIRD
+> wire format, never bound in `src/native/ffi.ts`) and was removed in v0.9.0.
+> `native_route.rs` implements the now-live ignex contract and supersedes it.
+
+## Route-wire v3
+
+- Magic `ROUT` (0x524f5554), version 3.
+- Stage tags: `parseQuery = 0 … requireJsonBody = 5`.
+- Result layout: `[flags u32][errorCode u32]` + optional query/cookie pair
+  sections.
+
+Descriptor/stage/part tags + result layout must match `route-wire.ts` EXACTLY —
+`ROUTE_DESC_VERSION` bumps on any wire change (a mismatched compiler/addon must
+be a hard reject, never a silent misparse).
+
+## Parse semantics (LENIENT)
+
+Byte-parity with ignex's JS `queryPairs` / `cookiePairs`: malformed `%ZZ` /
+invalid-UTF-8 `%FF` pass through raw, `+` → space, `%2B` → `+`, cookies trim +
+DQUOTE-unwrap the VALUE but not the name, no cookie URL-decoding. Do NOT reuse
+the strict scalar `query_parser` for this wire.
+
+## Validation
+
+The stack validates the BODY only (via `IngressSchema`); a non-body schema in
+the descriptor is an unsupported feature → fail compile so the caller falls
+back to JS. `requireJsonBody` → 400; `validateBody` schema fail → 422;
+first-failure-wins in stage order.
+
+## Surfaces
+
+- `castrum_route_compile` / `castrum_route_run` / `castrum_route_destroy`
+  (C-ABI, needed-size convention, panic-guarded, immutable `&self` run).
+- napi `Route` class (Node / fallback path).
+- **Public castrum surface (`createNativeRoute`, `nativeRouteHandler`)**:
+  the stack is now a first-class castrum API, not just the ignex wire.
+  - `createNativeRoute(plan)` (`src/ingress/native-route.ts`) compiles a
+    route-wire v3 descriptor once and runs each frame in ONE native call —
+    `run(query, cookie, body)` / `runFrame(frame)` return the decoded verdict
+    (flags + errorCode + query/cookie pairs); `destroy()` frees the handle.
+    The pure wire helpers (`encodeRouteDescriptor`, `packRouteFrame`,
+    `decodeRouteResult`, layout constants) live in
+    `src/ingress/packing/route-wire.ts`.
+  - `nativeRouteHandler(plan, responder, opts)` (`src/ingress/routes/native.ts`)
+    wraps a compiled route as a `RouteHandler`: extracts the query substring +
+    Cookie header, runs the tiny frame, rejects 400/422 on verdict failure,
+    and hands the decoded snapshot to the responder for the 2xx.
+  - `createIngressRouter`'s `native` route spec wires it into a server (see
+    `INGRESS-ROUTER.md`). 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, 2000 connections).
+  - Trade-off (deliberate): the native stack does NOT do CORS, rate limiting,
+    security headers, IP trust, or the castrum metadata envelope — routes that
+    need those must use the full pipeline. The lean path is for routes where
+    the framework owns the response body and only needs parse + verdict.
+
+## Tests / parity
+
+- `rust/ingress/native_route.rs` unit tests + `rust/ffi/` C-ABI tests.
+- `test/unit/ingress/native-route.test.ts` (wire round-trip + lenient parity).
+- `test/unit/ingress/native-route-public.test.ts` (public surface + router
+  `native` kind).
+- External parity: ignex's `route-wire.test.ts` /
+  `packages/native/test/route.test.ts` (in the `@ignex/native` repo).
+
+> **Naming note (flux → ignex)**: the external consumer was historically called
+> `@flux/native` (castrum v0.8.0, guarded by `test/compat/flux-contract.test.ts`).
+> The current live wire is `@ignex/native`. Both names appear in changelogs;
+> `@ignex/native` is the active contract.

package/docs/REPO_MAP.md

@@ -14,14 +14,14 @@ agent editing this repo, [`AGENTS.md`](../AGENTS.md) is the agent-facing map.
 
 - A **Rust cdylib** (`castrum.<platform>-<arch>.node`, built with napi-rs,
   ALSO exporting `extern "C"` symbols for Bun's `bun:ffi` — see
-  `rust/ffi.rs`) provides the performance-critical primitives (parsers,
+  `rust/ffi/`) provides the performance-critical primitives (parsers,
   crypto, hashing, JSON, compression, and the HTTP **ingress pipeline**).
   Under Bun, `bun:ffi` is the PRIMARY transport; NAPI is the fallback
   (Node, `CASTRUM_FFI_MODE=napi`, or a failed ffi self-test).
 - **TypeScript** (`src/`) provides the ergonomic public API: the flat `rust.*`
-  FFI client, the `proven` performance surface, and the ingress layer.
+  FFI client and the ingress layer.
 - It ships benchmarks: a **CPU benchmark** (`bench.ts` → `src/bench`) and an
-  **HTTP benchmark** (`bench/run-bench.ts` + `bench/servers/*`).
+  **HTTP benchmark** (`bench/http/run-bench.ts` + `bench/http/servers/*`).
 
 Bun is the primary runtime; Node.js ≥20.3 is supported via a compiled ESM entry
 (`dist/`).
@@ -37,16 +37,16 @@ Bun is the primary runtime; Node.js ≥20.3 is supported via a compiled ESM entr
 | Build Rust addon (LOCAL max perf) | `bun run build:perf` | x86-64-v3 + AVX2 — **never for publish** |
 | Build Rust addon (debug) | `bun run build:debug` | |
 | Build compiled JS entry (Node) | `bun run build:js` | bundle + types → `dist/` (gitignored) |
-| TS unit tests | `bun test` | ~540 tests, `test/unit/**` |
+| TS unit tests | `bun test` | ~760 tests, `test/unit/**` |
 | Rust unit tests | `bun run test:rust` | `cargo test`, ~440 tests |
 | Node smoke tests | `bun run test:node` | explicit `.mjs` paths (Node 24 rejects dir arg) |
 | Installed-tarball e2e | `bun run verify:install` | pack → install → import from `node_modules` |
 | Typecheck | `bun run typecheck` | `bunx tsc --noEmit` (only `index.ts`, `bench.ts`, `src/`) |
 | CPU benchmark + correctness | `bun run check` | == `bun bench.ts`; writes `bench/results/cpu/` |
-| Proven-surface audit | `bun run check:proven[:fail]` | `:fail` gates CI on regressions |
-| Performance JSDoc | `bun run check:annotate` | rewrites perf JSDoc from CPU report; `--dry-run` previews |
 | HTTP bench (all servers) | `bun run bench:http` | |
 | HTTP smoke (fast sanity) | `bun run bench:http:smoke` | **the wire-format guard** (CI-gated) |
+| FFI transport benches | `bun run bench:ffi` / `bench:ffi:load` / `bench:ffi:public` / `bench:ffi:workers` / `bench:margin` | `bench/ffi/` |
+| Ingress cost benches | `bun run bench:ingress-cost` / `bench:ingress-cost:post` / `bench:router` | `bench/cost/` |
 | Startup bench | `bun run bench:startup` | import + first-call timing |
 | JS lint (Biome) | `bun run lint` / `lint:fix` | `bunx biome check [--write] .` |
 | JS format (Biome) | `bun run format` | `bunx biome format --write .` |
@@ -62,7 +62,7 @@ Bun is the primary runtime; Node.js ≥20.3 is supported via a compiled ESM entr
 ### Source (what you edit)
 
 ```
-index.ts                  Package entry (Bun). Re-exports src/rust-ffi, proven, shared helpers, src/ingress.
+index.ts                  Package entry (Bun). Re-exports src/rust-ffi, shared helpers, src/ingress.
 bench.ts                  CPU benchmark entry point → src/bench/run.ts.
 
 examples/                 Runnable sample app (basic-server.ts + README) — see also README Quick Start.
@@ -70,43 +70,75 @@ examples/                 Runnable sample app (basic-server.ts + README) — see
 
 src/
   native/                 The native transport layer: bun:ffi (primary on Bun) + NAPI fallback.
-    types.ts              NativeAddon interface + every instance type (mirrors index.d.ts).
+    types.ts              NativeAddon module-surface interface (mirrors index.d.ts).
+    types/instances.ts    Per-class INSTANCE types (Ingress, SchemaValidator, JwtSigner, ...) + result types.
     loader.ts             Addon path resolution (multi-root) + getAddon()/lazyAddon().
-    ffi.ts                bun:ffi C-ABI bindings (Bun-only): lazy bind + bind-time self-test,
-                          CASTRUM_FFI_MODE gating, castrum_ingress_layout blob for constants.ts.
+    ffi.ts                bun:ffi C-ABI transport core (Bun-only): mode resolution, buffer/buffer_length
+                          probe, bind() orchestration (self-test + CASTRUM_FFI_MODE gating + napi fallback).
+    ffi/                  Decomposed bind surface: types.ts (BunFFI interface) + constants.ts +
+                          selftest.ts (thin aggregator) + build.ts (orchestrator) +
+                          build/{util,codecs,compress,parse,instances}.ts — per-domain method builders
+                          EACH with its self-test* function, so a new castrum_* symbol is bound AND
+                          self-tested in one domain file.
     index.ts              Barrel.
+  runtime/                THE RUNTIME ADAPTER seam (Bun/Node) — selected once at load.
+    detect.ts             Cached runtime detection — the ONLY place `typeof Bun` is checked.
+    types.ts              RuntimeAdapter contract (codec/uuid/env/builtins/transport/server/websocket).
+    codec.ts              Runtime-native UTF-8 codec (Bun transfer vs TextEncoder/Decoder).
+    uuid.ts               uuidv7 (Bun.randomUUIDv7 vs crypto.randomUUID).
+    builtins.ts           BUN_WINS delegation registry (single source; `has(op)`).
+    transport.ts          bun:ffi-first `resolve(op)` + ffi/napi surfaces (lazy bind).
+    native.ts             FFI-facing seam (codec/uuid/env/builtins/transport) — imported by rust-ffi.
+    server.ts             createIngressServer: Bun.serve on Bun, node:http on Node.
+    websocket.ts          101 upgrade on Bun; clear Bun-only error on Node.
+    index.ts              FULL adapter `runtime` (native + server + websocket) — for the public API.
   rust-ffi/               The flat `rust.*` FFI client (TS wrappers over the addon).
     client.ts             createRust() factory + the default `rust` instance + configure().
-    scalar/ / text.ts / batch.ts / packed.ts   namespaces (buildScalar, buildText, ...).
-    context.ts            Per-instance state (caches, rayon-pool bookkeeping).
+    scalar/ / text.ts / packed.ts   namespaces (buildScalar, buildText, ...).
+    batch/                Array-of-bytes batch namespace: types.ts (RustBatch interface) + build.ts (impl) + index.ts.
+    context.ts            Per-instance state (caches, rayon-pool bookkeeping, runtime seam).
     options.ts            RustOptions + rayon-thread resolution + coercion helpers.
     addon.ts              The single shared lazy addon proxy.
-    proven.ts             `proven` client — the FULL rust.* surface, annotated (same object as `rust`).
     index.ts              Barrel (exports rust, createRust, types).
   shared/                 Cross-cutting helpers.
-    runtime.ts            THE ONLY place `typeof Bun` is checked (isBun/isNode).
-    bytes.ts              Shared TextEncoder/Decoder singletons + toPlainBuffer.
-    packed.ts             Packed-wire unpackers (unpackU32Array, packBatch, readPairsPacked, ...).
+    runtime.ts            Facade over src/runtime/detect.ts (isBun/isNode — cached).
+    codec.ts              Facade over src/runtime/codec.ts.
+    uuid.ts               Facade over src/runtime/uuid.ts.
+    bytes.ts              encoder/decoder (Uint8Array|string union normalization) + toPlainBuffer.
+    packed/               Packed wire-format helpers (split from the old packed.ts monolith).
+      wire.ts             PURE byte encode/decode (u32/bitset/i64/byte-results/multipart, pairs, pack-scratch) — no addon.
+      schema.ts           SchemaValidator alias + schemaValidateBatch/Count.
+      parsers.ts          lazy-addon string parsers (parseQueryString/parseCookieHeader/parseFormBody).
+      index.ts            Barrel (existing `../shared/packed` imports unchanged).
     request-id.ts         Zero-alloc request-id generator (both ingress paths).
     buffer-pool.ts        Generic reusable byte-buffer pool (pooled ingress output).
     response.ts           pooledBodyResponse (releases the pool on body consume).
     log.ts                createStructuredLogger (CASTRUM_LOG_LEVEL-gated JSON lines).
-    proven.ts             PROVEN_SURFACE registry (PURE DATA — no addon imports).
+    metrics.ts            Zero-dep metrics registry (counters/gauges/histograms + Prometheus render).
+    trace.ts              W3C traceparent/span-id helpers.
+    env.ts                Centralized env-var resolution (CASTRUM_* + NAPI_RS_NATIVE_LIBRARY_PATH).
+    proven.ts             Baked benchmark-proven op selection (PROVEN_SELECTION — pure data).
+  loader/                 Higher-order-function data loader (HFC) over the curated op set.
+    index.ts              Dispatch core + factory (scalar/bulk dispatch, coalescing, LRU cache).
+    ops.ts                Op registry (LOADER_OPS) + type tower; state.ts / cost.ts / batch.ts / types.ts.
   ingress/                The HTTP ingress pipeline (two paths — see §4.2).
     fast.ts               PATH 1: createIngressFast (packed-input via handleRequestPacked).
     handlers.ts           PATH 2: createIngressHandler (JS-packs the frame via IngressInputPacker
-                          + gatherRawHeadersPacked → handleRequestPacked).
-    index.ts              Barrel + createIngress / createIngressSync convenience factories.
+                          + gatherRawHeadersPacked → handleRequestPacked); response builders
+                          extracted to response/baked-response.ts.
+    index.ts              Pure public barrel (all re-exports).
+    sync.ts               createIngressSync / createIngress convenience factories (path 1 wrapper).
     shared.ts             JS constants + buildHeaderPlan + assertSyncCallback (shared by both paths).
     constants.ts          Binary-layout constants read from Rust at runtime (SINGLE SOURCE).
     status.ts / errors.ts / options.ts / types.ts / body.ts / context.ts
     packing/              header-packing.ts, input-packer.ts, gather-raw-headers.ts
-    headers/              cors.ts, hsts.ts, fast-templates.ts, baked-templates.ts
+    headers/              cors.ts, hsts.ts, security.ts (baked security merge), fast-templates.ts, baked-templates.ts
     decode/               fast-result.ts, baked-result.ts   (TWO decoders — see §4.2)
-    response/             terminal.ts, error-bodies.ts
-    routes/               read/head/json-write/echo/fallback factories + common.ts
+    response/             terminal.ts, error-bodies.ts, baked-response.ts (pre-baked response builders)
+    routes/               read/head/json-write/echo/fallback factories + common.ts + responder.ts
     server.ts             createIngressServer (Bun.serve) + buildRouteHandlers + gracefulShutdown.
     server-node.ts        createIngressServerNode (node:http adapter, same route handlers).
+    path-matcher.ts       buildPathMatcher + PathMatch + safeDecode (shared by server-node + router).
   integration/            Framework integration (wraps path 2 — createIngressHandler).
     pipeline.ts           createPipeline (framework-agnostic request stage for Hono/Elysia/Bun.serve).
     websocket.ts          createWebSocketUpgrade (RFC 6455 101 handshake + subprotocol).
@@ -119,20 +151,33 @@ src/
 ```
 rust/                     ONE cdylib crate (Cargo [lib] → lib.rs).
   lib.rs                  Declaration hub + module map + crate docs.
-  util/                   Shared infrastructure: bytes, packed, batch (+batch_core), threadpool, validation.
+  selection.rs            Rust-side op selection metadata (mirrors src/selection.json).
+  util/                   Shared infrastructure: bytes, packed, batch/ (api.rs + core.rs + tests.rs),
+                          threadpool, validation.
   http/                   HTTP wire formats & parsing: headers, method, http/cookie/query parsers,
-                          form, media_type, url_codec, url_join, etag, accept, mime_lookup, multipart.
-  crypto/                 Auth & hashing: hmac_sha256, cookie_sign, csrf, jwt, aead, argon2,
-                          base64, hashing (fnv/crc32/xxh3), random_token.
-  json/                   JSON & schema: json_ops, json_ser, json_patch_ops, json_schema (napi),
+                          form, media_type, url_codec, url_join, http_date, etag, accept,
+                          mime_lookup, multipart.
+  crypto/                 Auth & hashing: hmac_sha256, cookie_sign, csrf, jwt/ (token.rs + api.rs +
+                          tests.rs), aead, argon2, base64, ed25519, hashing (fnv/crc32/xxh3),
+                          random_token.
+  json/                   JSON & schema: json_ops, json_ser, json/patch/ (pointer.rs + ops.rs +
+                          engine.rs + api.rs + tests.rs), json_schema (napi),
                           fast_schema/ (zero-DOM engine — pure, no napi).
   payload/                Output & streaming: compress, sse, ws_frames, websocket, template.
-  ingress/                THE ingress pipeline: mod.rs (napi boundary), pipeline.rs (core 8-stage),
-                          options/time/packed, cors, proxy, ip_trust, rate_limit, terminal,
-                          output.rs (single numeric layout source), ingress_constants.rs (napi projection).
-  ffi.rs                  #[no_mangle] extern "C" exports (45 castrum_* symbols) for Bun's bun:ffi
+  ingress/                THE ingress pipeline: api.rs (Ingress/IngressInner napi class) + mod.rs
+                          (declaration hub), pipeline.rs (core 8-stage), native_route.rs (per-route
+                          native stack), options/time/packed, cors, proxy, ip_trust, rate_limit,
+                          terminal, output.rs (single numeric layout source),
+                          ingress_constants.rs (napi projection).
+  ffi/                    #[no_mangle] extern "C" exports (85 castrum_* symbols — 77 direct + 4
+                          validator_c_abi! + 4 compress_to_out!; parity guarded by
+                          test/unit/native/ffi-symbol-parity.test.ts) for Bun's bun:ffi
                           primary transport, incl. castrum_ingress_layout (the layout blob).
-  unit_tests.rs / test_support.rs   Cross-module Rust test suites.
+                          mod.rs (module map) + util.rs (panic_guard / HMAC cache / cstring helpers)
+                          + per-domain wrappers (hashing/validators/crypto/jwt/http/payload/json/
+                          rate_limit/ingress/route/probe) + tests.rs.
+  panic_safety.rs / test_support.rs   Cross-module fuzz + shared #[cfg(test)] helpers.
+  proptest_suite.rs      Property-based adversarial-parser tests (dev-dep proptest).
 ```
 
 ### Generated / ignored (do NOT edit)
@@ -142,7 +187,7 @@ rust/                     ONE cdylib crate (Cargo [lib] → lib.rs).
 | `dist/` | Compiled ESM entry + types for Node | Built by `build:js`; gitignored |
 | `index.js` / `index.d.ts` | NAPI-RS generated loader/declarations | Regenerated by `napi build`; gitignored |
 | `castrum.<platform>-<arch>.node` | The native addon binary | Built locally; gitignored |
-| `bench/results/` | Bench reports (cpu/, http/) | Generated; gitignored |
+| `bench/results/` | Bench reports (cpu/, per-server http/, ffi-margin/, router/, startup/, autocannon/) | Generated; gitignored |
 | `target/` | Cargo build output | gitignored |
 | `node_modules/` | Deps | gitignored |
 | `artifacts/` | CI publish staging dir | gitignored |
@@ -154,7 +199,7 @@ rust/                     ONE cdylib crate (Cargo [lib] → lib.rs).
 ### 4.1 Constants never drift (single numeric source)
 `rust/ingress/output.rs` defines every ingress layout constant once → projected
 to JS two ways: `rust/ingress/ingress_constants.rs` via `#[napi] const` (NAPI)
-AND `rust/ffi.rs` `IngressLayout` via `castrum_ingress_layout` (C ABI, primary
+AND `rust/ffi/` `IngressLayout` via `castrum_ingress_layout` (C ABI, primary
 on Bun) → `src/ingress/constants.ts` reads them at runtime (ffi blob on Bun,
 napi on Node). Drift is pinned by the Rust unit test
 `ingress_layout_c_abi_matches_output_source` and the bun:ffi bind-time
@@ -173,7 +218,7 @@ self-test. **Never hardcode a layout value** — if you change the layout, chang
    `{"ok":true,...,"requestId":...}` (success) / `{"ok":false,"error":{code,
    message}}` (errors) with `ratelimit-*` headers.
 
-These wire formats are a **benchmark contract** (`bench/load.ts` validates
+These wire formats are a **benchmark contract** (`bench/http/load.ts` validates
 them) — they are intentionally NOT unified. The two decoders
 (`decode/fast-result.ts` vs `decode/baked-result.ts`) and the two header-template
 builders (`headers/fast-templates.ts` vs `headers/baked-templates.ts`) exist for
@@ -185,22 +230,22 @@ this reason. **Shared between both paths**: `generateRequestId`
 - `src/native/loader.ts` resolves the `.node` from multiple roots so it works
   from both the source layout (`src/…`) and the bundled layout (`dist/…`).
   Honors `CASTRUM_NATIVE_LIBRARY_PATH` / `NAPI_RS_NATIVE_LIBRARY_PATH`.
-- Runtime detection lives **only** in `src/shared/runtime.ts`
-  (`isBun`/`isNode`). `createIngressServer` is Bun-only; Node users use
-  `createIngressServerNode` (same route handlers via `buildRouteHandlers`).
+- Runtime detection lives **only** in `src/runtime/detect.ts` (resolved once at
+  load; `src/shared/runtime.ts` is a thin facade). The public
+  `createIngressServer` (via the adapter's `server`) picks `Bun.serve` on Bun
+  and the `node:http` backend on Node; `createIngressServerNode` stays for
+  pinned Node users (same route handlers via `buildRouteHandlers`).
 - ⚠️ `src/ingress/constants.ts` is the **one module that dlopens the addon at
   import time** (its constants are needed as soon as ingress is imported).
   Everything else is lazy.
 
-### 4.4 The `proven` performance surface
-`src/shared/proven.ts` (`PROVEN_SURFACE`) is the single source of truth for the
-per-function performance classifications. It is **pure data** (no addon
-imports) so `scripts/check-proven.ts` can audit it without dlopening.
-`src/rust-ffi/proven.ts` exposes the FULL `rust.*` surface (nothing is
-filtered); each function's JSDoc carries its measured performance vs the JS
-baseline, written by `scripts/annotate-performance.ts` (`bun run check:annotate`)
-and marked `@deprecated` when slower. `bun run check:proven:fail` (CI) audits
-the registry against the CPU benchmark report on a **release** build.
+### 4.4 The runtime adapter
+`src/runtime/` is the single seam for every Bun-vs-Node and transport decision
+(detection, codec, uuid, env, the BUN_WINS built-in delegation, the bun:ffi-vs-
+napi transport, the ingress server backend, websocket) — selected ONCE at
+module load. The FFI layer imports the seam (`src/runtime/native.ts`); the
+public API imports the full `runtime` (`src/runtime/index.ts`). No
+`isBun()` / `getBunFFI()` branches in builders.
 
 ### 4.5 Pooled output buffers (path 2)
 `createIngressHandler` owns a `BufferPool` (`src/shared/buffer-pool.ts`) sized
@@ -217,16 +262,19 @@ consumed.
 
 ## 5. Testing & benchmarks
 
-- **TS**: `bun test` → `test/unit/**` (`ingress/`, `shared/`, `features/`).
+- **TS**: `bun test` → `test/unit/**` (`native/`, `rust-ffi/`, `contract/`,
+  `ingress/`, `shared/`, `integration/`) + `test/compat/` + `test/property/`.
+  See `test/README.md` for the intended split.
 - **Rust**: `cargo test` → per-module `#[cfg(test)] mod tests` + cross-module
-  `rust/unit_tests.rs`.
+  `rust/panic_safety.rs` (fuzz) + `rust/proptest_suite.rs`.
 - **Node**: `test/integration/node-smoke.test.mjs` + `node-enterprise.test.mjs`
   via `node --test` (run with `bun run test:node`).
 - **CPU bench**: `bun run check` (correctness checks + comparisons). Sub-µs ops
   are batched (`CASTRUM_BENCH_BATCH_SIZE`). Report → `bench/results/cpu/`.
-- **HTTP bench**: `bench/run-bench.ts` + `bench/load.ts` (load generator that
-  validates response SHAPE) + `bench/servers/{bun,elysia,ingress}-server.ts`.
-  `bench:http:smoke` is the fast CI wire-format gate.
+- **HTTP bench**: `bench/http/run-bench.ts` + `bench/http/load.ts` (load generator that
+  validates response SHAPE) + `bench/http/servers/{bun,elysia,ingress,router}-server.ts`.
+  `bench:http:smoke` is the fast CI wire-format gate. FFI-transport benches live in
+  `bench/ffi/`; per-request cost benches in `bench/cost/` (see `bench/README.md`).
 
 ---
 
@@ -251,9 +299,11 @@ consumed.
 | Doc | Purpose |
 |-----|---------|
 | [`GETTING_STARTED.md`](./GETTING_STARTED.md) | Beginner tutorial (intern-friendly) |
+| [`API.md`](./API.md) | The complete public API reference |
+| [`CASE_STUDY.md`](./CASE_STUDY.md) | Data-driven case study: how castrum was built and measured |
 | [`ARCHITECTURE.md`](./ARCHITECTURE.md) | Deep-dive: modules, data flow, output layout, memory, concurrency |
 | [`INGRESS.md`](./INGRESS.md) | The pre-baked ingress API + route factories + servers |
 | [`BENCHMARKS.md`](./BENCHMARKS.md) | Benchmark scenarios, report format, how to run |
 | [`ENVIRONMENT.md`](./ENVIRONMENT.md) | All `CASTRUM_*` env vars (+ legacy aliases) |
 | [`AGENTS.md`](../AGENTS.md) | AI-agent editing guidance (commands, constraints, gotchas) |
-| `README.md` | Public-facing quick start + API reference |
+| `README.md` | Public-facing overview + quick start |

package/docs/adr/0001-two-wire-formats.md

@@ -20,7 +20,7 @@ They also use separate result decoders (`FastIngressResult` vs
 
 ## Decision
 
-**Do not unify them.** The HTTP benchmark load generator (`bench/load.ts`)
+**Do not unify them.** The HTTP benchmark load generator (`bench/http/load.ts`)
 requires `ok === true` + `requestId: string` on success and `error.code` /
 `error.message` on errors — i.e. path 2's format. The two formats are a
 **benchmark contract**: the benchmark server uses path 2, and changing its

package/docs/adr/0003-bun-builtins-delegation.md

@@ -17,7 +17,7 @@ Every overlapping op is **benchmarked against its Bun built-in** before it is
 built, kept, or delegated. Results live in
 `docs/bun-builtins-decision-matrix.md`. Rules:
 
-1. **Delegate to Bun** at the `@flux/native` wrapper layer where Bun wins
+1. **Delegate to Bun** at the selection/delegation layer where Bun wins
    clearly: non-crypto hashing (`Bun.hash.crc32` ~3x, `xxHash3` ~4x),
    gzip (`Bun.gzipSync`/`gunzipSync`), `Bun.randomUUIDv7` (~2x), HMAC
    (`Bun.CryptoHasher` ~1.2x).
@@ -31,10 +31,11 @@ built, kept, or delegated. Results live in
 
 - New `rust.*` primitives ship with a Bun-built-in baseline + decision-matrix
   entry (`xxh3`, `passwordHashBcrypt`/`verifyBcrypt`, `pbkdf2Sha256`).
-- `PROVEN_SURFACE` classifications reflect the Bun/JS baseline honestly
-  (e.g. `xxh3` is `not-competitive` vs `Bun.hash.xxHash3`).
-- Diagnostic benchmark tasks use `diag:` names so they never perturb the
-  `check:proven` audit.
+- The Bun/JS baselines are recorded honestly in the decision matrix
+  (e.g. `xxh3` is measured `Bun.hash.xxHash3` ~4x faster — the public
+  `rust.xxh3` delegates to it under Bun via the runtime adapter's `builtins`).
+- Diagnostic benchmark tasks use `diag:` names so they are never mistaken for
+  shipped-op `native:`/`rust:` comparisons.
 
 ## See also
 

package/docs/ai/LOCAL_DEV.md

@@ -0,0 +1,81 @@
+# Local Development with the Core Projects — `bun link`
+
+> **Scope**: maintainers and AI agents working across the IgnEX core stack.
+> Application developers consume published versions from npm and do **not**
+> need this file.
+
+## Why
+
+The IgnEX core packages live side-by-side, one directory back from this repo,
+in `/home/adeel/poc/`. When a change in this repo must be tested against the
+local source of a core project (or a core change must be tested against this
+repo), use `bun link` so the consumer resolves the local directory instead of
+the npm registry. This is the supported Bun ≥ 1.4 (Rust-based runtime)
+local-development mechanism
+([`bun link` docs](https://bun.com/docs/cli/link),
+[bun.com/blog/bun-v1.4](https://bun.com/blog/bun-v1.4)).
+
+This workflow is **only for maintainers and AI agents working with the core
+projects**. CI and release pipelines always resolve from the registry; local
+links are a development-only convenience.
+
+## Core packages (one directory back)
+
+| Repo (`/home/adeel/poc/`) | Package(s) | `bun link` name |
+| --- | --- | --- |
+| `ignus` — ignex monorepo, workspaces `packages/*` | `@ignex/core`, `@ignex/cli`, `@ignex/compiler`, `@ignex/native`, `@ignex/shared`, `@ignex/mcp`, `@ignex/app`, `create-ignex` | run `bun link` inside each package dir |
+| `bun-rust-runtime-bench` | `castrum` (Rust addon `castrum.<platform>-<arch>.node`) | `castrum` |
+| `ignex-mongodb` | `@ignex/ninox` | `@ignex/ninox` |
+| `ignex-nova` | `@ignex/nova` | `@ignex/nova` |
+
+Known cross-repo edges (verify with `grep` in `package.json` before assuming):
+
+- `@ignex/native` (in `ignus/packages/native`) depends on `castrum` — link
+  `castrum` there when changing the addon wire (`createNativeRoute`).
+- `@ignex/core` (in `ignus/packages/core`) optionally depends on
+  `@ignex/nova`; `@ignex/app` depends on `@ignex/core`, `@ignex/cli`, and
+  `@ignex/ninox`.
+
+## How to link
+
+```bash
+# 1. Register the core package (once per machine, from the core repo):
+cd /home/adeel/poc/ignex-mongodb
+bun link            # → Success! Registered "@ignex/ninox"
+
+# 2. Link it into the consumer project:
+cd /home/adeel/poc/ignex-app
+bun link @ignex/ninox              # symlinks node_modules/@ignex/ninox → ../ignex-mongodb
+bun link @ignex/ninox --save       # also writes "link:@ignex/ninox" into package.json deps
+```
+
+- `bun link` (no args) in a package directory registers that package globally
+  for this user.
+- `bun link <name>` in a consumer creates a symlink in the consumer's
+  `node_modules` pointing at the registered directory. `--save` additionally
+  records `"<name>": "link:<name>"` in `package.json` dependencies.
+- Unregister a package: `bun unlink` from the core repo dir.
+- Return to registry versions: remove the `link:` entry (or `bun unlink
+  <name>` in the consumer) and `bun install`.
+
+## Rust-core caveats (castrum & @ignex/nova)
+
+Both `castrum` and `@ignex/nova` ship a Rust cdylib. After changing Rust
+source, rebuild the addon **before** linking or using:
+
+- `castrum`: `bun run build` (release `napi build`) or `bun run build:debug`.
+  Under Bun the addon is also called through `bun:ffi` from the same cdylib.
+- `@ignex/nova`: `bun run build:rust`
+  (`cargo build --release --manifest-path rust/Cargo.toml`), or rely on
+  `prepack`/`prebuild` to stage `prebuilds/<platform>-<arch>/`.
+
+A stale `.node`/`.so` silently serves old behavior — rebuild, then re-test.
+`@ignex/nova` additionally fails its bind-time self-test on schema/wire-version
+mismatch (`IGNEX_FFI_PATH` can point at a specific build); `castrum` falls back
+to the napi transport when the `bun:ffi` self-test fails.
+
+## Never publish from a linked tree
+
+Publishing a consumer whose dependencies are `link:` entries ships symlinks,
+not packages. Releases always run against registry versions (`prepublishOnly` /
+CI re-verify with a clean install). Keep `bun link` strictly local.