@reventlessdev/reventless-core 3.0.0-alpha.237 → 3.0.0-alpha.239

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

@@ -5,6 +5,7 @@ import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Belt_SetString from "@rescript/runtime/lib/es6/Belt_SetString.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Owner$Reventless from "@reventlessdev/reventless-spec/src/components/Owner.res.mjs";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
@@ -101,20 +102,24 @@ function retiredValuesFromStateSchema(stateSchema) {
   return Stdlib_Option.flatMap(retiredFromStateSchema(stateSchema), r => r.values);
 }
 
+function namedWhenRetiredFromStateSchema(stateSchema) {
+  return Stdlib_Option.mapOr(retiredFromStateSchema(stateSchema), false, r => r.namedWhenRetired);
+}
+
 function checkRetiredValue(entityName, stateSchema) {
   let match = retiredFromStateSchema(stateSchema);
   if (match === undefined) {
-    return;
+    return "NotDeclared";
   }
   let values = match.values;
   if (values === undefined) {
-    return;
+    return "NotDeclared";
   }
   let field = match.field;
   let named = values.join(", ");
   let lifecycle = lifecycleFieldFromStateSchema(entityName, stateSchema);
   if (Primitive_object.notequal(lifecycle, field)) {
-    log.warn("Plugin_Structure", undefined, entityName + `: @retired(` + named + `) is on "` + field + `", which is not this record's lifecycle field` + Stdlib_Option.getOr(Stdlib_Option.map(lifecycle, f => ` (that is "` + f + `")`), " (it declares none)") + `. A retirement state no command's @allowedStates can name loses the command filtering the state form exists for.`);
+    log.warn("Plugin_Structure", undefined, entityName + `: @retired(` + named + `) is on "` + field + `", which is not this record's lifecycle field` + Stdlib_Option.getOr(Stdlib_Option.map(lifecycle, f => ` (that is "` + f + `")`), " (it declares none)") + `. A retirement state no command's @transition can name loses the command filtering the state form exists for.`);
   }
   let declared;
   declared = stateSchema.type === "object" ? Stdlib_Option.getOr(Stdlib_Option.map(stateSchema.items.find(item => item.location === field), item => {
@@ -138,12 +143,138 @@ function checkRetiredValue(entityName, stateSchema) {
           return [];
       }
     }), []) : [];
-  if (declared.length !== 0) {
-    values.filter(v => !declared.includes(v)).forEach(v => log.warn("Plugin_Structure", undefined, entityName + `: @retired(` + v + `) names a state "` + field + `" does not declare — known values: ` + declared.join(", ") + `.`));
-    return;
+  if (declared.length === 0) {
+    return {
+      TAG: "Unchecked",
+      _0: entityName + `: @retired(` + named + `) is on "` + field + `", whose shape carries no cases to check the names against.`
+    };
+  } else {
+    return {
+      TAG: "Checked",
+      _0: values.filter(v => !declared.includes(v)).map(v => entityName + `: @retired(` + v + `) names a state "` + field + `" does not declare — known values: ` + declared.join(", ") + `.`)
+    };
+  }
+}
+
+function reportRetiredStates(pluginName, failures, unchecked) {
+  if (unchecked.length !== 0) {
+    log.warn("Plugin_Structure", undefined, pluginName + `: ` + unchecked.length.toString() + ` @retired declaration(s) could not be checked.\n` + unchecked.join("\n"));
+  }
+  if (failures.length !== 0) {
+    return Stdlib_JsError.throwWithMessage(pluginName + `: @retired names states that do not exist.\n` + failures.join("\n"));
   }
 }
 
+function lifecycleStatesFromStateSchema(entityName, stateSchema) {
+  return Stdlib_Option.flatMap(lifecycleFieldFromStateSchema(entityName, stateSchema), field => {
+    if (stateSchema.type === "object") {
+      return Stdlib_Option.map(stateSchema.items.find(item => item.location === field), item => {
+        let match = shapeOfItem(entityName, item);
+        if (typeof match !== "object") {
+          return [];
+        }
+        switch (match.TAG) {
+          case "Nullable" :
+            let match$1 = match._0;
+            if (typeof match$1 !== "object") {
+              return [];
+            } else if (match$1.TAG === "Enum") {
+              return match$1._1;
+            } else {
+              return [];
+            }
+          case "Enum" :
+            return match._1;
+          default:
+            return [];
+        }
+      });
+    }
+  });
+}
+
+function checkDeclaredTransitions(pluginName, writables, lifecycleStatesByView) {
+  let unvalidated = {
+    contents: 0
+  };
+  let failures = [];
+  writables.forEach(w => {
+    w.commands.forEach(cmd => {
+      let t = cmd.targetState;
+      let declared = Stdlib_Option.getOr(cmd.allowedStates, []).concat(t !== undefined ? [t] : []);
+      if (declared.length === 0) {
+        return;
+      }
+      let known = Stdlib_Array.reduce(w.linkedViews, [], (acc, view) => {
+        let states = lifecycleStatesByView[view];
+        if (states !== undefined) {
+          return acc.concat(states);
+        } else {
+          return acc;
+        }
+      });
+      if (known.length === 0) {
+        unvalidated.contents = unvalidated.contents + 1 | 0;
+      } else {
+        declared.filter(state => !known.includes(state)).forEach(state => {
+          failures.push(w.name + `.` + cmd.name + `: @transition names "` + state + `", which none of its ` + (`linked views declare — ` + w.linkedViews.join(", ") + ` know ` + known.join(", ") + `.`));
+        });
+      }
+    });
+  });
+  if (unvalidated.contents > 0) {
+    log.warn("Plugin_Structure", undefined, pluginName + `: ` + unvalidated.contents.toString() + ` command(s) declare a @transition but no linked view declares a lifecycle to check it against.`);
+  }
+  if (failures.length !== 0) {
+    return Stdlib_JsError.throwWithMessage(pluginName + `: @transition names states that do not exist.\n` + failures.join("\n"));
+  }
+}
+
+function lifecycleTopologyFindings(writables, lifecycleStatesByView) {
+  let findings = [];
+  Object.entries(lifecycleStatesByView).forEach(param => {
+    let states = param[1];
+    let view = param[0];
+    let edges = Stdlib_Array.reduce(writables, [], (acc, w) => {
+      if (w.linkedViews.includes(view)) {
+        return acc.concat(Stdlib_Array.reduce(w.commands, [], (inner, cmd) => {
+          let match = cmd.allowedStates;
+          let match$1 = cmd.targetState;
+          if (match !== undefined && match$1 !== undefined) {
+            return inner.concat(match.map(from => [
+              from,
+              match$1
+            ]));
+          } else {
+            return inner;
+          }
+        }));
+      } else {
+        return acc;
+      }
+    });
+    if (edges.length === 0) {
+      return;
+    }
+    let initial = states[0];
+    let reachable = edges.map(param => param[1]);
+    states.forEach(state => {
+      if (!reachable.includes(state) && Primitive_object.notequal(state, initial)) {
+        findings.push([
+          view,
+          `no command declares a transition INTO "` + state + `" — it is unreachable unless something outside this plugin's declarations puts a row there.`
+        ]);
+        return;
+      }
+    });
+  });
+  return findings;
+}
+
+function checkLifecycleTopology(pluginName, writables, lifecycleStatesByView) {
+  lifecycleTopologyFindings(writables, lifecycleStatesByView).forEach(param => log.warn("Plugin_Structure", undefined, pluginName + `/` + param[0] + `: ` + param[1]));
+}
+
 function labelFieldSourceToString(s) {
   switch (s) {
     case "Annotation" :
@@ -587,13 +718,37 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       return "Internal";
     }
   };
+  let lifecycleStatesByView = {};
+  let recordLifecycle = (entityName, stateSchema) => {
+    let states = lifecycleStatesFromStateSchema(entityName, stateSchema);
+    if (states !== undefined && states.length !== 0) {
+      lifecycleStatesByView[entityName] = states;
+      return;
+    }
+  };
+  let retiredFailures = [];
+  let retiredUnchecked = [];
+  let recordRetired = (entityName, stateSchema) => {
+    let why = checkRetiredValue(entityName, stateSchema);
+    if (typeof why !== "object") {
+      return;
+    }
+    if (why.TAG === "Unchecked") {
+      retiredUnchecked.push(why._0);
+      return;
+    }
+    why._0.forEach(f => {
+      retiredFailures.push(f);
+    });
+  };
   let readModelDefs = readModels.map(R => {
     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);
-    checkRetiredValue(R.Spec.name, stateSchema);
+    recordRetired(R.Spec.name, stateSchema);
+    recordLifecycle(R.Spec.name, stateSchema);
     return {
       name: R.Spec.name,
       queryField: qf.listFieldName,
@@ -607,6 +762,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       ownerField: Owner$Reventless.fieldNames(stateSchema)[0],
       retiredField: retiredFieldFromStateSchema(stateSchema),
       retiredValues: retiredValuesFromStateSchema(stateSchema),
+      namedWhenRetired: namedWhenRetiredFromStateSchema(stateSchema),
       visibility: visibilityTag(R.Spec.visibility),
       chapter: componentChapters[R.Spec.name],
       singleQueryField: qf.singleFieldName,
@@ -622,7 +778,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let stateSchema = SVS.Spec.stateSchema;
     let label = labelFieldsFromStateSchema(SVS.Spec.name, stateSchema);
     let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField(SVS.Spec.name, stateSchema);
-    checkRetiredValue(SVS.Spec.name, stateSchema);
+    recordRetired(SVS.Spec.name, stateSchema);
+    recordLifecycle(SVS.Spec.name, stateSchema);
     return {
       name: SVS.Spec.name,
       queryField: qf.listFieldName,
@@ -636,6 +793,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       ownerField: Owner$Reventless.fieldNames(stateSchema)[0],
       retiredField: retiredFieldFromStateSchema(stateSchema),
       retiredValues: retiredValuesFromStateSchema(stateSchema),
+      namedWhenRetired: namedWhenRetiredFromStateSchema(stateSchema),
       visibility: visibilityTag(SVS.Spec.visibility),
       chapter: componentChapters[SVS.Spec.name],
       singleQueryField: qf.singleFieldName,
@@ -735,6 +893,9 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       commandTypes: Belt_SetString.toArray(Belt_SetString.fromArray(match[2]))
     };
   });
+  checkDeclaredTransitions(name, stateChangeDefs.concat(aggregateDefs), lifecycleStatesByView);
+  checkLifecycleTopology(name, stateChangeDefs.concat(aggregateDefs), lifecycleStatesByView);
+  reportRetiredStates(name, retiredFailures, retiredUnchecked);
   return {
     readModels: readModelDefs,
     stateViewSlices: stateViewDefs,
@@ -760,7 +921,13 @@ export {
   retiredFromStateSchema,
   retiredFieldFromStateSchema,
   retiredValuesFromStateSchema,
+  namedWhenRetiredFromStateSchema,
   checkRetiredValue,
+  reportRetiredStates,
+  lifecycleStatesFromStateSchema,
+  checkDeclaredTransitions,
+  lifecycleTopologyFindings,
+  checkLifecycleTopology,
   labelFieldSourceToString,
   labelFieldsFromStateSchema,
   extractReferences,

package/src/plugin/connect/PluginExtensionPoint_UiFragment.res

@@ -1,5 +1,5 @@
 // Second mapping on the admin PluginExtensionPoint, routing UI-fragment lifecycle to the
-// admin UiFragmentRegistry StateChangeSlice (docs/plans/event-sourced-fragment-registries.md).
+// admin UiFragmentRegistry StateChangeSlice (docs/plans/done/event-sourced-fragment-registries.md).
 //
 // The EP runtime fans every incoming command through ALL mappings and flattens the results
 // (ExtensionPoint_Callback.mapIncomingCommands). This mapping's Delegate is the slice, so its

package/tests/admin/Platform_BakedManifestTest.res

@@ -25,6 +25,7 @@ let queryable = (~name, ~visibility=?, ~ownerField=?, ()): queryableDef => {
   ownerField,
   retiredField: None,
   retiredValues: None,
+  namedWhenRetired: None,
 }
 
 let command = (~name, ~references=[], ~ownerField=?, ()): commandDef => {

package/tests/admin/Platform_BakedManifestTest.res.mjs

@@ -22,6 +22,7 @@ function queryable(name, visibility, ownerField, param) {
     ownerField: ownerField,
     retiredField: undefined,
     retiredValues: undefined,
+    namedWhenRetired: undefined,
     visibility: visibility,
     chapter: undefined,
     singleQueryField: `Ordering_` + name + `Single`,

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -40,6 +40,7 @@ let qbl: queryableDef = {
   ownerField: None,
   retiredField: None,
   retiredValues: None,
+  namedWhenRetired: None,
 }
 
 let wbl: writableDef = {
@@ -268,6 +269,7 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
       ownerField: None,
       retiredField: None,
       retiredValues: None,
+      namedWhenRetired: 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`.
@@ -367,6 +369,7 @@ describe("allowedStates + lifecycleField populated", () => {
       ownerField: None,
       retiredField: None,
       retiredValues: None,
+      namedWhenRetired: None,
   }
 
   let wblWithStates: writableDef = {

package/tests/admin/Platform_ComponentDefinitionsApiTest.res.mjs

@@ -55,6 +55,7 @@ let qbl = {
   ownerField: undefined,
   retiredField: undefined,
   retiredValues: undefined,
+  namedWhenRetired: undefined,
   visibility: undefined,
   chapter: undefined,
   singleQueryField: qbl_singleQueryField,
@@ -288,6 +289,7 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     ownerField: undefined,
     retiredField: undefined,
     retiredValues: undefined,
+    namedWhenRetired: undefined,
     visibility: internalQbl_visibility,
     chapter: undefined,
     singleQueryField: internalQbl_singleQueryField,
@@ -316,6 +318,7 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     ownerField: undefined,
     retiredField: undefined,
     retiredValues: undefined,
+    namedWhenRetired: undefined,
     visibility: internalSlice_visibility,
     chapter: undefined,
     singleQueryField: internalSlice_singleQueryField,
@@ -422,6 +425,7 @@ globalThis.describe("allowedStates + lifecycleField populated", () => {
     ownerField: undefined,
     retiredField: undefined,
     retiredValues: undefined,
+    namedWhenRetired: undefined,
     visibility: undefined,
     chapter: undefined,
     singleQueryField: qblWithStatus_singleQueryField,
@@ -503,6 +507,7 @@ globalThis.describe("singleQueryField reaches the caller", () => {
           ownerField: undefined,
           retiredField: undefined,
           retiredValues: undefined,
+          namedWhenRetired: undefined,
           visibility: undefined,
           chapter: undefined,
           singleQueryField: undefined,
@@ -550,6 +555,7 @@ globalThis.describe("idField / idFieldSource reach the caller", () => {
           ownerField: undefined,
           retiredField: undefined,
           retiredValues: undefined,
+          namedWhenRetired: undefined,
           visibility: undefined,
           chapter: undefined,
           singleQueryField: "Catalog_Product",

package/tests/admin/Platform_PluginStructuresApiTest.res

@@ -26,6 +26,7 @@ let publicRm: queryableDef = {
   ownerField: None,
   retiredField: None,
   retiredValues: None,
+  namedWhenRetired: None,
 }
 
 // The component `Platform_ComponentDefinitions` drops and this query must keep.

package/tests/admin/Platform_PluginStructuresApiTest.res.mjs

@@ -35,6 +35,7 @@ let publicRm = {
   ownerField: undefined,
   retiredField: undefined,
   retiredValues: undefined,
+  namedWhenRetired: undefined,
   visibility: undefined,
   chapter: publicRm_chapter,
   singleQueryField: publicRm_singleQueryField,
@@ -74,6 +75,7 @@ let internalRm = {
   ownerField: undefined,
   retiredField: undefined,
   retiredValues: undefined,
+  namedWhenRetired: undefined,
   visibility: internalRm_visibility,
   chapter: internalRm_chapter,
   singleQueryField: internalRm_singleQueryField,

package/tests/aggregate/AggregateCacheTest.res

@@ -1,5 +1,5 @@
 // Tests for the Aggregate_Callback in-process replay cache (Phase 1 of
-// docs/plans/aggregate-snapshotting.md): a warm same-id command skips the
+// docs/plans/done/aggregate-snapshotting.md): a warm same-id command skips the
 // event-log replay and decides on the cached (state, sequenceNr); the OCC
 // append fences staleness — a stale cache conflicts, invalidates, and the
 // retry replays cold.

package/tests/aggregate/AggregateSnapshotTest.res

@@ -1,4 +1,4 @@
-// Step 5 of docs/plans/aggregate-snapshotting.md — the Aggregate_Callback
+// Step 5 of docs/plans/done/aggregate-snapshotting.md — the Aggregate_Callback
 // snapshot wiring: a snapshot-enabled behavior seeds cold replays from the
 // latest persisted snapshot (hash-gated) and writes a fresh one every
 // `interval` events, fire-and-forget. Snapshots never affect correctness — the

package/tests/api/GraphQL_FragmentGeneratorTest.res

@@ -340,3 +340,174 @@ describe("GraphQL_FragmentGenerator.mutationArgTypes", () => {
     expect((mismatched, field->String.length > 0))->toEqual(([], true))
   })
 })
+
+module RefDoorRow = {
+  @schema
+  type state = {id: string, name: string}
+}
+
+let queryFor = (fragment, needle) =>
+  GraphQL_Stitcher.decode(fragment).queries->Array.find(q => q->String.includes(needle))
+
+let refDoorFragment = (~subIdField=?) =>
+  GraphQL_FragmentGenerator.generate(
+    ~mutationEntries=[],
+    ~queryEntries=[
+      {
+        ReventlessInfra.Api.singleFieldName: "Catalog_Product",
+        listFieldName: "Catalog_Products",
+        returnTypeName: "Catalog_Product",
+        stateSchema: RefDoorRow.stateSchema->S.castToUnknown,
+        authorization: None,
+        connectionSpec: true,
+        subIdField: ?subIdField,
+      },
+    ],
+  )
+
+// What a caller holding a pointer to a withheld row may learn about it, and what
+// the two doors that could never answer for one can now be asked.
+describe("the reference door and the archive argument", () => {
+  open Expect
+
+  // The narrowness is the type's, not a rule each backend re-implements: a caller
+  // cannot ask this door for a price, because there is no price on it.
+  testSync("projects a reference to id, label and the state that retired it", () => {
+    let sdl = GraphQL_FragmentGenerator.deriveRefTypeSdl(~returnTypeName="Catalog_Product")
+    expect((
+      sdl->String.includes("type Catalog_ProductRef"),
+      sdl->String.includes("label: String!"),
+      sdl->String.includes("retiredState: String"),
+      sdl->String.includes("price"),
+    ))->toEqual((true, true, true, false))
+  })
+
+  // Emitted for every view rather than only the annotated ones, on the reasoning
+  // `includeRetired` already states: a field that appears with an annotation makes
+  // adding or removing it a breaking schema change.
+  testSync("names the door after the list field it resolves against", () =>
+    expect(
+      GraphQL_FragmentGenerator.deriveRefsQueryField(
+        ~listFieldName="Catalog_Products",
+        ~returnTypeName="Catalog_Product",
+      ),
+    )->toEqual("  Catalog_ProductsRefs(ids: [ID!]!): [Catalog_ProductRef!]!")
+  )
+
+  // Every assertion above reads a `derive*` helper directly, which is how a door
+  // that no `generate` call emitted still passed them all: the SDL both AppSync
+  // APIs are built from comes from `generate`, while the adapter provisions a
+  // `<list>Refs` resolver per queryable on the premise that it is declared there.
+  // AppSync rejects a resolver for a field its schema does not have, so the
+  // mismatch surfaced as a failed deploy rather than a missing feature.
+  testSync("emits the door from generate, not only from the helper", () =>
+    expect((
+      queryFor(refDoorFragment(), "Catalog_ProductsRefs(ids: [ID!]!)")->Option.isSome,
+      typeDefFor(refDoorFragment(), "type Catalog_ProductRef")->Option.isSome,
+    ))->toEqual((true, true))
+  )
+
+  // The condition the resolver side uses, mirrored: a composite-key view gets no
+  // door, because the read behind it is a BatchGetItem that would need both keys.
+  // Emitting the field for one would restore the same mismatch, reversed.
+  testSync("withholds the door from a composite-key view", () =>
+    expect((
+      queryFor(refDoorFragment(~subIdField="lineNo"), "Catalog_ProductsRefs")->Option.isSome,
+      typeDefFor(refDoorFragment(~subIdField="lineNo"), "type Catalog_ProductRef")->Option.isSome,
+    ))->toEqual((false, false))
+  )
+
+  // The dead end this closes: the archive toggle put retired rows on screen and
+  // clicking one read a door that refused them to every caller alive, elevated
+  // included, because there was no way to ask.
+  testSync("lets the single-entity and by-ids doors be asked for the archive", () =>
+    expect((
+      GraphQL_FragmentGenerator.deriveObjectQueryField(
+        ~singleFieldName="Catalog_Product",
+        ~typeName="Catalog_Product",
+      )->String.includes("includeRetired: Boolean"),
+      GraphQL_FragmentGenerator.deriveByIdsQueryField(
+        ~listFieldName="Catalog_Products",
+        ~returnTypeName="Catalog_Product",
+      )->String.includes("includeRetired: Boolean"),
+    ))->toEqual((true, true))
+  )
+
+  // A sub-id read keeps its sort-key argument beside the new one; dropping it
+  // would silently turn a two-key door into a one-key one.
+  testSync("keeps the sub-id argument when the view has one", () =>
+    expect(
+      GraphQL_FragmentGenerator.deriveObjectQueryField(
+        ~singleFieldName="Ordering_OrderLine",
+        ~typeName="Ordering_OrderLine",
+        ~subIdField="lineNo",
+      ),
+    )->toEqual("  Ordering_OrderLine(id: ID!, lineNo: String!, includeRetired: Boolean): Ordering_OrderLine")
+  )
+})
+
+// The by-index door is asserted whole rather than by `String.includes`, because
+// what was wrong with it was never a missing substring: the field declared an
+// `id` its resolver did not read and omitted the key its resolver did, so every
+// part of the signature is load-bearing.
+describe("the by-index door", () => {
+  let index = (~index, ~idField=?, ~subIdField=?): Reventless.ReadModel.indexConfig => {
+    index,
+    type_: "S",
+    idField: ?idField,
+    subIdField: ?subIdField,
+    projectionType: ALL,
+  }
+
+  testSync("takes the index value it filters on, and can be asked for the archive", () =>
+    expect(
+      GraphQL_FragmentGenerator.deriveIndexQueryField(
+        ~singleFieldName="Catalog_Product",
+        ~indexConfig=index(~index="categoryId"),
+        ~connectionTypeName="Catalog_ProductConnection",
+      ),
+    )->toEqual(
+      "  Catalog_ProductByCategoryId(categoryId: String!, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): Catalog_ProductConnection!",
+    )
+  )
+
+  // A named index has two different strings in play — `byOwner` names the index,
+  // `ownerId` names the column. The field is named after the first and keyed on
+  // the second, and swapping them is how the local adapter came to offer an
+  // argument the row had no field for.
+  testSync("names the field after the index and keys it on the column", () =>
+    expect(
+      GraphQL_FragmentGenerator.deriveIndexQueryField(
+        ~singleFieldName="Ordering_Order",
+        ~indexConfig=index(~index="byOwner", ~idField="ownerId"),
+        ~connectionTypeName="Ordering_OrderConnection",
+      ),
+    )->toEqual(
+      "  Ordering_OrderByOwner(ownerId: String!, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): Ordering_OrderConnection!",
+    )
+  )
+
+  // Optional, unlike the partition argument: naming the index value is the point
+  // of the door, narrowing to one sort value is a refinement.
+  testSync("offers the sort key the sort template has always read", () =>
+    expect(
+      GraphQL_FragmentGenerator.deriveIndexQueryField(
+        ~singleFieldName="Ordering_Order",
+        ~indexConfig=index(~index="byCustomer", ~idField="customerId", ~subIdField="placedAt"),
+        ~connectionTypeName="Ordering_OrderConnection",
+      ),
+    )->toEqual(
+      "  Ordering_OrderByCustomer(customerId: String!, placedAt: String, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): Ordering_OrderConnection!",
+    )
+  )
+
+  // One derivation, called by every backend. The local adapter used to spell the
+  // name out itself and produced `XByByOwner` where this produces `XByOwner`.
+  testSync("drops a leading `by` exactly once", () =>
+    expect((
+      GraphQL_FragmentGenerator.indexQueryFieldName(~singleFieldName="X", ~index="byOwner"),
+      GraphQL_FragmentGenerator.indexQueryFieldName(~singleFieldName="X", ~index="ownerId"),
+      GraphQL_FragmentGenerator.indexQueryFieldName(~singleFieldName="X", ~index="by"),
+    ))->toEqual(("XByOwner", "XByOwnerId", "XByBy"))
+  )
+})