castrum 0.9.4 → 0.9.7

package/docs/bun-builtins-decision-matrix.md

@@ -7,7 +7,10 @@
 
 ## Methodology
 
-- **Runtime**: Bun **1.4.0** (the primary target).
+- **Runtime**: Bun **1.4.0** (the measurement anchor for the rows below; the
+  local toolchain has since moved to **1.4.2**, and these TIMING rows have not
+  been re-measured — only re-verified for parity, which
+  `test/unit/contract/delegation.test.ts` does on every run).
 - **Addon**: castrum **release** build (`bun run build`, baseline CPU — the
   shipped profile).
 - **Driver**: `bun run check` (CPU benchmark → `bench/results/cpu/latest.json`).

package/index.ts

@@ -20,6 +20,11 @@ export * from './src/integration'
 // dispatch single items, packed batches, and load() coalescing. See README.
 export * from './src/loader'
 export * from './src/rust-ffi'
+// Off-thread native task runtime ("castrum Tasks"): submit a CPU-bound native
+// op to the Rust pool and `await` it without ever blocking the JS thread.
+// Bun-only offload today; Node runs the op synchronously. See
+// docs/RND-CONCURRENCY.md.
+export * from './src/task'
 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

package/package.json

@@ -1,168 +1,177 @@
 {
-    "name": "castrum",
-    "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",
-    "main": "dist/index.js",
-    "module": "dist/index.js",
-    "types": "dist/index.d.ts",
-    "license": "MIT",
-    "keywords": [
-        "bun",
-        "rust",
-        "napi",
-        "ffi",
-        "ingress",
-        "http",
-        "validation",
-        "hashing",
-        "json",
-        "performance",
-        "benchmark"
-    ],
-    "repository": {
-        "type": "git",
-        "url": "git+https://github.com/Axylabs/flux-rs.git"
+  "name": "castrum",
+  "version": "0.9.7",
+  "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",
+  "main": "dist/index.js",
+  "module": "dist/index.js",
+  "types": "dist/index.d.ts",
+  "license": "MIT",
+  "keywords": [
+    "bun",
+    "rust",
+    "napi",
+    "ffi",
+    "ingress",
+    "http",
+    "validation",
+    "hashing",
+    "json",
+    "performance",
+    "benchmark"
+  ],
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/Axylabs/castrum.git"
+  },
+  "homepage": "https://github.com/Axylabs/castrum#readme",
+  "bugs": {
+    "url": "https://github.com/Axylabs/castrum/issues"
+  },
+  "publishConfig": {
+    "access": "public"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "bun": "./index.ts",
+      "node": "./dist/index.js",
+      "default": "./dist/index.js"
     },
-    "homepage": "https://github.com/Axylabs/flux-rs#readme",
-    "bugs": {
-        "url": "https://github.com/Axylabs/flux-rs/issues"
-    },
-    "publishConfig": {
-        "access": "public"
-    },
-    "exports": {
-        ".": {
-            "types": "./dist/index.d.ts",
-            "bun": "./index.ts",
-            "node": "./dist/index.js",
-            "default": "./dist/index.js"
-        },
-        "./package.json": "./package.json"
-    },
-    "files": [
-        "index.ts",
-        "dist",
-        "src",
-        "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",
-        "build:all": "bun run build && bun run build:v3",
-        "build:js": "bun run build:js:bundle && bun run build:js:types",
-        "build:js:bundle": "bun build ./index.ts --target=node --format=esm --outdir=dist",
-        "build:js:types": "dts-bundle-generator -o dist/index.d.ts index.ts",
-        "bench": "bun run build && bun bench.ts",
-        "check": "bun bench.ts",
-        "test": "bun test",
-        "test:all": "bun test && bun run typecheck && bun run typecheck:test && bun run lint:ci && bun run check:clean && cargo test --lib",
-        "test:coverage": "node scripts/check-coverage.mjs",
-        "setup": "bun install && bun run build",
-        "test:node": "node --test test/integration/node-smoke.test.mjs test/integration/node-enterprise.test.mjs",
-        "verify:install": "node scripts/verify-install.mjs",
-        "build:debug": "napi build --platform",
-        "lint": "bunx biome check .",
-        "lint:fix": "bunx biome check --write .",
-        "lint:ci": "bunx biome check . --formatter-enabled=false --assist-enabled=false --error-on-warnings",
-        "format": "bunx biome format --write .",
-        "typecheck": "bunx tsc --noEmit",
-        "typecheck:test": "bunx tsc --noEmit -p tsconfig.test.json",
-        "test:rust": "cargo test",
-        "deny": "cargo deny check",
-        "check:version": "bun scripts/check-version.mjs",
-        "check:jsdoc": "bun scripts/check-jsdoc.ts",
-        "check:selection": "bun scripts/select-native.ts --check",
-        "check:clean": "bun scripts/check-clean.ts",
-        "gen:ai-map": "bun scripts/gen-ai-map.ts",
-        "audit": "bun audit",
-        "publish:manual": "node scripts/publish-manual.mjs",
-        "publish:manual:dry": "node scripts/publish-manual.mjs --dry-run",
-        "prepublishOnly": "bun run build:js && node scripts/prepublish.mjs",
-        "bench:http": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts",
-        "bench:http:smoke": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts smoke",
-        "bench:http:stress": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts stress",
-        "bench:http:heavy": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts heavy-json",
-        "bench:http:crud": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts crud",
-        "bench:http:spike": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts spike",
-        "bench:http:soak": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts soak",
-        "bench:http:storm": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts storm",
-        "bench:http:boundary": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts boundary",
-        "bench:http:elysia": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts '' elysia",
-        "bench:http:ingress": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts '' ingress",
-        "bench:http:bun-only": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts '' bun",
-        "bench:http:all-heavy": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts 1",
-        "bench:http:ac": "bun bench/autocannon-stress.mjs",
-        "bench:http:stress:ac": "SCENARIO=03-stress bun bench/autocannon-stress.mjs",
-        "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",
+    "./package.json": "./package.json"
+  },
+  "files": [
+    "index.ts",
+    "dist",
+    "src",
+    "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",
+    "build:all": "bun run build && bun run build:v3",
+    "build:js": "bun run build:js:bundle && bun run build:js:types",
+    "build:js:bundle": "bun build ./index.ts --target=node --format=esm --outdir=dist",
+    "build:js:types": "dts-bundle-generator -o dist/index.d.ts index.ts",
+    "bench": "bun run build && bun bench.ts",
+    "check": "bun bench.ts",
+    "test": "bun test test/unit test/property test/compat",
+    "test:all": "bun test && bun run typecheck && bun run typecheck:test && bun run lint:ci && bun run check:clean && cargo test --lib",
+    "test:coverage": "node scripts/check-coverage.mjs",
+    "setup": "bun install && bun run build",
+    "test:node": "node --test test/integration/node-smoke.test.mjs test/integration/node-enterprise.test.mjs",
+    "verify:install": "node scripts/verify-install.mjs",
+    "build:debug": "napi build --platform",
+    "lint": "bunx biome check .",
+    "lint:fix": "bunx biome check --write .",
+    "lint:ci": "bunx biome check . --formatter-enabled=false --assist-enabled=false --error-on-warnings",
+    "format": "bunx biome format --write .",
+    "typecheck": "bunx tsc --noEmit",
+    "typecheck:test": "bunx tsc --noEmit -p tsconfig.test.json",
+    "test:rust": "cargo test",
+    "deny": "cargo deny check",
+    "check:version": "bun scripts/check-version.mjs",
+    "check:jsdoc": "bun scripts/check-jsdoc.ts",
+    "check:selection": "bun scripts/select-native.ts --check",
+    "check:clean": "bun scripts/check-clean.ts",
+    "gen:ai-map": "bun scripts/gen-ai-map.ts",
+    "audit": "bun audit",
+    "release": "bun scripts/release.ts",
+    "release:dry": "bun scripts/release.ts --dry-run",
+    "release:manual": "bun scripts/release.ts --publish",
+    "prepublishOnly": "bun run build:js && node scripts/prepublish.mjs",
+    "bench:http": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts",
+    "bench:http:smoke": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts smoke",
+    "bench:http:stress": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts stress",
+    "bench:http:heavy": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts heavy-json",
+    "bench:http:crud": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts crud",
+    "bench:http:spike": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts spike",
+    "bench:http:soak": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts soak",
+    "bench:http:storm": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts storm",
+    "bench:http:boundary": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts boundary",
+    "bench:http:elysia": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts '' elysia",
+    "bench:http:ingress": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts '' ingress",
+    "bench:http:bun-only": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts '' bun",
+    "bench:http:all-heavy": "BUN_CONFIG_MAX_HTTP_REQUESTS=65535 bun run bench/http/run-bench.ts 1",
+    "bench:http:ac": "bun bench/autocannon-stress.mjs",
+    "bench:http:stress:ac": "SCENARIO=03-stress bun bench/autocannon-stress.mjs",
+    "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",
-        "bench:margin": "bun run bench/ffi/ffi-margin.ts",
-        "bench:router": "bun run bench/cost/router-cost.ts",
-        "bench:ingress-cost": "bun run bench/cost/ingress-cost.ts",
-        "bench:ingress-cost:post": "bun run bench/cost/ingress-cost-post.ts",
-        "verify:native:batch": "bun run scripts/verify-native-batch.ts"
-    },
-    "dependencies": {},
-    "peerDependencies": {
-        "@types/node": "^26.1.2"
-    },
-    "peerDependenciesMeta": {
-        "@types/node": {
-            "optional": true
-        }
-    },
-    "devDependencies": {
-        "@elysia/cors": "^1.4.2",
-        "@napi-rs/cli": "^3.8.6",
-        "@types/bun": "^1.3.14",
-        "@types/mime-types": "^3.0.1",
-        "autocannon": "^8.0.0",
-        "@types/validator": "^13.15.10",
-        "ajv": "^8.20.0",
-        "crc-32": "^1.2.2",
-        "dts-bundle-generator": "^9.5.1",
-        "elysia": "^1.4.29",
-        "fast-json-patch": "^3.1.1",
-        "mime-types": "^3.0.2",
-        "typescript": "5.9.3",
-        "validator": "^13.15.35"
-    },
-    "overrides": {
-        "typescript": "5.9.3"
+    "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",
+    "bench:margin": "bun run bench/ffi/ffi-margin.ts",
+    "bench:router": "bun run bench/cost/router-cost.ts",
+    "bench:task": "bun run bench/cost/task-offload.ts",
+    "bench:ingress-cost": "bun run bench/cost/ingress-cost.ts",
+    "bench:ingress-cost:post": "bun run bench/cost/ingress-cost-post.ts",
+    "verify:native:batch": "bun run scripts/verify-native-batch.ts"
+  },
+  "dependencies": {},
+  "peerDependencies": {
+    "@types/node": "^26.1.2"
+  },
+  "peerDependenciesMeta": {
+    "@types/node": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@elysia/cors": "^1.4.2",
+    "@napi-rs/cli": "^3.8.6",
+    "@types/bun": "^1.3.14",
+    "@types/mime-types": "^3.0.1",
+    "autocannon": "^8.0.0",
+    "@types/validator": "^13.15.10",
+    "ajv": "^8.20.0",
+    "crc-32": "^1.2.2",
+    "dts-bundle-generator": "^9.5.1",
+    "elysia": "^1.4.29",
+    "fast-json-patch": "^3.1.1",
+    "mime-types": "^3.0.2",
+    "typescript": "7.0.2",
+    "validator": "^13.15.35"
+  },
+  "overrides": {
+    "typescript": "7.0.2",
+    "dts-bundle-generator": {
+      "typescript": "5.9.3"
     },
-    "engines": {
-        "bun": ">=1.1.0",
-        "node": ">=20.3"
+    "@napi-rs/cli": {
+      "typescript": "6.0.3"
     },
-    "napi": {
-        "binaryName": "castrum",
-        "targets": [
-            "aarch64-apple-darwin",
-            "aarch64-unknown-linux-gnu",
-            "aarch64-unknown-linux-musl",
-            "x86_64-apple-darwin",
-            "x86_64-pc-windows-msvc",
-            "x86_64-unknown-linux-gnu",
-            "x86_64-unknown-linux-musl"
-        ]
-    }
-}
+    "hyperid": "^4.0.0"
+  },
+  "engines": {
+    "bun": ">=1.1.0",
+    "node": ">=20.3"
+  },
+  "napi": {
+    "binaryName": "castrum",
+    "targets": [
+      "aarch64-apple-darwin",
+      "aarch64-unknown-linux-gnu",
+      "aarch64-unknown-linux-musl",
+      "x86_64-apple-darwin",
+      "x86_64-pc-windows-msvc",
+      "x86_64-unknown-linux-gnu",
+      "x86_64-unknown-linux-musl"
+    ]
+  }
+}

package/rust/crypto/pbkdf2.rs

@@ -17,6 +17,15 @@ pub const PBKDF2_MIN_LEN: u32 = 1;
 /// Cap derived-key length so a hostile caller can't request a huge allocation.
 pub const PBKDF2_MAX_LEN: u32 = 1024 * 1024;
 
+/// Pure core (no napi types) for [`pbkdf2_sha256`] and the off-thread task
+/// runtime: derive `dk_len` bytes, clamping the length to the documented range.
+pub fn pbkdf2_sha256_into(password: &[u8], salt: &[u8], rounds: u32, dk_len: u32) -> Vec<u8> {
+    let dk_len = dk_len.clamp(PBKDF2_MIN_LEN, PBKDF2_MAX_LEN) as usize;
+    let mut out = vec![0u8; dk_len];
+    pbkdf2_hmac::<Sha256>(password, salt, rounds.max(1), &mut out);
+    out
+}
+
 /// Derive a PBKDF2-HMAC-SHA256 key: `out = PBKDF2(password, salt, rounds, dkLen)`.
 #[napi]
 pub fn pbkdf2_sha256(

package/rust/crypto/session.rs

@@ -83,13 +83,10 @@ pub fn open_core(token: &[u8], secret: &[u8]) -> Option<(i64, Vec<u8>, Vec<u8>)>
                         if bytes.get(pos) != Some(&b'"') {
                             return None;
                         }
-                        let vs = pos + 1;
-                        let mut ve = vs;
-                        while ve < bytes.len() && bytes[ve] != b'"' {
-                            ve += 1;
-                        }
-                        id = Some(bytes[vs..ve].to_vec());
-                        pos = ve + 1;
+                        let body = pos + 1;
+                        let end = scan_json_string_end(bytes, body)?;
+                        id = Some(unescape_json_id(&bytes[body..end]));
+                        pos = end + 1;
                     }
                     b"exp" => {
                         let vs = pos;
@@ -174,6 +171,108 @@ fn skip_json_value(bytes: &[u8], pos: usize) -> Option<usize> {
     }
 }
 
+/// Index of the `"` that TERMINATES a JSON string whose body starts at `start`
+/// (just past the opening quote).
+///
+/// Escape-aware: the id used to be captured by scanning for the next `"`, which
+/// stops at the quote inside an escaped `\"` — truncating the id AND leaving
+/// `pos` in the middle of the string, so the rest of the envelope was then read
+/// as structure (a quote-carrying id could make `open` fail outright).
+fn scan_json_string_end(bytes: &[u8], start: usize) -> Option<usize> {
+    let mut i = start;
+    while i < bytes.len() {
+        match bytes[i] {
+            b'\\' => i += 2,
+            b'"' => return Some(i),
+            _ => i += 1,
+        }
+    }
+    None
+}
+
+/// Decode 4 hex digits at `at` (the `\uXXXX` payload).
+fn hex4(bytes: &[u8], at: usize) -> Option<u32> {
+    let mut v = 0u32;
+    for k in 0..4 {
+        v = (v << 4) | (*bytes.get(at + k)? as char).to_digit(16)?;
+    }
+    Some(v)
+}
+
+/// Inverse of `json_ser::write_json_escaped` for the id: decodes `\"`, `\\`,
+/// `\/`, `\b`, `\f`, `\n`, `\r`, `\t` and `\uXXXX`.
+///
+/// `\u00XX` maps back to the single BYTE `XX`. That is deliberate and load
+/// bearing: the escaper emits that form for control characters AND — in its
+/// invalid-UTF-8 mode — for every byte of binary input, so routing it through a
+/// code point and re-encoding as UTF-8 would expand bytes >= 0x80 into two
+/// bytes and destroy the byte-exact round trip the id is supposed to have.
+/// (A valid-UTF-8 id is written RAW by the escaper, so `\u00XX` cannot be its
+/// origin.)
+///
+/// `\uXXXX` above 0xFF can only come from a different producer (e.g. JS
+/// `JSON.stringify` of a non-ASCII id), so it is decoded as a code point with
+/// surrogate-pair combining. Unknown escapes and a trailing backslash are kept
+/// verbatim — never silently dropped.
+fn unescape_json_id(escaped: &[u8]) -> Vec<u8> {
+    let mut out = Vec::with_capacity(escaped.len());
+    let mut i = 0usize;
+    while i < escaped.len() {
+        if escaped[i] != b'\\' {
+            out.push(escaped[i]);
+            i += 1;
+            continue;
+        }
+        let Some(&e) = escaped.get(i + 1) else {
+            out.push(b'\\');
+            break;
+        };
+        i += 2;
+        match e {
+            b'"' => out.push(b'"'),
+            b'\\' => out.push(b'\\'),
+            b'/' => out.push(b'/'),
+            b'b' => out.push(0x08),
+            b'f' => out.push(0x0c),
+            b'n' => out.push(b'\n'),
+            b'r' => out.push(b'\r'),
+            b't' => out.push(b'\t'),
+            b'u' => {
+                let Some(cp) = hex4(escaped, i) else {
+                    out.push(b'\\');
+                    out.push(b'u');
+                    continue;
+                };
+                i += 4;
+                if cp <= 0xFF {
+                    out.push(cp as u8);
+                    continue;
+                }
+                let mut code = cp;
+                if (0xD800..=0xDBFF).contains(&cp)
+                    && escaped.get(i) == Some(&b'\\')
+                    && escaped.get(i + 1) == Some(&b'u')
+                {
+                    if let Some(lo) = hex4(escaped, i + 2) {
+                        if (0xDC00..=0xDFFF).contains(&lo) {
+                            code = 0x10000 + ((cp - 0xD800) << 10) + (lo - 0xDC00);
+                            i += 6;
+                        }
+                    }
+                }
+                let mut buf = [0u8; 4];
+                let ch = char::from_u32(code).unwrap_or('\u{FFFD}');
+                out.extend_from_slice(ch.encode_utf8(&mut buf).as_bytes());
+            }
+            other => {
+                out.push(b'\\');
+                out.push(other);
+            }
+        }
+    }
+    out
+}
+
 #[cfg(test)]
 mod tests {
     use super::*;
@@ -209,6 +308,64 @@ mod tests {
         assert!(seal_core(b"", b"{}", 0, SECRET).is_none());
     }
 
+    #[test]
+    fn id_round_trips_byte_exactly_through_escapes() {
+        // A `"` used to terminate the id scan early, and the id came back
+        // escaped. Both are the same root cause: an escape-unaware scan with no
+        // decode. Every id here must survive the envelope byte-for-byte.
+        for id in [
+            &b"plain-id"[..],
+            &b"sess\"quote"[..],
+            &b"back\\slash"[..],
+            &b"new\nline"[..],
+            &b"tab\there"[..],
+            &b"cr\rhere"[..],
+            &b"nul\0byte"[..],
+            &b"binary\xff\xfe"[..],
+            &b"trailing\\"[..],
+        ] {
+            let token = seal_core(id, br#"{"a":1}"#, 42, SECRET).expect("seal");
+            let (exp, got, data) = open_core(&token, SECRET).expect("open");
+            assert_eq!(got, id, "id must round-trip byte-exactly");
+            assert_eq!(exp, 42);
+            assert_eq!(data, br#"{"a":1}"#);
+        }
+    }
+
+    #[test]
+    fn unescape_json_id_matches_the_escaper() {
+        assert_eq!(unescape_json_id(br#"a\"b"#), b"a\"b");
+        assert_eq!(unescape_json_id(br#"a\\b"#), b"a\\b");
+        assert_eq!(unescape_json_id(br#"a\/b"#), b"a/b");
+        assert_eq!(unescape_json_id(br#"a\nb"#), b"a\nb");
+        assert_eq!(unescape_json_id(br#"a\rb"#), b"a\rb");
+        assert_eq!(unescape_json_id(br#"a\tb"#), b"a\tb");
+        assert_eq!(unescape_json_id(br#"a\bb"#), b"a\x08b");
+        assert_eq!(unescape_json_id(br#"a\fb"#), b"a\x0cb");
+        // `\u00XX` is a BYTE (the escaper's binary mode), not a code point.
+        assert_eq!(unescape_json_id(br#"a\u00e9b"#), b"a\xe9b");
+        // Above 0xFF is a real code point → UTF-8.
+        assert_eq!(unescape_json_id(br#"a\u20acb"#), "a\u{20ac}b".as_bytes());
+        // A surrogate pair combines into one code point.
+        assert_eq!(unescape_json_id(br#"\ud83d\ude00"#), "\u{1f600}".as_bytes());
+        // Unknown escapes and a trailing backslash stay verbatim.
+        assert_eq!(unescape_json_id(br#"a\qb"#), br#"a\qb"#);
+        assert_eq!(unescape_json_id(b"a\\"), b"a\\");
+    }
+
+    #[test]
+    fn scan_json_string_end_skips_escaped_quotes() {
+        // `a\"b"` (a, \, ", b, ") — the escaped quote does NOT terminate; the
+        // plain quote at index 4 does.
+        assert_eq!(scan_json_string_end(b"a\\\"b\"", 0), Some(4));
+        // No escape at all: the first quote terminates.
+        assert_eq!(scan_json_string_end(b"ab\"cd", 0), Some(2));
+        // Unterminated: the trailing backslash swallows the rest.
+        assert_eq!(scan_json_string_end(b"ab\\\"", 0), None);
+        // Escaped BACKSLASH then a terminator: `a\\"` = a, \, \, " → Some(3).
+        assert_eq!(scan_json_string_end(b"a\\\\\"", 0), Some(3));
+    }
+
     #[test]
     fn wire_format_matches_sign_cookie() {
         // The sealed token must be verifiable by the EXISTING cookie verify