@jarenjs/core 0.9.2 → 0.34.2

package/docs/DATES.md

@@ -0,0 +1,78 @@
+# `@jarenjs/core/dates`
+
+The calendar kernel. Two constraints shape everything in it. **There is
+no date type**: a date is an RFC 3339 *string* (lexical, interchange) or
+*epoch milliseconds* (arithmetic) — both already JSON items — never a
+wrapper object. And **there is no `now`**: the current instant enters as
+data (an app effect, an external), never as a hidden read, so everything
+here is pure and cacheable. Locale names live in `@jarenjs/locales`; the
+kernel itself is locale-free. Import the barrel (`@jarenjs/core/dates`)
+or a single module.
+
+## Lexical layer — `rfc3339.js`
+
+Validation: `isDateOnlyRFC3339`, `isTimeOnlyRFC3339`,
+`isDateTimeRFC3339` (strict RFC 3339 — an offset is required), and the
+lenient ISO twins `isValidISODateTime` / `isValidISOTime` (offset
+optional — what HTML's `datetime-local` control emits). Leap years and
+month lengths are checked, not just shape.
+
+Parsing: `parseRFC3339Parts(str)` → a flat **parts** record
+`{year, month, day, hours, minutes, seconds, offset}`. Absent fields are
+`-1` sentinels; `offset` is minutes east of UTC, `0` for `Z` and `null`
+when the string carried none. The inverse is `formatRFC3339Parts(parts)`
+(round-trips the offset). `epochOfRFC3339Parts(parts)` → epoch ms: a
+date-only reads as UTC midnight, an offset shifts to its instant, and a
+time-only has **no** instant — it returns `NaN` rather than inventing a
+day. `getDateTypeOf*` variants produce a `Date` for callers that want
+one; `isDateType` / `isDateishType` classify values.
+
+## Calendar arithmetic — `civil.js`
+
+Proleptic Gregorian math over **integer day numbers** (Howard Hinnant's
+civil-days algorithm — no `Date`, no timezone, no DST edge):
+`daysFromCivil(y, m, d)` ⇄ `civilFromDays(z)`, `weekdayFromDays` /
+`isoWeekdayFromDays`, `isLeapYear`, `daysInMonth`, `dayOfYear`,
+`quarterOfYear`, `isoWeekOfYear` (returns `{year, week}` — the ISO week
+year is not the calendar year at the edges), `partsFromEpoch(ms, offset)`.
+
+`addToParts(parts, amount, unit)`, `startOfParts`, `endOfParts` over
+`DATE_UNITS` (`year`…`millisecond`, plus `quarter` and `week`; weeks
+start Monday, per ISO). **Month math clamps**: 31 Jan + 1 month =
+28 Feb, which is what makes add and diff behave as inverses in the
+query operators built on this.
+
+## Durations — `duration.js`
+
+`parseDuration('P3DT4H')` — ISO 8601 duration decomposition into
+`{negative, years, months, weeks, days, hours, minutes, seconds}`
+(the boolean twin `isValidDuration` lives in `rfc3339.js` with the
+other format testers). The load-bearing distinction is
+`isFixedDuration(parts)`: days and smaller are a fixed millisecond span
+(`durationToMs`), while years and months are **calendar** units whose
+length depends on where they land — those go through
+`addDuration(dateParts, duration, sign)`, which applies the clamping
+month math. `monthsBetween(from, to)` is the calendar diff.
+
+## Formatting — `format.js`
+
+`compileDateFormat(pattern, names?)` compiles an
+[LDML](https://unicode.org/reports/tr35/tr35-dates.html#Date_Format_Patterns)
+pattern (`'yyyy-MM-dd HH:mm'`, quoted literals included) into a
+formatter **once**, instead of re-scanning the pattern per call — the
+same two-stage shape as every other compiler in the suite. Numeric and
+ISO tokens work bare; name tokens (`MMMM`, `EEE`, `a`) require a
+`names` provider, which is where `@jarenjs/locales` plugs in — the
+kernel ships no month names, so server-rendered output stays
+byte-stable across Node/ICU versions.
+
+## Not here
+
+`Temporal` is deliberately not a dependency (it is not in this repo's
+Node ≥ 24 baseline); the string/number representation is exactly what
+`Temporal.Instant.from()` consumes, so the kernel can delegate
+internally later without a surface change. Relative-time phrasing and
+month-name catalogs are `@jarenjs/locales`' job; `formatMinimum`/
+`formatMaximum` bound comparison lives in `@jarenjs/formats`; time
+*axes* (charts) and date *controls* (forms) consume this kernel from
+their own packages.

package/docs/FINANCE.md

@@ -0,0 +1,59 @@
+# `@jarenjs/core/finance`
+
+A first-class subpackage of finance & trading **formulas** — pure,
+zero-dependency (imports only `@jarenjs/core/math`), reusable by any
+package. The math lives here; orchestration (which variable to solve,
+input forms, display) belongs to the consumer. Import the barrel
+(`@jarenjs/core/finance`) or a single module (`@jarenjs/core/finance/tvm`).
+
+Sign convention (TVM/cash-flow): money **in** is positive, money **out**
+negative — the standard Excel / HP-12C model.
+
+## Time Value of Money — `tvm.js`
+
+`pmt`, `pv`, `fv`, `nper`, `rate`. The five obey one identity; each solves
+for its own variable. Rates are per period; `type` is 0 (ordinary
+annuity, payment at period end) or 1 (annuity-due, begin). `rate` is
+iterative (`math/solve`).
+
+## Cash flow — `cashflow.js`
+
+`npv(rate, cashflows)`, `irr(cashflows, guess?)`, `mirr(cashflows,
+financeRate, reinvestRate)`, and date-indexed `xnpv(rate, cashflows,
+dates)` / `xirr(cashflows, dates, guess?)` (dates as `Date` or ms). IRR
+uses Newton with a bisection fallback.
+
+## Amortization — `amortization.js`
+
+`amortizationSchedule(principal, rate, nper, { payment?, type? })` →
+rows of `{ period, payment, interest, principal, balance }`; the last row
+clears rounding residue to a zero balance.
+
+## Interest — `interest.js`
+
+`simpleInterest`, `compoundAmount`, `compoundInterest`,
+`nominalToEffective` (APR→APY/EAR), `effectiveToNominal`,
+`continuousCompound`.
+
+## Depreciation — `depreciation.js`
+
+`straightLine`, `decliningBalance` (factor 2 = double-declining, floored
+at salvage), `sumOfYearsDigits` — each returns per-period amounts.
+
+## Bonds — `bond.js`
+
+`bondPrice`, `bondYTM` (iterative), `macaulayDuration`,
+`modifiedDuration`, `convexity`. Basic day-count (level coupons, whole
+periods); exotic conventions are out of scope.
+
+## Technical indicators — `indicators.js`
+
+`sma`, `ema`, `wma`, `macd` (line + signal + histogram), `rsi`,
+`bollinger`, `stochastic`, `atr`, `roc`. Each returns an array **aligned**
+to the input (same length) with `null` in warm-up positions.
+`Float64Array` inputs are accepted.
+
+## Returns & risk — `returns.js`
+
+`cagr`, `holdingPeriodReturn`, `returnsOf` (price series → return series),
+`volatility` (sample stddev), `sharpe`, `maxDrawdown`.

package/docs/GEO.md

@@ -0,0 +1,114 @@
+# `@jarenjs/core/geo`
+
+The spatial kernel. **There is no geometry type**: the representation is
+GeoJSON ([RFC 7946](https://datatracker.ietf.org/doc/html/rfc7946)) —
+positions are `[longitude, latitude]` arrays, a `Polygon`'s `coordinates`
+IS an array of rings — so every value stays a plain JSON item: patchable,
+schema-checkable, addressable by pointer and path. RFC 7946 fixes the
+coordinate system to WGS 84 and removed CRS support, so there is no SRID
+table and no reprojection *in*; the one projection goes *out*, for
+drawing. Import the barrel (`@jarenjs/core/geo`) or a single module.
+
+The rule that keeps the module honest: **never measure on a projected
+coordinate.** Measurement is spherical; Mercator exists for renderers.
+
+## Robust orientation — `predicates.js`
+
+`orient2d(ax, ay, bx, by, cx, cy)` — which side of the line a→b point c
+lies on, with an **exactly correct sign** (Shewchuk's adaptive-precision
+arithmetic; a cheap filter first, the exact path only when the
+determinant is too close to zero to trust). A naive determinant returns
+the *wrong sign* on near-collinear input, which makes containment
+contradict itself. `orient2dFast` is the naive form, exported for
+callers that provably do not care. Every winding and containment answer
+in this module rests on this sign; its cost is the deliberate
+point-in-polygon loss on the benchmark page.
+
+## Distance — `distance.js`
+
+Spherical, on the IUGG mean radius (`EARTH_RADIUS` = 6 371 008.8 m). A
+Euclidean norm on raw degrees is 64% wrong over 1 km at 52°N, so the
+planar shortcut does not exist here. `haversineDistance` (<0.5%
+anywhere) is the answer; `equirectDistance` (0.02% at 430 km, 12.4%
+intercontinentally, a few multiply-adds) is the *screening* form for
+rejecting candidates before the real test. Also `initialBearing`,
+`destinationPoint`, `lineLength(positions)`. The ellipsoid is
+deliberately not modelled.
+
+## Rings — `ring.js`
+
+`isRingClosed`, `ringSignedArea` (shoelace over `orient2d` terms —
+the *sign* is the point), `ringWinding` (1 = counter-clockwise, the
+RFC 7946 exterior convention), `sphericalRingArea` (m², spherical
+excess), `pointInRing` / `pointInPolygon` (even-odd rule, boundary
+counts as inside, exact predicate per crossing).
+
+## Boxes — `bbox.js` + `index-tree.js`
+
+`bboxOfPositions`, `bboxIntersects`, `bboxContains`, `bboxUnion` —
+`[west, south, east, north]` arrays, writable straight into a
+document's `bbox` member. `createBboxIndex(boxes)` packs a **static**
+Hilbert R-tree into flat typed arrays (no per-node objects; the Hilbert
+distance is the bit-parallel transform): `search()` returns *candidate*
+indexes — box overlap is necessary, never sufficient, so a caller
+confirms each candidate with the exact test. Null entries index as
+never-matching, keeping positions aligned with the caller's array.
+Build and probe are level with Flatbush (`npm run benchmark:geo`; the
+table lives in [ARCHITECTURE](../ARCHITECTURE.md)).
+
+## GeoJSON traversal — `geojson.js`
+
+The one layer that reads the `type` discriminator; every function takes
+a bare position, a geometry, a Feature or a collection. `eachPosition`,
+`positionsOf`, `bboxOf`, `geometryOf`, `geometryArea` (exterior minus
+holes), `geometryLength`, `centroidOf` (vertex mean, not center of
+mass), `containsPosition`, `geoDistance` (between representative
+positions), `ringsClosed`. Nothing here validates — malformed input
+yields null or 0 — because judgment lives one module over.
+
+## Validity — `valid.js`, `wkt.js`, `geohash.js`
+
+The one-call judgments backing the `geoFormats` group in
+`@jarenjs/formats`:
+
+- `isValidGeoJson(value)` — structure per type, positions of 2–3
+  numbers inside WGS 84 bounds, and **every ring closed** — the
+  invariant a JSON Schema provably cannot express. The shallow twin of
+  the meta-schema artifacts in `@jarenjs/json`, which locate failures
+  and (via `$query`) also check winding.
+- `isValidWkt(text)` — strict ISO 19125 grammar: seven tags, `Z`/`M`/
+  `ZM` modifiers (unmodified accepts 2 or 3 coordinates, as PostGIS
+  does), consistent counts, closed rings, `EMPTY`, no surrounding text.
+- `isValidGeohash(hash)` — non-empty, lowercase base-32 alphabet.
+
+## Geohash — `geohash.js`
+
+`geohashEncode(lon, lat, precision)`, `geohashDecode`, `geohashBounds`,
+`geohashCellSize`, `geohashNeighbours`. A geohash is a **string**, so it
+needs no new vocabulary anywhere: proximity is a prefix test, bucketing
+is grouping on a substring, and a sorted index over the hash is a
+spatial index. Cells are not equal-area and neighbours can straddle a
+cell edge — use `geohashNeighbours` for boundary-safe proximity, and
+never as a distance.
+
+## Drawing — `mercator.js` + `simplify.js`
+
+`projectMercator(lon, lat)` → unit square, y growing southward
+(screen order); latitude clamps at `MERCATOR_MAX_LAT` (±85.051129°).
+`unprojectMercator` inverts; `fitMercator(bbox, aspect)` fits a
+geographic box into the unit square **without distorting aspect** (the
+spare room becomes margin — stretching is how maps look wrong).
+`simplifyLine` / `simplifyRing` are iterative Douglas-Peucker;
+endpoints always survive so a ring stays closed, and a ring that would
+drop below four positions is returned unsimplified rather than
+degenerate.
+
+## Not here
+
+Spatial *query operators* (`$distance`, `$within`, `$bbox-intersects`,
+`$centroid`, `$geohash`, index-screened spatial joins) live in the
+query engine of `@jarenjs/json` (QUERY-FORMAT §8.14); the GeoJSON
+meta-schema artifacts live in `@jarenjs/json/schemas`; the map chart
+and its bounded-memory streaming accumulator live in `@jarenjs/charts`.
+Overlay operations (union/intersection/buffer) are deliberately absent
+— see the ROADMAP.

package/docs/MATH.md

@@ -0,0 +1,75 @@
+# `@jarenjs/core/math`
+
+Zero-dependency numeric primitives. Static methods on `Float64`/`Int32`/
+`Vec2f64`/`Vec3f64`, free `mathf64_*`/`mathi32_*` aliases and constants,
+plus the newer subpath modules below. Import the barrel
+(`@jarenjs/core/math`) or a single module (`@jarenjs/core/math/word`).
+
+## Transcendental completeness — `float64.js`
+
+Constants `mathf64_E`, `mathf64_LN2`, `mathf64_LN10`, `mathf64_PHI`.
+Free aliases `mathf64_log`, `mathf64_log2`, `mathf64_log10`, `mathf64_exp`,
+`mathf64_expm1`, `mathf64_tan`, `mathf64_acos`, `mathf64_atan`,
+`mathf64_sinh`, `mathf64_cosh`, `mathf64_tanh`, `mathf64_cbrt`,
+`mathf64_hypot`, `mathf64_sign`.
+
+Statics on `Float64`: `factorial(n)` (exact for integers, `gamma(n+1)`
+otherwise), `gamma(x)` (Lanczos, whole real line), `hypot(...args)`,
+`roundTo(value, digits)` (decimal places),
+`roundToPrecision(value, digits)` (significant figures — the numeric
+value of `toPrecision`, without its exponential string formatting),
+`nthroot(x, n)` (odd roots of negatives), `sign(x)`,
+`logBase(base, x)`, `cosHp(r)` (a high-precision polynomial cosine).
+
+### Range remapping — `remap`
+
+The free export `remap(v, smin, smax, dmin, dmax)` is the one linear remap of
+`v` from `[smin, smax]` to `[dmin, dmax]`: `dmin + t·(dmax - dmin)` with
+`t = (v - smin)/(smax - smin)`. A degenerate source range (`smax === smin`)
+collapses to `dmin` instead of dividing by zero, so a constant-valued axis still
+maps to a drawable coordinate, and an inverted destination range works, which is
+what screen-space y-flips need. Use it for any value/screen interpolation.
+
+`Float64.norm(value, min, max)` is the bare normalization to `[0, 1]` that
+`remap` performs internally; reach for it when you want the fraction itself
+rather than a mapped coordinate.
+
+## Word math — `word.js`
+
+BigInt fixed-width integers for programmer-calculator mode. `toWord(value,
+bits, signed)` masks and sign-extends into an 8/16/32/64-bit word;
+`wAnd/wOr/wXor/wNot/wShl/wShr/wRol/wRor/wMod` operate at a width;
+`toBase(int, radix, {group, sep, pad, upper})` and `fromBase(str, radix)`
+(prefix-aware: `0x`/`0o`/`0b`) are the radix string I/O.
+
+## Root finders — `solve.js`
+
+Domain-free `newtonRaphson(f, df, x0, opts)`, `bisect(f, a, b, opts)`,
+`secant(f, x0, x1, opts)`. Each returns `{ root, iterations, converged }`
+and never throws on non-convergence. `@jarenjs/core/finance` builds
+`irr`/`rate` on top.
+
+## 3D kernel — `mat4.js` + `project.js`
+
+`Mat4` (column-major `Float64Array(16)`): `identity`, `multiply`,
+`rotationX/Y/Z`, `translation`, `scaling`, `ortho`, `perspective`,
+`transformPoint`. `project3dTo2d(point3, mat, viewport)` maps a point to
+SVG pixels (Y flipped); `surfaceNormal(a, b, c)` returns the face normal
+as a `Vec3f64`. Reusable for any 3D projection (the x·y·z plotter is the
+first consumer; Mermaid 3D is a candidate — see ROADMAP).
+
+## Number formatting — `format.js`
+
+`formatNumber(value, { notation:'auto'|'fixed'|'sci'|'eng', precision,
+group, radix, decimal })` and radix-aware `parseNumber(str, { radix })`
+(recognizes `0x`/`0o`/`0b` prefixes, grouping separators and scientific
+notation; returns `NaN` on failure). Radix I/O delegates to `word.js`.
+
+> **`notation: 'auto'` is not a drop-in for a fixed-unit readout.** The auto
+> branch escapes to exponential once `abs(value) >= 1e21` or
+> `abs(value) < 1e-6`, so `formatNumber(v, { precision: 3 })` is *not*
+> interchangeable with `Float64.roundToPrecision(v, 3)`. A caller that
+> appends its own unit — `"0.0509 ms"` — wants the value never to become
+> `5.09e-5`, and must either pass `notation: 'fixed'` or round to
+> significant figures itself. The website's timing helpers and the chart
+> tick labels take the second route, via `roundToPrecision`.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/core",
   "private": false,
-  "version": "0.9.2",
+  "version": "0.34.2",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -9,6 +9,7 @@
   "files": [
     "src/",
     "dist/types/",
+    "docs/",
     "ARCHITECTURE.md"
   ],
   "description": "Jaren Core Functions",
@@ -20,7 +21,7 @@
   },
   "license": "MIT",
   "engines": {
-    "node": ">=22"
+    "node": ">=24"
   },
   "publishConfig": {
     "access": "public",
@@ -43,14 +44,42 @@
       "types": "./dist/types/bigint.d.ts",
       "default": "./src/bigint.js"
     },
+    "./cache": {
+      "types": "./dist/types/cache.d.ts",
+      "default": "./src/cache.js"
+    },
+    "./chunk": {
+      "types": "./dist/types/chunk.d.ts",
+      "default": "./src/chunk.js"
+    },
+    "./color": {
+      "types": "./dist/types/color.d.ts",
+      "default": "./src/color.js"
+    },
     "./dates": {
-      "types": "./dist/types/dates.d.ts",
-      "default": "./src/dates.js"
+      "types": "./dist/types/dates/index.d.ts",
+      "default": "./src/dates/index.js"
+    },
+    "./errors": {
+      "types": "./dist/types/errors.d.ts",
+      "default": "./src/errors.js"
+    },
+    "./dates/*": {
+      "types": "./dist/types/dates/*.d.ts",
+      "default": "./src/dates/*.js"
     },
     "./float": {
       "types": "./dist/types/float.d.ts",
       "default": "./src/float.js"
     },
+    "./geo": {
+      "types": "./dist/types/geo/index.d.ts",
+      "default": "./src/geo/index.js"
+    },
+    "./geo/*": {
+      "types": "./dist/types/geo/*.d.ts",
+      "default": "./src/geo/*.js"
+    },
     "./function": {
       "types": "./dist/types/function.d.ts",
       "default": "./src/function.js"
@@ -59,6 +88,10 @@
       "types": "./dist/types/integer.d.ts",
       "default": "./src/integer.js"
     },
+    "./message": {
+      "types": "./dist/types/message.d.ts",
+      "default": "./src/message.js"
+    },
     "./number": {
       "types": "./dist/types/number.d.ts",
       "default": "./src/number.js"
@@ -71,6 +104,10 @@
       "types": "./dist/types/scan.d.ts",
       "default": "./src/scan.js"
     },
+    "./schema": {
+      "types": "./dist/types/schema.d.ts",
+      "default": "./src/schema.js"
+    },
     "./string": {
       "types": "./dist/types/string.d.ts",
       "default": "./src/string.js"
@@ -91,6 +128,22 @@
       "types": "./dist/types/math/*.d.ts",
       "default": "./src/math/*.js"
     },
+    "./finance": {
+      "types": "./dist/types/finance/index.d.ts",
+      "default": "./src/finance/index.js"
+    },
+    "./finance/*": {
+      "types": "./dist/types/finance/*.d.ts",
+      "default": "./src/finance/*.js"
+    },
+    "./convert": {
+      "types": "./dist/types/convert/index.d.ts",
+      "default": "./src/convert/index.js"
+    },
+    "./convert/*": {
+      "types": "./dist/types/convert/*.d.ts",
+      "default": "./src/convert/*.js"
+    },
     "./package.json": "./package.json"
   },
   "scripts": {

package/src/array.js

@@ -55,3 +55,19 @@ export function isUniqueArray(arr) {
 export function includesAll(arr, values) {
   return values.every(v => arr.includes(v));
 }
+
+/**
+ * The value when it is one of `allowed`, otherwise `fallback`. The point
+ * is untrusted input: a value restored from storage, a share link or a
+ * stale state slice can be anything, and a UI that switches on it directly
+ * renders nothing at all for a name it does not know. Narrowing to a known
+ * set turns that blank into the fallback.
+ * @template T
+ * @param {unknown} value - The candidate, from anywhere.
+ * @param {readonly T[]} allowed - The values that may pass through.
+ * @param {T} fallback - Used when `value` is not one of `allowed`.
+ * @returns {T}
+ */
+export function pickAllowed(value, allowed, fallback) {
+  return allowed.includes(/** @type {T} */ (value)) ? /** @type {T} */ (value) : fallback;
+}

package/src/cache.js

@@ -0,0 +1,206 @@
+//@ts-check
+/**
+ * @file The suite's one bounded-cache primitive. Before this file the
+ * FIFO-512 delete-oldest map was written five times (the query engine's
+ * string cache, the JSONPath query cache, forms' three pointer caches)
+ * with a sixth divergent flush-all variant in forms' regex cache and a
+ * true LRU in the view projection memo. One implementation, one policy:
+ *
+ *  - **LRU with recency refresh**: a `get` hit re-inserts the entry, so
+ *    the evicted entry is the least recently USED, not the oldest
+ *    inserted. (FIFO versus LRU was never result-observable at any call
+ *    site — both bound memory; LRU keeps hot entries hotter.)
+ *  - **Evict at `size >= limit` before inserting a new key**, so the
+ *    cache never holds more than `limit` entries. (The old sites
+ *    disagreed between `>=`-before and `>`-after; the capacity is the
+ *    same, the invariant here is simply "never above `limit`".)
+ *  - `undefined` is the miss sentinel: a cache MUST NOT store
+ *    `undefined` as a value (store `null` for "computed, negative" —
+ *    the regex cache does exactly that).
+ *
+ * The identity axis is {@link createWeakCache}: reference-keyed,
+ * unbounded by design because a WeakMap is bounded by its keys'
+ * lifetimes — an entry dies with its key. Compose the two for
+ * "per-registry bounded caches" (a WeakMap of bounded caches).
+ *
+ * The VALUE axis is {@link createSemanticCache}: keyed by what a
+ * plain-data value IS rather than by a fingerprint of it, for the caches
+ * whose entries carry meaning (a compiled query, a query plan, a
+ * registered function body) and where serving the wrong entry is wrong
+ * data rather than a slow repaint.
+ */
+
+import { semanticKey } from './object.js';
+
+/**
+ * @template K, V
+ * @typedef {object} BoundedCache
+ * @property {(key: K) => V | undefined} get - Lookup; a hit refreshes
+ *   recency. `undefined` means miss.
+ * @property {(key: K, value: V) => void} set - Insert or refresh; evicts
+ *   the least recently used entry when the cache is full.
+ * @property {(key: K, create: (key: K) => V) => V} getOrCreate - Lookup
+ *   or compute-and-insert in one step.
+ * @property {() => void} clear - Drop every entry.
+ * @property {() => number} size - Current entry count.
+ */
+
+/**
+ * A bounded, string-or-value-keyed LRU cache.
+ * @template K, V
+ * @param {number} limit - Maximum number of retained entries (> 0)
+ * @returns {BoundedCache<K, V>}
+ */
+export function createBoundedCache(limit) {
+  /** @type {Map<K, V>} */
+  const map = new Map();
+
+  /** @type {BoundedCache<K, V>['get']} */
+  function get(key) {
+    const value = map.get(key);
+    if (value !== undefined) {
+      // Refresh recency: Map iteration order is insertion order, so
+      // delete + set moves the entry to the back of the eviction queue.
+      map.delete(key);
+      map.set(key, value);
+    }
+    return value;
+  }
+
+  /** @type {BoundedCache<K, V>['set']} */
+  function set(key, value) {
+    if (map.has(key)) map.delete(key);
+    else if (map.size >= limit) map.delete(map.keys().next().value);
+    map.set(key, value);
+  }
+
+  /** @type {BoundedCache<K, V>['getOrCreate']} */
+  function getOrCreate(key, create) {
+    let value = get(key);
+    if (value === undefined) {
+      value = create(key);
+      set(key, value);
+    }
+    return value;
+  }
+
+  return { get, set, getOrCreate, clear: () => map.clear(), size: () => map.size };
+}
+
+/**
+ * @template V
+ * @typedef {object} SemanticCache
+ * @property {(value: any) => V | undefined} get - Lookup by structural
+ *   identity. `undefined` means miss — including "this value cannot be
+ *   keyed", which is a permanent miss, never someone else's entry.
+ * @property {(value: any, entry: V) => boolean} set - Insert or refresh.
+ *   Returns whether the entry was retained — `false` means the value
+ *   could not be keyed, which a caller comparing sizes to detect an
+ *   eviction must not mistake for one.
+ * @property {(value: any, create: (identity: string | null) => V) => V}
+ *   getOrCreate - Lookup or compute-and-insert in one step. `create`
+ *   receives the identity, or `null` when the value was unkeyable and
+ *   the result will NOT be retained.
+ * @property {() => void} clear - Drop every entry.
+ * @property {() => number} size - Current entry count.
+ */
+
+/**
+ * A bounded cache keyed by a value's COLLISION-FREE structural identity
+ * ({@link semanticKey}), for entries whose reuse decides a result.
+ *
+ * Two guarantees a fingerprint-keyed cache cannot give:
+ *
+ *  - **Distinct inputs never share an entry.** The key is the whole
+ *    deterministic serialization, so a hash collision cannot make one
+ *    document's compiled semantics answer for another's.
+ *  - **An unkeyable input is a permanent miss, never a wrong hit.** A
+ *    value carrying a cycle, a function or a class instance cannot be
+ *    keyed injectively, so it is computed afresh every time and never
+ *    retained. Correct and slow beats fast and wrong; callers that want
+ *    to *reject* such input should validate before asking the cache.
+ *
+ * Compose with a discriminating tuple when an entry depends on more than
+ * the document — `cache.getOrCreate([document, dialect, strict], …)`
+ * keys the whole tuple, which a `${a}|${b}` string concatenation cannot
+ * do injectively once `a` may itself contain the separator.
+ * @template V
+ * @param {number} limit - Maximum number of retained entries (> 0)
+ * @returns {SemanticCache<V>}
+ */
+export function createSemanticCache(limit) {
+  /** @type {BoundedCache<string, V>} */
+  const cache = createBoundedCache(limit);
+
+  /** @param {any} value @returns {string | null} */
+  const identify = (value) => {
+    try {
+      return semanticKey(value);
+    }
+    catch {
+      return null; // unkeyable: a permanent miss
+    }
+  };
+
+  /** @type {SemanticCache<V>['get']} */
+  function get(value) {
+    const identity = identify(value);
+    return identity === null ? undefined : cache.get(identity);
+  }
+
+  /** @type {SemanticCache<V>['set']} */
+  function set(value, entry) {
+    const identity = identify(value);
+    if (identity === null) return false;
+    cache.set(identity, entry);
+    return true;
+  }
+
+  /** @type {SemanticCache<V>['getOrCreate']} */
+  function getOrCreate(value, create) {
+    const identity = identify(value);
+    if (identity === null) return create(null);
+    let entry = cache.get(identity);
+    if (entry === undefined) {
+      entry = create(identity);
+      cache.set(identity, entry);
+    }
+    return entry;
+  }
+
+  return { get, set, getOrCreate, clear: () => cache.clear(), size: () => cache.size() };
+}
+
+/**
+ * @template {object} K
+ * @template V
+ * @typedef {object} WeakCache
+ * @property {(key: K) => V | undefined} get
+ * @property {(key: K, value: V) => void} set
+ * @property {(key: K, create: (key: K) => V) => V} getOrCreate
+ */
+
+/**
+ * The identity axis: a reference-keyed cache whose entries live exactly
+ * as long as their keys. No bound, deliberately — the bound is the
+ * caller's ownership of the key objects.
+ * @template {object} K
+ * @template V
+ * @returns {WeakCache<K, V>}
+ */
+export function createWeakCache() {
+  /** @type {WeakMap<K, V>} */
+  const map = new WeakMap();
+
+  /** @type {WeakCache<K, V>['getOrCreate']} */
+  function getOrCreate(key, create) {
+    let value = map.get(key);
+    if (value === undefined) {
+      value = create(key);
+      map.set(key, value);
+    }
+    return value;
+  }
+
+  return { get: (key) => map.get(key), set: (key, value) => map.set(key, value), getOrCreate };
+}