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

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 = {
@@ -106,6 +109,7 @@ describe("encodePluginStructureEntry", () => {
       "automationSlices",
       "extensions",
       "inboundTranslationSlices",
+      "internalQueryables",
       "outboundTranslationSlices",
       "pluginId",
       "readModels",
@@ -251,22 +255,72 @@ 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`.
+  let internalSlice: queryableDef = {
+    ...internalQbl,
+    name: "PendingShipments",
+    queryField: "Ordering_PendingShipments",
   }
   let mixed: pluginStructure = {
     ...structure,
     readModels: [qbl, internalQbl],
-    stateViewSlices: [internalQbl],
+    stateViewSlices: [internalSlice],
   }
-  let mixedJson =
-    Platform_ComponentDefinitionsApi.encodePluginStructureEntry(~pluginId="Ordering", mixed)->JSON.stringify
+  let mixedEntry =
+    Platform_ComponentDefinitionsApi.encodePluginStructureEntry(~pluginId="Ordering", mixed)
+
+  // Names under one key of the encoded entry. `String.includes` over the whole
+  // JSON can no longer answer this: an Internal view is legitimately present
+  // under `internalQueryables`, so a whole-document search cannot tell "kept out
+  // of the surfaces" from "dropped entirely" — which is the distinction the
+  // feature is.
+  let namesAt = (entry: JSON.t, key: string): array<string> =>
+    entry
+    ->JSON.Decode.object
+    ->Option.flatMap(o => o->Dict.get(key))
+    ->Option.flatMap(JSON.Decode.array)
+    ->Option.getOr([])
+    ->Array.filterMap(c =>
+      c->JSON.Decode.object->Option.flatMap(o => o->Dict.get("name"))->Option.flatMap(JSON.Decode.string)
+    )
+
+  testSync("excludes an Internal queryableDef from the encoded read-side", () => {
+    expect(mixedEntry->namesAt("readModels"))->toEqual(["Products"])
+    expect(mixedEntry->namesAt("stateViewSlices"))->toEqual([])
+  })
 
-  testSync("excludes an Internal queryableDef from the encoded read-side", () =>
-    expect(mixedJson->String.includes("AvailableProducts"))->toEqual(false)
+  testSync("keeps a Public queryableDef", () =>
+    expect(mixedEntry->namesAt("readModels")->Array.includes("Products"))->toEqual(true)
   )
 
-  testSync("keeps a Public queryableDef", () =>
-    expect(mixedJson->String.includes("\"name\":\"Products\""))->toEqual(true)
+  // Both directions, deliberately: a change that also leaked Internal views back
+  // into the surface lists would pass a presence-only assertion.
+  testSync("carries what the filter removed on internalQueryables", () =>
+    expect(mixedEntry->namesAt("internalQueryables"))->toEqual([
+      "AvailableProducts",
+      "PendingShipments",
+    ])
   )
+
+  testSync("encodes internalQueryables as [] for an all-Public entry, not a missing key", () => {
+    let entry = Platform_ComponentDefinitionsApi.encodePluginStructureEntry(
+      ~pluginId="Ordering",
+      {...structure, readModels: [qbl], stateViewSlices: []},
+    )
+    expect(
+      entry->JSON.Decode.object->Option.flatMap(o => o->Dict.get("internalQueryables")),
+    )->toEqual(Some(JSON.Encode.array([])))
+  })
+
+  testSync("declares internalQueryables on the entry type in the SDL", () => {
+    let sdl = Platform_ComponentDefinitionsApi.sdlTypes->Array.join("\n")
+    expect(sdl->String.includes("internalQueryables: [Platform_ReadSideDef!]!"))->toEqual(true)
+  })
 })
 
 describe("allowedStates + statusField populated", () => {
@@ -294,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 = {
@@ -347,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

@@ -1,6 +1,7 @@
 // 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 Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as Platform_ComponentDefinitionsApi$ReventlessCore from "../../src/admin/Platform_ComponentDefinitionsApi.res.mjs";
@@ -33,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",
@@ -44,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];
@@ -146,6 +156,7 @@ globalThis.describe("encodePluginStructureEntry", () => {
       "automationSlices",
       "extensions",
       "inboundTranslationSlices",
+      "internalQueryables",
       "outboundTranslationSlices",
       "pluginId",
       "readModels",
@@ -255,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",
@@ -266,13 +280,40 @@ 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",
+    schema: "{}",
+    consumedEventTypes: internalSlice_consumedEventTypes,
+    linkedWriteSide: internalSlice_linkedWriteSide,
+    labelField: "name",
+    searchableFields: internalSlice_searchableFields,
+    labelFieldSource: internalSlice_labelFieldSource,
+    statusField: undefined,
+    visibility: internalSlice_visibility,
+    chapter: undefined,
+    singleQueryField: internalSlice_singleQueryField,
+    idField: internalSlice_idField,
+    idFieldSource: internalSlice_idFieldSource
   };
   let mixed_readModels = [
     qbl,
     internalQbl
   ];
-  let mixed_stateViewSlices = [internalQbl];
+  let mixed_stateViewSlices = [internalSlice];
   let mixed_stateChangeSlices = structure_stateChangeSlices;
   let mixed_aggregates = structure_aggregates;
   let mixed_automationSlices = structure_automationSlices;
@@ -292,12 +333,40 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     requiredStores: undefined,
     requiredStoreDeclarations: undefined
   };
-  let mixedJson = JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Ordering", mixed));
+  let mixedEntry = Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Ordering", mixed);
+  let namesAt = (entry, key) => Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(entry), o => o[key]), Stdlib_JSON.Decode.array), []), c => Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(c), o => o["name"]), Stdlib_JSON.Decode.string));
   globalThis.test("excludes an Internal queryableDef from the encoded read-side", () => {
-    globalThis.expect(mixedJson.includes("AvailableProducts")).toEqual(false);
+    globalThis.expect(namesAt(mixedEntry, "readModels")).toEqual(["Products"]);
+    globalThis.expect(namesAt(mixedEntry, "stateViewSlices")).toEqual([]);
   });
   globalThis.test("keeps a Public queryableDef", () => {
-    globalThis.expect(mixedJson.includes("\"name\":\"Products\"")).toEqual(true);
+    globalThis.expect(namesAt(mixedEntry, "readModels").includes("Products")).toEqual(true);
+  });
+  globalThis.test("carries what the filter removed on internalQueryables", () => {
+    globalThis.expect(namesAt(mixedEntry, "internalQueryables")).toEqual([
+      "AvailableProducts",
+      "PendingShipments"
+    ]);
+  });
+  globalThis.test("encodes internalQueryables as [] for an all-Public entry, not a missing key", () => {
+    let entry = Platform_ComponentDefinitionsApi$ReventlessCore.encodePluginStructureEntry("Ordering", {
+      readModels: [qbl],
+      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(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(entry), o => o["internalQueryables"])).toEqual([]);
+  });
+  globalThis.test("declares internalQueryables on the entry type in the SDL", () => {
+    let sdl = Platform_ComponentDefinitionsApi$ReventlessCore.sdlTypes.join("\n");
+    globalThis.expect(sdl.includes("internalQueryables: [Platform_ReadSideDef!]!")).toEqual(true);
   });
 });
 
@@ -323,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",
@@ -334,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 = [];
@@ -390,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);
   });

package/tests/api/Api_IdsTest.res

@@ -0,0 +1,143 @@
+// The id contract: which form each door accepts, in one place.
+//
+// A row advertises a Relay global id (`btoa("<Type>:<localId>")`) while the
+// storage key is the local id. Before this, the typed doors took only the local
+// id, so the obvious `X(id: row.id)` returned null with no error. These pin the
+// rule that makes either form work — and, just as importantly, the cases where a
+// string must NOT be treated as a global id.
+
+open JestGlobals
+
+@val external btoa: string => string = "btoa"
+
+describe("Api_Ids.encode / decode", () => {
+  testSync("round-trips a type name and a local id", () => {
+    let g = Api_Ids.encode(~typeName="Ordering_Customer", ~localId="cust-42")
+    expect(g)->toEqual(btoa("Ordering_Customer:cust-42"))
+    expect(Api_Ids.decode(g))->toEqual(Some(("Ordering_Customer", "cust-42")))
+  })
+
+  // Ids carrying a colon of their own: only the first one separates.
+  testSync("a local id containing a colon survives the round trip", () => {
+    let g = Api_Ids.encode(~typeName="Platform_Plugin", ~localId="Catalog@1.0.0:beta")
+    expect(Api_Ids.decode(g))->toEqual(Some(("Platform_Plugin", "Catalog@1.0.0:beta")))
+  })
+
+  testSync("a plain storage key is not a global id", () =>
+    expect(Api_Ids.decode("cust-42"))->toEqual(None)
+  )
+
+  // `atob` accepts this and yields text with no colon — decoding must still say no.
+  testSync("valid base64 without a colon is not a global id", () =>
+    expect(Api_Ids.decode(btoa("nocolonhere")))->toEqual(None)
+  )
+
+  // A leading colon would mean an empty type name — nothing `node` could resolve.
+  testSync("a decoded value starting with the separator is not a global id", () =>
+    expect(Api_Ids.decode(btoa(":cust-42")))->toEqual(None)
+  )
+})
+
+describe("Api_Ids.alternateKey — the fallback a door tries on a miss", () => {
+  testSync("a global id offers the storage key inside it", () =>
+    expect(Api_Ids.alternateKey(Api_Ids.encode(~typeName="Catalog_Product", ~localId="p-1")))
+    ->toEqual(Some("p-1"))
+  )
+
+  testSync("a plain key offers nothing, so the lookup is never retried", () =>
+    expect(Api_Ids.alternateKey("p-1"))->toEqual(None)
+  )
+
+  // The reason doors try the raw key FIRST and only fall back here: a storage key
+  // that happens to be valid base64 must keep resolving to its own row.
+  testSync("a key that merely looks like base64 is not silently rewritten", () => {
+    let looksBase64 = btoa("Type:inner")
+    expect(Api_Ids.alternateKey(looksBase64))->toEqual(Some("inner"))
+    // …but the door asks for `looksBase64` first, so a row stored under that exact
+    // string wins. `alternateKey` only ever supplies the second attempt.
+    expect(Api_Ids.alternateKey("cGxhaW4="))->toEqual(None)
+  })
+})
+
+// A resolver that stamps the Relay `id` onto a row must not stamp it onto the
+// *stored* row: `JSON.Decode.object` hands back the very object the in-memory
+// QueryDb holds, so a `Dict.set` writes through. The symptom was a row whose
+// advertised id depended on query history — a list answered the storage key
+// until someone loaded the detail page, and the global id ever after.
+describe("stamping an id onto a row leaves the stored row alone", () => {
+  let storedRow = () => {
+    let d = Dict.make()
+    d->Dict.set("id", JSON.Encode.string("cust-42"))
+    d->Dict.set("email", JSON.Encode.string("a@b.c"))
+    JSON.Encode.object(d)
+  }
+
+  testSync("Dict.copy before set — the pattern the resolvers use", () => {
+    let row = storedRow()
+    let stamped = {
+      let obj = row->JSON.Decode.object->Option.mapOr(Dict.make(), Dict.copy)
+      obj->Dict.set(
+        "id",
+        Api_Ids.encode(~typeName="Ordering_Customer", ~localId="cust-42")->JSON.Encode.string,
+      )
+      JSON.Encode.object(obj)
+    }
+    let idOf = j =>
+      j->JSON.Decode.object->Option.flatMap(d => d->Dict.get("id"))->Option.flatMap(JSON.Decode.string)
+    expect(idOf(stamped))->toEqual(Some(Api_Ids.encode(~typeName="Ordering_Customer", ~localId="cust-42")))
+    // The stored row still carries its storage key.
+    expect(idOf(row))->toEqual(Some("cust-42"))
+  })
+})
+
+// `filter.ids` is the door that has always taken either form. Which side needs
+// decoding flipped when the typed doors stopped stamping global ids onto rows:
+// the row now carries its storage key and the *argument* may be the global one.
+describe("filter.ids matches whichever form each side holds", () => {
+  let row = (id: string) => {
+    let d = Dict.make()
+    d->Dict.set("id", JSON.Encode.string(id))
+    d->Dict.set("name", JSON.Encode.string("Alpha"))
+    JSON.Encode.object(d)
+  }
+  let idsIn = (~rowId, ~filterIds) => {
+    let args = Dict.make()
+    args->Dict.set(
+      "filter",
+      JSON.Encode.object(
+        Dict.fromArray([("ids", JSON.Encode.array(filterIds->Array.map(JSON.Encode.string)))]),
+      ),
+    )
+    let conn = QueryDbListQuery.run(
+      ~items=[row(rowId)],
+      ~argsDict=args,
+      ~capability=GraphQL_FragmentGenerator.emptyCapability,
+      ~labelField="name",
+    )
+    conn
+    ->JSON.Decode.object
+    ->Option.flatMap(d => d->Dict.get("edges"))
+    ->Option.flatMap(JSON.Decode.array)
+    ->Option.getOr([])
+    ->Array.length
+  }
+  let globalFor = localId => Api_Ids.encode(~typeName="Catalog_Product", ~localId)
+
+  testSync("storage key row, storage key filter", () =>
+    expect(idsIn(~rowId="p-1", ~filterIds=["p-1"]))->toBe(1)
+  )
+
+  // The case the flip fixes: a client passes back the global id it was given by
+  // `node`, while the list rows carry storage keys.
+  testSync("storage key row, global id filter", () =>
+    expect(idsIn(~rowId="p-1", ~filterIds=[globalFor("p-1")]))->toBe(1)
+  )
+
+  testSync("global id row, storage key filter", () =>
+    expect(idsIn(~rowId=globalFor("p-1"), ~filterIds=["p-1"]))->toBe(1)
+  )
+
+  testSync("a filter for another row still excludes it", () =>
+    expect(idsIn(~rowId="p-1", ~filterIds=[globalFor("p-2")]))->toBe(0)
+  )
+})