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

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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
+
+* **api:** emit a tagged-union state field as a GraphQL union ([3a380c0](https://github.com/ReventlessDev/reventless-core/commit/3a380c0ab055b87048d90a852ec1664f6aab6b00))
+
+
 # 3.0.0-alpha.118 (2026-08-18)
 
 ### Bug Fixes

package/package.json

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

package/src/components/TaggedUnion.res

@@ -0,0 +1,238 @@
+/**
+A variant used as a **field** of a queryable's state — one fact with several
+shapes, rather than several fields that have to be kept in step by hand.
+
+```rescript
+@schema
+type geolocation =
+  | Pending({requestedFor: string})
+  | Located({point: Reventless.GeoPoint.t})
+  | Unresolvable({reason: string})
+```
+
+The value is stored the way sury encodes it — `{"TAG":"Located","point":{…}}` —
+and reaches GraphQL as a union of one object type per arm. Both halves need the
+*same* name for the union, and neither can derive it from the other: the SDL
+emitter walks a schema it reaches through a field path, and the write path has
+only the schema in hand. So the name is carried **on the schema**, set once at
+the declaration by `named` — the ppx does it for a variant a state record uses,
+and a framework type carrying a union does it beside its `Semantic.mark`.
+
+A union with no name is not emitted as one. It falls through to the IR's
+`Unknown`, which is a `String` in the SDL — the behaviour that predates this
+module — except that it is now reported at deploy time instead of silently.
+*/
+let unionNameId: S.Metadata.Id.t<string> = S.Metadata.Id.make(
+  ~namespace="reventless",
+  ~name="taggedUnionName",
+)
+
+/**
+Names a union, so that the type emitted for it and the `__typename` stamped into
+every stored value of it agree.
+
+Written at the declaration, never at the field: two fields holding the same union
+hold the same type, and naming it per field is what produces one GraphQL type per
+field path — the mistake `semanticCompositeNames` exists to undo for `Money`.
+*/
+let named = (~name: string, schema: S.t<'a>): S.t<'a> =>
+  schema->S.Metadata.set(~id=unionNameId, name)
+
+/**
+The name a union field's schema carries.
+
+Read straight off the field's schema, wrapper included: sury's `option` keeps the
+metadata of what it wraps, which matters because it does *not* keep the union as
+a nested schema — `option<t>` flattens the arms and the `undefined` into one
+`anyOf`, leaving nothing inside to consult. `TaggedUnionTest` pins that, since a
+sury release that stopped preserving it would turn every optional union field
+into a `String` with no compile error anywhere.
+*/
+let getName = (schema: S.t<unknown>): option<string> => S.Metadata.get(schema, ~id=unionNameId)
+
+/**
+The GraphQL type emitted for one arm: the union's name with the arm's own
+appended (`Geolocation` + `Located` = `GeolocationLocated`).
+
+One derivation, used by the SDL emitter and by the write-time stamp. A second
+spelling of this rule anywhere is a `__typename` that resolves to no member,
+which GraphQL reports as a null — and a null in a non-nullable field takes its
+parent with it.
+*/
+let memberTypeName = (~union: string, ~arm: string): string => union ++ arm
+
+/** The key a stored union value carries its member type under. */
+let typenameKey = "__typename"
+
+/** One arm: the constructor name sury writes into `TAG`, and the arm's schema. */
+type arm = {tag: string, schema: S.t<unknown>}
+
+// A payload sury named rather than the author: `| Located(GeoPoint.t)` encodes to
+// `{"TAG":"Located","_0":{…}}`, and `_0` would be published as an SDL field name
+// and as a stored key. The ppx refuses the shape at its declaration; this refuses
+// it again for a union declared where the ppx cannot see it, by declining to
+// classify the union at all.
+let isPositionalName = (name: string): bool =>
+  name->String.startsWith("_") &&
+  name->String.length > 1 &&
+  name
+  ->String.slice(~start=1, ~end=name->String.length)
+  ->String.split("")
+  ->Array.every(c => c >= "0" && c <= "9")
+
+/**
+The arms of a schema that is a union of tagged objects, or `None`.
+
+Refuses three shapes, all for reasons that are GraphQL's rather than sury's, and
+all of which encode and decode perfectly well:
+
+- a payload-less arm (`| Pending`), which sury writes as the bare string
+  `"Pending"` — a union member must be an object type;
+- an arm with no field of its own (`| Pending({})`), which would imply a member
+  type with zero fields;
+- a positional payload, whose field name is the compiler's `_0`.
+
+Declining leaves the field an `Unknown`, which is reported where it is emitted.
+*/
+let armsOf = (schema: S.t<unknown>): option<array<arm>> =>
+  switch schema {
+  | AnyOf({anyOf}) =>
+    let members = anyOf->Array.filter(v =>
+      switch v {
+      | Null(_) | Undefined(_) => false
+      | _ => true
+      }
+    )
+    if members->Array.length < 2 {
+      None
+    } else {
+      let arms = members->Array.filterMap(member =>
+        switch member {
+        | Object({properties}) =>
+          switch properties->Dict.get("TAG") {
+          | Some(String({const: ?Some(tag)})) =>
+            let fields = properties->Dict.toArray->Array.filter(((name, _)) => name !== "TAG")
+            if (
+              fields->Array.length == 0 ||
+                fields->Array.some(((name, _)) => isPositionalName(name))
+            ) {
+              None
+            } else {
+              Some({tag, schema: member})
+            }
+          | _ => None
+          }
+        | _ => None
+        }
+      )
+      arms->Array.length == members->Array.length ? Some(arms) : None
+    }
+  | _ => None
+  }
+
+/** A named union of tagged objects: its name and its arms, or `None`. */
+let classify = (schema: S.t<unknown>): option<(string, array<arm>)> =>
+  switch (getName(schema), armsOf(schema)) {
+  | (Some(name), Some(arms)) => Some((name, arms))
+  | _ => None
+  }
+
+/**
+Whether a schema is a union of tagged objects that carries no name — the one case
+worth telling a deploy about, since it is a union the author meant and the SDL
+cannot emit.
+*/
+let isUnnamedUnion = (schema: S.t<unknown>): bool =>
+  getName(schema)->Option.isNone && armsOf(schema)->Option.isSome
+
+/**
+Stamps `__typename` into every union value inside an encoded row, in place.
+
+Written once at save rather than by each read door: both AppSync and graphql-js
+resolve a union member from `__typename` on the value they are handed, and the
+AppSync resolvers hand back the stored item unchanged. The doors that would each
+have to stamp number fourteen across three backends, and the live change channel
+— which carries the row as raw JSON, past the typed field entirely — is reachable
+from none of them. Stamping here is one place, and it is the only one both
+channels share.
+
+Driven by the schema, so a row of a view with no union field is walked and left
+byte-identical.
+*/
+let rec stampInto = (~schema: S.t<unknown>, json: JSON.t): unit =>
+  switch classify(schema) {
+  | Some((name, arms)) =>
+    switch json->JSON.Decode.object {
+    | Some(obj) =>
+      switch obj->Dict.get("TAG")->Option.flatMap(JSON.Decode.string) {
+      | Some(tag) =>
+        obj->Dict.set(typenameKey, JSON.Encode.string(memberTypeName(~union=name, ~arm=tag)))
+        // An arm's own fields may hold unions too, so the arm is walked as the
+        // record it is — the union case above cannot recurse into it, since a
+        // union's schema says nothing about which arm this value took.
+        switch arms->Array.find(a => a.tag === tag) {
+        | Some({schema: armSchema}) => stampMembers(~schema=armSchema, json)
+        | None => ()
+        }
+      | None => ()
+      }
+    | None => ()
+    }
+  | None => stampMembers(~schema, json)
+  }
+
+and stampMembers = (~schema: S.t<unknown>, json: JSON.t): unit =>
+  switch schema {
+  | Object({properties}) =>
+    switch json->JSON.Decode.object {
+    | Some(obj) =>
+      properties
+      ->Dict.toArray
+      ->Array.forEach(((name, propSchema)) =>
+        switch obj->Dict.get(name) {
+        | Some(value) => stampInto(~schema=propSchema, value)
+        | None => ()
+        }
+      )
+    | None => ()
+    }
+  | Array({items, additionalItems}) =>
+    let itemSchema = switch items->Array.get(0) {
+    | Some(itemSchema) => Some(itemSchema)
+    | None =>
+      switch additionalItems {
+      | Schema(s) => Some(s)
+      | _ => None
+      }
+    }
+    switch (itemSchema, json->JSON.Decode.array) {
+    | (Some(itemSchema), Some(values)) =>
+      values->Array.forEach(value => stampInto(~schema=itemSchema, value))
+    | _ => ()
+    }
+  | _ =>
+    // An optional field wraps its schema in a union with `undefined`; the value
+    // that reached us is the inner one either way.
+    switch Semantic.unwrapOptional(schema) {
+    | Some(inner) => stampInto(~schema=inner, json)
+    | None => ()
+    }
+  }
+
+/**
+The union fields an object schema declares, named and unnamed alike, with the
+name where there is one.
+
+The SDL emitter and the deploy-time report both need to say *which field* — a
+report that names only the view leaves the author grepping.
+*/
+let fieldsOf = (schema: S.t<unknown>): array<(string, option<string>)> =>
+  switch schema {
+  | Object({properties}) =>
+    properties
+    ->Dict.toArray
+    ->Array.filterMap(((name, propSchema)) =>
+      armsOf(propSchema)->Option.isSome ? Some((name, getName(propSchema))) : None
+    )
+  | _ => []
+  }

package/src/components/TaggedUnion.res.mjs

@@ -0,0 +1,193 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
+
+let unionNameId = Sury.$Metadata_Id_make("reventless", "taggedUnionName");
+
+function named(name, schema) {
+  return Sury.$Metadata_set(schema, unionNameId, name);
+}
+
+function getName(schema) {
+  return Sury.$Metadata_get(schema, unionNameId);
+}
+
+function memberTypeName(union, arm) {
+  return union + arm;
+}
+
+let typenameKey = "__typename";
+
+function isPositionalName(name) {
+  if (name.startsWith("_") && name.length > 1) {
+    return name.slice(1, name.length).split("").every(c => {
+      if (c >= "0") {
+        return c <= "9";
+      } else {
+        return false;
+      }
+    });
+  } else {
+    return false;
+  }
+}
+
+function armsOf(schema) {
+  if (schema.type !== "anyOf") {
+    return;
+  }
+  let members = schema.anyOf.filter(v => {
+    switch (v.type) {
+      case "null" :
+      case "undefined" :
+        return false;
+      default:
+        return true;
+    }
+  });
+  if (members.length < 2) {
+    return;
+  }
+  let arms = Stdlib_Array.filterMap(members, member => {
+    if (member.type !== "object") {
+      return;
+    }
+    let properties = member.properties;
+    let match = properties["TAG"];
+    if (match === undefined) {
+      return;
+    }
+    if (match.type !== "string") {
+      return;
+    }
+    let tag = match.const;
+    if (tag === undefined) {
+      return;
+    }
+    let fields = Object.entries(properties).filter(param => param[0] !== "TAG");
+    if (fields.length === 0 || fields.some(param => isPositionalName(param[0]))) {
+      return;
+    } else {
+      return {
+        tag: tag,
+        schema: member
+      };
+    }
+  });
+  if (arms.length === members.length) {
+    return arms;
+  }
+}
+
+function classify(schema) {
+  let match = Sury.$Metadata_get(schema, unionNameId);
+  let match$1 = armsOf(schema);
+  if (match !== undefined && match$1 !== undefined) {
+    return [
+      match,
+      match$1
+    ];
+  }
+}
+
+function isUnnamedUnion(schema) {
+  if (Stdlib_Option.isNone(Sury.$Metadata_get(schema, unionNameId))) {
+    return Stdlib_Option.isSome(armsOf(schema));
+  } else {
+    return false;
+  }
+}
+
+function stampInto(schema, json) {
+  let match = classify(schema);
+  if (match === undefined) {
+    return stampMembers(schema, json);
+  }
+  let obj = Stdlib_JSON.Decode.object(json);
+  if (obj === undefined) {
+    return;
+  }
+  let tag = Stdlib_Option.flatMap(obj["TAG"], Stdlib_JSON.Decode.string);
+  if (tag === undefined) {
+    return;
+  }
+  obj[typenameKey] = match[0] + tag;
+  let match$1 = match[1].find(a => a.tag === tag);
+  if (match$1 !== undefined) {
+    return stampMembers(match$1.schema, json);
+  }
+}
+
+function stampMembers(schema, json) {
+  switch (schema.type) {
+    case "array" :
+      let additionalItems = schema.additionalItems;
+      let itemSchema = schema.items[0];
+      let itemSchema$1 = itemSchema !== undefined ? itemSchema : (
+          additionalItems === "strip" || additionalItems === "strict" ? undefined : additionalItems
+        );
+      let match = Stdlib_JSON.Decode.array(json);
+      if (itemSchema$1 !== undefined && match !== undefined) {
+        match.forEach(value => stampInto(itemSchema$1, value));
+        return;
+      } else {
+        return;
+      }
+    case "object" :
+      let obj = Stdlib_JSON.Decode.object(json);
+      if (obj !== undefined) {
+        Object.entries(schema.properties).forEach(param => {
+          let value = obj[param[0]];
+          if (value !== undefined) {
+            return stampInto(param[1], value);
+          }
+        });
+        return;
+      } else {
+        return;
+      }
+    default:
+      let inner = Semantic$Reventless.unwrapOptional(schema);
+      if (inner !== undefined) {
+        return stampInto(inner, json);
+      } else {
+        return;
+      }
+  }
+}
+
+function fieldsOf(schema) {
+  if (schema.type === "object") {
+    return Stdlib_Array.filterMap(Object.entries(schema.properties), param => {
+      let propSchema = param[1];
+      if (Stdlib_Option.isSome(armsOf(propSchema))) {
+        return [
+          param[0],
+          Sury.$Metadata_get(propSchema, unionNameId)
+        ];
+      }
+    });
+  } else {
+    return [];
+  }
+}
+
+export {
+  unionNameId,
+  named,
+  getName,
+  memberTypeName,
+  typenameKey,
+  isPositionalName,
+  armsOf,
+  classify,
+  isUnnamedUnion,
+  stampInto,
+  stampMembers,
+  fieldsOf,
+}
+/* unionNameId Not a pure module */

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");