@reventlessdev/reventless-core 3.0.0-alpha.258 → 3.0.0-alpha.259

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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.259 (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))
+* **ppx:** a marker composes onto a branded type instead of replacing it ([250c455](https://github.com/ReventlessDev/reventless-core/commit/250c4559aec142558adadcb7f539fea607da5032))
+* **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.258 (2026-09-07)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.258",
+  "version": "3.0.0-alpha.259",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -30,15 +30,15 @@
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
-    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.9",
     "@reventlessdev/rescript-node": "2.0.0-alpha.9",
+    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.9",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.9",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.159",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
+    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.9",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.131",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.35"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.160",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.35",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.132"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/Projection.res

@@ -21,54 +21,172 @@ module Mapping = {
 // hot path at the default Info level.
 let logAction = makeStr => log.debugLazy(~comp="Projection", makeStr)
 
-// ── @displayName overlay ────────────────────────────────────────────────────
-// When a read model's state schema carries DisplayName metadata, every state
-// written by a projection action gets its [displayName] field overwritten with
-// the composite label derived from the annotated source fields. The overlay
-// encodes via sury, mutates the JSON dict, and parses back — unlocks fine
-// work on partial/option fields without duplicating the record shape here.
-
-let overlayDisplayName = (
-  state: 'state,
-  stateSchema: S.t<'state>,
-  spec: Reventless.DisplayName.displayNameSpec,
-): 'state => {
-  let json = state->Reventless.Util_Sury.toJson(stateSchema)
-  switch json->JSON.Decode.object {
-  | None => state
-  | Some(stateDict) =>
-    let label = Reventless.DisplayName.computeLabel(spec, stateDict)
-    stateDict->Dict.set("displayName", JSON.Encode.string(label))
-    stateDict->JSON.Encode.object->Reventless.Util_Sury.fromJson(stateSchema)
+// ── Schema-driven state overlays ────────────────────────────────────────────
+// Two things every state a projection writes carries that the domain does not
+// write: the composite `@displayName` label, and a lifecycle trail entry for an
+// action that moved the row's lifecycle field. Both are read off the state
+// schema and applied to one JSON round trip per written state.
+
+type overlays = {
+  displayName: option<Reventless.DisplayName.displayNameSpec>,
+  // (trail field, lifecycle field). A trail with no lifecycle field to follow
+  // records nothing — there is no value to append.
+  trail: option<(string, string)>,
+}
+
+let overlaysFor = (stateSchema: S.t<unknown>): option<overlays> => {
+  let displayName = Reventless.DisplayName.getSpec(stateSchema)
+  let trail = switch (
+    Reventless.Lifecycle.Trail.fieldName(stateSchema),
+    Reventless.Lifecycle.fieldName(stateSchema),
+  ) {
+  | (Some(trailField), Some(lifecycleField)) => Some((trailField, lifecycleField))
+  | _ => None
+  }
+  displayName->Option.isNone && trail->Option.isNone ? None : Some({displayName, trail})
+}
+
+// `priorLifecycle` is what the row's lifecycle field held before the action.
+// `None` where the row is created — that is a change from nothing, and it opens
+// the trail. `at` is the envelope's own time, never a clock: a projection that
+// read one would produce a different trail on every replay.
+let applyOverlays = (
+  stateDict: dict<JSON.t>,
+  {displayName, trail}: overlays,
+  ~priorLifecycle: option<JSON.t>,
+  ~at: string,
+): unit => {
+  displayName->Option.forEach(spec =>
+    stateDict->Dict.set(
+      "displayName",
+      JSON.Encode.string(Reventless.DisplayName.computeLabel(spec, stateDict)),
+    )
+  )
+  trail->Option.forEach(((trailField, lifecycleField)) =>
+    switch stateDict->Dict.get(lifecycleField) {
+    | Some(value) if Some(value) != priorLifecycle =>
+      stateDict->Reventless.Lifecycle.Trail.record(~field=trailField, ~state=value, ~at)
+    | _ => ()
+    }
+  )
+}
+
+// The action shapes, once, over a lens onto whatever a state is on this path:
+// a typed record encoded through sury, or JSON that already is one.
+//
+// Multi-state actions get the label but no trail entry: pairing a before-row
+// with an after-row needs the sub-id, which is not resolved until the action is
+// applied, and pairing by position would credit one row's transition to another.
+let rewriteActionWith = (
+  action: action<'id, 'state>,
+  ~overlays: overlays,
+  ~toDict: 'state => option<dict<JSON.t>>,
+  ~fromDict: dict<JSON.t> => 'state,
+  ~at: string,
+): action<'id, 'state> => {
+  // Read before the update function runs, so a projection that returns its
+  // argument mutated cannot make the prior state look like the new one.
+  let priorLifecycleOf = state =>
+    switch overlays.trail {
+    | None => None
+    | Some((_, lifecycleField)) => toDict(state)->Option.flatMap(Dict.get(_, lifecycleField))
+    }
+  let apply = (state, ~overlays, ~priorLifecycle) =>
+    switch toDict(state) {
+    | None => state
+    | Some(stateDict) =>
+      applyOverlays(stateDict, overlays, ~priorLifecycle, ~at)
+      fromDict(stateDict)
+    }
+  // `Set` opens a trail rather than extending one: it replaces the whole row,
+  // the trail included, so there is no prior value left to compare against.
+  let created = state => apply(state, ~overlays, ~priorLifecycle=None)
+  let updated = (fn, state) =>
+    apply(fn(state), ~overlays, ~priorLifecycle=priorLifecycleOf(state))
+  let labelled = state => apply(state, ~overlays={...overlays, trail: None}, ~priorLifecycle=None)
+  switch action {
+  | Create(id, state) => Create(id, created(state))
+  | CreateMany(pairs) => CreateMany(pairs->Array.map(((id, s)) => (id, created(s))))
+  | Set(id, state) => Set(id, created(state))
+  | SetMany(ids, fn) => SetMany(ids, id => created(fn(id)))
+  | Update(id, fn) => Update(id, state => updated(fn, state))
+  | UpdateMany(ids, fn) => UpdateMany(ids, (id, s) => updated(state => fn(id, state), s))
+  | UpdateWithDefault(id, default, fn) =>
+    UpdateWithDefault(id, created(default), state => updated(fn, state))
+  | UpdateManyWithDefault(ids, defFn, fn) =>
+    UpdateManyWithDefault(
+      ids,
+      id => created(defFn(id)),
+      (id, s) => updated(state => fn(id, state), s),
+    )
+  | CreateMultiState(id, states) => CreateMultiState(id, states->Array.map(labelled))
+  | UpdateMultiState(id, fn) => UpdateMultiState(id, states => states->fn->Array.map(labelled))
+  | UpdateManyMultiStates(ids, fn) =>
+    UpdateManyMultiStates(ids, (id, states) => fn(id, states)->Array.map(labelled))
+  | Delete(_) | DeleteMany(_) | DeleteIf(_, _) | DeleteManyIf(_, _) | Ignore => action
   }
 }
 
 let rewriteAction = (
   action: action<'id, 'state>,
+  ~at: string,
   stateSchema: S.t<'state>,
 ): action<'id, 'state> =>
-  switch Reventless.DisplayName.getSpec(stateSchema->S.castToUnknown) {
+  switch overlaysFor(stateSchema->S.castToUnknown) {
   | None => action
-  | Some(spec) =>
-    let overlay = state => overlayDisplayName(state, stateSchema, spec)
-    switch action {
-    | Create(id, state) => Create(id, overlay(state))
-    | CreateMany(pairs) => CreateMany(pairs->Array.map(((id, s)) => (id, overlay(s))))
-    | Set(id, state) => Set(id, overlay(state))
-    | SetMany(ids, fn) => SetMany(ids, id => overlay(fn(id)))
-    | Update(id, fn) => Update(id, state => overlay(fn(state)))
-    | UpdateMany(ids, fn) => UpdateMany(ids, (id, s) => overlay(fn(id, s)))
-    | UpdateWithDefault(id, default, fn) =>
-      UpdateWithDefault(id, overlay(default), state => overlay(fn(state)))
-    | UpdateManyWithDefault(ids, defFn, fn) =>
-      UpdateManyWithDefault(ids, id => overlay(defFn(id)), (id, s) => overlay(fn(id, s)))
-    | CreateMultiState(id, states) => CreateMultiState(id, states->Array.map(overlay))
-    | UpdateMultiState(id, fn) =>
-      UpdateMultiState(id, states => states->fn->Array.map(overlay))
-    | UpdateManyMultiStates(ids, fn) =>
-      UpdateManyMultiStates(ids, (id, states) => fn(id, states)->Array.map(overlay))
-    | Delete(_) | DeleteMany(_) | DeleteIf(_, _) | DeleteManyIf(_, _) | Ignore => action
-    }
+  | Some(overlays) =>
+    action->rewriteActionWith(
+      ~overlays,
+      ~at,
+      ~toDict=state => state->Reventless.Util_Sury.toJson(stateSchema)->JSON.Decode.object,
+      ~fromDict=stateDict =>
+        stateDict->JSON.Encode.object->Reventless.Util_Sury.fromJson(stateSchema),
+    )
+  }
+
+// The trail alone, for the two callers that must not compose `displayName`.
+let trailOverlays = (stateSchema: option<S.t<unknown>>): option<overlays> =>
+  switch stateSchema->Option.flatMap(overlaysFor) {
+  | Some({trail: Some(_)} as overlays) => Some({...overlays, displayName: None})
+  | _ => None
+  }
+
+/**
+The rewrite a test harness applies: the trail and nothing else. `displayName`
+lives in the state schema and not in the record, so composing it would produce a
+state no expectation can spell.
+*/
+let rewriteTrail = (
+  action: action<'id, 'state>,
+  ~at: string,
+  stateSchema: S.t<'state>,
+): action<'id, 'state> =>
+  switch trailOverlays(Some(stateSchema->S.castToUnknown)) {
+  | None => action
+  | Some(overlays) =>
+    action->rewriteActionWith(
+      ~overlays,
+      ~at,
+      ~toDict=state => state->Reventless.Util_Sury.toJson(stateSchema)->JSON.Decode.object,
+      ~fromDict=stateDict =>
+        stateDict->JSON.Encode.object->Reventless.Util_Sury.fromJson(stateSchema),
+    )
+  }
+
+/**
+The same, for the JSON-level pipeline a deployed state-view slice assembles,
+whose states are already JSON. `@displayName` is composed at save there
+(`ProjectionEntryPoint_Ops.withDisplayName`).
+*/
+let rewriteJsonAction = (
+  action: action<'id, JSON.t>,
+  ~at: string,
+  ~stateSchema: option<S.t<unknown>>,
+): action<'id, JSON.t> =>
+  switch trailOverlays(stateSchema) {
+  | None => action
+  | Some(overlays) =>
+    action->rewriteActionWith(~overlays, ~at, ~toDict=JSON.Decode.object, ~fromDict=JSON.Encode.object)
   }
 
 let applyChanges = async (

package/src/Projection.res.mjs

@@ -11,6 +11,7 @@ import * as Belt_SetString from "@rescript/runtime/lib/es6/Belt_SetString.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as Lifecycle$Reventless from "@reventlessdev/reventless-spec/src/types/Lifecycle.res.mjs";
 import * as Util_Sury$Reventless from "@reventlessdev/reventless-spec/src/util/Util_Sury.res.mjs";
 import * as Logger$ReventlessCore from "./util/Logger.res.mjs";
 import * as DisplayName$Reventless from "@reventlessdev/reventless-spec/src/components/DisplayName.res.mjs";
@@ -37,23 +38,59 @@ function logAction(makeStr) {
   log.debugLazy("Projection", makeStr);
 }
 
-function overlayDisplayName(state, stateSchema, spec) {
-  let json = Util_Sury$Reventless.toJson(state, stateSchema);
-  let stateDict = Stdlib_JSON.Decode.object(json);
-  if (stateDict === undefined) {
-    return state;
+function overlaysFor(stateSchema) {
+  let displayName = DisplayName$Reventless.getSpec(stateSchema);
+  let match = Lifecycle$Reventless.Trail.fieldName(stateSchema);
+  let match$1 = Lifecycle$Reventless.fieldName(stateSchema);
+  let trail = match !== undefined && match$1 !== undefined ? [
+      match,
+      match$1
+    ] : undefined;
+  if (Stdlib_Option.isNone(displayName) && Stdlib_Option.isNone(trail)) {
+    return;
+  } else {
+    return {
+      displayName: displayName,
+      trail: trail
+    };
   }
-  let label = DisplayName$Reventless.computeLabel(spec, stateDict);
-  stateDict["displayName"] = label;
-  return Util_Sury$Reventless.fromJson(stateDict, stateSchema);
 }
 
-function rewriteAction(action, stateSchema) {
-  let spec = DisplayName$Reventless.getSpec(stateSchema);
-  if (spec === undefined) {
-    return action;
-  }
-  let overlay = state => overlayDisplayName(state, stateSchema, spec);
+function applyOverlays(stateDict, param, priorLifecycle, at) {
+  Stdlib_Option.forEach(param.displayName, spec => {
+    stateDict["displayName"] = DisplayName$Reventless.computeLabel(spec, stateDict);
+  });
+  Stdlib_Option.forEach(param.trail, param => {
+    let value = stateDict[param[1]];
+    if (value !== undefined && Primitive_object.notequal(value, priorLifecycle)) {
+      return Lifecycle$Reventless.Trail.record(stateDict, param[0], value, at);
+    }
+  });
+}
+
+function rewriteActionWith(action, overlays, toDict, fromDict, at) {
+  let priorLifecycleOf = state => {
+    let match = overlays.trail;
+    if (match === undefined) {
+      return;
+    }
+    let lifecycleField = match[1];
+    return Stdlib_Option.flatMap(toDict(state), __x => __x[lifecycleField]);
+  };
+  let apply = (state, overlays, priorLifecycle) => {
+    let stateDict = toDict(state);
+    if (stateDict !== undefined) {
+      applyOverlays(stateDict, overlays, priorLifecycle, at);
+      return fromDict(stateDict);
+    } else {
+      return state;
+    }
+  };
+  let updated = (fn, state) => apply(fn(state), overlays, priorLifecycleOf(state));
+  let labelled = state => apply(state, {
+    displayName: overlays.displayName,
+    trail: undefined
+  }, undefined);
   if (typeof action !== "object") {
     return action;
   }
@@ -62,14 +99,14 @@ function rewriteAction(action, stateSchema) {
       return {
         TAG: "Create",
         _0: action._0,
-        _1: overlayDisplayName(action._1, stateSchema, spec)
+        _1: apply(action._1, overlays, undefined)
       };
     case "CreateMany" :
       return {
         TAG: "CreateMany",
         _0: action._0.map(param => [
           param[0],
-          overlayDisplayName(param[1], stateSchema, spec)
+          apply(param[1], overlays, undefined)
         ])
       };
     case "Update" :
@@ -77,22 +114,22 @@ function rewriteAction(action, stateSchema) {
       return {
         TAG: "Update",
         _0: action._0,
-        _1: state => overlayDisplayName(fn(state), stateSchema, spec)
+        _1: state => updated(fn, state)
       };
     case "UpdateMany" :
       let fn$1 = action._1;
       return {
         TAG: "UpdateMany",
         _0: action._0,
-        _1: (id, s) => overlayDisplayName(fn$1(id, s), stateSchema, spec)
+        _1: (id, s) => updated(state => fn$1(id, state), s)
       };
     case "UpdateWithDefault" :
       let fn$2 = action._2;
       return {
         TAG: "UpdateWithDefault",
         _0: action._0,
-        _1: overlayDisplayName(action._1, stateSchema, spec),
-        _2: state => overlayDisplayName(fn$2(state), stateSchema, spec)
+        _1: apply(action._1, overlays, undefined),
+        _2: state => updated(fn$2, state)
       };
     case "UpdateManyWithDefault" :
       let fn$3 = action._2;
@@ -100,47 +137,84 @@ function rewriteAction(action, stateSchema) {
       return {
         TAG: "UpdateManyWithDefault",
         _0: action._0,
-        _1: id => overlayDisplayName(defFn(id), stateSchema, spec),
-        _2: (id, s) => overlayDisplayName(fn$3(id, s), stateSchema, spec)
+        _1: id => apply(defFn(id), overlays, undefined),
+        _2: (id, s) => updated(state => fn$3(id, state), s)
       };
     case "Set" :
       return {
         TAG: "Set",
         _0: action._0,
-        _1: overlayDisplayName(action._1, stateSchema, spec)
+        _1: apply(action._1, overlays, undefined)
       };
     case "SetMany" :
       let fn$4 = action._1;
       return {
         TAG: "SetMany",
         _0: action._0,
-        _1: id => overlayDisplayName(fn$4(id), stateSchema, spec)
+        _1: id => apply(fn$4(id), overlays, undefined)
       };
     case "CreateMultiState" :
       return {
         TAG: "CreateMultiState",
         _0: action._0,
-        _1: action._1.map(overlay)
+        _1: action._1.map(labelled)
       };
     case "UpdateMultiState" :
       let fn$5 = action._1;
       return {
         TAG: "UpdateMultiState",
         _0: action._0,
-        _1: states => fn$5(states).map(overlay)
+        _1: states => fn$5(states).map(labelled)
       };
     case "UpdateManyMultiStates" :
       let fn$6 = action._1;
       return {
         TAG: "UpdateManyMultiStates",
         _0: action._0,
-        _1: (id, states) => fn$6(id, states).map(overlay)
+        _1: (id, states) => fn$6(id, states).map(labelled)
       };
     default:
       return action;
   }
 }
 
+function rewriteAction(action, at, stateSchema) {
+  let overlays = overlaysFor(stateSchema);
+  if (overlays !== undefined) {
+    return rewriteActionWith(action, overlays, state => Stdlib_JSON.Decode.object(Util_Sury$Reventless.toJson(state, stateSchema)), stateDict => Util_Sury$Reventless.fromJson(stateDict, stateSchema), at);
+  } else {
+    return action;
+  }
+}
+
+function trailOverlays(stateSchema) {
+  let overlays = Stdlib_Option.flatMap(stateSchema, overlaysFor);
+  if (overlays !== undefined && overlays.trail !== undefined) {
+    return {
+      displayName: undefined,
+      trail: overlays.trail
+    };
+  }
+}
+
+function rewriteTrail(action, at, stateSchema) {
+  let overlays = trailOverlays(stateSchema);
+  if (overlays !== undefined) {
+    return rewriteActionWith(action, overlays, state => Stdlib_JSON.Decode.object(Util_Sury$Reventless.toJson(state, stateSchema)), stateDict => Util_Sury$Reventless.fromJson(stateDict, stateSchema), at);
+  } else {
+    return action;
+  }
+}
+
+function rewriteJsonAction(action, at, stateSchema) {
+  let overlays = trailOverlays(stateSchema);
+  if (overlays !== undefined) {
+    return rewriteActionWith(action, overlays, Stdlib_JSON.Decode.object, prim => prim, at);
+  } else {
+    return action;
+  }
+}
+
 async function applyChanges(action, id, beforeStates, afterStates, param, param$1) {
   let getSubId = param$1.getSubId;
   let subIdField = param$1.subIdField;
@@ -714,8 +788,13 @@ export {
   log,
   Mapping,
   logAction,
-  overlayDisplayName,
+  overlaysFor,
+  applyOverlays,
+  rewriteActionWith,
   rewriteAction,
+  trailOverlays,
+  rewriteTrail,
+  rewriteJsonAction,
   applyChanges,
   stateToString,
   statesToString,

package/src/admin/UiFragmentRegistry/{StateChangeSlice → StateChange}/UiFragmentRegistry.res.mjs

@@ -58,7 +58,7 @@ let Id;
 
 let consumedEventSchema = eventSchema;
 
-let moduleUrl = "@reventlessdev/reventless-core/src/admin/UiFragmentRegistry/StateChangeSlice/UiFragmentRegistry.res.mjs";
+let moduleUrl = "@reventlessdev/reventless-core/src/admin/UiFragmentRegistry/StateChange/UiFragmentRegistry.res.mjs";
 
 let readConsistency = "EscalateOnRetry";
 

package/src/admin/UiFragmentRegistry/{StateChangeSlice → StateChange}/UiFragmentRegistry_Behavior.res.mjs

@@ -68,7 +68,7 @@ let Spec;
 
 let initialState;
 
-let moduleUrl = "@reventlessdev/reventless-core/src/admin/UiFragmentRegistry/StateChangeSlice/UiFragmentRegistry_Behavior.res.mjs";
+let moduleUrl = "@reventlessdev/reventless-core/src/admin/UiFragmentRegistry/StateChange/UiFragmentRegistry_Behavior.res.mjs";
 
 export {
   Spec,

package/src/admin/UiFragmentRegistry/{StateViewSlice → StateView}/UiFragments.res.mjs

@@ -42,7 +42,7 @@ let Id;
 
 let subIdConfig;
 
-let moduleUrl = "@reventlessdev/reventless-core/src/admin/UiFragmentRegistry/StateViewSlice/UiFragments.res.mjs";
+let moduleUrl = "@reventlessdev/reventless-core/src/admin/UiFragmentRegistry/StateView/UiFragments.res.mjs";
 
 let authorization = "AllowAuthenticated";
 

package/src/admin/UiFragmentRegistry/{StateViewSlice → StateView}/UiFragments_Projection.res.mjs

@@ -45,7 +45,7 @@ function project(param) {
 
 let Spec;
 
-let moduleUrl = "@reventlessdev/reventless-core/src/admin/UiFragmentRegistry/StateViewSlice/UiFragments_Projection.res.mjs";
+let moduleUrl = "@reventlessdev/reventless-core/src/admin/UiFragmentRegistry/StateView/UiFragments_Projection.res.mjs";
 
 export {
   Spec,

package/src/components/Api/GraphQL_FragmentGenerator.res

@@ -47,6 +47,7 @@ let rec fromSchemaType = (
   | ScalarBigInt => `String${bang}`
   | EntityId => `ID${bang}`
   | DateTime => `String${bang}`
+  | CalendarDate => `String${bang}`
   | Nullable(inner) => fromSchemaType(~required=false, ~asInput, inner, collectedTypes, seenTypes)
   | ArrayOf(item) =>
     let itemType = fromSchemaType(~required=true, ~asInput, item, collectedTypes, seenTypes)
@@ -594,8 +595,18 @@ let deriveByIdsQueryField = (
 // is not whether the door exists but whether a *retired* row comes through it —
 // without it this is a cheap label read that narrows exactly as every other door
 // does.
+// `image` travels beside `label` for the reason the label does: a card or a tile
+// drawing a reference wants the row's picture as well as its name, and the
+// alternative is a second query per grid asking the referenced view for one
+// field. It stays inside the narrowness above — a ref path is what a reference
+// already publishes, and a caller still cannot ask for anything else — and it is
+// `null` for the views (most of them) that declare no picture.
+//
+// Emitted unconditionally for the same reason the door itself is: a field that
+// appears once a view adopts an image would make adopting one a breaking schema
+// change for every client that had learned this type's shape.
 let deriveRefTypeSdl = (~returnTypeName: string): string =>
-  `type ${returnTypeName}Ref {\n  id: ID!\n  label: String!\n  retired: Boolean!\n  retiredState: String\n}`
+  `type ${returnTypeName}Ref {\n  id: ID!\n  label: String!\n  image: String\n  retired: Boolean!\n  retiredState: String\n}`
 
 // `retiredState` is null in two cases that do not need telling apart by a
 // consumer: a live row, and a boolean-form retirement, where the field is the

package/src/components/Api/GraphQL_FragmentGenerator.res.mjs

@@ -52,6 +52,7 @@ function fromSchemaType(_required, _asInputOpt, _st, collectedTypes, seenTypes)
         case "ScalarString" :
         case "ScalarBigInt" :
         case "DateTime" :
+        case "CalendarDate" :
         case "Unknown" :
           return `String` + bang;
       }
@@ -455,7 +456,7 @@ function deriveByIdsQueryField(listFieldName, returnTypeName) {
 }
 
 function deriveRefTypeSdl(returnTypeName) {
-  return `type ` + returnTypeName + `Ref {\n  id: ID!\n  label: String!\n  retired: Boolean!\n  retiredState: String\n}`;
+  return `type ` + returnTypeName + `Ref {\n  id: ID!\n  label: String!\n  image: String\n  retired: Boolean!\n  retiredState: String\n}`;
 }
 
 function deriveRefsQueryField(listFieldName, returnTypeName) {