@reventlessdev/reventless-spec 3.0.0-alpha.119 → 3.0.0-alpha.120

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.120 (2026-08-20)
+
+### Features
+
+* **spec:** type a geocoder's answer as one Geolocation value ([157be7a](https://github.com/ReventlessDev/reventless-core/commit/157be7aca4806ae19dba1f58979af13b88dc1821))
+
+
 # 3.0.0-alpha.119 (2026-08-20)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.119",
+  "version": "3.0.0-alpha.120",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/semantic/Geocoding.res

@@ -1,17 +1,9 @@
 /**
 Turning an address into a point, and deciding whether to believe the answer.
 
-The *transport* is provider-specific — Amazon Location, a self-hosted Nominatim,
-a vendor's HTTP API — and lives with its provider. What lives here is everything
-that is the same regardless of who answers: the shape of an answer, the two ways
-a lookup can fail, and the rule for when a ranked list is confident enough to
-write a coordinate into an event log.
-
-That split matters because the confidence rule is the part that is easy to get
-wrong and expensive to get wrong twice. A caller that re-derives it — takes
-`results[0]` because the list was ranked — produces a plausible marker in the
-wrong region, drawn without an error anywhere. Deciding it once, here, is what
-stops each transport inventing its own answer.
+The transport is provider-specific and lives with its provider. What is here is
+provider-neutral: the shape of an answer, the two ways a lookup fails, and the
+confidence rule — decided once, so no transport invents its own.
 */
 
 /** One candidate a geocoder returned. */
@@ -19,25 +11,13 @@ type candidate = {
   /** The provider's canonical rendering of the address it matched. */
   label: string,
   point: GeoPoint.t,
-  /**
-  How well this result matches the query, 0…1.
-
-  `None` when the provider does not score its results. That is not the same as a
-  low score and must not be read as a high one — `confidentMatch` declines it,
-  because an unscored list cannot support an unattended decision.
-  */
+  /** How well this matches, 0…1. `None` when the provider does not score, which
+      `confidentMatch` declines rather than reading as high. */
   relevance: option<float>,
 }
 
-/**
-Why a lookup produced no usable point.
-
-Two constructors rather than one message because the caller's retry decision
-turns on exactly this distinction, and a `switch` is the only form of it that
-cannot be got wrong. A translator that cannot tell "no such address" from "the
-service is down" turns one outage into a permanent verdict on every address in
-flight.
-*/
+/** Why a lookup produced no usable point. Two constructors because the retry
+    decision turns on the distinction: an outage must not become a verdict. */
 type failure =
   | /** The provider could not be reached, or refused the call. Retry. */
   Unavailable(string)
@@ -45,83 +25,82 @@ type failure =
   NoMatch
 
 /**
-The port a caller reaches a geocoder through.
-
-Everything above says what an answer looks like; this says how one is asked for.
-Written down as a type before anything is injected against it, so that swapping
-the implementation underneath a caller is a change of *supplier* rather than a
-change of call site: whatever eventually hands a translator its geocoder — an
-HTTP client reading an endpoint out of its environment, a provider SDK called
-directly — has to satisfy this, and the `await search(~text=…)` in the caller
-does not move.
+The port a caller reaches a geocoder through, so swapping the implementation is a
+change of supplier rather than of call site.
 
-`~text` is the address as a human typed it, unnormalised. Normalising it is the
-provider's job, and its canonical rendering comes back as `candidate.label`.
+`~text` is unnormalised; the provider's canonical rendering comes back as
+`candidate.label`.
 */
 type search = (~text: string) => promise<result<array<candidate>, failure>>
 
 /**
-The default confidence floor, calibrated against Amazon Location's Esri index.
-
-Measured, not guessed — and the measurement moved it a long way. Esri does not
-spread its scores over 0…1: everything it is willing to return at all lands in
-roughly 0.9…1.0, so a floor of `0.8` admitted almost every answer and left the
-ambiguity margin doing all the work. The separation is up at the top of the
-range instead — in a 24-address corpus the correct pinpoint matches scored
-≥ 0.988 while the wrong ones (a misspelling resolved to the wrong state, a
-street name matched to a different street in the right city) scored 0.913…0.958.
+The default confidence floor, measured against Amazon Location's Esri index:
+correct matches scored ≥ 0.988, wrong ones 0.913…0.958, so `0.97` sits in the gap.
 
-`0.97` sits in that gap. The wider consequence is that these numbers are
-*provider-calibrated* even though everything else in this module is
-provider-neutral, which is exactly why both are labelled arguments: a geocoder
-that scores on a different curve needs its own pair, and the defaults are the
-Esri answer rather than a universal one.
+Provider-calibrated, which is why it is a labelled argument — a geocoder scoring
+on a different curve needs its own pair.
 */
 let defaultMinRelevance = 0.97
 
-/**
-How close the runner-up may come before the answer is called ambiguous.
-
-Deliberately small, for the same reason the floor is large. Genuine ambiguity in
-Esri shows up as a *tie* — "Springfield" returns five states at exactly 1.0,
-"221B Baker" five towns at exactly 0.8222 — not as a near miss. A wide margin
-does not catch more of those; it only starts rejecting clear winners, because a
-correct match at 0.991 routinely has a plausible runner-up at 0.962.
-*/
+/** How close the runner-up may come before the answer is ambiguous. Small, because
+    real ambiguity shows up as a tie; a wide margin only rejects clear winners. */
 let defaultAmbiguityMargin = 0.01
 
-/**
-The one candidate confident enough to store, or `None`.
-
-Two ways to be unsure, and both decline:
-
-- the top candidate scores below `minRelevance` — the provider matched
-  something, loosely;
-- the runner-up scores within `ambiguityMargin` of the top — the provider
-  matched several things about equally well, which is what a bare town name
-  does.
-
-`None` means "ask a human", not "no result". The candidates are still there for
-a caller that wants to show them.
-*/
-let confidentMatch = (
+/** The confidence decision with the reason attached, for a caller that reports
+    the outcome rather than acting on it. */
+type assessment =
+  | Confident(candidate)
+  | NoCandidates
+  | /** Unscored is not a low score, and must not read as a high one. */
+  Unscored(candidate)
+  | LowRelevance({top: candidate, score: float, floor: float})
+  | /** Several matches about equally well. */
+  Ambiguous({top: candidate, runnerUp: candidate, margin: float})
+
+/** The confidence rule, stated once. Everything else here derives from it. */
+let assess = (
   candidates: array<candidate>,
   ~minRelevance: float=defaultMinRelevance,
   ~ambiguityMargin: float=defaultAmbiguityMargin,
-): option<candidate> =>
+): assessment =>
   switch candidates->Array.get(0) {
-  | None => None
+  | None => NoCandidates
   | Some(top) =>
     switch top.relevance {
-    | None => None
+    | None => Unscored(top)
     | Some(topScore) =>
       if topScore < minRelevance {
-        None
+        LowRelevance({top, score: topScore, floor: minRelevance})
       } else {
-        switch candidates->Array.get(1)->Option.flatMap(c => c.relevance) {
-        | Some(runnerUp) if topScore -. runnerUp < ambiguityMargin => None
-        | _ => Some(top)
+        switch candidates->Array.get(1) {
+        | Some(runnerUp) =>
+          switch runnerUp.relevance {
+          | Some(runnerUpScore) if topScore -. runnerUpScore < ambiguityMargin =>
+            Ambiguous({top, runnerUp, margin: ambiguityMargin})
+          | _ => Confident(top)
+          }
+        | None => Confident(top)
         }
       }
     }
   }
+
+/**
+The one candidate confident enough to store, or `None` — which means "ask a
+human", not "no result". Declines a top scoring below `minRelevance` and a
+runner-up within `ambiguityMargin`. `assess` says which rule declined.
+*/
+let confidentMatch = (
+  candidates: array<candidate>,
+  ~minRelevance: float=defaultMinRelevance,
+  ~ambiguityMargin: float=defaultAmbiguityMargin,
+): option<candidate> =>
+  // Listed rather than `_`, so a new case must be decided here.
+  switch candidates->assess(~minRelevance, ~ambiguityMargin) {
+  | Confident(top) => Some(top)
+  | NoCandidates
+  | Unscored(_)
+  | LowRelevance(_)
+  | Ambiguous(_) =>
+    None
+  }

package/src/semantic/Geocoding.res.mjs

@@ -1,26 +1,59 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 
-function confidentMatch(candidates, minRelevanceOpt, ambiguityMarginOpt) {
+function assess(candidates, minRelevanceOpt, ambiguityMarginOpt) {
   let minRelevance = minRelevanceOpt !== undefined ? minRelevanceOpt : 0.97;
   let ambiguityMargin = ambiguityMarginOpt !== undefined ? ambiguityMarginOpt : 0.01;
   let top = candidates[0];
   if (top === undefined) {
-    return;
+    return "NoCandidates";
   }
   let topScore = top.relevance;
   if (topScore === undefined) {
-    return;
+    return {
+      TAG: "Unscored",
+      _0: top
+    };
   }
   if (topScore < minRelevance) {
-    return;
+    return {
+      TAG: "LowRelevance",
+      top: top,
+      score: topScore,
+      floor: minRelevance
+    };
+  }
+  let runnerUp = candidates[1];
+  if (runnerUp === undefined) {
+    return {
+      TAG: "Confident",
+      _0: top
+    };
+  }
+  let runnerUpScore = runnerUp.relevance;
+  if (runnerUpScore !== undefined && topScore - runnerUpScore < ambiguityMargin) {
+    return {
+      TAG: "Ambiguous",
+      top: top,
+      runnerUp: runnerUp,
+      margin: ambiguityMargin
+    };
+  } else {
+    return {
+      TAG: "Confident",
+      _0: top
+    };
   }
-  let runnerUp = Stdlib_Option.flatMap(candidates[1], c => c.relevance);
-  if (runnerUp !== undefined && topScore - runnerUp < ambiguityMargin) {
+}
+
+function confidentMatch(candidates, minRelevanceOpt, ambiguityMarginOpt) {
+  let minRelevance = minRelevanceOpt !== undefined ? minRelevanceOpt : 0.97;
+  let ambiguityMargin = ambiguityMarginOpt !== undefined ? ambiguityMarginOpt : 0.01;
+  let top = assess(candidates, minRelevance, ambiguityMargin);
+  if (typeof top !== "object" || top.TAG !== "Confident") {
     return;
   } else {
-    return top;
+    return top._0;
   }
 }
 
@@ -31,6 +64,7 @@ let defaultAmbiguityMargin = 0.01;
 export {
   defaultMinRelevance,
   defaultAmbiguityMargin,
+  assess,
   confidentMatch,
 }
 /* No side effect */

package/src/semantic/Geolocation.res

@@ -0,0 +1,81 @@
+/**
+A geocoder's answer as one value; `Geocoding`'s return type.
+
+Three arms rather than `option<GeoPoint.t>`, whose `None` means both "has not run"
+and "ran and failed". Emitted as a GraphQL union (see `Reventless.TaggedUnion`).
+Replacing a point/status/note trio with it is wire-breaking.
+*/
+
+@schema
+type t =
+  | /** `requestedFor` is the address asked about, so a stale answer is detectable. */
+  Pending({requestedFor: string})
+  | Located({point: GeoPoint.t})
+  | /** Answered, with nothing storable unattended. A verdict for a human. */
+  Unresolvable({reason: string})
+
+/** Adds the two markers the shape cannot carry: the semantic, and the union name
+    the SDL and the `__typename` stamp share. */
+let schema: S.t<t> =
+  schema->Semantic.mark(~id=Semantic.Id.geolocation)->TaggedUnion.named(~name="Geolocation")
+
+/** The point, when there is one. */
+let point = (geolocation: t): option<GeoPoint.t> =>
+  switch geolocation {
+  | Located({point}) => Some(point)
+  | Pending(_) | Unresolvable(_) => None
+  }
+
+let isLocated = (geolocation: t): bool => geolocation->point->Option.isSome
+
+/** Why it could not be resolved. `None` for `Pending`, which is still waiting. */
+let reason = (geolocation: t): option<string> =>
+  switch geolocation {
+  | Unresolvable({reason}) => Some(reason)
+  | Pending(_) | Located(_) => None
+  }
+
+/**
+The geolocation a geocoder's answer implies, via `Geocoding.assess`.
+
+`Error(Unavailable(_))` returns `None` — leave the row alone, since an outage
+written as a verdict is permanent. Never returns `Pending`. Thresholds are
+threaded because they are provider-calibrated.
+*/
+let ofSearch = (
+  ~requestedFor: string,
+  ~minRelevance: float=Geocoding.defaultMinRelevance,
+  ~ambiguityMargin: float=Geocoding.defaultAmbiguityMargin,
+  answer: result<array<Geocoding.candidate>, Geocoding.failure>,
+): option<t> =>
+  switch answer {
+  | Error(Unavailable(_)) => None
+  | Error(NoMatch) => Some(Unresolvable({reason: `no match for "${requestedFor}"`}))
+  | Ok(candidates) =>
+    // Reasons report what came back; the rule that rejected it stays in `assess`.
+    switch candidates->Geocoding.assess(~minRelevance, ~ambiguityMargin) {
+    | Confident(top) => Some(Located({point: top.point}))
+    | NoCandidates => Some(Unresolvable({reason: `no candidates for "${requestedFor}"`}))
+    | Unscored(top) =>
+      Some(
+        Unresolvable({
+          reason: `the geocoder returned "${top.label}" for "${requestedFor}" without scoring it, ` ++
+          `and an unscored answer cannot be accepted unattended`,
+        }),
+      )
+    | LowRelevance({top, score, floor}) =>
+      Some(
+        Unresolvable({
+          reason: `the best match for "${requestedFor}" was "${top.label}" at relevance ` ++
+          `${Float.toString(score)}, below the ${Float.toString(floor)} needed to store one`,
+        }),
+      )
+    | Ambiguous({top, runnerUp}) =>
+      Some(
+        Unresolvable({
+          reason: `"${requestedFor}" matched "${top.label}" and "${runnerUp.label}" ` ++
+          `about equally well`,
+        }),
+      )
+    }
+  }

package/src/semantic/Geolocation.res.mjs

@@ -0,0 +1,104 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as GeoPoint$Reventless from "./GeoPoint.res.mjs";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+import * as Geocoding$Reventless from "./Geocoding.res.mjs";
+import * as TaggedUnion$Reventless from "../components/TaggedUnion.res.mjs";
+
+let schema = Sury.union([
+  Sury.$schema(s => ({
+    TAG: "Pending",
+    requestedFor: s.m(Sury.string)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Located",
+    point: s.m(GeoPoint$Reventless.schema)
+  })),
+  Sury.$schema(s => ({
+    TAG: "Unresolvable",
+    reason: s.m(Sury.string)
+  }))
+]);
+
+let schema$1 = TaggedUnion$Reventless.named("Geolocation", Semantic$Reventless.mark(schema, Semantic$Reventless.Id.geolocation, undefined));
+
+function point(geolocation) {
+  switch (geolocation.TAG) {
+    case "Located" :
+      return geolocation.point;
+    case "Pending" :
+    case "Unresolvable" :
+      return;
+  }
+}
+
+function isLocated(geolocation) {
+  return Stdlib_Option.isSome(point(geolocation));
+}
+
+function reason(geolocation) {
+  switch (geolocation.TAG) {
+    case "Pending" :
+    case "Located" :
+      return;
+    case "Unresolvable" :
+      return geolocation.reason;
+  }
+}
+
+function ofSearch(requestedFor, minRelevanceOpt, ambiguityMarginOpt, answer) {
+  let minRelevance = minRelevanceOpt !== undefined ? minRelevanceOpt : Geocoding$Reventless.defaultMinRelevance;
+  let ambiguityMargin = ambiguityMarginOpt !== undefined ? ambiguityMarginOpt : Geocoding$Reventless.defaultAmbiguityMargin;
+  if (answer.TAG === "Ok") {
+    let top = Geocoding$Reventless.assess(answer._0, minRelevance, ambiguityMargin);
+    if (typeof top !== "object") {
+      return {
+        TAG: "Unresolvable",
+        reason: `no candidates for "` + requestedFor + `"`
+      };
+    }
+    switch (top.TAG) {
+      case "Confident" :
+        return {
+          TAG: "Located",
+          point: top._0.point
+        };
+      case "Unscored" :
+        return {
+          TAG: "Unresolvable",
+          reason: `the geocoder returned "` + top._0.label + `" for "` + requestedFor + `" without scoring it, and an unscored answer cannot be accepted unattended`
+        };
+      case "LowRelevance" :
+        return {
+          TAG: "Unresolvable",
+          reason: `the best match for "` + requestedFor + `" was "` + top.top.label + `" at relevance ` + (top.score.toString() + `, below the ` + top.floor.toString() + ` needed to store one`)
+        };
+      case "Ambiguous" :
+        return {
+          TAG: "Unresolvable",
+          reason: `"` + requestedFor + `" matched "` + top.top.label + `" and "` + top.runnerUp.label + `" about equally well`
+        };
+    }
+  } else {
+    let tmp = answer._0;
+    if (typeof tmp !== "object") {
+      return {
+        TAG: "Unresolvable",
+        reason: `no match for "` + requestedFor + `"`
+      };
+    } else {
+      return;
+    }
+  }
+}
+
+export {
+  schema$1 as schema,
+  point,
+  isLocated,
+  reason,
+  ofSearch,
+}
+/* schema Not a pure module */

package/src/semantic/Semantic.res

@@ -1,34 +1,21 @@
 /**
 The one marker every typed semantic marks itself with.
 
-A semantic type says what a field's value *is* — a date-time, a reference to
-another entity, a ref into an object store — as a property of the field's
-**type**, not as a string stapled beside it. Every layer downstream then derives
-from that single declaration: validation, the wire contract, the UI widget it
-gets rendered with, and eventually the infrastructure provisioned for it.
-
-Typed markers predate this module, and each was bespoke: `DateTime` carried its
-own metadata id, `Reference` carried another, and the schema walk detected both
-by hardcoded special case. That made every new typed marker new detection code.
-One shared marker means the walk reads a semantic generically and a new semantic
-type is a new *value*, not a new branch.
-
-The payload is a real variant rather than free-form JSON. The semantic
-vocabulary is framework-owned — an application declares a field *is* a storage
-ref, it does not invent what a storage ref means — so the set is closed, and a
-closed set typed here is one the compiler checks at every producer and consumer.
-It also keeps `Reference.getTarget` a total typed function instead of a decode
-that can fail at runtime.
+A semantic says what a field's value *is*, as a property of its type; validation,
+the wire contract and the UI widget all derive from that one declaration. One
+shared marker means the schema walk reads semantics generically, so a new
+semantic is a new value rather than a new branch.
+
+The payload is a typed variant because the vocabulary is framework-owned and
+closed — which also keeps `Reference.getTarget` total.
 */
 
 /** Which entity a reference field points to. */
 type referenceTarget = {entity: string, plugin: option<string>}
 
-/** Which object store a storage-ref / offload field's value lives in. `plugin` is
-    absent when the store belongs to the declaring plugin, which is the common
-    case. `threshold` is the per-field inline-vs-offloaded byte cut an `@offload`
-    field may declare (`None` for `@storageRef`, which is always a ref, and for
-    `@offload` fields that leave it to the platform default). */
+/** Which object store the value lives in. `plugin` is absent for the declaring
+    plugin's own store; `threshold` is `@offload`'s per-field byte cut, `None`
+    when it defers to the platform default. */
 type storeTarget = {plugin: option<string>, store: string, threshold: option<int>}
 
 /** Per-semantic detail, for the semantics that carry any. */
@@ -40,37 +27,25 @@ type payload =
 /** A field's semantic: the vocabulary id, plus its detail. */
 type t = {id: string, payload: payload}
 
-/**
-The semantic ids the framework itself defines.
-
-These strings are the wire vocabulary — they are what `x-reventless-semantic`
-carries, and the same vocabulary the string annotation path already uses, so the
-type path and the annotation path converge on one wire format rather than two.
-*/
+/** The semantic ids the framework defines. These strings are the wire vocabulary
+    `x-reventless-semantic` carries, shared with the annotation path. */
 module Id = {
   let dateTime = "dateTime"
   let reference = "reference"
   let storageRef = "storageRef"
-  // A field whose large value the client stored in a content-addressed object
-  // store and carries by reference (inline below a size threshold). Sibling of
-  // `storageRef`: same `StoredIn` store declaration, but an inline-or-reference
-  // value rather than an always-a-ref path string.
+  // Like `storageRef`, but inline-or-reference rather than always a ref path.
   let offload = "offload"
 
-  // The uploadable family: the same `StoredIn` declaration as `storageRef`,
-  // plus a statement about what the value *is*, so one declaration picks both a
-  // renderer and an upload endpoint. The store is derived from the field name by
-  // the ppx rather than written on the type.
+  // `storageRef` plus what the value is, so one declaration picks a renderer and
+  // an upload endpoint. The ppx derives the store from the field name.
   let uploadableImage = "uploadableImage"
   let uploadableFile = "uploadableFile"
 
-  // The same content facts with no store attached, for values the platform
-  // reads but does not own. Nothing is provisioned for these.
+  // The same content facts with no store — nothing is provisioned.
   let imageRef = "imageRef"
   let fileRef = "fileRef"
 
-  // The branded scalars. Each refines a `string` or a number without changing
-  // its shape, so a field gains one of these without anything stored changing.
+  // Branded scalars: a refinement, so adopting one changes nothing stored.
   let email = "email"
   let phone = "phone"
   let url = "url"
@@ -79,23 +54,18 @@ module Id = {
   let duration = "duration"
   let color = "color"
 
-  // The first composite that is not infrastructure. Unlike the seven above it
-  // this one changes a field's *shape* — a number becomes an object — so it is
-  // a wire-breaking declaration rather than a refinement of one.
+  // The first composite: changes a field's shape, so it is wire-breaking.
   let money = "money"
 
-  // The second composite. A pair of ISO-8601 instants as one value, replacing a
-  // span the UI used to guess from a `start*`/`end*` name pair. Like `money` it
-  // is an object on the wire; unlike it, adopting it as a *new* optional field
-  // is additive — an absent optional decodes to `None`.
+  // A pair of ISO-8601 instants. Adopting it as a new optional field is additive.
   let dateRange = "dateRange"
 
-  // The third composite, and the cheapest to adopt. A latitude/longitude pair as
-  // one value, replacing a point the UI used to guess from a `lat`/`lng` name
-  // pair. Most coordinate fields already store `{lat, lng}` as a hand-rolled
-  // record, so retyping one is shape-preserving: the wire is unchanged and
-  // nothing stored needs upcasting.
+  // A lat/lng pair. Cheapest to adopt: `{lat, lng}` is already the stored shape.
   let geoPoint = "geoPoint"
+
+  // The first composite that is a union rather than an object. Collapses fields,
+  // so adopting it changes the wire and rebuilds a derived view.
+  let geolocation = "geolocation"
 }
 
 let semanticId: S.Metadata.Id.t<t> = S.Metadata.Id.make(~namespace="reventless", ~name="semantic")
@@ -104,20 +74,10 @@ let semanticId: S.Metadata.Id.t<t> = S.Metadata.Id.make(~namespace="reventless",
 let mark = (schema: S.t<'a>, ~id: string, ~payload: payload=Plain): S.t<'a> =>
   schema->S.Metadata.set(~id=semanticId, {id, payload})
 
-/**
-A schema that validates with `check` and carries the semantic `id`.
-
-The branded scalars all have the same shape — one constructor function that
-defines the grammar, and a schema that must agree with it — and `StorageRef`
-established that the schema is *derived* from the constructor rather than
-hand-rolling a second check beside it. Deriving it here makes that structural:
-there is one place a grammar can be written, so there is nowhere for a second
-one to drift.
-*/
-// sury's refiner is a predicate with a fixed message, so the per-value reason
-// `check` returns is not threaded into the schema error; call the scalar's own
-// `fromString`/`fromFloat` directly when the caller needs to report which rule
-// the value broke.
+/** A schema that validates with `check` and carries the semantic `id`, derived
+    from the constructor so no second grammar can drift from it. */
+// sury's refiner takes a fixed message, so `check`'s per-value reason is lost
+// here; call the scalar's own `fromString`/`fromFloat` to report which rule broke.
 let refined = (base: S.t<'a>, ~id: string, ~check: 'a => result<'a, string>): S.t<'a> =>
   base
   ->S.refine(
@@ -130,22 +90,16 @@ let refined = (base: S.t<'a>, ~id: string, ~check: 'a => result<'a, string>): S.
   )
   ->mark(~id)
 
-/** A value as it should read back to the person who typed it. Rejection messages
-    reach forms through `validateInput`, so they quote the offending value. */
+/** A value as it should read back to whoever typed it — rejection messages quote
+    the offending value. */
 let showString = (raw: string): string => raw->JSON.Encode.string->JSON.stringify
 
 /**
 The schema an optional field's wrapper stands for, if it is one.
 
-sury-ppx compiles `f?: X` to a union of `X`'s schema with `Undefined`/`Null`, and
-that wrapper is a new schema carrying no metadata of its own. Every reader that
-looks *through* a field — for its semantic, or for the element type inside it —
-needs the same one-level unwrap, so it lives here once rather than once per
-reader.
-
-Only a union with exactly one non-null variant is followed: that is the shape an
-optional field has, and a genuine multi-variant union has no single inner schema
-that could stand for the whole.
+sury-ppx compiles `f?: X` to a union with `Undefined`/`Null`, and that wrapper
+carries no metadata of its own. Only a union with exactly one non-null variant is
+followed — a real multi-variant union has no single inner schema.
 */
 let unwrapOptional = (schema: S.t<unknown>): option<S.t<unknown>> =>
   switch schema {
@@ -165,14 +119,8 @@ let unwrapOptional = (schema: S.t<unknown>): option<S.t<unknown>> =>
 /**
 The semantic a field's schema carries, if any.
 
-An **optional** field keeps its marker one level down, inside the wrapper
-`unwrapOptional` describes. So a walk that reads only the outer schema sees
-`imageUrl?: string` as carrying no semantic at all — the store goes undeclared,
-the reference goes uncollected, the branded scalar loses its brand. Every reader
-converges here, so following the wrapper once here is what keeps "optional" a
-statement about presence rather than a way to lose the field's type.
-
-The outer schema is read first, so a marker set on the wrapper itself still wins.
+An optional field keeps its marker inside the wrapper, so reading only the outer
+schema loses it. The outer schema is read first, so a marker on the wrapper wins.
 */
 let rec getFrom = (schema: S.t<unknown>): option<t> =>
   switch S.Metadata.get(schema, ~id=semanticId) {

package/src/semantic/Semantic.res.mjs

@@ -22,7 +22,8 @@ let Id = {
   color: "color",
   money: "money",
   dateRange: "dateRange",
-  geoPoint: "geoPoint"
+  geoPoint: "geoPoint",
+  geolocation: "geolocation"
 };
 
 let semanticId = Sury.$Metadata_Id_make("reventless", "semantic");