@jarenjs/json 0.34.2 → 0.43.1

package/ARCHITECTURE.md

@@ -163,7 +163,7 @@ Grouping, `$distinct` and the `$orderby` machinery need a total, deterministic e
 
 ### The operator registry
 
-All 93 §8 operators live in one table in `operators.js` — the query-language analogue of `path.js`'s `FUNCTIONS` table (the count is cross-checked against QUERY-FORMAT §8 by a test, so it cannot go stale again):
+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:
 
 ```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 (93 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 (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).
 
-**Extending the vocabulary (host opt-in).** The 93 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 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).
 
 **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.
 
@@ -417,7 +417,30 @@ queryJson({
 }, data); // a spatial filter and a spatial sort, in the language's own clauses
 ```
 
-A geohash needs no operator of its own to be useful: it is a string, so proximity is `$starts-with` on a prefix and spatial bucketing is `$groupby` over `$substring`. `$geohash` only produces it.
+**Geography goes in and out as the text the world already speaks.** `$geo-parse` reads Well-Known Text — what PostGIS, SpatiaLite, GEOS, JTS and every `ST_AsText` emit — and `$geo-text` writes it back, so a WKT column becomes measurable in one expression and a result leaves as something a spatial database reads. `$geohash-bounds` turns a cell string back into the `Polygon` it covers, and `$geo-simplify` reduces a value **for storage and transport**: the same structure and properties with fewer positions, rings still closed, so it can be kept or sent as-is.
+
+Getting a CSV of coordinates in needs **no code and no operator** — it is a stylesheet. `parseCsv(text, { headers: true, typed: true })` then one rule:
+
+```js
+compileJsltStylesheet([{
+  match: '$',
+  body: {
+    type: 'FeatureCollection',
+    features: [{
+      $for: { r: '$[*]' },
+      $return: {
+        type: 'Feature',
+        geometry: { type: 'Point', coordinates: ['$r.lon', '$r.lat'] },
+        properties: { name: '$r.name', pop: '$r.pop' },
+      },
+    }],
+  },
+}]);
+```
+
+The one trap: `coordinates` and `features` take the **array constructor** (the brackets, §3.4), never `$seq` — a two-item *sequence* in member position is `JQ2001`, because a sequence is not an array.
+
+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).
 
 ### External parameters
 

package/dist/types/canonical.d.ts

@@ -35,3 +35,19 @@ export declare class JsonCanonicalizeError extends TypeError {
  * canonicalizeJson(1e21); // '1e+21'
  */
 export declare function canonicalizeJson(value: any): string;
+/**
+ * The lowercase hex SHA-256 over the RFC 8785 canonical UTF-8 bytes of a
+ * JSON value — the content identity two independent processes agree on
+ * (a document revision, an idempotency request hash), which is why it is
+ * SHA-256 over the canonical text and never a 32-bit fingerprint that
+ * collides. Asynchronous because it rides the platform's
+ * `globalThis.crypto.subtle` (Node ≥ 20, Bun, browsers, workers); the
+ * canonicalization itself is synchronous and its refusals
+ * (`JsonCanonicalizeError`) surface as the rejection.
+ *
+ * @param {any} value - The JSON value to identify
+ * @returns {Promise<string>} 64 lowercase hex characters
+ * @example
+ * await canonicalSha256({ b: 1, a: 2 }) === await canonicalSha256({ a: 2, b: 1 }); // true
+ */
+export declare function canonicalSha256(value: any): Promise<string>;

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

@@ -495,22 +495,22 @@ export declare const OPERATORS: Readonly<{
     };
     $bbox: {
         params: string;
-        result: typeof resultEmptyPropagates;
+        result: typeof RESULT_OPT;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $area: {
         params: string;
-        result: typeof resultEmptyPropagates;
+        result: typeof RESULT_OPT;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $length: {
         params: string;
-        result: typeof resultEmptyPropagates;
+        result: typeof RESULT_OPT;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $centroid: {
         params: string;
-        result: typeof resultEmptyPropagates;
+        result: typeof RESULT_OPT;
         compile: (gets: any, args: any) => (f: any) => any;
     };
     $distance: {
@@ -542,9 +542,37 @@ export declare const OPERATORS: Readonly<{
             kinds: readonly string[];
             min: 1;
         }>;
-        result: typeof resultEmptyPropagates;
+        result: typeof RESULT_OPT;
         compile: (gets: any, args: any) => (f: any) => string | typeof EMPTY;
     };
+    '$geo-parse': {
+        params: string;
+        result: typeof RESULT_OPT;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    '$geo-text': {
+        params: string;
+        result: typeof RESULT_OPT;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    '$geohash-bounds': {
+        params: string;
+        result: typeof RESULT_OPT;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    '$geohash-neighbours': {
+        params: string;
+        result: typeof RESULT_MANY;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
+    '$geo-simplify': {
+        params: Readonly<{
+            kinds: readonly string[];
+            min: 2;
+        }>;
+        result: typeof resultEmptyPropagates;
+        compile: (gets: any, args: any) => (f: any) => any;
+    };
     '$date-add': {
         params: Readonly<{
             kinds: readonly string[];

package/docs/QUERY-FORMAT.md

@@ -211,7 +211,7 @@ evaluation, use `$const` (§3.5.1); to bind one without iteration, use `$let`
 
 #### 3.5.1 `$const` — quote
 
-```json
+```jsonc
 { "$const": v }
 ```
 
@@ -227,7 +227,7 @@ constructs `{ "template": { "$for": "kept verbatim", "price": null }, "label": "
 
 #### 3.5.2 `$map` — general map constructor
 
-```json
+```jsonc
 { "$map": [[keyExpr, valueExpr], ...] }
 ```
 
@@ -270,7 +270,7 @@ A query document is either:
    bare scalar; or
 2. the **version envelope** phrase:
 
-   ```json
+   ```jsonc
    { "$query": "0.1", "$expr": <expression> }
    ```
 
@@ -409,7 +409,7 @@ clause (§6.9), in which case it evaluates to the final accumulator and
 
 ### 6.2 `$for` — iteration bindings
 
-```json
+```jsonc
 "$for": { name: source, ... }
 ```
 
@@ -438,7 +438,7 @@ may reference variables bound earlier in the same `$for` object.
 **Extended binding form** — a source written as an object with an `$in`
 member iterates `$in` like a plain source, with options:
 
-```json
+```jsonc
 { "$in": expr, "$at": "posName" }
 ```
 
@@ -456,7 +456,7 @@ the `$window` family — are §6.10.
 
 ### 6.3 `$let` — sequence bindings
 
-```json
+```jsonc
 "$let": { name: expr, ... }
 ```
 
@@ -474,7 +474,7 @@ ordinary shadowing and is allowed.
 
 ### 6.4 `$where` — tuple filter
 
-```json
+```jsonc
 "$where": expr
 ```
 
@@ -484,7 +484,7 @@ true. Cross-variable predicates (joins) belong here, not in path filters
 
 ### 6.5 `$groupby` — grouping
 
-```json
+```jsonc
 "$groupby": { name: keyExpr, ... }
 ```
 
@@ -522,7 +522,7 @@ that genre's books.
 
 ### 6.6 `$orderby` — ordering
 
-```json
+```jsonc
 "$orderby": keySpec
 "$orderby": [keySpec, ...]
 ```
@@ -530,7 +530,7 @@ that genre's books.
 A *keySpec* is either an expression (shorthand for ascending, empty-least) or
 the explicit form
 
-```json
+```jsonc
 { "$key": expr, "$dir": "asc" | "desc", "$empty": "least" | "greatest",
   "$collation": "name" }
 ```
@@ -573,7 +573,7 @@ saved rule declares the collations it needs.
 
 ### 6.7 `$count` — tuple numbering
 
-```json
+```jsonc
 "$count": "name"
 ```
 
@@ -589,7 +589,7 @@ one key.
 
 ### 6.8 `$as` — schema assertions on bindings
 
-```json
+```jsonc
 "$as": { name: schema, ... }
 ```
 
@@ -625,7 +625,7 @@ instead.
 
 ### 6.9 `$fold` — the accumulator clause
 
-```json
+```jsonc
 "$fold": { name: initExpr }
 ```
 
@@ -682,7 +682,7 @@ Two further options of the extended `$for` binding form (§6.2).
 would yield no tuple at all, the clause emits exactly **one** tuple with the
 variable bound to the **empty sequence**, so the enclosing tuple survives.
 
-```json
+```jsonc
 { "$in": expr, "$allowing-empty": true }
 ```
 
@@ -711,7 +711,7 @@ because an empty member value omits the member (§3.4).
 **Windows** iterate consecutive *runs* of the item stream instead of single
 items:
 
-```json
+```jsonc
 { "$in": expr, "$window": "tumbling" | "sliding", "$size": n, "$step": m, "$at": "w" }
 ```
 
@@ -745,7 +745,7 @@ two if the stream does not divide evenly.
 
 ## 7. Quantifier phrases
 
-```json
+```jsonc
 { "$some":  { name: expr, ... }, "$satisfies": expr }
 { "$every": { name: expr, ... }, "$satisfies": expr }
 ```
@@ -1339,10 +1339,83 @@ intersection is overlay work and is deliberately absent.
 | `$within` | `[a, b]` → is `a`'s representative position inside `b`'s surface? Only a polygon has an inside, so a line or point as `b` is `false` |
 | `$bbox-intersects` | `[a, b]` → do the two bounding boxes overlap? Touching edges count |
 | `$geohash` | `[value]` or `[value, precision]` → the base-32 cell string; precision is 1-12, default 9 |
+| `$geo-parse` | a Well-Known Text string → the geometry it denotes; text that is not well-formed WKT → empty. A non-string operand is `JQ2001` |
+| `$geo-text` | any value → its Well-Known Text string; a value with no WKT spelling → empty |
+| `$geohash-bounds` | a cell string → the `Polygon` covering that cell; a string outside the base-32 alphabet → empty |
+| `$geohash-neighbours` | a cell string → the cell and its neighbours as a sequence of up to nine strings, in reading order (north-west first, the cell itself in the middle); cells past a pole do not exist and are absent |
+| `$geo-simplify` | `[value, tolerance]` → the same value with vertices dropped. The tolerance is in **degrees**, not metres |
+
+**Conversion is how geography gets in and out.** Well-Known Text is what
+PostGIS, SpatiaLite, GEOS, JTS and every `ST_AsText` emit, so `$geo-parse` and
+`$geo-text` are the doors: a WKT column becomes a value the rest of §8.14
+measures, and any value goes back out as the text the database reads.
+`$geo-parse` answers a **geometry**, never a `Feature` — WKT carries no
+properties, and inventing an empty `properties` member would be a value the
+source never had.
+
+`$geo-simplify` is reduction **for storage and transport**: a 50 MB
+`FeatureCollection` a caller wants to keep, send or store smaller comes back as
+valid GeoJSON with the same structure and fewer positions. A renderer's
+simplification is a different job and is not this one — a chart simplifies into
+its own drawing space and hands back a picture, not a document. A ring stays
+closed and a line keeps both endpoints, so a value that was valid before is
+valid after. The tolerance is a planar vertex-dropping threshold in the
+coordinate's own units, which for GeoJSON is degrees; calling it metres would
+be exactly the planar-for-geodesic confusion the rule above exists to prevent.
+A negative or non-numeric tolerance is `JQ2001`.
+
+**A non-finite coordinate has no measurement.** `NaN` and `Infinity` are not
+JSON numbers, but a value that reached the engine through a computation can
+carry one, and every underlying formula launders it into something plausible —
+a great-circle distance from `NaN` comes back as the antipodal distance, and a
+`NaN` area compares false against zero and reports `0`. So a measurement over a
+value carrying a non-finite coordinate answers **empty** (`$bbox`, `$area`,
+`$length`, `$centroid`, `$distance`, `$geohash`), and a predicate answers
+**false** (`$within`, `$bbox-intersects`) — each the same answer it already
+gives for a missing operand. A value with no positions at all is a different
+thing and still measures: `$area` of an empty `FeatureCollection` is `0`.
+
+Because of that rule, **every measurement and every conversion in this section
+is optional-valued**: `$bbox`, `$area`, `$length`, `$centroid`, `$distance`,
+`$geohash`, `$geo-parse`, `$geo-text` and `$geohash-bounds` can answer the
+empty sequence for an operand that is present — a non-finite coordinate, text
+that is not well-formed WKT, a cell outside the base-32 alphabet. Only the two
+predicates answer exactly one item, because `false` is their missing-operand
+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.
+
+**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
+positions sit either side of the line returns a box spanning the globe the
+*wrong* way — `[-179, 0, 179, 0]` for two points four degrees apart. Cut the
+geometry at the antimeridian, as the RFC asks, and every box, containment test
+and index probe is right. There is no flag for this: a box that silently meant
+"the short way round" for some values and "the long way" for others is worse
+than one rule.
+
+Note what needs **no** operator — and one that does. A geohash is a string, so
+**bucketing and tiling** need nothing new: `$groupby` over `$substring` groups
+by cell, ordering by the hash orders by locality, and an index over it is a
+spatial index. **Proximity is different, and `$starts-with` on a prefix is not
+it.** Two points ten metres apart can differ in the *first* character of their
+cell, so a single-prefix test misses a neighbour at every cell boundary — which
+is to say, everywhere a customer actually looks. A correct proximity probe
+tests the neighbourhood: `$geohash-neighbours` of the query point's cell, then
+a membership test against those cells, then the exact `$distance` on what
+survives.
+
+```json
+{ "$let": { "cells": { "$geohash-neighbours": { "$geohash": ["$.here", 6] } } },
+  "$return": { "$for": { "c": "$.places[*]" },
+               "$where": { "$exists": { "$index-of": ["$cells", { "$geohash": ["$c.at", 6] }] } },
+               "$return": "$c.name" } }
+```
 
-Note what needs **no** operator. A geohash is a string, so proximity is
-`$starts-with` on a prefix and spatial bucketing is `$groupby` over
-`$substring` — the existing vocabulary already indexes, groups and orders them.
+— the nine-cell probe, in the language's own clauses. Narrow it with
+`$distance` when an exact radius matters; the cells are the cheap filter, not
+the answer.
 
 ```json
 { "$for": { "c": "$.cities[*]" },

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@jarenjs/json",
   "private": false,
-  "version": "0.34.2",
+  "version": "0.43.1",
   "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.34.2"
+    "@jarenjs/core": "^0.43.1"
   }
 }

package/src/canonical.js

@@ -167,4 +167,33 @@ export function canonicalizeJson(value) {
   return serializeValue(value, '', new Set());
 }
 
+const HEX = '0123456789abcdef';
+
+/**
+ * The lowercase hex SHA-256 over the RFC 8785 canonical UTF-8 bytes of a
+ * JSON value — the content identity two independent processes agree on
+ * (a document revision, an idempotency request hash), which is why it is
+ * SHA-256 over the canonical text and never a 32-bit fingerprint that
+ * collides. Asynchronous because it rides the platform's
+ * `globalThis.crypto.subtle` (Node ≥ 20, Bun, browsers, workers); the
+ * canonicalization itself is synchronous and its refusals
+ * (`JsonCanonicalizeError`) surface as the rejection.
+ *
+ * @param {any} value - The JSON value to identify
+ * @returns {Promise<string>} 64 lowercase hex characters
+ * @example
+ * await canonicalSha256({ b: 1, a: 2 }) === await canonicalSha256({ a: 2, b: 1 }); // true
+ */
+export async function canonicalSha256(value) {
+  const text = canonicalizeJson(value);
+  const digest = await globalThis.crypto.subtle.digest('SHA-256', new TextEncoder().encode(text));
+  const bytes = new Uint8Array(digest);
+  let out = '';
+  for (let i = 0; i < bytes.length; i++) {
+    const b = bytes[i];
+    out += HEX[b >> 4] + HEX[b & 15];
+  }
+  return out;
+}
+
 //#endregion

package/src/query/normalize.js

@@ -402,6 +402,21 @@ const OPERATOR_ALIASES = {
   // conditionals ($coalesce is a real operator; the guesses are here)
   $case: "$if", $cond: "$if", $switch: "$if", $ternary: "$if",
   $ifnull: "$default", $ifempty: "$default", $nvl: "$default",
+  // spatial: the PostGIS/Turf spellings, and the American plural
+  $wkt: "$geo-parse to read one, $geo-text to write one",
+  "$parse-wkt": "$geo-parse", "$from-wkt": "$geo-parse", $st_geomfromtext: "$geo-parse",
+  "$to-wkt": "$geo-text", $st_astext: "$geo-text", "$geo-stringify": "$geo-text",
+  "$geohash-decode": "$geohash-bounds", "$geohash-bbox": "$geohash-bounds",
+  "$geohash-neighbors": "$geohash-neighbours", "$geohash-adjacent": "$geohash-neighbours",
+  $simplify: "$geo-simplify", "$douglas-peucker": "$geo-simplify",
+  $intersects: "$bbox-intersects (boxes only — real overlay is deliberately absent)",
+  $buffer: null, $union: null, $difference: null,
+  // the one absence that needs its reason, not a pointer: a projected
+  // position is the same [x, y] array as a geographic one, so an
+  // operator making one could not stop it reaching $distance
+  $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,
 };
 
 // JQ0002 for an unknown $-key, with a "did you mean" suggestion. A

package/src/query/operators.js

@@ -60,12 +60,18 @@ import {
   isPosition,
   bboxOf,
   bboxIntersects,
+  bboxPolygon,
   geometryArea,
   geometryLength,
   centroidOf,
   containsPosition,
   geoDistance,
   geohashEncode,
+  geohashBounds,
+  geohashNeighbours,
+  wktToGeoJson,
+  geoJsonToWkt,
+  simplifyGeometry,
 } from '@jarenjs/core/geo';
 import { JsonQueryCompileError, JsonQueryRuntimeError } from './errors.js';
 import {
@@ -748,7 +754,17 @@ function dateTruncEntry(truncate) {
 // What is deliberately absent is real geometry-to-geometry intersection.
 // `$bbox-intersects` says exactly what it tests, because an operator
 // named `$intersects` that only compared bounding boxes would be a lie
-// the first time two L-shapes shared a box and nothing else.
+// the first time two L-shapes shared a box and nothing else. So is any
+// operator producing a PROJECTED coordinate: a projected position is
+// the same `[x, y]` array as a geographic one, so a language that could
+// make one could not stop it reaching `$distance`. Leaving it out makes
+// "never measure on a projected coordinate" structural instead of
+// advisory; `projectMercator` stays a kernel export for renderers.
+//
+// The conversion members carry geography in and out of the forms the
+// rest of the world uses — Well-Known Text, geohash cells — and reduce
+// a value for storage. Each is a call into the kernel and nothing else:
+// the grammar, the cell arithmetic and Douglas-Peucker each exist once.
 
 // A spatial operand, rejected uniformly: the empty sequence propagates
 // at the call site, so this only ever sees a real item.
@@ -761,11 +777,53 @@ function geoArg(v, docPath) {
   return v;
 }
 
-// a unary spatial measurement: empty propagates, anything else is JQ2001
-function geoUnaryEntry(measure, resultCard = resultEmptyPropagates) {
+// A cell string operand — the geohash family and `$geo-parse` take text
+// where the rest of the family takes a value.
+function geoTextArg(v, what, docPath) {
+  if (typeof v !== 'string') {
+    throw runtimeError('JQ2001',
+      `expected ${what}, got ${describeItem(v)}`, docPath);
+  }
+  return v;
+}
+
+// The family's non-finite rule, in one place. A coordinate that is not a
+// finite number has no measurement, and every kernel function that
+// touches one launders it into something plausible: `haversineDistance`
+// answers the antipodal distance, a NaN area compares false against zero
+// and reports 0. A representative-position operator checks the one
+// position it uses; an aggregate measurement has to know that EVERY
+// position is finite, and `centroidOf` is the kernel walk that already
+// answers it — NaN propagates through the mean, and a null mean is "no
+// positions at all", which still measures (as zero) rather than being
+// refused. No second finiteness walk exists.
+function finitePosition(at) {
+  return at !== null && Number.isFinite(at[0]) && Number.isFinite(at[1]) ? at : null;
+}
+
+function geoFinite(value) {
+  const at = centroidOf(value);
+  return at === null || finitePosition(at) !== null;
+}
+
+// the representative position §8.14 measures a value by: a bare position
+// is itself, anything else is its centroid
+function representative(value) {
+  return finitePosition(isPosition(value) ? value : centroidOf(value));
+}
+
+// A unary spatial measurement: empty propagates, anything else is
+// JQ2001 — and the answer is OPTIONAL rather than exactly-one, because
+// `null` from the kernel IS the empty sequence and every one of these
+// can answer it for an operand that is present (a non-finite
+// coordinate, text that is not well-formed, a cell outside the
+// alphabet). Declaring exactly-one would let the internal empty marker
+// escape into an array or object constructor, which is neither an item
+// nor a JSON value.
+function geoUnaryEntry(measure, check = geoArg) {
   return {
     params: UNARY,
-    result: resultCard,
+    result: RESULT_OPT,
     compile: (gets, args) => {
       const get = gets[0];
       const docPath = args[0].docPath;
@@ -773,7 +831,7 @@ function geoUnaryEntry(measure, resultCard = resultEmptyPropagates) {
         const v = get(f);
         if (v === EMPTY)
           return EMPTY;
-        const out = measure(geoArg(v, docPath));
+        const out = measure(check(v, docPath));
         return out === null ? EMPTY : out;
       };
     },
@@ -1516,9 +1574,9 @@ export const OPERATORS = Object.freeze({
   //#region section 8.14 - spatial
 
   '$bbox': geoUnaryEntry(bboxOf),
-  '$area': geoUnaryEntry(geometryArea, RESULT_ONE),
-  '$length': geoUnaryEntry(geometryLength, RESULT_ONE),
-  '$centroid': geoUnaryEntry(centroidOf),
+  '$area': geoUnaryEntry((v) => (geoFinite(v) ? geometryArea(v) : null)),
+  '$length': geoUnaryEntry((v) => (geoFinite(v) ? geometryLength(v) : null)),
+  '$centroid': geoUnaryEntry((v) => finitePosition(centroidOf(v))),
 
   '$distance': { // metres between two values' representative positions
     params: ARGS_2,
@@ -1533,7 +1591,11 @@ export const OPERATORS = Object.freeze({
         const b = bGet(f);
         if (a === EMPTY || b === EMPTY)
           return EMPTY;
-        const out = geoDistance(geoArg(a, aPath), geoArg(b, bPath));
+        const pa = representative(geoArg(a, aPath));
+        const pb = representative(geoArg(b, bPath));
+        if (pa === null || pb === null)
+          return EMPTY;
+        const out = geoDistance(pa, pb);
         return out === null ? EMPTY : out;
       };
     },
@@ -1552,13 +1614,16 @@ export const OPERATORS = Object.freeze({
         const area = areaGet(f);
         if (point === EMPTY || area === EMPTY)
           return false; // nothing is inside nothing
-        const p = geoArg(point, pointPath);
         // a bare position is itself; anything else is represented by its
         // centroid, the same rule $distance uses
-        const at = isPosition(p) ? p : centroidOf(p);
-        if (at === null)
+        const at = representative(geoArg(point, pointPath));
+        const surface = geoArg(area, areaPath);
+        // a predicate answers its missing-operand value, not empty: the
+        // surface has to be bounded too, or a NaN vertex makes an
+        // even-odd crossing count report containment that is not there
+        if (at === null || !geoFinite(surface))
           return false;
-        return containsPosition(geoArg(area, areaPath), at[0], at[1]);
+        return containsPosition(surface, at[0], at[1]);
       };
     },
   },
@@ -1585,7 +1650,9 @@ export const OPERATORS = Object.freeze({
 
   '$geohash': { // a position as a base-32 cell string
     params: ARGS_1_2,
-    result: resultEmptyPropagates,
+    // OPTIONAL for the same reason the unary measurements are: a value
+    // with no bounded position answers the empty sequence
+    result: RESULT_OPT,
     compile: (gets, args) => {
       const get = gets[0];
       const docPath = args[0].docPath;
@@ -1595,8 +1662,7 @@ export const OPERATORS = Object.freeze({
         const v = get(f);
         if (v === EMPTY)
           return EMPTY;
-        const value = geoArg(v, docPath);
-        const at = isPosition(value) ? value : centroidOf(value);
+        const at = representative(geoArg(v, docPath));
         if (at === null)
           return EMPTY;
         let precision = 9;
@@ -1613,6 +1679,73 @@ export const OPERATORS = Object.freeze({
     },
   },
 
+  // -- conversion: geography in and out of the forms the world uses --
+
+  // Well-Known Text is what PostGIS, SpatiaLite, GEOS, JTS and every
+  // `ST_AsText` emit, so without these a document can only carry such a
+  // string through untouched. Text that is not well-formed WKT is empty
+  // rather than an error, like every other "nothing to answer" here.
+  '$geo-parse': geoUnaryEntry(wktToGeoJson,
+    (v, docPath) => geoTextArg(v, 'a Well-Known Text string', docPath)),
+
+  // A value with no WKT spelling — a non-finite coordinate — is empty,
+  // never written approximately.
+  '$geo-text': geoUnaryEntry(geoJsonToWkt),
+
+  '$geohash-bounds': geoUnaryEntry(
+    (hash) => bboxPolygon(geohashBounds(hash)),
+    (v, docPath) => geoTextArg(v, 'a geohash cell string', docPath)),
+
+  // The neighbourhood, not the cell: two points metres apart can sit in
+  // different cells, so a proximity probe tests the nine cells and a
+  // single prefix is bucketing. The cells come in reading order — north
+  // -west first, the cell itself in the middle; cells past a pole do
+  // not exist and are absent, so the sequence can be shorter.
+  '$geohash-neighbours': {
+    params: UNARY,
+    result: RESULT_MANY,
+    compile: (gets, args) => {
+      const get = gets[0];
+      const docPath = args[0].docPath;
+      return (f) => {
+        const v = get(f);
+        if (v === EMPTY)
+          return EMPTY;
+        return seqOf(geohashNeighbours(geoTextArg(v, 'a geohash cell string', docPath)));
+      };
+    },
+  },
+
+  // Reduction for STORAGE and TRANSPORT: the same value with vertices
+  // dropped, still valid GeoJSON a caller can keep or send. The chart
+  // layer simplifies too, but only into its own drawing space, so
+  // nothing there hands a document back.
+  '$geo-simplify': {
+    params: ARGS_2,
+    result: resultEmptyPropagates,
+    compile: (gets, args) => {
+      const valueGet = gets[0];
+      const valuePath = args[0].docPath;
+      const toleranceGet = gets[1];
+      const tolerancePath = args[1].docPath;
+      return (f) => {
+        const v = valueGet(f);
+        const tolerance = toleranceGet(f);
+        if (v === EMPTY || tolerance === EMPTY)
+          return EMPTY;
+        // degrees, not metres: a planar vertex-dropping threshold. A
+        // degree of longitude is not a fixed distance, so naming it a
+        // distance is the confusion this family exists to prevent.
+        if (typeof tolerance !== 'number' || !Number.isFinite(tolerance) || tolerance < 0) {
+          throw runtimeError('JQ2001',
+            `a simplification tolerance is a non-negative number of degrees, got ${describeItem(tolerance)}`,
+            tolerancePath);
+        }
+        return simplifyGeometry(geoArg(v, valuePath), tolerance);
+      };
+    },
+  },
+
   //#endregion
 
   //#region section 8.13 - dates and times, continued