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

package/tests/api/Api_IdsTest.res.mjs

@@ -0,0 +1,97 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Api_Ids$ReventlessCore from "../../src/components/Api/Api_Ids.res.mjs";
+import * as QueryDbListQuery$ReventlessCore from "../../src/components/Api/QueryDbListQuery.res.mjs";
+import * as GraphQL_FragmentGenerator$ReventlessCore from "../../src/components/Api/GraphQL_FragmentGenerator.res.mjs";
+
+globalThis.describe("Api_Ids.encode / decode", () => {
+  globalThis.test("round-trips a type name and a local id", () => {
+    let g = Api_Ids$ReventlessCore.encode("Ordering_Customer", "cust-42");
+    globalThis.expect(g).toEqual(btoa("Ordering_Customer:cust-42"));
+    globalThis.expect(Api_Ids$ReventlessCore.decode(g)).toEqual([
+      "Ordering_Customer",
+      "cust-42"
+    ]);
+  });
+  globalThis.test("a local id containing a colon survives the round trip", () => {
+    let g = Api_Ids$ReventlessCore.encode("Platform_Plugin", "Catalog@1.0.0:beta");
+    globalThis.expect(Api_Ids$ReventlessCore.decode(g)).toEqual([
+      "Platform_Plugin",
+      "Catalog@1.0.0:beta"
+    ]);
+  });
+  globalThis.test("a plain storage key is not a global id", () => {
+    globalThis.expect(Api_Ids$ReventlessCore.decode("cust-42")).toEqual(undefined);
+  });
+  globalThis.test("valid base64 without a colon is not a global id", () => {
+    globalThis.expect(Api_Ids$ReventlessCore.decode(btoa("nocolonhere"))).toEqual(undefined);
+  });
+  globalThis.test("a decoded value starting with the separator is not a global id", () => {
+    globalThis.expect(Api_Ids$ReventlessCore.decode(btoa(":cust-42"))).toEqual(undefined);
+  });
+});
+
+globalThis.describe("Api_Ids.alternateKey — the fallback a door tries on a miss", () => {
+  globalThis.test("a global id offers the storage key inside it", () => {
+    globalThis.expect(Api_Ids$ReventlessCore.alternateKey(Api_Ids$ReventlessCore.encode("Catalog_Product", "p-1"))).toEqual("p-1");
+  });
+  globalThis.test("a plain key offers nothing, so the lookup is never retried", () => {
+    globalThis.expect(Api_Ids$ReventlessCore.alternateKey("p-1")).toEqual(undefined);
+  });
+  globalThis.test("a key that merely looks like base64 is not silently rewritten", () => {
+    let looksBase64 = btoa("Type:inner");
+    globalThis.expect(Api_Ids$ReventlessCore.alternateKey(looksBase64)).toEqual("inner");
+    globalThis.expect(Api_Ids$ReventlessCore.alternateKey("cGxhaW4=")).toEqual(undefined);
+  });
+});
+
+globalThis.describe("stamping an id onto a row leaves the stored row alone", () => {
+  let storedRow = () => {
+    let d = {};
+    d["id"] = "cust-42";
+    d["email"] = "a@b.c";
+    return d;
+  };
+  globalThis.test("Dict.copy before set — the pattern the resolvers use", () => {
+    let row = storedRow();
+    let obj = Stdlib_Option.mapOr(Stdlib_JSON.Decode.object(row), {}, prim => Object.assign({}, prim));
+    obj["id"] = Api_Ids$ReventlessCore.encode("Ordering_Customer", "cust-42");
+    let idOf = j => Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(j), d => d["id"]), Stdlib_JSON.Decode.string);
+    globalThis.expect(idOf(obj)).toEqual(Api_Ids$ReventlessCore.encode("Ordering_Customer", "cust-42"));
+    globalThis.expect(idOf(row)).toEqual("cust-42");
+  });
+});
+
+globalThis.describe("filter.ids matches whichever form each side holds", () => {
+  let row = id => {
+    let d = {};
+    d["id"] = id;
+    d["name"] = "Alpha";
+    return d;
+  };
+  let idsIn = (rowId, filterIds) => {
+    let args = {};
+    args["filter"] = Object.fromEntries([[
+        "ids",
+        filterIds.map(prim => prim)
+      ]]);
+    let conn = QueryDbListQuery$ReventlessCore.run([row(rowId)], args, GraphQL_FragmentGenerator$ReventlessCore.emptyCapability, "name", undefined);
+    return Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(conn), d => d["edges"]), Stdlib_JSON.Decode.array), []).length;
+  };
+  globalThis.test("storage key row, storage key filter", () => {
+    globalThis.expect(idsIn("p-1", ["p-1"])).toBe(1);
+  });
+  globalThis.test("storage key row, global id filter", () => {
+    globalThis.expect(idsIn("p-1", [Api_Ids$ReventlessCore.encode("Catalog_Product", "p-1")])).toBe(1);
+  });
+  globalThis.test("global id row, storage key filter", () => {
+    globalThis.expect(idsIn(Api_Ids$ReventlessCore.encode("Catalog_Product", "p-1"), ["p-1"])).toBe(1);
+  });
+  globalThis.test("a filter for another row still excludes it", () => {
+    globalThis.expect(idsIn("p-1", [Api_Ids$ReventlessCore.encode("Catalog_Product", "p-2")])).toBe(0);
+  });
+});
+
+/*  Not a pure module */

package/tests/api/GraphQL_FragmentGeneratorTest.res

@@ -87,3 +87,172 @@ describe("GraphQL_FragmentGenerator slice TODO rows", () => {
     expect(item->String.includes("address: String!"))->toBe(true)
   })
 })
+
+// A state that declares no `@id` used to produce `emptyCapability` — no per-field
+// filter and no order-by at all, so every narrowing a client asked for happened
+// client-side over one page. The key is knowable without the annotation in the
+// common cases; these pin which cases those are, and which still need `@id`.
+describe("resolveKeyField — the ladder", () => {
+  let rungFor = (~entityName, schema) =>
+    GraphQL_FragmentGenerator.resolveKeyField(~entityName, schema->S.castToUnknown)
+
+  testSync("a lone `*Id` field is the only thing the key could be", () => {
+    let schema = S.schema(s => {"productId": s.matches(S.string), "name": s.matches(S.string)})
+    expect(rungFor(~entityName="AvailableProducts", schema))->toEqual(Some(("productId", "sole")))
+  })
+
+  testSync("several `*Id` fields are disambiguated by the component name", () => {
+    let schema = S.schema(s =>
+      {"productId": s.matches(S.string), "categoryId": s.matches(S.string)}
+    )
+    expect(rungFor(~entityName="Products", schema))->toEqual(Some(("productId", "convention")))
+  })
+
+  // The `-ies` plural the naive singulariser gets wrong, on the key side too.
+  testSync("the convention rung singularises the way Api_Naming does", () => {
+    let schema = S.schema(s =>
+      {"categoryId": s.matches(S.string), "ownerId": s.matches(S.string)}
+    )
+    expect(rungFor(~entityName="Categories", schema))->toEqual(Some(("categoryId", "convention")))
+  })
+
+  // ProductDemand: two `*Id` fields, and the name yields `productDemandId`, which
+  // is not a field. Declining is the honest answer — this is what `@id` is for.
+  testSync("several `*Id` fields with no name match declines", () => {
+    let schema = S.schema(s =>
+      {"productId": s.matches(S.string), "categoryId": s.matches(S.string)}
+    )
+    expect(rungFor(~entityName="ProductDemand", schema))->toEqual(None)
+  })
+
+  testSync("no `*Id` field at all declines", () => {
+    let schema = S.schema(s => {"email": s.matches(S.string), "address": s.matches(S.string)})
+    expect(rungFor(~entityName="Customers", schema))->toEqual(None)
+  })
+
+  // `paid` / `valid` end with a lowercase "id". SchemaType.isIdFieldName accepts
+  // them (it lowercases first, which is right for its own use); a key field must
+  // not be nominated that way.
+  testSync("a word merely ending in `id` is not a key", () => {
+    let schema = S.schema(s => {"paid": s.matches(S.string), "valid": s.matches(S.string)})
+    expect(rungFor(~entityName="Invoices", schema))->toEqual(None)
+  })
+})
+
+describe("deriveServerCapability — inferred keys reach the SDL surface", () => {
+  let capabilityFor = (~entityName, schema) =>
+    GraphQL_FragmentGenerator.deriveServerCapability(~entityName, schema->S.castToUnknown)
+
+  testSync("an inferred key yields an eq filter and a sort field", () => {
+    let schema = S.schema(s => {"orderId": s.matches(S.string), "total": s.matches(S.float)})
+    let c = capabilityFor(~entityName="Orders", schema)
+    expect(c.filterFields->Array.map(f => f.name))->toEqual(["orderId"])
+    expect(c.sortFields)->toEqual(["orderId"])
+  })
+
+  testSync("an unresolvable key still yields nothing — the old behaviour, now narrowed", () => {
+    let schema = S.schema(s => {"email": s.matches(S.string)})
+    let c = capabilityFor(~entityName="Customers", schema)
+    expect((c.filterFields->Array.length, c.sortFields->Array.length))->toEqual((0, 0))
+  })
+
+  testSync("the filter input carries the inferred key's eq field", () => {
+    let schema = S.schema(s => {"orderId": s.matches(S.string)})
+    let input = GraphQL_FragmentGenerator.deriveConnectionFilterType(
+      ~filterTypeName="Ordering_OrderFilter",
+      ~capability=capabilityFor(~entityName="Orders", schema),
+    )
+    // `ID`, not `String`: a `*Id`-named field is an EntityId in the IR, and the
+    // filter input mirrors the field's own GraphQL type.
+    expect(input->String.includes("orderIdEq: ID"))->toBe(true)
+  })
+
+  // No OrderBy type is emitted at all when nothing is sortable, so an inferred
+  // key is the difference between having the type and not having it.
+  testSync("the order-by pair exists because of the inferred key", () => {
+    let schema = S.schema(s => {"orderId": s.matches(S.string)})
+    let types = GraphQL_FragmentGenerator.deriveConnectionOrderByType(
+      ~singularTypeName="Ordering_Order",
+      ~capability=capabilityFor(~entityName="Orders", schema),
+    )
+    expect(types->Array.length)->toBe(2)
+    expect(types->Array.join("\n")->String.includes("enum Ordering_OrderOrderField"))->toBe(true)
+  })
+})
+
+// A semantic composite is one type wherever it appears. Named from the field
+// path that reached it, two commands taking a price produced two identical
+// `{amount, currency}` inputs and, beside each, its own copy of the 165-value
+// ISO 4217 enum — six copies of it across one example schema.
+module AddProductCmd = {
+  @schema
+  type command =
+    | AddProduct({productId: string, price: Reventless.Money.t})
+    | ArchiveProduct({productId: string})
+}
+
+module ChangePriceCmd = {
+  @schema
+  type command =
+    | ChangeProductPrice({productId: string, price: Reventless.Money.t})
+    | ClearProductPrice({productId: string})
+}
+
+describe("semantic composites are named once, not once per field", () => {
+  let countDefs = (types, keyword, name) =>
+    types->Array.filter(t => t->String.startsWith(`${keyword} ${name} {`))->Array.length
+
+  let fragmentTypes = GraphQL_Stitcher.decode(
+    GraphQL_FragmentGenerator.generate(
+      ~mutationEntries=[
+        {
+          ReventlessInfra.Api.fieldNames: ["Catalog_AddProduct"],
+          commandSchema: AddProductCmd.commandSchema->S.castToUnknown,
+          injectIdArg: false,
+        },
+        {
+          ReventlessInfra.Api.fieldNames: ["Catalog_ChangeProductPrice"],
+          commandSchema: ChangePriceCmd.commandSchema->S.castToUnknown,
+          injectIdArg: false,
+        },
+      ],
+      ~queryEntries=[],
+    ),
+  ).types
+
+  testSync("two commands taking a price share one input definition", () =>
+    expect(fragmentTypes->countDefs("input", "MoneyInput"))->toBe(1)
+  )
+
+  testSync("and one currency enum between them", () =>
+    expect(fragmentTypes->countDefs("enum", "MoneyCurrency"))->toBe(1)
+  )
+
+  // The control: these are the names the field-path naming produced, and their
+  // absence is the whole change. Without this the assertions above would pass
+  // just as well against a schema that emitted both namings.
+  testSync("nothing is named after the field path that reached it", () =>
+    expect(fragmentTypes->Array.some(t => t->String.includes("AddProductPrice")))->toBe(false)
+  )
+
+  // GraphQL forbids one name serving as both an object and an input, so the two
+  // positions differ by suffix — while sharing the enum, which has no such
+  // restriction and would otherwise be emitted twice over.
+  testSync("the output position keeps the bare name", () => {
+    let types = GraphQL_FragmentGenerator.deriveObjectTypeWithNested(
+      ~typeName="Catalog_Product",
+      ~includeIdParam=false,
+      S.schema(s =>
+        {
+          "productId": s.matches(S.string),
+          "price": s.matches(Reventless.Money.schema),
+        }
+      )->S.castToUnknown,
+    )
+    expect((
+      types->countDefs("type", "Money"),
+      types->countDefs("enum", "MoneyCurrency"),
+      types->Array.some(t => t->String.includes("price: Money!")),
+    ))->toEqual((1, 1, true))
+  })
+})

package/tests/api/GraphQL_FragmentGeneratorTest.res.mjs

@@ -2,6 +2,7 @@
 
 import * as S from "sury/src/S.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Money$Reventless from "@reventlessdev/reventless-spec/src/semantic/Money.res.mjs";
 import * as GraphQL_Stitcher$ReventlessCore from "../../src/components/Api/GraphQL_Stitcher.res.mjs";
 import * as GraphQL_FragmentGenerator$ReventlessCore from "../../src/components/Api/GraphQL_FragmentGenerator.res.mjs";
 import * as OutboundTranslationSlice_Callback$ReventlessCore from "../../src/components/OutboundTranslationSlice/OutboundTranslationSlice_Callback.res.mjs";
@@ -83,10 +84,188 @@ globalThis.describe("GraphQL_FragmentGenerator slice TODO rows", () => {
   });
 });
 
+globalThis.describe("resolveKeyField — the ladder", () => {
+  globalThis.test("a lone `*Id` field is the only thing the key could be", () => {
+    let schema = S.schema(s => ({
+      productId: s.m(S.string),
+      name: s.m(S.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("AvailableProducts", schema)).toEqual([
+      "productId",
+      "sole"
+    ]);
+  });
+  globalThis.test("several `*Id` fields are disambiguated by the component name", () => {
+    let schema = S.schema(s => ({
+      productId: s.m(S.string),
+      categoryId: s.m(S.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("Products", schema)).toEqual([
+      "productId",
+      "convention"
+    ]);
+  });
+  globalThis.test("the convention rung singularises the way Api_Naming does", () => {
+    let schema = S.schema(s => ({
+      categoryId: s.m(S.string),
+      ownerId: s.m(S.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("Categories", schema)).toEqual([
+      "categoryId",
+      "convention"
+    ]);
+  });
+  globalThis.test("several `*Id` fields with no name match declines", () => {
+    let schema = S.schema(s => ({
+      productId: s.m(S.string),
+      categoryId: s.m(S.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("ProductDemand", schema)).toEqual(undefined);
+  });
+  globalThis.test("no `*Id` field at all declines", () => {
+    let schema = S.schema(s => ({
+      email: s.m(S.string),
+      address: s.m(S.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("Customers", schema)).toEqual(undefined);
+  });
+  globalThis.test("a word merely ending in `id` is not a key", () => {
+    let schema = S.schema(s => ({
+      paid: s.m(S.string),
+      valid: s.m(S.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("Invoices", schema)).toEqual(undefined);
+  });
+});
+
+globalThis.describe("deriveServerCapability — inferred keys reach the SDL surface", () => {
+  globalThis.test("an inferred key yields an eq filter and a sort field", () => {
+    let schema = S.schema(s => ({
+      orderId: s.m(S.string),
+      total: s.m(S.float)
+    }));
+    let c = GraphQL_FragmentGenerator$ReventlessCore.deriveServerCapability("Orders", schema);
+    globalThis.expect(c.filterFields.map(f => f.name)).toEqual(["orderId"]);
+    globalThis.expect(c.sortFields).toEqual(["orderId"]);
+  });
+  globalThis.test("an unresolvable key still yields nothing — the old behaviour, now narrowed", () => {
+    let schema = S.schema(s => ({
+      email: s.m(S.string)
+    }));
+    let c = GraphQL_FragmentGenerator$ReventlessCore.deriveServerCapability("Customers", schema);
+    globalThis.expect([
+      c.filterFields.length,
+      c.sortFields.length
+    ]).toEqual([
+      0,
+      0
+    ]);
+  });
+  globalThis.test("the filter input carries the inferred key's eq field", () => {
+    let schema = S.schema(s => ({
+      orderId: s.m(S.string)
+    }));
+    let input = GraphQL_FragmentGenerator$ReventlessCore.deriveConnectionFilterType("Ordering_OrderFilter", GraphQL_FragmentGenerator$ReventlessCore.deriveServerCapability("Orders", schema));
+    globalThis.expect(input.includes("orderIdEq: ID")).toBe(true);
+  });
+  globalThis.test("the order-by pair exists because of the inferred key", () => {
+    let schema = S.schema(s => ({
+      orderId: s.m(S.string)
+    }));
+    let types = GraphQL_FragmentGenerator$ReventlessCore.deriveConnectionOrderByType("Ordering_Order", GraphQL_FragmentGenerator$ReventlessCore.deriveServerCapability("Orders", schema));
+    globalThis.expect(types.length).toBe(2);
+    globalThis.expect(types.join("\n").includes("enum Ordering_OrderOrderField")).toBe(true);
+  });
+});
+
+let commandSchema$1 = S.union([
+  S.schema(s => ({
+    TAG: "AddProduct",
+    productId: s.m(S.string),
+    price: s.m(Money$Reventless.schema)
+  })),
+  S.schema(s => ({
+    TAG: "ArchiveProduct",
+    productId: s.m(S.string)
+  }))
+]);
+
+function commandAuthorization$1(param) {
+  return "AllowAuthenticated";
+}
+
+let AddProductCmd = {
+  commandSchema: commandSchema$1,
+  commandAuthorization: commandAuthorization$1
+};
+
+let commandSchema$2 = S.union([
+  S.schema(s => ({
+    TAG: "ChangeProductPrice",
+    productId: s.m(S.string),
+    price: s.m(Money$Reventless.schema)
+  })),
+  S.schema(s => ({
+    TAG: "ClearProductPrice",
+    productId: s.m(S.string)
+  }))
+]);
+
+function commandAuthorization$2(param) {
+  return "AllowAuthenticated";
+}
+
+let ChangePriceCmd = {
+  commandSchema: commandSchema$2,
+  commandAuthorization: commandAuthorization$2
+};
+
+globalThis.describe("semantic composites are named once, not once per field", () => {
+  let countDefs = (types, keyword, name) => types.filter(t => t.startsWith(keyword + ` ` + name + ` {`)).length;
+  let fragmentTypes = GraphQL_Stitcher$ReventlessCore.decode(GraphQL_FragmentGenerator$ReventlessCore.generate([
+    {
+      fieldNames: ["Catalog_AddProduct"],
+      commandSchema: commandSchema$1,
+      injectIdArg: false
+    },
+    {
+      fieldNames: ["Catalog_ChangeProductPrice"],
+      commandSchema: commandSchema$2,
+      injectIdArg: false
+    }
+  ], [])).types;
+  globalThis.test("two commands taking a price share one input definition", () => {
+    globalThis.expect(countDefs(fragmentTypes, "input", "MoneyInput")).toBe(1);
+  });
+  globalThis.test("and one currency enum between them", () => {
+    globalThis.expect(countDefs(fragmentTypes, "enum", "MoneyCurrency")).toBe(1);
+  });
+  globalThis.test("nothing is named after the field path that reached it", () => {
+    globalThis.expect(fragmentTypes.some(t => t.includes("AddProductPrice"))).toBe(false);
+  });
+  globalThis.test("the output position keeps the bare name", () => {
+    let types = GraphQL_FragmentGenerator$ReventlessCore.deriveObjectTypeWithNested("Catalog_Product", undefined, false, S.schema(s => ({
+      productId: s.m(S.string),
+      price: s.m(Money$Reventless.schema)
+    })));
+    globalThis.expect([
+      countDefs(types, "type", "Money"),
+      countDefs(types, "enum", "MoneyCurrency"),
+      types.some(t => t.includes("price: Money!"))
+    ]).toEqual([
+      1,
+      1,
+      true
+    ]);
+  });
+});
+
 export {
   OrderSliceCmd,
   mutationFor,
   GeocodeItem,
   typeDefFor,
+  AddProductCmd,
+  ChangePriceCmd,
 }
 /* commandSchema Not a pure module */

package/tests/plugin/PluginStructureTest.res

@@ -78,6 +78,15 @@ module PsAnnotatedViewSlice: ReventlessInfra.StateViewSlice.T = {
   type component = svsComponent
   let make = (~dcbEventLog as _, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
 }
+module PsCategoriesViewSlice: ReventlessInfra.StateViewSlice.T = {
+  module Spec = PsCategoriesView
+  module Projection = {
+    let project = PsCategoriesView.project
+    let moduleUrl = PsCategoriesView.moduleUrl
+  }
+  type component = svsComponent
+  let make = (~dcbEventLog as _, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
+}
 
 module PsAttachInvoiceSlice: ReventlessInfra.StateChangeSlice.T = {
   module Spec = PsAttachInvoice
@@ -121,6 +130,20 @@ module PsChangePhotoSlice: ReventlessInfra.StateChangeSlice.T = {
   let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
 }
 
+module PsReserveStockSlice: ReventlessInfra.StateChangeSlice.T = {
+  module Spec = PsReserveStock
+  module Behavior = {
+    type state = PsReserveStock.state
+    let initialState = PsReserveStock.initialState
+    let evolve = PsReserveStock.evolve
+    let decide = PsReserveStock.decide
+    let moduleUrl = PsReserveStock.moduleUrl
+  }
+  let isAsync = false
+  type component = scsComponent
+  let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
+}
+
 let structure = Plugin_Structure.make(
   ~name="TestPlugin",
   ~stateChangeSlices=[module(PsPlaceOrderSlice), module(PsShipOrderSlice)],
@@ -546,6 +569,87 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
     })
   })
 
+  // The singular is published because it is not derivable from the plural without
+  // re-implementing `Api_Naming.singularize` — and a consumer that guesses gets an
+  // irregular plural wrong for both the detail query and the filter input type.
+  describe("singleQueryField — the singular the schema actually serves", () => {
+    let withIrregularPlural = Plugin_Structure.make(
+      ~name="TestPlugin",
+      ~stateChangeSlices=[],
+      ~stateViewSlices=[module(PsCategoriesViewSlice)],
+    )
+    let categories = withIrregularPlural.stateViewSlices->Array.getUnsafe(0)
+
+    // "strip a trailing `s`" would publish `TestPlugin_Categorie`, a field the
+    // generated SDL does not contain.
+    testSync("an `-ies` plural publishes the `y` singular, not a truncation", () => {
+      expect((categories.queryField, categories.singleQueryField))->toEqual((
+        "TestPlugin_Categories",
+        Some("TestPlugin_Category"),
+      ))
+    })
+
+    testSync("every built def states the name Api_Naming returned", () => {
+      let stated = structure.stateViewSlices->Array.every(q =>
+        q.singleQueryField ==
+          Some(
+            Api_Naming.queryFieldNamesForStateView(
+              ~plugin="TestPlugin",
+              ~viewName=q.name,
+            ).singleFieldName,
+          )
+      )
+      expect(stated)->toEqual(true)
+    })
+  })
+
+  // Which field identifies a row, and whether the author said so or this side
+  // worked it out — the same declaration-vs-guess distinction `labelFieldSource`
+  // publishes, for the field the generated filter and order-by are built from.
+  describe("idField / idFieldSource — the key and its provenance", () => {
+    let keyOf = (q: Reventless.Plugin.queryableDef) => (q.idField, q.idFieldSource)
+    let withCategories = Plugin_Structure.make(
+      ~name="TestPlugin",
+      ~stateChangeSlices=[],
+      ~stateViewSlices=[module(PsCategoriesViewSlice)],
+    )
+
+    // Orders holds `orderId` + `customerName`; the component name matches the
+    // former, so the rung is the one a client could also reach on its own.
+    testSync("a name-matching `*Id` field is a guess the consumer can also make", () =>
+      expect(keyOf(structure.stateViewSlices->Array.getUnsafe(0)))->toEqual((
+        Some("orderId"),
+        Some("convention"),
+      ))
+    )
+
+    // AvailableProducts: the name would ask for `availableProductId`, which is not
+    // a field — `productId` wins because it is the only candidate there is.
+    testSync("a sole `*Id` field is a fact only this side can see", () =>
+      expect(keyOf(structure.stateViewSlices->Array.getUnsafe(1)))->toEqual((
+        Some("productId"),
+        Some("sole"),
+      ))
+    )
+
+    testSync("an `-ies` component name singularises to its key", () =>
+      expect(keyOf(withCategories.stateViewSlices->Array.getUnsafe(0)))->toEqual((
+        Some("categoryId"),
+        Some("convention"),
+      ))
+    )
+
+    // AnnotatedView declares `@id itemId` beside an `@index` field `ownerId`, and
+    // its name matches neither — inference alone would decline here, so reporting
+    // `itemId` proves the declaration produced it.
+    testSync("a declared @id is used where inference would decline", () =>
+      expect(keyOf(structure.stateViewSlices->Array.getUnsafe(3)))->toEqual((
+        Some("itemId"),
+        Some("annotation"),
+      ))
+    )
+  })
+
   describe("statusField — the shape rule", () => {
     let statusOf = schema =>
       Plugin_Structure.statusFieldFromStateSchema(~entityName="Test", schema->S.castToUnknown)
@@ -960,4 +1064,59 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       )->toEqual([true, true, true, false, false])
     })
   })
+
+  // A plural reference is declared exactly like a singular one, and the ppx puts
+  // the marker where `Reference.to_` returns it: on the element schema, one level
+  // inside the array. Reading the field's own schema therefore answers "no
+  // reference" for every `@ref` array — and the consuming side treats a missing
+  // declaration as licence to guess, so the field resolves to whatever its name
+  // suggests instead of what the author wrote.
+  describe("plural references reach the manifest", () => {
+    let withPluralRefs = Plugin_Structure.make(
+      ~name="TestPlugin",
+      ~stateChangeSlices=[module(PsReserveStockSlice)],
+    )
+    let slice = withPluralRefs.stateChangeSlices->Array.getUnsafe(0)
+    let referencesOf = refs =>
+      refs->Array.map(({Reventless.Plugin.fieldName: f, entity}) => (f, entity))
+
+    // Scalar and plural in one command: the plural forms are the regression, the
+    // scalar one is here so a fix that reaches them by breaking it cannot pass.
+    testSync("a command collects its array refs alongside its scalar one", () => {
+      let cmd = slice.commands->Array.getUnsafe(0)
+      expect(cmd.references->referencesOf)->toEqual([
+        ("customerId", "Customers"),
+        ("productIds", "AvailableProducts"),
+        ("warehouseIds", "Warehouses"),
+      ])
+    })
+
+    // Optionality is a statement about presence. An optional array puts the
+    // element two wrappers down, which is the shape most likely to be missed by
+    // an unwrap that only handles one.
+    testSync("an optional array ref is collected under the field's own name", () => {
+      let cmd = slice.commands->Array.getUnsafe(0)
+      expect(
+        cmd.references->Array.find(({fieldName}) => fieldName == "warehouseIds"),
+      )->toEqual(Some({Reventless.Plugin.fieldName: "warehouseIds", entity: "Warehouses", plugin: None}))
+    })
+
+    // The event walk is a separate function over the same field dicts. Left to
+    // itself it would be fixed by accident or not at all.
+    testSync("an event collects its array ref too", () => {
+      let evt = slice.events->Array.getUnsafe(0)
+      expect(evt.references->referencesOf)->toEqual([("productIds", "AvailableProducts")])
+    })
+
+    // The declared entity, not the one `productIds` reads like. Before the
+    // element unwrap this field resolved by heuristic to `Products`.
+    testSync("the declared entity wins over the one the field name suggests", () => {
+      let cmd = slice.commands->Array.getUnsafe(0)
+      expect(
+        cmd.references
+        ->Array.find(({fieldName}) => fieldName == "productIds")
+        ->Option.map(({entity}) => entity),
+      )->toEqual(Some("AvailableProducts"))
+    })
+  })
 })