castrum 0.7.0 → 0.9.1

package/docs/ARCHITECTURE.md

@@ -0,0 +1,507 @@
+# Architecture Guide
+
+## Overview
+
+castrum is a **hybrid Bun + Rust** runtime benchmark package that provides high-performance backend primitives through a native bridge with **two transports**: `bun:ffi` (the C-ABI fast path, PRIMARY under Bun) and NAPI via napi-rs (the fallback — Node, forced `CASTRUM_FFI_MODE=napi`, or a failed ffi self-test). The architecture is designed for zero-copy data transfer between TypeScript and Rust, with batching support for high-throughput scenarios.
+
+---
+
+## Two-Layer Architecture
+
+```
+┌─────────────────────────────────────────────────────────────┐
+│                    TypeScript Layer                          │
+│                                                             │
+│  Purpose: API ergonomics, runtime safety, async handling    │
+│  Runtime: Bun (JavaScriptCore)                               │
+│  Pattern: Factory functions, lazy evaluation, batching       │
+└──────────↕ Native Bridge: bun:ffi (Bun, primary) + NAPI (fallback) ↕──────────┘
+│                                                             │
+│                    Rust Layer (cdylib)                       │
+│                                                             │
+│  Purpose: Performance-critical computation, I/O handling     │
+│  Allocator: mimalloc (global)                                │
+│  Pattern: Stateless functions, pre-allocated buffers         │
+└─────────────────────────────────────────────────────────────┘
+```
+
+### Native Bridge (two transports)
+
+The bridge between TypeScript and Rust has **two transports**, both loading the SAME
+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
+  `validator_c_abi!` + 4 `compress_to_out!`, parity guarded by
+  `test/unit/features/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`).
+- **NAPI (napi-rs v3) — the fallback** — used under Node.js, when `bun:ffi` is
+  unavailable (self-test failure, `CASTRUM_FFI_MODE=napi`), and for surfaces with no
+  C-ABI export. Since Phase 6 the compiled-once instances are NOT napi-only — their
+  hot per-call ops route through the C-ABI via an opaque-`usize` handle
+  (`conditional_is_not_modified`, `media_type_matcher_matches`,
+  `accept_negotiator_negotiate`, `jwt_signer_sign`/`_verify`, `template_render`,
+  `schema_validator_validate`, `rate_limiter_check*`, `url_builder_resolve`), and
+  `jwtVerify` has `castrum_jwt_verify`. Still napi-only: `rust.batch.*` /
+  `rust.packed.*`, `text.*`, and the DOM `jsonParse` (only `castrum_json_parse_packed`
+  exists).
+
+Shared characteristics:
+
+- **Zero-copy buffer sharing**: `Uint8Array` objects are passed by reference to Rust, avoiding serialization
+- **Synchronous calls**: All functions are synchronous, running on the main JS thread
+- **Thread pool**: Rayon is available for parallel CPU-bound work
+
+### Dual-binary CPU-detect (x86-64-v3 SIMD variant)
+
+On `linux-x64` the package ships a second artifact, `castrum.linux-x64-v3-gnu.node`,
+built with `-C target-cpu=x86-64-v3 -C target-feature=+avx2,+bmi2,+fma,+sse4.2`
+(`scripts/build-v3.sh`, package script `build:v3`; `build:all` builds both). The
+loader (`src/native/loader.ts`) picks the v3 variant at runtime when the host
+CPU exposes AVX2+BMI2+FMA+SSE4.2 (read from `/proc/cpuinfo`), falling back to the
+baseline artifact otherwise — a v3 binary dlopened on an unsupported CPU would
+SIGILL (not catchable from JS), so detection is conservative and requires ALL
+four flags. The v3 variant is OPTIONAL (an absent v3 file resolves to baseline),
+so `build:v3` is never a hard publish requirement.
+
+---
+
+## Module Architecture
+
+> **Canonical tree**: [`REPO_MAP.md`](./REPO_MAP.md) is the single-source module map
+> (src/ + rust/ trees, kept in sync). The trees below are the deep-dive annotations.
+
+### Rust Modules
+
+One cdylib crate (`Cargo [lib] → rust/lib.rs`) decomposed into domain folders.
+`lib.rs` is a declaration hub with a module map; `util/mod.rs` re-exports the
+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
+│
+├── util/                  ── Shared infrastructure (mod.rs re-exports crate::util::*)
+│   ├── bytes.rs           ── byte primitives (word-compare, hex, %XX decode, cookie_pairs)
+│   ├── packed.rs          ── zero-alloc packed iterators + byte writers (VecWriter, PackedIter)
+│   ├── batch.rs           ── aggregate packed batch napi APIs (bitset/count/sum/direct)
+│   ├── batch_core.rs      ── generic rayon-parallel batch helpers
+│   ├── threadpool.rs      ── rayon pool init + parallelism heuristic
+│   └── validation.rs      ── email / UUID / IPv4 / IPv6 validators
+│
+├── http/                  ── HTTP wire formats & parsing
+│   ├── headers.rs         ── zero-alloc packed-header parser (HeaderRefs)
+│   ├── method.rs          ── HTTP method classification
+│   ├── http_parser.rs     ── HTTP request line + headers → packed request (httparse)
+│   ├── query_parser.rs    ── query/form string → packed pairs
+│   ├── cookie_parser.rs   ── cookie header → packed pairs
+│   ├── form.rs            ── x-www-form-urlencoded parser + FormParser instance
+│   ├── media_type.rs      ── Content-Type parser + MediaTypeParser / MediaTypeMatcher
+│   ├── url_codec.rs       ── percent-encoding encode/decode
+│   ├── url_join.rs        ── RFC 3986 url_resolve + query builder (UrlBuilder)
+│   ├── etag.rs            ── etag / http_date + ConditionalRequest (304)
+│   ├── accept.rs          ── Accept-Encoding negotiation (AcceptNegotiator)
+│   ├── mime_lookup.rs     ── extension → MIME (phf table)
+│   └── multipart.rs       ── multipart/form-data parser (+ limits)
+│
+├── crypto/                ── Auth & hashing (compiled-once instances)
+│   ├── hmac_sha256.rs     ── HMAC-SHA256 (+ HmacSigner)
+│   ├── cookie_sign.rs     ── signed cookies (CookieSigner)
+│   ├── csrf.rs            ── CSRF tokens (CsrfProtector)
+│   ├── jwt.rs             ── HS256 JWT sign/verify (+ JwtSigner, precomputed header)
+│   ├── aead.rs            ── AES-256-GCM / chacha20-poly1305 (+ AeadCipher)
+│   ├── argon2.rs          ── argon2id password hashing (+ Argon2Hasher)
+│   ├── base64.rs          ── base64/base64url/hex codecs (+ Base64Codec)
+│   ├── hashing.rs         ── FNV-1a / XXH3 / crc32
+│   └── random_token.rs    ── random hex tokens
+│
+├── json/                  ── JSON & schema
+│   ├── json_ops.rs        ── zero-DOM validate/sum + DOM parse (sonic Value → JS)
+│   ├── napi_marshal.rs    ── sonic_rs::Value → napi walker (sonic_value_to_js, napi
+│   │                        serde-json Number parity) + sonic_values_equal
+│   │                        (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)
+│   ├── 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
+│
+├── payload/               ── Output & streaming
+│   ├── compress.rs        ── gzip (zlib-rs) + brotli + batch
+│   ├── sse.rs             ── SSE event framing + batch
+│   ├── ws_frames.rs       ── RFC 6455 frame codec + batch
+│   ├── websocket.rs       ── WebSocket accept-key
+│   └── template.rs        ── minijinja rendering (TemplateRenderer) + batch
+│
+└── ingress/               ── The ingress pipeline
+    ├── mod.rs             ── thin napi boundary: Ingress class + entry points
+    ├── pipeline.rs        ── core 8-stage pipeline (IngressInner::handle_packed,
+    │                        write_body_sections, BodySections, IngressSchema)
+    ├── tests.rs           ── ingress unit tests
+    ├── options.rs         ── napi option structs + Limits
+    ├── time.rs            ── monotonic/wall-clock helpers
+    ├── packed.rs          ── packed-input readers + builder
+    ├── cors.rs            ── CORS engine (origin matching, preflight evaluation)
+    ├── proxy.rs           ── HTTPS detection, URL extraction
+    ├── ip_trust.rs        ── IP resolution (X-Forwarded-For, X-Real-IP)
+    ├── rate_limit.rs      ── token-bucket rate limiter (per-IP keyed)
+    ├── terminal.rs        ── terminal response builders (errors)
+    ├── output.rs          ── SINGLE NUMERIC SOURCE for the output-buffer layout
+    └── ingress_constants.rs ── NAPI projection of output.rs (no drift)
+```
+
+### TypeScript Modules
+
+```
+src/
+├── ingress/               ── HTTP ingress pipeline (TS layer), decomposed by task
+│   ├── index.ts           ── Public API barrel + async factory
+│   ├── fast.ts            ── Thin: createIngressFast (packed input) + re-exports
+│   ├── handlers.ts        ── Thin: createIngressHandler (packs frame in JS → handleRequestPacked) + response builders
+│   ├── server.ts          ── createIngressServer (Bun.serve builder) + buildRouteHandlers + gracefulShutdown
+│   ├── server-node.ts     ── createIngressServerNode (node:http adapter, same route handlers; the runtime adapter picks the backend)
+│   ├── constants.ts       ── Layout constants (from Rust NAPI)
+│   ├── shared.ts          ── JS constants shared by both paths
+│   ├── status.ts          ── Status normalization helpers (both paths)
+│   ├── errors.ts          ── Fast-path error-code name/message mapping
+│   ├── options.ts         ── IngressFast option types + validation + trustProxy warning
+│   ├── types.ts           ── Public API types
+│   ├── body.ts            ── Streaming request-body reader (size guard + bodyTimeoutMs)
+│   ├── context.ts         ── Result snapshot + synthetic/error context builders
+│   ├── packing/           ── header-packing, input-packer, gather-raw-headers
+│   ├── headers/           ── cors, hsts, fast-templates, baked-templates
+│   ├── decode/            ── fast-result, baked-result (two decoders, NOT unified)
+│   ├── response/          ── terminal (fast), error-bodies (pre-baked)
+│   └── routes/            ── read/head/json-write/echo/fallback factories
+│
+├── shared/
+│   ├── runtime.ts         ── facade over src/runtime/detect.ts (isBun/isNode — cached)
+│   ├── codec.ts           ── facade over src/runtime/codec.ts (Bun-native UTF-8 codec)
+│   ├── uuid.ts            ── facade over src/runtime/uuid.ts
+│   ├── log.ts             ── createStructuredLogger (CASTRUM_LOG_LEVEL-gated JSON lines)
+│   ├── request-id.ts      ── zero-alloc request ID generator
+│   ├── buffer-pool.ts     ── reusable output-buffer pool
+│   ├── response.ts        ── pooledBodyResponse (zero-copy response)
+│   ├── bytes.ts           ── codec-backed encoder/decoder + toBytes/toText normalizers
+│   └── packed.ts          ── packed-wire unpackers + packers
+│
+├── native/                ── Native transport: bun:ffi (primary on Bun) + NAPI fallback
+│   ├── types.ts           ── NativeAddon interface + instance types
+│   ├── loader.ts          ── Path resolution (multi-root + env override) + getAddon/lazyAddon
+│   ├── ffi.ts             ── bun:ffi C-ABI bindings (Bun-only; bind-time self-test +
+│   │                        CASTRUM_FFI_MODE gating; castrum_ingress_layout blob)
+│   └── index.ts           ── Barrel
+│
+├── runtime/               ── 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/              ── Rust FFI bindings
+│   ├── options.ts         ── RustOptions + input-normalization helpers
+│   ├── addon.ts           ── shared lazy addon proxy
+│   ├── context.ts         ── per-instance state + namespace helpers
+│   ├── text.ts            ── string namespace
+│   ├── batch.ts           ── array-of-bytes namespace
+│   ├── packed.ts          ── raw packed-wire namespace
+│   ├── scalar/           ── scalar/feature methods (interface + per-domain builders)
+│   ├── client.ts          ── createRust factory + default `rust`
+│   └── index.ts           ── Barrel
+│
+├── baseline/              ── JS baseline implementations
+│   ├── index.ts           ── Aggregator
+│   └── tasks/             ── 21 baseline tasks (cookie, hashing, hmac, http, json,
+│                              json-patch, mime, query, token, url, validation,
+│                              websocket, aead, compress, jwt, multipart, password,
+│                              streaming, template, pbkdf2, bun-builtins) — full list in docs/REPO_MAP.md
+│
+├── bench/                 ── Benchmark framework
+│   ├── index.ts           ── Benchmark orchestrator
+│   ├── assert.ts          ── Result assertions
+│   ├── checks.ts          ── Correctness checks
+│   ├── checksum.ts        ── Checksum verification
+│   ├── comparisons.ts     ── Comparison reports
+│   ├── concurrent-worker.ts ── Concurrent worker pool
+│   ├── fixtures.ts        ── Test fixtures
+│   ├── measure.ts         ── Measurement utilities
+│   ├── now.ts             ── High-resolution timer
+│   ├── report.ts          ── Report generation
+│   ├── run.ts             ── Benchmark runner
+│   ├── types.ts           ── Type definitions
+│   └── tasks/             ── 33 benchmark tasks (complex, concurrent, cookie,
+│                              hashing, hmac, http, json, json-patch, mime, query,
+│                              stress, token, url, validation, websocket, aead,
+│                              compress, jwt, password, streaming, template,
+│                              json-schema, media-type, form, etag, accept,
+│                              encoding, cookie-sign, csrf, url-join, multipart,
+│                              loader, bun-builtins) — see docs/REPO_MAP.md
+│
+├── data/                  ── Benchmark-fixture data (internal)
+│   └── json-rows.ts       ── JSON row serialization
+```
+
+> **Two ingress consumption paths** (see `docs/INGRESS.md`):
+> 1. `src/ingress/fast.ts` (`createIngressFast`) — JS packs headers
+>    (`IngressInputPacker`) → Rust `handle_request_packed`. Wire format from
+>    `buildTerminalResponse`: `{"error":{code,status,message,requestId}}`,
+>    `x-ratelimit-*`.
+> 2. `src/ingress/handlers.ts` (`createIngressHandler` + route factories +
+>    `createIngressServer`) — JS packs the request frame (`IngressInputPacker`
+>    + `gatherRawHeadersPacked`) and drives the SAME native core as path 1
+>    (`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
+>    re-exports the pre-baked functions.
+
+## Node.js Compatibility
+
+**Bun is the primary target.** Bun resolves the `bun` exports condition → raw
+`index.ts` (native TS execution, zero startup cost). For Node.js consumers, the
+package ships a compiled ESM bundle built by `bun run build:js`:
+
+- `package.json` `exports` → `{ types: ./dist/index.d.ts, bun: ./index.ts,
+  node: ./dist/index.js, default: ./dist/index.js }`.
+- `dist/index.js` is a single-file ESM bundle (all runtime deps inlined); Node
+  requires `>= 20.3` (N-API floor).
+- The addon loader (`src/native/loader.ts`) resolves `castrum.<platform>-<arch>.node`
+  from multiple candidate roots so the same loader works from `src/native/…`
+  (Bun, source layout) and `dist/…` (Node, bundled layout), plus the
+  `CASTRUM_NATIVE_LIBRARY_PATH` / `NAPI_RS_NATIVE_LIBRARY_PATH` override.
+- `src/runtime/detect.ts` is the single runtime-detection seam (the ONLY place
+  `typeof Bun` is checked); `src/shared/runtime.ts` is a thin facade over it.
+- The public `createIngressServer` is runtime-adaptive: it delegates to the
+  Bun.serve builder (`src/ingress/server.ts`) on Bun and to `createIngressServerNode`
+  (`src/ingress/server-node.ts`, same route handlers over `node:http`) on Node,
+  via `src/runtime/server.ts`. The `BakedServer.server` type is a
+  runtime-agnostic `ServerHandle` so Node TS consumers don't need `@types/bun`.
+- The benchmark tooling (`bench/`, `bun:test` suites) remains Bun-only by design.
+
+---
+
+## Data Flow
+
+### Ingress Pipeline (Request Processing)
+
+```
+Request
+  │
+  ▼
+┌──────────────────────────────────────────────────────────────┐
+│  TypeScript: packHeaders()                                    │
+│  - Pre-encoded header names (cookie, origin, xff, etc.)      │
+│  - Binary packing with length-prefixed (u16 + u32) format    │
+│  - TLS header buffer (8KB, recycled across calls)            │
+└──────────────────┬───────────────────────────────────────────┘
+                   │ packed headers + URL bytes + method kind
+                   ▼
+┌──────────────────────────────────────────────────────────────┐
+│  Rust: Ingress::handle_request_packed()                       │
+│                                                               │
+│  1. Parse packed input (method, url, ip, rid, headers)       │
+│  2. IP trust resolution                                       │
+│  3. HTTPS detection                                           │
+│  4. CORS evaluation                                           │
+│  5. Rate limiting check                                       │
+│  6. Body size guard                                           │
+│  7. JSON validation & schema check                            │
+│  8. Cookie parsing → output buffer                             │
+│  9. Query parsing → output buffer                              │
+│  10. Optional metadata JSON                                    │
+│  11. Write output header (verdict, status, flags, ...)        │
+└──────────────────┬───────────────────────────────────────────┘
+                   │ output buffer
+                   ▼
+┌──────────────────────────────────────────────────────────────┐
+│  TypeScript: FastIngressResult.refresh()                      │
+│  - Read output header fields from binary buffer              │
+│  - Store slices for lazy decode (cookies, query, body)       │
+│  - Caller inspects result and builds Response                │
+└──────────────────────────────────────────────────────────────┘
+```
+
+### Batch Processing
+
+```
+Multiple Inputs
+  │
+  ▼
+┌──────────────────────────────────────────────────────────────┐
+│  TypeScript: packBatch()                                      │
+│  - Pack each input into binary format with length prefix     │
+│  - Single Uint8Array sent to Rust                             │
+└──────────────────┬───────────────────────────────────────────┘
+                   │ packed batch
+                   ▼
+┌──────────────────────────────────────────────────────────────┐
+│  Rust: SchemaValidator.validateBatchPacked()                  │
+│  - Iterate over packed inputs in a tight loop                │
+│  - Process each through validation pipeline                   │
+│  - Write results as packed output (bitset or length-prefixed)│
+└──────────────────┬───────────────────────────────────────────┘
+                   │ packed results
+                   ▼
+┌──────────────────────────────────────────────────────────────┐
+│  TypeScript: unpackBitset() / unpackByteResults()             │
+│  - Extract individual results from packed output             │
+│  - Map back to original inputs                                │
+└──────────────────────────────────────────────────────────────┘
+```
+
+---
+
+## Output Buffer Layout
+
+The output buffer is a binary format shared between Rust and TypeScript. All offsets are defined in `rust/ingress/output.rs` and exported via `rust/ingress/ingress_constants.rs` to `src/ingress/constants.ts`.
+
+```
+Offset (bytes)
+├─  0: OUT_VERDICT          (u8)    0=pass, 1=terminal
+├─  1: OUT_ERROR_CODE       (u8)    Error code enum
+├─  2: OUT_STATUS           (u16)   HTTP status code (LE)
+├─  4: OUT_FLAGS            (u32)   Bitfield of FLAG_* values (LE)
+├─  8: OUT_RATE_LIMIT       (u32)   Rate limit ceiling (LE)
+├─ 12: OUT_RATE_REMAINING   (u32)   Remaining requests (LE)
+├─ 16: OUT_RATE_RESET       (u64)   Rate limit reset timestamp ms (LE)
+├─ 24: OUT_RETRY_AFTER      (u64)   Retry-After duration ms (LE)
+├─ 32: OUT_COOKIES_JSON_LEN (u32)   Cookie JSON length (LE)
+├─ 36: OUT_QUERY_JSON_LEN   (u32)   Query JSON length (LE)
+├─ 40: OUT_HEADER_VARIANT   (u8)    Header variant index
+├─ 44: OUT_BODY_JSON_LEN    (u32)   Body metadata JSON length (LE)
+├─ 48: OUT_DATA_START       ─── Variable-length data starts here
+│      ├── Cookie JSON string (if present)
+│      ├── Query JSON string (if present)
+│      └── Body metadata JSON (if emitMetadataJson enabled)
+```
+
+### Flags (bitfield)
+
+| Flag | Bit | Description |
+|------|-----|-------------|
+| `FLAG_HAS_COOKIES` | 0 | Cookie data present in output |
+| `FLAG_HAS_QUERY` | 1 | Query data present in output |
+| `FLAG_BODY_VALID_JSON` | 2 | Body is valid JSON |
+| `FLAG_SCHEMA_VALID` | 3 | Body passes JSON Schema validation |
+| `FLAG_CORS_ALLOWED` | 4 | CORS origin allowed |
+| `FLAG_IS_PREFLIGHT` | 5 | Request is a CORS preflight |
+| `FLAG_RATE_LIMITED` | 6 | Rate limit exceeded |
+| `FLAG_HTTPS` | 7 | Request is HTTPS (detected or configured) |
+| `FLAG_TRUSTED_PROXY` | 8 | Request from trusted proxy |
+| `FLAG_BODY_TRUNCATED` | 9 | Output data truncated due to buffer size |
+
+### Error Codes
+
+| Code | Value | Description |
+|------|-------|-------------|
+| `ERR_CODE_NONE` | 0 | No error |
+| `ERR_CODE_CORS_PREFLIGHT` | 1 | CORS preflight rejected |
+| `ERR_CODE_RATE_LIMITED` | 2 | Rate limit exceeded |
+| `ERR_CODE_BODY_TOO_LARGE` | 3 | Request body exceeds maxBodyBytes |
+| `ERR_CODE_INVALID_JSON` | 4 | Invalid JSON in body |
+| `ERR_CODE_SCHEMA_VALIDATION` | 5 | Schema validation failed |
+| `ERR_CODE_BAD_REQUEST` | 6 | Malformed request |
+| `ERR_CODE_REQUEST_TOO_LARGE` | 7 | Request headers/URL too large |
+| `ERR_CODE_INTERNAL` | 8 | Internal server error |
+
+---
+
+## Memory Management
+
+1. **Global allocator**: mimalloc (`MiMalloc`) for fast, scalable allocation
+2. **Buffer reuse**: Output buffers are recycled across requests where possible
+3. **Zero-copy**: `Uint8Array` passed to Rust functions are used in-place, not copied
+4. **Slice overlap detection**: Rust checks for input/output buffer overlap and copies if needed
+5. **Thread-local caches**: Header buffers use thread-local recycling to reduce allocation pressure
+
+---
+
+## JSON & zero-DOM architecture
+
+- **`sonic_rs::Value` is the primary DOM** on every crate boundary that allows
+  it (compact 16-byte tagged nodes, borrowed/inline strings, zero per-key heap
+  `String`). `serde_json::Value` REMAINS only where a crate is hardwired to it
+  and cannot be swapped: the jsonschema 0.48 DOM fallback
+  (`json_schema.rs` + `pipeline.rs::IngressSchema`), `selection.rs`, and the
+  napi JS-object input of `jwt_sign` / `JwtSigner::sign`.
+- **`rust/json/napi_marshal.rs`** is the single sonic→JS bridge:
+  `sonic_value_to_js` walks a `sonic_rs::Value` into a napi value with
+  **byte-parity** to napi's `serde-json` `ToNapiValue for serde_json::Number`
+  (PosInt u64 ≤ u32::MAX → Number, larger → BigInt; NegInt within ±2^53-1 →
+  Number, outside → BigInt; Float → Number). `sonic_values_equal` replicates
+  jsonschema `cmp::equal` (exact cross-type numeric equality + insertion-order
+  object keys) for fast_schema enum/const/uniqueItems and is unit-pinned against
+  a serde_json reference over a value corpus.
+- **Zero-DOM hot paths** (no `serde_json::Value` on the per-request path):
+  - `castrum_json_parse_packed` (FFI) parses ONCE with sonic-rs and emits a
+    typed token stream (deduped string table) that the JS decoder assembles
+    with NO second JSON text parse.
+  - JWT verify (`verify_token_with_key`) decodes the payload ONCE, checks
+    `exp`/`nbf`/`iat` over `sonic_rs::Value`, and returns the payload BYTES
+    (no re-serialize); `jwt_verify` / `JwtSigner::verify` marshal via the
+    walker. JWT sign (`jwtSignBytes`, `JwtSigner::signBytes`,
+    `castrum_jwt_sign_bytes*`) injects `iat`/`exp` into a sonic object
+    (`inject_and_payload_b64_sonic`) and serializes with `sonic_rs::to_vec`.
+  - 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
+  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
+  `sonic_rs::Value`, keeping `JsonPatchError` semantics, the input/output size
+  guards, and the packed batch entry points. `json-patch` and `jsonptr` deps
+  are removed.
+- **Serialization determinism (`sonic sort_keys`)**: sonic's owned `Value`
+  backs MUTABLE objects with `AHashMap` (non-deterministic iteration order), so
+  the crate enables `sort_keys` (`Cargo.toml`), swapping the owned map to
+  `BTreeMap` → deterministic sorted serialization. This is a hard wire-format
+  requirement: JWT sign and the patch engine must emit byte-identical output
+  across the FFI/napi/scalar/bulk transports. Parsed (unmutated) values keep
+  the shared Vec (insertion order) — only `as_object_mut()` + `insert` switches
+  to the map — so `sonic_values_equal` / `sonic_value_to_js` (which iterate the
+  shared representation) keep insertion-order semantics.
+
+---
+
+## Concurrency Model
+
+- **Synchronous calls**: Run on the main JS thread (Bun's event loop)
+- **Rayon**: Available for parallel CPU-bound work (e.g., batch validation)
+- **Rate limiter**: Uses `parking_lot::Mutex` for low-contention access
+
+---
+
+## Dependency Graph
+
+```
+[ingress] ────┬─── [cors] ──── [headers] ──── [method]
+              ├─── [rate_limit] ─── [ip_trust]
+              ├─── [proxy]
+              ├─── [output] ──── [terminal]
+              ├─── [json_ser] ──── [util]
+              ├─── [query_parser]
+              └─── [cookie_parser]
+              [hashing] ──── [hmac_sha256]
+              [validation]
+              [json_ops] ──── [json_patch_ops]
+              [json_schema]
+              [url_codec]
+              [mime_lookup]
+              [websocket]
+              [random_token]
+              [batch]
+              [http_parser]