castrum 0.9.4 → 0.9.7

package/Cargo.lock

@@ -108,9 +108,9 @@ checksum = "72b3254f16251a8381aa12e40e3c4d2f0199f8c6508fbecb9d91f575e0fbb8c6"
 
 [[package]]
 name = "base64"
-version = "0.23.0"
+version = "0.23.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "b25655df2c3cdd83c5e5b293b88acd880332b2ddadd7c30ac43144fdc0033da9"
+checksum = "ac07cdecf99051d9a5238b80f35af32cdeba5b336e55d957b318b50137e18da5"
 
 [[package]]
 name = "base64ct"
@@ -233,11 +233,11 @@ checksum = "fc652a48c352aef3ea3aed32080501cf3ef6ed5da78602a020c991775b0aff04"
 
 [[package]]
 name = "castrum"
-version = "0.9.4"
+version = "0.9.7"
 dependencies = [
  "argon2",
  "aws-lc-rs",
- "base64 0.23.0",
+ "base64 0.23.1",
  "bcrypt",
  "brotli",
  "core_affinity",
@@ -344,9 +344,9 @@ dependencies = [
 
 [[package]]
 name = "crc32fast"
-version = "1.5.0"
+version = "1.5.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9481c1c90cbf2ac953f07c8d4a58aa3945c425b7185c9154d67a65e4230da511"
+checksum = "8498c871161e1742aaa9d52551b2d6ebdd4c3d45a3be423e3728f33b955be550"
 dependencies = [
  "cfg-if",
 ]
@@ -459,9 +459,9 @@ dependencies = [
 
 [[package]]
 name = "fancy-regex"
-version = "0.18.0"
+version = "0.19.0"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "e1e1dacd0d2082dfcf1351c4bdd566bbe89a2b263235a2b50058f1e130a47277"
+checksum = "476de73bddf2ef8490aa4ee8f1cf40b430bf1d56c48c22080e5186952cd580e6"
 dependencies = [
  "bit-set",
  "regex-automata",
@@ -528,12 +528,6 @@ version = "1.0.7"
 source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "3f9eec918d3f24069decb9af1554cad7c880e2da24a9afd88aca000531ab82c1"
 
-[[package]]
-name = "foldhash"
-version = "0.1.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "d9c4f5dac5e15c24eb999c26181a6ca40b39fe946cbe4c263c7209467bc83af2"
-
 [[package]]
 name = "foldhash"
 version = "0.2.0"
@@ -690,17 +684,6 @@ dependencies = [
  "r-efi 6.0.0",
 ]
 
-[[package]]
-name = "hashbrown"
-version = "0.15.5"
-source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "9229cfe53dfd69f0609a49f65461bd93001ea1ef889cd5529dd176593f5338a1"
-dependencies = [
- "allocator-api2",
- "equivalent",
- "foldhash 0.1.5",
-]
-
 [[package]]
 name = "hashbrown"
 version = "0.17.1"
@@ -709,7 +692,7 @@ checksum = "ed5909b6e89a2db4456e54cd5f673791d7eca6732202bbf2a9cc504fe2f9b84a"
 dependencies = [
  "allocator-api2",
  "equivalent",
- "foldhash 0.2.0",
+ "foldhash",
 ]
 
 [[package]]
@@ -849,7 +832,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "d466e9454f08e4a911e14806c24e16fba1b4c121d1ea474396f396069cf949d9"
 dependencies = [
  "equivalent",
- "hashbrown 0.17.1",
+ "hashbrown",
 ]
 
 [[package]]
@@ -896,9 +879,9 @@ dependencies = [
 
 [[package]]
 name = "jsonschema"
-version = "0.48.5"
+version = "0.49.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "f05a6cff806294a7699d48761d4ae2bdebab7fa2eef05e4a0b83320f0ff46901"
+checksum = "59ec8a241beed129f06114aa68007e905ca350e7baeb6e17a7631bb7978d91b2"
 dependencies = [
  "ahash",
  "bytecount",
@@ -925,18 +908,18 @@ dependencies = [
 
 [[package]]
 name = "jsonschema-regex"
-version = "0.48.5"
+version = "0.49.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "84708dd3f6c5327478a96f37378adb27deed6a626cf84d19de780d9e8ae84b17"
+checksum = "91994f45017ed5e66aa8e59b8415f4cb033a6380d7200387b7cf117595fbdf85"
 dependencies = [
  "regex-syntax",
 ]
 
 [[package]]
 name = "jsonschema-value"
-version = "0.48.5"
+version = "0.49.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "fd8c04ab4ce60e42c4e302d3bd9d184652bb56f212495d2eea23573bcbf72556"
+checksum = "7ec7637f83e510868ae6ed625f7ebfbbde4554ee8ce49854caa5126a8b9b9ecb"
 dependencies = [
  "ahash",
  "bytecount",
@@ -1000,11 +983,11 @@ dependencies = [
 
 [[package]]
 name = "lru"
-version = "0.12.5"
+version = "0.18.4"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "234cf4f4a04dc1f57e24b96cc0cd600cf2af460d4161ac5ecdd0af8e1f3b2a38"
+checksum = "ff9840bcc50b71349309900da0ce7279aa336ae71d73250b07998932c7d97c25"
 dependencies = [
- "hashbrown 0.15.5",
+ "hashbrown",
 ]
 
 [[package]]
@@ -1092,13 +1075,14 @@ dependencies = [
 
 [[package]]
 name = "napi"
-version = "3.11.0"
+version = "3.12.2"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "de33522036981030a75c231829566bc63414e08101a6f5ff4ac6cef19c8e0941"
+checksum = "58c5f4d5375213fdb7be2655e152386e82f026f9a5ba36a75556e11359aafe09"
 dependencies = [
  "bitflags",
  "ctor",
  "futures",
+ "libc",
  "napi-build",
  "napi-sys",
  "nohash-hasher",
@@ -1109,9 +1093,9 @@ dependencies = [
 
 [[package]]
 name = "napi-build"
-version = "2.3.2"
+version = "2.4.1"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "c9c366d2c8c60b86fa632df75f745509b52f9128f91a6bad4c796e44abb505e1"
+checksum = "60fdf9b392c50e7c4170fa633bd909490ed7835cea4c046776d1a4dd8d2ae0ab"
 
 [[package]]
 name = "napi-derive"
@@ -1557,14 +1541,14 @@ dependencies = [
 
 [[package]]
 name = "referencing"
-version = "0.48.5"
+version = "0.49.9"
 source = "registry+https://github.com/rust-lang/crates.io-index"
-checksum = "980e77f5cfffc592c0e7dfb6d20770a0b96a6ab94d403de7454ed9799505e4ba"
+checksum = "6efa2154ea6f5ce0fdecdd2a8d18f2fa1a39a8fbba91564f555a592e4dce8278"
 dependencies = [
  "ahash",
  "fluent-uri",
  "getrandom 0.3.4",
- "hashbrown 0.17.1",
+ "hashbrown",
  "itoa",
  "micromap",
  "parking_lot",
@@ -1614,7 +1598,7 @@ source = "registry+https://github.com/rust-lang/crates.io-index"
 checksum = "815cc8a37159a463064825246cadb07961e25cd9885908606f6d08a98d8f8874"
 dependencies = [
  "bytes",
- "hashbrown 0.17.1",
+ "hashbrown",
  "indexmap",
  "munge",
  "ptr_meta",

package/Cargo.toml

@@ -1,8 +1,11 @@
 [package]
 name = "castrum"
 # Keep in sync with package.json "version" (single source of truth: the npm package).
-version = "0.9.4"
+version = "0.9.7"
 edition = "2021"
+# Keep in sync with package.json "license" (cargo-deny rejects a crate with no
+# license expression).
+license = "MIT"
 
 [lib]
 name = "castrum"
@@ -17,6 +20,7 @@ path = "rust/lib.rs"
 [[bin]]
 name = "native-bench"
 path = "rust/src/bin/native-bench.rs"
+required-features = ["native-bench"]
 
 [dependencies]
 napi = { version = "3", features = ["napi10", "serde-json"] }
@@ -39,7 +43,7 @@ sonic-rs = { version = "0.5", features = ["sort_keys"] }
 # default-features=false: drop resolve-http + tls-aws-lc-rs which pull in
 # reqwest -> hyper/h2/tokio/rustls (large binary, attack surface). Format
 # validators (email etc.) are built-in and NOT feature-gated in 0.48.
-jsonschema = { version = "0.48", default-features = false, features = ["resolve-file"] }
+jsonschema = { version = "0.49", default-features = false, features = ["resolve-file"] }
 aws-lc-rs = "1"
 # NOTE: base64 0.23 enables SIMD (SSE/AVX) by default via the `simd-unsafe`
 # feature (part of `default`); no explicit feature is needed.
@@ -70,7 +74,9 @@ core_affinity = "0.8"
 parking_lot = "0.12"
 xxhash-rust = { version = "0.8", features = ["xxh3"] }
 ipnet = "2"
-lru = "0.12"
+# 0.18.2+ carries the RUSTSEC-2026-0253 fix (0.16.x is affected); keep this
+# requirement at or above the fixed release so `cargo deny` / OSV stay green.
+lru = "0.18.2"
 # Zero-cost hashing for fast_schema object-key lookups (default SipHash is slow
 # on short keys). Already a transitive dep, so no new download.
 rustc-hash = "2"
@@ -79,7 +85,7 @@ rustc-hash = "2"
 # lookahead/backrefs); fraction::BigFraction is the SAME exact-rational type used
 # for `multipleOf` divisibility. Both are already transitive deps, so no new
 # downloads — but they become direct deps so fast_schema can use them.
-fancy-regex = "0.18"
+fancy-regex = "0.19"
 fraction = "0.15"
 # Exact cross-type number equality for enum/const/uniqueItems (same semantics
 # jsonschema uses via jsonschema-value's cmp::equal). Already transitive.
@@ -92,6 +98,10 @@ argon2 = "0.5"
 bcrypt = "0.16"
 # PBKDF2-HMAC-SHA256 (RustCrypto) — pure-Rust KDF.
 pbkdf2 = "0.12"
+# sha2 is consumed ONLY by pbkdf2 (digest 0.10). Do NOT bump to 0.11: that
+# moves `Sha256` to digest 0.11 while pbkdf2 0.12 still requires digest 0.10,
+# so `pbkdf2_hmac::<Sha256>` stops compiling (E0277 CoreProxy). Revisit only
+# together with a pbkdf2 release that depends on digest 0.11.
 sha2 = "0.10"
 # HTML templating (fast, safe, no eval).
 minijinja = "2"
@@ -112,6 +122,13 @@ proptest = "1"
 [features]
 default = ["fast-email"]
 fast-email = ["dep:fast_chemail"]
+# Diagnostic-only gate for the `native-bench` binary (see the [[bin]] below):
+# without this feature the bin is not a default target, so `napi build` — and
+# therefore every shipped cross-compiled artifact — never links it. The napi
+# cross toolchains cannot resolve the aws-lc-sys C symbols an executable needs
+# (`undefined reference to __isoc23_sscanf`), while a cdylib tolerates them.
+# Run it with: cargo run --release --features native-bench --bin native-bench
+native-bench = []
 
 # Codify the CI clippy gate (`cargo clippy --all-targets -- -D warnings`) so a
 # bare local `cargo clippy` fails on the same lints — no flag drift between

package/README.md

@@ -187,17 +187,19 @@ For coverage floors, the typecheck/test configs, and the full test matrix, see
 ## Publishing
 
 The package ships **all platform addons in a single tarball**. Push a `v*` tag
-and CI builds + publishes every platform to npm; or use `bun run publish:manual`
+and CI builds + publishes every platform to npm; or use `bun run release:manual`
 for a quick single-platform release:
 
 ```bash
-bun run publish:manual -- --increment minor  # bump + tag + build + publish
-bun run publish:manual:dry                   # print the plan, change nothing
+bun run release minor          # bump + verify + commit + tag (CI publishes)
+bun run release:manual         # same, but also builds + publishes locally
+bun run release:dry            # print the plan, change nothing
 ```
 
-Run `bun run check:version` before tagging (it verifies `package.json`,
-`Cargo.toml`, and `CHANGELOG.md` agree). See [`docs/REPO_MAP.md`](./docs/REPO_MAP.md)
-§6 for the full flow.
+`bun run release` uses the shared canonical flow (`scripts/release.ts` +
+`.release.json`), syncing `package.json`, `Cargo.toml`, `Cargo.lock`, and
+`CHANGELOG.md`. Run `bun run check:version` before tagging (it verifies they
+agree). See [`docs/REPO_MAP.md`](./docs/REPO_MAP.md) §6 for the full flow.
 
 ## Documentation
 

package/dist/index.d.ts

@@ -2936,6 +2936,170 @@ export declare const rust: RustClient;
 export type ProvenClient = RustClient;
 /** The full `rust.*` surface, exposed for audit. Same object as `rust`. */
 export declare const proven: ProvenClient;
+/** Numeric op ids — mirror `rust/task/ops.rs`. */
+export declare const TASK_OP: {
+	/** args `[u32 maxDecompressed LE][gzip bytes]` (0 = native 64 MiB default). */
+	readonly gzipDecompress: 1;
+	/** args `[u32 rounds][u32 dkLen][u32 saltLen][salt][password]`. */
+	readonly pbkdf2Sha256: 2;
+	/** `gzipDecompress` writing into a caller buffer (zero-copy output). */
+	readonly gzipDecompressInto: 3;
+	/** args `[u32 pwLen][u32 phcLen][password][phc]` → body is one byte (1 = match). */
+	readonly argon2Verify: 4;
+	/** args `[u32 maxDecompressed LE][brotli bytes]` (0 = native 64 MiB default). */
+	readonly brotliDecompress: 5;
+	/** `brotliDecompress` writing into a caller buffer (zero-copy output). */
+	readonly brotliDecompressInto: 6;
+	/** args `[u32 level][gzip bytes]` (level clamped to 0-9 natively). */
+	readonly gzipCompress: 7;
+};
+/** A task op name (`gzipDecompress`). */
+export type TaskOpName = keyof typeof TASK_OP;
+/** Completion status codes (mirror `rust/task/ops.rs`). */
+export declare const TASK_STATUS_OK = 0;
+/** The op returned an error; the body is the UTF-8 error message. */
+export declare const TASK_STATUS_ERROR = 1;
+/** The task was cancelled before/while it ran; the body is empty. */
+export declare const TASK_STATUS_CANCELLED = 2;
+/**
+ * Pack the `gzip.decompress` task args: `[u32 maxDecompressed LE][gzip bytes]`.
+ *
+ * @param data            Compressed gzip bytes.
+ * @param maxDecompressed Output cap in bytes; `undefined`/`0` selects the
+ *                        native 64 MiB decompression-bomb default.
+ * @param out             Optional caller-owned destination (>= `4 + data.length`),
+ *                        returned as a view. Native copies args on submit, so the
+ *                        same buffer may be reused for the next submission — but
+ *                        only while the caller stays SYNCHRONOUS (a zero-copy
+ *                        retry re-submits after an await and must own its memory).
+ * @returns A packed args buffer.
+ */
+export declare function encodeGzipDecompressArgs(data: Uint8Array, maxDecompressed?: number, out?: Uint8Array): Uint8Array;
+/**
+ * Pack the `brotli.decompress` task args: `[u32 maxDecompressed LE][bytes]`.
+ *
+ * @param data            Compressed brotli bytes.
+ * @param maxDecompressed Output cap in bytes (`undefined`/`0` → native 64 MiB).
+ * @param out             Optional caller-owned destination (see the gzip form).
+ * @returns A packed args buffer.
+ */
+export declare function encodeBrotliDecompressArgs(data: Uint8Array, maxDecompressed?: number, out?: Uint8Array): Uint8Array;
+/**
+ * Pack the `gzip.compress` task HEADER: `[u32 level]`. The payload is passed
+ * separately so it can be read in place (zero-copy input) instead of copied.
+ *
+ * @param level Deflate level (`0`-`9`, clamped natively).
+ * @param out   Optional caller-owned destination (>= 4 bytes).
+ * @returns The 4-byte header.
+ */
+export declare function encodeGzipCompressHeader(level?: number, out?: Uint8Array): Uint8Array;
+/**
+ * Pack the `argon2id.verify` task args:
+ * `[u32 pwLen][u32 phcLen][password][phc]`. No `out` parameter on purpose: a
+ * shared scratch would keep a plaintext password alive far longer than a
+ * per-call allocation, which is the wrong trade for a secret.
+ *
+ * @param password Candidate password bytes.
+ * @param phc      PHC string bytes (`$argon2id$...`).
+ * @returns A packed args buffer owned by the caller (Rust copies it on submit).
+ */
+export declare function encodeArgon2VerifyArgs(password: Uint8Array, phc: Uint8Array): Uint8Array;
+/**
+ * Safe upper bound on the gzip size of `n` input bytes: deflate's worst case is
+ * stored blocks (5 bytes per block) plus the 18-byte gzip wrapper. The 16 KiB
+ * block assumption is deliberately conservative (real blocks are 64 KiB), so a
+ * destination sized with this can never be too small — no retry round trip.
+ *
+ * @param n Uncompressed input length in bytes.
+ * @returns An upper bound in bytes.
+ */
+export declare function gzipCompressUpperBound(n: number): number;
+/**
+ * Starting capacity for a brotli zero-copy destination. Brotli carries no
+ * ISIZE trailer, so there is no exact hint: this is a ratio guess, and the
+ * needed-size retry lands the exact size if it falls short.
+ *
+ * @param compressedLen Compressed input length in bytes.
+ * @returns A capacity guess in bytes (floored at the runtime's zero-copy size).
+ */
+export declare function brotliCapacityGuess(compressedLen: number): number;
+/**
+ * Pack the `pbkdf2.sha256` task args:
+ * `[u32 rounds][u32 dkLen][u32 saltLen][salt][password]`.
+ *
+ * @param password Password bytes (the PBKDF2 secret).
+ * @param salt     Salt bytes.
+ * @param rounds   Iteration count (clamped to >= 1 natively).
+ * @param dkLen    Derived-key length in bytes (default 32, capped at 1 MiB).
+ * @returns A packed args buffer owned by the caller (Rust copies it on submit).
+ */
+export declare function encodePbkdf2Args(password: Uint8Array, salt: Uint8Array, rounds: number, dkLen?: number): Uint8Array;
+/** Per-call options for an offloaded task. */
+export interface TaskRunOptions {
+	/** Abort the task; it completes with a cancelled error. */
+	signal?: AbortSignal;
+	/** Decompress ops: output cap in bytes (default native 64 MiB bomb cap). */
+	maxDecompressed?: number;
+	/** `gzipCompress` only: deflate level `0`-`9` (default `6`). */
+	level?: number;
+}
+/** Options for {@link TaskRuntime.pbkdf2Sha256}. */
+export interface Pbkdf2RunOptions extends TaskRunOptions {
+	/** Iteration count (clamped to >= 1 natively). */
+	rounds: number;
+	/** Derived-key length in bytes (default 32). */
+	dkLen?: number;
+}
+/** Runtime introspection snapshot. */
+export interface TaskStats {
+	/** Pool worker count (0 when the pool has not started). */
+	threads: number;
+	/** Finished-but-undrained completions in the native ring. */
+	pending: number;
+	/** JS promises currently awaiting a completion. */
+	inflight: number;
+	/** Completions resolved since the runtime was created. */
+	completed: number;
+	/** Drain rounds run on the JS thread (one per doorbell, plus coalesced work). */
+	drains: number;
+	/** Largest number of completions carried by a single drain round. */
+	maxBatch: number;
+	/** Zero-copy attempts that had to retry at the exact needed size. */
+	tooSmallRetries: number;
+}
+/** Off-thread task runtime handle. */
+export interface TaskRuntime {
+	/** gzip-decompress `data` on a pool thread (keeps the 64 MiB bomb cap). */
+	gzipDecompress(data: Uint8Array, options?: TaskRunOptions): Promise<Uint8Array>;
+	/** brotli-decompress `data` on a pool thread (keeps the 64 MiB bomb cap). */
+	brotliDecompress(data: Uint8Array, options?: TaskRunOptions): Promise<Uint8Array>;
+	/** gzip-compress `data` on a pool thread. */
+	gzipCompress(data: Uint8Array, options?: TaskRunOptions): Promise<Uint8Array>;
+	/** Verify a password against a PHC string on a pool thread (10-200 ms CPU). */
+	argon2Verify(password: Uint8Array, phc: Uint8Array, options?: TaskRunOptions): Promise<boolean>;
+	/** PBKDF2-HMAC-SHA256 on a pool thread (10-200 ms CPU, 1-64 B output). */
+	pbkdf2Sha256(password: Uint8Array, salt: Uint8Array, options: Pbkdf2RunOptions): Promise<Uint8Array>;
+	/** Pool / ring / in-flight counters. */
+	stats(): TaskStats;
+	/** Cancel everything in flight, stop the pool, release the doorbell. */
+	shutdown(): void;
+}
+/** Options for {@link createTaskRuntime}. */
+export interface TaskRuntimeOptions {
+	/** Pool worker count; `0`/omitted → native default (cores − 1). */
+	threads?: number;
+}
+/**
+ * Get the off-thread task runtime (created on first use, then shared). Binds
+ * the Bun ffi surface lazily.
+ *
+ * @example
+ * ```ts
+ * const tasks = createTaskRuntime()
+ * const out = await tasks.gzipDecompress(compressed)
+ * ```
+ */
+export declare function createTaskRuntime(options?: TaskRuntimeOptions): TaskRuntime;
 /** Recommended implementation for an operation. */
 export type OpImpl = "native" | "js";
 /** A selection decision: recommended implementation + rationale note. */