@jarenjs/json 0.43.3 → 0.46.4

package/ARCHITECTURE.md

@@ -163,7 +163,7 @@ Grouping, `$distinct` and the `$orderby` machinery need a total, deterministic e
 
 ### The operator registry
 
-All 98 §8 operators live in one table in `operators.js` — the query-language analogue of `path.js`'s `FUNCTIONS` table. A test derives the count from the registry and asserts it against QUERY-FORMAT §8 *and* against every committed document that states a number — this file, the README twice, `site.md` and `@jarenjs/linq`'s architecture — so an operator cannot be added without moving all of them in the same change:
+All 99 §8 operators live in one table in `operators.js` — the query-language analogue of `path.js`'s `FUNCTIONS` table. A test derives the count from the registry and asserts it against QUERY-FORMAT §8 *and* against every committed document that states a number — this file, the README twice, `site.md` and `@jarenjs/linq`'s architecture — so an operator cannot be added without moving all of them in the same change:
 
 ```javascript
 '$substring': {

package/README.md

@@ -386,9 +386,9 @@ queryJson({
 }, [1, 2, 3, 4, 5]); // [2, 3, 4] — a 3-point moving average
 ```
 
-The operator library (98 operators: comparisons, IEEE-double arithmetic, logic, strings with I-Regexp `$match`/`$search`/`$replace`, aggregates, sequence tools like `$distinct`/`$subsequence`/`$range`, type predicates and casts, `$coalesce`, the RFC 3339 date family, and the spatial family) is cataloged in [QUERY-FORMAT.md §8](./docs/QUERY-FORMAT.md#8-operators).
+The operator library (99 operators: comparisons, IEEE-double arithmetic, logic, strings with I-Regexp `$match`/`$search`/`$replace`, aggregates, sequence tools like `$distinct`/`$subsequence`/`$range`, type predicates and casts, `$coalesce`, the RFC 3339 date family, the spatial family and `$similarity`) is cataloged in [QUERY-FORMAT.md §8](./docs/QUERY-FORMAT.md#8-operators).
 
-**Extending the vocabulary (host opt-in).** The 98 are closed, but a host can add more the way `@jarenjs/validate` gains formats from `@jarenjs/formats`: `createJsltRegistry().use(mathPack).use(financePack)` composes packs of pure `@jarenjs/core` functions into a compiler, so `{ "$sqrt": "$.variance" }` and `{ "$npv": ["$.rate", "$.cashflows[*]"] }` work in a stylesheet, a bare query, and `@jarenjs/linq` — while a document compiled *without* the registry still rejects them. Aggregators fold a `seq` operand to an array before the pure call. See [JSLT-FORMAT.md §13](./docs/JSLT-FORMAT.md#13-registered-operators-host-opt-in-non-normative).
+**Extending the vocabulary (host opt-in).** The 99 are closed, but a host can add more the way `@jarenjs/validate` gains formats from `@jarenjs/formats`: `createJsltRegistry().use(mathPack).use(financePack)` composes packs of pure `@jarenjs/core` functions into a compiler, so `{ "$sqrt": "$.variance" }` and `{ "$npv": ["$.rate", "$.cashflows[*]"] }` work in a stylesheet, a bare query, and `@jarenjs/linq` — while a document compiled *without* the registry still rejects them. Aggregators fold a `seq` operand to an array before the pure call. See [JSLT-FORMAT.md §13](./docs/JSLT-FORMAT.md#13-registered-operators-host-opt-in-non-normative).
 
 **Dates are RFC 3339 strings** ([§8.13](./docs/QUERY-FORMAT.md#813-dates-and-times)): `$is-date`/`$is-time`/`$is-datetime`/`$is-duration` test the lexical forms, `$year`…`$seconds` and `$offset` read components *lexically, in the value's own offset* (so "group by month" means what you expect), `$week`/`$week-year`/`$quarter`/`$weekday` add the derived calendar fields, and `$epoch`/`$datetime` convert to and from epoch milliseconds — the one place a value is shifted to UTC, and therefore the way to compare instants across offsets. There is deliberately no `current-dateTime`: a compiled query is cached by document identity and saved as a rule, so it must answer the same for the same input forever.
 
@@ -406,7 +406,7 @@ queryJson({
 
 Bucketing by week is the shape components alone cannot express, because a week boundary is arithmetic rather than a field. Patterns stay locale-independent — `MMMM` and `EEEE` are rejected rather than silently rendered in English — because localized text belongs to the presentation layer, not to a query.
 
-**Geography is GeoJSON** ([§8.14](./docs/QUERY-FORMAT.md#814-spatial)), for the same reason dates are RFC 3339 strings: it is what the document already holds. Operands are a bare `[longitude, latitude]` position, a geometry, a `Feature` or a `FeatureCollection`, and wrappers unwrap for you. `$distance`, `$area` and `$length` answer in metres on the WGS 84 sphere — never planar, because a Euclidean answer over raw degrees is wrong by two thirds over a kilometre at Dutch latitudes. `$within` tests containment, `$bbox`/`$centroid` measure, and `$bbox-intersects` is named for exactly what it tests, since an `$intersects` that compared only boxes would be a lie the first time two L-shapes shared one.
+**Geography is GeoJSON** ([§8.14](./docs/QUERY-FORMAT.md#814-spatial)), for the same reason dates are RFC 3339 strings: it is what the document already holds. Thirteen of the 98 operators are spatial — eight measurements and predicates, five conversions — and JSLT and JTLT inherit every one. Operands are a bare `[longitude, latitude]` position, a geometry, a `Feature` or a `FeatureCollection`, and wrappers unwrap for you. `$distance`, `$area` and `$length` answer in metres on the WGS 84 sphere — never planar, because a Euclidean answer over raw degrees is wrong by two thirds over a kilometre at Dutch latitudes. `$within` tests containment, `$bbox`/`$centroid` measure, and `$bbox-intersects` is named for exactly what it tests, since an `$intersects` that compared only boxes would be a lie the first time two L-shapes shared one.
 
 ```js
 queryJson({
@@ -442,6 +442,45 @@ The one trap: `coordinates` and `features` take the **array constructor** (the b
 
 A geohash is a string, so **bucketing and tiling** need no operator: `$groupby` over `$substring` groups by cell and an index over the hash is a spatial index. **Proximity is different**, and a prefix test is not it — two points ten metres apart can differ in the *first* character of their cell, so a single prefix misses a neighbour at every cell boundary. `$geohash-neighbours` gives the nine-cell probe a correct proximity query needs; narrow it with `$distance` when an exact radius matters. The whole recipe, end to end, is in [HOWTO](../../docs/HOWTO.md#getting-geographic-data-in-and-out).
 
+### Similarity, and why there is no `$knn`
+
+An embedding is an array of numbers, which a JSON document can already hold, so
+the language needs exactly one operator to compare two of them
+([§8.15](./docs/QUERY-FORMAT.md#815-vectors)):
+
+```javascript
+queryJson({ $similarity: [[3, 4], [4, 3]] }, {}); // 0.96
+```
+
+`$similarity` is cosine, in [-1, 1], higher-is-better. One metric, because a
+stored vector is normally normalized and cosine, the dot product and Euclidean
+distance then rank the same candidates in the same order — a second metric
+would buy a different number for the same answer. An operand that is not an
+array of numbers is `JQ2001`; two vectors that cannot be compared — different
+widths, empty, or carrying a component a computation made non-finite — answer
+**empty**, so a document never carries a score nobody computed. Nothing is
+padded or truncated to make a comparison possible.
+
+"The k most similar" needs no keyword either: it is an ordering and a window,
+and both already exist.
+
+```javascript
+queryJson({ $subsequence: [{
+  $for: { m: '$.memories[*]' },
+  $orderby: [
+    { $key: { $similarity: ['$m.embedding', '$query'] }, $dir: 'desc', $empty: 'least' },
+    '$m.id',
+  ],
+  $return: '$m.text',
+}, 0, 10] }, data, { query: vector });
+```
+
+`$empty: 'least'` under a descending sort puts the rows with no vector **last**
+— present in the input, never in the top k, never scored — and the second key
+breaks ties by identity, so the same document answers with the same rows every
+time it runs. `@jarenjs/linq` spells the whole chain fluently as
+`.orderByDescending(m => m.embedding.similarity(q), { empty: 'least' }).take(10)`.
+
 ### External parameters
 
 A variable no phrase binds is an **external**: use is the declaration. The compiled query exposes the collected names and takes bindings at call time:
@@ -524,7 +563,7 @@ The validate step is not redundant: provider structured-output implementations s
 
 For those strict subsets each grammar also ships an **LLM profile** — [`jaren-query.llm-profile.schema.json`](./schemas/jaren-query.llm-profile.schema.json) and [`jaren-jslt.llm-profile.schema.json`](./schemas/jaren-jslt.llm-profile.schema.json) — a mechanically derived, pure *relaxation* of the canonical artifact: `patternProperties`, `propertyNames` and asserted `format`s are removed (each restated in the nearest `description`, which the model still reads) and every `oneOf` becomes `anyOf`. That last swap costs no precision: the canonical grammar discriminates its branches by member name — a map constructor has no `$`-prefixed key, every phrase pins its own (`$const`, `$map`, `$call`, `$return`, …) or draws its single key from a disjoint operator enum — so at most one branch can ever match a document, and exactly-one and at-least-one accept the same language. It is also *required* once the name constraints are gone: `oneOf` would then reject `{"$eq": [1, 2]}` for matching two now-overlapping branches. Every canonical-valid document validates under the profile; the reverse is deliberately not guaranteed, which is exactly why the local validate-then-compile step above stays mandatory. Hand the profile to the provider's constrained decoder, validate locally against the canonical schema. (`@jarenjs/ai`'s `createStructuredOutput` packages this handshake.)
 
-A relaxation, though, is not a *shrink*: restating every removed constraint in a `description` means the JSLT profile is 19,158 characters against the canonical 18,736, and on a small model an oversized `response_format` is the difference between a document and an empty reply. So the JSLT grammar also ships an **authoring profile** — [`jaren-jslt.authoring.schema.json`](./schemas/jaren-jslt.authoring.schema.json), **3,491 characters** — the same mechanical derivation with one more step: the `queryDocument` `$ref` that pulls the entire expression language into the document grammar is left *open*. What survives is the document shape (envelope, rules, match specs, modes); what leaves is the ~16 kB of phrase shapes. It is a pure widening of the canonical language, so nothing the engine can run becomes inexpressible, and it is deliberately weaker — a body of pure nonsense decodes under it. That is the trade, and it is only safe because the two authorities after the decoder are unchanged: validate against the canonical schema, then compile. The vocabulary the cut removes belongs in the prompt instead, where `@jarenjs/ai`'s `operatorCrib` puts it (operator names grouped by arity, ~1.1 kB, read off the query artifact). `@jarenjs/ai`'s [`createStylesheetAuthor`](../ai/README.md#when-the-grammar-is-too-big-to-decode-measured) packages the whole handshake.
+A relaxation, though, is not a *shrink*: restating every removed constraint in a `description` means the JSLT profile is 19,158 characters against the canonical 18,817, and on a small model an oversized `response_format` is the difference between a document and an empty reply. So the JSLT grammar also ships an **authoring profile** — [`jaren-jslt.authoring.schema.json`](./schemas/jaren-jslt.authoring.schema.json), **3,491 characters** — the same mechanical derivation with one more step: the `queryDocument` `$ref` that pulls the entire expression language into the document grammar is left *open*. What survives is the document shape (envelope, rules, match specs, modes); what leaves is the ~16 kB of phrase shapes. It is a pure widening of the canonical language, so nothing the engine can run becomes inexpressible, and it is deliberately weaker — a body of pure nonsense decodes under it. That is the trade, and it is only safe because the two authorities after the decoder are unchanged: validate against the canonical schema, then compile. The vocabulary the cut removes belongs in the prompt instead, where `@jarenjs/ai`'s `operatorCrib` puts it (operator names grouped by arity, ~1.1 kB, read off the query artifact). `@jarenjs/ai`'s [`createStylesheetAuthor`](../ai/README.md#when-the-grammar-is-too-big-to-decode-measured) packages the whole handshake.
 
 Query documents are plain JSON, so they travel through the rest of an LLM toolchain as-is: function-call arguments, retrieval filters, audit logs, replay.
 

package/dist/types/query/operators.d.ts

@@ -573,6 +573,14 @@ export declare const OPERATORS: Readonly<{
         result: typeof resultEmptyPropagates;
         compile: (gets: any, args: any) => (f: any) => any;
     };
+    $similarity: {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof RESULT_OPT;
+        compile: (gets: any, args: any) => (f: any) => number | typeof EMPTY;
+    };
     '$date-add': {
         params: Readonly<{
             kinds: readonly string[];

package/docs/QUERY-FORMAT.md

@@ -1385,6 +1385,13 @@ value. This matters wherever such an expression sits in a position that expects
 one item: `[{"$bbox": expr}]` builds an empty array rather than a one-item one,
 and `{"m": {"$bbox": expr}}` omits the member entirely.
 
+**Traversal is not validation.** `$within`, `$area` and `$length` walk the
+rings they are given and treat a ring as closed whether or not its last
+position repeats its first — the reading every implementation makes — so a
+ring `isValidGeoJson` (or the meta-schema) refuses still measures. A document
+that needs the judgment composes it: `$valid` against the GeoJSON meta-schema,
+or the `geojson` format, before the measurement, not inside it.
+
 **Boxes do not cross the antimeridian.** RFC 7946 §3.1.9 tells producers to cut
 geometries at ±180° rather than let them span it, and this format follows that
 rather than re-joining what a producer split: `$bbox` of an uncut geometry whose
@@ -1428,6 +1435,96 @@ the answer.
 selects the cities inside a region and orders them by how far they are from a
 point — a spatial filter and a spatial sort, in the language's own clauses.
 
+### 8.15 Vectors
+
+A vector is an **array of numbers** — what a JSON document already holds when
+something has been embedded. There is no vector type to construct, no width to
+declare, and nothing to register: `[0.1, 0.2, 0.3]` is one.
+
+| Operator | Definition |
+|---|---|
+| `$similarity` | `[a, b]` → the cosine similarity of two vectors, a number in [-1, 1]; two vectors that cannot be compared → empty |
+
+Cosine is the only metric, and that is a decision rather than a first
+instalment. For vectors of unit length — the form an embedding is normally
+stored in — cosine, the dot product and Euclidean distance all rank the same
+candidates in the same order, so a second metric would buy a different *number*
+for the same *answer* while doubling every recipe below. **Higher is better**:
+`1` is the same direction, `0` unrelated, `-1` opposite, which is why a
+similarity sort is always descending.
+
+**The operand split is §8.14's.** A value that is not an array of numbers has
+no similarity to anything — a string, an object, an array with a non-number in
+it — and is `JQ2001`, the same type-level refusal a non-geographic operand
+gets. Two operands that *are* arrays of numbers but cannot be compared —
+different widths, an empty array, or a component a computation made non-finite
+— answer the **empty sequence**, the same data-level answer a measurement with
+no bounded position gives. Nothing is padded, truncated or zero-filled to make
+a comparison possible: two vectors of different widths are not a near miss,
+they are unrelated.
+
+One degenerate pair is a **score, not a refusal**: a vector of all zeros
+points nowhere, and it answers `0` against everything, including itself. That
+is the one number here not derived from a direction, and it is the truthful
+answer to "how aligned are these" when one of them has no alignment — an
+all-zero embedding sorts below every real one and above the rows that have no
+vector at all, which is exactly where it belongs.
+
+Because of that rule `$similarity` is **optional-valued**: it can answer empty
+for two operands that are present, so `[{"$similarity": [a, b]}]` builds an
+empty array rather than a one-item one and `{"score": {"$similarity": [a, b]}}`
+omits the member entirely. That is the answer to want — a document that carries
+no score is honest, and one carrying `0` for a comparison that never happened
+is not, because `0` is a real similarity.
+
+**Nearest-neighbours is a composition, not an operator.** "The k most similar"
+is an ordering and a window, and this format already spells both: `$orderby` on
+a `$similarity` key, descending, then `$subsequence`.
+
+```json
+{ "$for": { "m": "$.memories[*]" },
+  "$orderby": [ { "$key": { "$similarity": ["$m.embedding", "$query"] },
+                  "$dir": "desc", "$empty": "least" } ],
+  "$return": "$m.text" }
+```
+
+```json
+{ "$subsequence": [ { "$for": { "m": "$.memories[*]" },
+                      "$orderby": [ { "$key": { "$similarity": ["$m.embedding", "$query"] },
+                                      "$dir": "desc", "$empty": "least" },
+                                    "$m.id" ],
+                      "$return": "$m" },
+                    0, 10 ] }
+```
+
+The first orders every memory by how close it is to an external `$query`
+vector; the second wraps that ordering in a window and takes the first ten of
+it, which is the whole of "k nearest". The window goes **outside** the phrase,
+because `$subsequence` inside `$return` would trim each tuple's own result
+rather than the stream of tuples.
+
+Two details in the second document are load-bearing. `"$empty": "least"` places
+an empty key **last** under `"desc"` (§6.6), which is where a row with no
+vector, or with one of the wrong width, belongs: present in the input, never in
+the top k, and never scored. And the second key, `"$m.id"`, breaks ties by row
+identity — the sort is stable, but stability is only about the *input* order,
+and two candidates at an identical similarity are exactly what a corpus of
+near-duplicates produces. An explicit tie-break is what makes the same document
+answer with the same rows every time it runs.
+
+A filter is the same key in a `$where`, and it composes with the ordering:
+
+```json
+{ "$for": { "m": "$.memories[*]" },
+  "$where": { "$gt": [{ "$similarity": ["$m.embedding", "$query"] }, 0.8] },
+  "$return": "$m.text" }
+```
+
+— everything closer than a threshold, in the language's own clauses. Note that
+`$gt` over an empty key answers `false`, so an unvectored row drops out of a
+threshold filter for free.
+
+
 ## 9. Variables, scoping, and external parameters
 
 1. Variables are introduced by `$for`, `$let`, `$at`, `$count`, `$groupby`

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/json",
   "private": false,
-  "version": "0.43.3",
+  "version": "0.46.4",
   "type": "module",
   "main": "./src/index.js",
   "types": "./dist/types/index.d.ts",
@@ -90,6 +90,6 @@
     "prepack": "npm run build:types"
   },
   "dependencies": {
-    "@jarenjs/core": "^0.43.3"
+    "@jarenjs/core": "^0.46.4"
   }
 }

package/schemas/jaren-jslt.draft-07.schema.json

@@ -621,7 +621,11 @@
           "$bbox",
           "$area",
           "$length",
-          "$centroid"
+          "$centroid",
+          "$geo-parse",
+          "$geo-text",
+          "$geohash-bounds",
+          "$geohash-neighbours"
         ]
       },
       "additionalProperties": {
@@ -661,6 +665,8 @@
           "$distance",
           "$within",
           "$bbox-intersects",
+          "$geo-simplify",
+          "$similarity",
           "$default"
         ]
       },

package/schemas/jaren-jslt.schema.json

@@ -621,7 +621,11 @@
           "$bbox",
           "$area",
           "$length",
-          "$centroid"
+          "$centroid",
+          "$geo-parse",
+          "$geo-text",
+          "$geohash-bounds",
+          "$geohash-neighbours"
         ]
       },
       "additionalProperties": {
@@ -661,6 +665,8 @@
           "$distance",
           "$within",
           "$bbox-intersects",
+          "$geo-simplify",
+          "$similarity",
           "$default"
         ]
       },

package/schemas/jaren-query.draft-07.schema.json

@@ -530,7 +530,11 @@
           "$bbox",
           "$area",
           "$length",
-          "$centroid"
+          "$centroid",
+          "$geo-parse",
+          "$geo-text",
+          "$geohash-bounds",
+          "$geohash-neighbours"
         ]
       },
       "additionalProperties": {
@@ -570,6 +574,8 @@
           "$distance",
           "$within",
           "$bbox-intersects",
+          "$geo-simplify",
+          "$similarity",
           "$default"
         ]
       },

package/schemas/jaren-query.schema.json

@@ -289,7 +289,8 @@
           "$year", "$month", "$day", "$hours", "$minutes", "$seconds",
           "$offset", "$epoch", "$datetime",
           "$week", "$week-year", "$quarter", "$weekday",
-          "$bbox", "$area", "$length", "$centroid"
+          "$bbox", "$area", "$length", "$centroid",
+          "$geo-parse", "$geo-text", "$geohash-bounds", "$geohash-neighbours"
         ]
       },
       "additionalProperties": { "$ref": "#/$defs/expression" }
@@ -306,7 +307,8 @@
           "$contains", "$starts-with", "$ends-with", "$match", "$search",
           "$index-of", "$range", "$get",
           "$start-of", "$end-of", "$date-format",
-          "$distance", "$within", "$bbox-intersects", "$default"
+          "$distance", "$within", "$bbox-intersects", "$geo-simplify",
+          "$similarity", "$default"
         ]
       },
       "additionalProperties": {

package/src/query/normalize.js

@@ -417,6 +417,22 @@ const OPERATOR_ALIASES = {
   $project: "the renderer — the language cannot make a projected coordinate at all, so a measurement can never land on one; measurement here is geodesic",
   "$geo-project": "the renderer, as for '$project'",
   $srid: null, $transform: null,
+  // vectors: the spellings a writer reaches for from a ranking library.
+  // The metric names all point at the one operator because the packed
+  // form is normalized and they then rank identically; `$knn` and its
+  // synonyms get the composition, because ordering and windowing are
+  // clauses this language already has and a second spelling of them
+  // would be the drift, not the convenience
+  $cosine: "$similarity", "$cosine-similarity": "$similarity",
+  "$cos-sim": "$similarity", "$dot-product": "$similarity",
+  $dot: "$similarity", "$inner-product": "$similarity",
+  "$vector-distance": "$similarity (higher is closer; there is no distance metric)",
+  "$l2-distance": "$similarity (higher is closer; there is no distance metric)",
+  $knn: "$orderby on a $similarity key with $dir 'desc', then $subsequence for the k",
+  $nearest: "$orderby on a $similarity key with $dir 'desc', then $subsequence for the k",
+  "$nearest-neighbours": "$orderby on a $similarity key, then $subsequence",
+  "$nearest-neighbors": "$orderby on a $similarity key, then $subsequence",
+  "$top-k": "$orderby then $subsequence", $embed: null, $normalize: null,
 };
 
 // JQ0002 for an unknown $-key, with a "did you mean" suggestion. A

package/src/query/operators.js

@@ -56,6 +56,7 @@ import {
   fixedUnitMs,
   compileDateFormat,
 } from '@jarenjs/core/dates';
+import { isVector, cosineSimilarity } from '@jarenjs/core/vector';
 import {
   isPosition,
   bboxOf,
@@ -840,6 +841,41 @@ function geoUnaryEntry(measure, check = geoArg) {
 
 //#endregion
 
+//#region vector operators (section 8.15)
+// One operator, one metric. A vector here is what a JSON document can
+// hold — an array of numbers — and the arithmetic lives once, in
+// `@jarenjs/core/vector`, where the ledger and the store read it too.
+//
+// The kernel and the language answer a malformed comparison
+// differently, on purpose. A kernel scores 0 so that one bad vector
+// among ten thousand loses a ranking sweep instead of killing it; the
+// language answers the empty sequence, the same thing §8.14 answers for
+// a measurement it cannot make, so a document never carries a score
+// that was never computed. The gate between the two is `isVector`, the
+// one shape guard the suite shares.
+
+// A vector operand, split the way §8.14 splits geography: a value that
+// is not an array of numbers is the wrong TYPE and raises, while an
+// array of numbers that cannot be compared — empty, or carrying a
+// component a computation made non-finite — is a DATA-level answer of
+// empty, decided by the caller against the other operand's width.
+function vectorArg(v, docPath) {
+  if (!Array.isArray(v)) {
+    throw runtimeError('JQ2001',
+      `expected a vector (an array of numbers), got ${describeItem(v)}`, docPath);
+  }
+  for (let i = 0; i < v.length; i++) {
+    if (typeof v[i] !== 'number') {
+      throw runtimeError('JQ2001',
+        `expected a vector (an array of numbers), got ${describeItem(v[i])} at index ${i}`,
+        docPath);
+    }
+  }
+  return v;
+}
+
+//#endregion
+
 // the RFC 3339 type tests, shaped like the section 8.10 $is-* family:
 // one item of the right lexical form, never an error
 function dateTestEntry(test) {
@@ -1748,6 +1784,39 @@ export const OPERATORS = Object.freeze({
 
   //#endregion
 
+  //#region section 8.15 - vectors
+
+  '$similarity': { // cosine similarity of two vectors, higher-is-better
+    params: ARGS_2,
+    // OPTIONAL: two present operands can still have no comparison — a
+    // width mismatch, an empty vector, a component a computation made
+    // non-finite. Declaring exactly-one would let the internal empty
+    // marker escape into an array or object constructor.
+    result: RESULT_OPT,
+    compile: (gets, args) => {
+      const aGet = gets[0];
+      const aPath = args[0].docPath;
+      const bGet = gets[1];
+      const bPath = args[1].docPath;
+      return (f) => {
+        const a = aGet(f);
+        const b = bGet(f);
+        if (a === EMPTY || b === EMPTY)
+          return EMPTY;
+        const va = vectorArg(a, aPath);
+        const vb = vectorArg(b, bPath);
+        // the width is the second operand's obligation, so the same
+        // guard answers both "is this comparable at all" and "is it
+        // comparable to THAT" — nothing here pads or truncates
+        if (!isVector(va) || !isVector(vb, va.length))
+          return EMPTY;
+        return cosineSimilarity(va, vb);
+      };
+    },
+  },
+
+  //#endregion
+
   //#region section 8.13 - dates and times, continued
 
   '$date-add': dateShiftEntry(1),