castrum 0.9.1 → 0.9.2

package/docs/INGRESS.md

@@ -83,7 +83,7 @@ provides ready-made route handlers, response builders, and a `Bun.serve`
 builder — no need to hand-build responses, header templates, or error bodies.
 
 All of these are exported from the package root and are **re-exported from the
-benchmark server** (`bench/servers/ingress-server.ts`), which itself is built
+benchmark server** (`bench/http/servers/ingress-server.ts`), which itself is built
 entirely from them:
 
 ```ts
@@ -106,7 +106,7 @@ createIngressServer({
 });
 ```
 
-> **Wire format** (a contract — `bench/load.ts` depends on it):
+> **Wire format** (a contract — `bench/http/load.ts` depends on it):
 > - Success (with `emitMetadataJson: true` — the bench enables it): the body is
 >   Rust-generated `{"ok":true,"requestId":"...",...}`. With the DEFAULT
 >   `emitMetadataJson: false` the success body is **empty** (lean reads) — serve
@@ -138,6 +138,9 @@ native options as `createIngressFast` (`trustProxy`, `https`,
 | `onResponse` | `(req, result, status, requestId) => void` | — | Hook invoked after a `Response` is produced (metrics/logging) |
 | `onError` | `(req, requestId, error) => void` | — | Hook invoked when the native pipeline fails (silent 500s are otherwise invisible) |
 | `structuredLog` | `boolean` | `false` | Emit one JSON line per request/error (gated by `CASTRUM_LOG_LEVEL`) |
+| `logger` | `StructuredLogger` | — | Custom structured logger (custom stream/extra fields); implies `structuredLog: true` |
+| `maxInFlight` | `number` | `0` (unlimited) | Hard cap on concurrently borrowed zero-copy output buffers (`BufferPool.maxInFlight`); exceeding it fails requests with 500 instead of allocating unbounded temporaries |
+| `zeroCopyTimeoutMs` | `number` | `0` (disabled) | Abandonment guard (ms) for zero-copy responses: unread/cancelled bodies release their pooled buffer and close the stream |
 
 Returns an `OptimizedIngressHandler`:
 
@@ -288,7 +291,7 @@ rendering).
 > (`createIngressServer`) and Node (`createIngressServerNode`). Raw handlers
 > are served for GET only and skip the ingress pipeline / OPTIONS preflight.
 > See `examples/basic-server.ts` and the bench ingress server
-> (`bench/servers/ingress-server.ts`), which wire `/metrics` + `/healthz`
+> (`bench/http/servers/ingress-server.ts`), which wire `/metrics` + `/healthz`
 > `/readyz` `/livez` end-to-end.
 
 **Tracing** — W3C trace-context helpers: `parseTraceParent(header)`,

package/docs/NATIVE-ROUTE.md

@@ -39,13 +39,37 @@ first-failure-wins in stage order.
 - `castrum_route_compile` / `castrum_route_run` / `castrum_route_destroy`
   (C-ABI, needed-size convention, panic-guarded, immutable `&self` run).
 - napi `Route` class (Node / fallback path).
+- **Public castrum surface (`createNativeRoute`, `nativeRouteHandler`)**:
+  the stack is now a first-class castrum API, not just the ignex wire.
+  - `createNativeRoute(plan)` (`src/ingress/native-route.ts`) compiles a
+    route-wire v3 descriptor once and runs each frame in ONE native call —
+    `run(query, cookie, body)` / `runFrame(frame)` return the decoded verdict
+    (flags + errorCode + query/cookie pairs); `destroy()` frees the handle.
+    The pure wire helpers (`encodeRouteDescriptor`, `packRouteFrame`,
+    `decodeRouteResult`, layout constants) live in
+    `src/ingress/packing/route-wire.ts`.
+  - `nativeRouteHandler(plan, responder, opts)` (`src/ingress/routes/native.ts`)
+    wraps a compiled route as a `RouteHandler`: extracts the query substring +
+    Cookie header, runs the tiny frame, rejects 400/422 on verdict failure,
+    and hands the decoded snapshot to the responder for the 2xx.
+  - `createIngressRouter`'s `native` route spec wires it into a server (see
+    `INGRESS-ROUTER.md`). Measured: ~580ns cheaper per request than the
+    full-pipeline responder on a parseQuery+parseCookies route, and **+34%
+    RPS at the HTTP level** on the bench server's `/api/native` vs `/api/users`
+    (server-bound config, 2000 connections).
+  - Trade-off (deliberate): the native stack does NOT do CORS, rate limiting,
+    security headers, IP trust, or the castrum metadata envelope — routes that
+    need those must use the full pipeline. The lean path is for routes where
+    the framework owns the response body and only needs parse + verdict.
 
 ## Tests / parity
 
-- `rust/ingress/native_route.rs` unit tests + `rust/ffi.rs` C-ABI tests.
-- `test/unit/ingress/native-route.test.ts`.
-- `scripts/verify-native-route.ts` + ignex's `route-wire.test.ts` /
-  `packages/native/test/route.test.ts`.
+- `rust/ingress/native_route.rs` unit tests + `rust/ffi/` C-ABI tests.
+- `test/unit/ingress/native-route.test.ts` (wire round-trip + lenient parity).
+- `test/unit/ingress/native-route-public.test.ts` (public surface + router
+  `native` kind).
+- External parity: ignex's `route-wire.test.ts` /
+  `packages/native/test/route.test.ts` (in the `@ignex/native` repo).
 
 > **Naming note (flux → ignex)**: the external consumer was historically called
 > `@flux/native` (castrum v0.8.0, guarded by `test/compat/flux-contract.test.ts`).

package/docs/REPO_MAP.md

@@ -14,14 +14,14 @@ agent editing this repo, [`AGENTS.md`](../AGENTS.md) is the agent-facing map.
 
 - A **Rust cdylib** (`castrum.<platform>-<arch>.node`, built with napi-rs,
   ALSO exporting `extern "C"` symbols for Bun's `bun:ffi` — see
-  `rust/ffi.rs`) provides the performance-critical primitives (parsers,
+  `rust/ffi/`) provides the performance-critical primitives (parsers,
   crypto, hashing, JSON, compression, and the HTTP **ingress pipeline**).
   Under Bun, `bun:ffi` is the PRIMARY transport; NAPI is the fallback
   (Node, `CASTRUM_FFI_MODE=napi`, or a failed ffi self-test).
 - **TypeScript** (`src/`) provides the ergonomic public API: the flat `rust.*`
   FFI client and the ingress layer.
 - It ships benchmarks: a **CPU benchmark** (`bench.ts` → `src/bench`) and an
-  **HTTP benchmark** (`bench/run-bench.ts` + `bench/servers/*`).
+  **HTTP benchmark** (`bench/http/run-bench.ts` + `bench/http/servers/*`).
 
 Bun is the primary runtime; Node.js ≥20.3 is supported via a compiled ESM entry
 (`dist/`).
@@ -37,7 +37,7 @@ Bun is the primary runtime; Node.js ≥20.3 is supported via a compiled ESM entr
 | Build Rust addon (LOCAL max perf) | `bun run build:perf` | x86-64-v3 + AVX2 — **never for publish** |
 | Build Rust addon (debug) | `bun run build:debug` | |
 | Build compiled JS entry (Node) | `bun run build:js` | bundle + types → `dist/` (gitignored) |
-| TS unit tests | `bun test` | ~540 tests, `test/unit/**` |
+| TS unit tests | `bun test` | ~760 tests, `test/unit/**` |
 | Rust unit tests | `bun run test:rust` | `cargo test`, ~440 tests |
 | Node smoke tests | `bun run test:node` | explicit `.mjs` paths (Node 24 rejects dir arg) |
 | Installed-tarball e2e | `bun run verify:install` | pack → install → import from `node_modules` |
@@ -45,6 +45,8 @@ Bun is the primary runtime; Node.js ≥20.3 is supported via a compiled ESM entr
 | CPU benchmark + correctness | `bun run check` | == `bun bench.ts`; writes `bench/results/cpu/` |
 | HTTP bench (all servers) | `bun run bench:http` | |
 | HTTP smoke (fast sanity) | `bun run bench:http:smoke` | **the wire-format guard** (CI-gated) |
+| FFI transport benches | `bun run bench:ffi` / `bench:ffi:load` / `bench:ffi:public` / `bench:ffi:workers` / `bench:margin` | `bench/ffi/` |
+| Ingress cost benches | `bun run bench:ingress-cost` / `bench:ingress-cost:post` / `bench:router` | `bench/cost/` |
 | Startup bench | `bun run bench:startup` | import + first-call timing |
 | JS lint (Biome) | `bun run lint` / `lint:fix` | `bunx biome check [--write] .` |
 | JS format (Biome) | `bun run format` | `bunx biome format --write .` |
@@ -71,9 +73,13 @@ src/
     types.ts              NativeAddon module-surface interface (mirrors index.d.ts).
     types/instances.ts    Per-class INSTANCE types (Ingress, SchemaValidator, JwtSigner, ...) + result types.
     loader.ts             Addon path resolution (multi-root) + getAddon()/lazyAddon().
-    ffi.ts                bun:ffi C-ABI bindings (Bun-only): lazy bind + bind-time self-test,
-                          CASTRUM_FFI_MODE gating, castrum_ingress_layout blob for constants.ts.
-    ffi/                  ffi/types.ts (BunFFI interface) + constants.ts + selftest.ts (bind-time self-test).
+    ffi.ts                bun:ffi C-ABI transport core (Bun-only): mode resolution, buffer/buffer_length
+                          probe, bind() orchestration (self-test + CASTRUM_FFI_MODE gating + napi fallback).
+    ffi/                  Decomposed bind surface: types.ts (BunFFI interface) + constants.ts +
+                          selftest.ts (thin aggregator) + build.ts (orchestrator) +
+                          build/{util,codecs,compress,parse,instances}.ts — per-domain method builders
+                          EACH with its self-test* function, so a new castrum_* symbol is bound AND
+                          self-tested in one domain file.
     index.ts              Barrel.
   runtime/                THE RUNTIME ADAPTER seam (Bun/Node) — selected once at load.
     detect.ts             Cached runtime detection — the ONLY place `typeof Bun` is checked.
@@ -108,21 +114,31 @@ src/
     buffer-pool.ts        Generic reusable byte-buffer pool (pooled ingress output).
     response.ts           pooledBodyResponse (releases the pool on body consume).
     log.ts                createStructuredLogger (CASTRUM_LOG_LEVEL-gated JSON lines).
+    metrics.ts            Zero-dep metrics registry (counters/gauges/histograms + Prometheus render).
+    trace.ts              W3C traceparent/span-id helpers.
+    env.ts                Centralized env-var resolution (CASTRUM_* + NAPI_RS_NATIVE_LIBRARY_PATH).
+    proven.ts             Baked benchmark-proven op selection (PROVEN_SELECTION — pure data).
+  loader/                 Higher-order-function data loader (HFC) over the curated op set.
+    index.ts              Dispatch core + factory (scalar/bulk dispatch, coalescing, LRU cache).
+    ops.ts                Op registry (LOADER_OPS) + type tower; state.ts / cost.ts / batch.ts / types.ts.
   ingress/                The HTTP ingress pipeline (two paths — see §4.2).
     fast.ts               PATH 1: createIngressFast (packed-input via handleRequestPacked).
     handlers.ts           PATH 2: createIngressHandler (JS-packs the frame via IngressInputPacker
-                          + gatherRawHeadersPacked → handleRequestPacked).
-    index.ts              Barrel + createIngress / createIngressSync convenience factories.
+                          + gatherRawHeadersPacked → handleRequestPacked); response builders
+                          extracted to response/baked-response.ts.
+    index.ts              Pure public barrel (all re-exports).
+    sync.ts               createIngressSync / createIngress convenience factories (path 1 wrapper).
     shared.ts             JS constants + buildHeaderPlan + assertSyncCallback (shared by both paths).
     constants.ts          Binary-layout constants read from Rust at runtime (SINGLE SOURCE).
     status.ts / errors.ts / options.ts / types.ts / body.ts / context.ts
     packing/              header-packing.ts, input-packer.ts, gather-raw-headers.ts
-    headers/              cors.ts, hsts.ts, fast-templates.ts, baked-templates.ts
+    headers/              cors.ts, hsts.ts, security.ts (baked security merge), fast-templates.ts, baked-templates.ts
     decode/               fast-result.ts, baked-result.ts   (TWO decoders — see §4.2)
-    response/             terminal.ts, error-bodies.ts
-    routes/               read/head/json-write/echo/fallback factories + common.ts
+    response/             terminal.ts, error-bodies.ts, baked-response.ts (pre-baked response builders)
+    routes/               read/head/json-write/echo/fallback factories + common.ts + responder.ts
     server.ts             createIngressServer (Bun.serve) + buildRouteHandlers + gracefulShutdown.
     server-node.ts        createIngressServerNode (node:http adapter, same route handlers).
+    path-matcher.ts       buildPathMatcher + PathMatch + safeDecode (shared by server-node + router).
   integration/            Framework integration (wraps path 2 — createIngressHandler).
     pipeline.ts           createPipeline (framework-agnostic request stage for Hono/Elysia/Bun.serve).
     websocket.ts          createWebSocketUpgrade (RFC 6455 101 handshake + subprotocol).
@@ -135,22 +151,33 @@ src/
 ```
 rust/                     ONE cdylib crate (Cargo [lib] → lib.rs).
   lib.rs                  Declaration hub + module map + crate docs.
-  util/                   Shared infrastructure: bytes, packed, batch (+batch_core), threadpool, validation.
+  selection.rs            Rust-side op selection metadata (mirrors src/selection.json).
+  util/                   Shared infrastructure: bytes, packed, batch/ (api.rs + core.rs + tests.rs),
+                          threadpool, validation.
   http/                   HTTP wire formats & parsing: headers, method, http/cookie/query parsers,
-                          form, media_type, url_codec, url_join, etag, accept, mime_lookup, multipart.
-  crypto/                 Auth & hashing: hmac_sha256, cookie_sign, csrf, jwt, aead, argon2,
-                          base64, hashing (fnv/crc32/xxh3), random_token.
-  json/                   JSON & schema: json_ops, json_ser, json_patch_ops, json_schema (napi),
+                          form, media_type, url_codec, url_join, http_date, etag, accept,
+                          mime_lookup, multipart.
+  crypto/                 Auth & hashing: hmac_sha256, cookie_sign, csrf, jwt/ (token.rs + api.rs +
+                          tests.rs), aead, argon2, base64, ed25519, hashing (fnv/crc32/xxh3),
+                          random_token.
+  json/                   JSON & schema: json_ops, json_ser, json/patch/ (pointer.rs + ops.rs +
+                          engine.rs + api.rs + tests.rs), json_schema (napi),
                           fast_schema/ (zero-DOM engine — pure, no napi).
   payload/                Output & streaming: compress, sse, ws_frames, websocket, template.
-  ingress/                THE ingress pipeline: mod.rs (napi boundary), pipeline.rs (core 8-stage),
-                          options/time/packed, cors, proxy, ip_trust, rate_limit, terminal,
-                          output.rs (single numeric layout source), ingress_constants.rs (napi projection).
-  ffi.rs                  #[no_mangle] extern "C" exports (79 castrum_* symbols — 71 direct + 4
+  ingress/                THE ingress pipeline: api.rs (Ingress/IngressInner napi class) + mod.rs
+                          (declaration hub), pipeline.rs (core 8-stage), native_route.rs (per-route
+                          native stack), options/time/packed, cors, proxy, ip_trust, rate_limit,
+                          terminal, output.rs (single numeric layout source),
+                          ingress_constants.rs (napi projection).
+  ffi/                    #[no_mangle] extern "C" exports (85 castrum_* symbols — 77 direct + 4
                           validator_c_abi! + 4 compress_to_out!; parity guarded by
-                          test/unit/features/ffi-symbol-parity.test.ts) for Bun's bun:ffi
+                          test/unit/native/ffi-symbol-parity.test.ts) for Bun's bun:ffi
                           primary transport, incl. castrum_ingress_layout (the layout blob).
-  unit_tests.rs / test_support.rs   Cross-module Rust test suites.
+                          mod.rs (module map) + util.rs (panic_guard / HMAC cache / cstring helpers)
+                          + per-domain wrappers (hashing/validators/crypto/jwt/http/payload/json/
+                          rate_limit/ingress/route/probe) + tests.rs.
+  panic_safety.rs / test_support.rs   Cross-module fuzz + shared #[cfg(test)] helpers.
+  proptest_suite.rs      Property-based adversarial-parser tests (dev-dep proptest).
 ```
 
 ### Generated / ignored (do NOT edit)
@@ -160,7 +187,7 @@ rust/                     ONE cdylib crate (Cargo [lib] → lib.rs).
 | `dist/` | Compiled ESM entry + types for Node | Built by `build:js`; gitignored |
 | `index.js` / `index.d.ts` | NAPI-RS generated loader/declarations | Regenerated by `napi build`; gitignored |
 | `castrum.<platform>-<arch>.node` | The native addon binary | Built locally; gitignored |
-| `bench/results/` | Bench reports (cpu/, http/) | Generated; gitignored |
+| `bench/results/` | Bench reports (cpu/, per-server http/, ffi-margin/, router/, startup/, autocannon/) | Generated; gitignored |
 | `target/` | Cargo build output | gitignored |
 | `node_modules/` | Deps | gitignored |
 | `artifacts/` | CI publish staging dir | gitignored |
@@ -172,7 +199,7 @@ rust/                     ONE cdylib crate (Cargo [lib] → lib.rs).
 ### 4.1 Constants never drift (single numeric source)
 `rust/ingress/output.rs` defines every ingress layout constant once → projected
 to JS two ways: `rust/ingress/ingress_constants.rs` via `#[napi] const` (NAPI)
-AND `rust/ffi.rs` `IngressLayout` via `castrum_ingress_layout` (C ABI, primary
+AND `rust/ffi/` `IngressLayout` via `castrum_ingress_layout` (C ABI, primary
 on Bun) → `src/ingress/constants.ts` reads them at runtime (ffi blob on Bun,
 napi on Node). Drift is pinned by the Rust unit test
 `ingress_layout_c_abi_matches_output_source` and the bun:ffi bind-time
@@ -191,7 +218,7 @@ self-test. **Never hardcode a layout value** — if you change the layout, chang
    `{"ok":true,...,"requestId":...}` (success) / `{"ok":false,"error":{code,
    message}}` (errors) with `ratelimit-*` headers.
 
-These wire formats are a **benchmark contract** (`bench/load.ts` validates
+These wire formats are a **benchmark contract** (`bench/http/load.ts` validates
 them) — they are intentionally NOT unified. The two decoders
 (`decode/fast-result.ts` vs `decode/baked-result.ts`) and the two header-template
 builders (`headers/fast-templates.ts` vs `headers/baked-templates.ts`) exist for
@@ -235,16 +262,19 @@ consumed.
 
 ## 5. Testing & benchmarks
 
-- **TS**: `bun test` → `test/unit/**` (`ingress/`, `shared/`, `features/`).
+- **TS**: `bun test` → `test/unit/**` (`native/`, `rust-ffi/`, `contract/`,
+  `ingress/`, `shared/`, `integration/`) + `test/compat/` + `test/property/`.
+  See `test/README.md` for the intended split.
 - **Rust**: `cargo test` → per-module `#[cfg(test)] mod tests` + cross-module
-  `rust/unit_tests.rs`.
+  `rust/panic_safety.rs` (fuzz) + `rust/proptest_suite.rs`.
 - **Node**: `test/integration/node-smoke.test.mjs` + `node-enterprise.test.mjs`
   via `node --test` (run with `bun run test:node`).
 - **CPU bench**: `bun run check` (correctness checks + comparisons). Sub-µs ops
   are batched (`CASTRUM_BENCH_BATCH_SIZE`). Report → `bench/results/cpu/`.
-- **HTTP bench**: `bench/run-bench.ts` + `bench/load.ts` (load generator that
-  validates response SHAPE) + `bench/servers/{bun,elysia,ingress}-server.ts`.
-  `bench:http:smoke` is the fast CI wire-format gate.
+- **HTTP bench**: `bench/http/run-bench.ts` + `bench/http/load.ts` (load generator that
+  validates response SHAPE) + `bench/http/servers/{bun,elysia,ingress,router}-server.ts`.
+  `bench:http:smoke` is the fast CI wire-format gate. FFI-transport benches live in
+  `bench/ffi/`; per-request cost benches in `bench/cost/` (see `bench/README.md`).
 
 ---
 

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

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

package/docs/ai/LOCAL_DEV.md

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