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

package/tests/admin/Platform_BakedManifestTest.res

@@ -0,0 +1,244 @@
+// The baked manifest is curation, so what matters is exactly which components
+// survive an include-list — and, decisively, that an entry which includes
+// everything is byte-identical to what the served query returns. Anything less
+// and a shell reading the file is reading a second, quietly different contract.
+
+open JestGlobals
+open Reventless.Plugin
+
+let queryable = (~name, ~visibility=?, ~ownerField=?, ()): queryableDef => {
+  name,
+  queryField: `Ordering_${name}`,
+  schema: "{}",
+  consumedEventTypes: [],
+  linkedWriteSide: [],
+  labelField: "displayName",
+  searchableFields: ["displayName"],
+  labelFieldSource: None,
+  statusField: None,
+  visibility,
+  chapter: None,
+  singleQueryField: Some(`Ordering_${name}Single`),
+  idField: Some("id"),
+  idFieldSource: Some("convention"),
+  requiredAccess: None,
+  ownerField,
+}
+
+let command = (~name, ~references=[], ~ownerField=?, ()): commandDef => {
+  name,
+  schema: "{}",
+  level: Collection,
+  aggregateIdField: None,
+  mutationField: name->String.toLowerCase,
+  references,
+  allowedStates: None,
+  targetState: None,
+  apiExposed: Some(true),
+  requiredAccess: None,
+  ownerField,
+}
+
+let writable = (~name, ~commands): writableDef => {
+  name,
+  commands,
+  linkedViews: [],
+  consistencyRead: None,
+  producedEventTypes: [],
+  consumedEventTypes: [],
+  events: [],
+  errors: [],
+  chapter: None,
+}
+
+// Mirrors the hybrid example's shape: a public order list, an Internal
+// denormalised product mirror a command @refs, one end-user command and one
+// operator command.
+let structure: pluginStructure = {
+  readModels: [queryable(~name="Customers", ())],
+  stateViewSlices: [
+    queryable(~name="Orders", ~ownerField="customerId", ()),
+    queryable(~name="AvailableProducts", ~visibility="Internal", ()),
+  ],
+  stateChangeSlices: [
+    writable(
+      ~name="PlaceOrder",
+      ~commands=[
+        command(
+          ~name="PlaceOrder",
+          ~references=[{fieldName: "productIds", entity: "AvailableProducts", plugin: None}],
+          ~ownerField="customerId",
+          (),
+        ),
+      ],
+    ),
+    writable(~name="ImportOrders", ~commands=[command(~name="ImportOrders", ())]),
+  ],
+  aggregates: [],
+  automationSlices: [],
+  outboundTranslationSlices: [],
+  inboundTranslationSlices: [],
+  extensions: [],
+  extensionPoints: None,
+  requiredStores: None,
+  requiredStoreDeclarations: None,
+}
+
+let structures = [("Ordering@1.0.0", structure)]
+
+let bake = selections =>
+  Platform_BakedManifest.curate(~structures, ~selections)
+
+let entries = (json: JSON.t) => json->JSON.Decode.array->Option.getOr([])
+
+let names = (entry: JSON.t, field: string) =>
+  entry
+  ->JSON.Decode.object
+  ->Option.flatMap(d => d->Dict.get(field))
+  ->Option.flatMap(JSON.Decode.array)
+  ->Option.getOr([])
+  ->Array.filterMap(v =>
+    v->JSON.Decode.object->Option.flatMap(d => d->Dict.get("name"))->Option.flatMap(JSON.Decode.string)
+  )
+
+let firstEntry = (r: result<JSON.t, Platform_BakedManifest.error>) =>
+  switch r {
+  | Ok(json) => json->entries->Array.getUnsafe(0)
+  | Error(e) => JsError.throwWithMessage(Platform_BakedManifest.describe(e))
+  }
+
+describe("curate", () => {
+  testSync("selects exactly the named components", () => {
+    let entry =
+      bake([{plugin: "Ordering", views: Some(["Orders"]), commands: Some(["PlaceOrder"])}])
+      ->firstEntry
+    expect((entry->names("stateViewSlices"), entry->names("readModels")))->toEqual((["Orders"], []))
+  })
+
+  testSync("drops a write side whose commands were all excluded", () => {
+    let entry =
+      bake([{plugin: "Ordering", views: Some([]), commands: Some(["PlaceOrder"])}])->firstEntry
+    expect(entry->names("stateChangeSlices"))->toEqual(["PlaceOrder"])
+  })
+
+  testSync("unset views and commands include every public component", () => {
+    let entry = bake([{plugin: "Ordering", views: None, commands: None}])->firstEntry
+    expect((
+      entry->names("readModels"),
+      entry->names("stateViewSlices"),
+      entry->names("stateChangeSlices"),
+    ))->toEqual((["Customers"], ["Orders"], ["PlaceOrder", "ImportOrders"]))
+  })
+
+  // A shell reading a baked file has no admin API to recover a reference target
+  // from, so an Internal view a kept command points at has to survive the bake.
+  testSync("carries an Internal view referenced by an included command", () => {
+    let entry =
+      bake([{plugin: "Ordering", views: Some(["Orders"]), commands: Some(["PlaceOrder"])}])
+      ->firstEntry
+    expect(entry->names("internalQueryables"))->toEqual(["AvailableProducts"])
+  })
+
+  testSync("omits an Internal view no included command references", () => {
+    let entry =
+      bake([{plugin: "Ordering", views: Some(["Orders"]), commands: Some(["ImportOrders"])}])
+      ->firstEntry
+    expect(entry->names("internalQueryables"))->toEqual([])
+  })
+
+  testSync("an Internal view is never selectable as a view", () =>
+    expect(
+      bake([{plugin: "Ordering", views: Some(["AvailableProducts"]), commands: None}]),
+    )->toEqual(
+      Error(Platform_BakedManifest.UnknownView({plugin: "Ordering", view: "AvailableProducts"})),
+    )
+  )
+
+  testSync("fails naming an unknown plugin", () =>
+    expect(bake([{plugin: "Shipping", views: None, commands: None}]))->toEqual(
+      Error(Platform_BakedManifest.UnknownPlugin("Shipping")),
+    )
+  )
+
+  testSync("fails naming an unknown command", () =>
+    expect(bake([{plugin: "Ordering", views: None, commands: Some(["CancelOrder"])}]))->toEqual(
+      Error(Platform_BakedManifest.UnknownCommand({plugin: "Ordering", command: "CancelOrder"})),
+    )
+  )
+
+  // The anti-drift assertion: include everything and the baked entry IS the
+  // served entry. Any future divergence in the encoder shows up here first.
+  testSync("an all-inclusive bake is byte-identical to the served entry", () => {
+    let baked = bake([{plugin: "Ordering", views: None, commands: None}])->firstEntry
+    let served = Platform_ComponentDefinitionsApi.encodePluginStructureEntry(
+      ~pluginId="Ordering@1.0.0",
+      structure,
+    )
+    expect(baked->JSON.stringify)->toEqual(served->JSON.stringify)
+  })
+
+  testSync("one entry per selection, in declaration order", () => {
+    let json =
+      Platform_BakedManifest.curate(
+        ~structures=[("Ordering@1.0.0", structure), ("Catalog@1.0.0", structure)],
+        ~selections=[
+          {plugin: "Catalog", views: Some([]), commands: Some([])},
+          {plugin: "Ordering", views: Some([]), commands: Some([])},
+        ],
+      )
+    let ids =
+      switch json {
+      | Ok(j) =>
+        j
+        ->entries
+        ->Array.filterMap(e =>
+          e
+          ->JSON.Decode.object
+          ->Option.flatMap(d => d->Dict.get("pluginId"))
+          ->Option.flatMap(JSON.Decode.string)
+        )
+      | Error(_) => []
+      }
+    expect(ids)->toEqual(["Catalog", "Ordering"])
+  })
+
+  // A shell reading a baked manifest has no admin API to ask instead, so a field
+  // the curation step forgot to copy is a field that view can never learn about.
+  // `curate` reuses the served encoder rather than writing its own, which is what
+  // makes this hold — the assertion guards that property, not a second code path.
+  testSync("a curated entry carries the owner field the served entry carries", () => {
+    let entry =
+      bake([{plugin: "Ordering", views: Some(["Orders"]), commands: Some(["PlaceOrder"])}])
+      ->firstEntry
+    let ownerOf = (key, name) =>
+      entry
+      ->JSON.Decode.object
+      ->Option.flatMap(d => d->Dict.get(key))
+      ->Option.flatMap(JSON.Decode.array)
+      ->Option.getOr([])
+      ->Array.filterMap(JSON.Decode.object)
+      ->Array.find(d =>
+        d->Dict.get("name")->Option.flatMap(JSON.Decode.string) == Some(name)
+      )
+      ->Option.flatMap(d => d->Dict.get("ownerField"))
+      ->Option.flatMap(JSON.Decode.string)
+    let commandOwner =
+      entry
+      ->JSON.Decode.object
+      ->Option.flatMap(d => d->Dict.get("stateChangeSlices"))
+      ->Option.flatMap(JSON.Decode.array)
+      ->Option.getOr([])
+      ->Array.filterMap(JSON.Decode.object)
+      ->Array.flatMap(w =>
+        w->Dict.get("commands")->Option.flatMap(JSON.Decode.array)->Option.getOr([])
+      )
+      ->Array.filterMap(JSON.Decode.object)
+      ->Array.get(0)
+      ->Option.flatMap(d => d->Dict.get("ownerField"))
+      ->Option.flatMap(JSON.Decode.string)
+    expect((ownerOf("stateViewSlices", "Orders"), commandOwner))->toEqual((
+      Some("customerId"),
+      Some("customerId"),
+    ))
+  })
+})

package/tests/admin/Platform_BakedManifestTest.res.mjs

@@ -0,0 +1,294 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Platform_BakedManifest$ReventlessCore from "../../src/admin/Platform_BakedManifest.res.mjs";
+import * as Platform_ComponentDefinitionsApi$ReventlessCore from "../../src/admin/Platform_ComponentDefinitionsApi.res.mjs";
+
+function queryable(name, visibility, ownerField, param) {
+  return {
+    name: name,
+    queryField: `Ordering_` + name,
+    schema: "{}",
+    consumedEventTypes: [],
+    linkedWriteSide: [],
+    labelField: "displayName",
+    searchableFields: ["displayName"],
+    labelFieldSource: undefined,
+    statusField: undefined,
+    ownerField: ownerField,
+    visibility: visibility,
+    chapter: undefined,
+    singleQueryField: `Ordering_` + name + `Single`,
+    idField: "id",
+    idFieldSource: "convention",
+    requiredAccess: undefined
+  };
+}
+
+function command(name, referencesOpt, ownerField, param) {
+  let references = referencesOpt !== undefined ? referencesOpt : [];
+  return {
+    name: name,
+    schema: "{}",
+    level: "Collection",
+    aggregateIdField: undefined,
+    mutationField: name.toLowerCase(),
+    references: references,
+    allowedStates: undefined,
+    targetState: undefined,
+    apiExposed: true,
+    requiredAccess: undefined,
+    ownerField: ownerField
+  };
+}
+
+function writable(name, commands) {
+  return {
+    name: name,
+    commands: commands,
+    producedEventTypes: [],
+    consumedEventTypes: [],
+    linkedViews: [],
+    consistencyRead: undefined,
+    events: [],
+    errors: [],
+    chapter: undefined
+  };
+}
+
+let structure_readModels = [queryable("Customers", undefined, undefined, undefined)];
+
+let structure_stateViewSlices = [
+  queryable("Orders", undefined, "customerId", undefined),
+  queryable("AvailableProducts", "Internal", undefined, undefined)
+];
+
+let structure_stateChangeSlices = [
+  writable("PlaceOrder", [command("PlaceOrder", [{
+        fieldName: "productIds",
+        entity: "AvailableProducts",
+        plugin: undefined
+      }], "customerId", undefined)]),
+  writable("ImportOrders", [command("ImportOrders", undefined, undefined, undefined)])
+];
+
+let structure_aggregates = [];
+
+let structure_automationSlices = [];
+
+let structure_outboundTranslationSlices = [];
+
+let structure_inboundTranslationSlices = [];
+
+let structure_extensions = [];
+
+let structure = {
+  readModels: structure_readModels,
+  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
+};
+
+let structures = [[
+    "Ordering@1.0.0",
+    structure
+  ]];
+
+function bake(selections) {
+  return Platform_BakedManifest$ReventlessCore.curate(structures, selections);
+}
+
+function entries(json) {
+  return Stdlib_Option.getOr(Stdlib_JSON.Decode.array(json), []);
+}
+
+function names(entry, field) {
+  return Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(entry), d => d[field]), Stdlib_JSON.Decode.array), []), v => Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(v), d => d["name"]), Stdlib_JSON.Decode.string));
+}
+
+function firstEntry(r) {
+  if (r.TAG === "Ok") {
+    return entries(r._0)[0];
+  } else {
+    return Stdlib_JsError.throwWithMessage(Platform_BakedManifest$ReventlessCore.describe(r._0));
+  }
+}
+
+globalThis.describe("curate", () => {
+  globalThis.test("selects exactly the named components", () => {
+    let entry = firstEntry(Platform_BakedManifest$ReventlessCore.curate(structures, [{
+        plugin: "Ordering",
+        views: ["Orders"],
+        commands: ["PlaceOrder"]
+      }]));
+    globalThis.expect([
+      names(entry, "stateViewSlices"),
+      names(entry, "readModels")
+    ]).toEqual([
+      ["Orders"],
+      []
+    ]);
+  });
+  globalThis.test("drops a write side whose commands were all excluded", () => {
+    let entry = firstEntry(Platform_BakedManifest$ReventlessCore.curate(structures, [{
+        plugin: "Ordering",
+        views: [],
+        commands: ["PlaceOrder"]
+      }]));
+    globalThis.expect(names(entry, "stateChangeSlices")).toEqual(["PlaceOrder"]);
+  });
+  globalThis.test("unset views and commands include every public component", () => {
+    let entry = firstEntry(Platform_BakedManifest$ReventlessCore.curate(structures, [{
+        plugin: "Ordering",
+        views: undefined,
+        commands: undefined
+      }]));
+    globalThis.expect([
+      names(entry, "readModels"),
+      names(entry, "stateViewSlices"),
+      names(entry, "stateChangeSlices")
+    ]).toEqual([
+      ["Customers"],
+      ["Orders"],
+      [
+        "PlaceOrder",
+        "ImportOrders"
+      ]
+    ]);
+  });
+  globalThis.test("carries an Internal view referenced by an included command", () => {
+    let entry = firstEntry(Platform_BakedManifest$ReventlessCore.curate(structures, [{
+        plugin: "Ordering",
+        views: ["Orders"],
+        commands: ["PlaceOrder"]
+      }]));
+    globalThis.expect(names(entry, "internalQueryables")).toEqual(["AvailableProducts"]);
+  });
+  globalThis.test("omits an Internal view no included command references", () => {
+    let entry = firstEntry(Platform_BakedManifest$ReventlessCore.curate(structures, [{
+        plugin: "Ordering",
+        views: ["Orders"],
+        commands: ["ImportOrders"]
+      }]));
+    globalThis.expect(names(entry, "internalQueryables")).toEqual([]);
+  });
+  globalThis.test("an Internal view is never selectable as a view", () => {
+    globalThis.expect(Platform_BakedManifest$ReventlessCore.curate(structures, [{
+        plugin: "Ordering",
+        views: ["AvailableProducts"],
+        commands: undefined
+      }])).toEqual({
+      TAG: "Error",
+      _0: {
+        TAG: "UnknownView",
+        plugin: "Ordering",
+        view: "AvailableProducts"
+      }
+    });
+  });
+  globalThis.test("fails naming an unknown plugin", () => {
+    globalThis.expect(Platform_BakedManifest$ReventlessCore.curate(structures, [{
+        plugin: "Shipping",
+        views: undefined,
+        commands: undefined
+      }])).toEqual({
+      TAG: "Error",
+      _0: {
+        TAG: "UnknownPlugin",
+        _0: "Shipping"
+      }
+    });
+  });
+  globalThis.test("fails naming an unknown command", () => {
+    globalThis.expect(Platform_BakedManifest$ReventlessCore.curate(structures, [{
+        plugin: "Ordering",
+        views: undefined,
+        commands: ["CancelOrder"]
+      }])).toEqual({
+      TAG: "Error",
+      _0: {
+        TAG: "UnknownCommand",
+        plugin: "Ordering",
+        command: "CancelOrder"
+      }
+    });
+  });
+  globalThis.test("an all-inclusive bake is byte-identical to the served entry", () => {
+    let baked = firstEntry(Platform_BakedManifest$ReventlessCore.curate(structures, [{
+        plugin: "Ordering",
+        views: undefined,
+        commands: undefined
+      }]));
+    let served = Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Ordering@1.0.0", structure);
+    globalThis.expect(JSON.stringify(baked)).toEqual(JSON.stringify(served));
+  });
+  globalThis.test("one entry per selection, in declaration order", () => {
+    let json = Platform_BakedManifest$ReventlessCore.curate([
+      [
+        "Ordering@1.0.0",
+        structure
+      ],
+      [
+        "Catalog@1.0.0",
+        structure
+      ]
+    ], [
+      {
+        plugin: "Catalog",
+        views: [],
+        commands: []
+      },
+      {
+        plugin: "Ordering",
+        views: [],
+        commands: []
+      }
+    ]);
+    let ids;
+    ids = json.TAG === "Ok" ? Stdlib_Array.filterMap(entries(json._0), e => Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(e), d => d["pluginId"]), Stdlib_JSON.Decode.string)) : [];
+    globalThis.expect(ids).toEqual([
+      "Catalog",
+      "Ordering"
+    ]);
+  });
+  globalThis.test("a curated entry carries the owner field the served entry carries", () => {
+    let entry = firstEntry(Platform_BakedManifest$ReventlessCore.curate(structures, [{
+        plugin: "Ordering",
+        views: ["Orders"],
+        commands: ["PlaceOrder"]
+      }]));
+    let ownerOf = (key, name) => Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(entry), d => d[key]), Stdlib_JSON.Decode.array), []), Stdlib_JSON.Decode.object).find(d => Primitive_object.equal(Stdlib_Option.flatMap(d["name"], Stdlib_JSON.Decode.string), name)), d => d["ownerField"]), Stdlib_JSON.Decode.string);
+    let commandOwner = Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Array.filterMap(Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(entry), d => d["stateChangeSlices"]), Stdlib_JSON.Decode.array), []), Stdlib_JSON.Decode.object).flatMap(w => Stdlib_Option.getOr(Stdlib_Option.flatMap(w["commands"], Stdlib_JSON.Decode.array), [])), Stdlib_JSON.Decode.object)[0], d => d["ownerField"]), Stdlib_JSON.Decode.string);
+    globalThis.expect([
+      ownerOf("stateViewSlices", "Orders"),
+      commandOwner
+    ]).toEqual([
+      "customerId",
+      "customerId"
+    ]);
+  });
+});
+
+export {
+  queryable,
+  command,
+  writable,
+  structure,
+  structures,
+  bake,
+  entries,
+  names,
+  firstEntry,
+}
+/* structure Not a pure module */

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -17,6 +17,8 @@ let cmd: commandDef = {
   allowedStates: None,
   targetState: None,
   apiExposed: Some(true),
+  requiredAccess: None,
+  ownerField: None,
 }
 
 let qbl: queryableDef = {
@@ -31,6 +33,11 @@ let qbl: queryableDef = {
   statusField: None,
   visibility: None,
   chapter: None,
+  singleQueryField: Some("Catalog_Product"),
+  idField: Some("productId"),
+  idFieldSource: Some("convention"),
+  requiredAccess: None,
+  ownerField: None,
 }
 
 let wbl: writableDef = {
@@ -252,6 +259,11 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
     statusField: None,
     visibility: Some("Internal"),
     chapter: None,
+    singleQueryField: Some("Ordering_AvailableProduct"),
+    idField: Some("productId"),
+    idFieldSource: Some("sole"),
+    requiredAccess: None,
+      ownerField: None,
   }
   // 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`.
@@ -328,6 +340,8 @@ describe("allowedStates + statusField populated", () => {
     allowedStates: Some(["Inactive"]),
     targetState: Some("Active"),
     apiExposed: Some(true),
+    requiredAccess: None,
+      ownerField: None,
   }
 
   let qblWithStatus: queryableDef = {
@@ -342,6 +356,11 @@ describe("allowedStates + statusField populated", () => {
     statusField: Some("status"),
     visibility: None,
     chapter: None,
+    singleQueryField: Some("Platform_Plugin"),
+    idField: None,
+    idFieldSource: None,
+    requiredAccess: None,
+      ownerField: None,
   }
 
   let wblWithStates: writableDef = {
@@ -395,3 +414,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)
+  })
+})