@reventlessdev/reventless-core 3.0.0-alpha.223 → 3.0.0-alpha.224

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

@@ -5,6 +5,7 @@ import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_Nullable from "@rescript/runtime/lib/es6/Stdlib_Nullable.js";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Api_Ids$ReventlessCore from "./Api_Ids.res.mjs";
 
 function encodeCursor(value) {
   return btoa(value);
@@ -47,7 +48,8 @@ function buildConnection(pageItems, hasNextPage, hasPreviousPage, cursorValueOf)
   };
 }
 
-function run(items, argsDict, capability, labelField, decodeLocalId) {
+function run(items, argsDict, capability, labelField, decodeLocalIdOpt) {
+  let decodeLocalId = decodeLocalIdOpt !== undefined ? decodeLocalIdOpt : Api_Ids$ReventlessCore.toLocalId;
   let filterDict = Stdlib_Option.getOr(Stdlib_Option.flatMap(argsDict["filter"], Stdlib_JSON.Decode.object), {});
   let search = Stdlib_Option.flatMap(filterDict["search"], Stdlib_JSON.Decode.string);
   let searchPrefix = Stdlib_Option.flatMap(filterDict["searchPrefix"], Stdlib_JSON.Decode.string);
@@ -83,10 +85,10 @@ function run(items, argsDict, capability, labelField, decodeLocalId) {
       let itemId = getId(item);
       let itemLocalId = decodeLocalId(itemId);
       passIds = ids.some(i => {
-        if (i === itemId) {
+        if (i === itemId || Primitive_object.equal(itemLocalId, i)) {
           return true;
         } else {
-          return Primitive_object.equal(itemLocalId, i);
+          return Primitive_object.equal(decodeLocalId(i), itemId);
         }
       });
     } else {

package/src/components/Api/SchemaType.res

@@ -32,8 +32,34 @@ let isIdsFieldName = (name: string): bool => {
   len > 3 && String.endsWith(lower, "ids")
 }
 
+/**
+The GraphQL type name a semantic **composite** is emitted under.
+
+The branded scalars are absent on purpose: they refine a `string` or a number
+without changing its shape, so each is already a `String` or a `Float` in GraphQL
+and has no definition that could be duplicated. Only the semantics that turn a
+field into an object or an enum need a name of their own — without one, the same
+type is emitted once per *field* that uses it, under the field path that reached
+it (`Catalog_AddProductPriceCurrency`, `Ordering_SyncNewProductPriceCurrency`, …
+six copies of ISO 4217 in one example schema).
+
+Naming them is what makes the definitions identical across plugins, which is the
+property merged-API composition needs: AppSync unions same-named types from
+different source APIs, and a union of identical definitions is that definition.
+The `Node` / `PageInfo` / `SortOrder` base types already rely on exactly this.
+*/
+let semanticCompositeNames = [
+  (Reventless.Semantic.Id.money, "Money"),
+  (Reventless.Semantic.Id.dateRange, "DateRange"),
+  (Reventless.Semantic.Id.geoPoint, "GeoPoint"),
+]
+
+let canonicalName = (id: string): option<string> =>
+  semanticCompositeNames
+  ->Array.find(((semanticId, _)) => semanticId == id)
+  ->Option.map(((_, name)) => name)
+
 let rec fromSury = (~parentName: string, ~fieldName: string, schema: S.t<unknown>): schemaType => {
-  let shape = shapeOf(~parentName, ~fieldName, schema)
   // Semantics the IR already has a dedicated shape for keep it: `dateTime` and
   // `reference` are read below via `isDateTime` / `getTarget`, both of which now
   // consult the generic marker, and their `format` output is a published
@@ -42,8 +68,16 @@ let rec fromSury = (~parentName: string, ~fieldName: string, schema: S.t<unknown
   switch Reventless.Semantic.get(schema) {
   | Some({id} as sem)
     if id !== Reventless.Semantic.Id.dateTime && id !== Reventless.Semantic.Id.reference =>
+    // A composite is one type wherever it appears, so its shape is walked under
+    // its own name rather than under the field path that reached it. That
+    // renames what is nested inside it too — `Money`'s currency enum becomes
+    // `MoneyCurrency` for every field, rather than one enum per price field.
+    let shape = switch canonicalName(id) {
+    | Some(name) => shapeOf(~parentName=name, ~fieldName="", schema)
+    | None => shapeOf(~parentName, ~fieldName, schema)
+    }
     Semantic(sem, shape)
-  | _ => shape
+  | _ => shapeOf(~parentName, ~fieldName, schema)
   }
 }
 

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

@@ -27,22 +27,41 @@ function isIdsFieldName(name) {
   }
 }
 
+let semanticCompositeNames = [
+  [
+    Semantic$Reventless.Id.money,
+    "Money"
+  ],
+  [
+    Semantic$Reventless.Id.dateRange,
+    "DateRange"
+  ],
+  [
+    Semantic$Reventless.Id.geoPoint,
+    "GeoPoint"
+  ]
+];
+
+function canonicalName(id) {
+  return Stdlib_Option.map(semanticCompositeNames.find(param => param[0] === id), param => param[1]);
+}
+
 function fromSury(parentName, fieldName, schema) {
-  let shape = shapeOf(parentName, fieldName, schema);
   let sem = Semantic$Reventless.get(schema);
   if (sem === undefined) {
-    return shape;
+    return shapeOf(parentName, fieldName, schema);
   }
   let id = sem.id;
-  if (id !== Semantic$Reventless.Id.dateTime && id !== Semantic$Reventless.Id.reference) {
-    return {
-      TAG: "Semantic",
-      _0: sem,
-      _1: shape
-    };
-  } else {
-    return shape;
+  if (id === Semantic$Reventless.Id.dateTime || id === Semantic$Reventless.Id.reference) {
+    return shapeOf(parentName, fieldName, schema);
   }
+  let name = canonicalName(id);
+  let shape = name !== undefined ? shapeOf(name, "", schema) : shapeOf(parentName, fieldName, schema);
+  return {
+    TAG: "Semantic",
+    _0: sem,
+    _1: shape
+  };
 }
 
 function shapeOf(parentName, fieldName, schema) {
@@ -195,6 +214,8 @@ export {
   isDateTime,
   isIdFieldName,
   isIdsFieldName,
+  semanticCompositeNames,
+  canonicalName,
   fromSury,
   shapeOf,
   optionalFieldNames,

package/src/plugin/component/Plugin_Structure.res

@@ -650,6 +650,12 @@ let make = (
       let qf = Api_Naming.queryFieldNamesForReadModel(~plugin=name, ~name=R.Spec.name)
       let stateSchema = R.Spec.stateSchema->S.castToUnknown
       let label = labelFieldsFromStateSchema(~entityName=R.Spec.name, stateSchema)
+      // The same call the capability deriver makes, so the published key and the
+      // key the generated filter/order-by is built from cannot disagree.
+      let keyField = GraphQL_FragmentGenerator.resolveKeyField(
+        ~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
@@ -667,6 +673,12 @@ let make = (
         statusField: statusFieldFromStateSchema(~entityName=R.Spec.name, stateSchema),
         visibility: visibilityTag(R.Spec.visibility),
         chapter: chapterOf(R.Spec.name),
+        // Taken from the `qf` record, never re-derived: `Api_Naming` is the only
+        // place that decides how `Products`/`Categories` singularise, and the
+        // point of publishing the name is that a consumer stops guessing it.
+        singleQueryField: Some(qf.singleFieldName),
+        idField: keyField->Option.map(((f, _)) => f),
+        idFieldSource: keyField->Option.map(((_, rung)) => rung),
       }: Reventless.Plugin.queryableDef)
     })
 
@@ -676,6 +688,10 @@ let make = (
       let (_, consumed) = svsConsumed->Array.getUnsafe(i)
       let stateSchema = SVS.Spec.stateSchema->S.castToUnknown
       let label = labelFieldsFromStateSchema(~entityName=SVS.Spec.name, stateSchema)
+      let keyField = GraphQL_FragmentGenerator.resolveKeyField(
+        ~entityName=SVS.Spec.name,
+        stateSchema,
+      )
       ({
         Reventless.Plugin.name: SVS.Spec.name,
         queryField: qf.listFieldName,
@@ -688,6 +704,9 @@ let make = (
         statusField: statusFieldFromStateSchema(~entityName=SVS.Spec.name, stateSchema),
         visibility: visibilityTag(SVS.Spec.visibility),
         chapter: chapterOf(SVS.Spec.name),
+        singleQueryField: Some(qf.singleFieldName),
+        idField: keyField->Option.map(((f, _)) => f),
+        idFieldSource: keyField->Option.map(((_, rung)) => rung),
       }: Reventless.Plugin.queryableDef)
     })
 

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

@@ -19,6 +19,7 @@ import * as SuryToJsonSchema$ReventlessCore from "../../components/Api/SuryToJso
 import * as Capability_Inference$ReventlessCore from "./Capability_Inference.res.mjs";
 import * as ApiTargetStateHelpers$ReventlessCore from "../../components/Api/ApiTargetStateHelpers.res.mjs";
 import * as ApiAllowedStatesHelpers$ReventlessCore from "../../components/Api/ApiAllowedStatesHelpers.res.mjs";
+import * as GraphQL_FragmentGenerator$ReventlessCore from "../../components/Api/GraphQL_FragmentGenerator.res.mjs";
 
 let log = Logger$ReventlessCore.fromEnv();
 
@@ -500,6 +501,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let qf = Api_Naming$ReventlessCore.queryFieldNamesForReadModel(name, R.Spec.name, undefined);
     let stateSchema = R.Spec.stateSchema;
     let label = labelFieldsFromStateSchema(R.Spec.name, stateSchema);
+    let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField(R.Spec.name, stateSchema);
     let consumed = qualify(name, R.consumedEventNames);
     return {
       name: R.Spec.name,
@@ -512,7 +514,10 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       labelFieldSource: labelFieldSourceToString(label.source),
       statusField: statusFieldFromStateSchema(R.Spec.name, stateSchema),
       visibility: visibilityTag(R.Spec.visibility),
-      chapter: componentChapters[R.Spec.name]
+      chapter: componentChapters[R.Spec.name],
+      singleQueryField: qf.singleFieldName,
+      idField: Stdlib_Option.map(keyField, param => param[0]),
+      idFieldSource: Stdlib_Option.map(keyField, param => param[1])
     };
   });
   let stateViewDefs = stateViewSlices.map((SVS, i) => {
@@ -521,6 +526,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let consumed = match[1];
     let stateSchema = SVS.Spec.stateSchema;
     let label = labelFieldsFromStateSchema(SVS.Spec.name, stateSchema);
+    let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField(SVS.Spec.name, stateSchema);
     return {
       name: SVS.Spec.name,
       queryField: qf.listFieldName,
@@ -532,7 +538,10 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       labelFieldSource: labelFieldSourceToString(label.source),
       statusField: statusFieldFromStateSchema(SVS.Spec.name, stateSchema),
       visibility: visibilityTag(SVS.Spec.visibility),
-      chapter: componentChapters[SVS.Spec.name]
+      chapter: componentChapters[SVS.Spec.name],
+      singleQueryField: qf.singleFieldName,
+      idField: Stdlib_Option.map(keyField, param => param[0]),
+      idFieldSource: Stdlib_Option.map(keyField, param => param[1])
     };
   });
   let stateChangeDefs = stateChangeSlices.map((SCS, i) => {

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -31,6 +31,9 @@ let qbl: queryableDef = {
   statusField: None,
   visibility: None,
   chapter: None,
+  singleQueryField: Some("Catalog_Product"),
+  idField: Some("productId"),
+  idFieldSource: Some("convention"),
 }
 
 let wbl: writableDef = {
@@ -252,6 +255,9 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
     statusField: None,
     visibility: Some("Internal"),
     chapter: None,
+    singleQueryField: Some("Ordering_AvailableProduct"),
+    idField: Some("productId"),
+    idFieldSource: Some("sole"),
   }
   // A distinct name per source array: the complement has to be fed by both, and
   // reusing one def would hide a version that only walks `readModels`.
@@ -342,6 +348,9 @@ describe("allowedStates + statusField populated", () => {
     statusField: Some("status"),
     visibility: None,
     chapter: None,
+    singleQueryField: Some("Platform_Plugin"),
+    idField: None,
+    idFieldSource: None,
   }
 
   let wblWithStates: writableDef = {
@@ -395,3 +404,57 @@ describe("allowedStates + statusField populated", () => {
     expect(json->String.includes("\"errors\":null"))->toEqual(false)
   })
 })
+
+// The name exists so a consumer can stop re-implementing `Api_Naming.singularize`;
+// it is only worth publishing if it reaches the caller intact, so assert the wire
+// value and the SDL that types it, not just the record field.
+describe("singleQueryField reaches the caller", () => {
+  testSync("encodes the stated singular beside the list field", () => {
+    expect(json->String.includes("\"queryField\":\"Catalog_Products\""))->toEqual(true)
+    expect(json->String.includes("\"singleQueryField\":\"Catalog_Product\""))->toEqual(true)
+  })
+
+  // Nullable on purpose: a structure persisted before the field existed, or a
+  // hand-rolled def that declines to state it, must decode rather than fail.
+  testSync("encodes an unstated singular as null", () => {
+    let unstated =
+      {...structure, readModels: [{...qbl, singleQueryField: None}]}
+      ->Platform_ComponentDefinitionsApi.encodePluginStructureEntry(~pluginId="Catalog", _)
+      ->JSON.stringify
+    expect(unstated->String.includes("\"singleQueryField\":null"))->toEqual(true)
+  })
+
+  testSync("types it as a nullable String on the read-side SDL", () => {
+    let sdl = Platform_ComponentDefinitionsApi.sdlTypes->Array.join("\n")
+    expect(sdl->String.includes("singleQueryField: String\n"))->toEqual(true)
+    expect(sdl->String.includes("singleQueryField: String!"))->toEqual(false)
+  })
+})
+
+// The key and its rung travel together: a consumer ranking its own guess against
+// this one needs both, so a version that carried the field and dropped the
+// provenance would be worse than useless.
+describe("idField / idFieldSource reach the caller", () => {
+  testSync("encodes the key field and the rung that produced it", () => {
+    expect(json->String.includes("\"idField\":\"productId\""))->toEqual(true)
+    expect(json->String.includes("\"idFieldSource\":\"convention\""))->toEqual(true)
+  })
+
+  // A state whose key cannot be resolved (several `*Id` fields and no name match,
+  // or none at all) has nothing to report — null, not an invented field name.
+  testSync("encodes an unresolved key as null on both fields", () => {
+    let unresolved =
+      {...structure, readModels: [{...qbl, idField: None, idFieldSource: None}]}
+      ->Platform_ComponentDefinitionsApi.encodePluginStructureEntry(~pluginId="Catalog", _)
+      ->JSON.stringify
+    expect(unresolved->String.includes("\"idField\":null"))->toEqual(true)
+    expect(unresolved->String.includes("\"idFieldSource\":null"))->toEqual(true)
+  })
+
+  testSync("types both as nullable Strings on the read-side SDL", () => {
+    let sdl = Platform_ComponentDefinitionsApi.sdlTypes->Array.join("\n")
+    expect(sdl->String.includes("idField: String\n"))->toEqual(true)
+    expect(sdl->String.includes("idFieldSource: String\n"))->toEqual(true)
+    expect(sdl->String.includes("idField: String!"))->toEqual(false)
+  })
+})

package/tests/admin/Platform_ComponentDefinitionsApiTest.res.mjs

@@ -34,6 +34,12 @@ let qbl_searchableFields = ["displayName"];
 
 let qbl_labelFieldSource = "annotation";
 
+let qbl_singleQueryField = "Catalog_Product";
+
+let qbl_idField = "productId";
+
+let qbl_idFieldSource = "convention";
+
 let qbl = {
   name: "Products",
   queryField: "Catalog_Products",
@@ -45,7 +51,10 @@ let qbl = {
   labelFieldSource: qbl_labelFieldSource,
   statusField: undefined,
   visibility: undefined,
-  chapter: undefined
+  chapter: undefined,
+  singleQueryField: qbl_singleQueryField,
+  idField: qbl_idField,
+  idFieldSource: qbl_idFieldSource
 };
 
 let wbl_commands = [cmd];
@@ -257,6 +266,9 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
   let internalQbl_searchableFields = ["name"];
   let internalQbl_labelFieldSource = "convention";
   let internalQbl_visibility = "Internal";
+  let internalQbl_singleQueryField = "Ordering_AvailableProduct";
+  let internalQbl_idField = "productId";
+  let internalQbl_idFieldSource = "sole";
   let internalQbl = {
     name: "AvailableProducts",
     queryField: "Ordering_AvailableProducts",
@@ -268,13 +280,19 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     labelFieldSource: internalQbl_labelFieldSource,
     statusField: undefined,
     visibility: internalQbl_visibility,
-    chapter: undefined
+    chapter: undefined,
+    singleQueryField: internalQbl_singleQueryField,
+    idField: internalQbl_idField,
+    idFieldSource: internalQbl_idFieldSource
   };
   let internalSlice_consumedEventTypes = internalQbl_consumedEventTypes;
   let internalSlice_linkedWriteSide = internalQbl_linkedWriteSide;
   let internalSlice_searchableFields = internalQbl_searchableFields;
   let internalSlice_labelFieldSource = "convention";
   let internalSlice_visibility = "Internal";
+  let internalSlice_singleQueryField = "Ordering_AvailableProduct";
+  let internalSlice_idField = "productId";
+  let internalSlice_idFieldSource = "sole";
   let internalSlice = {
     name: "PendingShipments",
     queryField: "Ordering_PendingShipments",
@@ -286,7 +304,10 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     labelFieldSource: internalSlice_labelFieldSource,
     statusField: undefined,
     visibility: internalSlice_visibility,
-    chapter: undefined
+    chapter: undefined,
+    singleQueryField: internalSlice_singleQueryField,
+    idField: internalSlice_idField,
+    idFieldSource: internalSlice_idFieldSource
   };
   let mixed_readModels = [
     qbl,
@@ -371,6 +392,7 @@ globalThis.describe("allowedStates + statusField populated", () => {
   let qblWithStatus_searchableFields = ["name"];
   let qblWithStatus_labelFieldSource = "convention";
   let qblWithStatus_statusField = "status";
+  let qblWithStatus_singleQueryField = "Platform_Plugin";
   let qblWithStatus = {
     name: "Plugin",
     queryField: "Platform_Plugins",
@@ -382,7 +404,10 @@ globalThis.describe("allowedStates + statusField populated", () => {
     labelFieldSource: qblWithStatus_labelFieldSource,
     statusField: qblWithStatus_statusField,
     visibility: undefined,
-    chapter: undefined
+    chapter: undefined,
+    singleQueryField: qblWithStatus_singleQueryField,
+    idField: undefined,
+    idFieldSource: undefined
   };
   let wblWithStates_commands = [cmdWithStates];
   let wblWithStates_producedEventTypes = [];
@@ -438,6 +463,94 @@ globalThis.describe("allowedStates + statusField populated", () => {
   });
 });
 
+globalThis.describe("singleQueryField reaches the caller", () => {
+  globalThis.test("encodes the stated singular beside the list field", () => {
+    globalThis.expect(json.includes("\"queryField\":\"Catalog_Products\"")).toEqual(true);
+    globalThis.expect(json.includes("\"singleQueryField\":\"Catalog_Product\"")).toEqual(true);
+  });
+  globalThis.test("encodes an unstated singular as null", () => {
+    let unstated = JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Catalog", {
+      readModels: [{
+          name: "Products",
+          queryField: "Catalog_Products",
+          schema: "{}",
+          consumedEventTypes: qbl_consumedEventTypes,
+          linkedWriteSide: qbl_linkedWriteSide,
+          labelField: "displayName",
+          searchableFields: qbl_searchableFields,
+          labelFieldSource: "annotation",
+          statusField: undefined,
+          visibility: undefined,
+          chapter: undefined,
+          singleQueryField: undefined,
+          idField: "productId",
+          idFieldSource: "convention"
+        }],
+      stateViewSlices: structure_stateViewSlices,
+      stateChangeSlices: structure_stateChangeSlices,
+      aggregates: structure_aggregates,
+      automationSlices: structure_automationSlices,
+      outboundTranslationSlices: structure_outboundTranslationSlices,
+      inboundTranslationSlices: structure_inboundTranslationSlices,
+      extensions: structure_extensions,
+      extensionPoints: undefined,
+      requiredStores: undefined,
+      requiredStoreDeclarations: undefined
+    }));
+    globalThis.expect(unstated.includes("\"singleQueryField\":null")).toEqual(true);
+  });
+  globalThis.test("types it as a nullable String on the read-side SDL", () => {
+    let sdl = Platform_ComponentDefinitionsApi$ReventlessCore.sdlTypes.join("\n");
+    globalThis.expect(sdl.includes("singleQueryField: String\n")).toEqual(true);
+    globalThis.expect(sdl.includes("singleQueryField: String!")).toEqual(false);
+  });
+});
+
+globalThis.describe("idField / idFieldSource reach the caller", () => {
+  globalThis.test("encodes the key field and the rung that produced it", () => {
+    globalThis.expect(json.includes("\"idField\":\"productId\"")).toEqual(true);
+    globalThis.expect(json.includes("\"idFieldSource\":\"convention\"")).toEqual(true);
+  });
+  globalThis.test("encodes an unresolved key as null on both fields", () => {
+    let unresolved = JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Catalog", {
+      readModels: [{
+          name: "Products",
+          queryField: "Catalog_Products",
+          schema: "{}",
+          consumedEventTypes: qbl_consumedEventTypes,
+          linkedWriteSide: qbl_linkedWriteSide,
+          labelField: "displayName",
+          searchableFields: qbl_searchableFields,
+          labelFieldSource: "annotation",
+          statusField: undefined,
+          visibility: undefined,
+          chapter: undefined,
+          singleQueryField: "Catalog_Product",
+          idField: undefined,
+          idFieldSource: undefined
+        }],
+      stateViewSlices: structure_stateViewSlices,
+      stateChangeSlices: structure_stateChangeSlices,
+      aggregates: structure_aggregates,
+      automationSlices: structure_automationSlices,
+      outboundTranslationSlices: structure_outboundTranslationSlices,
+      inboundTranslationSlices: structure_inboundTranslationSlices,
+      extensions: structure_extensions,
+      extensionPoints: undefined,
+      requiredStores: undefined,
+      requiredStoreDeclarations: undefined
+    }));
+    globalThis.expect(unresolved.includes("\"idField\":null")).toEqual(true);
+    globalThis.expect(unresolved.includes("\"idFieldSource\":null")).toEqual(true);
+  });
+  globalThis.test("types both as nullable Strings on the read-side SDL", () => {
+    let sdl = Platform_ComponentDefinitionsApi$ReventlessCore.sdlTypes.join("\n");
+    globalThis.expect(sdl.includes("idField: String\n")).toEqual(true);
+    globalThis.expect(sdl.includes("idFieldSource: String\n")).toEqual(true);
+    globalThis.expect(sdl.includes("idField: String!")).toEqual(false);
+  });
+});
+
 export {
   cmd,
   qbl,

package/tests/admin/Platform_PluginStructuresApiTest.res

@@ -19,6 +19,9 @@ let publicRm: queryableDef = {
   statusField: None,
   visibility: None,
   chapter: Some("Inventory"),
+  singleQueryField: Some("Catalog_Product"),
+  idField: Some("productId"),
+  idFieldSource: Some("convention"),
 }
 
 // The component `Platform_ComponentDefinitions` drops and this query must keep.
@@ -113,6 +116,13 @@ describe("Platform_PluginStructures entry", () => {
     )->toEqual(true)
   )
 
+  // Both read-side queries share `encodeQueryableDef`, so this asserts the singular
+  // name is not a ComponentDefinitions-only field: a developer tool building a detail
+  // query reads it from here.
+  testSync("encodes the singular query field beside the list one", () =>
+    expect(json->String.includes("\"singleQueryField\":\"Catalog_Product\""))->toEqual(true)
+  )
+
   testSync("encodes required stores with their provenance", () =>
     expect(json->String.includes("\"requiredStores\":[\"Catalog.images\"]"))->toEqual(true)
   )

package/tests/admin/Platform_PluginStructuresApiTest.res.mjs

@@ -16,6 +16,12 @@ let publicRm_labelFieldSource = "annotation";
 
 let publicRm_chapter = "Inventory";
 
+let publicRm_singleQueryField = "Catalog_Product";
+
+let publicRm_idField = "productId";
+
+let publicRm_idFieldSource = "convention";
+
 let publicRm = {
   name: "Products",
   queryField: "Catalog_Products",
@@ -27,7 +33,10 @@ let publicRm = {
   labelFieldSource: publicRm_labelFieldSource,
   statusField: undefined,
   visibility: undefined,
-  chapter: publicRm_chapter
+  chapter: publicRm_chapter,
+  singleQueryField: publicRm_singleQueryField,
+  idField: publicRm_idField,
+  idFieldSource: publicRm_idFieldSource
 };
 
 let internalRm_consumedEventTypes = publicRm_consumedEventTypes;
@@ -42,6 +51,12 @@ let internalRm_visibility = "Internal";
 
 let internalRm_chapter = "Inventory";
 
+let internalRm_singleQueryField = "Catalog_Product";
+
+let internalRm_idField = "productId";
+
+let internalRm_idFieldSource = "convention";
+
 let internalRm = {
   name: "ProductAudit",
   queryField: "Catalog_ProductAudit",
@@ -53,7 +68,10 @@ let internalRm = {
   labelFieldSource: internalRm_labelFieldSource,
   statusField: undefined,
   visibility: internalRm_visibility,
-  chapter: internalRm_chapter
+  chapter: internalRm_chapter,
+  singleQueryField: internalRm_singleQueryField,
+  idField: internalRm_idField,
+  idFieldSource: internalRm_idFieldSource
 };
 
 let structure_readModels = [
@@ -150,6 +168,9 @@ globalThis.describe("Platform_PluginStructures entry", () => {
   globalThis.test("encodes extension points with their source event types", () => {
     globalThis.expect(json.includes("\"extensionPoints\":[{\"name\":\"Catalog.Products\",\"delegateNames\":[\"onAdded\"],\"sourceEventTypes\":[\"Catalog.ProductAdded\"],\"commandTypes\":null}]")).toEqual(true);
   });
+  globalThis.test("encodes the singular query field beside the list one", () => {
+    globalThis.expect(json.includes("\"singleQueryField\":\"Catalog_Product\"")).toEqual(true);
+  });
   globalThis.test("encodes required stores with their provenance", () => {
     globalThis.expect(json.includes("\"requiredStores\":[\"Catalog.images\"]")).toEqual(true);
   });