castrum 0.7.0 → 0.9.1

package/src/loader/batch.ts

@@ -0,0 +1,137 @@
+// src/loader/batch.ts — Microtask coalescer + bounded LRU cache.
+//
+// The coalescer is the DataLoader-style engine: N `load()` calls made within
+// the same event-loop tick are grouped by op and flushed together in ONE
+// packed native batch call (reducing N native crossings → 1). The cache is a
+// bounded LRU (default key = fnv1a64 of the input) for repeated-key hot loads.
+
+/** A pending `load()` request inside a coalescing tick. */
+export interface LoadRequest {
+  input: Uint8Array
+  resolve(value: unknown): void
+  reject(err: unknown): void
+  /** Cache key (only set when caching is enabled for this request). */
+  key?: string | bigint
+  /**
+   * The default cache key should be computed lazily at flush time (coalesce
+   * mode deferral) so all keys are computed in ONE packed native crossing.
+   */
+  needsDefaultKey?: boolean
+}
+
+/** Bounded LRU cache used by the loader (Hot Function Cache). */
+export interface LoaderCache {
+  get(key: string | bigint): unknown
+  set(key: string | bigint, value: unknown): void
+  clear(): void
+  readonly size: number
+  readonly evictions: number
+  readonly hits: number
+}
+
+/** A cache that never stores anything (maxKeys <= 0). */
+const NULL_CACHE: LoaderCache = {
+  get: () => undefined,
+  set: () => {},
+  clear: () => {},
+  size: 0,
+  evictions: 0,
+  hits: 0,
+}
+
+/**
+ * Bounded LRU cache. `maxKeys <= 0` disables caching entirely.
+ * LRU order is maintained by delete+re-insert on access (Map order).
+ */
+export function createLruCache(maxKeys: number): LoaderCache {
+  if (maxKeys <= 0) return NULL_CACHE
+  const map = new Map<string | bigint, unknown>()
+  let evictions = 0
+  let hits = 0
+
+  return {
+    get(key) {
+      const value = map.get(key)
+      if (value === undefined) return undefined
+      hits++
+      map.delete(key)
+      map.set(key, value)
+      return value
+    },
+    set(key, value) {
+      if (map.has(key)) map.delete(key)
+      map.set(key, value)
+      if (map.size > maxKeys) {
+        const oldest = map.keys().next().value
+        if (oldest !== undefined) {
+          map.delete(oldest)
+          evictions++
+        }
+      }
+    },
+    clear() {
+      map.clear()
+    },
+    get size() {
+      return map.size
+    },
+    get evictions() {
+      return evictions
+    },
+    get hits() {
+      return hits
+    },
+  }
+}
+
+/**
+ * Per-tick coalescer. `enqueue` schedules a single `queueMicrotask` flush that
+ * drains ALL pending ops; the flush callback receives one group per op.
+ */
+export interface TickCoalescer {
+  enqueue(op: string, request: LoadRequest): void
+  /** Number of requests not yet flushed. */
+  readonly pending: number
+}
+
+/**
+ * Create a microtask-based coalescer: `enqueue` schedules one flush that
+ * drains ALL pending ops; each op group is delivered to `flush` once.
+ */
+export function createTickCoalescer(
+  flush: (op: string, requests: LoadRequest[]) => void,
+): TickCoalescer {
+  let buffer = new Map<string, LoadRequest[]>()
+  let scheduled = false
+  let pending = 0
+
+  function schedule() {
+    if (scheduled) return
+    scheduled = true
+    queueMicrotask(() => {
+      scheduled = false
+      const snapshot = buffer
+      buffer = new Map()
+      pending = 0
+      for (const [op, requests] of snapshot) {
+        if (requests.length > 0) flush(op, requests)
+      }
+    })
+  }
+
+  return {
+    enqueue(op, request) {
+      let list = buffer.get(op)
+      if (!list) {
+        list = []
+        buffer.set(op, list)
+      }
+      list.push(request)
+      pending++
+      schedule()
+    },
+    get pending() {
+      return pending
+    },
+  }
+}

package/src/loader/cost.ts

@@ -0,0 +1,105 @@
+// src/loader/cost.ts — Adaptive scalar-vs-batch cost model.
+//
+// Each op owns one cost model. It learns from ACTUAL dispatch timings (EWMA)
+// and decides, at runtime, whether a bulk of `n` items should go through the
+// packed batch path (ONE native crossing) or a scalar loop (`n` crossings).
+//
+//   - `n === 1` always routes to the scalar path.
+//   - `n >= batchMin` routes to the batch path.
+//   - `batchMin` starts at the configured value (default 2) and adapts in
+//     [2, 8]: if measured batch-per-item cost stays above the scalar-per-item
+//     cost, `batchMin` rises so tiny batches fall back to the scalar loop; if
+//     batching wins, `batchMin` sinks back to 2.
+//
+// Timing is sampled (every `sampleEvery` dispatches) so the hot path does NOT
+// pay a `hrtime` call on every invocation.
+
+/** A per-op adaptive cost model. */
+export interface LoaderCostModel {
+  /**
+   * Should a bulk of `n` items use the packed batch path?
+   * `false` → scalar loop (`n` crossings).
+   */
+  decide(n: number): boolean
+  /** Record a scalar-path dispatch of `n` items taking `elapsedNs`. */
+  recordScalar(n: number, elapsedNs: number): void
+  /** Record a batch-path dispatch of `n` items taking `elapsedNs`. */
+  recordBatch(n: number, elapsedNs: number): void
+  /** Current learned batch threshold. */
+  readonly batchMin: number
+  /** Snapshot for observability/tests. */
+  readonly stats: {
+    batchMin: number
+    scalarPerItemNs: number
+    batchPerItemNs: number
+    samples: number
+  }
+}
+
+const MIN_BATCH_MIN = 2
+const MAX_BATCH_MIN = 8
+const EWMA_ALPHA = 0.3
+
+function clampBatchMin(v: number): number {
+  return Math.max(MIN_BATCH_MIN, Math.min(MAX_BATCH_MIN, v))
+}
+
+/** High-resolution nanosecond clock (Bun/Node). */
+export const nowNs: () => number =
+  typeof process !== 'undefined' && typeof process.hrtime === 'function'
+    ? () => Number(process.hrtime.bigint())
+    : () => performance.now() * 1e6
+
+/** Options for `createCostModel` (adaptive batch-threshold learning). */
+export interface CostModelOptions {
+  /** Allow the model to adjust `batchMin` from measurement. Default true. */
+  adaptive?: boolean
+  /** Initial batch threshold in [2, 8]. Default 2 (batch wins for n >= 2). */
+  batchMin?: number
+}
+
+/** Build a per-op cost model. */
+export function createCostModel(options: CostModelOptions = {}): LoaderCostModel {
+  const adaptive = options.adaptive !== false
+  let batchMin = clampBatchMin(options.batchMin ?? MIN_BATCH_MIN)
+  let scalarPerItemNs = 0
+  let batchPerItemNs = 0
+  let samples = 0
+
+  function ewma(prev: number, next: number): number {
+    return prev === 0 ? next : prev * (1 - EWMA_ALPHA) + next * EWMA_ALPHA
+  }
+
+  return {
+    decide(n) {
+      if (n <= 1) return false
+      return n >= batchMin
+    },
+    recordScalar(n, elapsedNs) {
+      samples++
+      const perItem = n > 0 ? elapsedNs / n : elapsedNs
+      scalarPerItemNs = ewma(scalarPerItemNs, perItem)
+      if (adaptive && n >= 2 && batchPerItemNs > 0 && perItem < batchPerItemNs * 0.8) {
+        batchMin = clampBatchMin(batchMin + 1)
+      }
+    },
+    recordBatch(n, elapsedNs) {
+      samples++
+      const perItem = n > 0 ? elapsedNs / n : elapsedNs
+      batchPerItemNs = ewma(batchPerItemNs, perItem)
+      if (adaptive && scalarPerItemNs > 0) {
+        if (perItem > scalarPerItemNs * 1.2) {
+          batchMin = clampBatchMin(batchMin + 1)
+        } else if (perItem < scalarPerItemNs * 0.8) {
+          batchMin = clampBatchMin(batchMin - 1)
+        }
+      }
+    },
+    get batchMin() {
+      return batchMin
+    },
+    get stats() {
+      return { batchMin, scalarPerItemNs, batchPerItemNs, samples }
+    },
+  }
+}