@reventlessdev/reventless-core 3.0.0-alpha.190 → 3.0.0-alpha.191

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.191 (2026-07-29)
+
+### Bug Fixes
+
+* **plugin:** the field a read model is named by ([c679bb9](https://github.com/ReventlessDev/reventless-core/commit/c679bb9f610be9947417174bc3dfceea38207ba0))
+### Features
+
+* **plugin:** why a read model is named by that field ([699ef8e](https://github.com/ReventlessDev/reventless-core/commit/699ef8e72f1b1d82fb04672739e5e4a8db61ae9a))
+
+
 # 3.0.0-alpha.190 (2026-07-28)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.190",
+  "version": "3.0.0-alpha.191",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,16 +29,16 @@
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.31",
-    "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.14",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.13",
+    "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.14",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
     "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.17",
     "@reventlessdev/rescript-ssh2": "1.1.0-alpha.14",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.108",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.17",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.17",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.109",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.29",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.83"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.84"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/admin/Platform_Admin.res

@@ -252,7 +252,7 @@ module Make = (
       // pushed SDL — CreateResolver then loops on
       // `NotFoundException: No field named ...`.
       let registryKey = entry.specName->Option.getOr(entityName)
-      let (labelField, _searchableFields) = Plugin_Structure.labelFieldsFromStateSchema(
+      let label: Plugin_Structure.labelResolution = Plugin_Structure.labelFieldsFromStateSchema(
         ~entityName,
         entry.stateSchema,
       )
@@ -263,7 +263,7 @@ module Make = (
         pluralTypeName: entry.listFieldName,
         includeIdParam: entry.includeIdParam->Option.getOr(true),
         connectionSpec: entry.connectionSpec->Option.getOr(true),
-        labelField,
+        labelField: label.field,
         connectionFilterTypeName: entry.returnTypeName ++ "Filter",
       }
       Plugin_Helpers.queryFieldNamesRegistry->Dict.set(registryKey, qn)

package/src/admin/Platform_Admin.res.mjs

@@ -110,13 +110,13 @@ function Make(RuntimeEnvironment) {
         let prefix = "Platform_";
         let entityName = entry.returnTypeName.startsWith(prefix) ? entry.returnTypeName.slice(prefix.length, entry.returnTypeName.length) : entry.returnTypeName;
         let registryKey = Stdlib_Option.getOr(entry.specName, entityName);
-        let match = Plugin_Structure$ReventlessCore.labelFieldsFromStateSchema(entityName, entry.stateSchema);
+        let label = Plugin_Structure$ReventlessCore.labelFieldsFromStateSchema(entityName, entry.stateSchema);
         let qn_singleFieldName = entry.singleFieldName;
         let qn_listFieldName = entry.listFieldName;
         let qn_returnTypeName = entry.returnTypeName;
         let qn_pluralTypeName = entry.listFieldName;
         let qn_connectionFilterTypeName = entry.returnTypeName + "Filter";
-        let qn_labelField = match[0];
+        let qn_labelField = label.field;
         let qn_includeIdParam = Stdlib_Option.getOr(entry.includeIdParam, true);
         let qn_connectionSpec = Stdlib_Option.getOr(entry.connectionSpec, true);
         let qn = {

package/src/admin/Platform_Admin_Structure.res

@@ -111,6 +111,9 @@ let pluginReadModel: queryableDef = {
   linkedWriteSide: ["Plugin"],
   labelField: "name",
   searchableFields: ["name"],
+  // Hand-rolled rather than resolved, but the rung is the same one
+  // `labelFieldsFromStateSchema` would report for a field literally named `name`.
+  labelFieldSource: Some("convention"),
   statusField: Some("status"),
   visibility: None,
   chapter: None,

package/src/admin/Platform_Admin_Structure.res.mjs

@@ -126,6 +126,8 @@ let pluginReadModel_linkedWriteSide = ["Plugin"];
 
 let pluginReadModel_searchableFields = ["name"];
 
+let pluginReadModel_labelFieldSource = "convention";
+
 let pluginReadModel_statusField = "status";
 
 let pluginReadModel = {
@@ -136,6 +138,7 @@ let pluginReadModel = {
   linkedWriteSide: pluginReadModel_linkedWriteSide,
   labelField: "name",
   searchableFields: pluginReadModel_searchableFields,
+  labelFieldSource: pluginReadModel_labelFieldSource,
   statusField: pluginReadModel_statusField,
   visibility: undefined,
   chapter: undefined

package/src/admin/Platform_ComponentDefinitionsApi.res

@@ -11,7 +11,7 @@ let sdlTypes: array<string> = [
   `type Platform_CommandDef {\n  name: String!\n  schema: String!\n  level: String!\n  aggregateIdField: String\n  mutationField: String!\n  references: [Platform_FieldReference!]!\n  allowedStates: [String!]\n  targetState: String\n  apiExposed: Boolean\n}`,
   `type Platform_EventDef {\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}`,
-  `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  statusField: 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  statusField: String\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n}`,
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n}`,
   `type Platform_InboundTranslationSliceDef {\n  name: String!\n  commandTypes: [String!]!\n}`,
@@ -72,6 +72,10 @@ let encodeQueryableDef = (r: queryableDef): JSON.t =>
     ("linkedWriteSide", encodeStrings(r.linkedWriteSide)),
     ("labelField", JSON.Encode.string(r.labelField)),
     ("searchableFields", encodeStrings(r.searchableFields)),
+    (
+      "labelFieldSource",
+      r.labelFieldSource->Option.mapOr(JSON.Encode.null, JSON.Encode.string),
+    ),
     ("statusField", r.statusField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
     ("chapter", r.chapter->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
   ])->JSON.Encode.object

package/src/admin/Platform_ComponentDefinitionsApi.res.mjs

@@ -9,7 +9,7 @@ let sdlTypes = [
   `type Platform_CommandDef {\n  name: String!\n  schema: String!\n  level: String!\n  aggregateIdField: String\n  mutationField: String!\n  references: [Platform_FieldReference!]!\n  allowedStates: [String!]\n  targetState: String\n  apiExposed: Boolean\n}`,
   `type Platform_EventDef {\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}`,
-  `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  statusField: 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  statusField: String\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n}`,
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n}`,
   `type Platform_InboundTranslationSliceDef {\n  name: String!\n  commandTypes: [String!]!\n}`,
@@ -116,6 +116,10 @@ function encodeQueryableDef(r) {
       "searchableFields",
       r.searchableFields.map(prim => prim)
     ],
+    [
+      "labelFieldSource",
+      Stdlib_Option.mapOr(r.labelFieldSource, null, prim => prim)
+    ],
     [
       "statusField",
       Stdlib_Option.mapOr(r.statusField, null, prim => prim)

package/src/components/Dcb/Dcb_Builder.res

@@ -526,13 +526,13 @@ module Make = (
           module(V: StateViewSlice.T),
         ) => {
           let qn = Api_Naming.queryFieldNamesForStateView(~plugin=name, ~viewName=V.Spec.name)
-          let (labelField, _searchableFields) = Plugin_Structure.labelFieldsFromStateSchema(
+          let label = Plugin_Structure.labelFieldsFromStateSchema(
             ~entityName=V.Spec.name,
             V.Spec.stateSchema->S.castToUnknown,
           )
           let qn = {
             ...qn,
-            labelField,
+            labelField: label.field,
             connectionFilterTypeName: qn.returnTypeName ++ "Filter",
           }
           let qn = switch V.Spec.subIdConfig {

package/src/components/Dcb/Dcb_Builder.res.mjs

@@ -276,13 +276,13 @@ function Make(DcbEventLogStorage) {
       }
       stateViewSlices.forEach(V => {
         let qn = Api_Naming$ReventlessCore.queryFieldNamesForStateView(name, V.Spec.name, undefined);
-        let match = Plugin_Structure$ReventlessCore.labelFieldsFromStateSchema(V.Spec.name, V.Spec.stateSchema);
+        let label = Plugin_Structure$ReventlessCore.labelFieldsFromStateSchema(V.Spec.name, V.Spec.stateSchema);
         let newrecord = {...qn};
-        newrecord.labelField = match[0];
+        newrecord.labelField = label.field;
         newrecord.connectionFilterTypeName = qn.returnTypeName + "Filter";
-        let match$1 = V.Spec.subIdConfig;
+        let match = V.Spec.subIdConfig;
         let qn$1;
-        if (match$1 !== undefined) {
+        if (match !== undefined) {
           let newrecord$1 = {...newrecord};
           newrecord$1.itemsFilterTypeName = newrecord.returnTypeName + "ItemsFilter";
           newrecord$1.itemsFieldName = newrecord.singleFieldName + "Items";

package/src/plugin/component/Plugin_Builder.res

@@ -267,13 +267,13 @@ module Make = (
       module(R: ReventlessInfra.ReadModel.T with type api = api and type role = role),
     ) => {
       let qn = Api_Naming.queryFieldNamesForReadModel(~plugin=name, ~name=R.Spec.name)
-      let (labelField, _searchableFields) = Plugin_Structure.labelFieldsFromStateSchema(
+      let label = Plugin_Structure.labelFieldsFromStateSchema(
         ~entityName=R.Spec.name,
         R.Spec.stateSchema->S.castToUnknown,
       )
       let qn = {
         ...qn,
-        labelField,
+        labelField: label.field,
         connectionFilterTypeName: qn.returnTypeName ++ "Filter",
       }
       let qn = switch R.Spec.subIdConfig {

package/src/plugin/component/Plugin_Builder.res.mjs

@@ -208,13 +208,13 @@ function Make(Spec) {
         let eventLogEntries = eventLogEntriesFromAggregates.concat(dcbResult.eventLogEntries);
         readModels.forEach(R => {
           let qn = Api_Naming$ReventlessCore.queryFieldNamesForReadModel(extra$1, R.Spec.name, undefined);
-          let match = Plugin_Structure$ReventlessCore.labelFieldsFromStateSchema(R.Spec.name, R.Spec.stateSchema);
+          let label = Plugin_Structure$ReventlessCore.labelFieldsFromStateSchema(R.Spec.name, R.Spec.stateSchema);
           let newrecord = {...qn};
-          newrecord.labelField = match[0];
+          newrecord.labelField = label.field;
           newrecord.connectionFilterTypeName = qn.returnTypeName + "Filter";
-          let match$1 = R.Spec.subIdConfig;
+          let match = R.Spec.subIdConfig;
           let qn$1;
-          if (match$1 !== undefined) {
+          if (match !== undefined) {
             let newrecord$1 = {...newrecord};
             newrecord$1.itemsFilterTypeName = newrecord.returnTypeName + "ItemsFilter";
             newrecord$1.itemsFieldName = newrecord.singleFieldName + "Items";

package/src/plugin/component/Plugin_Structure.res

@@ -5,26 +5,53 @@
 
 let log = Logger.fromEnv()
 
-// Returns (labelField, searchableFields) from a state schema.
-// Source ladder:
-//   1. @displayName spec present → "displayName" + spec.fields (raw underlying fields)
-//   2. First non-id, non-`*Id`/`*Ids`, non-TAG, string-typed field in declaration order
-//   3. "id" fallback with a logged warning (no searchable fields)
-//
-// `*Id` / `*Ids` fields (e.g. `productId`, `customerId`, `orderIds`) are entity
-// references, not human-readable labels — skipping them lets a sibling like
-// `name` win even when it appears later in declaration order.
-let isIdLikeFieldName = (name: string): bool =>
-  name == "id" || name->String.endsWith("Id") || name->String.endsWith("Ids")
-
-// Resolve the field that holds the entity's lifecycle status, used by
-// AutoUI to filter the per-row command menu against each command's
-// `allowedStates`. Resolution order:
+// What a field *is* is `SchemaType`'s question, and it is the IR every other
+// schema consumer here reads. The two predicates below are the only two answers
+// this module needs; both are stated over the IR rather than over sury shapes,
+// so a field that is a date, a reference or an enum is one for the label picker
+// too.
+
+// Whether a field can name a record. `Nullable` unwraps — an optional name is
+// still the entity's name, absent on some rows, which is a rendering question
+// rather than a declaration one. A `Semantic` wrapper is refused: it is the
+// schema saying the string means something other than prose (a storage ref, a
+// URL), and a bucket key is not a name. `DateTime`, `EntityId`, `Enum` and every
+// composite shape fall out of the catch-all without being named — which is the
+// point of reading an IR rather than restating it: the next shape it grows is
+// excluded before it exists.
+let rec isLabelShape = (t: SchemaType.schemaType): bool =>
+  switch t {
+  | ScalarString => true
+  | Nullable(inner) => isLabelShape(inner)
+  | _ => false
+  }
+
+// Whether a field can hold a lifecycle status: a closed set of values, or an
+// optional one. A free-text `status: string` is not a lifecycle — filtering a
+// command menu against `allowedStates` needs states to compare with.
+let rec isStatusShape = (t: SchemaType.schemaType): bool =>
+  switch t {
+  | Enum(_, _) => true
+  | Nullable(inner) => isStatusShape(inner)
+  | _ => false
+  }
+
+// Field names that say "this one is the record's name" in the only way
+// available short of the `@displayName` annotation. Matched case-insensitively
+// and *exactly*: `customerName` holds a customer's name, not this record's.
+let conventionalLabelNames = ["name", "title", "label", "displayname"]
+
+let shapeOfItem = (~entityName: string, item: S.item): SchemaType.schemaType =>
+  SchemaType.fromSury(~parentName=entityName, ~fieldName=item.location, item.schema)
+
+// Resolve the field that holds the entity's lifecycle status, used to filter a
+// per-row command menu against each command's `allowedStates`. Resolution order:
 //   1. Field annotated `@status` (PPX-emitted; see StateAnnotations).
-//   2. Field literally named `"status"` (convention; mirrors how
-//      labelField falls back to a conventionally-named string field).
+//   2. Field literally named `"status"` whose IR shape is an enum (convention;
+//      mirrors how labelField falls back to a conventionally-named field).
 //   3. None — filter is inert for this read model.
 let statusFieldFromStateSchema = (
+  ~entityName: string,
   stateSchema: S.t<unknown>,
 ): option<string> => {
   let annotated = switch Reventless.StateAnnotations.getSpec(stateSchema) {
@@ -37,40 +64,96 @@ let statusFieldFromStateSchema = (
     switch stateSchema {
     | Object({items}) =>
       items
-      ->Array.find(item => item.location == "status")
+      ->Array.find(item =>
+        item.location == "status" && isStatusShape(shapeOfItem(~entityName, item))
+      )
       ->Option.map(item => item.location)
     | _ => None
     }
   }
 }
 
+// Which rung of the ladder below produced the label. Published on `queryableDef`
+// as `labelFieldSource`, because the four rungs are not equally believable and a
+// consumer with a name rule of its own has to rank the declaration against it:
+// rung 1 is the author saying which field names the record, rungs 2 and 3 are
+// guesses this repo makes on their behalf, and rung 4 is the admission that
+// there was nothing to guess from. Convention and position are both guesses and
+// nothing here branches on the difference — but a conventional name is the one a
+// client can independently arrive at, while a positional pick is a fact only
+// this side knows.
+type labelFieldSource =
+  | Annotation
+  | Convention
+  | Position
+  | Fallback
+
+let labelFieldSourceToString = (s: labelFieldSource): string =>
+  switch s {
+  | Annotation => "annotation"
+  | Convention => "convention"
+  | Position => "position"
+  | Fallback => "fallback"
+  }
+
+type labelResolution = {
+  field: string,
+  searchableFields: array<string>,
+  source: labelFieldSource,
+}
+
+// Resolves the field a state is named by, from a state schema.
+// Source ladder:
+//   1. @displayName spec present → "displayName" + spec.fields (raw underlying fields)
+//   2. A candidate field named `name`/`title`/`label`/`displayName`
+//   3. The first candidate in declaration order
+//   4. "id" fallback with a logged warning (no searchable fields)
+//
+// A *candidate* is a non-TAG field, not literally named `id`, whose IR shape can
+// name a record (`isLabelShape`). Rungs 2 and 3 are both guesses, and the order
+// between them matters: declaration order alone means a state gains a new name
+// whenever a field is inserted above the old one — a `placedAt` added so date
+// views have something to key off renames every order to a timestamp.
+//
+// `id` is excluded here rather than by the IR because `SchemaType` treats a name
+// that short as an ordinary string; every other reference — `*Id`/`*Ids`, a DCB
+// tag, a `Reference.to` — is already an `EntityId` there.
 let labelFieldsFromStateSchema = (
   ~entityName: string,
   stateSchema: S.t<unknown>,
-): (string, array<string>) =>
+): labelResolution =>
   switch Reventless.DisplayName.getSpec(stateSchema) {
-  | Some(spec) => ("displayName", spec.fields)
+  | Some(spec) => {field: "displayName", searchableFields: spec.fields, source: Annotation}
   | None =>
-    let firstStringItem = switch stateSchema {
+    let candidates = switch stateSchema {
     | Object({items}) =>
-      items->Array.find(item =>
+      items->Array.filter(item =>
         item.location != "TAG" &&
-        !isIdLikeFieldName(item.location) &&
-        switch item.schema {
-        | String(_) => true
-        | _ => false
-        }
+        item.location != "id" &&
+        isLabelShape(shapeOfItem(~entityName, item))
       )
-    | _ => None
+    | _ => []
+    }
+    let conventional = candidates->Array.find(item => {
+      let lower = item.location->String.toLowerCase
+      conventionalLabelNames->Array.some(n => n == lower)
+    })
+    let picked = switch conventional {
+    | Some(item) => Some((item, Convention))
+    | None => candidates->Array.get(0)->Option.map(item => (item, Position))
     }
-    switch firstStringItem {
-    | Some(item) => (item.location, [item.location])
+    switch picked {
+    | Some((item, source)) => {
+        field: item.location,
+        searchableFields: [item.location],
+        source,
+      }
     | None =>
       log.warn(
         ~comp="Plugin_Structure",
         `${entityName}: no @displayName annotation and no suitable string field — labelField falls back to "id"`,
       )
-      ("id", [])
+      {field: "id", searchableFields: [], source: Fallback}
     }
   }
 
@@ -475,10 +558,7 @@ let make = (
     ) => {
       let qf = Api_Naming.queryFieldNamesForReadModel(~plugin=name, ~name=R.Spec.name)
       let stateSchema = R.Spec.stateSchema->S.castToUnknown
-      let (labelField, searchableFields) = labelFieldsFromStateSchema(
-        ~entityName=R.Spec.name,
-        stateSchema,
-      )
+      let label = labelFieldsFromStateSchema(~entityName=R.Spec.name, stateSchema)
       // The events this read model projects from, qualified to the plugin's event ids so
       // they match the producers' nodes in the graph. Was empty — which dropped projection
       // edges for any event reaching the read model via a DCB-log-sourced mapping (a classic
@@ -490,9 +570,10 @@ let make = (
         schema: stateSchema->SuryToJsonSchema.deriveObjectSchema->JSON.stringify,
         consumedEventTypes: consumed,
         linkedWriteSide: linkedWriteSideFor(consumed),
-        labelField,
-        searchableFields,
-        statusField: statusFieldFromStateSchema(stateSchema),
+        labelField: label.field,
+        searchableFields: label.searchableFields,
+        labelFieldSource: Some(labelFieldSourceToString(label.source)),
+        statusField: statusFieldFromStateSchema(~entityName=R.Spec.name, stateSchema),
         visibility: visibilityTag(R.Spec.visibility),
         chapter: chapterOf(R.Spec.name),
       }: Reventless.Plugin.queryableDef)
@@ -503,19 +584,17 @@ let make = (
       let qf = Api_Naming.queryFieldNamesForStateView(~plugin=name, ~viewName=SVS.Spec.name)
       let (_, consumed) = svsConsumed->Array.getUnsafe(i)
       let stateSchema = SVS.Spec.stateSchema->S.castToUnknown
-      let (labelField, searchableFields) = labelFieldsFromStateSchema(
-        ~entityName=SVS.Spec.name,
-        stateSchema,
-      )
+      let label = labelFieldsFromStateSchema(~entityName=SVS.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: SVS.Spec.name,
         queryField: qf.listFieldName,
         schema: stateSchema->SuryToJsonSchema.deriveObjectSchema->JSON.stringify,
         consumedEventTypes: consumed,
         linkedWriteSide: linkedWriteSideFor(consumed),
-        labelField,
-        searchableFields,
-        statusField: statusFieldFromStateSchema(stateSchema),
+        labelField: label.field,
+        searchableFields: label.searchableFields,
+        labelFieldSource: Some(labelFieldSourceToString(label.source)),
+        statusField: statusFieldFromStateSchema(~entityName=SVS.Spec.name, stateSchema),
         visibility: visibilityTag(SVS.Spec.visibility),
         chapter: chapterOf(SVS.Spec.name),
       }: Reventless.Plugin.queryableDef)

package/src/plugin/component/Plugin_Structure.res.mjs

@@ -11,6 +11,7 @@ import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
 import * as StorageRef$Reventless from "@reventlessdev/reventless-spec/src/semantic/StorageRef.res.mjs";
 import * as DisplayName$Reventless from "@reventlessdev/reventless-spec/src/components/DisplayName.res.mjs";
 import * as Api_Naming$ReventlessCore from "../../components/Api/Api_Naming.res.mjs";
+import * as SchemaType$ReventlessCore from "../../components/Api/SchemaType.res.mjs";
 import * as StateAnnotations$Reventless from "@reventlessdev/reventless-spec/src/components/StateAnnotations.res.mjs";
 import * as ApiNoApiHelpers$ReventlessCore from "../../components/Api/ApiNoApiHelpers.res.mjs";
 import * as SuryToJsonSchema$ReventlessCore from "../../components/Api/SuryToJsonSchema.res.mjs";
@@ -19,54 +20,122 @@ import * as ApiAllowedStatesHelpers$ReventlessCore from "../../components/Api/Ap
 
 let log = Logger$ReventlessCore.fromEnv();
 
-function isIdLikeFieldName(name) {
-  if (name === "id" || name.endsWith("Id")) {
-    return true;
-  } else {
-    return name.endsWith("Ids");
-  }
+function isLabelShape(_t) {
+  while (true) {
+    let t = _t;
+    if (typeof t !== "object") {
+      return t === "ScalarString";
+    }
+    if (t.TAG !== "Nullable") {
+      return false;
+    }
+    _t = t._0;
+    continue;
+  };
+}
+
+function isStatusShape(_t) {
+  while (true) {
+    let t = _t;
+    if (typeof t !== "object") {
+      return false;
+    }
+    switch (t.TAG) {
+      case "Nullable" :
+        _t = t._0;
+        continue;
+      case "Enum" :
+        return true;
+      default:
+        return false;
+    }
+  };
 }
 
-function statusFieldFromStateSchema(stateSchema) {
+let conventionalLabelNames = [
+  "name",
+  "title",
+  "label",
+  "displayname"
+];
+
+function shapeOfItem(entityName, item) {
+  return SchemaType$ReventlessCore.fromSury(entityName, item.location, item.schema);
+}
+
+function statusFieldFromStateSchema(entityName, stateSchema) {
   let spec = StateAnnotations$Reventless.getSpec(stateSchema);
   let annotated = spec !== undefined ? spec.status : undefined;
   if (annotated !== undefined) {
     return annotated;
   } else if (stateSchema.type === "object") {
-    return Stdlib_Option.map(stateSchema.items.find(item => item.location === "status"), item => item.location);
+    return Stdlib_Option.map(stateSchema.items.find(item => {
+      if (item.location === "status") {
+        return isStatusShape(shapeOfItem(entityName, item));
+      } else {
+        return false;
+      }
+    }), item => item.location);
   } else {
     return;
   }
 }
 
+function labelFieldSourceToString(s) {
+  switch (s) {
+    case "Annotation" :
+      return "annotation";
+    case "Convention" :
+      return "convention";
+    case "Position" :
+      return "position";
+    case "Fallback" :
+      return "fallback";
+  }
+}
+
 function labelFieldsFromStateSchema(entityName, stateSchema) {
   let spec = DisplayName$Reventless.getSpec(stateSchema);
   if (spec !== undefined) {
-    return [
-      "displayName",
-      spec.fields
-    ];
+    return {
+      field: "displayName",
+      searchableFields: spec.fields,
+      source: "Annotation"
+    };
   }
-  let firstStringItem;
-  firstStringItem = stateSchema.type === "object" ? stateSchema.items.find(item => {
-      if (item.location === "TAG" || isIdLikeFieldName(item.location)) {
+  let candidates;
+  candidates = stateSchema.type === "object" ? stateSchema.items.filter(item => {
+      if (item.location !== "TAG" && item.location !== "id") {
+        return isLabelShape(shapeOfItem(entityName, item));
+      } else {
         return false;
       }
-      let match = item.schema;
-      return match.type === "string";
-    }) : undefined;
-  if (firstStringItem !== undefined) {
-    return [
-      firstStringItem.location,
-      [firstStringItem.location]
-    ];
-  } else {
-    log.warn("Plugin_Structure", undefined, entityName + `: no @displayName annotation and no suitable string field — labelField falls back to "id"`);
-    return [
-      "id",
-      []
-    ];
+    }) : [];
+  let conventional = candidates.find(item => {
+    let lower = item.location.toLowerCase();
+    return conventionalLabelNames.some(n => n === lower);
+  });
+  let picked = conventional !== undefined ? [
+      conventional,
+      "Convention"
+    ] : Stdlib_Option.map(candidates[0], item => [
+      item,
+      "Position"
+    ]);
+  if (picked !== undefined) {
+    let item = picked[0];
+    return {
+      field: item.location,
+      searchableFields: [item.location],
+      source: picked[1]
+    };
   }
+  log.warn("Plugin_Structure", undefined, entityName + `: no @displayName annotation and no suitable string field — labelField falls back to "id"`);
+  return {
+    field: "id",
+    searchableFields: [],
+    source: "Fallback"
+  };
 }
 
 function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChangeSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, extensionsOpt, extensionPointsOpt, componentChaptersOpt) {
@@ -350,7 +419,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
   let readModelDefs = readModels.map(R => {
     let qf = Api_Naming$ReventlessCore.queryFieldNamesForReadModel(name, R.Spec.name, undefined);
     let stateSchema = R.Spec.stateSchema;
-    let match = labelFieldsFromStateSchema(R.Spec.name, stateSchema);
+    let label = labelFieldsFromStateSchema(R.Spec.name, stateSchema);
     let consumed = qualify(name, R.consumedEventNames);
     return {
       name: R.Spec.name,
@@ -358,9 +427,10 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(stateSchema)),
       consumedEventTypes: consumed,
       linkedWriteSide: linkedWriteSideFor(consumed),
-      labelField: match[0],
-      searchableFields: match[1],
-      statusField: statusFieldFromStateSchema(stateSchema),
+      labelField: label.field,
+      searchableFields: label.searchableFields,
+      labelFieldSource: labelFieldSourceToString(label.source),
+      statusField: statusFieldFromStateSchema(R.Spec.name, stateSchema),
       visibility: visibilityTag(R.Spec.visibility),
       chapter: componentChapters[R.Spec.name]
     };
@@ -370,16 +440,17 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let match = svsConsumed[i];
     let consumed = match[1];
     let stateSchema = SVS.Spec.stateSchema;
-    let match$1 = labelFieldsFromStateSchema(SVS.Spec.name, stateSchema);
+    let label = labelFieldsFromStateSchema(SVS.Spec.name, stateSchema);
     return {
       name: SVS.Spec.name,
       queryField: qf.listFieldName,
       schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(stateSchema)),
       consumedEventTypes: consumed,
       linkedWriteSide: linkedWriteSideFor(consumed),
-      labelField: match$1[0],
-      searchableFields: match$1[1],
-      statusField: statusFieldFromStateSchema(stateSchema),
+      labelField: label.field,
+      searchableFields: label.searchableFields,
+      labelFieldSource: labelFieldSourceToString(label.source),
+      statusField: statusFieldFromStateSchema(SVS.Spec.name, stateSchema),
       visibility: visibilityTag(SVS.Spec.visibility),
       chapter: componentChapters[SVS.Spec.name]
     };
@@ -489,8 +560,12 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
 
 export {
   log,
-  isIdLikeFieldName,
+  isLabelShape,
+  isStatusShape,
+  conventionalLabelNames,
+  shapeOfItem,
   statusFieldFromStateSchema,
+  labelFieldSourceToString,
   labelFieldsFromStateSchema,
   make,
 }

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -27,6 +27,7 @@ let qbl: queryableDef = {
   linkedWriteSide: ["Product"],
   labelField: "displayName",
   searchableFields: ["displayName"],
+  labelFieldSource: Some("annotation"),
   statusField: None,
   visibility: None,
   chapter: None,
@@ -228,6 +229,7 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
     linkedWriteSide: [],
     labelField: "name",
     searchableFields: ["name"],
+    labelFieldSource: Some("convention"),
     statusField: None,
     visibility: Some("Internal"),
     chapter: None,
@@ -270,6 +272,7 @@ describe("allowedStates + statusField populated", () => {
     linkedWriteSide: ["Plugin"],
     labelField: "name",
     searchableFields: ["name"],
+    labelFieldSource: Some("convention"),
     statusField: Some("status"),
     visibility: None,
     chapter: None,

package/tests/admin/Platform_ComponentDefinitionsApiTest.res.mjs

@@ -31,6 +31,8 @@ let qbl_linkedWriteSide = ["Product"];
 
 let qbl_searchableFields = ["displayName"];
 
+let qbl_labelFieldSource = "annotation";
+
 let qbl = {
   name: "Products",
   queryField: "Catalog_Products",
@@ -39,6 +41,7 @@ let qbl = {
   linkedWriteSide: qbl_linkedWriteSide,
   labelField: "displayName",
   searchableFields: qbl_searchableFields,
+  labelFieldSource: qbl_labelFieldSource,
   statusField: undefined,
   visibility: undefined,
   chapter: undefined
@@ -233,6 +236,7 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
   let internalQbl_consumedEventTypes = ["CatalogProductSynced"];
   let internalQbl_linkedWriteSide = [];
   let internalQbl_searchableFields = ["name"];
+  let internalQbl_labelFieldSource = "convention";
   let internalQbl_visibility = "Internal";
   let internalQbl = {
     name: "AvailableProducts",
@@ -242,6 +246,7 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     linkedWriteSide: internalQbl_linkedWriteSide,
     labelField: "name",
     searchableFields: internalQbl_searchableFields,
+    labelFieldSource: internalQbl_labelFieldSource,
     statusField: undefined,
     visibility: internalQbl_visibility,
     chapter: undefined
@@ -298,6 +303,7 @@ globalThis.describe("allowedStates + statusField populated", () => {
   let qblWithStatus_consumedEventTypes = [];
   let qblWithStatus_linkedWriteSide = ["Plugin"];
   let qblWithStatus_searchableFields = ["name"];
+  let qblWithStatus_labelFieldSource = "convention";
   let qblWithStatus_statusField = "status";
   let qblWithStatus = {
     name: "Plugin",
@@ -307,6 +313,7 @@ globalThis.describe("allowedStates + statusField populated", () => {
     linkedWriteSide: qblWithStatus_linkedWriteSide,
     labelField: "name",
     searchableFields: qblWithStatus_searchableFields,
+    labelFieldSource: qblWithStatus_labelFieldSource,
     statusField: qblWithStatus_statusField,
     visibility: undefined,
     chapter: undefined

package/tests/plugin/PluginStructureTest.res

@@ -275,6 +275,252 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
     })
   })
 
+  // What a field *is* comes from `SchemaType`, the IR every other schema
+  // consumer reads, rather than from a `String(_)` match here. These pin the
+  // shapes that separates the two: a date, a reference, a semantic-carrying
+  // string and an optional one all match `String(_)` loosely or not at all, and
+  // each was answered wrong before.
+  describe("labelField — the shape rule", () => {
+    let labelOf = (~entityName="Test", schema) => {
+      let r = Plugin_Structure.labelFieldsFromStateSchema(~entityName, schema->S.castToUnknown)
+      (r.field, r.searchableFields)
+    }
+
+    testSync("a DateTime is not a name — a state whose only string is one falls to id", () => {
+      // The shipped `Orders` case: `placedAt` was added so date views have a
+      // field to key off, and a positional rule let it rename the entity.
+      let schema = S.schema(s =>
+        {
+          "orderId": s.matches(Reventless.Reference.to_("Order")),
+          "placedAt": s.matches(Reventless.DateTime.string),
+          "shippedAt": s.matches(Reventless.DateTime.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("id", []))
+    })
+
+    testSync("a DateTime is skipped, not fatal — a later plain string still wins", () => {
+      let schema = S.schema(s =>
+        {
+          "placedAt": s.matches(Reventless.DateTime.string),
+          "reference": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("reference", ["reference"]))
+    })
+
+    testSync("an optional string is still the entity's name", () => {
+      let schema = S.schema(s =>
+        {
+          "nickname": s.matches(S.option(S.string)),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("nickname", ["nickname"]))
+    })
+
+    testSync("a reference is not a name even when its field is not called `*Id`", () => {
+      let schema = S.schema(s =>
+        {
+          "customer": s.matches(Reventless.Reference.to_("Customer")),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("note", ["note"]))
+    })
+
+    testSync("a DCB-tagged string is not a name", () => {
+      let schema = S.schema(s =>
+        {
+          "partition": s.matches(Reventless.DcbTag.string),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("note", ["note"]))
+    })
+
+    testSync("the `*Id` test is case-insensitive — `productID` is a reference", () => {
+      let schema = S.schema(s =>
+        {
+          "productID": s.matches(S.string),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("note", ["note"]))
+    })
+
+    testSync("a semantic-carrying string is a value, not a name", () => {
+      // `imageUrl` names a stored object. A bucket key read as a product's name
+      // is what the previous rule did whenever no plain string preceded it.
+      let schema = S.schema(s =>
+        {
+          "imageUrl": s.matches(Reventless.StorageRef.forStore(~store="productImages")),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("note", ["note"]))
+    })
+
+    testSync("a state whose only string is a semantic falls to id", () => {
+      let schema = S.schema(s =>
+        {
+          "imageUrl": s.matches(Reventless.StorageRef.forStore(~store="productImages")),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("id", []))
+    })
+
+    testSync("`id` itself is still excluded by name", () => {
+      // `SchemaType` reads a name that short as an ordinary string, so the
+      // exclusion cannot come from the IR.
+      let schema = S.schema(s =>
+        {
+          "id": s.matches(S.string),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("note", ["note"]))
+    })
+  })
+
+  describe("labelField — the conventional-name rung", () => {
+    let labelOf = schema => {
+      let r = Plugin_Structure.labelFieldsFromStateSchema(~entityName="Test", schema->S.castToUnknown)
+      (r.field, r.searchableFields)
+    }
+
+    testSync("a field named `name` beats an earlier string", () => {
+      let schema = S.schema(s =>
+        {
+          "sku": s.matches(S.string),
+          "name": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("name", ["name"]))
+    })
+
+    testSync("`title` counts too, case-insensitively", () => {
+      let schema = S.schema(s =>
+        {
+          "body": s.matches(S.string),
+          "Title": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("Title", ["Title"]))
+    })
+
+    testSync("the match is exact — `customerName` is a customer's name, not this record's", () => {
+      // The shipped `OrdersView` fixture depends on this: it has exactly one
+      // eligible field and must be picked by position, not by convention.
+      let schema = S.schema(s =>
+        {
+          "customerName": s.matches(S.string),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("customerName", ["customerName"]))
+    })
+
+    testSync("an optional `name` still outranks an earlier string", () => {
+      let schema = S.schema(s =>
+        {
+          "sku": s.matches(S.string),
+          "name": s.matches(S.option(S.string)),
+        }
+      )
+      expect(labelOf(schema))->toEqual(("name", ["name"]))
+    })
+  })
+
+  // The rung is published because the four are not equally believable: a
+  // consumer with a name rule of its own has to know whether it is ranking
+  // against a declaration or against a guess.
+  describe("labelFieldSource — which rung answered", () => {
+    let sourceOf = schema =>
+      Plugin_Structure.labelFieldsFromStateSchema(
+        ~entityName="Test",
+        schema->S.castToUnknown,
+      ).source->Plugin_Structure.labelFieldSourceToString
+
+    testSync("a @displayName spec is a declaration", () => {
+      let customers = structure.stateViewSlices->Array.getUnsafe(2)
+      expect((customers.labelField, customers.labelFieldSource))->toEqual((
+        "displayName",
+        Some("annotation"),
+      ))
+    })
+
+    testSync("a field named `name` is a guess the consumer can also make", () => {
+      let schema = S.schema(s =>
+        {
+          "sku": s.matches(S.string),
+          "name": s.matches(S.string),
+        }
+      )
+      expect(sourceOf(schema))->toEqual("convention")
+    })
+
+    testSync("declaration order is a guess only this side can make", () => {
+      // `customerName` is eligible and unconventional, so it wins by position —
+      // and a consumer told only "customerName" could not tell that from a
+      // declaration.
+      let schema = S.schema(s =>
+        {
+          "customerName": s.matches(S.string),
+          "note": s.matches(S.string),
+        }
+      )
+      expect(sourceOf(schema))->toEqual("position")
+    })
+
+    testSync("no candidate at all is the state saying it has no human field", () => {
+      let schema = S.schema(s =>
+        {
+          "orderId": s.matches(Reventless.Reference.to_("Order")),
+          "placedAt": s.matches(Reventless.DateTime.string),
+        }
+      )
+      expect(sourceOf(schema))->toEqual("fallback")
+    })
+
+    testSync("every built def states one", () => {
+      let stated =
+        Array.concat(structure.readModels, structure.stateViewSlices)->Array.every(q =>
+          q.labelFieldSource->Option.isSome
+        )
+      expect(stated)->toEqual(true)
+    })
+  })
+
+  describe("statusField — the shape rule", () => {
+    let statusOf = schema =>
+      Plugin_Structure.statusFieldFromStateSchema(~entityName="Test", schema->S.castToUnknown)
+
+    testSync("a `status` field holding a closed set of values is the lifecycle field", () => {
+      let schema = S.schema(s =>
+        {
+          "status": s.matches(S.union([S.literal("Placed"), S.literal("Shipped")])),
+        }
+      )
+      expect(statusOf(schema))->toEqual(Some("status"))
+    })
+
+    testSync("an optional one counts too", () => {
+      let schema = S.schema(s =>
+        {
+          "status": s.matches(S.option(S.union([S.literal("Placed"), S.literal("Shipped")]))),
+        }
+      )
+      expect(statusOf(schema))->toEqual(Some("status"))
+    })
+
+    testSync("free text named `status` is not a lifecycle", () => {
+      // `allowedStates` filtering needs states to compare against; a string
+      // field named `status` gives a command menu nothing to match.
+      let schema = S.schema(s => {"status": s.matches(S.string)})
+      expect(statusOf(schema))->toEqual(None)
+    })
+  })
+
   // Phase 4: queryableDef.schema must carry x-reventless-* extension keys for
   // annotated state types. Plugin_Structure now uses SuryToJsonSchema.deriveObjectSchema
   // (annotation-aware) instead of S.toJSONSchema (metadata-blind).

package/tests/plugin/PluginStructureTest.res.mjs

@@ -1,8 +1,13 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as S from "sury/src/S.res.mjs";
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
+import * as DateTime$Reventless from "@reventlessdev/reventless-spec/src/types/DateTime.res.mjs";
+import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
+import * as StorageRef$Reventless from "@reventlessdev/reventless-spec/src/semantic/StorageRef.res.mjs";
 import * as PsShipOrder$ReventlessCore from "./StateChangeSlice/PsShipOrder.res.mjs";
 import * as PsOrdersView$ReventlessCore from "./StateViewSlice/PsOrdersView.res.mjs";
 import * as PsPlaceOrder$ReventlessCore from "./StateChangeSlice/PsPlaceOrder.res.mjs";
@@ -395,6 +400,218 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       ]);
     });
   });
+  globalThis.describe("labelField — the shape rule", () => {
+    let labelOf = (entityNameOpt, schema) => {
+      let entityName = entityNameOpt !== undefined ? entityNameOpt : "Test";
+      let r = Plugin_Structure$ReventlessCore.labelFieldsFromStateSchema(entityName, schema);
+      return [
+        r.field,
+        r.searchableFields
+      ];
+    };
+    globalThis.test("a DateTime is not a name — a state whose only string is one falls to id", () => {
+      let schema = S.schema(s => ({
+        orderId: s.m(Reference$Reventless.to_(undefined, undefined, "Order")),
+        placedAt: s.m(DateTime$Reventless.string),
+        shippedAt: s.m(DateTime$Reventless.string)
+      }));
+      globalThis.expect(labelOf(undefined, schema)).toEqual([
+        "id",
+        []
+      ]);
+    });
+    globalThis.test("a DateTime is skipped, not fatal — a later plain string still wins", () => {
+      let schema = S.schema(s => ({
+        placedAt: s.m(DateTime$Reventless.string),
+        reference: s.m(S.string)
+      }));
+      globalThis.expect(labelOf(undefined, schema)).toEqual([
+        "reference",
+        ["reference"]
+      ]);
+    });
+    globalThis.test("an optional string is still the entity's name", () => {
+      let schema = S.schema(s => ({
+        nickname: s.m(S.option(S.string))
+      }));
+      globalThis.expect(labelOf(undefined, schema)).toEqual([
+        "nickname",
+        ["nickname"]
+      ]);
+    });
+    globalThis.test("a reference is not a name even when its field is not called `*Id`", () => {
+      let schema = S.schema(s => ({
+        customer: s.m(Reference$Reventless.to_(undefined, undefined, "Customer")),
+        note: s.m(S.string)
+      }));
+      globalThis.expect(labelOf(undefined, schema)).toEqual([
+        "note",
+        ["note"]
+      ]);
+    });
+    globalThis.test("a DCB-tagged string is not a name", () => {
+      let schema = S.schema(s => ({
+        partition: s.m(DcbTag$Reventless.string),
+        note: s.m(S.string)
+      }));
+      globalThis.expect(labelOf(undefined, schema)).toEqual([
+        "note",
+        ["note"]
+      ]);
+    });
+    globalThis.test("the `*Id` test is case-insensitive — `productID` is a reference", () => {
+      let schema = S.schema(s => ({
+        productID: s.m(S.string),
+        note: s.m(S.string)
+      }));
+      globalThis.expect(labelOf(undefined, schema)).toEqual([
+        "note",
+        ["note"]
+      ]);
+    });
+    globalThis.test("a semantic-carrying string is a value, not a name", () => {
+      let schema = S.schema(s => ({
+        imageUrl: s.m(StorageRef$Reventless.forStore(undefined, "productImages")),
+        note: s.m(S.string)
+      }));
+      globalThis.expect(labelOf(undefined, schema)).toEqual([
+        "note",
+        ["note"]
+      ]);
+    });
+    globalThis.test("a state whose only string is a semantic falls to id", () => {
+      let schema = S.schema(s => ({
+        imageUrl: s.m(StorageRef$Reventless.forStore(undefined, "productImages"))
+      }));
+      globalThis.expect(labelOf(undefined, schema)).toEqual([
+        "id",
+        []
+      ]);
+    });
+    globalThis.test("`id` itself is still excluded by name", () => {
+      let schema = S.schema(s => ({
+        id: s.m(S.string),
+        note: s.m(S.string)
+      }));
+      globalThis.expect(labelOf(undefined, schema)).toEqual([
+        "note",
+        ["note"]
+      ]);
+    });
+  });
+  globalThis.describe("labelField — the conventional-name rung", () => {
+    let labelOf = schema => {
+      let r = Plugin_Structure$ReventlessCore.labelFieldsFromStateSchema("Test", schema);
+      return [
+        r.field,
+        r.searchableFields
+      ];
+    };
+    globalThis.test("a field named `name` beats an earlier string", () => {
+      let schema = S.schema(s => ({
+        sku: s.m(S.string),
+        name: s.m(S.string)
+      }));
+      globalThis.expect(labelOf(schema)).toEqual([
+        "name",
+        ["name"]
+      ]);
+    });
+    globalThis.test("`title` counts too, case-insensitively", () => {
+      let schema = S.schema(s => ({
+        body: s.m(S.string),
+        Title: s.m(S.string)
+      }));
+      globalThis.expect(labelOf(schema)).toEqual([
+        "Title",
+        ["Title"]
+      ]);
+    });
+    globalThis.test("the match is exact — `customerName` is a customer's name, not this record's", () => {
+      let schema = S.schema(s => ({
+        customerName: s.m(S.string),
+        note: s.m(S.string)
+      }));
+      globalThis.expect(labelOf(schema)).toEqual([
+        "customerName",
+        ["customerName"]
+      ]);
+    });
+    globalThis.test("an optional `name` still outranks an earlier string", () => {
+      let schema = S.schema(s => ({
+        sku: s.m(S.string),
+        name: s.m(S.option(S.string))
+      }));
+      globalThis.expect(labelOf(schema)).toEqual([
+        "name",
+        ["name"]
+      ]);
+    });
+  });
+  globalThis.describe("labelFieldSource — which rung answered", () => {
+    let sourceOf = schema => Plugin_Structure$ReventlessCore.labelFieldSourceToString(Plugin_Structure$ReventlessCore.labelFieldsFromStateSchema("Test", schema).source);
+    globalThis.test("a @displayName spec is a declaration", () => {
+      let customers = structure.stateViewSlices[2];
+      globalThis.expect([
+        customers.labelField,
+        customers.labelFieldSource
+      ]).toEqual([
+        "displayName",
+        "annotation"
+      ]);
+    });
+    globalThis.test("a field named `name` is a guess the consumer can also make", () => {
+      let schema = S.schema(s => ({
+        sku: s.m(S.string),
+        name: s.m(S.string)
+      }));
+      globalThis.expect(sourceOf(schema)).toEqual("convention");
+    });
+    globalThis.test("declaration order is a guess only this side can make", () => {
+      let schema = S.schema(s => ({
+        customerName: s.m(S.string),
+        note: s.m(S.string)
+      }));
+      globalThis.expect(sourceOf(schema)).toEqual("position");
+    });
+    globalThis.test("no candidate at all is the state saying it has no human field", () => {
+      let schema = S.schema(s => ({
+        orderId: s.m(Reference$Reventless.to_(undefined, undefined, "Order")),
+        placedAt: s.m(DateTime$Reventless.string)
+      }));
+      globalThis.expect(sourceOf(schema)).toEqual("fallback");
+    });
+    globalThis.test("every built def states one", () => {
+      let stated = structure.readModels.concat(structure.stateViewSlices).every(q => Stdlib_Option.isSome(q.labelFieldSource));
+      globalThis.expect(stated).toEqual(true);
+    });
+  });
+  globalThis.describe("statusField — the shape rule", () => {
+    globalThis.test("a `status` field holding a closed set of values is the lifecycle field", () => {
+      let schema = S.schema(s => ({
+        status: s.m(S.union([
+          S.literal("Placed"),
+          S.literal("Shipped")
+        ]))
+      }));
+      globalThis.expect(Plugin_Structure$ReventlessCore.statusFieldFromStateSchema("Test", schema)).toEqual("status");
+    });
+    globalThis.test("an optional one counts too", () => {
+      let schema = S.schema(s => ({
+        status: s.m(S.option(S.union([
+          S.literal("Placed"),
+          S.literal("Shipped")
+        ])))
+      }));
+      globalThis.expect(Plugin_Structure$ReventlessCore.statusFieldFromStateSchema("Test", schema)).toEqual("status");
+    });
+    globalThis.test("free text named `status` is not a lifecycle", () => {
+      let schema = S.schema(s => ({
+        status: s.m(S.string)
+      }));
+      globalThis.expect(Plugin_Structure$ReventlessCore.statusFieldFromStateSchema("Test", schema)).toEqual(undefined);
+    });
+  });
   globalThis.describe("queryableDef.schema propagates x-reventless-* annotations", () => {
     let getProperty = (json, key) => {
       let obj = Stdlib_JSON.Decode.object(json);