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

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/Money.res

@@ -0,0 +1,196 @@
+/**
+An amount of money: a whole number of a currency's minor units, and the currency
+those units belong to.
+
+## Why the currency travels with the number
+
+A minor unit is currency-dependent — ISO 4217 gives EUR two decimal places, **JPY
+zero** and **TND three** — so a bare `1000` is €10.00 or ¥1000 or 1.000 TND, and
+there is no way to tell which. It cannot be rendered, compared, summed or
+sanity-checked without knowing. The currency is part of the number's meaning, not
+metadata beside it.
+
+The alternative considered and rejected was a branded `amount` scalar with the
+currency held once on the aggregate. Its appeal is real: mixing currencies
+becomes unrepresentable rather than merely checkable. But it only works while
+every amount an aggregate touches shares one currency, and the moment one does
+not, the information needed to notice has already been deleted. `add` checks
+instead — see below.
+
+## Why whole minor units and not a decimal major amount
+
+`0.1 +. 0.2` is not `0.3`, and money is summed. Minor units keep every amount an
+exact integer, so addition is exact and equality means what it says.
+
+## Why `float` for a whole number
+
+Because ReScript's `int` is int32, and sury enforces that — an `int` amount caps
+at 2,147,483,647 minor units, which is €21,474,836.47. A framework type that
+cannot express a €22M total is not a money type. `float` is exact for every
+integer below 2^53 (about €90 trillion in cents), and the wholeness that `int`
+would have given for free is recovered by checking it in `schema`.
+
+This is the same correction `Bytes` already made for the same reason, and the
+wire form is identical either way: both are JSON numbers.
+
+## How a field declares it
+
+Unlike the branded scalars, this is not an `@s.matches` refinement — the field's
+declared type *is* `Money.t`, and sury-ppx resolves it to this module's `schema`:
+
+```rescript
+@schema type state = {
+  productId: string,
+  price: Reventless.Money.t,
+}
+```
+
+which serializes as `{"amount": 1000, "currency": "EUR"}`.
+
+**That is a structural change to the field.** Retyping an existing `price: float`
+rewrites the wire shape, so stored events no longer decode and projections must
+be rebuilt. Retyping a field in a log that has to survive needs an upcaster
+first; a log that can be discarded can take it today.
+*/
+
+/**
+Validate a minor-unit amount, saying why when it is not one.
+
+The single definition of what an amount may hold; `amountSchema` is derived from
+it rather than hand-rolling a second check, the rule `StorageRef` established.
+*/
+let validateAmount = (amount: float): result<float, string> =>
+  if !Float.isFinite(amount) {
+    Error(`an amount must be a finite number of minor units, got ${Float.toString(amount)}`)
+  } else if amount !== Math.trunc(amount) {
+    Error(
+      `an amount is a whole number of a currency's minor units, got ` ++
+      `${Float.toString(amount)}. There is no such thing as a fraction of the ` ++
+      `smallest unit — a major amount converts with Money.ofMajor.`,
+    )
+  } else {
+    Ok(amount)
+  }
+
+/** The amount's own schema. The check sits on the field rather than on the pair
+    because wholeness is a property of the amount — and because sury 11-alpha
+    miscompiles a refinement wrapping a *record* schema (it hoists the result
+    object above the field reads, so both parse and serialize throw
+    `Cannot access 'v0' before initialization`). Refining the field is both the
+    honest placement and the one that works. */
+let amountSchema: S.t<float> =
+  S.float->S.refine(s => amount =>
+    switch validateAmount(amount) {
+    | Ok(_) => ()
+    | Error(why) => s.fail(why)
+    }
+  )
+
+@schema
+type t = {
+  /** Whole minor units of `currency` — 1000 is €10.00, ¥1000 or 1.000 TND
+      depending on which. Negative amounts are allowed: a refund is money. */
+  amount: @s.matches(amountSchema) float,
+  currency: Currency.t,
+}
+
+/** The sury schema for a money field, carrying the `money` 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.money)
+
+/** An amount already counted in minor units. */
+let make = (~amount: float, ~currency: Currency.t): t => {amount, currency}
+
+/** Nothing, in a currency. A zero still has a currency — "no money" and "no
+    euros" are different claims, and only the second one adds to a total. */
+let zero = (~currency: Currency.t): t => {amount: 0.0, currency}
+
+/**
+Convert a major-unit decimal (`10.5`) into minor units (`1050`), using the
+currency's own exponent.
+
+This is the one place a decimal is allowed to become money, and it is here rather
+than at each call site precisely so that `*. 100.0` is written once and is
+correct for JPY and TND — where it would be `*. 1.0` and `*. 1000.0`.
+
+Rounds half away from zero (`10.005` EUR → `1001`), which is what a reader
+expects of a price. That is a *boundary conversion* and not an arithmetic
+policy: the half-even question that FX and tax rounding turn on is a separate
+decision, and nothing here forecloses it.
+*/
+let ofMajor = (~amount: float, ~currency: Currency.t): t => {
+  let scale = Math.pow(10.0, ~exp=Int.toFloat(Currency.exponent(currency)))
+  {amount: Math.round(amount *. scale), currency}
+}
+
+/** The amount as a major-unit decimal — for charts, averages and anything that
+    has to be a number rather than money. Lossy by nature: the result is a float
+    again, so it is an output, not something to compute a balance in. */
+let toMajor = (m: t): float =>
+  m.amount /. Math.pow(10.0, ~exp=Int.toFloat(Currency.exponent(m.currency)))
+
+/**
+The amount as text: the decimal point placed by the currency's exponent, digits
+grouped in threes, and the ISO code after it — `"1,234.50 EUR"`, `"1,000 JPY"`,
+`"1.000 TND"`.
+
+Deliberately locale-independent, matching the rest of the framework's
+formatters: the same value reads the same in every log line and every test. A
+locale-aware, symbol-bearing rendering is the presentation layer's job, and it
+has the currency code to do it with.
+*/
+let format = (m: t): string => {
+  let exponent = Currency.exponent(m.currency)
+  let negative = m.amount < 0.0
+  let digits = Float.toString(negative ? -.m.amount : m.amount)
+  // Pad so there is always at least one digit left of the point: 5 minor units
+  // of EUR is "0.05", not ".05".
+  let padded = digits->String.padStart(exponent + 1, "0")
+  let split = String.length(padded) - exponent
+  let whole = padded->String.slice(~start=0, ~end=split)
+  let fraction = padded->String.slice(~start=split, ~end=String.length(padded))
+  let rec group = (s: string): string => {
+    let length = String.length(s)
+    length <= 3
+      ? s
+      : group(s->String.slice(~start=0, ~end=length - 3)) ++
+        "," ++
+        s->String.slice(~start=length - 3, ~end=length)
+  }
+  (negative ? "-" : "") ++
+  group(whole) ++
+  (exponent == 0 ? "" : "." ++ fraction) ++
+  " " ++
+  Currency.toString(m.currency)
+}
+
+/**
+Add two amounts, refusing to add across currencies.
+
+This is §15.1's second rider made executable. The genuine appeal of the
+branded-scalar shape was that mixing currencies could not be written at all; the
+answer is to *check* it rather than to delete the information that makes checking
+possible. An aggregate that must hold one currency rejects a line item in
+another — a decider's concern, and one it can now actually express.
+*/
+let add = (a: t, b: t): result<t, string> =>
+  a.currency == b.currency
+    ? Ok({amount: a.amount +. b.amount, currency: a.currency})
+    : Error(
+        `cannot add ${format(b)} to ${format(a)}: they are different currencies. ` ++
+        `Converting between them needs a rate, which is not something an amount carries.`,
+      )
+
+/** Add a run of amounts, refusing at the first currency that does not match the
+    first amount's. `None` for an empty run — the sum of no amounts has no
+    currency to be in. */
+let sum = (amounts: array<t>): option<result<t, string>> =>
+  switch amounts {
+  | [] => None
+  | _ => Some(amounts->Array.reduce(Ok(zero(~currency=(amounts->Array.getUnsafe(0)).currency)), (
+      acc,
+      m,
+    ) => acc->Result.flatMap(total => add(total, m))))
+  }

package/src/semantic/Money.res.mjs

@@ -0,0 +1,138 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Result from "@rescript/runtime/lib/es6/Stdlib_Result.js";
+import * as Currency$Reventless from "./Currency.res.mjs";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+function validateAmount(amount) {
+  if (isFinite(amount)) {
+    if (amount !== Math.trunc(amount)) {
+      return {
+        TAG: "Error",
+        _0: `an amount is a whole number of a currency's minor units, got ` + (amount.toString() + `. There is no such thing as a fraction of the `) + `smallest unit — a major amount converts with Money.ofMajor.`
+      };
+    } else {
+      return {
+        TAG: "Ok",
+        _0: amount
+      };
+    }
+  } else {
+    return {
+      TAG: "Error",
+      _0: `an amount must be a finite number of minor units, got ` + amount.toString()
+    };
+  }
+}
+
+let amountSchema = S.refine(S.float, s => (amount => {
+  let why = validateAmount(amount);
+  if (why.TAG === "Ok") {
+    return;
+  } else {
+    return s.fail(why._0, undefined);
+  }
+}));
+
+let schema = S.schema(s => ({
+  amount: s.m(amountSchema),
+  currency: s.m(Currency$Reventless.schema)
+}));
+
+let schema$1 = Semantic$Reventless.mark(schema, Semantic$Reventless.Id.money, undefined);
+
+function make(amount, currency) {
+  return {
+    amount: amount,
+    currency: currency
+  };
+}
+
+function zero(currency) {
+  return {
+    amount: 0.0,
+    currency: currency
+  };
+}
+
+function ofMajor(amount, currency) {
+  let scale = Math.pow(10.0, Currency$Reventless.exponent(currency));
+  return {
+    amount: Math.round(amount * scale),
+    currency: currency
+  };
+}
+
+function toMajor(m) {
+  return m.amount / Math.pow(10.0, Currency$Reventless.exponent(m.currency));
+}
+
+function format(m) {
+  let exponent = Currency$Reventless.exponent(m.currency);
+  let negative = m.amount < 0.0;
+  let digits = (
+    negative ? - m.amount : m.amount
+  ).toString();
+  let padded = digits.padStart(exponent + 1 | 0, "0");
+  let split = padded.length - exponent | 0;
+  let whole = padded.slice(0, split);
+  let fraction = padded.slice(split, padded.length);
+  let group = s => {
+    let length = s.length;
+    if (length <= 3) {
+      return s;
+    } else {
+      return group(s.slice(0, length - 3 | 0)) + "," + s.slice(length - 3 | 0, length);
+    }
+  };
+  return (
+    negative ? "-" : ""
+  ) + group(whole) + (
+    exponent === 0 ? "" : "." + fraction
+  ) + " " + Currency$Reventless.toString(m.currency);
+}
+
+function add(a, b) {
+  if (a.currency === b.currency) {
+    return {
+      TAG: "Ok",
+      _0: {
+        amount: a.amount + b.amount,
+        currency: a.currency
+      }
+    };
+  } else {
+    return {
+      TAG: "Error",
+      _0: `cannot add ` + format(b) + ` to ` + format(a) + `: they are different currencies. Converting between them needs a rate, which is not something an amount carries.`
+    };
+  }
+}
+
+function sum(amounts) {
+  if (amounts.length !== 0) {
+    return Stdlib_Array.reduce(amounts, {
+      TAG: "Ok",
+      _0: {
+        amount: 0.0,
+        currency: amounts[0].currency
+      }
+    }, (acc, m) => Stdlib_Result.flatMap(acc, total => add(total, m)));
+  }
+}
+
+export {
+  validateAmount,
+  amountSchema,
+  schema$1 as schema,
+  make,
+  zero,
+  ofMajor,
+  toMajor,
+  format,
+  add,
+  sum,
+}
+/* amountSchema Not a pure module */

package/src/semantic/Semantic.res

@@ -58,6 +58,17 @@ module Id = {
   let bytes = "bytes"
   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.
+  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`.
+  let dateRange = "dateRange"
 }
 
 let semanticId: S.Metadata.Id.t<t> = S.Metadata.Id.make(~namespace="reventless", ~name="semantic")

package/src/semantic/Semantic.res.mjs

@@ -12,7 +12,9 @@ let Id = {
   percent: "percent",
   bytes: "bytes",
   duration: "duration",
-  color: "color"
+  color: "color",
+  money: "money",
+  dateRange: "dateRange"
 };
 
 let semanticId = S.Metadata.Id.make("reventless", "semantic");