castrum 0.7.0 → 0.9.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 castrum contributors
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,262 +1,40 @@
 # castrum
 
-**Enterprise-Grade Bun + Rust FFI Runtime Benchmark Package**
+**Rust-accelerated primitives and a production-grade HTTP pipeline for Bun — and Node.js.**
 
-A high-performance Bun backend framework with Rust-accelerated FFI functions, providing production-grade HTTP ingress pipeline, validation, hashing, JSON processing, and more — all with benchmark-grade performance.
+castrum is a hybrid TypeScript + Rust package. A single Rust addon does the
+performance-critical work — hashing, JSON validation, parsing, crypto,
+compression, and a full HTTP request pipeline — while TypeScript gives you a
+small, flat API. Bun talks to the addon through `bun:ffi` (a ~10–20 ns C-ABI
+call); Node.js falls back to NAPI automatically.
 
----
+## Why castrum
 
-## Architecture Overview
+- **Native speed without the plumbing** — call `rust.crc32()`, `rust.jsonValid()`,
+  `rust.validateEmail()`, … directly from TypeScript. No WASM, no subprocess.
+- **A real HTTP server in a few lines** — `createIngressServer` wires CORS, rate
+  limiting, body-size guards, JSON-schema validation, and security headers for you.
+- **Zero-copy hot paths** — request data travels in packed binary buffers shared
+  with Rust, so there's no serialization and no per-request allocation.
+- **Honest performance data** — the CPU benchmark (`bun run check`) races every
+  `rust.*` op against a pure-JS baseline and writes a machine-readable report, so
+  you always know what to reach for.
+- **Bun first, Node ready** — the same API runs on Node ≥ 20.3 via a compiled ESM
+  entry.
 
-```
-┌─────────────────────────────────────────────────────────────────┐
-│                     TypeScript (Bun) Layer                       │
-│                                                                  │
-│  index.ts (entry point)                                          │
-│    ├── src/rust-ffi/     Raw Rust FFI bindings                   │
-│    ├── src/native/       NAPI native addon loader                │
-│    ├── src/ingress/      High-performance HTTP ingress pipeline  │
-│    ├── src/baseline/     JS baseline (benchmark reference)       │
-│    ├── src/data/         Data serialization utilities            │
-│    └── src/shared/       Shared constants and helpers            │
-│                                                                  │
-├─────────────────── NAPI Bridge (napi-rs) ──────────────────────┤
-│                                                                  │
-│                     Rust (cdylib) Layer                          │
-│                                                                  │
-│  rust/lib.rs                                                     │
-│    ├── Core Pipeline: ingress, cors, rate_limit, ip_trust        │
-│    ├── Parsers:       http_parser, query_parser, cookie_parser   │
-│    ├── Validation:    validation (email/uuid/IP)                 │
-│    ├── JSON:          json_ops, json_patch_ops, json_schema,     │
-│    │                  json_ser                                    │
-│    ├── Crypto:        hashing, hmac_sha256, random_token         │
-│    ├── Data:          url_codec, mime_lookup, websocket          │
-│    ├── Batch:         batch                                       │
-│    ├── Utilities:     util, method, headers, output, terminal    │
-└─────────────────────────────────────────────────────────────────┘
-```
-
-## Quick Start
-
-```bash
-# Install dependencies
-bun install
-
-# Build Rust native addon (release)
-bun run build
-
-# Run benchmarks
-bun bench.ts
-
-# Run tests
-bun test
-```
+> **Want the full story?** See the [case study](./docs/CASE_STUDY.md) for how
+> castrum was built and measured — and where native speed did (and didn't) pay off.
 
-## Build
+## Quick start
 
-```bash
-# Production build
-bun run build
-
-# Debug build
-bun run build:debug
-```
-
-## Benchmarks
+### 1. Install
 
 ```bash
-# Full benchmark suite
-bun bench.ts
-
-# HTTP server benchmarks
-bun run bench:http
-
-# Compare with specific frameworks
-bun run bench:http:elysia   # vs Elysia
-bun run bench:http:ingress  # vs Ingress (native)
-bun run bench:http:bun-only # vs raw Bun
-
-# Load patterns
-bun run bench:http:smoke    # smoke test
-bun run bench:http:stress   # stress test
-bun run bench:http:heavy    # heavy JSON
-bun run bench:http:crud     # CRUD operations
-bun run bench:http:soak     # soak (endurance) test
-bun run bench:http:storm    # storm (burst) test
-bun run bench:http:boundary # boundary conditions
-```
-
-## API Reference
-
-### Core Exports
-
-```ts
-import { rust, native, rustBatch } from "castrum";
-
-// `rust`      — All Rust FFI native implementations (flat, complete API)
-// `native`    — JavaScript/Bun baseline implementations for benchmarking
-// `rustBatch` — Back-compat alias === rust.batch
-```
-
-### Rust Utility API
-
-`rust` is a single flat object exposing **every** native Rust utility with
-optimized defaults baked in. 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 |
-
-#### Scalar utilities
-
-| Function | Returns |
-|----------|---------|
-| `crc32(input)` | `number` — CRC32 checksum |
-| `fnv1a64(input)` | `bigint` — FNV-1a 64-bit hash |
-| `hmacSha256(key, data)` | `Uint8Array` — HMAC-SHA256 signature |
-| `hmacSha256Verify(key, data, sig)` | `boolean` |
-| `jsonValid(input)` | `boolean` — JSON validity check |
-| `jsonSumIds(input)` | `bigint` — sum of numeric `id` fields |
-| `jsonPatch(doc, patch)` | `Uint8Array` — RFC 6902 result |
-| `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 |
-
-Low-level / packed variants: `rust.httpParseRequestPacked`, `rust.queryParsePacked`,
-`rust.cookieParsePacked`.
-
-#### 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.schemaValidate(validator, docs); // bitset
-```
-
-Raw packed + metadata variants (advanced): `rust.packed.*` mirrors the native
-functions 1:1 (`jsonValidBatchPacked`, `jsonValidBatchCountPacked`,
-`queryParseBatchTotalLenPacked`, …).
-
-#### Configuring defaults
-
-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.
-
-### Sub-modules
-
-| Import | Description |
-|--------|-------------|
-| `import { encoder, decoder } from "castrum"` | Text encode/decode utilities |
-| `import { packBatch, packPairs, unpackBitset, unpackByteResults, unpackI64ArrayAsBigInt, unpackU32Array } from "castrum"` | Batch/pair packing + unpacking utilities |
-| `import { readPairsPacked, pairsToObject, readHttpPacked } from "castrum"` | Decode packed pairs / parsed HTTP buffers |
-| `import { parseQueryString, parseCookieHeader } from "castrum"` | High-level string parsers (no hand-packing) |
-| `import { jsonRowsBytes, createJsonRows } from "castrum"` | JSON row serialization |
-| `import { createIngress, createIngressSync, createIngressFast } from "castrum"` | HTTP ingress pipeline (low-level) |
-| `import { createIngressHandler, createIngressServer, readHandler, jsonWriteHandler, echoHandler, fallbackHandler } from "castrum"` | **Pre-baked** ingress handlers — route factories + Bun.serve builder |
-
-```ts
-import { parseQueryString, parseCookieHeader } 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 [docs/ENVIRONMENT.md](./docs/ENVIRONMENT.md) for the
-> full reference of `INGRESS_*`, `CASTRUM_*` and `RUST_*` runtime variables.
-
-### Ingress Pipeline
-
-The ingress system is a high-performance request processing pipeline that handles:
-
-- **Method routing** — GET, HEAD, POST, PUT, PATCH, DELETE, OPTIONS
-- **CORS evaluation** — Origin validation, preflight handling
-- **Rate limiting** — Token-bucket per IP with configurable window
-- **IP trust & proxy** — X-Forwarded-For, X-Real-IP resolution
-- **HTTPS detection** — X-Forwarded-Proto based
-- **Cookie parsing** — Structured JSON output
-- **Query parsing** — Key-value pair extraction
-- **JSON body validation** — Syntax + optional schema validation
-- **Body size guarding** — Configurable max body size
-- **Security headers** — HSTS, CSP, X-Frame-Options, etc.
-
-```ts
-// Fast synchronous handler (zero allocations per call)
-import { createIngressFast } from "castrum";
-
-const handler = createIngressFast({
-  cors: { allowOrigin: ["https://example.com"] },
-  rateLimit: { limit: 100, windowMs: 60_000 },
-  parseCookies: true,
-  parseQuery: true,
-});
-
-// Inside a Bun server:
-Bun.serve({
-  port: 3000,
-  async fetch(req) {
-    return handler.run(req, req.headers.get("x-forwarded-for"), null, "", (result) => {
-      if (result.ok) {
-        return new Response("OK", { status: 200 });
-      }
-      return new Response("Error", { status: result.status });
-    });
-  },
-});
+bun install
+bun run build        # compile the Rust addon (release)
 ```
 
-#### Pre-baked handlers (recommended for servers)
-
-`src/ingress/handlers.ts` provides ready-to-use route handlers and a `Bun.serve`
-builder so **any system can consume the optimized ingress pipeline in a few
-lines** — no need to hand-build responses or manage header templates:
+### 2. Start a server
 
 ```ts
 import { createIngressHandler, createIngressServer } from "castrum";
@@ -268,165 +46,173 @@ const ingress = createIngressHandler({
   rateLimit: { limit: 1000, windowMs: 60_000 },
 });
 
-createIngressServer({
+const server = createIngressServer({
   port: 3000,
   routes: {
-    "/health":    { read: ingress },                  // GET + HEAD
-    "/api/users": { read: ingress, write: ingress },  // + POST/PUT/PATCH
-    "/api/echo":  { echo: ingress },                  // POST echo
+    "/health":    { read: ingress },                 // GET + HEAD
+    "/api/users": { read: ingress, write: ingress }, // + POST/PUT/PATCH (+OPTIONS)
+    "/api/echo":  { echo: ingress },                 // POST echo
   },
 });
-```
 
-The route factories (`readHandler`, `headHandler`, `jsonWriteHandler`,
-`echoHandler`, `fallbackHandler`) are runtime-agnostic — use them with any
-fetch-style server. The benchmark server (`bench/servers/ingress-server.ts`)
-is built entirely from these and re-exports them. See
-[docs/INGRESS.md](./docs/INGRESS.md) for the full pre-baked API reference.
+console.log("listening on", server.port);
+```
 
+Run it with `bun`, then `curl http://localhost:3000/health`. A complete
+walkthrough lives in [`examples/basic-server.ts`](examples/basic-server.ts) and
+the tutorial in [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md).
 
----
+### 3. Call native primitives
 
-## Project Structure
+```ts
+import { rust, encoder } from "castrum";
 
-```
-castrum/
-├── index.ts                 # Entry point / public API
-├── AGENTS.md                # AI agent instructions (commands, constraints, gotchas)
-├── bench.ts                 # Benchmark runner
-├── build.rs                 # NAPI build script
-├── Cargo.toml               # Rust dependencies & build config
-├── package.json             # Node/Bun package config
-├── tsconfig.json            # TypeScript config
-│
-├── rust/                    # Rust source (cdylib)
-│   ├── lib.rs               # Crate root, module declarations
-│   ├── ingress.rs           # NAPI ingress class
-│   ├── cors.rs              # CORS engine
-│   ├── rate_limit.rs        # Keyed rate limiter
-│   ├── ip_trust.rs          # IP trust & proxy resolution
-│   ├── http_parser.rs       # HTTP request parser
-│   ├── query_parser.rs      # Query string parser
-│   ├── cookie_parser.rs     # Cookie header parser
-│   ├── validation.rs        # Email/UUID/IP validation
-│   ├── hashing.rs           # FNV-1a & fast hashing
-│   ├── hmac_sha256.rs       # HMAC-SHA256
-│   ├── json_ops.rs          # JSON operations
-│   ├── json_patch_ops.rs    # JSON Patch operations
-│   ├── json_schema.rs       # JSON Schema validation
-│   ├── json_ser.rs          # JSON serialization utilities
-│   ├── url_codec.rs         # URL encode/decode
-│   ├── mime_lookup.rs       # MIME type lookup
-│   ├── websocket.rs         # WebSocket utilities
-│   ├── random_token.rs      # Secure random token generation
-│   ├── batch.rs             # Batch processing
-│   ├── method.rs            # HTTP method enum
-│   ├── headers.rs           # Header packing
-│   ├── output.rs            # Output buffer layout
-│   ├── terminal.rs          # Terminal response writers
-│   ├── proxy.rs             # Proxy detection utilities
-│   ├── util.rs              # Core utilities
-│   └── ingress_constants.rs # NAPI-exported constants
-│
-├── src/                     # TypeScript source
-│   ├── ingress/             # Ingress pipeline (TS layer)
-│   │   ├── index.ts         # Public API + async factory
-│   │   ├── fast.ts          # Fast synchronous handler (packed input)
-│   │   ├── handlers.ts      # PRE-BAKED handlers + createIngressServer
-│   │   ├── constants.ts     # Layout constants (from Rust)
-│   │   └── packed-input.ts  # Input buffer packing
-│   ├── native/              # Native addon loader
-│   │   └── index.ts         # Module loading + type definitions
-│   ├── rust-ffi/            # Rust FFI bindings
-│   │   └── index.ts         # Flat, complete FFI API
-│   ├── baseline/            # JS baseline implementations
-│   │   ├── index.ts         # Aggregator
-│   │   └── tasks/           # Individual baseline implementations
-│   ├── bench/               # Benchmark framework
-│   ├── data/                # Data serialization
-│   └── shared/              # Shared utilities
-│
-├── bench/                   # HTTP benchmark servers
-│   ├── servers/             # bun-server.ts, elysia-server.ts, ingress-server.ts (+ shared.ts)
-│   ├── load.ts              # HTTP load generator & scenarios
-│   └── run-bench.ts         # Benchmark runner
-│
-├── test/                    # Tests (see CONTRIBUTING.md → Testing Requirements)
-├── docs/                    # Documentation
-└── scripts/                 # Build/utility scripts
+rust.crc32(encoder.encode("hello"));          // number
+rust.jsonValid(encoder.encode('{"a":1}'));    // boolean (zero-DOM)
+rust.validateEmail(encoder.encode("a@b.co")); // boolean
+rust.text.mimeFromExtension(".js");           // "text/javascript"
+rust.batch.jsonValid([docA, docB]);           // Uint8Array bitset (one packed call)
 ```
 
----
+Everything is synchronous. For repeated calls, the higher-order
+[`loader`](#api-at-a-glance) batches and caches for you automatically.
 
-## Performance Characteristics
+## Node.js support
 
-All Rust FFI functions are designed for **zero-allocation** paths where possible:
+Bun is the primary target — it resolves the `bun` export condition to raw
+`index.ts` (zero startup cost). Node.js ≥ 20.3 resolves the `node`/`default`
+condition to a compiled ESM bundle (`dist/`, built with `bun run build:js`). It's
+the same cdylib either way: Bun uses `bun:ffi`, Node uses the NAPI fallback, so
+`rust.*` calls behave identically on both runtimes.
 
-- **Ingress pipeline**: Single output buffer written by Rust, read by JS — minimal copies
-- **Validation functions**: Pure CPU-bound, 10-100x faster than JS equivalents
-- **Hashing**: SIMD-optimized crates under the hood
-- **Batch operations**: Packed binary format minimizes NAPI boundary crossings
-- **JSON parsing**: Uses `sonic-rs` (Rust) — one of the fastest JSON parsers available
+```ts
+// Node (ESM) — the same pre-baked handlers over node:http
+import { createIngressServerNode } from "castrum";
+const srv = createIngressServerNode({ port: 3000, routes: { "/health": { read: ingress } } });
+await srv.ready; // resolves once listening
+```
 
----
+The public `createIngressServer` is runtime-adaptive — it picks `Bun.serve` on
+Bun and `node:http` on Node; `createIngressServerNode` stays available for pinned
+Node users with the same route handlers. `rust.transport()` /
+`rust.ffiActive()` report which transport is live, and `CASTRUM_FFI_MODE` forces
+one (see [`docs/ENVIRONMENT.md`](./docs/ENVIRONMENT.md)).
 
-## Testing
+## How it works
 
-```bash
-# Run all tests
-bun test
+TypeScript is the API; a Rust cdylib (`rust/`, one crate) is the engine. Bun
+`dlopen`s the addon and JIT-calls its `extern "C"` exports — that's `bun:ffi`,
+the primary transport (~10–20 ns per crossing). On Node, or if the bind-time
+ffi self-test fails, the same addon loads through napi-rs (NAPI). Request data is
+packed into shared, length-prefixed buffers so hot paths allocate nothing per
+request. See [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) for the full deep
+dive.
 
-# Run specific test file
-bun test test/unit/ingress/fast.test.ts
+## Benchmarks
 
-# Run tests with coverage
-bun test --coverage
-```
+Two suites ship with the repo:
 
----
+- **CPU benchmark** — `bun run check` races every `rust.*` op against a pure-JS
+  baseline (and Bun's built-ins) and writes a machine-readable report to
+  `bench/results/cpu/`.
+- **HTTP benchmark** — `bun run bench:http` compares raw `Bun.serve`, Elysia,
+  and the castrum ingress server across ~20 load scenarios (smoke, stress,
+  soak, spike, heavy JSON, slowloris, …).
 
-## Publishing
+```bash
+bun run check             # CPU benchmark + correctness (writes latest.json)
+bun run bench:http        # HTTP benchmark, all servers
+bun run bench:http:smoke  # fast HTTP sanity — the CI wire-format guard
+```
+
+For scenario details, how to read the reports, and the benchmark-specific env
+controls, see [`docs/BENCHMARKS.md`](./docs/BENCHMARKS.md). The keep/delegate
+decisions for ops where Bun's built-ins win (gzip, crc32, xxh3, `randomUUIDv7`,
+…) live in [`docs/bun-builtins-decision-matrix.md`](./docs/bun-builtins-decision-matrix.md).
+
+## API at a glance
+
+The complete, verified reference lives in [`docs/API.md`](./docs/API.md). This
+is the map:
+
+| Export | What it is |
+|--------|-----------|
+| `rust` | The flat native surface: hashing, JSON, validation, URL/cookie/query/form parsing, MIME, WebSocket/SSE, crypto (HMAC, JWT, AEAD, argon2, bcrypt, PBKDF2), signed cookies, CSRF, gzip/brotli, and more. |
+| `rust.text.*` | String-in / string-out ergonomics over `rust.*`. |
+| `rust.batch.*` | Array-of-bytes → native results (bitsets, typed arrays, byte arrays) in one packed call. |
+| `rust.packed.*` | Raw packed-wire low-level variants + metadata. |
+| `loader` / `createLoader` | Higher-order loader: pre-bound ops, automatic scalar-vs-bulk dispatch, DataLoader-style coalescing, LRU cache. |
+| `opImpl` / `isNativeOp` / `opDecision` | Benchmark-driven native-vs-JS selection hints for framework consumers. |
+| `createIngressHandler` + route factories | Pre-baked HTTP pipeline: CORS, rate limit, body guard, schema validation, security headers. |
+| `createIngressServer` / `createIngressServerNode` | Server builders — the runtime adapter picks `Bun.serve` on Bun and `node:http` on Node. |
+| `createIngress` / `createIngressFast` / `createIngressSync` | Lower-level ingress entry points. |
+| `createPipeline` / `createWebSocketUpgrade` / `sseResponse` | Framework-agnostic integration helpers. |
+| `createMetrics` / `createIngressMetrics` / `livenessHandler` / `readinessHandler` / trace helpers | Zero-dependency observability. |
+| `uuidv7` / `AdaptiveEstimate` / packing & parsing utilities | Shared utilities (`encoder`, `decoder`, `packBatch`, `parseQueryString`, …). |
 
-The package ships **all platform native addons in a single tarball**, so a release
-needs every `napi.targets` platform artifact present (see `scripts/prepublish.mjs`).
+```ts
+import { rust, loader } from "castrum";
 
-### Automatic (recommended)
+rust.jsonValid(bytes);            // scalar boolean
+const isEmail = loader("validateEmail");
+isEmail([a, b, c]);               // one packed batch call
+```
 
-CI builds every platform addon and publishes to npm when you push a `v*` tag.
-Bump `version` in `package.json` (and `Cargo.toml`), add a `CHANGELOG.md` entry,
-then:
+> **The selection surface** — framework consumers that want to bind each op to
+> a fixed implementation at load time use `opImpl(op)` / `isNativeOp(op)` /
+> `opDecision(op)` (source of truth: `rust/selection.rs` + `src/selection.json`,
+> audited by CI). They read it once at startup — they don't swap native↔js per
+> call. See [`docs/API.md`](./docs/API.md) and
+> [`docs/bun-builtins-decision-matrix.md`](./docs/bun-builtins-decision-matrix.md).
+
+## Testing
 
 ```bash
-git tag v0.6.0 && git push origin v0.6.0
+bun test                  # TypeScript unit tests (~540)
+bun run test:rust         # Rust unit tests (cargo test)
+bun run typecheck         # TypeScript typecheck
+bun run test:node         # Node.js integration tests (run `bun run build:js` first)
+bun run bench:http:smoke  # HTTP smoke — the CI wire-format guard
 ```
 
-### Manual
+For coverage floors, the typecheck/test configs, and the full test matrix, see
+[`docs/REPO_MAP.md`](./docs/REPO_MAP.md).
+
+## Publishing
 
-To build and publish a release by hand (no CI needed; npm logged in or `NPM_TOKEN`
-exported):
+The package ships **all platform addons in a single tarball**. Push a `v*` tag
+and CI builds + publishes every platform to npm; or use `bun run publish:manual`
+for a quick single-platform release:
 
 ```bash
-bun run publish:manual                            # build + publish current version
-bun run publish:manual -- --increment minor       # bump version + tag + push + publish
-bun run publish:manual:dry                        # print the plan, change nothing
+bun run publish:manual -- --increment minor  # bump + tag + build + publish
+bun run publish:manual:dry                   # print the plan, change nothing
 ```
 
-`publish:manual` bumps the version (`--increment`), creates + pushes the `v<version>`
-git tag via `bun pm version` (keeping `Cargo.toml`, `Cargo.lock`, and `CHANGELOG.md`
-in sync), builds the host addon locally, and runs `npm publish --access public`.
+Run `bun run check:version` before tagging (it verifies `package.json`,
+`Cargo.toml`, and `CHANGELOG.md` agree). See [`docs/REPO_MAP.md`](./docs/REPO_MAP.md)
+§6 for the full flow.
 
-> **Platform note:** because only the current platform can be built locally, the
-> manual publish ships a **single-platform tarball** (it sets
-> `CASTRUM_PUBLISH_ALLOW_PARTIAL=1` so `prepublishOnly` doesn't fail on the missing
-> platforms). For a full multi-platform tarball, push a `v*` tag and let the CI
-> workflow build + publish.
+## Documentation
 
----
+| Doc | Read it for |
+|-----|-------------|
+| [`docs/GETTING_STARTED.md`](./docs/GETTING_STARTED.md) | First-time walkthrough: install → server → bench → test. |
+| [`docs/API.md`](./docs/API.md) | The complete public API reference. |
+| [`docs/INGRESS.md`](./docs/INGRESS.md) | The ingress pipeline: options, route factories, servers, framework integration. |
+| [`docs/CASE_STUDY.md`](./docs/CASE_STUDY.md) | Data-driven case study: how castrum was built and measured. |
+| [`docs/ARCHITECTURE.md`](./docs/ARCHITECTURE.md) | Internals: modules, data flow, wire layout, memory, concurrency. |
+| [`docs/BENCHMARKS.md`](./docs/BENCHMARKS.md) | Benchmark scenarios + how to interpret reports. |
+| [`docs/ENVIRONMENT.md`](./docs/ENVIRONMENT.md) | Every `CASTRUM_*` / `INGRESS_*` env var. |
+| [`docs/REPO_MAP.md`](./docs/REPO_MAP.md) | Where everything lives + how to build/test/publish. |
+| [`docs/bun-builtins-decision-matrix.md`](./docs/bun-builtins-decision-matrix.md) | Bun built-in vs castrum keep/delegate decisions. |
+| [`examples/`](examples/README.md) | Runnable examples. |
 
 ## License
 
-MIT
+MIT — see [LICENSE](./LICENSE).
 
 ## Contributing
 
-Please see [CONTRIBUTING.md](./CONTRIBUTING.md).
+See [CONTRIBUTING.md](./CONTRIBUTING.md) and [`AGENTS.md`](./AGENTS.md) (AI-agent
+guidance) for contribution and testing requirements.