@jarenjs/core 0.43.1 → 0.46.4

package/ARCHITECTURE.md

@@ -126,6 +126,10 @@ flowchart TB
             GeoMerc["mercator.js + simplify.js<br/>Projection out, simplification"]
         end
 
+        subgraph VectorModule["Vectors"]
+            VectorIndex["vector/index.js<br/>Similarity kernels, normalization, packed form"]
+        end
+
         subgraph MathModules["Mathematics"]
             MathIndex["math/index.js"]
             Int32Math["int32.js<br/>Fixed-point math"]
@@ -205,6 +209,7 @@ flowchart TB
     style MathModules fill:#ffccbc
     style DateModule fill:#fff9c4
     style GeoModule fill:#b2dfdb
+    style VectorModule fill:#b2dfdb
 ```
 
 ---
@@ -573,15 +578,17 @@ direction is *not* claimed, because WKT whitespace, the `M` measure and number
 spelling are normalized on the way through.
 
 Against [`wellknown`](https://www.npmjs.com/package/wellknown), the established
-WKT↔GeoJSON converter (`npm run benchmark:geo`, Node v24.19.0):
+WKT↔GeoJSON converter (`npm run benchmark:geo`, Node <!--bm:geo.node-->v24.19.0<!--/bm-->):
 
-| scenario | Jaren | wellknown | ratio |
+<!--bm:geo.wktTable-->
+| scenario | Jaren | rival | ratio |
 |---|---|---|---|
-| parse a `POINT` | 439 ns | 1.34 µs | **3.1×** |
-| parse a 2000-vertex `POLYGON` | 820 µs | 2.20 ms | **2.7×** |
-| write that polygon | 160 µs | 213 µs | **1.3×** |
-| validate a `POINT` | 241 ns | 1.29 µs | **5.4×** |
-| validate that polygon | 493 µs | 1.94 ms | **3.9×** |
+| wkt parse (POINT) | 431.1 ns | 1.31 µs (wellknown) | **3.1×** |
+| wkt parse (2000-vertex polygon) | 843.80 µs | 1.98 ms (wellknown) | **2.3×** |
+| wkt stringify (2000-vertex polygon) | 163.40 µs | 229.70 µs (wellknown) | **1.4×** |
+| wkt validate (POINT) | 242.7 ns | 1.28 µs (wellknown) | **5.3×** |
+| wkt validate (2000-vertex polygon) | 496.00 µs | 1.90 ms (wellknown) | **3.8×** |
+<!--/bm-->
 
 The last two rows are the ones the sink exists for: `wellknown` has no
 predicate, so validating means parsing and throwing the geometry away. And the
@@ -620,37 +627,48 @@ RFC 7946 removed coordinate-reference-system support and mandates WGS 84, so
 there is no SRID table and no reprojection: conformance removes the need rather
 than an omission hiding it.
 
-**Measured against the field** (`npm run benchmark:geo`, Node v22.22.2). Every
+**Measured against the field** (`npm run benchmark:geo`, Node <!--bm:geo.node-->v24.19.0<!--/bm-->). Every
 scenario asserts result equivalence before any timing, and the harness refuses
 to print a table if the engines disagree: distance, area, length and bounding
 box come out *bit-identical* to Turf, containment agrees on a 400-point sweep,
 and the index returns exactly Flatbush's answer on 200 queries. Ratios are the
-rival's time over this kernel's, so above 1 means Jaren is faster.
+rival's time over this kernel's, so above 1 means Jaren is faster; the rows
+below derive from the committed measurement and are refreshed with it.
 
+<!--bm:geo.table-->
 | scenario | Jaren | rival | ratio |
 |---|---|---|---|
-| distance, two positions | 26.2 ns | 128.5 ns (turf) | **4.9×** |
-| distance vs an ellipsoidal library | 52.3 ns | 648.4 ns (geolib) | **12.4×** |
-| line length, 500 positions | 20.5 µs | 63.6 µs (turf) | **3.1×** |
-| point in polygon, 12 vertices | 228 ns | 327 ns (turf) | **1.4×** |
-| bounding box, 2000 vertices | 15.3 µs | 18.1 µs (turf) | **1.2×** |
-| polygon area, 2000 vertices | 18.8 µs | 20.4 µs (turf) | **1.1×** |
-| centroid, 2000 vertices | 18.4 µs | 19.1 µs (turf) | 1.0× |
-| index build, 100k boxes | 12.2 ms | 12.4 ms (flatbush) | 1.0× |
-| index probe, 100k boxes | 529 ns | 529 ns (flatbush) | 1.0× |
-| point in polygon, 2000 vertices | 8.2 µs | 3.7 µs (turf) | **0.5×** |
-
-One row is a loss, and it is kept on purpose. **Point-in-polygon on a large
-ring runs at about half Turf's speed** because every edge that could matter
-goes through the exact orientation predicate, where Turf uses naive
+| distance (two positions) | 28.3 ns | 111.0 ns (turf) | **3.9×** |
+| distance (vs geolib, ellipsoidal) | 50.7 ns | 609.1 ns (geolib) | **12.0×** |
+| distance (equirectangular screen) | 26.4 ns | — | — |
+| point in polygon (12-vertex) | 72.9 ns | 226.4 ns (turf) | **3.1×** |
+| point in polygon (2000-vertex) | 8.23 µs | 3.71 µs (turf) | 0.5× |
+| polygon area (2000-vertex) | 17.65 µs | 18.45 µs (turf) | **1.0×** |
+| line length (500 positions) | 26.65 µs | 63.47 µs (turf) | **2.4×** |
+| bounding box (2000-vertex) | 21.08 µs | 18.65 µs (turf) | 0.9× |
+| centroid (2000-vertex) | 16.70 µs | 23.18 µs (turf) | **1.4×** |
+| index build (100k boxes) | 12.70 ms | 10.62 ms (flatbush) | 0.8× |
+| index probe (100k boxes) | 602.3 ns | 668.9 ns (flatbush) | **1.1×** |
+| linear scan (100k boxes, no index) | 141.50 µs | — | — |
+<!--/bm-->
+
+The losses are kept, and named by the same measurement: on the committed run <!--bm:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/bm-->.
+**Point-in-polygon on a large ring runs at about half Turf's speed**
+(<!--bm:geo.pip2000-->0.5×<!--/bm--> at 2000 vertices) because every edge that could
+matter goes through the exact orientation predicate, where Turf uses naive
 floating-point arithmetic. That is the trade this module exists to make — it
 is the difference between a containment test that is right on near-collinear
 input and one that is merely fast. Cheap straddle/span tests already skip the
 predicate on edges that cannot affect the answer, which took this from 0.2×
-to 0.5×; the rest is the predicate itself.
+to about 0.5×; the rest is the predicate itself, and the campaign that made
+geography reachable across the suite never traded it away. The bounding box
+of the same ring and the index build against Flatbush sit within a few tenths
+of level (<!--bm:geo.bbox2000-->0.9×<!--/bm--> and <!--bm:geo.indexBuild-->0.8×<!--/bm-->) and move
+between runs and Node versions; they are published as measured rather than
+rounded to a win.
 
-Two former losses closed, and both closures carry a lesson about profiling
-before fixing:
+Two former losses were closed by profiling before fixing, and both closures
+carry the lesson:
 
 - **Index build** was 2.6× behind Flatbush, and the assumed cause — the leaf
   sort permuting the four-wide bounds rows on every swap — turned out to be
@@ -660,7 +678,8 @@ before fixing:
   (identical values, verified exhaustively at the corners and over 200k
   pseudo-random points), the sort orders a `Uint32Array` permutation with an
   insertion-sort cutoff, and the bounds are written once, already in leaf
-  order. Build and probe are both level with Flatbush now.
+  order. Whether the row is level or a few tenths behind on a given run is
+  what the derived table above says.
 - **Centroid** walked the same `eachPosition` as `bboxOf` yet lost where
   `bboxOf` won. The difference was the callback body: accumulating doubles
   into *closure variables* writes a boxed heap number per `+=` — two per
@@ -674,9 +693,34 @@ import { orient2d, haversineDistance, ringWinding, geohashEncode } from '@jarenj
 orient2d(0, 0, 1, 0, 0, 1);                    // > 0 — counter-clockwise, exactly
 haversineDistance(4.9041, 52.3676, 2.3522, 48.8566);  // 429_862 m
 ringWinding([[0,0],[1,0],[1,1],[0,1],[0,0]]);  // 1 — RFC 7946 exterior ring
-geohashEncode(4.9041, 52.3676, 5);             // 'u173z' — a string, so $starts-with is proximity
+geohashEncode(4.9041, 52.3676, 5);             // 'u173z' — a string: a prefix buckets, geohashNeighbours is proximity
 ```
 
+### 5c. Vector Module (`vector/`)
+
+The suite's one home for n-dimensional vector arithmetic — what an embedding
+is compared, normalized and stored with. As with geo, **there is no vector
+type**: a vector is a plain array of finite numbers (`number[]` out of JSON, a
+`Float32Array` out of a packed column), so it survives every JSON boundary
+it travels through. One file, seven functions, three rules every consumer
+relies on: similarity is *higher-is-better* in every metric; a malformed
+comparison (mismatched lengths, empty, null, non-finite) *scores 0 and never
+throws*; and the constructors (`packVector`, `l2Normalize`) *refuse with
+null* rather than truncate, pad or zero-fill.
+
+| Function | Owns |
+|---|---|
+| `isVector(v, dims?)` | the one shape guard — array or float typed array, all finite, optionally an exact width |
+| `dotProduct`, `cosineSimilarity`, `euclideanSimilarity` | the similarity kernels; cosine is the one the suite ranks by |
+| `l2Normalize` | the unit vector, as a new `Float32Array` — the stored form, so cosine, dot and Euclidean agree in rank |
+| `packVector`, `unpackVector` | the little-endian binary32 column form; an aligned unpack is a view, a misaligned one a copy |
+
+The comparison kernels do not re-check components — that is the gate's job,
+once, at the boundary — and they keep their loops tight for the sweep that is
+their reason to exist; they guarantee a finite answer. The fixed-arity vector
+classes in `math/` (`Vec2f64`, `Vec3f64`) are 2D/3D geometry with a
+different convention and a different job, and they stay where they are.
+
 ### 6. Text Module (`text/`)
 
 Comprehensive string format validation organized by domain.

package/README.md

@@ -1,6 +1,6 @@
 # @jarenjs/core
 
-The zero-dependency foundation of [Jaren](https://github.com/jklarenbeek/jarenjs). Everything the rest of the suite is built on lives here — type guards, Unicode-aware string handling, a large text-validation toolbox, number range helpers, fixed-point and vector math, the calendar kernel, the spatial kernel, the message-catalog compiler, unit/currency conversion and a finance library.
+The zero-dependency foundation of [Jaren](https://github.com/jklarenbeek/jarenjs). Everything the rest of the suite is built on lives here — type guards, Unicode-aware string handling, a large text-validation toolbox, number range helpers, fixed-point and vector math, the calendar kernel, the spatial kernel, the vector kernel, the message-catalog compiler, unit/currency conversion and a finance library.
 
 None of it depends on JSON Schema: every module can be used standalone in any JavaScript project.
 
@@ -23,6 +23,7 @@ None of it depends on JSON Schema: every module can be used standalone in any Ja
 | `@jarenjs/core/bigint` | bigint helpers (`BigInt_min`, `BigInt_MinMax`, ...) |
 | `@jarenjs/core/dates` | RFC 3339 / ISO 8601 validation, plus the calendar kernel: integer date arithmetic, compiled formatting, durations |
 | `@jarenjs/core/geo` | the spatial kernel over GeoJSON: robust orientation, great-circle measurement, rings, bounding boxes, geohash, GeoJSON/WKT validity, a packed-Hilbert box index, Web Mercator and Douglas-Peucker simplification |
+| `@jarenjs/core/vector` | the vector kernel over plain arrays: dot, cosine and Euclidean similarity (higher-is-better; a malformed pair scores 0), l2 normalization, the packed little-endian Float32 form and the one shape guard (`isVector`) |
 | `@jarenjs/core/text` | text validators: emails, hostnames, IPs, URIs/IRIs, UUIDs, punycode, ... |
 | `@jarenjs/core/math` | int32/float64 math and 2D/3D vector classes; the linear `remap` and unit-interval `clamp01` |
 | `@jarenjs/core/finance` | zero-dependency finance/trading formulas: TVM, cash flow, amortization, interest, depreciation, bonds, technical indicators, returns/risk |
@@ -95,11 +96,33 @@ Four design decisions carry the module:
 
 - **Orientation is computed exactly** (Shewchuk's adaptive predicates): a naive floating-point determinant returns the *wrong sign* on near-collinear input, which makes containment contradict itself. Every ring winding and point-in-polygon answer rests on this sign, and the deliberate cost is on the [benchmark page](https://jklarenbeek.github.io/jarenjs/#/benchmarks?suite=geo).
 - **Measurement is spherical, drawing is projected, and the two never mix.** A Euclidean norm on raw degrees is 64% wrong over 1 km at Dutch latitudes, so `haversineDistance`/`sphericalRingArea` work on the sphere (`equirectDistance` is the cheap screening form for rejecting candidates first), while `projectMercator`/`fitMercator` and `simplifyLine`/`simplifyRing` exist for renderers — never measure on a projected coordinate.
-- **Validity is a separate concern from traversal.** `eachPosition`, `bboxOf`, `centroidOf` and friends measure without judging; `isValidGeoJson` (structure plus the ring closure a JSON Schema provably cannot express), `isValidWkt` and `isValidGeohash` are the one-call judgments that back the `geoFormats` group in [`@jarenjs/formats`](../formats), next to the full GeoJSON meta-schema artifacts in [`@jarenjs/json`](../json).
-- **WKT is one grammar walk with two entry points.** `isValidWkt` and `wktToGeoJson` run the *same* scan, parameterized by a sink that is absent for the predicate and present for the parser — so the `wkt` format tester (which runs per value in the validator and per keystroke in the form layer) allocates nothing, and the two cannot drift apart. A committed corpus asserts `isValidWkt(s) === (wktToGeoJson(s) !== null)` for all 181 entries, malformed half included. `geoJsonToWkt` writes the string back, and `wktToGeoJson(geoJsonToWkt(g))` returns `g`; the text direction is *not* claimed, because whitespace, the `M` measure and number spelling are normalized. Against [`wellknown`](https://www.npmjs.com/package/wellknown) the parse is 3.1× faster on a `POINT` and the yes-or-no answer 5.4× — and wellknown *validates less* while being slower, which is the honest framing; the table and every language difference are in [ARCHITECTURE](./ARCHITECTURE.md).
+- **Validity is a separate concern from traversal, and a box is refused rather than made too small.** `eachPosition`, `bboxOf`, `centroidOf` and friends measure without judging (a ring is read as closed whether or not it is); a box over any non-finite coordinate is `null`, never a plausible box that misses its input; and boxes never cross the antimeridian — cut the geometry at ±180° as RFC 7946 §3.1.9 asks, and every containment test and index probe is right. `isValidGeoJson` (structure plus the ring closure a JSON Schema provably cannot express), `isValidWkt` and `isValidGeohash` are the one-call judgments that back the `geoFormats` group in [`@jarenjs/formats`](../formats), next to the full GeoJSON meta-schema artifacts in [`@jarenjs/json`](../json).
+- **WKT is one grammar walk with two entry points.** `isValidWkt` and `wktToGeoJson` run the *same* scan, parameterized by a sink that is absent for the predicate and present for the parser — so the `wkt` format tester (which runs per value in the validator and per keystroke in the form layer) allocates nothing, and the two cannot drift apart. A committed corpus asserts `isValidWkt(s) === (wktToGeoJson(s) !== null)` for all 181 entries, malformed half included. `geoJsonToWkt` writes the string back, and `wktToGeoJson(geoJsonToWkt(g))` returns `g`; the text direction is *not* claimed, because whitespace, the `M` measure and number spelling are normalized. Against [`wellknown`](https://www.npmjs.com/package/wellknown) the parse is <!--bm:geo.wktParsePoint-->3.1×<!--/bm--> faster on a `POINT` and the yes-or-no answer <!--bm:geo.wktValidatePoint-->5.3×<!--/bm--> — and wellknown *validates less* while being slower, which is the honest framing; the table and every language difference are in [ARCHITECTURE](./ARCHITECTURE.md). The kernel's own losses are published there too, derived from the same run: <!--bm:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/bm-->.
 
 The spatial query operators (`$distance`, `$within`, `$geohash`, spatial joins over the box index) live in the query engine in [`@jarenjs/json`](../json); the streaming map chart that draws a FeatureCollection with bounded memory lives in [`@jarenjs/charts`](../../components/charts). The full module reference is [docs/GEO.md](./docs/GEO.md).
 
+## Vectors
+
+`@jarenjs/core/vector` is the suite's one home for n-dimensional vector arithmetic — the kernels an embedding is compared, normalized and stored with. As with GeoJSON positions, there is no vector type: a vector is a plain array of finite numbers, `number[]` straight out of JSON or a `Float32Array` straight out of a packed column, so it survives a ledger record, a document store and a wire reply unchanged.
+
+```javascript
+import { cosineSimilarity, l2Normalize, packVector, unpackVector, isVector } from '@jarenjs/core/vector';
+
+cosineSimilarity([1, 0], [1, 1]);              // 0.7071… — higher is better, in [-1, 1]
+cosineSimilarity([1, 0], [1, 0, 0]);           // 0 — a malformed pair scores 0, never throws
+const bytes = packVector(l2Normalize([3, 4])); // Uint8Array of 8 bytes: little-endian binary32
+unpackVector(bytes, 2);                        // Float32Array [0.6, 0.8]
+isVector([0.1, NaN]);                          // false — the shape guard every consumer shares
+```
+
+Three rules, kept by every function so that no caller has to check them again:
+
+- **Higher is better, in every metric.** Cosine answers in [-1, 1], the dot product is unbounded, Euclidean similarity is `1 / (1 + distance)` in (0, 1] — so one descending sort ranks any of them, and nobody remembers which way a metric sorts.
+- **A malformed comparison scores 0 and never throws.** Mismatched lengths, an empty vector, a null or a non-finite component answer 0: one bad vector among ten thousand loses the comparison, it does not kill the sweep, and it never poisons a ranking with `NaN`.
+- **Refuse, never fix.** `packVector` and `l2Normalize` answer `null` for anything `isVector` refuses, the way a bounding box refuses a position it cannot bound; nothing truncates, pads or zero-fills a vector into the shape it was supposed to have.
+
+The packed form is `4·d` bytes of little-endian binary32 — the value a database column stores; components round to `Math.fround` and come back exactly. Unpacking aligned bytes on a little-endian host is a *view*, not a copy, which is what a sweep over ten thousand fetched rows is paid for by; misaligned bytes (a pooled `Buffer`, an odd offset into a record) and big-endian hosts take the copy path to the same values. The client that produces embeddings — and a deterministic reference embedder for tests — lives in [`@jarenjs/ai`](../ai/README.md#embeddings).
+
 ## Messages
 
 `@jarenjs/core/message` is the template/catalog compiler behind the validator's uniform error messages and the form layer's labels — msgid plus parameters in, rendered text out, so every message is translatable by swapping a catalog ([`@jarenjs/locales`](../locales) ships eleven language packs over it):

package/dist/types/geo/geohash.d.ts

@@ -53,9 +53,10 @@ export declare function geohashCellSize(precision: number): number[] | null;
  * nine-element array. Cells that would fall off the poles are omitted,
  * so the result may be shorter.
  *
- * This is what makes a prefix search safe near a boundary: two points
+ * This is the proximity probe, and a single cell is not one: two points
  * metres apart can sit in different cells, so a proximity query tests
- * the neighbourhood rather than the single cell.
+ * the neighbourhood rather than the single cell — a prefix buckets, it
+ * does not find neighbours.
  *
  * @param {string} hash
  * @returns {string[]}

package/dist/types/vector/index.d.ts

@@ -0,0 +1,98 @@
+export type Vector = number[] | Float32Array | Float64Array;
+/**
+ * Whether `v` is a vector: a non-empty `Array`, `Float32Array` or
+ * `Float64Array` whose every component is a finite number — and, when
+ * `dims` is given, exactly that many of them. The one shape guard the
+ * suite shares, so a ledger, an operator and a store refuse the same
+ * inputs.
+ * @param {unknown} v
+ * @param {number} [dims] - the exact length required
+ * @returns {v is Vector}
+ * @example
+ * isVector([0.1, 0.2, 0.3]);        // true
+ * isVector([0.1, 0.2, 0.3], 4);     // false — wrong width
+ * isVector([0.1, NaN]);             // false — not finite
+ * isVector(new Uint8Array(4));      // false — bytes are not a vector; unpack them first
+ */
+export declare function isVector(v: unknown, dims?: number): v is Vector;
+/**
+ * The dot product. Unbounded; equal to the cosine for unit vectors, so
+ * a sweep over l2-normalized vectors can take this cheaper form.
+ * @param {Vector | null | undefined} a
+ * @param {Vector | null | undefined} b
+ * @returns {number} the product — or 0 for a malformed pair (mismatched
+ *   lengths, empty, null, or a result that is not finite)
+ */
+export declare function dotProduct(a: Vector | null | undefined, b: Vector | null | undefined): number;
+/**
+ * Cosine similarity, in [-1, 1]: 1 for the same direction, 0 for
+ * orthogonal, -1 for opposite. The one metric the suite ranks by —
+ * scale-free, so vectors from a model that does not normalize compare
+ * the same as vectors from one that does.
+ * @param {Vector | null | undefined} a
+ * @param {Vector | null | undefined} b
+ * @returns {number} the similarity — or 0 for a malformed pair, and 0
+ *   when either vector has no direction (all zeros)
+ * @example
+ * cosineSimilarity([1, 0], [1, 0]);   // 1
+ * cosineSimilarity([1, 0], [0, 1]);   // 0
+ * cosineSimilarity([1, 0], [-2, 0]);  // -1
+ * cosineSimilarity([1, 0], [1]);      // 0 — mismatched, never a throw
+ */
+export declare function cosineSimilarity(a: Vector | null | undefined, b: Vector | null | undefined): number;
+/**
+ * Euclidean similarity, `1 / (1 + distance)`, in (0, 1]: 1 for equal
+ * vectors, falling towards 0 as they move apart. The distance turned
+ * into the same higher-is-better direction as the other kernels, so a
+ * caller never has to remember which way a metric sorts.
+ * @param {Vector | null | undefined} a
+ * @param {Vector | null | undefined} b
+ * @returns {number} the similarity — or 0 for a malformed pair
+ */
+export declare function euclideanSimilarity(a: Vector | null | undefined, b: Vector | null | undefined): number;
+/**
+ * The unit vector in `a`'s direction, as a new `Float32Array` — the
+ * form the packed column stores, so that cosine, dot and Euclidean
+ * then agree in rank. The input is never modified.
+ * @param {Vector | null | undefined} a
+ * @returns {Float32Array | null} the normalized copy; the zero vector
+ *   stays zero (it has no direction, and scores 0 against everything);
+ *   null for anything `isVector` refuses, or a norm that overflows
+ */
+export declare function l2Normalize(a: Vector | null | undefined): Float32Array | null;
+/**
+ * The packed form: `4·d` bytes of little-endian binary32, the value a
+ * database column stores. Components round to their nearest binary32
+ * (`Math.fround`); `unpackVector` returns exactly those.
+ *
+ * A component too large for binary32 has no nearest one — it rounds to
+ * an infinity — so such a vector is REFUSED rather than stored as bytes
+ * that unpack into something `isVector` would reject. Normalized
+ * vectors, which is what a column holds, can never meet it.
+ * @param {Vector | null | undefined} a
+ * @returns {Uint8Array | null} the bytes — null for anything `isVector`
+ *   refuses (empty, non-finite) and for a component that overflows
+ *   binary32, never a partial or zero-filled record
+ * @example
+ * packVector([1]);                 // Uint8Array [0, 0, 128, 63]
+ * packVector([1, NaN]);            // null
+ * packVector([1e39]);              // null — no finite binary32 is nearest
+ */
+export declare function packVector(a: Vector | null | undefined): Uint8Array | null;
+/**
+ * The vector packed in `bytes`, read as `dims` little-endian binary32
+ * components. The width is the caller's to state — a column declares
+ * it — and bytes of any other length are refused rather than partially
+ * read.
+ *
+ * On a little-endian host, 4-byte-aligned bytes come back as a VIEW over
+ * the same buffer — no copy, which is what a sweep over ten thousand
+ * fetched rows is paid for by; writing into the result writes into the
+ * bytes. Misaligned bytes (a pooled `Buffer`, a slice at an odd offset)
+ * and big-endian hosts take the copy path and answer the same values.
+ * @param {Uint8Array | null | undefined} bytes
+ * @param {number} dims - the width the bytes must hold
+ * @returns {Float32Array | null} the vector — null when `bytes` is not a
+ *   `Uint8Array` of exactly `4·dims` bytes
+ */
+export declare function unpackVector(bytes: Uint8Array | null | undefined, dims: number): Float32Array | null;

package/docs/GEO.md

@@ -22,7 +22,10 @@ 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.
+point-in-polygon loss on the benchmark page (<!--bm:geo.pip2000-->0.5×<!--/bm--> against
+Turf at 2000 vertices, kept on purpose). Every loss the kernel carries is
+published in [ARCHITECTURE](../ARCHITECTURE.md), derived from the committed
+measurement: <!--bm:geo.losses-->three rows lose to a rival: point in polygon (2000-vertex) at 0.5× (turf), bounding box (2000-vertex) at 0.9× (turf), index build (100k boxes) at 0.8× (flatbush)<!--/bm-->.
 
 ## Distance — `distance.js`
 
@@ -79,6 +82,25 @@ plausible box that does not contain its input, and a candidate filter
 built on such a box loses matching entries with nothing to show for it.
 `null` is the answer every caller already handles.
 
+**Boxes do not cross the antimeridian.** RFC 7946 §3.1.9 tells producers
+to cut a geometry at ±180° rather than let it span the line, and the
+kernel follows that posture instead of re-joining what a producer split:
+`bboxOf` of an uncut geometry with positions either side of the line
+returns a box spanning the globe the *wrong* way (`[-179, 0, 179, 0]` for
+two points four degrees apart), and `circleBounds` answers a west below
+−180 rather than wrapping, which is how a caller detects the case. Cut
+the geometry as the RFC asks and every box, containment test and index
+probe is right; there is no flag, because a box that meant "the short way
+round" for some values and "the long way" for others would be worse than
+one rule.
+
+**Traversal is not validation.** `containsPosition`, `geometryArea` and
+the rest walk whatever rings they are given and treat a ring as closed
+whether or not its last position repeats its first — the same reading
+every implementation makes. A ring `isValidGeoJson` refuses (unclosed,
+too short) therefore still measures; judgment is one call away and is not
+duplicated inside every walk.
+
 ## GeoJSON traversal — `geojson.js`
 
 The one layer that reads the `type` discriminator; every function takes
@@ -158,11 +180,16 @@ spelling are all normalized.
 
 `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.
+needs no new vocabulary anywhere: bucketing is grouping on a substring,
+tiling is a prefix, and a sorted index over the hash is a spatial index.
+**A prefix is bucketing, not proximity.** Two points ten metres apart can
+differ in the *first* character of their cell, so a single-prefix "near
+here" misses a neighbour at every cell boundary; the proximity probe is
+`geohashNeighbours` — the cell and its eight neighbours, in reading order
+(north-west first, the cell itself in the middle, fewer past a pole) —
+followed by the exact distance on what survives. Cells are not equal-area
+(2.4× between the equatorial and polar bands), and a cell is never a
+distance.
 
 ## Drawing — `mercator.js` + `simplify.js`
 
@@ -178,10 +205,15 @@ 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.
+The thirteen spatial *query operators* — the eight measurements and
+predicates (`$bbox`, `$area`, `$length`, `$centroid`, `$distance`,
+`$within`, `$bbox-intersects`, `$geohash`) and the five conversions
+(`$geo-parse`, `$geo-text`, `$geohash-bounds`, `$geohash-neighbours`,
+`$geo-simplify`), plus index-screened spatial joins — live in the query
+engine of `@jarenjs/json` (QUERY-FORMAT §8.14), and `@jarenjs/linq`
+spells every one of them; the GeoJSON meta-schema artifacts live in
+`@jarenjs/json/schemas`; derived spatial index columns and the two-stage
+pushdown live in `@jarenjs/db`; the map chart and its bounded-memory
+streaming accumulator live in `@jarenjs/charts`. Overlay operations
+(union/intersection/difference/buffer) are deliberately absent — see the
+ROADMAP.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/core",
   "private": false,
-  "version": "0.43.1",
+  "version": "0.46.4",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -80,6 +80,10 @@
       "types": "./dist/types/geo/*.d.ts",
       "default": "./src/geo/*.js"
     },
+    "./vector": {
+      "types": "./dist/types/vector/index.d.ts",
+      "default": "./src/vector/index.js"
+    },
     "./function": {
       "types": "./dist/types/function.d.ts",
       "default": "./src/function.js"

package/src/geo/geohash.js

@@ -184,9 +184,10 @@ export function geohashCellSize(precision) {
  * nine-element array. Cells that would fall off the poles are omitted,
  * so the result may be shorter.
  *
- * This is what makes a prefix search safe near a boundary: two points
+ * This is the proximity probe, and a single cell is not one: two points
  * metres apart can sit in different cells, so a proximity query tests
- * the neighbourhood rather than the single cell.
+ * the neighbourhood rather than the single cell — a prefix buckets, it
+ * does not find neighbours.
  *
  * @param {string} hash
  * @returns {string[]}

package/src/geo/wkt.js

@@ -26,7 +26,9 @@
 // point must match. Polygon rings must close and carry at least four
 // points, as the spec requires. No leading or trailing text is
 // tolerated: a format that trims would accept strings a consumer then
-// fails on.
+// fails on. A GEOMETRYCOLLECTION nests at most eight deep — the bound
+// the GeoJSON value gate applies — so hostile nesting is refused, never
+// recursed into.
 //
 // Parsing answers what the text says and judges nothing else: a
 // coordinate outside the WGS 84 bounds parses, and `isValidGeoJson` is
@@ -260,9 +262,31 @@ function scanPolygonBody(text, at, dim, out) {
   return scanNested(text, at, dim, 1, scanRing, out);
 }
 
+/**
+ * How deep a `GEOMETRYCOLLECTION` may nest. A nesting guard, not a spec
+ * rule, and the same bound `isValidGeoJson` applies to a GeoJSON
+ * `GeometryCollection`: unbounded recursion on hostile input is a
+ * different problem than an unusual document, and a WKT string nested
+ * deeper than the value gate admits could never become a valid value
+ * anyway. Past the bound the walk answers "not WKT" — the same answer
+ * both entry points give for any other malformed text — rather than
+ * overflowing the stack.
+ */
+const MAX_COLLECTION_DEPTH = 8;
+
+/** The collection nesting the walk is currently inside (one walk at a
+ * time; reset at the entry point, so an aborted walk cannot poison the
+ * next). */
+let collectionDepth = 0;
+
 /** A collection member is a whole tagged geometry, modifier and all. */
 function scanCollectionItem(text, at, dim, out) {
-  return scanGeometry(text, at, out);
+  if (collectionDepth >= MAX_COLLECTION_DEPTH)
+    return -1;
+  collectionDepth += 1;
+  const end = scanGeometry(text, at, out);
+  collectionDepth -= 1;
+  return end;
 }
 
 /**
@@ -349,6 +373,7 @@ function scanGeometry(text, at, out) {
 function scanWkt(text, out) {
   if (typeof text !== 'string' || text.length === 0 || isWhitespaceCode(text.charCodeAt(0)))
     return false;
+  collectionDepth = 0;
   return scanGeometry(text, 0, out) === text.length;
 }
 

package/src/vector/index.js

@@ -0,0 +1,266 @@
+//@ts-check
+
+//#region @jarenjs/core/vector
+// The suite's one home for n-dimensional vector arithmetic: the kernels
+// an embedding is compared, normalized and stored with. There is no
+// vector type. A vector is a plain array of finite numbers — `number[]`
+// straight out of JSON, or a `Float32Array` straight out of a packed
+// column — the convention the spatial kernel keeps for GeoJSON
+// positions, and for the same reason: an embedding travels through a
+// ledger record, a jsonb document and a wire reply, and a wrapper class
+// survives none of those boundaries.
+//
+// Three rules every function here keeps, so that every caller — a
+// ranked recall, a query operator, a store's fetch-and-rank plan — can
+// rely on them without checking again:
+//
+//   higher is better    every similarity answers in the same direction:
+//                       cosine in [-1, 1], the dot product unbounded,
+//                       Euclidean as 1 / (1 + distance) in (0, 1] — so
+//                       one descending sort ranks any of them
+//   malformed scores 0  a comparison over mismatched lengths, an empty
+//                       vector, a null, or a non-finite component answers
+//                       0 and never throws: one bad vector among ten
+//                       thousand loses the comparison, it does not kill
+//                       the sweep, and it never poisons a ranking with NaN
+//   refuse, never fix   the constructors — `packVector`, `l2Normalize` —
+//                       answer null for anything `isVector` refuses, the
+//                       way a bounding box refuses a position it cannot
+//                       bound; nothing here truncates, pads or zero-fills
+//                       a vector into the shape it was supposed to have
+//
+// `isVector` is the one definition of "a vector" the ledger, the query
+// operators and the store share, so they refuse the same inputs. The
+// comparison kernels do not re-check components (that is the gate's
+// job, once, at the boundary); they guarantee a finite answer.
+//
+// The packed form is little-endian IEEE 754 binary32, 4·d bytes for d
+// dimensions — the bytes a database column stores. Unpacking an aligned
+// buffer on a little-endian host is a view, not a copy, which is what
+// makes ranking over a fetched column fast; a misaligned buffer (a slice
+// of a pooled allocation, an offset into a larger record) or a
+// big-endian host takes the copy path. Alignment is an observation about
+// one driver on one day, not a contract any driver signed.
+
+/**
+ * A vector as this module accepts it: plain numbers, in a plain array or
+ * a float typed array. Never a class.
+ * @typedef {number[] | Float32Array | Float64Array} Vector
+ */
+
+/** Whether this host stores a Float32 in the packed (little-endian) byte order. */
+const LITTLE_ENDIAN = new Uint8Array(new Uint16Array([1]).buffer)[0] === 1;
+
+/**
+ * Whether `v` is a vector: a non-empty `Array`, `Float32Array` or
+ * `Float64Array` whose every component is a finite number — and, when
+ * `dims` is given, exactly that many of them. The one shape guard the
+ * suite shares, so a ledger, an operator and a store refuse the same
+ * inputs.
+ * @param {unknown} v
+ * @param {number} [dims] - the exact length required
+ * @returns {v is Vector}
+ * @example
+ * isVector([0.1, 0.2, 0.3]);        // true
+ * isVector([0.1, 0.2, 0.3], 4);     // false — wrong width
+ * isVector([0.1, NaN]);             // false — not finite
+ * isVector(new Uint8Array(4));      // false — bytes are not a vector; unpack them first
+ */
+export function isVector(v, dims) {
+  if (!(Array.isArray(v) || v instanceof Float32Array || v instanceof Float64Array))
+    return false;
+  const n = v.length;
+  if (n === 0 || (dims !== undefined && n !== dims))
+    return false;
+  for (let i = 0; i < n; i++) {
+    if (!Number.isFinite(v[i]))
+      return false;
+  }
+  return true;
+}
+
+/**
+ * The dot product. Unbounded; equal to the cosine for unit vectors, so
+ * a sweep over l2-normalized vectors can take this cheaper form.
+ * @param {Vector | null | undefined} a
+ * @param {Vector | null | undefined} b
+ * @returns {number} the product — or 0 for a malformed pair (mismatched
+ *   lengths, empty, null, or a result that is not finite)
+ */
+export function dotProduct(a, b) {
+  if (a == null || b == null)
+    return 0;
+  const n = a.length;
+  if (n === 0 || n !== b.length)
+    return 0;
+  let sum = 0;
+  for (let i = 0; i < n; i++)
+    sum += a[i] * b[i];
+  return Number.isFinite(sum) ? sum : 0;
+}
+
+/**
+ * Cosine similarity, in [-1, 1]: 1 for the same direction, 0 for
+ * orthogonal, -1 for opposite. The one metric the suite ranks by —
+ * scale-free, so vectors from a model that does not normalize compare
+ * the same as vectors from one that does.
+ * @param {Vector | null | undefined} a
+ * @param {Vector | null | undefined} b
+ * @returns {number} the similarity — or 0 for a malformed pair, and 0
+ *   when either vector has no direction (all zeros)
+ * @example
+ * cosineSimilarity([1, 0], [1, 0]);   // 1
+ * cosineSimilarity([1, 0], [0, 1]);   // 0
+ * cosineSimilarity([1, 0], [-2, 0]);  // -1
+ * cosineSimilarity([1, 0], [1]);      // 0 — mismatched, never a throw
+ */
+export function cosineSimilarity(a, b) {
+  if (a == null || b == null)
+    return 0;
+  const n = a.length;
+  if (n === 0 || n !== b.length)
+    return 0;
+  let dot = 0;
+  let na = 0;
+  let nb = 0;
+  for (let i = 0; i < n; i++) {
+    const x = a[i];
+    const y = b[i];
+    dot += x * y;
+    na += x * x;
+    nb += y * y;
+  }
+  // the two roots separately: their product can overflow where neither does
+  const denominator = Math.sqrt(na) * Math.sqrt(nb);
+  if (!(denominator > 0) || !Number.isFinite(denominator) || !Number.isFinite(dot))
+    return 0;
+  const r = dot / denominator;
+  // rounding can land a hair outside the interval; the contract is [-1, 1]
+  return r > 1 ? 1 : r < -1 ? -1 : r;
+}
+
+/**
+ * Euclidean similarity, `1 / (1 + distance)`, in (0, 1]: 1 for equal
+ * vectors, falling towards 0 as they move apart. The distance turned
+ * into the same higher-is-better direction as the other kernels, so a
+ * caller never has to remember which way a metric sorts.
+ * @param {Vector | null | undefined} a
+ * @param {Vector | null | undefined} b
+ * @returns {number} the similarity — or 0 for a malformed pair
+ */
+export function euclideanSimilarity(a, b) {
+  if (a == null || b == null)
+    return 0;
+  const n = a.length;
+  if (n === 0 || n !== b.length)
+    return 0;
+  let sum = 0;
+  for (let i = 0; i < n; i++) {
+    const d = a[i] - b[i];
+    sum += d * d;
+  }
+  return Number.isFinite(sum) ? 1 / (1 + Math.sqrt(sum)) : 0;
+}
+
+/**
+ * The unit vector in `a`'s direction, as a new `Float32Array` — the
+ * form the packed column stores, so that cosine, dot and Euclidean
+ * then agree in rank. The input is never modified.
+ * @param {Vector | null | undefined} a
+ * @returns {Float32Array | null} the normalized copy; the zero vector
+ *   stays zero (it has no direction, and scores 0 against everything);
+ *   null for anything `isVector` refuses, or a norm that overflows
+ */
+export function l2Normalize(a) {
+  if (!isVector(a))
+    return null;
+  const n = a.length;
+  let sum = 0;
+  for (let i = 0; i < n; i++)
+    sum += a[i] * a[i];
+  if (!Number.isFinite(sum))
+    return null;
+  const out = new Float32Array(n);
+  if (sum === 0)
+    return out;
+  const norm = Math.sqrt(sum);
+  for (let i = 0; i < n; i++)
+    out[i] = a[i] / norm;
+  return out;
+}
+
+/**
+ * The packed form: `4·d` bytes of little-endian binary32, the value a
+ * database column stores. Components round to their nearest binary32
+ * (`Math.fround`); `unpackVector` returns exactly those.
+ *
+ * A component too large for binary32 has no nearest one — it rounds to
+ * an infinity — so such a vector is REFUSED rather than stored as bytes
+ * that unpack into something `isVector` would reject. Normalized
+ * vectors, which is what a column holds, can never meet it.
+ * @param {Vector | null | undefined} a
+ * @returns {Uint8Array | null} the bytes — null for anything `isVector`
+ *   refuses (empty, non-finite) and for a component that overflows
+ *   binary32, never a partial or zero-filled record
+ * @example
+ * packVector([1]);                 // Uint8Array [0, 0, 128, 63]
+ * packVector([1, NaN]);            // null
+ * packVector([1e39]);              // null — no finite binary32 is nearest
+ */
+export function packVector(a) {
+  if (!isVector(a))
+    return null;
+  const n = a.length;
+  const bytes = new Uint8Array(n * 4);
+  if (LITTLE_ENDIAN) {
+    // a fresh buffer is aligned, and the host's byte order is the packed
+    // one — so the rounded components are readable back through the view
+    const floats = new Float32Array(bytes.buffer);
+    floats.set(a);
+    for (let i = 0; i < n; i++) {
+      if (!Number.isFinite(floats[i]))
+        return null;
+    }
+  }
+  else {
+    const view = new DataView(bytes.buffer);
+    for (let i = 0; i < n; i++) {
+      const rounded = Math.fround(a[i]);
+      if (!Number.isFinite(rounded))
+        return null;
+      view.setFloat32(i * 4, rounded, true);
+    }
+  }
+  return bytes;
+}
+
+/**
+ * The vector packed in `bytes`, read as `dims` little-endian binary32
+ * components. The width is the caller's to state — a column declares
+ * it — and bytes of any other length are refused rather than partially
+ * read.
+ *
+ * On a little-endian host, 4-byte-aligned bytes come back as a VIEW over
+ * the same buffer — no copy, which is what a sweep over ten thousand
+ * fetched rows is paid for by; writing into the result writes into the
+ * bytes. Misaligned bytes (a pooled `Buffer`, a slice at an odd offset)
+ * and big-endian hosts take the copy path and answer the same values.
+ * @param {Uint8Array | null | undefined} bytes
+ * @param {number} dims - the width the bytes must hold
+ * @returns {Float32Array | null} the vector — null when `bytes` is not a
+ *   `Uint8Array` of exactly `4·dims` bytes
+ */
+export function unpackVector(bytes, dims) {
+  if (!(bytes instanceof Uint8Array) || !Number.isInteger(dims) || dims < 1
+    || bytes.byteLength !== dims * 4)
+    return null;
+  if (LITTLE_ENDIAN && bytes.byteOffset % 4 === 0)
+    return new Float32Array(bytes.buffer, bytes.byteOffset, dims);
+  const out = new Float32Array(dims);
+  const view = new DataView(bytes.buffer, bytes.byteOffset, bytes.byteLength);
+  for (let i = 0; i < dims; i++)
+    out[i] = view.getFloat32(i * 4, true);
+  return out;
+}
+
+//#endregion