@reventlessdev/reventless-spec 3.0.0-alpha.90 → 3.0.0-alpha.92

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 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.92 (2026-08-01)
+
+* feat(aws,core,spec)!: qualify store prefixes by plugin and refuse name collisions ([da39405](https://github.com/ReventlessDev/reventless-core/commit/da394059d9f8f981bf7adc79e2c1ce2b429e0267))
+### Features
+
+* **spec:** a coordinate is one declared point, not two fields and a name guess ([bfe2f90](https://github.com/ReventlessDev/reventless-core/commit/bfe2f90241492422d6c242e3f50e31b81ed2a010))
+
+### BREAKING CHANGES
+
+* objects minted under the old bare prefix are orphaned and their
+refs unresolvable. The migration is `seed:reset` for the owning plugin, then
+re-seed. Legacy-prefix grandfathering was considered and deliberately dropped —
+it would have added a permanent prefix SET across the deploy argument, both store
+configs, the presign IAM fan-out, the release scope check and the stack output,
+to spare a disposable stack one wipe.
+
+
+
+# 3.0.0-alpha.91 (2026-08-01)
+
+### Bug Fixes
+
+* **spec,core:** heal a missing scalar on read ([de9a98e](https://github.com/ReventlessDev/reventless-core/commit/de9a98ec5fe11ec19bef80626e99244d9c30a6b1))
+* **spec,core:** make the storageRef annotation optional, as its readers already are ([c8477c5](https://github.com/ReventlessDev/reventless-core/commit/c8477c5c34384b864c06716dc5896310629dc349))
+
+
 # 3.0.0-alpha.90 (2026-08-01)
 
 ### Features

package/package.json

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

package/src/components/CapabilityManifest.res

@@ -56,7 +56,7 @@ let fromStructure = (structure: Plugin.pluginStructure): t => {
       key,
       declaredBy: declarations->Array.filterMap(d =>
         d.store == key
-          ? Some({component: d.component, field: d.field, annotation: d.annotation})
+          ? Some({component: d.component, field: d.field, annotation: ?d.annotation})
           : None
       ),
     }),

package/src/components/Plugin.res

@@ -395,13 +395,26 @@ than reconstructed: only here is the owning plugin unambiguous, so anything
 downstream would have to infer it by comparing a registered plugin name with
 whatever name a deploy manifest happened to use, and those were never required
 to match.
+
+Optional for the same reason `CapabilityManifest.provenance` and
+`PlatformCodegen.provenance` — the two places this value travels onward to —
+already declare it optional: an event stored before the field existed cannot
+say what the source said, and a reader that cannot say omits the claim rather
+than inventing one. Every definition emitted now carries it.
+
+That is not a stylistic preference. It was first added here as a required
+`string` while events written without it were already stored, and since the
+lifecycle aggregate replays its own log before every decision, those events
+stopped decoding and the plugin's registration froze for two days. `None` is
+also the honest value: `""` would assert the author wrote an empty annotation.
+See the schema-evolution note on `pluginStructure` below.
 */
 @schema
 type requiredStoreDeclaration = {
   store: string,
   component: string,
   field: string,
-  annotation: string,
+  annotation: @s.matches(stringOptionSchema) option<string>,
 }
 
 let requiredStoreDeclarationArrayOptionSchema = _jsNullable(
@@ -409,6 +422,32 @@ let requiredStoreDeclarationArrayOptionSchema = _jsNullable(
   (),
 )
 
+/**
+Adding a field here? It has to be a shape a stale event can be healed into.
+
+Everything reachable from `pluginDefinition` is persisted in the Plugin lifecycle
+aggregate's event log, and that aggregate replays its own log before every
+decision. Events already written do not have your new field, so if decoding one
+of them throws, the aggregate cannot process ANY command for that plugin — it
+stops answering the deploy handshake and its registration silently freezes at
+whatever version connected last.
+
+`Message.parseJsonTolerant` heals a stale event on read, but only for shapes it
+can supply a value for: a `T | null` union (→ `None`), an array (→ `[]`), a
+mandatory enum (→ first variant), a nested object (→ recursively filled), and a
+scalar (→ `""` / `0` / `false`, logged as a warning because it is a fabricated
+value, not a derived one).
+
+So: **prefer `js_nullable` for anything genuinely optional**, and expect a scalar
+addition to show up as a warning in the logs of every deployment that still holds
+older events. A field that can be absent should say so in its type rather than
+lean on the healer.
+
+The regression suite for this is `PluginLifecycleCorpusTest` in reventless-core,
+which decodes frozen payloads captured off a deployed log. If it goes red naming
+your field, re-shape the field — do not re-cut the fixtures. Background:
+`docs/analysis/plugin-definition-schema-evolution-wedge.md`.
+*/
 @schema
 type pluginStructure = {
   readModels: array<queryableDef>,

package/src/components/Plugin.res.mjs

@@ -182,7 +182,7 @@ let requiredStoreDeclarationSchema = S.schema(s => ({
   store: s.m(S.string),
   component: s.m(S.string),
   field: s.m(S.string),
-  annotation: s.m(S.string)
+  annotation: s.m(stringOptionSchema)
 }));
 
 let requiredStoreDeclarationArrayOptionSchema = SuryResMjs.js_nullable(S.array(requiredStoreDeclarationSchema));

package/src/generator/PlatformCodegen.res

@@ -106,6 +106,62 @@ let renderEntry = (entry: unionEntry): result<array<string>, string> =>
     }
   }
 
+/**
+Two deployables each claiming to own one plugin name.
+
+Nothing else in the toolchain catches this. The deploy manifest's keys are
+*deployable* names with no rule relating them to registered ones, and the Plugin
+aggregate is keyed by the registered name — so a second plugin registering an
+existing name is not rejected but read as a **new version of the first**, and
+silently supersedes it in the registry.
+
+Ownership is read from the annotation as authored, which is the one signal that
+separates a duplicate from legitimate sharing: an **unqualified**
+`@storageRef("productImages")` means "a store of my own plugin", so the
+deployable that wrote it is the plugin the key names. A **qualified**
+`@storageRef("Catalog.productImages")` points at someone else's store and says
+nothing about who owns it — that is the sanctioned cross-plugin form and must not
+trip this.
+
+Partial by construction: it can only see plugins that declare a store, because
+capability manifests are the only per-plugin input the generator reads. A
+duplicate between two store-less plugins is invisible here and stays uncaught.
+*/
+let duplicatePluginOwners = (entries: array<unionEntry>): array<(string, array<string>)> => {
+  let owners: dict<array<string>> = Dict.make()
+  entries->Array.forEach(entry =>
+    switch splitKey(entry.key) {
+    | None => ()
+    | Some((plugin, _)) =>
+      entry.declaredBy->Array.forEach(site =>
+        switch site.annotation {
+        // A site with no recorded annotation predates the recording, so it
+        // cannot be read either way and is skipped rather than guessed at.
+        | Some(annotation) if !(annotation->String.includes(".")) =>
+          let claimants = owners->Dict.get(plugin)->Option.getOr([])
+          if !(claimants->Array.includes(site.pluginName)) {
+            owners->Dict.set(plugin, Array.concat(claimants, [site.pluginName]))
+          }
+        | _ => ()
+        }
+      )
+    }
+  )
+  owners
+  ->Dict.toArray
+  ->Array.filter(((_, claimants)) => claimants->Array.length > 1)
+  ->Array.toSorted(((a, _), (b, _)) => String.compare(a, b))
+}
+
+let duplicatePluginMessage = ((plugin, claimants): (string, array<string>)): string =>
+  `Plugin name "${plugin}" is registered by more than one deployable: ${claimants->Array.join(
+      ", ",
+    )}.\n` ++
+  `  A platform keys its plugin registry by name, so the second registration is read as a new ` ++
+  `VERSION of the first and supersedes it.\n` ++
+  `  Give each deployable's plugin a distinct name (plugin.json), or — if these were meant to be ` ++
+  `one plugin — deploy only one of them.`
+
 let header = [
   "// AUTO-GENERATED — do not edit. Run `pnpm run generate:platform` to update.",
   "//",
@@ -122,14 +178,22 @@ let header = [
 let render = (manifests: array<pluginManifest>): result<string, string> => {
   let entries = union(manifests)
   let rendered = entries->Array.map(renderEntry)
-  switch rendered->Array.findMap(r =>
-    switch r {
-    | Error(e) => Some(e)
-    | Ok(_) => None
-    }
+  switch (
+    duplicatePluginOwners(entries),
+    rendered->Array.findMap(r =>
+      switch r {
+      | Error(e) => Some(e)
+      | Ok(_) => None
+      }
+    ),
   ) {
-  | Some(e) => Error(e)
-  | None => {
+  // Generation is the earliest point a deployment's plugins are seen together,
+  // so a name two of them both claim is refused here rather than left to
+  // supersede one of them at runtime.
+  | (duplicates, _) if duplicates->Array.length > 0 =>
+    Error(duplicates->Array.map(duplicatePluginMessage)->Array.join("\n\n"))
+  | (_, Some(e)) => Error(e)
+  | (_, None) => {
       let body = if entries->Array.length == 0 {
         ["let capabilities: array<ReventlessInfra.Platform.capability> = []"]
       } else {

package/src/generator/PlatformCodegen.res.mjs

@@ -71,6 +71,36 @@ function renderEntry(entry) {
   };
 }
 
+function duplicatePluginOwners(entries) {
+  let owners = {};
+  entries.forEach(entry => {
+    let match = splitKey(entry.key);
+    if (match === undefined) {
+      return;
+    }
+    let plugin = match[0];
+    entry.declaredBy.forEach(site => {
+      let annotation = site.annotation;
+      if (annotation === undefined) {
+        return;
+      }
+      if (annotation.includes(".")) {
+        return;
+      }
+      let claimants = Stdlib_Option.getOr(owners[plugin], []);
+      if (!claimants.includes(site.pluginName)) {
+        owners[plugin] = claimants.concat([site.pluginName]);
+        return;
+      }
+    });
+  });
+  return Object.entries(owners).filter(param => param[1].length > 1).toSorted((param, param$1) => Primitive_string.compare(param[0], param$1[0]));
+}
+
+function duplicatePluginMessage(param) {
+  return `Plugin name "` + param[0] + `" is registered by more than one deployable: ` + param[1].join(", ") + `.\n  A platform keys its plugin registry by name, so the second registration is read as a new VERSION of the first and supersedes it.\n  Give each deployable's plugin a distinct name (plugin.json), or — if these were meant to be one plugin — deploy only one of them.`;
+}
+
 let header = [
   "// AUTO-GENERATED — do not edit. Run `pnpm run generate:platform` to update.",
   "//",
@@ -84,17 +114,24 @@ let header = [
 function render(manifests) {
   let entries = union(manifests);
   let rendered = entries.map(renderEntry);
-  let e = Stdlib_Array.findMap(rendered, r => {
+  let match = duplicatePluginOwners(entries);
+  let match$1 = Stdlib_Array.findMap(rendered, r => {
     if (r.TAG === "Ok") {
       return;
     } else {
       return r._0;
     }
   });
-  if (e !== undefined) {
+  if (match.length !== 0) {
+    return {
+      TAG: "Error",
+      _0: match.map(duplicatePluginMessage).join("\n\n")
+    };
+  }
+  if (match$1 !== undefined) {
     return {
       TAG: "Error",
-      _0: e
+      _0: match$1
     };
   }
   let body = entries.length === 0 ? ["let capabilities: array<ReventlessInfra.Platform.capability> = []"] : ["let capabilities: array<ReventlessInfra.Platform.capability> = ["].concat(rendered.flatMap(r => Stdlib_Result.getOr(r, []))).concat(["]"]);
@@ -109,6 +146,8 @@ export {
   quote,
   splitKey,
   renderEntry,
+  duplicatePluginOwners,
+  duplicatePluginMessage,
   header,
   render,
 }

package/src/semantic/GeoPoint.res

@@ -0,0 +1,226 @@
+/**
+A location on the earth: a latitude and a longitude, as one value.
+
+## Why the pair is the value, not two fields beside each other
+
+Before this type a coordinate reached a map by three statements agreeing with
+each other: a read model flattened the point into `lat` and `lng` scalar fields,
+the UI guessed the pair back from those names, and a map was offered only when
+both guesses hit. Three things go wrong and all three are silent. Two points in
+one row mispair across each other — the two guesses are independent, so
+`pickupLat`/`pickupLng` beside `dropoffLat`/`dropoffLng` can pin a marker at one
+point's latitude and the other's longitude, a location in the sea drawn without
+an error. A pair named anything else — `y`/`x`, `northing`/`easting` — is
+invisible. And nothing checks the numbers: `lat: 181.0` is a `float` and passes
+every boundary in the system.
+
+Making the two numbers one value removes the pairing question, and gives the
+checks somewhere to live.
+
+## Latitude first here, longitude first only in GeoJSON
+
+This is the ordering trap the whole geo domain is famous for. GeoJSON (RFC 7946)
+encodes a point as `{"type":"Point","coordinates":[lng, lat]}` — **longitude
+first** — while every UI API and every human writes latitude first. A swapped
+pair is not an error anywhere: it is a plausible-looking marker in the wrong
+hemisphere.
+
+So the shape here keeps *names*, where an order cannot be got wrong, and the
+positional order exists in exactly one place: `toGeoJson`/`fromGeoJson` below.
+Any consumer that re-derives that conversion is re-deciding something already
+decided, and will eventually disagree with it.
+
+## The invariants are checked at decode
+
+Latitude runs −90…90 and longitude −180…180. Each range is a property of *one*
+field, so — unlike `DateRange`, whose ordering rule relates two fields and cannot
+be refined while sury 11-alpha miscompiles a record-level refinement — these sit
+on the field schemas and the boundary rejects a bad coordinate on the way in.
+This type has the same decode-time guarantee `Money` has, and more than
+`DateRange`; a reader arriving from `DateRange` would assume the weaker one.
+
+The two ranges are deliberately not one "coordinate" check: latitude saturates
+at the poles and longitude wraps at the antimeridian, and ±90 versus ±180 is the
+whole of the difference between them.
+
+## How a field declares it
+
+The field's declared type *is* `GeoPoint.t`, and sury-ppx resolves it to this
+module's `schema`:
+
+```rescript
+@schema type state = {
+  customerId: string,
+  location: option<Reventless.GeoPoint.t>,
+}
+```
+
+which serializes as `{"lat": 48.2082, "lng": 16.3738}`.
+
+**Replacing a hand-rolled `{lat: float, lng: float}` record with this type is
+free** — the wire shape is identical, so every stored event decodes unchanged and
+no upcaster is owed. That is the cheapest of the three adoption paths a semantic
+type has, and it is the one most existing coordinate fields are on. It costs a
+log something only if it *collapses* two flattened scalar fields back into one,
+which rewrites that shape.
+*/
+
+/**
+Validate a latitude, saying why when it is out of range.
+
+The single statement of the rule; `latSchema` is derived from it, so there is
+nowhere for a second grammar to drift.
+*/
+let validateLat = (raw: float): result<float, string> =>
+  if !Float.isFinite(raw) {
+    Error(`a latitude must be a finite number of degrees, got ${Float.toString(raw)}`)
+  } else if raw < -90.0 || raw > 90.0 {
+    Error(
+      `a latitude runs from -90 to 90 degrees, got ${Float.toString(raw)}. ` ++
+      `A value beyond ±90 is usually a longitude in the latitude's place.`,
+    )
+  } else {
+    Ok(raw)
+  }
+
+/** Validate a longitude, saying why when it is out of range. The other half of
+    the pair, separate because ±180 is what makes it a longitude. */
+let validateLng = (raw: float): result<float, string> =>
+  if !Float.isFinite(raw) {
+    Error(`a longitude must be a finite number of degrees, got ${Float.toString(raw)}`)
+  } else if raw < -180.0 || raw > 180.0 {
+    Error(`a longitude runs from -180 to 180 degrees, got ${Float.toString(raw)}`)
+  } else {
+    Ok(raw)
+  }
+
+/** The latitude's own schema. The check sits on the field rather than on the
+    pair because the range is a property of the one number — and because sury
+    11-alpha miscompiles a refinement wrapping a *record* schema. Refining the
+    field is both the honest placement and the one that works. */
+let latSchema: S.t<float> =
+  S.float->S.refine(s => raw =>
+    switch validateLat(raw) {
+    | Ok(_) => ()
+    | Error(why) => s.fail(why)
+    }
+  )
+
+/** The longitude's own schema, for the same reason. */
+let lngSchema: S.t<float> =
+  S.float->S.refine(s => raw =>
+    switch validateLng(raw) {
+    | Ok(_) => ()
+    | Error(why) => s.fail(why)
+    }
+  )
+
+@schema
+type t = {
+  /** Degrees north of the equator, −90…90. Negative is south. */
+  lat: @s.matches(latSchema) float,
+  /** Degrees east of the prime meridian, −180…180. Negative is west. */
+  lng: @s.matches(lngSchema) float,
+}
+
+/** The sury schema for a geo-point field, carrying the `geoPoint` semantic.
+
+    Shadows the schema sury-ppx derived from the type above: the derived one is
+    the shape, and this adds the marker the shape cannot carry. */
+let schema: S.t<t> = schema->Semantic.mark(~id=Semantic.Id.geoPoint)
+
+/** Build a validated point. Both coordinates are checked, and the message names
+    which one is wrong — the common mistake is a swapped pair, where the
+    longitude lands in the latitude and is the value that fails. */
+let make = (~lat: float, ~lng: float): result<t, string> =>
+  switch (validateLat(lat), validateLng(lng)) {
+  | (Error(why), _) | (Ok(_), Error(why)) => Error(why)
+  | (Ok(lat), Ok(lng)) => Ok({lat, lng})
+  }
+
+/**
+The point as text: latitude, then longitude — `"48.2082, 16.3738"`.
+
+Latitude first, the order a human reads and the opposite of GeoJSON's. Locale
+independent, matching the rest of the framework's formatters: the same value
+reads the same in every log line and every test.
+*/
+let format = (p: t): string => `${Float.toString(p.lat)}, ${Float.toString(p.lng)}`
+
+/** The mean radius of the earth in metres (IUGG R₁). One constant, so a distance
+    computed here and a distance computed elsewhere cannot disagree by their
+    choice of sphere. */
+let earthRadiusMetres = 6371008.8
+
+let toRadians = (degrees: float): float => degrees *. Math.Constants.pi /. 180.0
+
+/**
+The great-circle distance between two points, in metres.
+
+Haversine on a spherical earth, which is accurate to roughly 0.5% — right for
+radii, catchments and sorting by nearness, and wrong for surveying. Anything
+needing geodesic accuracy needs an ellipsoid and a library that models one.
+
+It lives here rather than at each consumer because "how far" is the operation
+every geo consumer eventually wants, and writing it per consumer is where the
+degrees-versus-radians and earth-radius mistakes live — mistakes that produce a
+plausible number rather than a failure.
+*/
+let distanceTo = (a: t, b: t): float => {
+  let lat1 = toRadians(a.lat)
+  let lat2 = toRadians(b.lat)
+  let dLat = toRadians(b.lat -. a.lat)
+  let dLng = toRadians(b.lng -. a.lng)
+  let h =
+    Math.sin(dLat /. 2.0) *. Math.sin(dLat /. 2.0) +.
+      Math.cos(lat1) *. Math.cos(lat2) *. Math.sin(dLng /. 2.0) *. Math.sin(dLng /. 2.0)
+  2.0 *. Math.asin(Math.sqrt(Math.min(1.0, h))) *. earthRadiusMetres
+}
+
+/**
+The point as a GeoJSON `Point` geometry — `{"type":"Point","coordinates":[lng, lat]}`.
+
+**This is the one place the positional order is written.** Longitude first, per
+RFC 7946. Every map library, spatial database and geocoding API on that side of
+the boundary expects it; every human on this side does not, which is why the
+stored shape keeps names and only this function turns them into an array.
+*/
+let toGeoJson = (p: t): JSON.t =>
+  JSON.Encode.object(
+    Dict.fromArray([
+      ("type", JSON.Encode.string("Point")),
+      ("coordinates", JSON.Encode.array([JSON.Encode.float(p.lng), JSON.Encode.float(p.lat)])),
+    ]),
+  )
+
+/**
+Read a GeoJSON `Point` geometry back, validating both coordinates.
+
+The inverse of `toGeoJson`, and the only other place the positional order is
+read. Returns `Error` for a geometry that is not a point, for coordinates that
+are not two numbers, and — via `make` — for numbers out of range, which is what
+catches a `[lat, lng]` array produced by something that got the order wrong,
+whenever the latitude exceeds ±90.
+*/
+let fromGeoJson = (json: JSON.t): result<t, string> =>
+  switch json->JSON.Decode.object {
+  | None => Error("a GeoJSON point is an object")
+  | Some(o) =>
+    switch o->Dict.get("type")->Option.flatMap(JSON.Decode.string) {
+    | Some("Point") =>
+      switch o->Dict.get("coordinates")->Option.flatMap(JSON.Decode.array) {
+      | Some(coords) =>
+        switch (
+          coords->Array.get(0)->Option.flatMap(JSON.Decode.float),
+          coords->Array.get(1)->Option.flatMap(JSON.Decode.float),
+        ) {
+        // [lng, lat] — the RFC's order, not this module's.
+        | (Some(lng), Some(lat)) => make(~lat, ~lng)
+        | _ => Error("a GeoJSON point's coordinates are two numbers, [lng, lat]")
+        }
+      | None => Error("a GeoJSON point has a coordinates array")
+      }
+    | Some(other) => Error(`expected a GeoJSON Point, got ${other}`)
+    | None => Error("a GeoJSON geometry has a type")
+    }
+  }

package/src/semantic/GeoPoint.res.mjs

@@ -0,0 +1,190 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+function validateLat(raw) {
+  if (isFinite(raw)) {
+    if (raw < -90.0 || raw > 90.0) {
+      return {
+        TAG: "Error",
+        _0: `a latitude runs from -90 to 90 degrees, got ` + raw.toString() + `. A value beyond ±90 is usually a longitude in the latitude's place.`
+      };
+    } else {
+      return {
+        TAG: "Ok",
+        _0: raw
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: `a latitude must be a finite number of degrees, got ` + raw.toString()
+    };
+  }
+}
+
+function validateLng(raw) {
+  if (isFinite(raw)) {
+    if (raw < -180.0 || raw > 180.0) {
+      return {
+        TAG: "Error",
+        _0: `a longitude runs from -180 to 180 degrees, got ` + raw.toString()
+      };
+    } else {
+      return {
+        TAG: "Ok",
+        _0: raw
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: `a longitude must be a finite number of degrees, got ` + raw.toString()
+    };
+  }
+}
+
+let latSchema = S.refine(S.float, s => (raw => {
+  let why = validateLat(raw);
+  if (why.TAG === "Ok") {
+    return;
+  } else {
+    return s.fail(why._0, undefined);
+  }
+}));
+
+let lngSchema = S.refine(S.float, s => (raw => {
+  let why = validateLng(raw);
+  if (why.TAG === "Ok") {
+    return;
+  } else {
+    return s.fail(why._0, undefined);
+  }
+}));
+
+let schema = S.schema(s => ({
+  lat: s.m(latSchema),
+  lng: s.m(lngSchema)
+}));
+
+let schema$1 = Semantic$Reventless.mark(schema, Semantic$Reventless.Id.geoPoint, undefined);
+
+function make(lat, lng) {
+  let match = validateLat(lat);
+  let match$1 = validateLng(lng);
+  if (match.TAG === "Ok") {
+    if (match$1.TAG === "Ok") {
+      return {
+        TAG: "Ok",
+        _0: {
+          lat: match._0,
+          lng: match$1._0
+        }
+      };
+    } else {
+      return {
+        TAG: "Error",
+        _0: match$1._0
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: match._0
+    };
+  }
+}
+
+function format(p) {
+  return p.lat.toString() + `, ` + p.lng.toString();
+}
+
+function toRadians(degrees) {
+  return degrees * Math.PI / 180.0;
+}
+
+function distanceTo(a, b) {
+  let lat1 = toRadians(a.lat);
+  let lat2 = toRadians(b.lat);
+  let dLat = toRadians(b.lat - a.lat);
+  let dLng = toRadians(b.lng - a.lng);
+  let h = Math.sin(dLat / 2.0) * Math.sin(dLat / 2.0) + Math.cos(lat1) * Math.cos(lat2) * Math.sin(dLng / 2.0) * Math.sin(dLng / 2.0);
+  return 2.0 * Math.asin(Math.sqrt(Math.min(1.0, h))) * 6371008.8;
+}
+
+function toGeoJson(p) {
+  return Object.fromEntries([
+    [
+      "type",
+      "Point"
+    ],
+    [
+      "coordinates",
+      [
+        p.lng,
+        p.lat
+      ]
+    ]
+  ]);
+}
+
+function fromGeoJson(json) {
+  let o = Stdlib_JSON.Decode.object(json);
+  if (o === undefined) {
+    return {
+      TAG: "Error",
+      _0: "a GeoJSON point is an object"
+    };
+  }
+  let other = Stdlib_Option.flatMap(o["type"], Stdlib_JSON.Decode.string);
+  if (other === undefined) {
+    return {
+      TAG: "Error",
+      _0: "a GeoJSON geometry has a type"
+    };
+  }
+  if (other !== "Point") {
+    return {
+      TAG: "Error",
+      _0: `expected a GeoJSON Point, got ` + other
+    };
+  }
+  let coords = Stdlib_Option.flatMap(o["coordinates"], Stdlib_JSON.Decode.array);
+  if (coords === undefined) {
+    return {
+      TAG: "Error",
+      _0: "a GeoJSON point has a coordinates array"
+    };
+  }
+  let match = Stdlib_Option.flatMap(coords[0], Stdlib_JSON.Decode.float);
+  let match$1 = Stdlib_Option.flatMap(coords[1], Stdlib_JSON.Decode.float);
+  if (match !== undefined && match$1 !== undefined) {
+    return make(match$1, match);
+  } else {
+    return {
+      TAG: "Error",
+      _0: "a GeoJSON point's coordinates are two numbers, [lng, lat]"
+    };
+  }
+}
+
+let earthRadiusMetres = 6371008.8;
+
+export {
+  validateLat,
+  validateLng,
+  latSchema,
+  lngSchema,
+  schema$1 as schema,
+  make,
+  format,
+  earthRadiusMetres,
+  toRadians,
+  distanceTo,
+  toGeoJson,
+  fromGeoJson,
+}
+/* latSchema Not a pure module */

package/src/semantic/Semantic.res

@@ -69,6 +69,13 @@ module Id = {
   // is an object on the wire; unlike it, adopting it as a *new* optional field
   // is additive — an absent optional decodes to `None`.
   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.
+  let geoPoint = "geoPoint"
 }
 
 let semanticId: S.Metadata.Id.t<t> = S.Metadata.Id.make(~namespace="reventless", ~name="semantic")

package/src/semantic/Semantic.res.mjs

@@ -14,7 +14,8 @@ let Id = {
   duration: "duration",
   color: "color",
   money: "money",
-  dateRange: "dateRange"
+  dateRange: "dateRange",
+  geoPoint: "geoPoint"
 };
 
 let semanticId = S.Metadata.Id.make("reventless", "semantic");

package/src/types/Message.res

@@ -156,27 +156,53 @@ type commandJson = {
 // message); only when it throws do we schema-guide the raw JSON and retry once. The fill
 // walks the target sury schema and inserts, for any absent field, the value that field's
 // schema expects: `null` for a `T | null` union (→ `None`), `[]` for a missing array, the
-// first variant of a mandatory enum (`kind` → `Domain`), and a filled `{}` for a missing
-// nested object. It descends only into values actually present, matches tagged-union
-// members by their `TAG` const, is purely additive (clones via a JSON round-trip; never
-// re-encodes through the schema), is idempotent on valid data, and falls back to the
-// ORIGINAL error when the fill doesn't resolve the failure — so genuine corruption still
-// surfaces. See docs/plans/platform-infrastructure-in-plugin-list.md (durable fix option 2).
-let fillMissingDefaults: (S.t<'a>, JSON.t) => JSON.t = %raw(`function(schema, json){
+// first variant of a mandatory enum (`kind` → `Domain`), a filled `{}` for a missing
+// nested object, and a zero value for a missing scalar. It descends only into values
+// actually present, matches tagged-union members by their `TAG` const, is purely additive
+// (clones via a JSON round-trip; never re-encodes through the schema), is idempotent on
+// valid data, and falls back to the ORIGINAL error when the fill doesn't resolve the
+// failure — so genuine corruption still surfaces.
+// See docs/plans/platform-infrastructure-in-plugin-list.md (durable fix option 2).
+//
+// The scalar arm is the odd one out and is deliberately noisy. Every other fill is
+// *derived* — the schema states what an absent value means, and the fill supplies exactly
+// that. A scalar has no such statement, so `""` / `0` / `false` is a value this code
+// invented: right for a descriptive field added later, wrong for a field that carries
+// meaning. It also widens what can be masked, since a genuinely truncated payload now
+// decodes where it used to throw. Every scalar fill is therefore reported to the caller
+// and logged, so healing stays findable instead of becoming the silent default. Without
+// it, a required-scalar addition freezes an aggregate outright — see
+// docs/analysis/plugin-definition-schema-evolution-wedge.md.
+//
+// `bigint` is excluded on purpose: it has no JSON representation, so any value invented
+// here would fail the retry anyway and mask the real error path.
+//
+// `scalarFills` is an out-parameter: the walker pushes `path := value` for each scalar it
+// invented.
+let fillMissingDefaults: (S.t<'a>, JSON.t, array<string>) => JSON.t = %raw(`function(schema, json, scalarFills){
   function isSchema(x){ return x && typeof x === "object" && typeof x.type === "string"; }
   function firstConst(anyOf){ var m=(anyOf||[]).find(function(s){return s.const!==undefined;}); return m ? m.const : undefined; }
-  function fill(schema, value){
+  function scalarDefault(schema){
+    if(schema.const!==undefined) return schema.const;
+    switch(schema.type){
+      case "string": return "";
+      case "number": return 0;
+      case "boolean": return false;
+      default: return undefined;
+    }
+  }
+  function fill(schema, value, path){
     if(!isSchema(schema)) return value;
     switch(schema.type){
       case "object": {
         if(value===undefined){ value={}; }
         else if(value===null || typeof value!=="object" || Array.isArray(value)) return value;
         var items=schema.items||[];
-        for(var i=0;i<items.length;i++){ var it=items[i]; value[it.location]=fill(it.schema, value[it.location]); }
+        for(var i=0;i<items.length;i++){ var it=items[i]; value[it.location]=fill(it.schema, value[it.location], path+"."+it.location); }
         return value;
       }
       case "array": {
-        if(Array.isArray(value)){ var el=schema.additionalItems; return isSchema(el) ? value.map(function(v){return fill(el,v);}) : value; }
+        if(Array.isArray(value)){ var el=schema.additionalItems; return isSchema(el) ? value.map(function(v,ix){return fill(el,v,path+"["+ix+"]");}) : value; }
         if(value===undefined) return [];
         return value;
       }
@@ -185,24 +211,30 @@ let fillMissingDefaults: (S.t<'a>, JSON.t) => JSON.t = %raw(`function(schema, js
         if(value===undefined){
           if(has.null) return null;
           var c=firstConst(schema.anyOf); if(c!==undefined) return c;
-          var obj=(schema.anyOf||[]).find(function(s){return s.type==="object";}); if(obj) return fill(obj,{});
+          var obj=(schema.anyOf||[]).find(function(s){return s.type==="object";}); if(obj) return fill(obj,{},path);
           return undefined;
         }
         if(value===null) return null;
         var members=schema.anyOf||[];
-        if(Array.isArray(value)){ var a=members.find(function(s){return s.type==="array";}); return a ? fill(a,value) : value; }
+        if(Array.isArray(value)){ var a=members.find(function(s){return s.type==="array";}); return a ? fill(a,value,path) : value; }
         if(typeof value==="object"){
           var m=members.find(function(s){return s.type==="object" && (s.items||[]).some(function(it){return it.location==="TAG" && it.schema.const===value.TAG;});});
           if(!m) m=members.find(function(s){return s.type==="object";});
-          return m ? fill(m,value) : value;
+          return m ? fill(m,value,path) : value;
         }
         return value;
       }
-      default: return value;
+      default: {
+        if(value!==undefined) return value;
+        var d=scalarDefault(schema);
+        if(d===undefined) return value;
+        scalarFills.push(path + " := " + JSON.stringify(d));
+        return d;
+      }
     }
   }
   // Clone via JSON round-trip (json is already pure JSON) so the caller's value is never mutated.
-  return fill(schema, JSON.parse(JSON.stringify(json)));
+  return fill(schema, JSON.parse(JSON.stringify(json)), "");
 }`)
 
 // Strict parse with a single schema-migration-on-read retry (see fillMissingDefaults).
@@ -210,8 +242,22 @@ let parseJsonTolerant = (json, schema) =>
   switch json->S.parseJsonOrThrow(schema) {
   | value => value
   | exception firstErr =>
-    switch fillMissingDefaults(schema, json)->S.parseJsonOrThrow(schema) {
-    | value => value
+    let scalarFills = []
+    switch fillMissingDefaults(schema, json, scalarFills)->S.parseJsonOrThrow(schema) {
+    | value =>
+      // Only the invented values are worth a line. A heal that used nothing but
+      // schema-derived defaults is the mechanism working as designed.
+      if scalarFills->Array.length > 0 {
+        Console.warn(
+          `[reventless] decoded a stored message by inventing ${scalarFills
+            ->Array.length
+            ->Int.toString} missing scalar field(s): ${scalarFills->Array.join(
+              ", ",
+            )}. A required scalar was added to a persisted type after this message was ` ++
+          `written; the value above is fabricated, not recovered. Prefer a js_nullable (T | null) field.`,
+        )
+      }
+      value
     | exception _ => throw(firstErr)
     }
   }

package/src/types/Message.res.mjs

@@ -35,21 +35,30 @@ let commandJsonSchema = S.schema(s => ({
   delay: s.m(S.option(S.int))
 }));
 
-let fillMissingDefaults = (function(schema, json){
+let fillMissingDefaults = (function(schema, json, scalarFills){
   function isSchema(x){ return x && typeof x === "object" && typeof x.type === "string"; }
   function firstConst(anyOf){ var m=(anyOf||[]).find(function(s){return s.const!==undefined;}); return m ? m.const : undefined; }
-  function fill(schema, value){
+  function scalarDefault(schema){
+    if(schema.const!==undefined) return schema.const;
+    switch(schema.type){
+      case "string": return "";
+      case "number": return 0;
+      case "boolean": return false;
+      default: return undefined;
+    }
+  }
+  function fill(schema, value, path){
     if(!isSchema(schema)) return value;
     switch(schema.type){
       case "object": {
         if(value===undefined){ value={}; }
         else if(value===null || typeof value!=="object" || Array.isArray(value)) return value;
         var items=schema.items||[];
-        for(var i=0;i<items.length;i++){ var it=items[i]; value[it.location]=fill(it.schema, value[it.location]); }
+        for(var i=0;i<items.length;i++){ var it=items[i]; value[it.location]=fill(it.schema, value[it.location], path+"."+it.location); }
         return value;
       }
       case "array": {
-        if(Array.isArray(value)){ var el=schema.additionalItems; return isSchema(el) ? value.map(function(v){return fill(el,v);}) : value; }
+        if(Array.isArray(value)){ var el=schema.additionalItems; return isSchema(el) ? value.map(function(v,ix){return fill(el,v,path+"["+ix+"]");}) : value; }
         if(value===undefined) return [];
         return value;
       }
@@ -58,35 +67,47 @@ let fillMissingDefaults = (function(schema, json){
         if(value===undefined){
           if(has.null) return null;
           var c=firstConst(schema.anyOf); if(c!==undefined) return c;
-          var obj=(schema.anyOf||[]).find(function(s){return s.type==="object";}); if(obj) return fill(obj,{});
+          var obj=(schema.anyOf||[]).find(function(s){return s.type==="object";}); if(obj) return fill(obj,{},path);
           return undefined;
         }
         if(value===null) return null;
         var members=schema.anyOf||[];
-        if(Array.isArray(value)){ var a=members.find(function(s){return s.type==="array";}); return a ? fill(a,value) : value; }
+        if(Array.isArray(value)){ var a=members.find(function(s){return s.type==="array";}); return a ? fill(a,value,path) : value; }
         if(typeof value==="object"){
           var m=members.find(function(s){return s.type==="object" && (s.items||[]).some(function(it){return it.location==="TAG" && it.schema.const===value.TAG;});});
           if(!m) m=members.find(function(s){return s.type==="object";});
-          return m ? fill(m,value) : value;
+          return m ? fill(m,value,path) : value;
         }
         return value;
       }
-      default: return value;
+      default: {
+        if(value!==undefined) return value;
+        var d=scalarDefault(schema);
+        if(d===undefined) return value;
+        scalarFills.push(path + " := " + JSON.stringify(d));
+        return d;
+      }
     }
   }
   // Clone via JSON round-trip (json is already pure JSON) so the caller's value is never mutated.
-  return fill(schema, JSON.parse(JSON.stringify(json)));
+  return fill(schema, JSON.parse(JSON.stringify(json)), "");
 });
 
 function parseJsonTolerant(json, schema) {
   try {
     return S.parseJsonOrThrow(json, schema);
   } catch (firstErr) {
+    let scalarFills = [];
+    let value;
     try {
-      return S.parseJsonOrThrow(fillMissingDefaults(schema, json), schema);
+      value = S.parseJsonOrThrow(fillMissingDefaults(schema, json, scalarFills), schema);
     } catch (exn) {
       throw firstErr;
     }
+    if (scalarFills.length !== 0) {
+      console.warn(`[reventless] decoded a stored message by inventing ` + scalarFills.length.toString() + ` missing scalar field(s): ` + scalarFills.join(", ") + `. A required scalar was added to a persisted type after this message was written; the value above is fabricated, not recovered. Prefer a js_nullable (T | null) field.`);
+    }
+    return value;
   }
 }