castrum 0.7.0 → 0.9.0

package/docs/BENCHMARKS.md

@@ -0,0 +1,307 @@
+# Benchmarks Guide
+
+This document describes the benchmark framework, how to run benchmarks, and how to interpret results.
+
+---
+
+## Overview
+
+The benchmark system compares the Rust implementations against pure JavaScript/Bun baseline implementations. It measures throughput (ops/sec), latency (mean/percentiles), and memory allocation. Under Bun the `rust:*` side runs through the PRIMARY `bun:ffi` transport (NAPI is the fallback); the CPU bench warns — or hard-fails with `CASTRUM_BENCH_FFI=1` — if the ffi transport is not live.
+
+### Benchmark Types
+
+| Type | Description |
+|------|-------------|
+| **Unit benchmarks** | Individual function comparisons (hashing, validation, JSON, etc.) |
+| **HTTP benchmarks** | Full HTTP server comparisons (Bun vs Elysia vs Ingress) |
+| **Batch benchmarks** | Throughput for batch operations |
+| **Stress benchmarks** | Performance under load |
+| **Concurrency benchmarks** | Performance with multiple concurrent requests |
+
+---
+
+## Running Benchmarks
+
+### Unit Benchmarks
+
+```bash
+# Run all unit benchmarks
+bun bench.ts
+```
+
+### Performance-proven surface & auto-annotated JSDoc
+
+The CPU benchmark persists a machine-readable report to `bench/results/cpu/latest.json`
+(+ timestamped snapshots). Three commands consume it; `bun run check:docs` runs all
+three as the one-stop "informed decision" pipeline:
+
+| Command | What it does |
+|---------|--------------|
+| `bun run check` | Runs the CPU benchmark and writes `bench/results/cpu/latest.json` (report-only — **never mutates source**). |
+| `bun run check:annotate` | Rewrites the `@performance` / `@deprecated` / `@remarks` JSDoc on the public `rust.*` declarations (`src/rust-ffi/scalar/interface.ts`, `batch.ts`, `client.ts`) from the report. Idempotent — generated lines carry the `[check:annotate]` marker; hand-written JSDoc is preserved. `--dry-run` previews changes. |
+| `bun run check:proven` | Audits the `PROVEN_SURFACE` registry against the report and flags `REGRESSION`, `PARITY-DRIFT`, and `PROMOTABLE`. `--fail` exits 1 on regressions. |
+| `bun run check:docs` | `check` + `check:annotate` + `check:proven` — the full pipeline. |
+
+**Automatic annotation (opt-in):** `CASTRUM_BENCH_ANNOTATE=1 bun run check`
+auto-runs the annotator right after the benchmark, so the JSDoc always reflects
+the latest run. It is opt-in because it mutates tracked source files.
+
+**How the annotations work (data-driven):**
+
+- Each function's **score** is embedded in the `@performance` line, e.g.
+  `JSON valid: ~3.2x faster than the JS baseline (8/8 tasks won)` or
+  `CRC32: ~4.1x slower than the JS baseline (2/3 tasks failed)`. A function's
+  benchmark set is the canonical comparison plus all its `_`-suffixed variants
+  (`_large`, `_batch`, `_concurrent_*`, `_stress`, pooled `_into` overloads)
+  that no other registry entry claims.
+- Task bands (see `src/shared/bench-classify.ts`): **won** = `ratio >= 1`
+  (Rust at least as fast), **failed** = `ratio < 1 / 1.35` (clear loss), the
+  middle is a **tie** that counts toward neither.
+- `@deprecated` is **hybrid**:
+  - A clear **majority** of a function's benchmarks failing in the latest run
+    auto-deprecates it even when the static registry says `proven`/`parity` — a
+    `@remarks Auto-deprecated: N/M benchmarks failed ...` note records the drift.
+  - A single good run **never** removes an existing `@deprecated` (static
+    classifications reflect the shipped release build, not one local run). A
+    majority win on a static `not-competitive` function only adds a
+    `@remarks Promotion candidate ...` note.
+- Classifications are **build-dependent** (debug/SIMD builds distort ratios). The
+  annotator warns when the report carries no `buildFlavor`; confirm on a release
+  build (`bun run build`) or local perf build (`bun run build:perf`).
+
+### Bun built-ins diagnostic set ("don't reinvent the wheel")
+
+`bun run check` also races castrum ops against **Bun's native built-ins**
+(`Bun.hash`, `Bun.password`, `Bun.CryptoHasher`, `Bun.gzipSync`,
+`Bun.randomUUIDv7`) as a diagnostic set:
+
+- Task names use the **`diag:`** prefix (not `native:`/`rust:`) so
+  `check-proven`'s aggregation (which matches `PROVEN_SURFACE` rustTask names
+  and their `_`-suffixed variants) never picks them up — they are informational.
+- Sources: `src/baseline/tasks/bun-builtins.ts` (Bun-only baselines, guarded
+  with `typeof Bun` so the module still loads under Node),
+  `src/bench/tasks/bun-builtins.ts`, comparisons in `src/bench/comparisons.ts`.
+- **Runtime honesty guard**: a Bun API must be verified to actually execute real
+  work before its result is trusted. The first run produced false "wins"
+  (brotli 156x, validators 3-5x) because Bun 1.4 has **no**
+  `Bun.brotliCompressSync` and **no** `Bun.validators` — those pairs were
+  removed, not reported.
+- Results and the keep/delegate/add decisions live in
+  `docs/bun-builtins-decision-matrix.md`.
+
+### HTTP Benchmarks
+
+```bash
+# Run all HTTP scenarios
+bun run bench:http
+
+# Run specific scenario
+bun run bench:http:smoke     # Light load, quick health check
+bun run bench:http:stress    # High concurrency, short duration
+bun run bench:http:heavy     # Heavy JSON payloads
+bun run bench:http:crud      # CRUD operations
+bun run bench:http:spike     # Burst traffic patterns
+bun run bench:http:soak      # Long duration (endurance)
+bun run bench:http:storm     # Very high concurrency burst
+bun run bench:http:boundary  # Edge case payloads
+
+# Compare specific frameworks
+bun run bench:http:elysia    # Run only Elysia vs baseline
+bun run bench:http:ingress   # Run only Ingress vs baseline
+bun run bench:http:bun-only  # Run only raw Bun vs baseline
+
+# Run all heavy scenarios
+bun run bench:http:all-heavy
+```
+
+---
+
+## HTTP Benchmark Scenarios
+
+Each scenario targets a specific performance aspect:
+
+### 01-smoke
+- **Goal**: Quick health check (health, GET, POST mix)
+- **Duration**: ~10 seconds
+- **Concurrency**: up to 50
+
+### 02-load
+- **Goal**: Sustained mixed load (warm-up → sustain → cool-down)
+- **Duration**: ~120 seconds
+- **Concurrency**: up to 1,000
+- **Traffic**: GET/POST mix with cookies, health
+
+### 03-stress
+- **Goal**: Ramp to maximum throughput
+- **Duration**: ~100 seconds (5 × 20s ramp phases)
+- **Concurrency**: up to 10,000
+
+### 04-spike
+- **Goal**: Burst resilience (baseline → spike → recovery)
+- **Duration**: ~100 seconds
+- **Concurrency**: up to 8,000 (spikes up to 5,000 req/s)
+
+### 05-soak
+- **Goal**: Endurance/stability
+- **Duration**: ~600 seconds (10 minutes)
+- **Concurrency**: up to 1,000
+
+### 06-edge-cases
+- **Goal**: Malformed / edge-case payloads
+- **Duration**: ~30 seconds
+- **Concurrency**: up to 200
+- **Traffic**: invalid JSON, schema failures, 404/405/415/422, Unicode, oversize query
+
+### 07-cors-preflight
+- **Goal**: CORS preflight storm (allowed + disallowed origins)
+- **Duration**: ~30 seconds
+- **Concurrency**: up to 500
+
+### 08-rate-limit
+- **Goal**: Rate limiting (under limit → over limit → recovery)
+- **Duration**: ~40 seconds
+- **Concurrency**: up to 1,000
+
+### 09-large-payload
+- **Goal**: Large payload handling
+- **Duration**: ~30 seconds
+- **Concurrency**: up to 100
+- **Payload**: large binary + large JSON arrays
+
+### 10-mixed-realistic
+- **Goal**: Realistic mixed traffic (origins, cookies, auth)
+- **Duration**: ~60 seconds (ramp)
+- **Concurrency**: up to 5,000
+
+### 11-concurrent-burst
+- **Goal**: High-concurrency bursts with pauses
+- **Duration**: ~35 seconds
+- **Concurrency**: up to 8,000
+
+### 12-slowloris
+- **Goal**: Slow clients
+- **Duration**: ~60 seconds
+- **Concurrency**: up to 500
+
+### Heavy JSON scenarios (`13`–`20`)
+
+`13-heavy-json-nested` … `20-validation-storm` stress schema validation with nested, array-heavy, wide, CRUD-mix, spike, soak, large-body, and storm payloads. Run them with `bun run bench:http:heavy`.
+
+---
+
+## Interpreting Results
+
+### Report Format
+
+Results are saved to `bench/results/<framework>/<scenario>.bench.md` and include:
+
+```md
+# Benchmark Report: bun / 01-smoke
+
+| Metric | Value |
+|--------|-------|
+| Duration | 10.0s |
+| Requests | 125,432 |
+| Throughput | 12,543 req/s |
+| Mean Latency | 0.79ms |
+| p50 Latency | 0.72ms |
+| p95 Latency | 1.13ms |
+| p99 Latency | 2.45ms |
+| Max Latency | 15.67ms |
+| Errors | 0 |
+```
+
+### Comparison Reports
+
+When comparing multiple frameworks, differences are expressed as:
+
+- **Speedup**: `2.45x` (Rust is 2.45x faster than JS)
+- **Slowdown**: `0.82x` (Rust is 0.82x the speed of JS, i.e., 18% slower)
+- **% Improvement**: `+145%` throughput increase
+
+### Key Metrics
+
+| Metric | What It Measures |
+|--------|-----------------|
+| **Throughput** | Requests per second — higher is better |
+| **Mean Latency** | Average response time — lower is better |
+| **p50/p95/p99** | Percentile latencies — lower is better |
+| **Max Latency** | Worst-case response time — should be bounded |
+| **Error Rate** | Percentage of failed requests — should be 0% |
+
+---
+
+## Benchmark Architecture
+
+```
+bench.ts
+  └─ Loads benchmark tasks from src/bench/tasks/ (30 tasks)
+       ├── hashing.ts       Compare Rust fnv1a64 vs JS TextEncoder + hash
+       ├── validation.ts    Compare Rust validation vs validator library
+       ├── json.ts          Compare Rust sonic-rs vs JSON.parse
+       ├── http.ts          Compare Rust httparse vs manual
+       ├── complex.ts       Combined operations
+       ├── stress.ts        Concurrent load tests
+       └── ...              (aead, accept, compress, cookie-sign, csrf, encoding, etag,
+                            form, json-schema, jwt, media-type, multipart, password,
+                            streaming, template, url-join, ... — full list in docs/REPO_MAP.md)
+```
+
+Each task runs:
+1. **Warmup**: 100ms to JIT-compile JavaScript
+2. **Measurement**: Fixed duration (default 2000ms) in a tight loop
+3. **Operations counted**: Number of function calls completed
+4. **Result**: Ops/sec calculated from wall-clock time
+
+### Benchmark controls
+
+| Env / flag | Effect |
+|------------|--------|
+| `CASTRUM_BENCH_BATCH_SIZE` | Batch size for sub-µs operations (default `64`). Batching amortizes the timer/measurement overhead for very fast ops. |
+| `CASTRUM_BENCH_ANNOTATE=1` | After `bun run check`, auto-rewrite the `rust.*` JSDoc annotations from the fresh report (see "Performance-proven surface & auto-annotated JSDoc"). |
+| `HTTP_NO_SHAPE=1` | The HTTP load generator (`bench/load.ts`) skips response-shape `JSON.parse` for pure-throughput runs. |
+
+---
+
+## HTTP Server Architecture
+
+```
+bench/servers/
+├── bun-server.ts       # Raw Bun.serve with manual routing
+├── elysia-server.ts    # Elysia framework
+├── ingress-server.ts   # Ingress (this project) optimized handler
+└── shared.ts           # Shared route handlers
+```
+
+Each server implements the same routes for fair comparison:
+
+- `GET /` — Plain text hello
+- `GET /json` — JSON response
+- `POST /json` — Echo JSON body
+- `GET /id/:id` — Path parameter
+- `POST /users` — User creation
+
+---
+
+## Environment
+
+All benchmarks should be run on a dedicated machine for reproducible results:
+
+- **CPU**: Modern x86_64 (Intel/AMD) or Apple Silicon
+- **Memory**: 8GB+ RAM
+- **OS**: Linux (recommended) or macOS
+- **Bun**: Latest stable
+- **Rust**: Latest stable (via rustup)
+
+### Turbo Mode (Linux)
+
+For consistent results on Linux, disable CPU frequency scaling:
+
+```bash
+sudo cpupower frequency-set --governor performance
+```
+
+Run benchmarks, then restore:
+
+```bash
+sudo cpupower frequency-set --governor powersave

package/docs/ENVIRONMENT.md

@@ -0,0 +1,79 @@
+# Environment Variables Reference
+
+This document lists every environment variable read by the package and its
+example servers. All values are read once at module load; invalid values are
+warned about and replaced with the documented default.
+
+## Ingress server (`bench/servers/ingress-server.ts`)
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `INGRESS_TRUST_PROXY` | bool | `false` | **Opt-in.** When `true`, honors `X-Forwarded-For` / `X-Real-IP` for client-IP resolution. Keep **off** unless the server sits behind a trusted edge that strips these headers, otherwise clients can spoof arbitrary IPs for IP-based rate limiting. |
+| `INGRESS_REQUEST_ID_HEADER` | bool | `false` | Emit an `x-request-id` response header per request. The request ID is always generated internally; this only controls whether it is echoed to clients. |
+| `INGRESS_UNSAFE_ZERO_COPY` | bool | `false` | Enable zero-copy response bodies. **Not recommended** unless per-response output buffers are implemented; leave off for safety (bodies are copied by default). |
+| `INGRESS_OUTPUT_BUF_BYTES` | int | `131072` | Size of the Rust output buffer (min `65536`). If cookies + query + metadata JSON exceed this, `FLAG_BODY_TRUNCATED` is set and the request fails closed. |
+| `INGRESS_SECURITY_HEADERS` | bool | `true` | Emit the precomputed security headers (CSP, HSTS, X-Frame-Options, etc.). Disable only behind an edge that already sets them. |
+| `INGRESS_REUSE_PORT` | bool | `false` | Enable `SO_REUSEPORT` for multi-process deployments (spawn N processes, each with a distinct `INGRESS_WORKER_ID`). |
+| `INGRESS_LOG_REQUESTS` | bool | `false` | Write one JSON line per request to **stderr** (`{ts, kind, requestId, method, path, status, errorCode?, rateLimited?, ...}`). |
+| `INGRESS_METRICS` | bool | `false` | Write a periodic aggregate summary to **stderr** every 10s (`{ts, kind, total, rps, status, rateLimited, internalErrors}`). |
+| `INGRESS_HOST` | string | `0.0.0.0` | Bind address. |
+| `INGRESS_IDLE_TIMEOUT` | int | `30` | Idle keep-alive timeout in seconds (min `1`). |
+| `INGRESS_WORKER_ID` | int | `0` | Worker identifier (0–65535), mixed into request-ID generation to reduce collision risk across processes. |
+
+Boolean flags accept `1`/`true`/`yes`/`on` for true and `0`/`false`/`no`/`off`
+for false; anything else is warned about and falls back to the default.
+
+## Rust FFI thread pool
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `CASTRUM_RAYON_THREADS` / `RUST_RAYON_THREADS` (legacy `RUST_BENCH_RAYON_THREADS`) | int | `max(1, cores-1)` | Rayon thread pool size. The pool is process-wide and initialized **once** — the first use wins. With lazy init, call `rust.configure({ rayonThreads })` (or set this env) before the first batch operation. |
+| `CASTRUM_MAX_RAYON_THREADS` (legacy `RUST_BENCH_MAX_RAYON_THREADS`) | int | `cores` | Hard cap on rayon threads (native). |
+| `CASTRUM_PIN_CORES` (legacy `RUST_BENCH_PIN_CORES`) | (presence) | — | When set (Linux), pin rayon worker threads to distinct cores. |
+
+## Native transport selection (`src/native/ffi.ts`)
+
+`bun:ffi` is the PRIMARY transport under Bun; NAPI is the fallback (Node,
+`CASTRUM_FFI_MODE=napi`, or a failed bind-time self-test). `rust.transport()`
+reports the resolved transport (`"ffi"` / `"napi"`); `rust.ffiActive()` reports
+whether the ffi transport is live.
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `CASTRUM_FFI_MODE` (legacy `RUST_FFI_MODE`) | string | `auto` | Native transport selection: `auto` (default) — use `bun:ffi` on Bun, silently fall back to napi on bind/self-test failure (and always on Node); `ffi` — force `bun:ffi` on Bun and THROW if it cannot bind or the self-test fails (for benches/CI that must run the primary transport; invalid on Node); `napi` — never bind, every call goes through the napi addon (exercises the fallback on Bun). |
+
+## Native addon loader (`src/native/loader.ts`)
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `CASTRUM_DEBUG` (legacy `RUST_BENCH_DEBUG`) | (presence) | — | Log the resolved addon path and exported keys at load time. |
+| `CASTRUM_NATIVE_LIBRARY_PATH` / `NAPI_RS_NATIVE_LIBRARY_PATH` | path | — | Explicit path (file or directory) to the native `.node` artifact, overriding normal resolution. Useful for bundled/electron layouts. |
+
+## Library logging (`src/shared/log.ts`)
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `CASTRUM_LOG_LEVEL` | string | `info` | Threshold for the built-in structured logger (`debug`/`info`/`warn`/`error`/`silent`). Enabled per handler via the `structuredLog: true` runtime option; emits one JSON line per request/error to stderr (`{ts, level, event, requestId, method, path, status, durationMs, ...}`). |
+
+## Security guidance
+
+- **Proxy trust**: `trustProxy: true` is deprecated — it trusts EVERY hop of
+  `X-Forwarded-For`/`X-Real-IP`, so clients can forge their IP and bypass IP-based
+  rate limiting. Prefer `trustedProxies: { enabled: true, networks: [...] }` and only
+  enable proxy trust behind a trusted edge that strips these headers.
+- **Rate limiting is per-process, not distributed**: with N worker processes
+  (`reusePort`), an IP's effective limit is multiplied by N. The shared-limiter config
+  registry is bounded (LRU, max 16 distinct configs) to prevent unbounded memory growth.
+- **Request bodies**: `createIngressServer` applies a server-level `maxRequestBodySize`
+  default of 16 MiB, and JSON-write routes stream-read with `maxBodyBytes` enforced
+  while reading (an oversized body is rejected as soon as the limit is crossed, never
+  fully buffered). Route/async handlers apply a non-zero body-read deadline by default
+  (`bodyTimeoutMs`, default **30 s** — set `bodyTimeoutMs: 0` to disable) that guards
+  against slowloris/trickling bodies.
+- **Secrets (JWT/AEAD)**: keys and secrets are caller-owned buffers; treat them as
+  sensitive (never log them, rotate regularly). The AEAD **batch** APIs derive a unique
+  nonce per item, but callers MUST use a fresh base nonce for every batch call — never
+  reuse a base nonce with the same key.
+- **Multipart**: `multipart_parse` accepts an optional `limits` object
+  (`max_parts`, `max_field_count`, `max_part_bytes`, `max_total_bytes`) with generous
+  defaults to bound worst-case parse cost.

package/docs/GETTING_STARTED.md

@@ -0,0 +1,209 @@
+# Getting Started with castrum
+
+A walkthrough for a first-time contributor or intern. By the end you'll know
+how to import the package, use the `rust.*` primitives, stand up an HTTP
+server, run the benchmarks, and run the test suite. For the full file map see
+[`REPO_MAP.md`](./REPO_MAP.md).
+
+## Prerequisites
+
+- [Bun](https://bun.sh) ≥ 1.1 (primary runtime)
+- [Rust](https://rustup.rs) — stable + `cargo` (to build/test the addon). The
+  repo pins a toolchain in `rust-toolchain.toml` (`channel = "1.97.1"`); install
+  it with `rustup` so local builds match CI.
+- Node.js ≥ 20.3 (optional — only for the Node compatibility path)
+
+> **Building on different OSes**: `bun run build` (napi) works on Linux, macOS,
+> and Windows (WSL recommended on Windows). `bun run build:perf` shells out to
+> `bash scripts/build-perf.sh` and is **Linux-only** — it is a local max-perf
+> build, never for publish. If `bash` is unavailable, use plain `bun run build`.
+
+```bash
+bun install
+```
+
+## 1. Import the package
+
+The entry point is `index.ts` (Bun resolves it via the `bun` export condition).
+Node users get the compiled `dist/index.js`.
+
+```ts
+import { rust } from "castrum";
+```
+
+## 2. Use the Rust-accelerated primitives
+
+The flat `rust.*` namespace wraps every native function:
+
+```ts
+import { rust } from "castrum";
+
+rust.crc32(new TextEncoder().encode("hello"));     // number
+rust.fnv1a64(bytes);                               // bigint
+rust.jsonValid(bytes);                             // boolean
+rust.validateEmail(emailBytes);                    // boolean
+
+// Text helpers (string in / string out)
+rust.text.mimeFromExtension(".js");                // "text/javascript"
+rust.text.urlEncode("a b");                        // "a%20b"
+
+// Batch helpers (array of byte arrays → packed bitset/count)
+rust.batch.jsonValid([docA, docB, docC]);          // Uint8Array bitset
+rust.batch.fnv1a64([a, b]);                        // BigUint64Array
+rust.batch.etag([a, b]);                           // Uint8Array[]
+```
+
+Most functions accept `Uint8Array` (or strings via the `text.` namespace).
+Everything is **synchronous** — there is no async/await in the FFI surface.
+
+> **Transport**: under Bun these calls run through `bun:ffi` (the PRIMARY
+> transport — see `rust.transport()` / `rust.ffiActive()`); Node and any
+> `CASTRUM_FFI_MODE=napi` fall back to the napi addon. Surfaces with no C-ABI
+> export (instances, `rust.batch.*`/`packed.*`, `text.*`, structured scalars)
+> always use the napi addon.
+
+> **Tip**: `rust` is a singleton created with sensible defaults. If you need
+> isolated state (own rayon threads, own HMAC cache), call
+> `createRust({ rayonThreads: 4 })`.
+
+### Higher-order data loader (`loader`)
+
+For workloads that call the same op many times, `loader` gives you a hot,
+pre-bound function with automatic bulk-vs-scalar dispatch, DataLoader-style
+coalescing and a bounded LRU cache — over **44 ops** including paired and
+schema-validator ops:
+
+```ts
+import { loader } from "castrum";
+
+const isEmail = loader("validateEmail");
+isEmail(emailBytes);                              // scalar → boolean
+isEmail([a, b, c]);                               // bulk → ONE packed call
+await isEmail.load(a);                            // coalesced + cached
+
+loader.run("jsonPatch", docs, patches);           // paired ops (companion array)
+loader.schema(validator)(docs);                   // schema bitset (+ .count())
+```
+
+See the README "Higher-order data loader" section for the full op table and
+`createLoader` options.
+
+## 3. The `proven` performance surface
+
+Not every `rust.*` function beats the JS baseline on every CPU. `proven`
+exposes the **full** `rust.*` surface, and each function's JSDoc records its
+measured performance vs the JS baseline — functions that are slower carry
+`@deprecated`:
+
+```ts
+import { proven, PROVEN_SURFACE } from "castrum";
+
+proven.fnv1a64(bytes);   // JSDoc: ~11x faster than the JS baseline
+```
+
+`PROVEN_SURFACE` is the registry (pure data); `scripts/check-proven.ts`
+audits it against the CPU benchmark so it can't drift, and
+`scripts/annotate-performance.ts` (`bun run check:annotate`) refreshes the
+per-function JSDoc from the latest report.
+
+## 4. Stand up an HTTP server (the ingress pipeline)
+
+The quickest path is the **pre-baked** route handlers + the server builder:
+
+```ts
+import { createIngressHandler, createIngressServer } from "castrum";
+
+const ingress = createIngressHandler({
+  parseCookies: true,
+  parseQuery: true,
+  cors: { allowOrigin: ["https://app.example.com"] },
+});
+
+// createIngressServer is SYNCHRONOUS — it wraps Bun.serve over the routes.
+// Each route maps HTTP methods to the pre-baked handlers (see below):
+const server = createIngressServer({
+  port: 3000,
+  routes: {
+    "/health":    { read: ingress },                  // GET + HEAD
+    "/api/users": { read: ingress, write: ingress },  // + POST/PUT/PATCH (+OPTIONS)
+  },
+});
+
+console.log("listening on", server.port);
+```
+
+- `read: ingress` — GET (+ HEAD) returns the ingress body JSON.
+- `write: ingress` — POST/PUT/PATCH validates + echoes JSON.
+- `echo: ingress`, `cookies: ingress`, and a top-level `fallback` are the other
+  route options. The underlying factories (`readHandler`, `jsonWriteHandler`,
+  `echoHandler`, `headHandler`, `fallbackHandler`) are also exported directly
+  if you'd rather wire methods by hand.
+- **Bun-only**: `createIngressServer`. **Node**: use `createIngressServerNode`
+  with the same `routes` spec (and `await srv.ready` for the port).
+
+The wire format is `{"ok":true,...,"requestId":...}` on success and
+`{"ok":false,"error":{code,message}}` on errors, with `ratelimit-*` headers.
+
+> There is also a lower-level **fast path** (`createIngressFast` +
+> `createIngressSync`/`createIngress`). Prefer it only when you need the
+> absolute lowest overhead and are comfortable calling `run()` yourself with a
+> synchronous callback.
+
+## 5. Run the benchmarks
+
+```bash
+# CPU benchmark (correctness checks + comparisons) — also gates `proven`
+bun run check
+
+# HTTP benchmark across all servers (bun / elysia / ingress)
+bun run bench:http
+
+# Fast HTTP smoke (the CI wire-format guard)
+bun run bench:http:smoke
+```
+
+Results land in `bench/results/` (gitignored).
+
+## 6. Run the tests
+
+```bash
+# Everything at once (TS unit + Rust unit + typecheck + lint)
+bun run test:all
+
+bun test          # TypeScript unit tests (test/unit/**)
+bun run test:rust # Rust unit tests (cargo test)
+bun run typecheck # TypeScript typecheck
+bun run lint:ci   # Biome lint gate (what CI enforces)
+bun run test:node # Node.js integration tests (node --test) — run `bun run build:js` first
+```
+
+## 7. Make your first change
+
+1. Find where the code lives with [`REPO_MAP.md`](./REPO_MAP.md).
+2. Edit the TypeScript (`src/`) and/or Rust (`rust/`).
+3. If you changed Rust, rebuild the addon: `bun run build:debug`.
+4. Run `bun test`, `bun run typecheck`, and `cargo test`.
+5. If you touched any server or `handlers.ts`, run `bun run bench:http:smoke`.
+6. If you changed a public function, update the `PROVEN_SURFACE` registry
+   (`src/shared/proven.ts`) and run `bun run check:proven:fail` on a release
+   build (`bun run build`).
+7. Format + lint: `bun run format` and `bun run lint`.
+
+## Common gotchas
+
+- The **two ingress paths** have different wire formats — don't unify them
+  (see REPO_MAP §4.2 and AGENTS.md).
+- `tsconfig.json` typechecks `index.ts`, `bench.ts`, and `src/` (so `bench/` IS
+  covered by `bun run typecheck`); `test/` + `bench/` are covered by
+  `bun run typecheck:test` (`-p tsconfig.test.json`).
+- `src/ingress/constants.ts` dlopens the addon at import time — that's
+  intentional.
+- The native addon must be rebuilt (`bun run build:debug`) before tests that
+  touch Rust changes will see them.
+
+## Next steps
+
+- [`REPO_MAP.md`](./REPO_MAP.md) — where everything is and how it connects
+- [`INGRESS.md`](./INGRESS.md) — the full pre-baked ingress API
+- [`ARCHITECTURE.md`](./ARCHITECTURE.md) — deep-dive internals
+- [`AGENTS.md`](../AGENTS.md) — agent/contributor guidance