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

package/CHANGELOG.md

@@ -3,6 +3,24 @@
 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

package/package.json

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

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