castrum 0.9.3 → 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

@@ -11,50 +11,49 @@
 // 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'
-
+// 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
 // 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,160 +1,177 @@
 {
-    "name": "castrum",
-    "version": "0.9.3",
-    "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",
-        "!src/bench",
-        "!src/baseline",
-        "!src/data"
-    ],
-    "scripts": {
-        "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",
-        "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"
+    "./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: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"
+    ]
+  }
+}