@reventlessdev/reventless-spec 3.0.0-alpha.131 → 3.0.0-alpha.132

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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.132 (2026-09-08)
+
+### Features
+
+* a slice folder is named for its kind, without the Slice ([a400555](https://github.com/ReventlessDev/reventless-core/commit/a400555121b023823983ebe846e99cda27063c1f))
+* **core:** a reference names a row and shows its picture ([2b40d04](https://github.com/ReventlessDev/reventless-core/commit/2b40d0418bba2bf83463f446e94e372ea0c9898c))
+* **core:** a state view records when it reached each state ([5216f71](https://github.com/ReventlessDev/reventless-core/commit/5216f71b8dcafcb2f0c991923ebcf2438b27e347))
+* **spec:** an instant is a type, and a calendar day is a different one ([a60bebc](https://github.com/ReventlessDev/reventless-core/commit/a60bebc20fe5f3413f9252be36f94ba2a9fb620d))
+
+
 # 3.0.0-alpha.131 (2026-09-07)
 
 ### Features

package/package.json

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

package/schema/platform-api.graphql

@@ -201,6 +201,7 @@ enum Platform_PluginKind {
 
 type Platform_PluginRef {
   id: ID!
+  image: String
   label: String!
   retired: Boolean!
   retiredState: String

package/src/components/ComponentKind.res

@@ -36,15 +36,17 @@ let all = [
 ]
 
 // The canonical (singular) folder name for a kind — the spelling the naming
-// conventions and the graph `kind` field use.
+// conventions and the graph `kind` field use. A slice folder drops the `Slice`
+// the kind carries: the folder already sits inside a plugin's `src/`, so the
+// suffix only lengthened every path. The suffixed spellings stay accepted below.
 let folderName = (t: t): string =>
   switch t {
-  | StateChangeSlice => "StateChangeSlice"
-  | StateViewSlice => "StateViewSlice"
-  | StateViewSliceStream => "StateViewSliceStream"
-  | AutomationSlice => "AutomationSlice"
-  | InboundTranslationSlice => "InboundTranslationSlice"
-  | OutboundTranslationSlice => "OutboundTranslationSlice"
+  | StateChangeSlice => "StateChange"
+  | StateViewSlice => "StateView"
+  | StateViewSliceStream => "StateViewStream"
+  | AutomationSlice => "Automation"
+  | InboundTranslationSlice => "InboundTranslation"
+  | OutboundTranslationSlice => "OutboundTranslation"
   | Aggregate => "Aggregate"
   | ReadModel => "ReadModel"
   | ReadModelStream => "ReadModelStream"
@@ -60,7 +62,11 @@ let folderToKind = (folder: string): option<t> =>
   | "StateChange" | "StateChanges" | "StateChangeSlice" | "StateChangeSlices" =>
     Some(StateChangeSlice)
   | "StateView" | "StateViews" | "StateViewSlice" | "StateViewSlices" => Some(StateViewSlice)
-  | "StateViewSliceStream" | "StateViewSliceStreams" => Some(StateViewSliceStream)
+  | "StateViewStream"
+  | "StateViewStreams"
+  | "StateViewSliceStream"
+  | "StateViewSliceStreams" =>
+    Some(StateViewSliceStream)
   | "Automation" | "Automations" | "AutomationSlice" | "AutomationSlices" => Some(AutomationSlice)
   | "InboundTranslation"
   | "InboundTranslations"

package/src/components/ComponentKind.res.mjs

@@ -20,17 +20,17 @@ let all = [
 function folderName(t) {
   switch (t) {
     case "StateChangeSlice" :
-      return "StateChangeSlice";
+      return "StateChange";
     case "StateViewSlice" :
-      return "StateViewSlice";
+      return "StateView";
     case "StateViewSliceStream" :
-      return "StateViewSliceStream";
+      return "StateViewStream";
     case "AutomationSlice" :
-      return "AutomationSlice";
+      return "Automation";
     case "InboundTranslationSlice" :
-      return "InboundTranslationSlice";
+      return "InboundTranslation";
     case "OutboundTranslationSlice" :
-      return "OutboundTranslationSlice";
+      return "OutboundTranslation";
     case "Aggregate" :
       return "Aggregate";
     case "ReadModel" :
@@ -85,6 +85,8 @@ function folderToKind(folder) {
       return "StateChangeSlice";
     case "StateViewSliceStream" :
     case "StateViewSliceStreams" :
+    case "StateViewStream" :
+    case "StateViewStreams" :
       return "StateViewSliceStream";
     case "StateView" :
     case "StateViewSlice" :

package/src/lifecycle/CheckLifecycleModel.res

@@ -897,16 +897,32 @@ let roots: array<appRoot> = switch flagValues("--root") {
   })
 }
 
-/** Sidecar paths that describe a queryable, and those that describe a writable.
-    Told apart by the folder the source sits in, which is the same vocabulary the
-    plugin generator and the PPX already read a component's kind from. */
-let isViewPath = (path: string) =>
-  ["/ReadModel/", "/ReadModelStream/", "/StateViewSlice/", "/StateViewSliceStream/"]->Array.some(
-    seg => path->String.includes(seg),
+/** The kind a sidecar's source folder names, read through `ComponentKind` — the
+    one vocabulary the plugin generator and the PPX already classify a folder by,
+    so every accepted spelling (short, plural, `Slice`-suffixed) lands here too.
+    The innermost matching segment wins, as it does everywhere else. */
+let kindOfPath = (path: string): option<ComponentKind.t> =>
+  path
+  ->String.split("/")
+  ->Array.reduce(None, (found, segment) =>
+    switch ComponentKind.folderToKind(segment) {
+    | Some(_) as kind => kind
+    | None => found
+    }
   )
 
+/** Sidecar paths that describe a queryable, and those that describe a writable. */
+let isViewPath = (path: string) =>
+  switch kindOfPath(path) {
+  | Some(ReadModel | ReadModelStream | StateViewSlice | StateViewSliceStream) => true
+  | _ => false
+  }
+
 let isWritablePath = (path: string) =>
-  ["/Aggregate/", "/StateChangeSlice/"]->Array.some(seg => path->String.includes(seg))
+  switch kindOfPath(path) {
+  | Some(Aggregate | StateChangeSlice) => true
+  | _ => false
+  }
 
 let runPlugin = async (
   ~plugin: string,

package/src/lifecycle/CheckLifecycleModel.res.mjs

@@ -11,6 +11,7 @@ import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as Nodechild_process from "node:child_process";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as ComponentKind$Reventless from "../components/ComponentKind.res.mjs";
 import * as LoadPluginStructureMjs from "./loadPluginStructure.mjs";
 
 process.env["REVENTLESS_DECLARED_TRANSITIONS_ONLY"] = "1";
@@ -612,20 +613,45 @@ if (given.length !== 0) {
   }
 }
 
+function kindOfPath(path) {
+  return Stdlib_Array.reduce(path.split("/"), undefined, (found, segment) => {
+    let kind = ComponentKind$Reventless.folderToKind(segment);
+    if (kind !== undefined) {
+      return kind;
+    } else {
+      return found;
+    }
+  });
+}
+
 function isViewPath(path) {
-  return [
-    "/ReadModel/",
-    "/ReadModelStream/",
-    "/StateViewSlice/",
-    "/StateViewSliceStream/"
-  ].some(seg => path.includes(seg));
+  let match = kindOfPath(path);
+  if (match === undefined) {
+    return false;
+  }
+  switch (match) {
+    case "StateViewSlice" :
+    case "StateViewSliceStream" :
+    case "ReadModel" :
+    case "ReadModelStream" :
+      return true;
+    default:
+      return false;
+  }
 }
 
 function isWritablePath(path) {
-  return [
-    "/Aggregate/",
-    "/StateChangeSlice/"
-  ].some(seg => path.includes(seg));
+  let match = kindOfPath(path);
+  if (match === undefined) {
+    return false;
+  }
+  switch (match) {
+    case "StateChangeSlice" :
+    case "Aggregate" :
+      return true;
+    default:
+      return false;
+  }
 }
 
 async function runPlugin(plugin, pluginDir, findings, opaque) {
@@ -1092,6 +1118,7 @@ export {
   compare,
   pluginDirsIn,
   roots,
+  kindOfPath,
   isViewPath,
   isWritablePath,
   runPlugin,

package/src/semantic/CalendarDate.res

@@ -0,0 +1,58 @@
+/**
+Marks a `string` field as a calendar day — `2026-03-02`, with no instant in it.
+
+## Why this is not a `DateTime`
+
+A birth date, a due date, an invoice date, an `effectiveFrom` — the value has no
+time of day, and storing one as an instant creates the midnight bug: a renderer
+that localizes `2026-03-02T00:00:00Z` shows *March 1st* to every reader west of
+Greenwich. That is a wrong date on a screen produced by a correct renderer, and
+no annotation can repair it, because the value itself has lost the distinction.
+
+## The grammar
+
+Sury's `S.isoDate`: `2026-03-02` accepts, `2026-13-02`, `09:00:00`,
+`2026-03-02T09:00:00Z` and the empty string all reject. It emits
+`format: "date"`, the standard JSON Schema keyword a consumer already reads.
+
+## Why `CalendarDate` and not `Date`
+
+`reventless-spec` compiles with `-open RescriptCore`, and its own modules resolve
+unqualified inside the package — so a `Date.res` here would shadow the stdlib
+`Date` for every file in it. The wire vocabulary id stays the short `"date"`;
+only the module name carries the qualifier.
+
+@example
+```rescript
+@schema
+type state = {
+  invoiceId: string,
+  issuedOn: Reventless.CalendarDate.t,
+}
+```
+*/
+
+/** The day's representation. Transparent `string`, like the rest of the branded
+    scalars: the marker refines an existing field rather than replacing it. */
+type t = string
+
+external unsafe: string => t = "%identity"
+external toString: t => string = "%identity"
+
+// Sury's rule, 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.isoDate
+
+/** Validate a raw string as an ISO-8601 calendar day, saying why when it is not one. */
+let fromString = (raw: string): result<t, string> =>
+  switch raw->S.parseOrThrow(~to=grammar) {
+  | value => Ok(value)
+  | exception _ => Error(`expected a calendar date (YYYY-MM-DD), got ${Semantic.showString(raw)}`)
+  }
+
+/** The sury schema for a calendar-date field. Write the field's type as
+    `Reventless.CalendarDate.t` and sury-ppx resolves it. */
+let schema: S.t<t> = S.string->Semantic.refined(~id=Semantic.Id.date, ~check=fromString)
+
+/** Whether a field schema carries the calendar-date marker. */
+let isCalendarDate = (fieldSchema: S.t<unknown>) => fieldSchema->Semantic.has(~id=Semantic.Id.date)

package/src/semantic/CalendarDate.res.mjs

@@ -0,0 +1,37 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+let grammar = Sury.isoDate;
+
+function fromString(raw) {
+  let value;
+  try {
+    value = S.parseOrThrow(raw, grammar);
+  } catch (exn) {
+    return {
+      TAG: "Error",
+      _0: `expected a calendar date (YYYY-MM-DD), got ` + Semantic$Reventless.showString(raw)
+    };
+  }
+  return {
+    TAG: "Ok",
+    _0: value
+  };
+}
+
+let schema = Semantic$Reventless.refined(Sury.string, Semantic$Reventless.Id.date, fromString);
+
+function isCalendarDate(fieldSchema) {
+  return Semantic$Reventless.has(fieldSchema, Semantic$Reventless.Id.date);
+}
+
+export {
+  grammar,
+  fromString,
+  schema,
+  isCalendarDate,
+}
+/* grammar Not a pure module */

package/src/semantic/DateRange.res

@@ -41,10 +41,10 @@ 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.
+The *parts* are checked, though, and by their own type rather than by anything
+here: each is a `DateTime`, so a string that is not a UTC instant is rejected at
+decode. What is left for `validate` is the one rule that relates the two — a
+range whose instants both parse, the earlier one second.
 
 ## How a field declares it
 
@@ -70,12 +70,12 @@ projection rebuild. It costs a log something only if it *collapses* an existing
 @schema
 type t = {
   /** The instant the range opens, inclusive. */
-  start: @s.matches(DateTime.string) string,
+  start: DateTime.t,
   /** 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,
+  @as("end") end_: DateTime.t,
 }
 
 /** The sury schema for a date-range field, carrying the `dateRange` semantic.
@@ -85,10 +85,10 @@ type t = {
     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
+/** An instant as milliseconds since the epoch. `DateTime`'s, so end-exclusivity
+    and the ordering rule are expressed against the same single parse the type
+    itself uses rather than a second copy of it here. */
+let millis = DateTime.millis
 
 /**
 Validate a range's ordering, saying why when it is reversed.

package/src/semantic/DateRange.res.mjs

@@ -1,22 +1,18 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Sury from "sury";
-import * as DateTime$Reventless from "../types/DateTime.res.mjs";
+import * as DateTime$Reventless from "./DateTime.res.mjs";
 import * as Semantic$Reventless from "./Semantic.res.mjs";
 
 let schema = Sury.$schema(s => ({
-  start: s.m(DateTime$Reventless.string),
-  end: s.m(DateTime$Reventless.string)
+  start: s.m(DateTime$Reventless.schema),
+  end: s.m(DateTime$Reventless.schema)
 }));
 
 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()) {
+  if (DateTime$Reventless.millis(range.start) > DateTime$Reventless.millis(range.end)) {
     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.`
@@ -37,21 +33,21 @@ function make(start, end_) {
 }
 
 function duration(range) {
-  return Math.trunc((new Date(range.end).getTime() - new Date(range.start).getTime()) / 1000.0) | 0;
+  return Math.trunc((DateTime$Reventless.millis(range.end) - DateTime$Reventless.millis(range.start)) / 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();
+  let t = DateTime$Reventless.millis(instant);
+  if (t >= DateTime$Reventless.millis(range.start)) {
+    return t < DateTime$Reventless.millis(range.end);
   } 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();
+  if (DateTime$Reventless.millis(a.start) < DateTime$Reventless.millis(b.end)) {
+    return DateTime$Reventless.millis(b.start) < DateTime$Reventless.millis(a.end);
   } else {
     return false;
   }
@@ -61,6 +57,8 @@ function format(range) {
   return range.start + ` – ` + range.end;
 }
 
+let millis = DateTime$Reventless.millis;
+
 export {
   schema$1 as schema,
   millis,

package/src/semantic/DateTime.res

@@ -0,0 +1,92 @@
+/**
+Marks a `string` field as an ISO-8601 instant.
+
+## The grammar
+
+Sury's `S.isoDateTime`, and nothing added — the same rule the branded scalars
+follow. `S.datetime` is the other binding and is not this one: it *transforms* to
+`Js.Date.t`, changing the field's runtime type, where this keeps the string the
+projection wrote.
+
+## UTC only
+
+`S.isoDateTime` accepts a `Z` instant and rejects an offset — `2026-03-02T09:00:00+01:00`
+and a bare `2026-03-02T09:00:00` both fail. That is stricter than RFC 3339 and it
+is the strictness worth adopting: every instant the framework produces comes from
+`Message.nowAsISOString`, which is always `Z`. "Instants are stored in UTC" is a
+fact a reader can rely on; "we accept whatever offset arrived" pushes the zone
+question onto every consumer.
+
+An inbound feed carrying a supplier's local offset converts at the boundary,
+which is what an `InboundTranslation` slice is for — `Date.fromString` then
+`toISOString`. Forgetting it is now a rejection rather than a row nobody can sort.
+
+`SchemaType`/`SuryToJsonSchema` surface the marker as `format: "date-time"` on
+the field's JSON Schema, which the AutoUI date heuristics key off (CalendarView,
+TimelineView, date-axis charts).
+
+A date with no instant in it — a birth date, a due date — is `CalendarDate`, not
+this. Storing one as an instant creates the midnight bug.
+
+@example
+```rescript
+@schema
+type state = {
+  orderId: string,
+  placedAt: Reventless.DateTime.t,
+  shippedAt: option<Reventless.DateTime.t>,
+}
+```
+*/
+
+/** The instant's representation. Transparent `string`: the marker refines an
+    existing field rather than replacing it, so nothing stored changes, and
+    `placedAt: meta.time` keeps compiling. */
+type t = string
+
+external unsafe: string => t = "%identity"
+external toString: t => string = "%identity"
+
+// Sury's rule, 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.isoDateTime
+
+/** Validate a raw string as a UTC ISO-8601 instant, saying why when it is not one. */
+let fromString = (raw: string): result<t, string> =>
+  switch raw->S.parseOrThrow(~to=grammar) {
+  | value => Ok(value)
+  | exception _ =>
+    Error(`expected a UTC ISO-8601 instant, got ${Semantic.showString(raw)}`)
+  }
+
+/** The sury schema for an instant field. Use with `@s.matches(Reventless.DateTime.schema)`,
+    or write the field's type as `Reventless.DateTime.t` and let sury-ppx resolve it. */
+let schema: S.t<t> = S.string->Semantic.refined(~id=Semantic.Id.dateTime, ~check=fromString)
+
+/** A sury string schema annotated as an instant, without the grammar.
+
+    @deprecated Use `schema`, which carries the same marker and checks the value. */
+let string: S.t<string> = S.string->Semantic.mark(~id=Semantic.Id.dateTime)
+
+/** Whether a field schema carries the date-time marker. */
+let isDateTime = (fieldSchema: S.t<unknown>) => fieldSchema->Semantic.has(~id=Semantic.Id.dateTime)
+
+/** An instant as milliseconds since the epoch — `NaN` if it does not parse. The
+    one place an instant becomes a number, so every comparison here and in
+    `DateRange` is expressed against a single parse. */
+let millis = (instant: t): float => instant->Date.fromString->Date.getTime
+
+/** Whether one instant is strictly earlier than another. */
+let isBefore = (a: t, b: t): bool => millis(a) < millis(b)
+
+/** Order two instants, oldest first. */
+let compare = (a: t, b: t) => Float.compare(millis(a), millis(b))
+
+/** The instant as text, to the minute, in UTC — `"2026-03-02 09:00"`.
+    Locale-independent, the way `Money.format` and `Duration.format` are: the
+    same value reads the same in every log line and every test. A value that is
+    not the shape the grammar admits reads back unchanged. */
+let format = (instant: t): string =>
+  String.length(instant) >= 16
+    ? String.slice(instant, ~start=0, ~end=10) ++ " " ++ String.slice(instant, ~start=11, ~end=16)
+    : instant

package/src/semantic/DateTime.res.mjs

@@ -0,0 +1,65 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
+import * as Primitive_float from "@rescript/runtime/lib/es6/Primitive_float.js";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+let grammar = Sury.isoDateTime;
+
+function fromString(raw) {
+  let value;
+  try {
+    value = S.parseOrThrow(raw, grammar);
+  } catch (exn) {
+    return {
+      TAG: "Error",
+      _0: `expected a UTC ISO-8601 instant, got ` + Semantic$Reventless.showString(raw)
+    };
+  }
+  return {
+    TAG: "Ok",
+    _0: value
+  };
+}
+
+let schema = Semantic$Reventless.refined(Sury.string, Semantic$Reventless.Id.dateTime, fromString);
+
+let string = Semantic$Reventless.mark(Sury.string, Semantic$Reventless.Id.dateTime, undefined);
+
+function isDateTime(fieldSchema) {
+  return Semantic$Reventless.has(fieldSchema, Semantic$Reventless.Id.dateTime);
+}
+
+function millis(instant) {
+  return new Date(instant).getTime();
+}
+
+function isBefore(a, b) {
+  return new Date(a).getTime() < new Date(b).getTime();
+}
+
+function compare(a, b) {
+  return Primitive_float.compare(new Date(a).getTime(), new Date(b).getTime());
+}
+
+function format(instant) {
+  if (instant.length >= 16) {
+    return instant.slice(0, 10) + " " + instant.slice(11, 16);
+  } else {
+    return instant;
+  }
+}
+
+export {
+  grammar,
+  fromString,
+  schema,
+  string,
+  isDateTime,
+  millis,
+  isBefore,
+  compare,
+  format,
+}
+/* grammar Not a pure module */

package/src/semantic/RowImage.res

@@ -0,0 +1,122 @@
+/**
+The picture a row is shown by, wherever a row is shown as a reference to it.
+
+## Why this is derived once, here
+
+The reference door (`{list}Refs`) names a row for a caller holding a pointer to
+it, and a card or a tile that draws such a reference wants its picture for the
+same reason it wants its name. Three backends answer that door — an AppSync
+resolver over DynamoDB, the Postgres query Lambda, and the local GraphQL server
+— and a rule about "where a row keeps its picture" spelled three times is a rule
+the three would eventually disagree about. So the *field* is found once, from the
+state schema, and each backend only reads it out.
+
+## What counts as the picture
+
+The first field, in declaration order, carrying an image semantic:
+`uploadableImage` or `imageRef` (the field's value IS the ref) or
+`captionedImage` (the ref sits inside the record, beside its text). A field
+holding a set of them is read at `[0]`, because a set puts the primary member
+first — the same member a card, a gallery tile and a list cell already draw.
+
+Declaration order rather than a name rule: a view with two image fields has
+already said which one comes first, and guessing from names would let a field
+called `thumbnail` outrank the one the author put at the top.
+*/
+
+/** Where the ref string sits, relative to the field that carries it. */
+type shape =
+  | /** The field's own value is the ref. */ Scalar
+  | /** The ref is one member of the field's record. */ Member(string)
+
+type source = {
+  field: string,
+  shape: shape,
+  /** The field holds a set, and the row is shown by its first member. */
+  fromArray: bool,
+}
+
+/** `CaptionedImage`'s own name for the reference it wraps. Named here rather
+    than spelled at each reader: the record is this package's, so a rename would
+    otherwise be caught nowhere. */
+let captionedImageMember = "ref"
+
+let shapeOf = (schema: S.t<unknown>): option<shape> =>
+  switch Semantic.getFrom(schema) {
+  | Some({id}) if id === Semantic.Id.uploadableImage || id === Semantic.Id.imageRef => Some(Scalar)
+  | Some({id}) if id === Semantic.Id.captionedImage => Some(Member(captionedImageMember))
+  | _ => None
+  }
+
+// sury keeps a homogeneous element schema in `additionalItems` and a tuple's
+// positional schemas in `items`; both are read, as `StorageRef.getFieldStore`
+// does, so the marker is found wherever the element sits.
+let elementOf = (schema: S.t<unknown>): option<S.t<unknown>> =>
+  switch schema {
+  | Array({items, additionalItems}) =>
+    switch items->Array.get(0) {
+    | Some(_) as element => element
+    | None =>
+      switch additionalItems {
+      | Schema(element) => Some(element)
+      | _ => None
+      }
+    }
+  | _ => None
+  }
+
+let sourceOfField = (~field: string, schema: S.t<unknown>): option<source> => {
+  // The marker on an optional field lives inside the wrapper, and an array's
+  // lives on its element — so both are stepped through before asking.
+  let unwrapped = schema->Semantic.unwrapOptional->Option.getOr(schema)
+  switch shapeOf(unwrapped) {
+  | Some(shape) => Some({field, shape, fromArray: false})
+  | None =>
+    unwrapped
+    ->elementOf
+    ->Option.flatMap(shapeOf)
+    ->Option.map(shape => {field, shape, fromArray: true})
+  }
+}
+
+/** The field a reference to this row shows it by, or nothing where the view
+    declares no picture — which is most of them. */
+let sourceFrom = (stateSchema: S.t<unknown>): option<source> =>
+  switch stateSchema {
+  | Object({properties}) =>
+    properties
+    ->Dict.toArray
+    ->Array.filterMap(((field, schema)) => sourceOfField(~field, schema))
+    ->Array.get(0)
+  | _ => None
+  }
+
+/** The ref one row carries, read out of the stored item. An empty string is read
+    as absent: a projection that wrote a placeholder said nothing about a
+    picture, and a consumer resolving `""` against a store gets a broken tile. */
+let refFrom = (row: dict<JSON.t>, source: source): option<string> => {
+  let value = row->Dict.get(source.field)
+  let value = source.fromArray
+    ? value->Option.flatMap(JSON.Decode.array)->Option.flatMap(members => members->Array.get(0))
+    : value
+  switch source.shape {
+  | Scalar => value->Option.flatMap(JSON.Decode.string)
+  | Member(member) =>
+    value
+    ->Option.flatMap(JSON.Decode.object)
+    ->Option.flatMap(d => d->Dict.get(member))
+    ->Option.flatMap(JSON.Decode.string)
+  }->Option.filter(ref => ref != "")
+}
+
+/** The same read as a JavaScript expression, for the one backend whose resolver
+    is generated source rather than a function: the AppSync template. `null`
+    where the row carries nothing, which is what the field's type promises. */
+let jsExpr = (~row: string, source: source): string => {
+  let at = `${row}['${source.field}']`
+  let at = source.fromArray ? `(${at} ?? [])[0]` : at
+  switch source.shape {
+  | Scalar => `${at} ?? null`
+  | Member(member) => `${at}?.['${member}'] ?? null`
+  }
+}

package/src/semantic/RowImage.res.mjs

@@ -0,0 +1,101 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+let captionedImageMember = "ref";
+
+function shapeOf(schema) {
+  let match = Semantic$Reventless.getFrom(schema);
+  if (match === undefined) {
+    return;
+  }
+  let id = match.id;
+  if (id === Semantic$Reventless.Id.uploadableImage || id === Semantic$Reventless.Id.imageRef) {
+    return "Scalar";
+  } else if (id === Semantic$Reventless.Id.captionedImage) {
+    return {
+      TAG: "Member",
+      _0: captionedImageMember
+    };
+  } else {
+    return;
+  }
+}
+
+function elementOf(schema) {
+  if (schema.type !== "array") {
+    return;
+  }
+  let additionalItems = schema.additionalItems;
+  let element = schema.items[0];
+  if (element !== undefined) {
+    return element;
+  } else if (additionalItems === "strip" || additionalItems === "strict") {
+    return;
+  } else {
+    return additionalItems;
+  }
+}
+
+function sourceOfField(field, schema) {
+  let unwrapped = Stdlib_Option.getOr(Semantic$Reventless.unwrapOptional(schema), schema);
+  let shape = shapeOf(unwrapped);
+  if (shape !== undefined) {
+    return {
+      field: field,
+      shape: shape,
+      fromArray: false
+    };
+  } else {
+    return Stdlib_Option.map(Stdlib_Option.flatMap(elementOf(unwrapped), shapeOf), shape => ({
+      field: field,
+      shape: shape,
+      fromArray: true
+    }));
+  }
+}
+
+function sourceFrom(stateSchema) {
+  if (stateSchema.type === "object") {
+    return Stdlib_Array.filterMap(Object.entries(stateSchema.properties), param => sourceOfField(param[0], param[1]))[0];
+  }
+}
+
+function refFrom(row, source) {
+  let value = row[source.field];
+  let value$1 = source.fromArray ? Stdlib_Option.flatMap(Stdlib_Option.flatMap(value, Stdlib_JSON.Decode.array), members => members[0]) : value;
+  let member = source.shape;
+  let tmp;
+  if (typeof member !== "object") {
+    tmp = Stdlib_Option.flatMap(value$1, Stdlib_JSON.Decode.string);
+  } else {
+    let member$1 = member._0;
+    tmp = Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(value$1, Stdlib_JSON.Decode.object), d => d[member$1]), Stdlib_JSON.Decode.string);
+  }
+  return Stdlib_Option.filter(tmp, ref => ref !== "");
+}
+
+function jsExpr(row, source) {
+  let at = row + `['` + source.field + `']`;
+  let at$1 = source.fromArray ? `(` + at + ` ?? [])[0]` : at;
+  let member = source.shape;
+  if (typeof member !== "object") {
+    return at$1 + ` ?? null`;
+  } else {
+    return at$1 + `?.['` + member._0 + `'] ?? null`;
+  }
+}
+
+export {
+  captionedImageMember,
+  shapeOf,
+  elementOf,
+  sourceOfField,
+  sourceFrom,
+  refFrom,
+  jsExpr,
+}
+/* Semantic-Reventless Not a pure module */

package/src/semantic/Semantic.res

@@ -59,6 +59,9 @@ type t = {id: string, payload: payload}
     `x-reventless-semantic` carries, shared with the annotation path. */
 module Id = {
   let dateTime = "dateTime"
+  // A day with no instant in it. Separate from `dateTime` because storing one as
+  // an instant is what produces the midnight bug — see `CalendarDate`.
+  let date = "date"
   let reference = "reference"
   let storageRef = "storageRef"
   // Like `storageRef`, but inline-or-reference rather than always a ref path.
@@ -101,6 +104,11 @@ module Id = {
   // A lat/lng pair. Cheapest to adopt: `{lat, lng}` is already the stored shape.
   let geoPoint = "geoPoint"
 
+  // The ordered record of the states a row has been through. Marks a shape
+  // rather than a scalar's meaning, and rides here anyway: this is the marker
+  // the schema walk emits, so anything else would be invisible on the wire.
+  let lifecycleTrail = "lifecycleTrail"
+
   // The first composite that is a union rather than an object. Collapses fields,
   // so adopting it changes the wire and rebuilds a derived view.
   let geolocation = "geolocation"

package/src/semantic/Semantic.res.mjs

@@ -6,6 +6,7 @@ import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 
 let Id = {
   dateTime: "dateTime",
+  date: "date",
   reference: "reference",
   storageRef: "storageRef",
   offload: "offload",
@@ -25,6 +26,7 @@ let Id = {
   money: "money",
   dateRange: "dateRange",
   geoPoint: "geoPoint",
+  lifecycleTrail: "lifecycleTrail",
   geolocation: "geolocation"
 };
 

package/src/types/Lifecycle.res

@@ -0,0 +1,106 @@
+/**
+Where a record's lifecycle lives, and the trail of states it has been through.
+
+`fieldName` is the single rule for which field holds a lifecycle — every
+consumer resolves it here rather than restating it. `Trail` is the one field a
+view declares to have each state it reaches recorded with the instant it was
+reached; the projection machinery fills it, not the domain.
+*/
+
+// A wire enum: a union whose non-null members are all string constants. A
+// tagged union's members are objects, so the same test excludes it.
+let isEnumSchema = (schema: S.t<unknown>): bool =>
+  switch schema {
+  | AnyOf({anyOf}) =>
+    let members = anyOf->Array.filter(v =>
+      switch v {
+      | Null(_) | Undefined(_) => false
+      | _ => true
+      }
+    )
+    members->Array.length > 0 &&
+      members->Array.every(v =>
+        switch v {
+        | String({const: ?Some(_)}) => true
+        | _ => false
+        }
+      )
+  | _ => false
+  }
+
+// A semantic or a DCB tag makes the field an instant, an id or a reference
+// before it is ever an enum — the order `SchemaType.fromSury` resolves in.
+let isLifecycleShape = (schema: S.t<unknown>): bool =>
+  Semantic.get(schema)->Option.isNone && !DcbTag.isTagged(schema) && isEnumSchema(schema)
+
+/**
+The field holding a record's lifecycle: `@lifecycle`, else an enum field
+literally named `lifecycle`. Not keyed on `status`, a name that would guess.
+*/
+let fieldName = (stateSchema: S.t<unknown>): option<string> =>
+  switch StateAnnotations.getSpec(stateSchema) {
+  | Some({lifecycle: Some(_) as annotated}) => annotated
+  | _ =>
+    switch stateSchema {
+    | Object({properties}) =>
+      properties
+      ->Dict.get("lifecycle")
+      ->Option.flatMap(schema => isLifecycleShape(schema) ? Some("lifecycle") : None)
+    | _ => None
+    }
+  }
+
+/**
+The ordered record of the states a row has been through.
+
+Ordered rather than keyed by state because a lifecycle revisits states — a
+reopened order is `Placed` twice, and a map has to choose which visit to keep.
+A state the row never reached has no entry; there is no value to invent for it.
+*/
+module Trail = {
+  /** One state the row entered, and the instant it did. */
+  @schema
+  type entry<'state> = {
+    state: 'state,
+    at: DateTime.t,
+    /** First entry after a span the cap dropped. Absent while trails are kept
+        whole; declared now so capping later is not a contract change. */
+    afterGap?: bool,
+  }
+
+  type t<'state> = array<entry<'state>>
+
+  /** The schema for a trail field. Resolved by sury-ppx from the declared type
+      `Reventless.Lifecycle.Trail.t<lifecycle>`, so a view writes no annotation.
+
+      Marked with the shared semantic rather than a metadata id of its own: that
+      marker is the one the JSON Schema walk emits, so a private id would leave
+      the trail indistinguishable on the wire from any other array of objects —
+      and a consumer reduced to matching a field called `trail` by name. */
+  let schema = (stateSchema: S.t<'state>): S.t<t<'state>> =>
+    S.array(entrySchema(stateSchema))->Semantic.mark(~id=Semantic.Id.lifecycleTrail)
+
+  let isTrail = (schema: S.t<unknown>): bool =>
+    Semantic.has(schema, ~id=Semantic.Id.lifecycleTrail)
+
+  /** The trail field declared on a state record, if it declares one. */
+  let fieldName = (stateSchema: S.t<unknown>): option<string> =>
+    switch stateSchema {
+    | Object({properties}) =>
+      properties
+      ->Dict.toArray
+      ->Array.find(((_, schema)) => isTrail(schema))
+      ->Option.map(((name, _)) => name)
+    | _ => None
+    }
+
+  /** Append `{state, at}` to the trail a state's JSON holds at `field`. */
+  let record = (stateDict: dict<JSON.t>, ~field: string, ~state: JSON.t, ~at: string): unit => {
+    let entries = switch stateDict->Dict.get(field) {
+    | Some(Array(existing)) => existing
+    | _ => []
+    }
+    let entry = Dict.fromArray([("state", state), ("at", JSON.Encode.string(at))])
+    stateDict->Dict.set(field, entries->Array.concat([entry->JSON.Encode.object])->JSON.Encode.array)
+  }
+}

package/src/types/Lifecycle.res.mjs

@@ -0,0 +1,115 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as DcbTag$Reventless from "../components/DcbTag.res.mjs";
+import * as DateTime$Reventless from "../semantic/DateTime.res.mjs";
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
+import * as StateAnnotations$Reventless from "../components/StateAnnotations.res.mjs";
+
+function isEnumSchema(schema) {
+  if (schema.type !== "anyOf") {
+    return false;
+  }
+  let members = schema.anyOf.filter(v => {
+    switch (v.type) {
+      case "null" :
+      case "undefined" :
+        return false;
+      default:
+        return true;
+    }
+  });
+  if (members.length !== 0) {
+    return members.every(v => {
+      if (v.type === "string") {
+        return v.const !== undefined;
+      } else {
+        return false;
+      }
+    });
+  } else {
+    return false;
+  }
+}
+
+function isLifecycleShape(schema) {
+  if (Stdlib_Option.isNone(Semantic$Reventless.get(schema)) && !DcbTag$Reventless.isTagged(schema)) {
+    return isEnumSchema(schema);
+  } else {
+    return false;
+  }
+}
+
+function fieldName(stateSchema) {
+  let match = StateAnnotations$Reventless.getSpec(stateSchema);
+  if (match !== undefined) {
+    let annotated = match.lifecycle;
+    if (annotated !== undefined) {
+      return annotated;
+    }
+  }
+  if (stateSchema.type === "object") {
+    return Stdlib_Option.flatMap(stateSchema.properties["lifecycle"], schema => {
+      if (isLifecycleShape(schema)) {
+        return "lifecycle";
+      }
+    });
+  }
+}
+
+function entrySchema(_stateSchema) {
+  return Sury.$schema(s => ({
+    state: s.m(_stateSchema),
+    at: s.m(DateTime$Reventless.schema),
+    afterGap: s.m(Sury.$option(Sury.bool))
+  }));
+}
+
+function schema(stateSchema) {
+  return Semantic$Reventless.mark(Sury.array(entrySchema(stateSchema)), Semantic$Reventless.Id.lifecycleTrail, undefined);
+}
+
+function isTrail(schema) {
+  return Semantic$Reventless.has(schema, Semantic$Reventless.Id.lifecycleTrail);
+}
+
+function fieldName$1(stateSchema) {
+  if (stateSchema.type === "object") {
+    return Stdlib_Option.map(Object.entries(stateSchema.properties).find(param => Semantic$Reventless.has(param[1], Semantic$Reventless.Id.lifecycleTrail)), param => param[0]);
+  }
+}
+
+function record(stateDict, field, state, at) {
+  let match = stateDict[field];
+  let entries = match !== undefined ? (
+      Array.isArray(match) ? match : []
+    ) : [];
+  let entry = Object.fromEntries([
+    [
+      "state",
+      state
+    ],
+    [
+      "at",
+      at
+    ]
+  ]);
+  stateDict[field] = entries.concat([entry]);
+}
+
+let Trail = {
+  entrySchema: entrySchema,
+  schema: schema,
+  isTrail: isTrail,
+  fieldName: fieldName$1,
+  record: record
+};
+
+export {
+  isEnumSchema,
+  isLifecycleShape,
+  fieldName,
+  Trail,
+}
+/* sury Not a pure module */

package/src/types/DateTime.res

@@ -1,29 +0,0 @@
-/**
-Marks a `string` state field as an ISO-8601 date-time.
-
-Sury has no string-typed datetime format (`S.datetime` transforms to `Js.Date.t`,
-changing the field's runtime type), so this mirrors the `DcbTag.string`
-precedent: a `S.t<string>` carrying sury metadata that downstream schema walkers
-detect. `SchemaType`/`SuryToJsonSchema` surface it as `format: "date-time"` on
-the field's JSON Schema, which the AutoUI date heuristics key off (CalendarView,
-TimelineView, date-axis charts).
-
-Use on a producer/storage timestamp a projection writes into its state — most
-commonly a `meta.time`-derived field such as `placedAt` / `shippedAt`:
-
-@example
-```rescript
-@schema
-type state = {
-  orderId: string,
-  placedAt: @s.matches(Reventless.DateTime.string) string,
-}
-```
-*/
-
-/** A sury string schema annotated as an ISO-8601 date-time field.
-    Use with `@s.matches(Reventless.DateTime.string)`. */
-let string: S.t<string> = S.string->Semantic.mark(~id=Semantic.Id.dateTime)
-
-/** Whether a field schema carries the date-time marker. */
-let isDateTime = (fieldSchema: S.t<unknown>) => fieldSchema->Semantic.has(~id=Semantic.Id.dateTime)

package/src/types/DateTime.res.mjs

@@ -1,16 +0,0 @@
-// Generated by ReScript, PLEASE EDIT WITH CARE
-
-import * as Sury from "sury";
-import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
-
-let string = Semantic$Reventless.mark(Sury.string, Semantic$Reventless.Id.dateTime, undefined);
-
-function isDateTime(fieldSchema) {
-  return Semantic$Reventless.has(fieldSchema, Semantic$Reventless.Id.dateTime);
-}
-
-export {
-  string,
-  isDateTime,
-}
-/* string Not a pure module */