castrum 0.9.2 → 0.9.4

package/docs/API.md

@@ -38,7 +38,7 @@ runtimes, and binary ops (`gzip*`, `brotli*`, `aead*`, `pbkdf2Sha256`,
 | `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. |
+| `encoder`, `decoder` | Codec-backed UTF-8 helpers (shared native `TextEncoder` / Bun: `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). |

package/docs/ARCHITECTURE.md

@@ -31,8 +31,9 @@ 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/`, 85 `castrum_*` symbols — 77 direct + 4
-  `validator_c_abi!` + 4 `compress_to_out!`, parity guarded by
+  `extern "C"` exports (`rust/ffi/`, 109 `castrum_*` symbols — 97 direct + 4
+  `validator_c_abi!` + 4 `validator_bytes_c_abi!` + 4 `compress_to_out!`,
+  parity guarded by
   `test/unit/native/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.

package/docs/CASE_STUDY.md

@@ -42,8 +42,8 @@ as a pre-baked pipeline, and still be usable from both runtimes.
 ### 2.1 One cdylib, two transports
 
 The addon is built with napi-rs (so Node can load it), but it *also* exports
-`extern "C"` symbols (`rust/ffi/`, **85 `castrum_*` symbols** — 77 direct + 4
-`validator_c_abi!` + 4 `compress_to_out!`) so Bun can
+`extern "C"` symbols (`rust/ffi/`, **109 `castrum_*` symbols** — 97 direct + 4
+`validator_c_abi!` + 4 `validator_bytes_c_abi!` + 4 `compress_to_out!`) so Bun can
 `dlopen` it directly:
 
 - **`bun:ffi` (primary on Bun)** — Bun JIT-calls the C-ABI exports at

package/docs/ENVIRONMENT.md

@@ -72,6 +72,22 @@ whether the ffi transport is live.
 |----------|------|---------|-------------|
 | `CASTRUM_PUBLISH_ALLOW_PARTIAL` | bool | — | When `1`, `prepublishOnly` ships a tarball containing only the locally-built platforms instead of failing on the full `napi.targets` set. Set automatically by `bun run publish:manual`; **never** set it for a normal `npm publish`.
 
+## Postinstall fallback build (`scripts/postinstall.mjs`)
+
+The package ships prebuilt addons for every `napi.targets` platform (built by
+the CI "build" job on push/PR and staged into the tarball on a `v*` tag push).
+`postinstall` is a fast no-op when a matching prebuilt is present. When none
+ships for the host (an exotic platform / libc, or a partial tarball), it
+compiles the addon **from source** in the consumer's `node_modules` via
+`cargo build --release` (needs a Rust toolchain + crates.io access).
+
+| Variable | Type | Default | Description |
+|----------|------|---------|-------------|
+| `CASTRUM_SKIP_BUILD` | (presence) | — | Skip the source-build fallback entirely (warn and continue). Use when a Rust toolchain is intentionally unavailable; the runtime loader will then fail with a clear "build it" error if the addon is needed. |
+| `CASTRUM_REQUIRE_BUILD` | (presence) | — | Turn every postinstall "warn and skip" (missing toolchain, build failure, missing cdylib) into a hard install failure — for environments that must guarantee a loadable addon. |
+| `npm_config_build_from_source` | bool | — | Set by `npm install --build-from-source`; forces a rebuild even when a prebuilt artifact is present. |
+| `CI` | bool | — | GitHub Actions (and other CI) set this; the postinstall skips the fallback build because CI builds the addon explicitly (`bun run build`). |
+
 ## Security guidance
 
 - **Proxy trust**: `trustProxy: true` is deprecated — it trusts EVERY hop of

package/docs/FFI_BUN_GUIDE.md

@@ -99,14 +99,23 @@ the matching shape and nothing else:
    (no copy). **Benchmark-gated** (`bench:margin` `cstringArg` scenario):
    ~40–52 ns/call vs ~209–233 ns for `encodeUtf8` + `(ptr,len)` — a ~76–82% win,
    including non-ASCII inputs. It is a LOSS for BYTE inputs (decode + re-encode)
-   — keep `(ptr,len)` there. **Verified `bun:ffi` facts**: JS `null` → NULL
-   pointer, and JS `''` (empty string) → NULL too — a present-but-empty value is
-   indistinguishable from absent through a `cstring` arg (so SSE's `Option`
-   event/id semantics stay on `(ptr,len)`). Adopted by: the validators
-   (`castrum_validate_*`), `castrum_ws_accept_key`, `castrum_mime_from_extension`,
+   — keep `(ptr,len)` there (the validators ship BOTH shapes:
+   `castrum_validate_*` for strings, `castrum_validate_*_bytes` for bytes).
+   **Verified `bun:ffi` facts**: JS `null` → NULL pointer, and JS `''` (empty
+   string) → NULL too — a present-but-empty value is indistinguishable from
+   absent through a `cstring` arg UNLESS a presence flag crosses alongside it.
+   Adopted by: the validators (`castrum_validate_*`),
+   `castrum_ws_accept_key`, `castrum_mime_from_extension`,
    `castrum_password_verify_bcrypt` (phc), `castrum_rate_limiter_check` (key),
    and `castrum_ingress_handle_components` (url/ip).
 
+   > **CASE STUDY — a conversion we REVERTED (2026-08-23)**: SSE's event/id
+   > were converted to `cstring` ARGs (+ presence flags) and shipped briefly,
+   > then reverted. The conversion itself was sound; what failed was the dev
+   > loop — see §14. Every "bun:ffi is broken" signal during that episode
+   > traced back to a mismatched addon↔JS state, never to the engine. Do not
+   > cite this as an engine bug.
+
 Opaque instance handles are passed as a **bare `usize`** (`inner: usize`), and
 must be null-checked at the top of the function (return the `0` sentinel) —
 castrum's `castrum_ingress_handle_packed` / `castrum_*_matcher_matches` etc.
@@ -328,8 +337,82 @@ Rust-based runtime family. Castrum's own measurements live in `bench/`.
 **Verify after any FFI change**:
 
 ```bash
-nm -D --defined-only <addon> | grep -c castrum_   # = 85
+nm -D --defined-only <addon> | grep -c castrum_   # = 109
 bun run bench:http:smoke                           # after touching decoders/handlers
 bun test test/unit/native/ffi.test.ts            # FFI↔napi parity + self-test
 bun test test/unit/native/ffi-symbol-parity.test.ts
 ```
+
+---
+
+## 14. Changing an existing symbol's ABI — the desync hazard (post-mortem 2026-08-23)
+
+Adding or re-signing a `castrum_*` symbol means touching **Rust and the JS
+dlopen map in lockstep**. `bun:ffi` performs ZERO runtime validation of the
+declared ABI: if the addon on disk and `src/native/ffi.ts` disagree — arity,
+arg order, or arg type — the call still crosses, the callee reads your scalar
+as a pointer (or vice versa), and the process **segfaults**. This is not a
+Bun bug; it is inherent to raw FFI, and it is why the bind-time self-test is
+mandatory.
+
+### The 2026-08-23 incident (recorded so nobody repeats it)
+
+Converting `castrum_sse_encode_into`'s event/id to `cstring` args triggered
+repeated SIGSEGVs that looked like an engine bug ("crash at address 0x5/0x6",
+flaky across runs, "raw bindings pass but the package crashes"). After a full
+root-cause pass, **every** crash traced to a development-loop desync — never
+to bun:ffi itself:
+
+1. **Half-updated trees**: rebuilding the Rust side while the JS map (or a
+   scratch probe) still declared the old signature — e.g. after `git stash`
+   / `git checkout` of one side. The callee then dereferenced a small integer
+   argument as a pointer: crash addresses literally equalled values passed in
+   earlier calls (`0x5`, `0x6`).
+2. **Probe methodology bugs**: shell probes treated ANY non-zero exit as a
+   crash — including clean `TypeError: Symbol "<key>" not found` failures
+   from a misnamed dlopen-map key. Several "crashes" were exit-code-1
+   TypeErrors.
+3. **A mid-session runtime auto-update** (Bun canary replaced under us),
+   invalidating comparisons across runs.
+
+The minimal C-dylib control experiment bound every suspect signature shape
+(`cstring` leading/middle/trailing, mixed with `buffer`/`buffer_length`,
+`u64_fast` returns) against trivial exports: all marshaled correctly on Bun
+1.4.0/1.4.1 canaries. **No engine bug exists to report.**
+
+### Rules for any ABI change (signature, arg order, or type)
+
+1. **Treat Rust signature + JS dlopen-map entry + JS wrapper as ONE commit.**
+   Never run anything that binds (`bun test`, benches, `import castrum`)
+   between editing one side and the other.
+2. **Rebuild before you bind**: after ANY `rust/ffi/**` edit (including
+   reverting one via git), run `bun run build` before running tests. A stale
+   `castrum.*.node` next to fresh JS is a guaranteed segfault, not an error.
+3. **Fail loudly while debugging**: use `CASTRUM_FFI_MODE=ffi`. In `auto`
+   mode a failed bind/self-test silently falls back to napi — which masks
+   breakage as mysterious slowness or wrong-path results instead of an error.
+4. **Know the failure signatures**:
+   - `SIGSEGV at a tiny address (0x5–0xB)` right after a binding → almost
+     always an ABI mismatch; check `git status rust/ src/native/ffi.ts` and
+     rebuild before theorizing about the engine.
+   - `Symbol "<name>" not found` at dlopen → key/name drift (parity test's
+     domain).
+   - ffi silently off → self-test returned false; run with
+     `CASTRUM_FFI_MODE=ffi` to get the throw instead of the fallback.
+5. **Known guard gap**: `test/unit/native/ffi-symbol-parity.test.ts` checks
+   symbol NAMES (rust exports ⊆ dlopen map ⊆ self-test), NOT arities/types.
+   Arity drift surfaces only at call time — as a crash. When changing a
+   signature, update BOTH sides plus the self-test vectors in the same edit,
+   and let `bun test test/unit/native/ffi.test.ts` (FFI↔napi parity) catch
+   value divergence.
+6. **Probe discipline when investigating**: distinguish crash from failure
+   explicitly (exit code 139 + `Segmentation fault` line vs exit 1 +
+   stderr), verify `bun --version` before AND after long sessions (canary
+   auto-updates invalidate comparisons), and test hypotheses against a
+   minimal dylib before blaming the engine.
+7. **No repo-wide auto-fixers mid-investigation**: `bun run lint:fix`
+   rewrites import order across ~90 files; in this codebase import ORDER
+   carries side-effect semantics (eager-dlopen contract). Scope formatters
+   to your changed files, and treat mass diffs appearing during a debug
+   session as a variable to eliminate (revert them) before drawing
+   conclusions.

package/docs/REPO_MAP.md

@@ -169,8 +169,8 @@ rust/                     ONE cdylib crate (Cargo [lib] → lib.rs).
                           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
+  ffi/                    #[no_mangle] extern "C" exports (109 castrum_* symbols — 97 direct + 4
+                          validator_c_abi! + 4 validator_bytes_c_abi! + 4 compress_to_out!; parity guarded by
                           test/unit/native/ffi-symbol-parity.test.ts) for Bun's bun:ffi
                           primary transport, incl. castrum_ingress_layout (the layout blob).
                           mod.rs (module map) + util.rs (panic_guard / HMAC cache / cstring helpers)

package/index.ts

@@ -11,50 +11,44 @@
 // load. Do NOT add more eager-native modules; keep everything else lazy (see
 // test/unit/features/import-contract.test.ts).
 
+export * from './src/ingress'
+// Framework-agnostic integration helpers: run the ingress pipeline as a
+// request stage (createPipeline), RFC 6455 upgrade (createWebSocketUpgrade),
+// and SSE framing (sseResponse). See docs/INGRESS.md.
+export * from './src/integration'
+// Higher-order loader (HFC) over the curated op set: createLoader / loader
+// dispatch single items, packed batches, and load() coalescing. See README.
+export * from './src/loader'
 export * from './src/rust-ffi'
-
+export type { OpDecision, OpImpl } from './src/selection'
 // Native-vs-JS selection (OWNED HERE, not by consumers): `opImpl(op)` is the
 // benchmark-driven recommendation for which operations should use the Rust
 // addon vs a pure-JS implementation. Consumers read it once at load time and
 // bind each op to a fixed impl. Source: rust/selection.rs (audited by
 // `bun run check:selection`). See src/selection.ts.
-export { opImpl, isNativeOp, opDecision } from './src/selection'
-export type { OpImpl, OpDecision } from './src/selection'
-
-export { encoder, decoder } from './src/shared/bytes'
+export { isNativeOp, opDecision, opImpl } from './src/selection'
+export type { AdaptiveEstimateOptions } from './src/shared/adaptive'
 // Bounded EWMA adaptive-estimate utility (drives BufferPool adaptive sizing
 // and reusable runtime self-optimization decisions).
 export { AdaptiveEstimate } from './src/shared/adaptive'
-export type { AdaptiveEstimateOptions } from './src/shared/adaptive'
-// UUIDv7 generation — delegates to Bun.randomUUIDv7, crypto.randomUUID on Node.
-export { uuidv7 } from './src/shared/uuid'
+export { decoder, encoder } from './src/shared/bytes'
+export type { Counter, Gauge, Histogram, MetricsRegistry } from './src/shared/metrics'
 // Zero-dep metrics registry (counters/gauges/histograms + Prometheus render).
 export { createMetrics, DEFAULT_BUCKETS } from './src/shared/metrics'
-export type { MetricsRegistry, Counter, Gauge, Histogram } from './src/shared/metrics'
-
+export type { Pair, ParsedHttpRequestPacked } from './src/shared/packed'
 export {
   packBatch,
   packPairs,
-  readPairsPacked,
-  readHttpPacked,
   pairsToObject,
-  parseQueryString,
   parseCookieHeader,
   parseFormBody,
+  parseQueryString,
+  readHttpPacked,
+  readPairsPacked,
   unpackBitset,
   unpackByteResults,
   unpackI64ArrayAsBigInt,
   unpackU32Array,
 } from './src/shared/packed'
-export type { Pair, ParsedHttpRequestPacked } from './src/shared/packed'
-
-export * from './src/ingress'
-
-// Framework-agnostic integration helpers: run the ingress pipeline as a
-// request stage (createPipeline), RFC 6455 upgrade (createWebSocketUpgrade),
-// and SSE framing (sseResponse). See docs/INGRESS.md.
-export * from './src/integration'
-
-// Higher-order loader (HFC) over the curated op set: createLoader / loader
-// dispatch single items, packed batches, and load() coalescing. See README.
-export * from './src/loader'
+// UUIDv7 generation — delegates to Bun.randomUUIDv7, crypto.randomUUID on Node.
+export { uuidv7 } from './src/shared/uuid'

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "castrum",
-    "version": "0.9.2",
+    "version": "0.9.4",
     "private": false,
     "description": "Enterprise-grade Bun + Rust runtime: Rust-accelerated FFI primitives, a production-grade HTTP ingress pipeline, validation, hashing, and JSON processing with benchmark-grade performance.",
     "type": "module",
@@ -48,11 +48,18 @@
         "docs",
         "README.md",
         "*.node",
+        "scripts/postinstall.mjs",
+        "rust",
+        "Cargo.toml",
+        "Cargo.lock",
+        "build.rs",
+        "rust-toolchain.toml",
         "!src/bench",
         "!src/baseline",
         "!src/data"
     ],
     "scripts": {
+        "postinstall": "node scripts/postinstall.mjs",
         "build": "napi build --release --platform",
         "build:perf": "bash scripts/build-perf.sh",
         "build:v3": "bash scripts/build-v3.sh",
@@ -104,6 +111,7 @@
         "bench:startup": "bun run bench/startup.ts",
         "bench:load": "bun run bench/http/load-phase.ts",
         "bench:ffi": "bun run bench/ffi/ffi-all.ts",
+    "bench:newops": "bun bench/cost/rust-vs-js-new-ops.ts",
         "bench:ffi:load": "bun run bench/ffi/ffi-load.ts",
         "bench:ffi:public": "bun run bench/ffi/ffi-public.ts",
         "bench:ffi:workers": "bun run bench/ffi/ffi-workers.ts",

package/rust/crypto/aead.rs

@@ -0,0 +1,378 @@
+// rust/crypto/aead.rs — authenticated encryption (AES-256-GCM, ChaCha20-Poly1305).
+//
+// Backend-framework feature: symmetric encryption for cookies / session
+// payloads / at-rest secrets. Uses aws-lc-rs's `aead` module (already a
+// dependency for HMAC-SHA256), so no new crate is pulled in. Nonce and plaintext
+// lengths are validated; a 12-byte nonce is required (both algorithms use the
+// same 96-bit nonce length).
+//
+// Pure-Rust core (no napi types) stays unit-testable; only the entry points
+// use napi types.
+
+use aws_lc_rs::aead::{self, Aad, LessSafeKey, Nonce, UnboundKey};
+use aws_lc_rs::error::Unspecified;
+use napi::bindgen_prelude::*;
+use napi_derive::napi;
+
+const NONCE_LEN: usize = 12;
+
+/// Derive a unique per-item nonce for the batch APIs.
+///
+/// AES-GCM and ChaCha20-Poly1305 are catastrophic under nonce reuse with the
+/// same key. The batch APIs accept ONE caller-provided base nonce; this derives
+/// a distinct nonce per item by XOR-ing the item index into the low 8 bytes.
+///
+/// SAFETY CONTRACT: callers MUST use a fresh base nonce for every batch call
+/// (never reuse a base nonce with the same key across calls), otherwise item `i`
+/// of two different batches share a nonce and keystream/tag reuse applies.
+#[inline]
+fn batch_nonce(base: &[u8], index: usize) -> [u8; NONCE_LEN] {
+    let mut nonce = [0u8; NONCE_LEN];
+    nonce.copy_from_slice(base);
+    let idx = (index as u64).to_be_bytes();
+    for (slot, byte) in nonce[4..].iter_mut().zip(idx.iter()) {
+        *slot ^= byte;
+    }
+    nonce
+}
+
+fn resolve_algorithm(name: Option<&str>) -> Result<&'static aead::Algorithm> {
+    match name {
+        None | Some("aes-256-gcm") => Ok(&aead::AES_256_GCM),
+        Some("chacha20-poly1305") => Ok(&aead::CHACHA20_POLY1305),
+        Some(other) => Err(Error::from_reason(format!(
+            "unsupported aead algorithm: {other} (expected aes-256-gcm | chacha20-poly1305)"
+        ))),
+    }
+}
+
+// ── Pure-Rust core ─────────────────────────────────────────────
+
+/// Encrypt `plaintext`, appending the 16-byte auth tag. Returns the ciphertext
+/// (plaintext length + tag).
+pub fn encrypt(
+    alg: &'static aead::Algorithm,
+    key: &[u8],
+    nonce: &[u8],
+    plaintext: &[u8],
+) -> std::result::Result<Vec<u8>, Unspecified> {
+    let unbound = UnboundKey::new(alg, key)?;
+    let sealing = LessSafeKey::new(unbound);
+    encrypt_with_key(&sealing, nonce, plaintext)
+}
+
+/// Encrypt with a PRE-COMPILED key (no per-call `UnboundKey`/`LessSafeKey`
+/// derivation — the win the `AeadCipher` instance exploits).
+pub fn encrypt_with_key(
+    sealing: &LessSafeKey,
+    nonce: &[u8],
+    plaintext: &[u8],
+) -> std::result::Result<Vec<u8>, Unspecified> {
+    if nonce.len() != NONCE_LEN {
+        return Err(Unspecified);
+    }
+    let mut nonce_arr = [0u8; NONCE_LEN];
+    nonce_arr.copy_from_slice(nonce);
+    let nonce = Nonce::assume_unique_for_key(nonce_arr);
+    let mut in_out = plaintext.to_vec();
+    sealing.seal_in_place_append_tag(nonce, Aad::empty(), &mut in_out)?;
+    Ok(in_out)
+}
+
+/// Decrypt `ciphertext` (ciphertext + tag), returning the plaintext.
+pub fn decrypt(
+    alg: &'static aead::Algorithm,
+    key: &[u8],
+    nonce: &[u8],
+    ciphertext: &[u8],
+) -> std::result::Result<Vec<u8>, Unspecified> {
+    let unbound = UnboundKey::new(alg, key)?;
+    let opening = LessSafeKey::new(unbound);
+    decrypt_with_key(&opening, nonce, ciphertext)
+}
+
+/// Decrypt with a PRE-COMPILED key (no per-call key derivation).
+pub fn decrypt_with_key(
+    opening: &LessSafeKey,
+    nonce: &[u8],
+    ciphertext: &[u8],
+) -> std::result::Result<Vec<u8>, Unspecified> {
+    if nonce.len() != NONCE_LEN {
+        return Err(Unspecified);
+    }
+    let mut nonce_arr = [0u8; NONCE_LEN];
+    nonce_arr.copy_from_slice(nonce);
+    let nonce = Nonce::assume_unique_for_key(nonce_arr);
+    // Single copy: borrow the ciphertext in, then truncate in place to the
+    // plaintext length (the tag occupies the trailing bytes) and return it.
+    let mut in_out = ciphertext.to_vec();
+    let opened = opening.open_in_place(nonce, Aad::empty(), &mut in_out)?;
+    let plaintext_len = opened.len();
+    in_out.truncate(plaintext_len);
+    Ok(in_out)
+}
+
+// ── NAPI entry points ──────────────────────────────────────────
+
+/// Encrypt `plaintext` → ciphertext+tag. `key` must be 32 bytes; `nonce` must
+/// be 12 bytes. Defaults to AES-256-GCM; pass `"chacha20-poly1305"` to switch.
+#[napi]
+pub fn aead_encrypt(
+    key: Uint8Array,
+    nonce: Uint8Array,
+    plaintext: Uint8Array,
+    algorithm: Option<String>,
+) -> Result<Buffer> {
+    let alg = resolve_algorithm(algorithm.as_deref())?;
+    encrypt(alg, key.as_ref(), nonce.as_ref(), plaintext.as_ref())
+        .map(Buffer::from)
+        .map_err(|e| Error::from_reason(format!("aead encrypt failed: {e:?}")))
+}
+
+/// Decrypt `ciphertext`+tag → plaintext. Returns `null` when the tag fails to
+/// authenticate (tampered / wrong key) or the inputs are malformed.
+#[napi]
+pub fn aead_decrypt(
+    key: Uint8Array,
+    nonce: Uint8Array,
+    ciphertext: Uint8Array,
+    algorithm: Option<String>,
+) -> Result<Option<Buffer>> {
+    let alg = resolve_algorithm(algorithm.as_deref())?;
+    match decrypt(alg, key.as_ref(), nonce.as_ref(), ciphertext.as_ref()) {
+        Ok(pt) => Ok(Some(Buffer::from(pt))),
+        Err(_) => Ok(None),
+    }
+}
+
+/// Higher-order instance: precompiles the algorithm + key into a `LessSafeKey`
+/// once at construction, so `encrypt`/`decrypt` never re-derive the key on the
+/// per-call path.
+#[napi]
+pub struct AeadCipher {
+    key: LessSafeKey,
+}
+
+#[napi]
+impl AeadCipher {
+    #[napi(constructor)]
+    pub fn new(key: Uint8Array, algorithm: Option<String>) -> Result<Self> {
+        let alg = resolve_algorithm(algorithm.as_deref())?;
+        let unbound = UnboundKey::new(alg, key.as_ref())
+            .map_err(|e| Error::from_reason(format!("invalid aead key: {e:?}")))?;
+        Ok(Self {
+            key: LessSafeKey::new(unbound),
+        })
+    }
+
+    /// Encrypt `plaintext` → ciphertext+tag with the precompiled key.
+    #[napi]
+    pub fn encrypt(&self, nonce: Uint8Array, plaintext: Uint8Array) -> Result<Buffer> {
+        encrypt_with_key(&self.key, nonce.as_ref(), plaintext.as_ref())
+            .map(Buffer::from)
+            .map_err(|e| Error::from_reason(format!("aead encrypt failed: {e:?}")))
+    }
+
+    /// Decrypt `ciphertext`+tag → plaintext, or `null` on auth failure.
+    #[napi]
+    pub fn decrypt(&self, nonce: Uint8Array, ciphertext: Uint8Array) -> Result<Option<Buffer>> {
+        match decrypt_with_key(&self.key, nonce.as_ref(), ciphertext.as_ref()) {
+            Ok(pt) => Ok(Some(Buffer::from(pt))),
+            Err(_) => Ok(None),
+        }
+    }
+}
+
+/// Parallel encrypt batch: packed `[u32 count]{[u32 len][plaintext]}` in →
+/// packed `[u32 count]{[u32 len][ciphertext+tag]}` out.
+///
+/// SECURITY: a unique nonce is derived per item from the caller-provided base
+/// `nonce` (item index XOR-ed into the low 8 bytes). The base nonce MUST be
+/// fresh for every batch call — never reuse a base nonce with the same key.
+#[napi]
+pub fn aead_encrypt_batch_packed(
+    data: Uint8Array,
+    key: Uint8Array,
+    nonce: Uint8Array,
+    algorithm: Option<String>,
+) -> Result<Buffer> {
+    let alg = resolve_algorithm(algorithm.as_deref())?;
+
+    let enc_for = |plaintext: &[u8], index: usize| -> Vec<u8> {
+        let n = batch_nonce(nonce.as_ref(), index);
+        encrypt(alg, key.as_ref(), &n, plaintext).unwrap_or_default()
+    };
+
+    crate::util::run_packed_batch_idx(data.as_ref(), enc_for).map(Buffer::from)
+}
+
+/// Parallel decrypt batch: packed ciphertexts in → packed plaintexts out.
+/// Items whose tag fails to authenticate produce an empty (zero-length) entry.
+///
+/// SECURITY: the SAME per-item nonce derivation as
+/// {@link aead_encrypt_batch_packed} must be used — pass the same base `nonce`
+/// and batch ordering to decrypt what was encrypted.
+#[napi]
+pub fn aead_decrypt_batch_packed(
+    data: Uint8Array,
+    key: Uint8Array,
+    nonce: Uint8Array,
+    algorithm: Option<String>,
+) -> Result<Buffer> {
+    let alg = resolve_algorithm(algorithm.as_deref())?;
+
+    let dec_for = |ciphertext: &[u8], index: usize| -> Vec<u8> {
+        let n = batch_nonce(nonce.as_ref(), index);
+        decrypt(alg, key.as_ref(), &n, ciphertext).unwrap_or_default()
+    };
+
+    crate::util::run_packed_batch_idx(data.as_ref(), dec_for).map(Buffer::from)
+}
+
+#[cfg(test)]
+mod tests {
+    use super::*;
+
+    fn key_bytes() -> [u8; 32] {
+        [7u8; 32]
+    }
+
+    fn nonce_bytes() -> [u8; 12] {
+        [3u8; 12]
+    }
+
+    #[test]
+    fn aes256gcm_roundtrip() {
+        let pt = b"secret session payload";
+        let ct = encrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), pt).unwrap();
+        assert_eq!(ct.len(), pt.len() + 16);
+        let dec = decrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), &ct).unwrap();
+        assert_eq!(dec, pt);
+    }
+
+    #[test]
+    fn aead_cipher_instance_roundtrips_and_rejects() {
+        // Precompiled-key instance: encrypt/decrypt with no per-call key
+        // derivation. Must match the scalar core exactly.
+        let cipher = AeadCipher::new(Uint8Array::new(key_bytes().to_vec()), None).unwrap();
+        let pt = b"session cookie value";
+
+        let ct = cipher
+            .encrypt(
+                Uint8Array::new(nonce_bytes().to_vec()),
+                Uint8Array::new(pt.to_vec()),
+            )
+            .unwrap();
+        assert_eq!(ct.len(), pt.len() + 16);
+
+        let ct_bytes = ct.to_vec();
+        let dec = cipher
+            .decrypt(
+                Uint8Array::new(nonce_bytes().to_vec()),
+                Uint8Array::new(ct_bytes.clone()),
+            )
+            .unwrap();
+        assert_eq!(&dec.unwrap()[..], pt);
+
+        // Wrong-key instance fails to authenticate.
+        let other = AeadCipher::new(Uint8Array::new([9u8; 32].to_vec()), None).unwrap();
+        assert!(other
+            .decrypt(
+                Uint8Array::new(nonce_bytes().to_vec()),
+                Uint8Array::new(ct_bytes)
+            )
+            .unwrap()
+            .is_none());
+
+        // Malformed nonce length → error.
+        assert!(cipher
+            .encrypt(Uint8Array::new(vec![0u8; 8]), Uint8Array::new(pt.to_vec()))
+            .is_err());
+
+        // Unsupported algorithm → construction error.
+        assert!(AeadCipher::new(
+            Uint8Array::new(key_bytes().to_vec()),
+            Some("aes-128-gcm".to_string())
+        )
+        .is_err());
+    }
+
+    #[test]
+    fn batch_nonce_unique_per_item() {
+        // Regression: the batch APIs must NEVER reuse a nonce across items.
+        let base = nonce_bytes();
+        let n0 = batch_nonce(&base, 0);
+        let n1 = batch_nonce(&base, 1);
+        let n2 = batch_nonce(&base, 2);
+        assert_ne!(n0, n1, "nonce for item 0 and 1 must differ");
+        assert_ne!(n1, n2, "nonce for item 1 and 2 must differ");
+        assert_ne!(n0, n2);
+        // Uniqueness for a full large batch too.
+        let mut seen = std::collections::HashSet::new();
+        for i in 0..1024 {
+            assert!(
+                seen.insert(batch_nonce(&base, i)),
+                "nonce reused at item {i}"
+            );
+        }
+    }
+
+    #[test]
+    fn batch_nonce_derived_encrypt_roundtrip() {
+        // Each item encrypted with its derived nonce decrypts correctly, and a
+        // mismatched nonce fails to authenticate (catches nonce-reuse misuse).
+        let alg = &aead::AES_256_GCM;
+        let key = key_bytes();
+        let base = nonce_bytes();
+
+        let p0 = b"first payload";
+        let p1 = b"second payload";
+
+        let c0 = encrypt(alg, &key, &batch_nonce(&base, 0), p0).unwrap();
+        let c1 = encrypt(alg, &key, &batch_nonce(&base, 1), p1).unwrap();
+
+        assert_eq!(decrypt(alg, &key, &batch_nonce(&base, 0), &c0).unwrap(), p0);
+        assert_eq!(decrypt(alg, &key, &batch_nonce(&base, 1), &c1).unwrap(), p1);
+        // Cross-nonce decryption must fail authentication.
+        assert!(decrypt(alg, &key, &batch_nonce(&base, 1), &c0).is_err());
+        assert!(decrypt(alg, &key, &batch_nonce(&base, 0), &c1).is_err());
+    }
+
+    #[test]
+    fn chacha20_roundtrip() {
+        let pt = b"another payload";
+        let ct = encrypt(&aead::CHACHA20_POLY1305, &key_bytes(), &nonce_bytes(), pt).unwrap();
+        let dec = decrypt(&aead::CHACHA20_POLY1305, &key_bytes(), &nonce_bytes(), &ct).unwrap();
+        assert_eq!(dec, pt);
+    }
+
+    #[test]
+    fn tampered_ciphertext_fails_auth() {
+        let pt = b"integrity matters";
+        let mut ct = encrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), pt).unwrap();
+        ct[0] ^= 0xff;
+        assert!(decrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), &ct).is_err());
+    }
+
+    #[test]
+    fn wrong_key_fails_auth() {
+        let pt = b"integrity matters";
+        let ct = encrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), pt).unwrap();
+        let wrong_key = [9u8; 32];
+        assert!(decrypt(&aead::AES_256_GCM, &wrong_key, &nonce_bytes(), &ct).is_err());
+    }
+
+    #[test]
+    fn wrong_nonce_fails_auth() {
+        let pt = b"integrity matters";
+        let ct = encrypt(&aead::AES_256_GCM, &key_bytes(), &nonce_bytes(), pt).unwrap();
+        let wrong_nonce = [4u8; 12];
+        assert!(decrypt(&aead::AES_256_GCM, &key_bytes(), &wrong_nonce, &ct).is_err());
+    }
+
+    #[test]
+    fn rejects_bad_nonce_length() {
+        assert!(encrypt(&aead::AES_256_GCM, &key_bytes(), &[0u8; 8], b"x").is_err());
+        assert!(decrypt(&aead::AES_256_GCM, &key_bytes(), &[0u8; 8], b"x").is_err());
+    }
+}