castrum 0.7.0 → 0.9.0

package/package.json

@@ -1,12 +1,12 @@
 {
     "name": "castrum",
-    "version": "0.7.0",
+    "version": "0.9.0",
     "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": "index.ts",
-    "module": "index.ts",
-    "types": "index.ts",
+    "main": "dist/index.js",
+    "module": "dist/index.js",
+    "types": "dist/index.d.ts",
     "license": "MIT",
     "keywords": [
         "bun",
@@ -29,27 +29,58 @@
         "access": "public"
     },
     "exports": {
-        ".": "./index.ts"
+        ".": {
+            "types": "./dist/index.d.ts",
+            "bun": "./index.ts",
+            "node": "./dist/index.js",
+            "default": "./dist/index.js"
+        },
+        "./package.json": "./package.json"
     },
     "files": [
         "index.ts",
-        "bench.ts",
+        "dist",
         "src",
-        "rust",
-        "Cargo.toml",
+        "docs",
         "README.md",
-        "*.node"
+        "*.node",
+        "!src/bench",
+        "!src/baseline"
     ],
     "scripts": {
         "build": "napi build --release --platform",
+        "build:perf": "bash scripts/build-perf.sh",
+        "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 && 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",
-        "artifacts": "napi artifacts",
+        "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",
+        "audit": "bun audit",
         "publish:manual": "node scripts/publish-manual.mjs",
         "publish:manual:dry": "node scripts/publish-manual.mjs --dry-run",
-        "prepublishOnly": "node scripts/prepublish.mjs",
+        "prepublishOnly": "bun run build:js && node scripts/prepublish.mjs",
+        "check:proven": "bun scripts/check-proven.ts",
+        "check:proven:fail": "bun scripts/check-proven.ts --fail",
+        "check:annotate": "bun scripts/annotate-performance.ts",
+        "check:annotate:dry": "bun scripts/annotate-performance.ts --dry-run",
+        "check:docs": "bun run check && bun run check:annotate && bun run check:proven",
         "bench:http": "bun run bench/run-bench.ts",
         "bench:http:smoke": "bun run bench/run-bench.ts smoke",
         "bench:http:stress": "bun run bench/run-bench.ts stress",
@@ -62,13 +93,22 @@
         "bench:http:elysia": "bun run bench/run-bench.ts '' elysia",
         "bench:http:ingress": "bun run bench/run-bench.ts '' ingress",
         "bench:http:bun-only": "bun run bench/run-bench.ts '' bun",
-        "bench:http:all-heavy": "bun run bench/run-bench.ts 1"
+        "bench:http:all-heavy": "bun run bench/run-bench.ts 1",
+        "bench:startup": "bun run bench/startup.ts",
+        "bench:ffi": "bun run bench/ffi-all.ts",
+        "bench:ffi:load": "bun run bench/ffi-load.ts",
+        "bench:ffi:public": "bun run bench/ffi-public.ts",
+        "bench:ffi:workers": "bun run bench/ffi-workers.ts",
+        "verify:native:batch": "bun run scripts/verify-native-batch.ts"
     },
-    "dependencies": {
-        "crc-32": "^1.2.2",
-        "fast-json-patch": "^3.1.1",
-        "mime-types": "^3.0.2",
-        "validator": "^13.15.35"
+    "dependencies": {},
+    "peerDependencies": {
+        "@types/node": ">=20"
+    },
+    "peerDependenciesMeta": {
+        "@types/node": {
+            "optional": true
+        }
     },
     "devDependencies": {
         "@elysia/cors": "^1.4.2",
@@ -76,19 +116,32 @@
         "@types/bun": "^1.3.14",
         "@types/mime-types": "^3.0.1",
         "@types/validator": "^13.15.10",
-        "elysia": "^1.4.0"
+        "ajv": "^8.20.0",
+        "crc-32": "^1.2.2",
+        "dts-bundle-generator": "^9.5.1",
+        "elysia": "^1.4.0",
+        "fast-json-patch": "^3.1.1",
+        "mime-types": "^3.0.2",
+        "typescript": "5.9.3",
+        "validator": "^13.15.35"
+    },
+    "overrides": {
+        "typescript": "5.9.3"
     },
     "engines": {
-        "bun": ">=1.1.0"
+        "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-gnu",
+            "x86_64-unknown-linux-musl"
         ]
     }
 }

package/src/data/json-rows.ts

@@ -1,17 +1,17 @@
-import { encoder } from "../shared/bytes";
+import { encoder } from '../shared/bytes'
 
 export interface JsonRowNested {
-  version: number;
-  createdAt: string;
+  version: number
+  createdAt: string
 }
 
 export interface JsonRow {
-  id: number;
-  name: string;
-  active: boolean;
-  score: number;
-  tags: string[];
-  nested: JsonRowNested;
+  id: number
+  name: string
+  active: boolean
+  score: number
+  tags: string[]
+  nested: JsonRowNested
 }
 
 export function createJsonRows(rows: number): JsonRow[] {
@@ -20,14 +20,14 @@ export function createJsonRows(rows: number): JsonRow[] {
     name: `user_${i}`,
     active: i % 2 === 0,
     score: i * 1.25,
-    tags: ["alpha", "beta", "gamma"],
+    tags: ['alpha', 'beta', 'gamma'],
     nested: {
       version: i % 10,
-      createdAt: "2026-01-01T00:00:00Z",
+      createdAt: '2026-01-01T00:00:00Z',
     },
-  }));
+  }))
 }
 
 export function jsonRowsBytes(rows: number): Uint8Array {
-  return encoder.encode(JSON.stringify(createJsonRows(rows)));
+  return encoder.encode(JSON.stringify(createJsonRows(rows)))
 }

package/src/ingress/body.ts

@@ -0,0 +1,149 @@
+// src/ingress/body.ts — Streaming request-body reading for the async ingress
+// API.
+
+const EMPTY_BODY = new Uint8Array(0)
+
+/** Read the request body once, enforcing the size guard when enabled. */
+export function readRequestBodyOnce(
+  req: Request,
+  maxBytes: number,
+  guard: boolean,
+  timeoutMs?: number,
+): Promise<Uint8Array> {
+  if (req.body === null) {
+    return Promise.resolve(EMPTY_BODY)
+  }
+
+  return readBodyWithLimit(req, maxBytes, guard, timeoutMs)
+}
+
+function bodyTooLargeError(): Error & { code?: string } {
+  const err = new Error('BODY_TOO_LARGE') as Error & { code?: string }
+  err.code = 'BODY_TOO_LARGE'
+  return err
+}
+
+/**
+ * Stream-read the request body, enforcing the size guard when enabled and an
+ * optional overall deadline.
+ *
+ * Errors carry `err.code`:
+ * - `BODY_TOO_LARGE` when `guard` is on and the body exceeds `maxBytes`
+ *   (thrown as soon as the limit is crossed — the body is never fully
+ *   buffered first, which is the slowloris/large-body protection).
+ * - `REQUEST_TIMEOUT` when `timeoutMs` elapses before the body completes.
+ */
+export async function readBodyWithLimit(
+  req: Request,
+  maxBytes: number,
+  guard: boolean,
+  timeoutMs?: number,
+): Promise<Uint8Array> {
+  const body = req.body
+
+  if (!body) {
+    return EMPTY_BODY
+  }
+
+  const deadline = timeoutMs && timeoutMs > 0 ? timeoutMs : 0
+  let timer: ReturnType<typeof setTimeout> | undefined
+  const timeout = new Promise<never>((_resolve, reject) => {
+    if (deadline <= 0) return
+    timer = setTimeout(() => reject(timeoutError()), deadline)
+    // Don't let a pending body timeout keep the event loop alive once the
+    // request has otherwise completed (Node; a no-op under Bun).
+    timer.unref?.()
+  })
+
+  // Fast path: a declared Content-Length lets us PROVE the body fits the
+  // guard before reading, so one native `arrayBuffer()` read replaces the
+  // reader + per-chunk `Promise.race` + `concatUint8Arrays` churn (the bench
+  // POSTs are single-shot bodies — this removes ~4-6 allocations per write
+  // request). The deadline (when set) is still enforced with a single race,
+  // not one per chunk. `req.arrayBuffer()` is bounded by the server's
+  // `maxRequestBodySize`, and the post-read length re-check catches a client
+  // that lies about Content-Length.
+  const declared = req.headers.get('content-length')
+  if (declared !== null) {
+    const declaredLen = Number(declared)
+    if (Number.isFinite(declaredLen)) {
+      if (guard && declaredLen > maxBytes) {
+        throw bodyTooLargeError()
+      }
+      try {
+        const buf =
+          deadline > 0 ? await Promise.race([req.arrayBuffer(), timeout]) : await req.arrayBuffer()
+        const bytes = new Uint8Array(buf)
+        if (guard && bytes.byteLength > maxBytes) {
+          throw bodyTooLargeError()
+        }
+        return bytes
+      } finally {
+        clearTimeout(timer)
+      }
+    }
+  }
+
+  const reader = body.getReader()
+  const chunks: Uint8Array[] = []
+  let total = 0
+  // True when the stream was fully read to `done` — on that path the reader is
+  // already closed, so the `cancel()` in `finally` is a wasted async round-trip
+  // per request. It is still required when the loop exits early (timeout/error).
+  let completed = false
+
+  try {
+    for (;;) {
+      const { done, value } =
+        deadline > 0 ? await Promise.race([reader.read(), timeout]) : await reader.read()
+
+      if (done) {
+        completed = true
+        break
+      }
+      if (!value) continue
+
+      total += value.byteLength
+
+      if (guard && total > maxBytes) {
+        throw bodyTooLargeError()
+      }
+
+      chunks.push(value)
+    }
+  } finally {
+    clearTimeout(timer)
+    // Release the underlying stream. Cancelling while a read() is still
+    // pending (the timeout case) can resolve that pending read() as `done`
+    // and RACE the timeout rejection — so reject first, cancel only AFTER
+    // the loop has settled. The `.catch` keeps the cancel from masking a
+    // thrown REQUEST_TIMEOUT / BODY_TOO_LARGE. On the normal `done` path the
+    // stream is already closed, so skip the cancel entirely.
+    if (!completed) {
+      await reader.cancel().catch(() => {})
+    }
+  }
+
+  return concatUint8Arrays(chunks, total)
+}
+
+function timeoutError(): Error & { code?: string } {
+  const err = new Error('REQUEST_TIMEOUT') as Error & { code?: string }
+  err.code = 'REQUEST_TIMEOUT'
+  return err
+}
+
+function concatUint8Arrays(chunks: Uint8Array[], total: number): Uint8Array {
+  if (chunks.length === 0) return EMPTY_BODY
+  if (chunks.length === 1) return chunks[0] ?? EMPTY_BODY
+
+  const out = new Uint8Array(total)
+  let offset = 0
+
+  for (const chunk of chunks) {
+    out.set(chunk, offset)
+    offset += chunk.byteLength
+  }
+
+  return out
+}

package/src/ingress/constants.ts

@@ -1,56 +1,228 @@
 // src/ingress/constants.ts — SINGLE SOURCE OF TRUTH for ingress binary layout constants
-// These are read from the Rust native addon to eliminate duplication across:
+// These are read from Rust to eliminate duplication across:
 //   - src/ingress/index.ts
 //   - bench/servers/ingress-server.ts
 //   - Any future consumers
 //
-// IMPORTANT: Do NOT hardcode these values. They come from Rust's ingress_constants.rs
-// and are typed on the NativeAddon interface (src/native/index.ts).
+// IMPORTANT: Do NOT hardcode these values. They come from Rust's
+// `ingress/output.rs` (the single numeric source), projected to JS via either
+// `ingress_constants.rs` (NAPI) or the C-ABI layout blob `rust/ffi.rs`
+// `IngressLayout` (`castrum_ingress_layout`). Both read the same numbers, so
+// they cannot drift.
 
-import addon from "../native";
+import { getAddon } from '../native'
+import { getBunFFI, type BunFFI } from '../native/ffi'
+
+// Transport: bun:ffi is PRIMARY on Bun, so the layout is read through the
+// C-ABI blob WITHOUT dlopening the napi addon. Node — or forced
+// `CASTRUM_FFI_MODE=napi`, a missing symbol, or a failed bind-time self-test —
+// falls back to the napi addon. This is the ONE module that touches native at
+// import time; everything else in the package stays lazy.
+const ffi = getBunFFI()
+
+// Slot order mirrors the `#[repr(C)] IngressLayout` struct in rust/ffi.rs
+// (38 × u32 LE). Drift is guarded by the Rust unit test
+// `ingress_layout_c_abi_matches_output_source` and by the pinned values in the
+// bun:ffi bind-time self-test (a reorder → self-test fails → napi fallback).
+const SLOT = {
+  OUT_VERDICT: 0,
+  OUT_ERROR_CODE: 1,
+  OUT_STATUS: 2,
+  OUT_FLAGS: 3,
+  OUT_RATE_LIMIT: 4,
+  OUT_RATE_REMAINING: 5,
+  OUT_RATE_RESET: 6,
+  OUT_RETRY_AFTER: 7,
+  OUT_COOKIES_JSON_LEN: 8,
+  OUT_QUERY_JSON_LEN: 9,
+  OUT_HEADER_VARIANT: 10,
+  OUT_BODY_JSON_LEN: 11,
+  OUT_DATA_START: 12,
+  FLAG_HAS_COOKIES: 13,
+  FLAG_HAS_QUERY: 14,
+  FLAG_BODY_VALID_JSON: 15,
+  FLAG_SCHEMA_VALID: 16,
+  FLAG_CORS_ALLOWED: 17,
+  FLAG_IS_PREFLIGHT: 18,
+  FLAG_RATE_LIMITED: 19,
+  FLAG_HTTPS: 20,
+  FLAG_TRUSTED_PROXY: 21,
+  FLAG_BODY_TRUNCATED: 22,
+  HV_JSON: 23,
+  HV_CORS_SIMPLE: 24,
+  HV_CORS_PREFLIGHT: 25,
+  HV_RATE_ACTIVE: 26,
+  HV_RATE_LIMITED: 27,
+  HV_COUNT: 28,
+  ERR_NONE: 29,
+  ERR_CORS_PREFLIGHT: 30,
+  ERR_RATE_LIMITED: 31,
+  ERR_BODY_TOO_LARGE: 32,
+  ERR_INVALID_JSON: 33,
+  ERR_SCHEMA_VALIDATION: 34,
+  ERR_BAD_REQUEST: 35,
+  ERR_REQUEST_TOO_LARGE: 36,
+  ERR_INTERNAL: 37,
+} as const
+
+type Layout = Record<keyof typeof SLOT, number>
+
+/** Read the layout via the bun:ffi C-ABI blob (Bun primary path). */
+function readLayoutViaFfi(ffiLive: BunFFI): Layout {
+  const buf = new Uint8Array(38 * 4)
+  ffiLive.ingressLayout(buf)
+  const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength)
+  const out = {} as Layout
+  for (const key of Object.keys(SLOT) as (keyof typeof SLOT)[]) {
+    out[key] = view.getUint32(SLOT[key] * 4, true)
+  }
+  return out
+}
+
+/** Read the layout via the napi addon (Node / fallback). */
+function readLayoutViaNapi(): Layout {
+  const addon = getAddon()
+  return {
+    OUT_VERDICT: addon.INGRESS_OUT_VERDICT,
+    OUT_ERROR_CODE: addon.INGRESS_OUT_ERROR_CODE,
+    OUT_STATUS: addon.INGRESS_OUT_STATUS,
+    OUT_FLAGS: addon.INGRESS_OUT_FLAGS,
+    OUT_RATE_LIMIT: addon.INGRESS_OUT_RATE_LIMIT,
+    OUT_RATE_REMAINING: addon.INGRESS_OUT_RATE_REMAINING,
+    OUT_RATE_RESET: addon.INGRESS_OUT_RATE_RESET,
+    OUT_RETRY_AFTER: addon.INGRESS_OUT_RETRY_AFTER,
+    OUT_COOKIES_JSON_LEN: addon.INGRESS_OUT_COOKIES_JSON_LEN,
+    OUT_QUERY_JSON_LEN: addon.INGRESS_OUT_QUERY_JSON_LEN,
+    OUT_HEADER_VARIANT: addon.INGRESS_OUT_HEADER_VARIANT,
+    OUT_BODY_JSON_LEN: addon.INGRESS_OUT_BODY_JSON_LEN,
+    OUT_DATA_START: addon.INGRESS_OUT_DATA_START,
+    FLAG_HAS_COOKIES: addon.INGRESS_FLAG_HAS_COOKIES,
+    FLAG_HAS_QUERY: addon.INGRESS_FLAG_HAS_QUERY,
+    FLAG_BODY_VALID_JSON: addon.INGRESS_FLAG_BODY_VALID_JSON,
+    FLAG_SCHEMA_VALID: addon.INGRESS_FLAG_SCHEMA_VALID,
+    FLAG_CORS_ALLOWED: addon.INGRESS_FLAG_CORS_ALLOWED,
+    FLAG_IS_PREFLIGHT: addon.INGRESS_FLAG_IS_PREFLIGHT,
+    FLAG_RATE_LIMITED: addon.INGRESS_FLAG_RATE_LIMITED,
+    FLAG_HTTPS: addon.INGRESS_FLAG_HTTPS,
+    FLAG_TRUSTED_PROXY: addon.INGRESS_FLAG_TRUSTED_PROXY,
+    FLAG_BODY_TRUNCATED: addon.INGRESS_FLAG_BODY_TRUNCATED,
+    HV_JSON: addon.INGRESS_HV_JSON,
+    HV_CORS_SIMPLE: addon.INGRESS_HV_CORS_SIMPLE,
+    HV_CORS_PREFLIGHT: addon.INGRESS_HV_CORS_PREFLIGHT,
+    HV_RATE_ACTIVE: addon.INGRESS_HV_RATE_ACTIVE,
+    HV_RATE_LIMITED: addon.INGRESS_HV_RATE_LIMITED,
+    HV_COUNT: addon.INGRESS_HV_COUNT,
+    ERR_NONE: addon.INGRESS_ERR_NONE,
+    ERR_CORS_PREFLIGHT: addon.INGRESS_ERR_CORS_PREFLIGHT,
+    ERR_RATE_LIMITED: addon.INGRESS_ERR_RATE_LIMITED,
+    ERR_BODY_TOO_LARGE: addon.INGRESS_ERR_BODY_TOO_LARGE,
+    ERR_INVALID_JSON: addon.INGRESS_ERR_INVALID_JSON,
+    ERR_SCHEMA_VALIDATION: addon.INGRESS_ERR_SCHEMA_VALIDATION,
+    ERR_BAD_REQUEST: addon.INGRESS_ERR_BAD_REQUEST,
+    ERR_REQUEST_TOO_LARGE: addon.INGRESS_ERR_REQUEST_TOO_LARGE,
+    ERR_INTERNAL: addon.INGRESS_ERR_INTERNAL,
+  }
+}
+
+const L: Layout = ffi !== null ? readLayoutViaFfi(ffi) : readLayoutViaNapi()
 
 // ── Output buffer layout ───────────────────────────────────
-export const OUT_VERDICT: number = addon.INGRESS_OUT_VERDICT;
-export const OUT_ERROR_CODE: number = addon.INGRESS_OUT_ERROR_CODE;
-export const OUT_STATUS: number = addon.INGRESS_OUT_STATUS;
-export const OUT_FLAGS: number = addon.INGRESS_OUT_FLAGS;
-export const OUT_RATE_LIMIT: number = addon.INGRESS_OUT_RATE_LIMIT;
-export const OUT_RATE_REMAINING: number = addon.INGRESS_OUT_RATE_REMAINING;
-export const OUT_RATE_RESET: number = addon.INGRESS_OUT_RATE_RESET;
-export const OUT_RETRY_AFTER: number = addon.INGRESS_OUT_RETRY_AFTER;
-export const OUT_COOKIES_JSON_LEN: number = addon.INGRESS_OUT_COOKIES_JSON_LEN;
-export const OUT_QUERY_JSON_LEN: number = addon.INGRESS_OUT_QUERY_JSON_LEN;
-export const OUT_HEADER_VARIANT: number = addon.INGRESS_OUT_HEADER_VARIANT;
-export const OUT_BODY_JSON_LEN: number = addon.INGRESS_OUT_BODY_JSON_LEN;
-export const OUT_DATA_START: number = addon.INGRESS_OUT_DATA_START;
-
-// ── Flags ──────────────────────────────────────────────────
-export const FLAG_HAS_COOKIES: number = addon.INGRESS_FLAG_HAS_COOKIES;
-export const FLAG_HAS_QUERY: number = addon.INGRESS_FLAG_HAS_QUERY;
-export const FLAG_BODY_VALID_JSON: number = addon.INGRESS_FLAG_BODY_VALID_JSON;
-export const FLAG_SCHEMA_VALID: number = addon.INGRESS_FLAG_SCHEMA_VALID;
-export const FLAG_CORS_ALLOWED: number = addon.INGRESS_FLAG_CORS_ALLOWED;
-export const FLAG_IS_PREFLIGHT: number = addon.INGRESS_FLAG_IS_PREFLIGHT;
-export const FLAG_RATE_LIMITED: number = addon.INGRESS_FLAG_RATE_LIMITED;
-export const FLAG_HTTPS: number = addon.INGRESS_FLAG_HTTPS;
-export const FLAG_TRUSTED_PROXY: number = addon.INGRESS_FLAG_TRUSTED_PROXY;
-export const FLAG_BODY_TRUNCATED: number = addon.INGRESS_FLAG_BODY_TRUNCATED;
-
-// ── Header variant bits ────────────────────────────────────
-export const HV_JSON: number = addon.INGRESS_HV_JSON;
-export const HV_CORS_SIMPLE: number = addon.INGRESS_HV_CORS_SIMPLE;
-export const HV_CORS_PREFLIGHT: number = addon.INGRESS_HV_CORS_PREFLIGHT;
-export const HV_RATE_ACTIVE: number = addon.INGRESS_HV_RATE_ACTIVE;
-export const HV_RATE_LIMITED: number = addon.INGRESS_HV_RATE_LIMITED;
-export const HV_COUNT: number = addon.INGRESS_HV_COUNT;
-
-// ── Error codes ────────────────────────────────────────────
-export const ERR_CODE_NONE: number = addon.INGRESS_ERR_NONE;
-export const ERR_CODE_CORS_PREFLIGHT: number = addon.INGRESS_ERR_CORS_PREFLIGHT;
-export const ERR_CODE_RATE_LIMITED: number = addon.INGRESS_ERR_RATE_LIMITED;
-export const ERR_CODE_BODY_TOO_LARGE: number = addon.INGRESS_ERR_BODY_TOO_LARGE;
-export const ERR_CODE_INVALID_JSON: number = addon.INGRESS_ERR_INVALID_JSON;
-export const ERR_CODE_SCHEMA_VALIDATION: number = addon.INGRESS_ERR_SCHEMA_VALIDATION;
-export const ERR_CODE_BAD_REQUEST: number = addon.INGRESS_ERR_BAD_REQUEST;
-export const ERR_CODE_REQUEST_TOO_LARGE: number = addon.INGRESS_ERR_REQUEST_TOO_LARGE;
-export const ERR_CODE_INTERNAL: number = addon.INGRESS_ERR_INTERNAL;
+// Byte offsets into the fixed header of the native ingress OUTPUT buffer.
+// The header occupies [0, OUT_DATA_START); the cookie/query/body JSON sections
+// follow at OUT_DATA_START (see decode/packed-sections.ts). Read through the
+// C-ABI layout blob (Bun) or napi (Node) — never hardcoded.
+
+/** Offset of the verdict byte (0 = accepted, nonzero = terminal error). */
+export const OUT_VERDICT: number = L.OUT_VERDICT
+/** Offset of the error-code byte (see ERR_CODE_* below). */
+export const OUT_ERROR_CODE: number = L.OUT_ERROR_CODE
+/** Offset of the raw u16 status. */
+export const OUT_STATUS: number = L.OUT_STATUS
+/** Offset of the u32 flags word (see FLAG_* below). */
+export const OUT_FLAGS: number = L.OUT_FLAGS
+/** Offset of the u32 rate-limit budget (U32_MAX = disabled). */
+export const OUT_RATE_LIMIT: number = L.OUT_RATE_LIMIT
+/** Offset of the u32 rate-limit remaining count. */
+export const OUT_RATE_REMAINING: number = L.OUT_RATE_REMAINING
+/** Offset of the u64 rate-limit window reset (ms epoch). */
+export const OUT_RATE_RESET: number = L.OUT_RATE_RESET
+/** Offset of the u64 Retry-After value (ms). */
+export const OUT_RETRY_AFTER: number = L.OUT_RETRY_AFTER
+/** Offset of the u32 cookies-JSON section length. */
+export const OUT_COOKIES_JSON_LEN: number = L.OUT_COOKIES_JSON_LEN
+/** Offset of the u32 query-JSON section length. */
+export const OUT_QUERY_JSON_LEN: number = L.OUT_QUERY_JSON_LEN
+/** Offset of the header-template variant byte (see HV_* below). */
+export const OUT_HEADER_VARIANT: number = L.OUT_HEADER_VARIANT
+/** Offset of the u32 body-JSON section length. */
+export const OUT_BODY_JSON_LEN: number = L.OUT_BODY_JSON_LEN
+/** Byte offset where the variable-length JSON sections begin. */
+export const OUT_DATA_START: number = L.OUT_DATA_START
+
+// ── Flags (bits within the OUT_FLAGS u32) ──────────────────
+/** Request carried a cookie header (cookie-JSON section present). */
+export const FLAG_HAS_COOKIES: number = L.FLAG_HAS_COOKIES
+/** Request carried a query string (query-JSON section present). */
+export const FLAG_HAS_QUERY: number = L.FLAG_HAS_QUERY
+/** The request body parsed as valid JSON. */
+export const FLAG_BODY_VALID_JSON: number = L.FLAG_BODY_VALID_JSON
+/** The request body validated against the ingress schema. */
+export const FLAG_SCHEMA_VALID: number = L.FLAG_SCHEMA_VALID
+/** The CORS engine allowed the request origin. */
+export const FLAG_CORS_ALLOWED: number = L.FLAG_CORS_ALLOWED
+/** The request was a CORS preflight (OPTIONS + request-method). */
+export const FLAG_IS_PREFLIGHT: number = L.FLAG_IS_PREFLIGHT
+/** The request was rate-limited. */
+export const FLAG_RATE_LIMITED: number = L.FLAG_RATE_LIMITED
+/** The request arrived over HTTPS (trusted-proxy scheme). */
+export const FLAG_HTTPS: number = L.FLAG_HTTPS
+/** The request came from a trusted proxy (per the proxy config). */
+export const FLAG_TRUSTED_PROXY: number = L.FLAG_TRUSTED_PROXY
+/** A declared output section overran the buffer (truncated). */
+export const FLAG_BODY_TRUNCATED: number = L.FLAG_BODY_TRUNCATED
+
+// ── Header variant bits (bits within the OUT_HEADER_VARIANT byte) ──
+/** Response body is JSON (`content-type: application/json`). */
+export const HV_JSON: number = L.HV_JSON
+/** CORS simple-request variant (Origin echoed + vary headers). */
+export const HV_CORS_SIMPLE: number = L.HV_CORS_SIMPLE
+/** CORS preflight variant (allow-methods/headers/max-age). */
+export const HV_CORS_PREFLIGHT: number = L.HV_CORS_PREFLIGHT
+/** Rate-limit active variant (`ratelimit-limit` header). */
+export const HV_RATE_ACTIVE: number = L.HV_RATE_ACTIVE
+/** Rate-limited variant (Retry-After emitted). */
+export const HV_RATE_LIMITED: number = L.HV_RATE_LIMITED
+/** Total number of header-variant combinations (32). */
+export const HV_COUNT: number = L.HV_COUNT
+
+// ── Error codes (bytes in OUT_ERROR_CODE) ──────────────────
+/** No error (accepted). */
+export const ERR_CODE_NONE: number = L.ERR_NONE
+/** CORS preflight rejected. */
+export const ERR_CODE_CORS_PREFLIGHT: number = L.ERR_CORS_PREFLIGHT
+/** Rate limit exceeded. */
+export const ERR_CODE_RATE_LIMITED: number = L.ERR_RATE_LIMITED
+/** Request body exceeded the size guard. */
+export const ERR_CODE_BODY_TOO_LARGE: number = L.ERR_BODY_TOO_LARGE
+/** Request body is not valid JSON. */
+export const ERR_CODE_INVALID_JSON: number = L.ERR_INVALID_JSON
+/** Request body failed schema validation. */
+export const ERR_CODE_SCHEMA_VALIDATION: number = L.ERR_SCHEMA_VALIDATION
+/** Malformed request (bad request line / headers). */
+export const ERR_CODE_BAD_REQUEST: number = L.ERR_BAD_REQUEST
+/** Request headers/URL exceeded the configured limits. */
+export const ERR_CODE_REQUEST_TOO_LARGE: number = L.ERR_REQUEST_TOO_LARGE
+/** Internal pipeline failure (maps to 500). */
+export const ERR_CODE_INTERNAL: number = L.ERR_INTERNAL
+
+/**
+ * JS-only error-code sentinel for a request-body read timeout in the async
+ * `createIngress` path.
+ *
+ * The native pipeline never emits this value — it is a JS body-reader error
+ * (`REQUEST_TIMEOUT` from `readBodyWithLimit`) mapped onto the numeric
+ * error-code contract so the shared status/name/message helpers stay
+ * consistent. Deliberately not sourced from Rust (see the header comment:
+ * numeric layout values come from the addon; this one is a JS-level error).
+ */
+export const ERR_CODE_REQUEST_TIMEOUT: number = -1