castrum 0.7.0 → 0.9.0

package/src/rust-ffi/text.ts

@@ -0,0 +1,95 @@
+// src/rust-ffi/text.ts — String-oriented FFI namespace (text in → text out).
+//
+// `rust.text.*` is the ergonomic string API over the byte-level native
+// functions. Pure wrappers: encode input, call native, decode output.
+
+import { decoder, encoder } from '../shared/bytes'
+import { isBun } from '../shared/runtime'
+import { resolveNative, type RustClientContext } from './context'
+
+/** String-oriented FFI namespace. */
+export interface RustText {
+  /**
+   * Resolve a lowercase file extension to a MIME type string (e.g. `"html"` →
+   * `"text/html"`). Unknown extensions return `"application/octet-stream"`.
+   * @param ext the file extension WITHOUT a leading dot, case-insensitive.
+   * @returns the MIME type for `ext`.
+   */
+  mimeFromExtension(ext: string): string
+  /**
+   * RFC 3986 percent-encode a string (the `encodeURIComponent` unreserved
+   * set). Under Bun this delegates to the native `encodeURIComponent` for
+   * ~4x speed with byte-for-byte parity.
+   * @param input the string to encode.
+   * @returns the percent-encoded string.
+   */
+  urlEncode(input: string): string
+  /**
+   * Percent-decode a string. Throws on malformed `%XX` or invalid UTF-8
+   * output (parity with `decodeURIComponent`, which is used under Bun).
+   * @param input the percent-encoded string to decode.
+   * @returns the decoded string.
+   */
+  urlDecode(input: string): string
+  /**
+   * Compute the RFC 6455 `Sec-WebSocket-Accept` value for a client key.
+   * @param key the base64 `Sec-WebSocket-Key` header value.
+   * @returns the 28-byte base64 accept value.
+   */
+  wsAcceptKey(key: string): string
+  /** @param input an email address. @returns whether it is RFC-valid. */
+  validateEmail(input: string): boolean
+  /** @param input a UUID string. @returns whether it is a valid (v1-v8) UUID. */
+  validateUuid(input: string): boolean
+  /** @param input an IPv4 address. @returns whether it is valid. */
+  validateIpv4(input: string): boolean
+  /** @param input an IPv6 address. @returns whether it is valid. */
+  validateIpv6(input: string): boolean
+}
+
+/** Build the `text` namespace for a client context. */
+export function buildText(ctx: RustClientContext): RustText {
+  // String memo: the byte path already caches the native bytes; this avoids the
+  // encode → native lookup → slice → decode round-trip for repeated extension
+  // strings (the common case) — 0 allocations on a cache hit.
+  const mimeStrCache = new Map<string, string>()
+
+  return {
+    mimeFromExtension(ext) {
+      let mime = mimeStrCache.get(ext)
+      if (mime === undefined) {
+        mime = decoder.decode(ctx.cachedMime(encoder.encode(ext)))
+        mimeStrCache.set(ext, mime)
+      }
+      return mime
+    },
+    urlEncode(input) {
+      // Bun's native encodeURIComponent beats the rust+FFI/NAPI string crossing
+      // (~4x, measured) with byte-for-byte parity (RFC 3986 unreserved set) —
+      // see docs/bun-builtins-decision-matrix.md.
+      if (isBun()) return encodeURIComponent(input)
+      return resolveNative(ctx, 'urlEncodeStr')(input) as string
+    },
+    urlDecode(input) {
+      // decodeURIComponent matches the rust decoder on valid input and also
+      // throws on malformed/invalid UTF-8 (URIError, an Error subclass).
+      if (isBun()) return decodeURIComponent(input)
+      return resolveNative(ctx, 'urlDecodeStr')(input) as string
+    },
+    wsAcceptKey(key) {
+      return decoder.decode(resolveNative(ctx, 'wsAcceptKey')(encoder.encode(key)) as Uint8Array)
+    },
+    validateEmail(input) {
+      return resolveNative(ctx, 'validateEmail')(encoder.encode(input)) as boolean
+    },
+    validateUuid(input) {
+      return resolveNative(ctx, 'validateUuid')(encoder.encode(input)) as boolean
+    },
+    validateIpv4(input) {
+      return resolveNative(ctx, 'validateIpv4')(encoder.encode(input)) as boolean
+    },
+    validateIpv6(input) {
+      return resolveNative(ctx, 'validateIpv6')(encoder.encode(input)) as boolean
+    },
+  }
+}

package/src/selection.json

@@ -0,0 +1,194 @@
+{
+  "generatedAt": "2026-08-13T09:13:26.107Z",
+  "note": "Auto-selected by `bun scripts/select-native.ts --write` from measurements of the castrum addon vs representative pure-TS implementations. Do NOT hand-edit — regenerate with the benchmark script. The public API reads this via `opImpl(op)` and binds each op to a fixed impl (native or js) at load time.",
+  "ops": {
+    "fnv1a64": {
+      "impl": "native",
+      "nativeRatio": 12.603
+    },
+    "crc32": {
+      "impl": "js",
+      "nativeRatio": 0.659
+    },
+    "hmacSha256": {
+      "impl": "native",
+      "nativeRatio": 1.212
+    },
+    "hmacSha256Verify": {
+      "impl": "native",
+      "nativeRatio": 9.028
+    },
+    "signCookie": {
+      "impl": "native",
+      "nativeRatio": 3.64
+    },
+    "verifyCookie": {
+      "impl": "native",
+      "nativeRatio": 1.772
+    },
+    "csrfToken": {
+      "impl": "native",
+      "nativeRatio": 12.671
+    },
+    "csrfVerify": {
+      "impl": "native",
+      "nativeRatio": 12.458
+    },
+    "randomToken": {
+      "impl": "native",
+      "nativeRatio": 9.546
+    },
+    "passwordHash": {
+      "impl": "native",
+      "nativeRatio": 1.657
+    },
+    "aeadEncrypt": {
+      "impl": "native",
+      "nativeRatio": 1.288
+    },
+    "aeadDecrypt": {
+      "impl": "native",
+      "nativeRatio": 1.108
+    },
+    "queryPairs": {
+      "impl": "js",
+      "nativeRatio": 0.279
+    },
+    "cookiePairs": {
+      "impl": "js",
+      "nativeRatio": 0.105
+    },
+    "formPairs": {
+      "impl": "js",
+      "nativeRatio": 0.328
+    },
+    "etag": {
+      "impl": "js",
+      "nativeRatio": 0.187
+    },
+    "parseMediaType": {
+      "impl": "js",
+      "nativeRatio": 0.378
+    },
+    "parseAcceptEncoding": {
+      "impl": "js",
+      "nativeRatio": 0.367
+    },
+    "createConditionalRequest": {
+      "impl": "js",
+      "nativeRatio": 0.275
+    },
+    "createAcceptNegotiator": {
+      "impl": "native",
+      "nativeRatio": 2.01
+    },
+    "multipartParse": {
+      "impl": "js",
+      "nativeRatio": null
+    },
+    "jsonValid": {
+      "impl": "js",
+      "nativeRatio": 0.749
+    },
+    "jsonPatch": {
+      "impl": "js",
+      "nativeRatio": 0.014
+    },
+    "gzipCompress": {
+      "impl": "native",
+      "nativeRatio": 22.132
+    },
+    "gzipDecompress": {
+      "impl": "native",
+      "nativeRatio": 61.039
+    },
+    "brotliCompress": {
+      "impl": "native",
+      "nativeRatio": 9.983
+    },
+    "brotliDecompress": {
+      "impl": "native",
+      "nativeRatio": 33.327
+    },
+    "sseEncode": {
+      "impl": "js",
+      "nativeRatio": 0.586
+    },
+    "wsFrameEncode": {
+      "impl": "js",
+      "nativeRatio": 0.152
+    },
+    "wsFrameDecode": {
+      "impl": "js",
+      "nativeRatio": 0.988
+    },
+    "wsAcceptKey": {
+      "impl": "js",
+      "nativeRatio": 0.939
+    },
+    "validateEmail": {
+      "impl": "js",
+      "nativeRatio": 0.007
+    },
+    "validateUuid": {
+      "impl": "js",
+      "nativeRatio": 0.008
+    },
+    "validateIpv4": {
+      "impl": "js",
+      "nativeRatio": 0.012
+    },
+    "validateIpv6": {
+      "impl": "js",
+      "nativeRatio": 0.078
+    },
+    "createRateLimiter": {
+      "impl": "js",
+      "nativeRatio": 0.061
+    },
+    "renderTemplate": {
+      "impl": "js",
+      "nativeRatio": 0.141
+    },
+    "xxh3": {
+      "impl": "native",
+      "nativeRatio": null
+    },
+    "urlEncode": {
+      "impl": "js",
+      "nativeRatio": 0.214
+    },
+    "urlDecode": {
+      "impl": "js",
+      "nativeRatio": 0.092
+    },
+    "base64Encode": {
+      "impl": "js",
+      "nativeRatio": 0.376
+    },
+    "httpDate": {
+      "impl": "js",
+      "nativeRatio": 0.401
+    },
+    "jwtSign": {
+      "impl": "native",
+      "nativeRatio": null
+    },
+    "jwtVerify": {
+      "impl": "native",
+      "nativeRatio": null
+    },
+    "passwordVerify": {
+      "impl": "native",
+      "nativeRatio": null
+    },
+    "createTemplate": {
+      "impl": "native",
+      "nativeRatio": null
+    },
+    "createSchemaValidator": {
+      "impl": "native",
+      "nativeRatio": null
+    }
+  }
+}

package/src/selection.ts

@@ -0,0 +1,77 @@
+// src/selection.ts — native-vs-JS selection surface (OWNED BY CASTRUM).
+//
+// The decision of whether an operation should use the Rust addon ("native")
+// or a pure-JS implementation ("js") is a property of this library, not of
+// any consumer. The single source of truth is `rust/selection.rs`
+// (benchmark-driven, audited by `scripts/select-native.ts --check`); this
+// module is its TS projection and the API consumers call ONCE at load time.
+//
+// Consumers bind each operation to a fixed implementation at startup by
+// reading `opImpl(op)` here — they do NOT swap native↔js per call.
+
+import { lazyAddon, getAddon } from './native'
+import { isBun } from './shared/runtime'
+
+/** Recommended implementation for an operation. */
+export type OpImpl = 'native' | 'js'
+
+export interface OpDecision {
+  /** The recommended implementation when the addon is available. */
+  readonly impl: OpImpl
+  /** Why this decision (measured ratio / rationale). */
+  readonly note?: string
+}
+
+/**
+ * Ops where Bun's NATIVE built-in beats the Rust addon (measured in
+ * `docs/bun-builtins-decision-matrix.md`: `Bun.gzipSync` ~2.0x, `Bun.hash.crc32`
+ * 2.8–8.4x, `Bun.CryptoHasher` ~1.2x, `Bun.hash.xxHash3` ~4.2x, and
+ * `crypto.getRandomValues` for token-sized random). Under Bun the fastest
+ * choice for these is the pure-JS path that DELEGATES to the Bun built-in
+ * (`"js"`), not the Rust addon — so we never ship something slower than what
+ * Bun natively provides. Under Node the base benchmark decision stands (Rust
+ * wins for gzip/random/hmac there).
+ *
+ * NOTE: `gzipDecompress` is deliberately NOT in this set — the rust surface
+ * keeps the native path (with its 64 MiB decompression-bomb cap) even under
+ * Bun, because `Bun.gunzipSync` has no output-size bound.
+ */
+const BUN_WINS = new Set([
+  'gzipCompress',
+  'crc32',
+  'randomToken',
+  'hmacSha256',
+  'xxh3',
+  'urlEncode',
+  'urlDecode',
+  'base64Encode',
+  'httpDate',
+])
+
+// Lazy: importing this module does NOT dlopen the addon; `opImpl` reads the
+// baked decision from Rust on first call.
+const addon = lazyAddon(getAddon)
+
+/**
+ * The benchmark-driven native-vs-JS decision for `op` — runtime-aware.
+ *
+ * Returns `"native"` when the Rust addon is the recommended implementation,
+ * `"js"` when a pure-JS (or Bun built-in) implementation wins, or `null` for
+ * unknown ops (or when the addon is unavailable — with no addon there is no
+ * "native" choice). Under Bun, ops in {@link BUN_WINS} resolve to `"js"` so the
+ * consumer's JS path delegates to the faster Bun built-in.
+ */
+export const opImpl = (op: string): OpImpl | null => {
+  if (isBun() && BUN_WINS.has(op)) return 'js'
+  return addon.opImpl(op)
+}
+
+/** `true` when the Rust addon is the recommended impl for `op`. */
+export const isNativeOp = (op: string): boolean => opImpl(op) === 'native'
+
+/** The decision record for `op`, or `null` when unknown. */
+export const opDecision = (op: string): OpDecision | null => {
+  const impl = opImpl(op)
+  if (impl === null) return null
+  return { impl }
+}

package/src/shared/adaptive.ts

@@ -0,0 +1,68 @@
+// src/shared/adaptive.ts — Reusable EWMA adaptive-estimate utility.
+//
+// The loader's cost model (src/loader/cost.ts) learns per-op dispatch costs at
+// runtime with an exponential moving average (EWMA). This is that same
+// machinery, extracted as a tiny reusable class so OTHER subsystems can
+// self-optimize without re-implementing the math — e.g. BufferPool learns the
+// observed request size to pre-size future buffers (`adaptive` option), and
+// consumers can drive their own runtime decisions (batch-vs-loop, delegate
+// vs-native, cache-size) with a bounded, noise-smoothed estimate.
+
+export interface AdaptiveEstimateOptions {
+  /**
+   * EWMA smoothing factor in (0, 1]. Higher reacts faster to new samples;
+   * lower smooths more. Default: 0.25.
+   */
+  alpha?: number
+  /** Starting estimate. Default 0 (the first sample wins). */
+  initial?: number
+  /** Clamp the estimate to at least this. Default 0. */
+  min?: number
+  /** Clamp the estimate to at most this (bounds memory / resources). Default Infinity. */
+  max?: number
+}
+
+/**
+ * A bounded exponential-moving-average estimate of an observed quantity.
+ *
+ * `sample(x)` folds a new observation into the running estimate; `estimate`
+ * reads the current value. The estimate is clamped to `[min, max]`, so it is
+ * safe to drive resource sizing (buffer pools, batch thresholds) with it —
+ * a single outlier cannot blow up the estimate, and it decays toward recent
+ * observations.
+ */
+export class AdaptiveEstimate {
+  private readonly alpha: number
+  private readonly min: number
+  private readonly max: number
+  private readonly initial: number
+  private value: number
+
+  constructor(options: AdaptiveEstimateOptions = {}) {
+    const alpha = options.alpha ?? 0.25
+    if (!Number.isFinite(alpha) || alpha <= 0 || alpha > 1) {
+      throw new RangeError(`AdaptiveEstimate: alpha must be in (0,1], got ${alpha}`)
+    }
+    this.alpha = alpha
+    this.min = Math.max(0, options.min ?? 0)
+    this.max = options.max ?? Number.POSITIVE_INFINITY
+    this.initial = options.initial ?? 0
+    this.value = this.initial
+  }
+
+  /** Fold a new observation into the running estimate. */
+  sample(x: number): void {
+    const v = this.value === 0 ? x : this.value * (1 - this.alpha) + x * this.alpha
+    this.value = v < this.min ? this.min : v > this.max ? this.max : v
+  }
+
+  /** Current estimate (clamped to `[min, max]`). */
+  get estimate(): number {
+    return this.value
+  }
+
+  /** Reset the estimate (back to `initial`). */
+  reset(): void {
+    this.value = this.initial
+  }
+}

package/src/shared/bench-classify.ts

@@ -0,0 +1,209 @@
+/**
+ * src/shared/bench-classify.ts — Pure benchmark classification for PROVEN_SURFACE.
+ *
+ * Given the CPU report's `comparisons` array and the static PROVEN_SURFACE
+ * registry, compute per-function live classification: aggregate all of a
+ * function's benchmark tasks (the canonical comparison plus its `_`-suffixed
+ * variants that no other registry entry claims), score each task pass/fail,
+ * and derive:
+ *
+ *   - `live`       status purely from the latest report (majority-fail rule)
+ *   - `effective`  hybrid status the JSDoc annotator and the audit use:
+ *                  a clear MAJORITY of task losses overrides the static
+ *                  status and auto-deprecates the function, while a single
+ *                  good run never auto-promotes a "not-competitive" function
+ *                  (static classifications reflect the shipped release build).
+ *   - `promotable` static "not-competitive" but live majority WIN (ratio >= 1)
+ *   - `won`/`failed`/`total` — the score embedded in the generated JSDoc.
+ *
+ * Task bands: won = ratio >= 1 (rust at least as fast), failed = ratio <
+ * 1/LOSS_TOLERANCE (clear loss), middle = tie (counts toward neither).
+ *
+ * PURE DATA — imports only the registry (no addon, no `rust` client), so it is
+ * unit-testable and shared by scripts/annotate-performance.ts and
+ * scripts/check-proven.ts (one source of truth for classification).
+ */
+
+import { PROVEN_SURFACE, type PerformanceStatus, type ProvenEntry } from './proven'
+
+/** A "proven"/"parity" function whose baseline is more than this much faster is a clear loss. */
+export const LOSS_TOLERANCE = 1.35
+/** A "not-competitive" function that wins by more than this is a promotion candidate. */
+export const PROMOTE_TOLERANCE = 1.5
+
+/** One measured rust-vs-baseline comparison from the CPU report. */
+export interface Comparison {
+  label: string
+  nativeName: string
+  rustName: string
+  nativeAvgMs: number
+  rustAvgMs: number
+  ratio: number
+  faster: 'rust' | 'native'
+}
+
+/** Pass/fail outcome for one of a function's benchmark tasks. */
+export interface TaskOutcome {
+  rustName: string
+  label: string
+  ratio: number
+  /** True when rust is at least as fast (ratio >= 1) — a genuine win. */
+  won: boolean
+  /** True when rust is a CLEAR loss (ratio < 1 / LOSS_TOLERANCE) — the deprecation signal. */
+  failed: boolean
+  /** False for the registry's canonical rustTask; true for aggregated variants. */
+  isVariant: boolean
+}
+
+export interface ClassifiedEntry {
+  entry: ProvenEntry
+  tasks: TaskOutcome[]
+  total: number
+  /** Tasks where rust is at least as fast (ratio >= 1). */
+  won: number
+  /** Tasks where rust is a clear loss (ratio < 1 / LOSS_TOLERANCE). */
+  failed: number
+  /** True when a clear majority of the function's benchmarks lose (failed > total/2). */
+  majorityFail: boolean
+  /** True when a clear majority of the function's benchmarks win (won > total/2). */
+  majorityWin: boolean
+  /**
+   * Ratio to display in JSDoc: the worst task when majority-failing (honest
+   * "this loses" number), otherwise the canonical comparison, else the median.
+   */
+  ratio: number | undefined
+  /** Status derived purely from the latest report. */
+  live: PerformanceStatus
+  /** Hybrid status the annotator/audit should act on (majority-fail overrides static). */
+  effective: PerformanceStatus
+  /** Live results contradict the static classification (majority fail on a proven/parity fn). */
+  drifted: boolean
+  /** Static "not-competitive" that now majority-wins (keep deprecated, add a note). */
+  promotable: boolean
+}
+
+function median(values: number[]): number | undefined {
+  if (values.length === 0) return undefined
+  const sorted = [...values].sort((a, b) => a - b)
+  const mid = Math.floor(sorted.length / 2)
+  if (sorted.length % 2 === 1) return sorted[mid] ?? 0
+  return ((sorted[mid - 1] ?? 0) + (sorted[mid] ?? 0)) / 2
+}
+
+/** Every rustTask claimed by any registry entry (prevents cross-entry variant theft). */
+function defaultClaimed(): Set<string> {
+  return new Set(PROVEN_SURFACE.map((e) => e.rustTask).filter(Boolean))
+}
+
+/**
+ * Classify a single registry entry against the report's comparisons.
+ *
+ * `claimedRustTasks` is the set of rustTasks owned by OTHER registry entries;
+ * a variant comparison is aggregated only when no other entry claims it (e.g.
+ * `rust:jwt_sign_bytes` belongs to `jwtSignBytes`, not `jwtSign`).
+ */
+export function classifyEntry(
+  entry: ProvenEntry,
+  comparisons: Comparison[],
+  claimedRustTasks: ReadonlySet<string> = defaultClaimed(),
+): ClassifiedEntry {
+  const unmeasured: ClassifiedEntry = {
+    entry,
+    tasks: [],
+    total: 0,
+    won: 0,
+    failed: 0,
+    majorityFail: false,
+    majorityWin: false,
+    ratio: undefined,
+    live: 'unmeasured',
+    effective: 'unmeasured',
+    drifted: false,
+    promotable: false,
+  }
+  if (!entry.rustTask) return unmeasured
+
+  const tasks: TaskOutcome[] = []
+  for (const c of comparisons) {
+    const isCanonical = c.rustName === entry.rustTask
+    const isVariant =
+      !isCanonical &&
+      !claimedRustTasks.has(c.rustName) &&
+      c.rustName.startsWith(`${entry.rustTask}_`)
+    if (isCanonical || isVariant) {
+      // Three-band classification (honest, noise-resistant): a task is WON when
+      // rust is at least as fast (ratio >= 1), FAILED when rust clearly loses
+      // (ratio < 1 / LOSS_TOLERANCE), and a TIE in between. The middle band
+      // counts toward neither majority, so marginal losses can never produce a
+      // false win (e.g. a stale PROMOTABLE flag for a function that never
+      // actually beat its baseline).
+      tasks.push({
+        rustName: c.rustName,
+        label: c.label,
+        ratio: c.ratio,
+        won: c.ratio >= 1,
+        failed: c.ratio < 1 / LOSS_TOLERANCE,
+        isVariant: !isCanonical,
+      })
+    }
+  }
+
+  const total = tasks.length
+  if (total === 0) return unmeasured
+
+  const won = tasks.filter((t) => t.won).length
+  const failed = tasks.filter((t) => t.failed).length
+  const majorityFail = failed * 2 > total
+  const majorityWin = won * 2 > total
+
+  const canonical = tasks.find((t) => !t.isVariant)
+  const ratio = majorityFail
+    ? Math.min(...tasks.map((t) => t.ratio))
+    : (canonical?.ratio ?? median(tasks.map((t) => t.ratio)))
+
+  const live: PerformanceStatus = majorityFail
+    ? 'not-competitive'
+    : majorityWin
+      ? 'proven'
+      : 'parity'
+
+  // Hybrid effective status: a clear majority of losses overrides the static
+  // registry (auto-deprecate); otherwise the static classification stands —
+  // classifications reflect the shipped release build, not one local run.
+  const effective: PerformanceStatus =
+    entry.status !== 'unmeasured' && majorityFail ? 'not-competitive' : entry.status
+
+  return {
+    entry,
+    tasks,
+    total,
+    won,
+    failed,
+    majorityFail,
+    majorityWin,
+    ratio,
+    live,
+    effective,
+    drifted: entry.status !== 'unmeasured' && effective !== entry.status,
+    promotable: entry.status === 'not-competitive' && majorityWin,
+  }
+}
+
+/** Classify every registry entry (single source of truth for the audit + annotator). */
+export function classifySurface(
+  entries: readonly ProvenEntry[],
+  comparisons: Comparison[],
+): Map<string, ClassifiedEntry> {
+  const claimed = new Set(entries.map((e) => e.rustTask).filter(Boolean))
+  const out = new Map<string, ClassifiedEntry>()
+  for (const entry of entries) {
+    out.set(entry.name, classifyEntry(entry, comparisons, claimed))
+  }
+  return out
+}
+
+/** Human ratio summary: "3.18x rust" / "2.34x baseline". */
+export function formatRatio(ratio: number): string {
+  if (ratio >= 1) return `${ratio.toFixed(2)}x rust`
+  return `${(1 / ratio).toFixed(2)}x baseline`
+}