@reventlessdev/reventless-spec 3.0.0-alpha.100

package/src/semantic/DateRange.res

@@ -0,0 +1,148 @@
+/**
+A span of time: two ISO-8601 instants, a start and an end, as one value.
+
+## Why the pair is the value, not two fields beside each other
+
+Before this type a span was a *guess*. A view that wanted a calendar, a timeline
+or a gantt bar asked which fields were date-like and took the first named
+`start…` and the first named `end…`, independently. Three things go wrong and
+all three are silent: two intervals in one row mispair across each other (a bar
+drawn from one interval's start to the other's end); an interval named anything
+else — `checkIn`/`checkOut`, `from`/`to` — is invisible; and a lone `started…`
+point pairs with whatever `end…` is nearby. Making the two instants one value
+removes the pairing question: a consumer either holds the span or it does not.
+
+The parts keep their own `dateTime` marker, so a walker that only understands
+date-times still sees them, and the whole carries `dateRange` besides. That is
+the same layering `Money` uses — the amount keeps being a number, the composite
+adds the meaning the number cannot carry.
+
+## `[start, end)` — end exclusive
+
+A range runs from `start` up to but not including `end`. `09:00–11:00` and
+`11:00–13:00` are adjacent, not overlapping, and an all-day grid needs no
+off-by-one-millisecond convention invented per consumer. This is a decision, not
+a default: `overlaps` and `contains` are the only places it is written, and no
+layout may re-decide it.
+
+## Why the ordering rule is not enforced at decode
+
+`start <= end` relates two fields, so — unlike `Money`'s wholeness, which is a
+property of one field and rides on that field's schema — it is a *record-level*
+invariant. sury 11.0.0-alpha.4 miscompiles a refinement wrapping a record schema
+(it hoists the result object above the field reads, so parse and serialize throw
+`Cannot access 'v0' before initialization`), and the pin has not moved. So the
+rule lives in `validate`/`make` and **the schema does not enforce it at decode**.
+
+This is the first semantic type in this library whose invariant the boundary does
+not check: `Money` rejects a fractional minor unit on the way in; `DateRange`
+will accept a range that ends before it starts if one is ever written. A reader
+who assumes parity with `Money` assumes wrong. When sury fixes the record
+refinement the rule moves into the schema and `validate` stays as its single
+definition — the relationship `Money.validateAmount` has with `amountSchema`.
+
+Parsing is `Date.fromString` on each instant. A range whose strings do not parse
+is a decode-time problem the `DateTime` marker does not currently catch either,
+so there is no second validation layer here — a reversed *parseable* range is
+what `validate` catches, and an unparseable one is out of both their scope.
+
+## How a field declares it
+
+The field's declared type *is* `DateRange.t`, and sury-ppx resolves it to this
+module's `schema`:
+
+```rescript
+@schema type state = {
+  orderId: string,
+  deliveryWindow: option<Reventless.DateRange.t>,
+}
+```
+
+which serializes as `{"start": "2026-03-02T09:00:00Z", "end": "2026-03-02T11:00:00Z"}`.
+
+**Introduced as a new optional field it is additive** — an absent optional
+decodes to `None` for events written before it existed, so no upcaster and no
+projection rebuild. It costs a log something only if it *collapses* an existing
+`start*`/`end*` pair, which rewrites the wire shape the way `Money` rewrote
+`price: float`. That collapse belongs to whoever builds the upcaster.
+*/
+
+@schema
+type t = {
+  /** The instant the range opens, inclusive. */
+  start: @s.matches(DateTime.string) string,
+  /** The instant the range closes, **exclusive** — the range does not contain
+      it. `@as("end")` puts `end` on the wire (where the UI's own `GanttChart`
+      already spells it that way); `end_` is the source spelling because `end`
+      is awkward as a bare ReScript field. */
+  @as("end") end_: @s.matches(DateTime.string) string,
+}
+
+/** The sury schema for a date-range field, carrying the `dateRange` 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. The ordering rule
+    is deliberately *not* refined in here — see the module doc. */
+let schema: S.t<t> = schema->Semantic.mark(~id=Semantic.Id.dateRange)
+
+/** An instant as milliseconds since the epoch — `NaN` if it does not parse. The
+    one place a range's strings become numbers, so end-exclusivity and the
+    ordering rule are all expressed against a single parse. */
+let millis = (instant: string): float => instant->Date.fromString->Date.getTime
+
+/**
+Validate a range's ordering, saying why when it is reversed.
+
+The single statement of the `start <= end` rule; `make` is derived from it, and
+`schema` will be once sury's record refinement is fixed. An unparseable instant
+is not caught here (see the module doc) — a reversed range means two instants
+that both parse, the earlier one second.
+*/
+let validate = (range: t): result<t, string> =>
+  millis(range.start) > millis(range.end_)
+    ? Error(
+        `a range ends before it starts: ${range.start} is after ${range.end_}. ` ++
+        `A range is [start, end) — the start is the earlier instant.`,
+      )
+    : Ok(range)
+
+/** Build a validated range from its two instants. `end` is exclusive. */
+let make = (~start: string, ~end_: string): result<t, string> => validate({start, end_})
+
+/**
+The range's length as a `Duration`, in whole seconds — the composite composing
+with one of the branded scalars.
+
+Total: a valid range has a non-negative length, and a zero-length range is
+zero seconds. Truncated to whole seconds because that is what `Duration` is.
+*/
+let duration = (range: t): Duration.t =>
+  Duration.unsafe(Math.trunc((millis(range.end_) -. millis(range.start)) /. 1000.0)->Float.toInt)
+
+/**
+Whether an instant falls within the range — at or after `start`, strictly before
+`end`. End-exclusive, so the instant that opens the next adjacent range is *not*
+contained by this one. One of the two places `[start, end)` is decided.
+*/
+let contains = (range: t, instant: string): bool => {
+  let t = millis(instant)
+  t >= millis(range.start) && t < millis(range.end_)
+}
+
+/**
+Whether two ranges share any instant. End-exclusive: `09:00–11:00` and
+`11:00–13:00` are adjacent and do *not* overlap. The other place `[start, end)`
+is decided — a layout that re-decides it will disagree with this.
+*/
+let overlaps = (a: t, b: t): bool =>
+  millis(a.start) < millis(b.end_) && millis(b.start) < millis(a.end_)
+
+/**
+The range as text: the two instants with an en dash between them —
+`"2026-03-02T09:00:00Z – 2026-03-02T11:00:00Z"`.
+
+Locale-independent, matching the rest of the framework's formatters: the same
+value reads the same in every log line and every test. A calendar-style
+rendering is the presentation layer's job.
+*/
+let format = (range: t): string => `${range.start} – ${range.end_}`

package/src/semantic/DateRange.res.mjs

@@ -0,0 +1,74 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as DateTime$Reventless from "../types/DateTime.res.mjs";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+let schema = S.schema(s => ({
+  start: s.m(DateTime$Reventless.string),
+  end: s.m(DateTime$Reventless.string)
+}));
+
+let schema$1 = Semantic$Reventless.mark(schema, Semantic$Reventless.Id.dateRange, undefined);
+
+function millis(instant) {
+  return new Date(instant).getTime();
+}
+
+function validate(range) {
+  if (new Date(range.start).getTime() > new Date(range.end).getTime()) {
+    return {
+      TAG: "Error",
+      _0: `a range ends before it starts: ` + range.start + ` is after ` + range.end + `. A range is [start, end) — the start is the earlier instant.`
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: range
+    };
+  }
+}
+
+function make(start, end_) {
+  return validate({
+    start: start,
+    end: end_
+  });
+}
+
+function duration(range) {
+  return Math.trunc((new Date(range.end).getTime() - new Date(range.start).getTime()) / 1000.0) | 0;
+}
+
+function contains(range, instant) {
+  let t = new Date(instant).getTime();
+  if (t >= new Date(range.start).getTime()) {
+    return t < new Date(range.end).getTime();
+  } else {
+    return false;
+  }
+}
+
+function overlaps(a, b) {
+  if (new Date(a.start).getTime() < new Date(b.end).getTime()) {
+    return new Date(b.start).getTime() < new Date(a.end).getTime();
+  } else {
+    return false;
+  }
+}
+
+function format(range) {
+  return range.start + ` – ` + range.end;
+}
+
+export {
+  schema$1 as schema,
+  millis,
+  validate,
+  make,
+  duration,
+  contains,
+  overlaps,
+  format,
+}
+/* schema Not a pure module */

package/src/semantic/Duration.res

@@ -0,0 +1,53 @@
+/**
+Marks an `int` field as a length of time, in **seconds**.
+
+## Why a scalar, and why seconds are part of the type
+
+The obvious richer design is `{value, unit}`. It is not available here, and the
+reason is the reason this whole set of types is safe to add: a record is an
+*object* on the wire, so adopting it would turn every field that used it into a
+decode failure against events already written. These types are additive
+precisely because they stay scalars. A duration that carries its unit is a
+different type for a different plan, not a later version of this one — widening
+this one would retroactively hand an upcaster obligation to every field that had
+already adopted it.
+
+Seconds, because that is what the renderer reads: it formats `3660` as
+`"1h 1m"`. Milliseconds would be off by a factor of a thousand and would
+render as weeks, which is the same class of silent wrongness `Percent` avoids by
+matching its gauge.
+
+`int` is right here where it was wrong for `Bytes`: int32 seconds is 68 years,
+which no duration field needs to exceed.
+
+## The grammar
+
+A whole number of seconds, zero or greater. Zero is a real duration — an instant
+timeout, a zero-length window.
+
+@example
+```rescript
+@schema type state = {
+  jobId: string,
+  runtimeSeconds: @s.matches(Reventless.Duration.schema) int,
+}
+```
+*/
+
+/** The duration's representation, in seconds. Transparent `int`. */
+type t = int
+
+external unsafe: int => t = "%identity"
+external toInt: t => int = "%identity"
+
+/** Validate a number of seconds as a duration, saying why when it is not one. */
+let fromInt = (raw: int): result<t, string> =>
+  if raw < 0 {
+    Error(`a duration cannot be negative, got ${Int.toString(raw)} seconds`)
+  } else {
+    Ok(raw)
+  }
+
+/** The sury schema for a duration field, in seconds.
+    Use with `@s.matches(Reventless.Duration.schema)`. */
+let schema: S.t<t> = S.int->Semantic.refined(~id=Semantic.Id.duration, ~check=fromInt)

package/src/semantic/Duration.res.mjs

@@ -0,0 +1,26 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+function fromInt(raw) {
+  if (raw < 0) {
+    return {
+      TAG: "Error",
+      _0: `a duration cannot be negative, got ` + raw.toString() + ` seconds`
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: raw
+    };
+  }
+}
+
+let schema = Semantic$Reventless.refined(S.int, Semantic$Reventless.Id.duration, fromInt);
+
+export {
+  fromInt,
+  schema,
+}
+/* schema Not a pure module */

package/src/semantic/Email.res

@@ -0,0 +1,51 @@
+/**
+Marks a `string` field as an email address.
+
+## Why a type rather than a name
+
+An `email` field already renders as a mailto link today, because the UI guesses
+from the field's *name*. The guess is the whole problem: `contact`, `owner` and
+`notifyTo` hold addresses and are not guessed, `emailTemplate` is guessed and is
+not an address, and nothing anywhere checks that what was written is one. A type
+says it, and the check comes with it.
+
+## The grammar
+
+Sury's `S.email`, and nothing added. This is a case where the framework has no
+opinion worth having: address syntax is somebody else's specification, and a
+second regex here would only be a way to disagree with it.
+
+Note that a syntactically valid address is not a deliverable one — nothing here
+sends a probe. This rejects what is not an address, which is the part a boundary
+check can honestly do.
+
+@example
+```rescript
+@schema type command =
+  | InviteMember({
+      teamId: @s.matches(DcbTag.string) string,
+      email: @s.matches(Reventless.Email.schema) string,
+    })
+```
+*/
+
+/** The address's representation. Transparent `string`: the marker refines an
+    existing field rather than replacing it, so nothing stored changes. */
+type t = string
+
+external unsafe: string => t = "%identity"
+external toString: t => string = "%identity"
+
+// Sury's check, held once. `fromString` runs it rather than restating it, and
+// `schema` is built from `fromString`, so there is exactly one grammar here.
+let grammar: S.t<string> = S.string->S.email
+
+/** Validate a raw string as an email address, saying why when it is not one. */
+let fromString = (raw: string): result<t, string> =>
+  switch raw->S.parseOrThrow(grammar) {
+  | value => Ok(value)
+  | exception _ => Error(`expected an email address, got ${Semantic.showString(raw)}`)
+  }
+
+/** The sury schema for an email field. Use with `@s.matches(Reventless.Email.schema)`. */
+let schema: S.t<t> = S.string->Semantic.refined(~id=Semantic.Id.email, ~check=fromString)

package/src/semantic/Email.res.mjs

@@ -0,0 +1,31 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+let grammar = S.email(S.string, undefined);
+
+function fromString(raw) {
+  let value;
+  try {
+    value = S.parseOrThrow(raw, grammar);
+  } catch (exn) {
+    return {
+      TAG: "Error",
+      _0: `expected an email address, got ` + Semantic$Reventless.showString(raw)
+    };
+  }
+  return {
+    TAG: "Ok",
+    _0: value
+  };
+}
+
+let schema = Semantic$Reventless.refined(S.string, Semantic$Reventless.Id.email, fromString);
+
+export {
+  grammar,
+  fromString,
+  schema,
+}
+/* grammar Not a pure module */

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")
+    }
+  }