castrum 0.9.4 → 0.9.6

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.6",
+  "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/ffi/mod.rs

@@ -52,6 +52,7 @@ mod payload;
 mod probe;
 mod rate_limit;
 mod route;
+mod task;
 mod util;
 mod validators;
 

package/rust/ffi/task.rs

@@ -0,0 +1,172 @@
+// rust/ffi/task.rs — C-ABI exports for the off-thread task runtime.
+//
+// Eight symbols, all thin: the pool/ring/ops live in `rust/task/`. `submit`
+// COPIES the packed args onto the worker (the JS caller's pooled buffer is
+// released as soon as submit returns), and `drain` follows the repo-wide
+// needed-size convention so JS grows once and retries once.
+
+use std::slice;
+
+use super::util::panic_guard;
+use crate::task;
+
+/// Start the pool with `threads` workers (0 → runtime default).
+/// Returns `0` started, `1` already running, `2` internal error.
+#[no_mangle]
+pub extern "C" fn castrum_task_init(threads: u32) -> u32 {
+    panic_guard(|| task::init(Some(threads)), 2)
+}
+
+/// Submit `op` with `args_len` packed arg bytes, completing under `task_id`.
+/// Returns `1` accepted, `0` rejected (null args with a non-zero length).
+///
+/// # Safety
+/// `args` must be valid for reads of `args_len` bytes.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_task_submit(
+    op: u32,
+    args: *const u8,
+    args_len: usize,
+    task_id: usize,
+) -> u32 {
+    if args.is_null() && args_len != 0 {
+        return 0;
+    }
+    let owned: Vec<u8> = if args_len == 0 {
+        Vec::new()
+    } else {
+        slice::from_raw_parts(args, args_len).to_vec()
+    };
+    u32::from(task::submit_op(op, owned, task_id as u64))
+}
+
+/// Drain finished tasks into `out` (packed `[u32 count][entry…]`).
+/// Returns bytes written, `0` when nothing is pending, or the EXACT required
+/// size when `out` is too small (nothing is consumed in that case).
+///
+/// # Safety
+/// `out` must be valid for writes of `out_cap` bytes.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_task_drain(out: *mut u8, out_cap: usize) -> usize {
+    if out.is_null() {
+        return 0;
+    }
+    panic_guard(|| task::drain(slice::from_raw_parts_mut(out, out_cap)), 0)
+}
+
+/// Completions waiting to be drained.
+#[no_mangle]
+pub extern "C" fn castrum_task_pending() -> u32 {
+    task::pending()
+}
+
+/// Submit an op that writes its result DIRECTLY into `out` (zero-copy output):
+/// the completion body is the 8-byte LE written length, not the data, so JS
+/// resolves a view of the buffer it already owns. A too-small `out` completes
+/// with status 3 (TOO_SMALL) and the exact required size as the body; status 4
+/// (UNSUPPORTED) means the op has no `_into` form and the caller should fall
+/// back to `castrum_task_submit`.
+///
+/// Returns `1` accepted, `0` rejected.
+///
+/// # Safety
+/// `args` must be valid for reads of `args_len` bytes. `out` must be valid for
+/// writes of `out_cap` bytes and must stay alive (and untouched by JS) until the
+/// completion for `task_id` is drained.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_task_submit_out(
+    op: u32,
+    args: *const u8,
+    args_len: usize,
+    task_id: usize,
+    out: *mut u8,
+    out_cap: usize,
+) -> u32 {
+    if (args.is_null() && args_len != 0) || out.is_null() || out_cap == 0 {
+        return 0;
+    }
+    let owned: Vec<u8> = if args_len == 0 {
+        Vec::new()
+    } else {
+        slice::from_raw_parts(args, args_len).to_vec()
+    };
+    u32::from(task::submit_op_into(
+        op,
+        owned,
+        task_id as u64,
+        out as usize,
+        out_cap,
+    ))
+}
+
+/// Mark `task_id` cancelled. Returns `1` when newly marked, `0` otherwise.
+#[no_mangle]
+pub extern "C" fn castrum_task_cancel(task_id: usize) -> u32 {
+    u32::from(task::mark_cancelled(task_id as u64))
+}
+
+/// Submit an op whose PAYLOAD is read IN PLACE from the caller's buffer
+/// (zero-copy INPUT). Only the `hdr_len` header bytes are copied, so a large
+/// argument never crosses the boundary — without this, offloading a big
+/// compression costs a full-size copy on the JS thread and measured WORSE than
+/// the synchronous built-in (docs/RND-CONCURRENCY.md §7b).
+///
+/// Returns `1` accepted, `0` rejected.
+///
+/// # Safety
+/// `hdr` must be valid for reads of `hdr_len` bytes. `data` must be valid for
+/// reads of `data_len` bytes and must stay alive (and unmodified by JS) until
+/// the completion for `task_id` is drained.
+#[no_mangle]
+pub unsafe extern "C" fn castrum_task_submit_slice(
+    op: u32,
+    hdr: *const u8,
+    hdr_len: usize,
+    data: *const u8,
+    data_len: usize,
+    task_id: usize,
+) -> u32 {
+    if (hdr.is_null() && hdr_len != 0) || (data.is_null() && data_len != 0) {
+        return 0;
+    }
+    // The header is small, so copying it keeps the caller free to reuse a
+    // scratch buffer; the payload is never copied.
+    let owned = if hdr_len == 0 {
+        Vec::new()
+    } else {
+        slice::from_raw_parts(hdr, hdr_len).to_vec()
+    };
+    u32::from(task::submit_slice_op(
+        op,
+        owned,
+        data as usize,
+        data_len,
+        task_id as u64,
+    ))
+}
+
+/// Register the thread-safe doorbell trampoline address (`0` disables it).
+/// Returns `1` on success.
+///
+/// # Safety
+/// `cb` must be a live `void()` C trampoline that is safe to call from any
+/// thread (a `bun:ffi` `JSCallback({ threadsafe: true }).ptr`).
+#[no_mangle]
+pub extern "C" fn castrum_task_set_doorbell(cb: *const std::os::raw::c_void) -> u32 {
+    task::set_doorbell(cb as usize);
+    1
+}
+
+/// Stop the pool and drop pending completions. Returns `0`.
+#[no_mangle]
+pub extern "C" fn castrum_task_shutdown() -> u32 {
+    task::shutdown();
+    task::completion::clear();
+    0
+}
+
+/// Configured pool worker count (0 before the pool starts).
+#[no_mangle]
+pub extern "C" fn castrum_task_threads() -> u32 {
+    task::threads()
+}

package/rust/http/form.rs

@@ -108,8 +108,12 @@ mod tests {
     }
 
     #[test]
-    fn form_parse_rejects_malformed_percent() {
-        assert!(form_parse_packed_vec(b"a=%ZZ").is_err());
+    fn form_parse_malformed_percent_falls_back_to_raw() {
+        let packed = form_parse_packed_vec(b"a=%ZZ").unwrap();
+        assert_eq!(
+            crate::test_support::decode_packed_pairs(&packed),
+            vec![(b"a".to_vec(), b"%ZZ".to_vec())]
+        );
     }
 
     #[test]