castrum 0.9.0 → 0.9.1

package/docs/API.md

@@ -0,0 +1,337 @@
+# castrum — API Reference
+
+The complete public API, verified against the current source. For the friendly
+overview and quick start, see the [README](../README.md); for the HTTP pipeline
+deep-dive, see [`INGRESS.md`](./INGRESS.md).
+
+Everything is **synchronous**. All byte-level functions accept `Uint8Array`;
+`rust.text.*` provides string-in/string-out ergonomics.
+
+---
+
+## Runtime return-type divergence (Bun vs Node)
+
+On **Bun** the `bun:ffi` C-ABI transport returns text results as **JS strings**
+via JSC's native transfer (cstring → `new CString(ptr, 0, len)`), with **zero
+`TextEncoder`/`TextDecoder`** on the hot path. So `rust.urlEncode`,
+`rust.base64Encode`, `rust.hexEncode`, `rust.hmacSha256`, `rust.etag`,
+`rust.wsAcceptKey`, `rust.randomToken`, `rust.signCookie`, `rust.verifyCookie`
+(`string | null`), `rust.csrfToken`, `rust.passwordHash`,
+`rust.passwordHashBcrypt`, `rust.jwtSignBytes`, `rust.jwtVerify`
+(`string | null`), `rust.jsonPatch`, `rust.httpDate`, `rust.mimeFromExtension`,
+`rust.urlResolve`, `rust.urlEncodeQuery`, and `rust.acceptNegotiatorNegotiate`
+(`string | null` — the `null` is the C `NULL` sentinel) return **`string`** on Bun. On **Node** (napi fallback) the same
+functions return **`Uint8Array`**. The TypeScript surface types these as
+`Uint8Array | string`; normalize with `toBytes(value)` / `toText(value)` (from
+`src/shared/bytes`). The `*Into`/pooled variants always return bytes on both
+runtimes, and binary ops (`gzip*`, `brotli*`, `aead*`, `pbkdf2Sha256`,
+`wsFrame*`, packed parsers, `batch.*`/`packed.*`) return `Uint8Array` on both.
+
+---
+
+## Core exports
+
+| Export | Description |
+|--------|-------------|
+| `rust` | The default, shared native client — every Rust utility, flat and complete. |
+| `createRust(options?)` | Build an isolated client (own caches / rayon settings). |
+| `proven`, `PROVEN_SELECTION`, `provenImpl`, `provenStatus`, `isProven`, `provenSurface`, `provenSummary` | The full `rust.*` surface + the baked (pure-data) proven-selection registry of benchmark winners (`native` / `js` / `bun`). |
+| `opImpl`, `isNativeOp`, `opDecision` | Native-vs-JS selection hints (benchmark-driven). |
+| `loader`, `createLoader` | Higher-order loader over the batch surface. |
+| `encoder`, `decoder` | Codec-backed UTF-8 helpers (Bun: `Bun.ArrayBufferSink` / `CString`; Node: `TextEncoder`/`TextDecoder`). `encode`/`decode` accept the `Uint8Array | string` union and normalize. |
+| `uuidv7()` | UUIDv7 — `Bun.randomUUIDv7` on Bun, `crypto.randomUUID` on Node. |
+| `AdaptiveEstimate`, `AdaptiveEstimateOptions` | Bounded EWMA adaptive-estimate utility. |
+| `createMetrics`, `DEFAULT_BUCKETS` | Zero-dependency metrics registry (counters/gauges/histograms + Prometheus text). |
+| `packBatch`, `packPairs`, `readPairsPacked`, `readHttpPacked`, `pairsToObject`, `parseQueryString`, `parseCookieHeader`, `parseFormBody`, `unpackBitset`, `unpackByteResults`, `unpackI64ArrayAsBigInt`, `unpackU32Array` | Packed-wire + high-level parsing utilities. |
+| Ingress: `createIngress`, `createIngressSync`, `createIngressFast`, `createIngressHandler`, `createIngressServer`, `createIngressServerNode`, `createIngressRouter`, route factories, metrics/health/trace helpers | See [`INGRESS.md`](./INGRESS.md) and [`INGRESS-ROUTER.md`](./INGRESS-ROUTER.md). |
+| Integration: `createPipeline`, `createWebSocketUpgrade`, `sseResponse` | Framework-agnostic helpers — see [`INGRESS.md`](./INGRESS.md) §Framework Integration. |
+
+---
+
+## The `rust` client
+
+`rust` is a single flat object exposing **every** native utility. Text-oriented
+operations also have ergonomic string variants under `rust.text`.
+
+| Namespace | Description |
+|-----------|-------------|
+| `rust.crc32(...)`, `rust.jsonValid(...)`, … | Scalar utilities (bytes in → typed out) |
+| `rust.text.mimeFromExtension(".js")`, … | String ergonomics (string in → string/bool out) |
+| `rust.batch.jsonValid(docs)`, … | High-throughput batch (arrays → unpacked results) |
+| `rust.packed.jsonValidBatchPacked(p)`, … | Raw packed low-level variants + metadata |
+| `rust.configure({ ... })` | Override defaults on the shared instance |
+
+`rust.transport()` returns `"ffi"` / `"napi"` (the resolved transport);
+`rust.ffiActive()` reports whether the bun:ffi transport is live.
+
+### Scalar utilities
+
+| Function | Returns |
+|----------|---------|
+| `crc32(input)` | `number` — CRC32 checksum |
+| `fnv1a64(input)` | `bigint` — FNV-1a 64-bit hash |
+| `xxh3(input)` | `bigint` — XXH3-64 (non-crypto hash) |
+| `hmacSha256(key, data)` | `Uint8Array` — HMAC-SHA256 signature |
+| `hmacSha256Verify(key, data, sig)` | `boolean` |
+| `jsonValid(input)` | `boolean` — JSON validity check (zero-DOM) |
+| `jsonParse(input)` | `unknown` — JSON → JS value (native sonic-rs DOM; throws on invalid) |
+| `jsonSumIds(input)` | `bigint` — sum of numeric `id` fields |
+| `jsonPatch(doc, patch)` | `Uint8Array` — RFC 6902 result |
+| `createSchemaValidator(schema)` | `SchemaValidator` — compile a JSON Schema (draft-07); `.validate(doc): boolean`, `.validateDetailed(doc): SchemaError[]`, `.validateFirstError(doc): SchemaError | null`, `.validateBatchPackedCount(packed): number`, … |
+| `mimeFromExtension(ext)` | `Uint8Array` — MIME type |
+| `randomToken(byteLen)` | `Uint8Array` — CSPRNG token |
+| `urlEncode(input)` / `urlDecode(input)` | `Uint8Array` — percent encode/decode |
+| `urlDecodeBytes(input)` | `Uint8Array` — strict %-decode (no UTF-8 check) |
+| `validateEmail/Uuid/Ipv4/Ipv6(input)` | `boolean` |
+| `wsAcceptKey(key)` | `Uint8Array` — WebSocket accept key |
+| `passwordHashBcrypt(password, salt?, cost?)` | `Uint8Array` — bcrypt `$2b$` PHC string |
+| `passwordVerifyBcrypt(password, phc)` | `boolean` |
+| `pbkdf2Sha256(password, salt, iterations, dkLen?)` | `Uint8Array` — PBKDF2-HMAC-SHA256 |
+| `gzipCompress(data)` / `gzipDecompress(data, maxDecompressed?)` | `Uint8Array` — gzip (decompress capped at 64 MiB by default) |
+| `brotliCompress(data)` / `brotliDecompress(data, maxDecompressed?)` | `Uint8Array` — brotli |
+
+### Framework actions (HTTP semantics + security)
+
+| Function | Returns |
+|----------|---------|
+| `formParsePacked(body)` | `Uint8Array` — packed x-www-form-urlencoded pairs |
+| `createFormParser(capacity?)` | `FormParser` — reusable-buffer form parser (`.parse`, `.parseInto`) |
+| `parseMediaType(header)` | `{ mediaType, charset, boundary, params }` — Content-Type parse |
+| `createMediaTypeParser()` | `MediaTypeParser` — `.parse`, `.matches(actual, expected)` (wildcards) |
+| `createMediaTypeMatcher(expected)` | `MediaTypeMatcher` — `.matches(actual)` (expected precompiled once) |
+| `etag(data, weak?)` | `Uint8Array` — strong/weak ETag (crc32-based) |
+| `httpDate(secs?)` / `parseHttpDate(input)` | `Uint8Array` / `bigint | null` — IMF-fixdate format/parse |
+| `createConditionalRequest(etag, lastModifiedSecs?)` | `ConditionalRequest` — `.isNotModified(ifNoneMatch, ifModifiedSince)` → 304 |
+| `parseAcceptEncoding(header)` | `{ encoding, q, order }[]` |
+| `createAcceptNegotiator(supported[])` | `AcceptNegotiator` — `.negotiate(header)` → best encoding |
+| `base64Encode/Decode(input, urlSafe?, padding?)`, `base64UrlEncode/Decode(input)` | `Uint8Array` |
+| `createBase64Codec(urlSafe?, padding?)` | `Base64Codec` — `.encode`, `.decode` |
+| `hexEncode(input)` / `hexDecode(input)` | `Uint8Array` — lowercase hex |
+| `signCookie(value, secret)` / `verifyCookie(signed, secret)` | `Uint8Array` / `Uint8Array | null` — signed cookies |
+| `createCookieSigner(secret)` | `CookieSigner` — `.sign`, `.verify` (HMAC key compiled once) |
+| `csrfToken(secret)` / `csrfVerify(token, secret)` | `Uint8Array` / `boolean` |
+| `createCsrfProtector(secret)` | `CsrfProtector` — `.create`, `.verify` |
+| `urlResolve(base, reference)` | `Uint8Array` — RFC 3986 resolution |
+| `urlEncodeQuery(params)` | `Uint8Array` — percent-encoded query (sorted keys) |
+| `createUrlBuilder(base)` | `UrlBuilder` — `.resolve(reference)` (base parsed once) |
+| `createJwtSigner(secret, ttlSeconds?)` | `JwtSigner` — `.sign(claims, now)`, `.verify(token, now)` (HS256 key + ttl compiled once) |
+| `createAeadCipher(key, algorithm?)` | `AeadCipher` — `.encrypt(nonce, pt)`, `.decrypt(nonce, ct)` (key compiled once) |
+| `createArgon2Hasher(options?)` | `Argon2Hasher` — `.hash(password, salt)`, `.verify(password, phc)` (params compiled once) |
+| `httpParseRequestPacked(bytes)` | packed HTTP request parse (low-level) |
+| `queryParsePacked(query)` / `cookieParsePacked(header)` / `formParsePacked(body)` | packed pair parsing (low-level) |
+
+> `passwordHash` / `passwordVerify` (argon2id) and `passwordHashBcrypt` /
+> `passwordVerifyBcrypt` are also exposed as scalar helpers; the compiled-once
+> `createArgon2Hasher` is preferred when hashing repeatedly.
+
+### String ergonomics (`rust.text`)
+
+```ts
+rust.text.mimeFromExtension(".js");  // "text/javascript"
+rust.text.mimeFromExtension("html"); // "text/html"
+rust.text.urlEncode("a b");         // "a%20b"
+rust.text.urlDecode("a%20b");       // "a b"
+rust.text.wsAcceptKey(keyBase64);    // base64 accept key
+rust.text.validateEmail("a@b.co");   // true
+```
+
+### Batch operations (`rust.batch`)
+
+All batch helpers accept `Uint8Array[]` and return unpacked, ready-to-use results:
+
+```ts
+const docs = [encoder.encode('{"id":1}'), encoder.encode('{"id":2}')];
+
+rust.batch.jsonValid(docs);             // Uint8Array bitset (1 per doc)
+rust.batch.crc32(docs);                 // Uint32Array
+rust.batch.jsonSumIds(docs);            // BigInt64Array
+rust.batch.queryParse(docs);            // Uint8Array[]
+rust.batch.formParse(docs);             // Uint8Array[] (packed pairs per doc)
+rust.batch.signCookie(docs, secret);    // Uint8Array[] (signed)
+rust.batch.verifyCookie(docs, secret);  // Uint8Array bitset (valid?)
+rust.batch.csrfVerify(tokens, secret);  // Uint8Array bitset (valid?)
+rust.batch.schemaValidate(validator, docs); // bitset
+
+// Hashing / url / mime / ws / base64url
+rust.batch.fnv1a64(docs);               // BigUint64Array (unsigned hashes)
+rust.batch.etag(docs);                  // Uint8Array[]
+rust.batch.urlEncode(docs);             // Uint8Array[]
+rust.batch.urlDecode(docs);             // Uint8Array[]
+rust.batch.base64UrlEncode(docs);       // Uint8Array[]
+rust.batch.wsAcceptKey(keys);           // Uint8Array[]
+rust.batch.mimeFromExtension(exts);     // Uint8Array[]
+
+// Backend-framework batches (zipped lists / shared args)
+rust.batch.passwordVerify(pwds, phcs);  // Uint8Array bitset (zipped)
+rust.batch.urlResolve(bases, refs);     // Uint8Array[] (zipped)
+rust.batch.jwtSign(claimDocs, secret);  // Uint8Array[] (sign N JSON claim docs)
+rust.batch.jwtVerify(tokens, secret, now); // Uint8Array bitset
+rust.batch.sseEncode(items, "event");   // Uint8Array[]
+rust.batch.wsFrameEncode(items, 1, false, true); // Uint8Array[]
+rust.batch.wsFrameDecode(frames);       // Uint8Array[] (payloads)
+rust.batch.multipartParse(bodies, boundary); // MultipartPart[][]
+```
+
+Raw packed + metadata variants (advanced): `rust.packed.*` mirrors the native
+functions 1:1 (`jsonValidBatchPacked`, `jsonValidBatchCountPacked`,
+`queryParseBatchTotalLenPacked`, …).
+
+---
+
+## Higher-order data loader (`loader` / `createLoader`)
+
+`loader` is a callable higher-order function over the whole batch surface. It
+pre-binds an op so repeated calls skip registry dispatch, and it routes small
+vs. large workloads automatically: a single item → one scalar native call, a
+bulk → ONE packed batch call, and `load()` coalesces N same-tick calls into one
+packed call (DataLoader-style) with a bounded LRU cache.
+
+```ts
+import { loader } from "castrum";
+
+const isEmail = loader("validateEmail");
+isEmail(emailBytes);                    // scalar → boolean
+isEmail([a, b, c]);                     // bulk → Uint8Array bitset (one packed call)
+await isEmail.load(a);                  // coalesced + cached (auto batch/strategy)
+
+// Covered op families (44 ops):
+//   hash     crc32, fnv1a64
+//   json     jsonValid, jsonSumIds, jsonPatch*, schemaValidate
+//   validate email, uuid, ipv4, ipv6
+//   parse    query, cookie, form, httpParseRequest, urlResolve*
+//   encode   hex, base64, base64Url, urlEncode, urlDecode, urlDecodeBytes, etag
+//   compress gzip, brotli
+//   crypto   hmacSha256, hmacSha256Verify*, signCookie, verifyCookie, csrfVerify,
+//            passwordHash, passwordVerify*, aeadEncrypt, aeadDecrypt, jwtSign, jwtVerify
+//   web      wsAcceptKey, wsFrameEncode, sseEncode, mimeFromExtension
+//   (* = paired: per-item companion array, e.g. loader.run("jsonPatch", docs, patches))
+
+// Paired ops take a companion array:
+loader.run("jsonPatch", docs, patches);       // bulk
+loader.run("jsonPatch", doc, patch);          // single
+
+// verifyCookie / jwtVerify are boolean-validity ops (valid/invalid);
+// use rust.verifyCookie / rust.jwtVerify for the decoded value.
+
+// Bind a schema validator for repeated single/bulk validation + count:
+const schema = loader.schema(rust.createSchemaValidator(schemaBytes));
+schema(doc);              // boolean
+schema(docs);             // Uint8Array bitset
+schema.count(docs);       // number of valid docs
+
+// Fine-grained control: createLoader({ adaptive, batchMin, maxCacheKeys, ... })
+```
+
+---
+
+## The `proven` selection surface
+
+`proven` is literally the same object as `rust` (`export const proven = rust`) —
+nothing is filtered. Alongside it, the pure-data registry `PROVEN_SELECTION`
+(`src/shared/proven.ts`) states which implementation is the benchmark-proven
+winner for every op: `native` (the addon), `js` (pure TS), or `bun` (a Bun
+built-in that is delegated under Bun). The winners are **baked** from
+measurements (`src/selection.json` + `docs/bun-builtins-decision-matrix.md`),
+and `test/unit/shared/proven.test.ts` verifies each winner is actually wired
+(`opImpl` agrees, `builtins.has` matches, native/js entries match the addon's
+embedded `selection.json`) — so the registry cannot silently drift. There is no
+live benchmark gate (the old `check:proven` / `check:annotate` friction is gone).
+
+- Statuses: `proven` (decisive win) / `parity` (borderline) / `unmeasured` (no
+  direct ratio — pinned by policy). `provenImpl(op)` returns the baked winner.
+- The full surface is unchanged — `rust.jsonParse`, `rust.createSchemaValidator`,
+  etc. remain available for completeness; they just aren't advertised as wins.
+- Classifications are based on the **release build on the shipped baseline CPU**
+  (published artifacts are baseline — not the local SIMD `build:perf`).
+
+```ts
+import { proven, PROVEN_SELECTION, provenImpl } from "castrum";
+
+proven.fnv1a64(bytes);        // native — Rust wins ~12x vs the JS baseline
+provenImpl("crc32");          // "bun" — Bun.hash.crc32 wins under Bun
+provenImpl("validateEmail");  // "js" — pure-TS wins
+```
+
+```bash
+bun test test/unit/shared/proven.test.ts   # proves every baked winner is wired
+```
+
+---
+
+## Native-vs-JS selection surface
+
+For framework consumers that want to bind each operation to a fixed
+implementation at load time (instead of calling `rust.*` directly):
+
+```ts
+import { opImpl, isNativeOp, opDecision } from "castrum";
+
+opImpl("gzipCompress");   // "native" | "js" | null
+isNativeOp("crc32");      // boolean
+opDecision("fnv1a64");    // { impl, note? } | null
+```
+
+- Source of truth: `rust/selection.rs`, which embeds the benchmark-generated
+  `src/selection.json` (produced by `scripts/select-native.ts --write`, audited
+  by `--check` in CI).
+- Under Bun, ops where the Bun built-in beats the Rust addon (gzip, crc32, xxh3,
+  HMAC, random tokens) are selected as `"js"` (a JS path that delegates to the
+  Bun built-in); under Node the base benchmark decision stands.
+- Consumers read `opImpl(op)` **once at startup** and bind each op to a fixed
+  implementation — they do not swap native↔js per call.
+
+---
+
+## Configuration
+
+Defaults are selected automatically, and can be overridden:
+
+```ts
+// Defaults:
+//   rayonThreads = max(1, hardwareConcurrency - 1)
+//                  (env override: CASTRUM_RAYON_THREADS / RUST_RAYON_THREADS)
+//   mimeCache    = true
+//   hmacCache    = true
+
+// Override per-instance options on the shared instance:
+rust.configure({ mimeCache: false, hmacCache: false });
+
+// Or create an isolated instance with custom defaults:
+import { createRust } from "castrum";
+const myRust = createRust({ mimeCache: false });
+```
+
+> **Thread pool note**: the rayon pool is process-wide and initialized **once**
+> (native `OnceLock`) — the first initialization wins. Because importing the
+> module initializes it with the default, set
+> `CASTRUM_RAYON_THREADS` / `RUST_RAYON_THREADS` (or call
+> `rust.configure({ rayonThreads })` / `createRust({ rayonThreads })` before any
+> other pool use) to tune it. `mimeCache` / `hmacCache` are per-instance and can
+> be toggled any time.
+
+---
+
+## Shared utilities
+
+```ts
+import {
+  encoder, decoder,             // TextEncoder/TextDecoder singletons
+  packBatch, packPairs,         // batch/pair packing
+  unpackBitset, unpackByteResults, unpackI64ArrayAsBigInt, unpackU32Array,
+  readPairsPacked, pairsToObject, readHttpPacked,
+  parseQueryString, parseCookieHeader, parseFormBody,
+  uuidv7, createMetrics,
+} from "castrum";
+
+parseQueryString("a=1&b=2&tag=a&tag=b");       // { a: "1", b: "2", tag: ["a", "b"] }
+parseCookieHeader("session=abc; theme=dark");  // { session: "abc", theme: "dark" }
+```
+
+> **Environment variables**: see [`ENVIRONMENT.md`](./ENVIRONMENT.md) for the
+> full reference of `INGRESS_*`, `CASTRUM_*`, and `RUST_*` runtime variables.
+
+## Ingress & integration
+
+The HTTP pipeline (options, route factories, `BakedIngressResult`, server
+builders, observability, and the framework integration helpers) has its own
+dedicated reference: [`INGRESS.md`](./INGRESS.md).

package/docs/ARCHITECTURE.md

@@ -31,14 +31,22 @@ 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`, 45 `castrum_*` symbols) and Bun JIT-calls them
+  `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 (stateful instances, `rust.batch.*` / `rust.packed.*`, `text.*`, and
-  structured-return scalars like `jsonParse` / `jwtVerify`).
+  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:
 
@@ -46,10 +54,25 @@ Shared characteristics:
 - **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.
@@ -97,9 +120,15 @@ rust/
 │   └── random_token.rs    ── random hex tokens
 │
 ├── json/                  ── JSON & schema
-│   ├── json_ops.rs        ── zero-DOM validate/sum + DOM parse
+│   ├── 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  ── RFC 6902 JSON patch
+│   ├── 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
@@ -137,7 +166,7 @@ src/
 │   ├── 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)
+│   ├── 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)
@@ -153,14 +182,15 @@ src/
 │   └── routes/            ── read/head/json-write/echo/fallback factories
 │
 ├── shared/
-│   ├── runtime.ts         ── isBun/isNode runtime detection (single seam)
+│   ├── 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           ── shared TextEncoder/Decoder singletons
-│   ├── packed.ts          ── packed-wire unpackers + packers
-│   └── proven.ts          ── PROVEN_SURFACE registry (single source for `proven`)
+│   ├── 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
@@ -169,6 +199,18 @@ src/
 │   │                        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
@@ -240,10 +282,12 @@ package ships a compiled ESM bundle built by `bun run build:js`:
   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/shared/runtime.ts` is the single runtime-detection seam (`isBun`/`isNode`).
-- `createIngressServer` (Bun.serve) is Bun-only; `createIngressServerNode`
-  (`src/ingress/server-node.ts`) serves the SAME route handlers over `node:http`,
-  sharing `buildRouteHandlers` in `server.ts`. The `BakedServer.server` type is a
+- `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.
 
@@ -385,6 +429,54 @@ Offset (bytes)
 
 ---
 
+## 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)