castrum 0.7.0 → 0.9.1

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)