@reventlessdev/reventless-core 3.0.0-alpha.237 → 3.0.0-alpha.239

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 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.239 (2026-08-18)
+
+### Bug Fixes
+
+* **api:** declare the reference door in the SDL every backend is built from ([5c1857e](https://github.com/ReventlessDev/reventless-core/commit/5c1857ea90ff40305a1c44a9e57043528e6a93aa))
+* **api:** make the by-index door answer, and let an elevated caller widen it ([0fe0c6f](https://github.com/ReventlessDev/reventless-core/commit/0fe0c6f8dec6228ecaba39577e28d780b4f79c83))
+* **core:** fail the build on a retired state the field's enum does not declare ([781935b](https://github.com/ReventlessDev/reventless-core/commit/781935bf8f3e9c418d1e7b25e7235717e4812d7c))
+### Features
+
+* **core:** let a reference name a retired row, and let an elevated caller open one ([9e2623a](https://github.com/ReventlessDev/reventless-core/commit/9e2623a4b22487561607fcc0ca19d51726069ee4))
+
+
+# 3.0.0-alpha.238 (2026-08-16)
+
+### Bug Fixes
+
+* **core:** stamp the owner from each DCB slice's own command schema ([6edbdf4](https://github.com/ReventlessDev/reventless-core/commit/6edbdf4680f2535597c3b560215aa514ceed27eb))
+### Features
+
+* **core:** check a declared lifecycle edge against the states that exist ([d427d92](https://github.com/ReventlessDev/reventless-core/commit/d427d92f8912b4dc9a9407c3c0cec3200d41a5f1))
+* **core:** report a lifecycle state no command can reach ([eb24dbd](https://github.com/ReventlessDev/reventless-core/commit/eb24dbd90df07185f0f4785c4bb726f5b617e7b2))
+* **ppx:** declare a command's lifecycle edge once, as [@transition](https://github.com/transition) ([dd35130](https://github.com/ReventlessDev/reventless-core/commit/dd3513014f14b71879ee21263c6755d3c3d95096))
+
+
 # 3.0.0-alpha.237 (2026-08-16)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.237",
+  "version": "3.0.0-alpha.239",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,21 +29,21 @@
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.8",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.7",
-    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.7",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.7",
+    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.8",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
-    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.143",
+    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.8",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.145",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.117",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.31",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.115"
+    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.67"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.69"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/Message.res

@@ -69,7 +69,7 @@ let toCommandSchema' = (idSchema, commandSchema) =>
 // before a nested `@schema` field existed still decodes instead of bricking the
 // aggregate's log replay. These two entry points thread the memoized envelope schema;
 // `Reventless.Message.decode` (the other central decoder) is tolerant at the source.
-// See docs/plans/platform-infrastructure-in-plugin-list.md (durable fix option 2).
+// See docs/plans/done/platform-infrastructure-in-plugin-list.md (durable fix option 2).
 let decodeEvent' = (json, idSchema, eventSchema) =>
   json->parseJsonTolerant(toEventSchema'(idSchema, eventSchema))
 let decodeCommand' = (json, idSchema, commandSchema) =>

package/src/adapter/Monitoring/Monitoring.res

@@ -10,7 +10,7 @@ concern; this only exposes the choke point through which the framework says
 "I just provisioned an execution unit" and leaves what to do about it to the
 listener.
 
-See `docs/plans/monitoring-hook-seam.md`.
+See `docs/plans/done/monitoring-hook-seam.md`.
 */
 
 /**

package/src/admin/Platform_Admin_Structure.res

@@ -141,6 +141,7 @@ let pluginReadModel: queryableDef = {
   ownerField: None,
   retiredField: None,
   retiredValues: None,
+  namedWhenRetired: None,
 }
 
 let structure: pluginStructure = {

package/src/admin/Platform_Admin_Structure.res.mjs

@@ -154,6 +154,7 @@ let pluginReadModel = {
   ownerField: undefined,
   retiredField: undefined,
   retiredValues: undefined,
+  namedWhenRetired: undefined,
   visibility: undefined,
   chapter: undefined,
   singleQueryField: pluginReadModel_singleQueryField,

package/src/admin/Platform_ComponentDefinitionsApi.res

@@ -29,7 +29,7 @@ let sdlTypes: array<string> = [
   // structures persisted before the fields existed decode as `None`, a hand-rolled
   // def may decline to state them, and a state whose key cannot be resolved has no
   // `idField` to report.
-  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  lifecycleField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n  requiredAccess: [String!]\n  ownerField: String\n  retiredField: String\n  retiredValues: [String!]\n}`,
+  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  lifecycleField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n  requiredAccess: [String!]\n  ownerField: String\n  retiredField: String\n  retiredValues: [String!]\n  namedWhenRetired: Boolean!\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n  targetName: String\n  chapter: String\n}`,
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_InboundTranslationSliceDef {\n  name: String!\n  commandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
@@ -130,6 +130,7 @@ let encodeQueryableDef = (r: queryableDef): JSON.t =>
     ("ownerField", r.ownerField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
     ("retiredField", r.retiredField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
     ("retiredValues", r.retiredValues->Option.mapOr(JSON.Encode.null, encodeStrings)),
+    ("namedWhenRetired", JSON.Encode.bool(r.namedWhenRetired->Option.getOr(false))),
   ])->JSON.Encode.object
 
 let encodeEventDef = (e: eventDef): JSON.t =>

package/src/admin/Platform_ComponentDefinitionsApi.res.mjs

@@ -10,7 +10,7 @@ let sdlTypes = [
   `type Platform_EventDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   `type Platform_ErrorDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   `type Platform_WriteSideDef {\n  name: String!\n  commands: [Platform_CommandDef!]!\n  linkedViews: [String!]!\n  consistencyRead: String\n  producedEventTypes: [String!]!\n  consumedEventTypes: [String!]!\n  events: [Platform_EventDef!]!\n  errors: [Platform_ErrorDef!]!\n  chapter: String\n}`,
-  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  lifecycleField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n  requiredAccess: [String!]\n  ownerField: String\n  retiredField: String\n  retiredValues: [String!]\n}`,
+  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  lifecycleField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n  requiredAccess: [String!]\n  ownerField: String\n  retiredField: String\n  retiredValues: [String!]\n  namedWhenRetired: Boolean!\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n  targetName: String\n  chapter: String\n}`,
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_InboundTranslationSliceDef {\n  name: String!\n  commandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
@@ -168,6 +168,10 @@ function encodeQueryableDef(r) {
     [
       "retiredValues",
       Stdlib_Option.mapOr(r.retiredValues, null, encodeStrings)
+    ],
+    [
+      "namedWhenRetired",
+      Stdlib_Option.getOr(r.namedWhenRetired, false)
     ]
   ]);
 }

package/src/admin/UiFragmentRegistry/StateChangeSlice/UiFragmentRegistry.res

@@ -1,6 +1,6 @@
 // UiFragmentRegistry StateChangeSlice — the write side of the platform UI-fragment
 // registry, extracted off the Plugin aggregate (see
-// docs/plans/event-sourced-fragment-registries.md).
+// docs/plans/done/event-sourced-fragment-registries.md).
 //
 // Commands are driven by the plugin runtime's connect handshake and routed here by the
 // admin PluginExtensionPoint's UI-fragment mapping (RegisterUiFragment on ConnectPlugin,

package/src/components/Aggregate/Aggregate_Callback.res

@@ -114,7 +114,7 @@ module Make = (
   // at append time → the conflict branch invalidates the entry and the retry
   // replays cold. Mirrors the StateChangeSlice decision-model cache, including
   // the fixed capacity (a per-aggregate knob is a future refinement — see
-  // docs/plans/aggregate-snapshotting.md).
+  // docs/plans/done/aggregate-snapshotting.md).
   let replayCacheCapacity = 100
   let replayCache: Lru.t<string, (Behavior.state, int)> = Lru.make(
     ~capacity=replayCacheCapacity,
@@ -122,7 +122,7 @@ module Make = (
 
   let resetCache = () => replayCache->Lru.clear
 
-  // Persisted-snapshot configuration (docs/plans/aggregate-snapshotting.md).
+  // Persisted-snapshot configuration (docs/plans/done/aggregate-snapshotting.md).
   // `None` (the default) keeps full replay; `Some({interval, stateSchema})`
   // seeds cold replays from the latest persisted snapshot and writes a fresh
   // one every `interval` events. Snapshots are a read optimization only — the

package/src/components/Api/ApiAllowedStatesHelpers.res

@@ -1,5 +1,5 @@
 // Read per-variant `allowedStates` metadata that the reventless-ppx
-// `@allowedStates([…])` attribute attaches to a command schema. Consumed by
+// an `@transition` from-set attaches to a command schema. Consumed by
 // `Plugin_Structure.toCommandDef` when building the `commandDef` records that
 // land in `Platform_ComponentDefinitions` so AutoUI can filter the per-row command
 // menu by the row's status.
@@ -7,8 +7,7 @@
 open ReventlessInfra.Api
 
 /** Returns the allowed-state list for a given command-variant name, or None
-    when the variant has no `@allowedStates` annotation (back-compat default
-    — the command shows on every row). */
+    when the variant declares no `@transition` (the command shows on every row). */
 let getAllowedStates = (
   commandSchema: S.t<unknown>,
   ~variantName: string,

package/src/components/Api/ApiTargetStateHelpers.res

@@ -1,5 +1,5 @@
 // Read per-variant `targetState` metadata that the reventless-ppx
-// `@targetState("…")` attribute attaches to a command schema. Consumed by
+// an `@transition` target attaches to a command schema. Consumed by
 // `Plugin_Structure.toCommandDef` when building the `commandDef` records that
 // land in `Platform_ComponentDefinitions`, so AutoUI's board drag resolver can
 // move a row by a *declared* transition instead of a name-stem guess. Mirrors
@@ -8,8 +8,9 @@
 open ReventlessInfra.Api
 
 /** Returns the declared target state for a given command-variant name, or None
-    when the variant has no `@targetState` annotation (back-compat default —
-    the resolver falls back to its name-stem heuristic). */
+    when the variant declares no target — either because it carries no
+    `@transition` at all, or because it declares a from-set only, which is a
+    command saying it does not move the row. */
 let getTargetState = (
   commandSchema: S.t<unknown>,
   ~variantName: string,

package/src/components/Api/GraphQL_FragmentGenerator.res

@@ -411,9 +411,16 @@ let deriveObjectQueryField = (
   ~subIdField: option<string>=?,
 ): string =>
   if includeIdParam {
+    // `includeRetired` reaches this door for the reason it reaches the list: a
+    // caller the server would serve a retired row to had, until it did, no way
+    // to ask for one *singly*. The archive toggle put such rows on screen and
+    // clicking one read a door that refuses them to everybody — `decideRetired`
+    // withholds from `Elevated` and `System` too until they ask, and here there
+    // was nothing to ask with.
     switch subIdField {
-    | Some(sortField) => `  ${singleFieldName}(id: ID!, ${sortField}: String!): ${typeName}`
-    | None => `  ${singleFieldName}(id: ID!): ${typeName}`
+    | Some(sortField) =>
+      `  ${singleFieldName}(id: ID!, ${sortField}: String!, includeRetired: Boolean): ${typeName}`
+    | None => `  ${singleFieldName}(id: ID!, includeRetired: Boolean): ${typeName}`
     }
   } else {
     `  ${singleFieldName}: ${typeName}`
@@ -434,7 +441,38 @@ let deriveByIdsQueryField = (
   ~listFieldName: string,
   ~returnTypeName: string,
 ): string =>
-  `  ${listFieldName}ByIds(ids: [String!]!): [${returnTypeName}!]!`
+  `  ${listFieldName}ByIds(ids: [String!]!, includeRetired: Boolean): [${returnTypeName}!]!`
+
+// ── The reference door ─────────────────────────────────────────────────────
+//
+// What a caller holding a pointer to a row may learn about it: its id, the label
+// a reference resolves to, and — where the view declares a retirement — whether
+// this row is in one and which state that is.
+//
+// The narrowness is the *type's*, which is the whole reason this is a separate
+// field rather than an argument on the by-ids door. A rule that answered a
+// retired row on the existing door "as long as only the safe fields were asked
+// for" would have to be re-implemented, identically, in four backends and to
+// survive aliases, fragments and `__typename`. Here a caller cannot ask for a
+// price, because the type has no price.
+//
+// Emitted for every view, not only for the ones that opted in, on exactly the
+// reasoning `includeRetired` states above: a field that appears and disappears
+// with an annotation makes adding or removing that annotation a breaking schema
+// change, and forces every client to feature-detect. What the annotation decides
+// 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.
+let deriveRefTypeSdl = (~returnTypeName: string): string =>
+  `type ${returnTypeName}Ref {\n  id: ID!\n  label: 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
+// state and `retired: true` has already said everything there is to say.
+let deriveRefsQueryField = (
+  ~listFieldName: string,
+  ~returnTypeName: string,
+): string => `  ${listFieldName}Refs(ids: [ID!]!): [${returnTypeName}Ref!]!`
 
 // `includeRetired` sits beside the paging arguments rather than inside `filter`,
 // and that placement is the point. `filter` is the caller's description of the
@@ -459,6 +497,63 @@ let deriveConnectionQueryField = (
   `  ${listFieldName}(filter: ${filterTypeName}${orderByArg}, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): ${singularTypeName}Connection!`
 }
 
+// ── The by-index door ──────────────────────────────────────────────────────
+//
+// One derivation, called by every backend that serves this field, because the
+// alternative was tried and did not survive contact. The field used to be
+// emitted here for AppSync and again, independently, in the local adapter, and
+// the two agreed on neither its name, its argument nor its return type. Both
+// were wrong in the same way: each disagreed with the resolver standing behind
+// it. The AppSync shape declared `id: ID!` while its resolver read the index
+// field, so the value could not be passed at all; the local shape promised
+// `[String]` while its resolver returned whole rows, so every call failed to
+// serialise. A door that answers on no backend is a door whose signature can be
+// chosen on the merits, which is what the one below is.
+
+/** The row field an index is keyed on.
+
+For a named index (`@index("byOwner") ownerId`) the index name and the field it
+indexes differ, and it is the *field* every resolver filters on; for an unnamed
+index the two are the same string. */
+let indexKeyField = (indexConfig: Reventless.ReadModel.indexConfig): string =>
+  indexConfig.idField->Option.getOr(indexConfig.index)
+
+/** `<single>By<Index>`, dropping a leading `by` from the index name so
+`@index("byOwner")` reads `XByOwner` rather than `XByByOwner`. */
+let indexQueryFieldName = (~singleFieldName: string, ~index: string): string => {
+  let stripped = if index->String.startsWith("by") && index->String.length > 2 {
+    index->String.slice(~start=2, ~end=index->String.length)
+  } else {
+    index
+  }
+  singleFieldName ++ "By" ++ stripped->String.capitalize
+}
+
+/** The by-index door's signature.
+
+Paging and `includeRetired` are here for the reasons `deriveConnectionQueryField`
+gives above — this door reads a secondary index that can carry as many rows as
+the list, and an elevated caller that can widen every other door but this one
+would find the archive reachable by id and by list and not by the index that
+exists to look rows up. */
+let deriveIndexQueryField = (
+  ~singleFieldName: string,
+  ~indexConfig: Reventless.ReadModel.indexConfig,
+  ~connectionTypeName: string,
+): string => {
+  let fieldName = indexQueryFieldName(~singleFieldName, ~index=indexConfig.index)
+  let keyField = indexKeyField(indexConfig)
+  // An index with a sort key can be narrowed to one exact value on it. Optional,
+  // unlike the partition argument: naming the index value is what the door is
+  // for, narrowing further is a refinement. The AppSync sort template has read
+  // this argument all along, against an SDL that never offered it.
+  let sortArg = switch indexConfig.subIdField {
+  | Some(sortField) => `${sortField}: String, `
+  | None => ""
+  }
+  `  ${fieldName}(${keyField}: String!, ${sortArg}first: Int, after: String, last: Int, before: String, includeRetired: Boolean): ${connectionTypeName}!`
+}
+
 // ── Mutation field derivation ──────────────────────────────────────────────
 
 let deriveMutationFieldFromObject = (
@@ -652,6 +747,23 @@ let generate = (
           ~returnTypeName=entry.returnTypeName,
         ),
       )
+
+      // The reference door, under the by-ids condition because it is the same
+      // read. Emitted here rather than per-backend so the field a backend
+      // provisions a resolver for is one this SDL declares: the AppSync adapter
+      // registers `<list>Refs` for every queryable on exactly that premise, and
+      // a door named in one half and not the other fails the deploy outright.
+      let refTypeName = entry.returnTypeName ++ "Ref"
+      if !(seenTypes->Set.has(refTypeName)) {
+        seenTypes->Set.add(refTypeName)
+        types->Array.push(deriveRefTypeSdl(~returnTypeName=entry.returnTypeName))
+      }
+      queries->Array.push(
+        deriveRefsQueryField(
+          ~listFieldName=entry.listFieldName,
+          ~returnTypeName=entry.returnTypeName,
+        ),
+      )
     }
 
     let listFieldName = entry.listFieldName
@@ -677,17 +789,15 @@ let generate = (
     switch entry.indexQueries {
     | Some(indexes) =>
       let connectionTypeName = entry.returnTypeName ++ "Connection"
-      indexes->Array.forEach(({index}) => {
-        let stripped = if index->String.startsWith("by") && index->String.length > 2 {
-          index->String.slice(~start=2, ~end=index->String.length)
-        } else {
-          index
-        }
-        let fieldName = entry.singleFieldName ++ "By" ++ stripped->String.capitalize
+      indexes->Array.forEach(indexConfig =>
         queries->Array.push(
-          `  ${fieldName}(id: ID!, first: Int, after: String, last: Int, before: String): ${connectionTypeName}!`,
+          deriveIndexQueryField(
+            ~singleFieldName=entry.singleFieldName,
+            ~indexConfig,
+            ~connectionTypeName,
+          ),
         )
-      })
+      )
     | None => ()
     }
 

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

@@ -354,9 +354,9 @@ function deriveObjectQueryField(singleFieldName, typeName, includeIdParamOpt, su
   let includeIdParam = includeIdParamOpt !== undefined ? includeIdParamOpt : true;
   if (includeIdParam) {
     if (subIdField !== undefined) {
-      return `  ` + singleFieldName + `(id: ID!, ` + subIdField + `: String!): ` + typeName;
+      return `  ` + singleFieldName + `(id: ID!, ` + subIdField + `: String!, includeRetired: Boolean): ` + typeName;
     } else {
-      return `  ` + singleFieldName + `(id: ID!): ` + typeName;
+      return `  ` + singleFieldName + `(id: ID!, includeRetired: Boolean): ` + typeName;
     }
   } else {
     return `  ` + singleFieldName + `: ` + typeName;
@@ -368,7 +368,15 @@ function deriveListQueryField(listFieldName, pluralTypeName) {
 }
 
 function deriveByIdsQueryField(listFieldName, returnTypeName) {
-  return `  ` + listFieldName + `ByIds(ids: [String!]!): [` + returnTypeName + `!]!`;
+  return `  ` + listFieldName + `ByIds(ids: [String!]!, includeRetired: Boolean): [` + returnTypeName + `!]!`;
+}
+
+function deriveRefTypeSdl(returnTypeName) {
+  return `type ` + returnTypeName + `Ref {\n  id: ID!\n  label: String!\n  retired: Boolean!\n  retiredState: String\n}`;
+}
+
+function deriveRefsQueryField(listFieldName, returnTypeName) {
+  return `  ` + listFieldName + `Refs(ids: [ID!]!): [` + returnTypeName + `Ref!]!`;
 }
 
 function deriveConnectionQueryField(listFieldName, singularTypeName, filterTypeName, hasOrderByOpt) {
@@ -377,6 +385,23 @@ function deriveConnectionQueryField(listFieldName, singularTypeName, filterTypeN
   return `  ` + listFieldName + `(filter: ` + filterTypeName + orderByArg + `, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): ` + singularTypeName + `Connection!`;
 }
 
+function indexKeyField(indexConfig) {
+  return Stdlib_Option.getOr(indexConfig.idField, indexConfig.index);
+}
+
+function indexQueryFieldName(singleFieldName, index) {
+  let stripped = index.startsWith("by") && index.length > 2 ? index.slice(2, index.length) : index;
+  return singleFieldName + "By" + Stdlib_String.capitalize(stripped);
+}
+
+function deriveIndexQueryField(singleFieldName, indexConfig, connectionTypeName) {
+  let fieldName = indexQueryFieldName(singleFieldName, indexConfig.index);
+  let keyField = indexKeyField(indexConfig);
+  let sortField = indexConfig.subIdField;
+  let sortArg = sortField !== undefined ? sortField + `: String, ` : "";
+  return `  ` + fieldName + `(` + keyField + `: String!, ` + sortArg + `first: Int, after: String, last: Int, before: String, includeRetired: Boolean): ` + connectionTypeName + `!`;
+}
+
 function deriveMutationFieldFromObject(fieldName, collectedTypes, seenTypes, variantSchema) {
   let fields = SchemaType$ReventlessCore.fromSuryObject(fieldName, variantSchema);
   if (fields === undefined) {
@@ -481,6 +506,12 @@ function generate(mutationEntries, queryEntries) {
     queries.push(singleField);
     if (includeIdParam && entry.subIdField === undefined) {
       queries.push(deriveByIdsQueryField(entry.listFieldName, entry.returnTypeName));
+      let refTypeName = entry.returnTypeName + "Ref";
+      if (!seenTypes.has(refTypeName)) {
+        seenTypes.add(refTypeName);
+        types.push(deriveRefTypeSdl(entry.returnTypeName));
+      }
+      queries.push(deriveRefsQueryField(entry.listFieldName, entry.returnTypeName));
     }
     let listFieldName = entry.listFieldName;
     let _sf = entry.subIdField;
@@ -495,11 +526,8 @@ function generate(mutationEntries, queryEntries) {
     let indexes = entry.indexQueries;
     if (indexes !== undefined) {
       let connectionTypeName = entry.returnTypeName + "Connection";
-      indexes.forEach(param => {
-        let index = param.index;
-        let stripped = index.startsWith("by") && index.length > 2 ? index.slice(2, index.length) : index;
-        let fieldName = entry.singleFieldName + "By" + Stdlib_String.capitalize(stripped);
-        queries.push(`  ` + fieldName + `(id: ID!, first: Int, after: String, last: Int, before: String): ` + connectionTypeName + `!`);
+      indexes.forEach(indexConfig => {
+        queries.push(deriveIndexQueryField(entry.singleFieldName, indexConfig, connectionTypeName));
       });
     }
     if (connectionSpec) {
@@ -579,7 +607,12 @@ export {
   deriveObjectQueryField,
   deriveListQueryField,
   deriveByIdsQueryField,
+  deriveRefTypeSdl,
+  deriveRefsQueryField,
   deriveConnectionQueryField,
+  indexKeyField,
+  indexQueryFieldName,
+  deriveIndexQueryField,
   deriveMutationFieldFromObject,
   mutationArgTypes,
   generate,

package/src/components/Api/SuryToJsonSchema.res

@@ -137,6 +137,14 @@ let mergeAnnotations = (
       }
       let entries =
         r.label === "" ? entries : Array.concat([("label", JSON.Encode.string(r.label))], entries)
+      // `namedWhenRetired` travels only when true, on the omit-the-default rule
+      // the keys above follow: false is what every record said before the opt-in
+      // existed, and writing it would put a key on every retirement to say
+      // nothing changed.
+      let entries =
+        r.namedWhenRetired
+          ? Array.concat(entries, [("namedWhenRetired", JSON.Encode.bool(true))])
+          : entries
       obj->Dict.set("x-reventless-retired", JSON.Encode.object(Dict.fromArray(entries)))
     | _ => ()
     }

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

@@ -119,20 +119,24 @@ function mergeAnnotations(fieldSchema, fieldName, spec) {
           "label",
           r.label
         ]].concat(entries$1);
-    obj["x-reventless-retired"] = Object.fromEntries(entries$3);
+    let entries$4 = r.namedWhenRetired ? entries$3.concat([[
+          "namedWhenRetired",
+          true
+        ]]) : entries$3;
+    obj["x-reventless-retired"] = Object.fromEntries(entries$4);
   }
   let match$4 = spec.metric.find(param => param[0] === fieldName);
   if (match$4 !== undefined) {
     let m = match$4[1];
-    let entries$4 = [[
+    let entries$5 = [[
         "aggregate",
         m.aggregate
       ]];
-    let entries$5 = m.label === "" ? entries$4 : entries$4.concat([[
+    let entries$6 = m.label === "" ? entries$5 : entries$5.concat([[
           "label",
           m.label
         ]]);
-    obj["x-reventless-metric"] = Object.fromEntries(entries$5);
+    obj["x-reventless-metric"] = Object.fromEntries(entries$6);
   }
   return obj;
 }