castrum 0.9.0 → 0.9.1

package/src/loader/index.ts

@@ -18,247 +18,58 @@
 //   - caching      → bounded LRU ("Hot Function Cache"), default key =
 //                    fnv1a64(input) (skipped for sustained-unique workloads),
 //                    opt-in per call via `{ key, cache }`
+//
+// Structure: this file is the DISPATCH CORE + factory. The pure pieces live
+// beside it: `types.ts` (public type surface), `state.ts` (internal dispatch
+// state), `ops.ts` (op registry), `cost.ts` (adaptive cost model), `batch.ts`
+// (LRU cache + tick coalescer). Public types are re-exported below.
 
+import { rust } from '../rust-ffi'
+import { encoder, viewForArrayBuffer } from '../shared/bytes'
+import type { SchemaValidator } from '../shared/packed'
+import {
+  createLruCache,
+  createTickCoalescer,
+  type LoadRequest,
+} from './batch'
+import { createCostModel, nowNs } from './cost'
 import {
-  LOADER_OPS,
   fnvBatchKeysInto,
-  type LoaderBulkArgs,
-  type LoaderOpArgs,
+  LOADER_OPS,
   type LoaderOpName,
   type LoaderOpSpec,
   type LoaderScalar,
-  type LoaderBulk,
 } from './ops'
-import { createCostModel, nowNs, type LoaderCostModel } from './cost'
-import {
-  createLruCache,
-  createTickCoalescer,
-  type LoaderCache,
-  type LoadRequest,
-  type TickCoalescer,
-} from './batch'
-import { rust } from '../rust-ffi'
-import { viewForArrayBuffer } from '../shared/bytes'
-import type { SchemaValidator } from '../shared/packed'
+import type { LoaderState, OpDispatchCtx, OpFnEntry } from './state'
+import { KEY_SEP } from './state'
+import type {
+  LoadableName,
+  Loader,
+  LoaderOpFn,
+  LoaderOpStats,
+  LoaderOptions,
+  LoaderSchemaFn,
+  LoaderStats,
+  LoadOptions,
+} from './types'
 
 // Re-export the op registry + types for introspection and authoring.
 export {
-  LOADER_OPS,
+  type BulkResult,
   LOADER_OP_NAMES,
-  type LoaderOpName,
-  type LoaderOpArgs,
-  type LoaderBulkArgs,
+  LOADER_OPS,
   type LoaderBulk,
-  type LoaderScalar,
+  type LoaderBulkArgs,
+  type LoaderOpArgs,
+  type LoaderOpName,
   type LoaderResultKind,
+  type LoaderScalar,
   type ScalarResult,
-  type BulkResult,
 } from './ops'
 
-// ── Public types ────────────────────────────────────────────────────────────
-
-/** Options for `createLoader()` / `loader.configure()`. */
-export interface LoaderOptions {
-  /** Let each op adapt `batchMin` from measured dispatch cost. Default true. */
-  adaptive?: boolean
-  /** Initial batch threshold in [2, 8]. Default 2 (batch wins for n >= 2). */
-  batchMin?: number
-  /** Max cached keys (bounded LRU). 0 disables caching. Default 256. */
-  maxCacheKeys?: number
-  /** Default `cache` behavior for `load()`. Default true. */
-  caching?: boolean
-  /** Sample timing every N dispatches (hot-path cost control). Default 32. */
-  sampleEvery?: number
-  /**
-   * `load()` dispatch strategy. `"auto"` (default) switches each op between
-   * `"single"` (low load → direct scalar call, no coalescer) and
-   * `"coalesce"` (rising load → one packed batch call) from observed load.
-   */
-  loadStrategy?: LoadStrategy
-}
-
-/** Options for `load()` / `opFn.load()`. */
-export interface LoadOptions {
-  /**
-   * Explicit cache key. When omitted (and caching is on) the default key is
-   * `fnv1a64(input)` — which costs one extra native call per load.
-   */
-  key?: string
-  /** Override the loader-wide caching toggle for this call. Default true. */
-  cache?: boolean
-}
-
-/** Per-op counters exposed on `opFn.stats`. */
-export interface LoaderOpStats {
-  scalarCalls: number
-  batchCalls: number
-  itemsDispatched: number
-  cachedHits: number
-  /** Current learned batch threshold for this op. */
-  batchMin: number
-  /** Current `load()` strategy: "single" (low load) or "coalesce" (bulk). */
-  mode: 'single' | 'coalesce'
-}
-
-/** Aggregate loader statistics. */
-export interface LoaderStats {
-  scalarCalls: number
-  batchCalls: number
-  itemsDispatched: number
-  flushes: number
-  cachedHits: number
-  cacheSize: number
-  cacheEvictions: number
-}
-
-/** A specialized, pre-bound op function returned by `loader(op)`. */
-export interface LoaderOpFn<K extends LoaderOpName> {
-  /** Single item → scalar result. */
-  (input: Uint8Array, ...rest: LoaderOpArgs[K]): LoaderScalar<K>
-  /** Bulk items → ONE packed batch call; same shape as `rust.batch.<op>`. */
-  (inputs: Uint8Array[], ...rest: LoaderBulkArgs<K>): LoaderBulk<K>
-  readonly name: K
-  readonly stats: LoaderOpStats
-  clear(): void
-  /** Sync cache peek (default key `fnv1a64(input)` unless `key` given). */
-  cache(input: Uint8Array, key?: string): LoaderScalar<K> | undefined
-  /**
-   * Coalesced, cache-aware load. Unavailable (`undefined`) on ops that require
-   * extra arguments (e.g. `hmacSha256`, `signCookie`) — use `run` for those.
-   */
-  load: K extends LoadableName ? LoaderLoadFn<K> : undefined
-}
-
-type LoaderLoadFn<K extends LoaderOpName> = (
-  input: Uint8Array,
-  opts?: LoadOptions,
-) => Promise<LoaderScalar<K>>
-
-/** Ops whose extra args are all optional/empty → they support `load()`. */
-type LoadableName = {
-  [K in LoaderOpName]: LoaderOpArgs[K] extends
-    | []
-    | [unknown?]
-    | [unknown?, unknown?]
-    | [unknown?, unknown?, unknown?]
-    ? K
-    : never
-}[LoaderOpName]
-
-/** A validator-bound helper returned by `loader.schema(validator)`. */
-export interface LoaderSchemaFn {
-  /** Single JSON document → valid? */
-  (input: Uint8Array): boolean
-  /** Bulk JSON documents → bitset (1 per doc). */
-  (inputs: Uint8Array[]): Uint8Array
-  /** Count how many bulk documents are valid. */
-  count(inputs: Uint8Array[]): number
-}
-
-/** The global callable loader. */
-export interface Loader {
-  /** Higher-order function: `loader(op)` → specialized hot op function. */
-  <K extends LoaderOpName>(op: K): LoaderOpFn<K>
-  /** Single-item dispatch. */
-  run<K extends LoaderOpName>(op: K, input: Uint8Array, ...rest: LoaderOpArgs[K]): LoaderScalar<K>
-  /** Bulk dispatch (one packed batch call, or adaptive scalar loop). */
-  run<K extends LoaderOpName>(
-    op: K,
-    inputs: Uint8Array[],
-    ...rest: LoaderBulkArgs<K>
-  ): LoaderBulk<K>
-  /** Coalesced, cache-aware load (ops with required extra args throw). */
-  load<K extends LoadableName>(
-    op: K,
-    input: Uint8Array,
-    opts?: LoadOptions,
-  ): Promise<LoaderScalar<K>>
-  /** Sync cache peek. */
-  cache<K extends LoaderOpName>(op: K, input: Uint8Array, key?: string): LoaderScalar<K> | undefined
-  /**
-   * Bind a `SchemaValidator` for repeated single/bulk JSON-schema validation
-   * plus a whole-batch `count`. The returned callable uses the loader's normal
-   * dispatch machinery (cost model + counters).
-   */
-  schema(validator: SchemaValidator): LoaderSchemaFn
-  /** Clear the shared cache (pending coalesced loads still flush). */
-  clear(): void
-  /** Update options at runtime. */
-  configure(options: LoaderOptions): void
-  readonly stats: LoaderStats
-  readonly opNames: LoaderOpName[]
-}
-
-// ── Internal state ──────────────────────────────────────────────────────────
-
-interface OpCounters {
-  scalarCalls: number
-  batchCalls: number
-  itemsDispatched: number
-  cachedHits: number
-}
-
-/** Load-dispatch strategy selector for `load()`. */
-type LoadStrategy = 'auto' | 'single' | 'coalesce'
-
-/**
- * Pre-bound per-op dispatch context — avoids Map lookups on the hot path.
- * Holds the load-aware `load()` strategy plus its cheap integer signals so
- * the single-vs-coalesce decision costs no Map lookup or allocation.
- */
-interface OpDispatchCtx {
-  cost: LoaderCostModel
-  counters: OpCounters
-  sampleEvery: number
-  /** Per-op sample tick counter (advances on every dispatch). */
-  counter: number
-  /** Current `load()` strategy for this op. */
-  mode: 'single' | 'coalesce'
-  /** Consecutive single-load flushes observed (coalesce mode only). */
-  singleStreak: number
-  /** A single-mode load is waiting on its microtask to dispatch. */
-  pendingSingle: boolean
-  pendingInput: Uint8Array | null
-  pendingResolve: ((value: unknown) => void) | null
-  pendingReject: ((error: unknown) => void) | null
-  pendingKey: string | undefined
-  /** Default-key attempts (adaptive key computation). */
-  keyAttempts: number
-  /** Default-key cache hits observed. */
-  keyHits: number
-  /** Periodic re-probe counter for skipped default keys. */
-  keyProbeCounter: number
-}
-
-/** A memoized op fn plus a hook to rebind its dispatch context on configure. */
-interface OpFnEntry {
-  op: LoaderOpName
-  fn: LoaderOpFn<LoaderOpName>
-  /** Rebind to a fresh context after `configure()` so dispatch + stats stay current. */
-  rebind(ctx: OpDispatchCtx): void
-}
-
-interface LoaderState {
-  options: Required<
-    Pick<
-      LoaderOptions,
-      'adaptive' | 'batchMin' | 'maxCacheKeys' | 'caching' | 'sampleEvery' | 'loadStrategy'
-    >
-  >
-  ctxs: Map<LoaderOpName, OpDispatchCtx>
-  cache: LoaderCache
-  coalescer: TickCoalescer
-  opFns: Map<LoaderOpName, OpFnEntry>
-  flushes: number
-  /** Reusable packed-input scratch for the zero-alloc fast flush (grows). */
-  packScratch: Uint8Array
-  /** Reusable packed-output buffer for the zero-alloc fast flush (grows). */
-  outScratch: Uint8Array
-  /** Reusable packed-key output buffer for the batched default-key flush. */
-  keyScratch: Uint8Array
-}
-
-const KEY_SEP = '\u0000'
+// Re-export the public type surface so `import type { LoaderOptions } from
+// '../loader'` keeps working (existing call sites).
+export * from './types'
 
 // ── Load-aware `load()` strategy + adaptive-key tuning ──
 /** Consecutive single-load flushes before an op drops the coalescer. */
@@ -268,7 +79,6 @@ const KEY_WARMUP = 8
 /** After warm-up with zero hits, re-probe the default key every N loads. */
 const KEY_PROBE_EVERY = 64
 
-/** Get (or lazily create) the dispatch context for an op. */
 function ctxFor(state: LoaderState, op: LoaderOpName): OpDispatchCtx {
   let ctx = state.ctxs.get(op)
   if (!ctx) {
@@ -299,6 +109,11 @@ function ctxFor(state: LoaderState, op: LoaderOpName): OpDispatchCtx {
   return ctx
 }
 
+/** Normalize a loader scalar result to bytes (the string-returning rust.* ops
+ * return strings on the Bun path — the loader's BYTES contract stays bytes). */
+const asBytes = (v: unknown): Uint8Array =>
+  typeof v === 'string' ? encoder.encode(v) : (v as Uint8Array)
+
 /** Build a bulk-shaped result by looping scalar calls (the adaptive fallback). */
 function scalarLoopBulk(spec: LoaderOpSpec, items: Uint8Array[], rest: unknown[]): unknown {
   const n = items.length
@@ -345,7 +160,7 @@ function scalarLoopBulk(spec: LoaderOpSpec, items: Uint8Array[], rest: unknown[]
       const out = new Array<Uint8Array>(n)
       let i = 0
       for (const item of items) {
-        out[i] = spec.scalar(item, ...itemRest(i)) as Uint8Array
+        out[i] = asBytes(spec.scalar(item, ...itemRest(i)))
         i++
       }
       return out
@@ -364,7 +179,7 @@ function dispatchSingle(
   c.scalarCalls++
   c.itemsDispatched++
   const t = ++ctx.counter % ctx.sampleEvery === 0 ? nowNs() : 0
-  const out = rest.length === 0 ? spec.scalar(input) : spec.scalar(input, ...rest)
+  const out = asBytes(rest.length === 0 ? spec.scalar(input) : spec.scalar(input, ...rest))
   if (t !== 0) ctx.cost.recordScalar(1, nowNs() - t)
   return out
 }

package/src/loader/state.ts

@@ -0,0 +1,84 @@
+// src/loader/state.ts — internal loader dispatch state (pure types).
+//
+// The per-op dispatch context, memoized op-fn entry, and the aggregate
+// `LoaderState` shared by the dispatch core (index.ts). `KEY_SEP` is the
+// cache-key separator for `op + '\0' + key`.
+
+import type { LoaderCache, TickCoalescer } from './batch'
+import type { LoaderCostModel } from './cost'
+import type { LoaderOpName } from './ops'
+import type { LoaderOpFn, LoaderOptions } from './types'
+
+// ── Internal state ──────────────────────────────────────────────────────────
+
+/** Per-op dispatch counters: scalar calls, batch calls, items dispatched, and
+ * cache hits. Advanced on every dispatch and exposed via `loader.stats()`. */
+export interface OpCounters {
+  scalarCalls: number
+  batchCalls: number
+  itemsDispatched: number
+  cachedHits: number
+}
+
+/**
+ * Pre-bound per-op dispatch context — avoids Map lookups on the hot path.
+ * Holds the load-aware `load()` strategy plus its cheap integer signals so
+ * the single-vs-coalesce decision costs no Map lookup or allocation.
+ */
+export interface OpDispatchCtx {
+  cost: LoaderCostModel
+  counters: OpCounters
+  sampleEvery: number
+  /** Per-op sample tick counter (advances on every dispatch). */
+  counter: number
+  /** Current `load()` strategy for this op. */
+  mode: 'single' | 'coalesce'
+  /** Consecutive single-load flushes observed (coalesce mode only). */
+  singleStreak: number
+  /** A single-mode load is waiting on its microtask to dispatch. */
+  pendingSingle: boolean
+  pendingInput: Uint8Array | null
+  pendingResolve: ((value: unknown) => void) | null
+  pendingReject: ((error: unknown) => void) | null
+  pendingKey: string | undefined
+  /** Default-key attempts (adaptive key computation). */
+  keyAttempts: number
+  /** Default-key cache hits observed. */
+  keyHits: number
+  /** Periodic re-probe counter for skipped default keys. */
+  keyProbeCounter: number
+}
+
+/** A memoized op fn plus a hook to rebind its dispatch context on configure. */
+export interface OpFnEntry {
+  op: LoaderOpName
+  fn: LoaderOpFn<LoaderOpName>
+  /** Rebind to a fresh context after `configure()` so dispatch + stats stay current. */
+  rebind(ctx: OpDispatchCtx): void
+}
+
+/** Aggregate loader state shared by the dispatch core (index.ts): the resolved
+ * options, per-op dispatch contexts, the LRU cache + tick coalescer, memoized
+ * op fns, and the reusable zero-alloc pack/out/key scratch buffers. */
+export interface LoaderState {
+  options: Required<
+    Pick<
+      LoaderOptions,
+      'adaptive' | 'batchMin' | 'maxCacheKeys' | 'caching' | 'sampleEvery' | 'loadStrategy'
+    >
+  >
+  ctxs: Map<LoaderOpName, OpDispatchCtx>
+  cache: LoaderCache
+  coalescer: TickCoalescer
+  opFns: Map<LoaderOpName, OpFnEntry>
+  flushes: number
+  /** Reusable packed-input scratch for the zero-alloc fast flush (grows). */
+  packScratch: Uint8Array
+  /** Reusable packed-output buffer for the zero-alloc fast flush (grows). */
+  outScratch: Uint8Array
+  /** Reusable packed-key output buffer for the batched default-key flush. */
+  keyScratch: Uint8Array
+}
+
+/** NUL separator used to join composite cache keys (never appears in keys). */
+export const KEY_SEP = '\u0000'

package/src/loader/types.ts

@@ -0,0 +1,145 @@
+// src/loader/types.ts — public loader type surface (pure types).
+//
+// The callable loader contract (`Loader`), its option/stats shapes, the
+// specialized op-function type (`LoaderOpFn`), and the `load()` helpers.
+// No runtime code — erased at compile time.
+
+import type { SchemaValidator } from '../shared/packed'
+import type { LoaderBulk, LoaderBulkArgs, LoaderOpArgs, LoaderOpName, LoaderScalar } from './ops'
+
+// ── Public types ────────────────────────────────────────────────────────────
+
+/** Options for `createLoader()` / `loader.configure()`. */
+export interface LoaderOptions {
+  /** Let each op adapt `batchMin` from measured dispatch cost. Default true. */
+  adaptive?: boolean
+  /** Initial batch threshold in [2, 8]. Default 2 (batch wins for n >= 2). */
+  batchMin?: number
+  /** Max cached keys (bounded LRU). 0 disables caching. Default 256. */
+  maxCacheKeys?: number
+  /** Default `cache` behavior for `load()`. Default true. */
+  caching?: boolean
+  /** Sample timing every N dispatches (hot-path cost control). Default 32. */
+  sampleEvery?: number
+  /**
+   * `load()` dispatch strategy. `"auto"` (default) switches each op between
+   * `"single"` (low load → direct scalar call, no coalescer) and
+   * `"coalesce"` (rising load → one packed batch call) from observed load.
+   */
+  loadStrategy?: LoadStrategy
+}
+
+/** Options for `load()` / `opFn.load()`. */
+export interface LoadOptions {
+  /**
+   * Explicit cache key. When omitted (and caching is on) the default key is
+   * `fnv1a64(input)` — which costs one extra native call per load.
+   */
+  key?: string
+  /** Override the loader-wide caching toggle for this call. Default true. */
+  cache?: boolean
+}
+
+/** Per-op counters exposed on `opFn.stats`. */
+export interface LoaderOpStats {
+  scalarCalls: number
+  batchCalls: number
+  itemsDispatched: number
+  cachedHits: number
+  /** Current learned batch threshold for this op. */
+  batchMin: number
+  /** Current `load()` strategy: "single" (low load) or "coalesce" (bulk). */
+  mode: 'single' | 'coalesce'
+}
+
+/** Aggregate loader statistics. */
+export interface LoaderStats {
+  scalarCalls: number
+  batchCalls: number
+  itemsDispatched: number
+  flushes: number
+  cachedHits: number
+  cacheSize: number
+  cacheEvictions: number
+}
+
+/** A specialized, pre-bound op function returned by `loader(op)`. */
+export interface LoaderOpFn<K extends LoaderOpName> {
+  /** Single item → scalar result. */
+  (input: Uint8Array, ...rest: LoaderOpArgs[K]): LoaderScalar<K>
+  /** Bulk items → ONE packed batch call; same shape as `rust.batch.<op>`. */
+  (inputs: Uint8Array[], ...rest: LoaderBulkArgs<K>): LoaderBulk<K>
+  readonly name: K
+  readonly stats: LoaderOpStats
+  clear(): void
+  /** Sync cache peek (default key `fnv1a64(input)` unless `key` given). */
+  cache(input: Uint8Array, key?: string): LoaderScalar<K> | undefined
+  /**
+   * Coalesced, cache-aware load. Unavailable (`undefined`) on ops that require
+   * extra arguments (e.g. `hmacSha256`, `signCookie`) — use `run` for those.
+   */
+  load: K extends LoadableName ? LoaderLoadFn<K> : undefined
+}
+
+type LoaderLoadFn<K extends LoaderOpName> = (
+  input: Uint8Array,
+  opts?: LoadOptions,
+) => Promise<LoaderScalar<K>>
+
+/** Ops whose extra args are all optional/empty → they support `load()`. */
+export type LoadableName = {
+  [K in LoaderOpName]: LoaderOpArgs[K] extends
+    | []
+    | [unknown?]
+    | [unknown?, unknown?]
+    | [unknown?, unknown?, unknown?]
+    ? K
+    : never
+}[LoaderOpName]
+
+/** A validator-bound helper returned by `loader.schema(validator)`. */
+export interface LoaderSchemaFn {
+  /** Single JSON document → valid? */
+  (input: Uint8Array): boolean
+  /** Bulk JSON documents → bitset (1 per doc). */
+  (inputs: Uint8Array[]): Uint8Array
+  /** Count how many bulk documents are valid. */
+  count(inputs: Uint8Array[]): number
+}
+
+/** The global callable loader. */
+export interface Loader {
+  /** Higher-order function: `loader(op)` → specialized hot op function. */
+  <K extends LoaderOpName>(op: K): LoaderOpFn<K>
+  /** Single-item dispatch. */
+  run<K extends LoaderOpName>(op: K, input: Uint8Array, ...rest: LoaderOpArgs[K]): LoaderScalar<K>
+  /** Bulk dispatch (one packed batch call, or adaptive scalar loop). */
+  run<K extends LoaderOpName>(
+    op: K,
+    inputs: Uint8Array[],
+    ...rest: LoaderBulkArgs<K>
+  ): LoaderBulk<K>
+  /** Coalesced, cache-aware load (ops with required extra args throw). */
+  load<K extends LoadableName>(
+    op: K,
+    input: Uint8Array,
+    opts?: LoadOptions,
+  ): Promise<LoaderScalar<K>>
+  /** Sync cache peek. */
+  cache<K extends LoaderOpName>(op: K, input: Uint8Array, key?: string): LoaderScalar<K> | undefined
+  /**
+   * Bind a `SchemaValidator` for repeated single/bulk JSON-schema validation
+   * plus a whole-batch `count`. The returned callable uses the loader's normal
+   * dispatch machinery (cost model + counters).
+   */
+  schema(validator: SchemaValidator): LoaderSchemaFn
+  /** Clear the shared cache (pending coalesced loads still flush). */
+  clear(): void
+  /** Update options at runtime. */
+  configure(options: LoaderOptions): void
+  readonly stats: LoaderStats
+  readonly opNames: LoaderOpName[]
+}
+
+/** Load-dispatch strategy selector for `load()`. */
+export type LoadStrategy = 'auto' | 'single' | 'coalesce'

package/src/native/ffi/constants.ts

@@ -0,0 +1,58 @@
+// src/native/ffi/constants.ts — caps / sizing heuristics / self-test
+// vectors for the bun:ffi transport (pure data, no logic).
+//
+// The caps mirror the Rust napi layer (decompression-bomb guard, JSON-patch
+// output bound). The sizing heuristics are ALLOCATION caps only — `growExact`
+// in the core covers any residual miss with one exact-size retry, so a guess
+// that is too small costs one extra native pass, never a wrong result.
+
+// ── Caps mirrored from the Rust napi layer ────────────────────────
+/** rust/payload/compress.rs DEFAULT_MAX_DECOMPRESSED (64 MiB decompression-bomb
+ * guard — must stay in sync; do not raise without benchmarking). */
+export const MAX_DECOMPRESSED = 64 * 1024 * 1024
+/** rust/json/json_patch_ops.rs MAX_JSON_PATCH_OUTPUT (128 MiB). */
+export const MAX_JSON_PATCH_OUTPUT = 128 * 1024 * 1024
+
+// ── Output-buffer sizing heuristics (measured) ─────────────────────
+// These are ALLOCATION caps only, not correctness bounds: `growExact` covers
+// any residual miss with at most one exact-size retry (no re-run loop), so a
+// guess that is too small costs one extra native pass, never a wrong result.
+//
+// Compress: a 75 KiB input compresses to <1 KiB, so a 16 KiB initial is
+// plenty and single-pass; the 1 MiB ceiling bounds incompressible data.
+/** gzip/brotli compress: initial output-buffer size (bytes). */
+export const COMPRESS_INITIAL_CAP = 16 * 1024
+/** gzip/brotli compress: ceiling that bounds incompressible input (bytes). */
+export const COMPRESS_MAX_CAP = 1024 * 1024
+/** gzip/brotli compress: small-input slack added above `data.length` (bytes). */
+export const COMPRESS_HEADROOM = 64
+// Decompress (no trailer / expensive trailer): typical JSON/text ratios.
+/** gzip decompress: output-size guess multiplier over the input length. */
+export const DECOMPRESS_GUESS_MULTIPLIER_GZIP = 16
+/** brotli decompress: output-size guess multiplier over the input length. */
+export const DECOMPRESS_GUESS_MULTIPLIER_BROTLI = 32
+/** decompress: 4 MiB over-alloc bound used as a last-resort initial size. */
+export const DECOMPRESS_FALLBACK_CAP = 4 * 1024 * 1024
+/** decompress: minimum initial output size (bytes). */
+export const DECOMPRESS_MIN_INITIAL = 1024
+// JWT: token ≈ header(~36) + payload(≈4/3× claims) + sig(~43) + 2 dots. The
+// old `claims.length + 128` under-sized a typical token (measured 168 B for a
+// 30 B claim → grow-retry double-run, making ffi slower than napi). 2×+128
+// with a 256-byte floor covers typical claims in one pass.
+/** jwt sign: claims-length multiplier for the initial output-size guess. */
+export const JWT_INITIAL_MULTIPLIER = 2
+/** jwt sign: fixed byte slack added to the claims-length guess. */
+export const JWT_INITIAL_EXTRA = 128
+/** jwt sign: minimum initial output size (bytes). */
+export const JWT_INITIAL_FLOOR = 256
+
+// ── Known-good vectors for the bind-time self-test ───────────────
+// These mirror the Rust `#[cfg(test)]` vectors in rust/ffi.rs.
+/** Self-test vector: ASCII "hello" (hex-encodes to `68656c6c6f`). */
+export const SELFTEST_HEX = new Uint8Array([0x68, 0x65, 0x6c, 0x6c, 0x6f]) // "hello" -> 68656c6c6f
+/** Self-test vector: JSON `{"a":1}` (validates via the packed JSON ops). */
+export const SELFTEST_JSON = new Uint8Array([0x7b, 0x22, 0x61, 0x22, 0x3a, 0x31, 0x7d]) // "{\"a\":1}"
+
+/** Empty view for `null` body slots in (ptr, len) pairs — the C side treats
+ * len 0 as "no body" regardless of the pointer value. */
+export const EMPTY_VIEW = new Uint8Array(0)