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

package/src/plugin/component/Plugin_Structure.res

@@ -108,17 +108,55 @@ let retiredFieldFromStateSchema = (stateSchema: S.t<unknown>): option<string> =>
 let retiredValuesFromStateSchema = (stateSchema: S.t<unknown>): option<array<string>> =>
   retiredFromStateSchema(stateSchema)->Option.flatMap(r => r.values)
 
+// Whether a reference to a retired row of this view still resolves its name —
+// `@namedWhenRetired`. Read off the retirement rather than from a second
+// annotation, so a record cannot declare the reach of a retirement it does not
+// have; the PPX refuses that pairing, and reading it here from the same place
+// keeps the two halves agreeing by construction rather than by review.
+let namedWhenRetiredFromStateSchema = (stateSchema: S.t<unknown>): bool =>
+  retiredFromStateSchema(stateSchema)->Option.mapOr(false, r => r.namedWhenRetired)
+
+// What one record's `@retired` declaration could be told about its own field.
+//
+// Three outcomes rather than a bool, because "nothing to check" and "could not
+// check" are different facts and only the second is worth a plugin's attention.
+type retiredCheck =
+  | NotDeclared
+  // Why the names could not be compared. A fatal rule that is invisible when it
+  // does not run is the failure mode the transition check spends a counter to
+  // avoid, so this is reported rather than skipped in silence.
+  | Unchecked(string)
+  | Checked(array<string>)
+
 // The check the PPX cannot make, in the one place that can: the payload is a
 // constructor reference the PPX only ever sees as a name, and whether that name
 // is a case of the field's enum needs the schema.
 //
-// Two rules, and the second is the one the form exists for. A `value` on a field
-// that is not the record's lifecycle would keep the read narrowing while silently
-// losing the command filtering that motivates it — `@transition` is written in
-// terms of the lifecycle field, so a retirement state anywhere else is a state no
-// command can name.
-let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =>
+// Two rules, and they are held to different standards on purpose.
+//
+// **A name the field's enum does not declare is unambiguously wrong** — no domain
+// means it — and the symptom is a data-exposure bug: the retirement predicate
+// compares every row against a state no row is ever in, so every row stays
+// visible to every caller while the annotation sits on the schema looking like
+// enforcement. That is returned as a failure for the caller to raise on.
+//
+// It is the same fault the PPX already refuses to compile when the enum is
+// declared in the same file, and the PPX says so in its own message. This is the
+// residue that a per-file pass cannot reach: field form, enum imported from
+// elsewhere. Two rungs of one ladder — until this was promoted, which rung you
+// landed on decided whether a data-exposure bug stopped the build, and the
+// arbiter was where the enum happened to be declared.
+//
+// **A `value` on a field that is not the record's lifecycle stays a warning.**
+// It would keep the read narrowing while silently losing the command filtering
+// that motivates it — `@transition` is written in terms of the lifecycle field,
+// so a retirement state anywhere else is a state no command can name. That is a
+// modelling judgement rather than a wrong name, and judgement calls are what the
+// withdrawn dead-end rule taught us not to hard-fail on.
+let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): retiredCheck =>
   switch retiredFromStateSchema(stateSchema) {
+  // The boolean form names no state, so there is nothing to compare. Not a skip.
+  | None | Some({values: None}) => NotDeclared
   | Some({field, values: Some(values)}) =>
     let named = values->Array.join(", ")
     let lifecycle = lifecycleFieldFromStateSchema(~entityName, stateSchema)
@@ -146,24 +184,56 @@ let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =
       ->Option.getOr([])
     | _ => []
     }
-    // Reported per state rather than as a set: one wrong entry among three still
-    // narrows something, so the symptom is a subset of rows leaking rather than
-    // all of them — which is harder to spot than the single-value case was.
-    if Array.length(declared) > 0 {
-      values
-      ->Array.filter(v => !(declared->Array.includes(v)))
-      ->Array.forEach(v =>
-        log.warn(
-          ~comp="Plugin_Structure",
-          `${entityName}: @retired(${v}) names a state "${field}" does not declare — known values: ${declared->Array.join(
-              ", ",
-            )}.`,
-        )
+    if Array.length(declared) == 0 {
+      Unchecked(
+        `${entityName}: @retired(${named}) is on "${field}", whose shape carries no cases to check the names against.`,
+      )
+    } else {
+      // Reported per state rather than as a set: one wrong entry among three still
+      // narrows something, so the symptom is a subset of rows leaking rather than
+      // all of them — which is harder to spot than the single-value case was.
+      Checked(
+        values
+        ->Array.filter(v => !(declared->Array.includes(v)))
+        ->Array.map(
+          v =>
+            `${entityName}: @retired(${v}) names a state "${field}" does not declare — known values: ${declared->Array.join(
+                ", ",
+              )}.`,
+        ),
       )
     }
-  | _ => ()
   }
 
+// Raised together, after every view has been walked, so an author sees every bad
+// name at once rather than the first one and then a rebuild.
+//
+// Retroactive in a way the transition check was not: `@transition` was new when
+// its check landed, so nothing deployed could carry a stale name, while `@retired`
+// has been shipping. A deployed plugin holding a misspelled retired value gets a
+// red build on its next deploy — which is the point, and is why the examples were
+// swept before this was promoted.
+let reportRetiredStates = (
+  ~pluginName: string,
+  ~failures: array<string>,
+  ~unchecked: array<string>,
+): unit => {
+  if Array.length(unchecked) > 0 {
+    log.warn(
+      ~comp="Plugin_Structure",
+      `${pluginName}: ${unchecked
+        ->Array.length
+        ->Int.toString} @retired declaration(s) could not be checked.\n` ++
+      unchecked->Array.join("\n"),
+    )
+  }
+  if Array.length(failures) > 0 {
+    JsError.throwWithMessage(
+      `${pluginName}: @retired names states that do not exist.\n` ++ failures->Array.join("\n"),
+    )
+  }
+}
+
 // The states a record's lifecycle field can hold. The same extraction
 // `checkRetiredValue` does, keyed on the declared lifecycle field rather than the
 // retired one — which is the field a command's `@transition` is written in terms
@@ -1071,6 +1141,17 @@ let make = (
     }
   }
 
+  // Collected as the view defs are built and reported once, so a plugin with
+  // three bad names fails naming three rather than one at a time.
+  let retiredFailures = []
+  let retiredUnchecked = []
+  let recordRetired = (~entityName, stateSchema) =>
+    switch checkRetiredValue(~entityName, stateSchema) {
+    | NotDeclared => ()
+    | Unchecked(why) => retiredUnchecked->Array.push(why)->ignore
+    | Checked(failures) => failures->Array.forEach(f => retiredFailures->Array.push(f)->ignore)
+    }
+
   let readModelDefs =
     readModels
     ->Array.map((
@@ -1090,7 +1171,7 @@ let make = (
       // edges for any event reaching the read model via a DCB-log-sourced mapping (a classic
       // aggregate→view link is also drawn from the producer's linkedViews, deduped downstream).
       let consumed = qualify(~prefix=name, R.consumedEventNames)
-      checkRetiredValue(~entityName=R.Spec.name, stateSchema)
+      recordRetired(~entityName=R.Spec.name, stateSchema)
       recordLifecycle(~entityName=R.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: R.Spec.name,
@@ -1107,6 +1188,7 @@ let make = (
         ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
         retiredField: retiredFieldFromStateSchema(stateSchema),
         retiredValues: retiredValuesFromStateSchema(stateSchema),
+        namedWhenRetired: Some(namedWhenRetiredFromStateSchema(stateSchema)),
         visibility: visibilityTag(R.Spec.visibility),
         chapter: chapterOf(R.Spec.name),
         // Taken from the `qf` record, never re-derived: `Api_Naming` is the only
@@ -1129,7 +1211,7 @@ let make = (
         ~entityName=SVS.Spec.name,
         stateSchema,
       )
-      checkRetiredValue(~entityName=SVS.Spec.name, stateSchema)
+      recordRetired(~entityName=SVS.Spec.name, stateSchema)
       recordLifecycle(~entityName=SVS.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: SVS.Spec.name,
@@ -1144,6 +1226,7 @@ let make = (
         ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
         retiredField: retiredFieldFromStateSchema(stateSchema),
         retiredValues: retiredValuesFromStateSchema(stateSchema),
+        namedWhenRetired: Some(namedWhenRetiredFromStateSchema(stateSchema)),
         visibility: visibilityTag(SVS.Spec.visibility),
         chapter: chapterOf(SVS.Spec.name),
         singleQueryField: Some(qf.singleFieldName),
@@ -1313,6 +1396,10 @@ let make = (
     ~writables=Array.concat(stateChangeDefs, aggregateDefs),
     ~lifecycleStatesByView,
   )
+  // Also a second pass, for a different reason: the failures are gathered per
+  // view as those defs are built, and raising inline would report the first bad
+  // name and hide the rest.
+  reportRetiredStates(~pluginName=name, ~failures=retiredFailures, ~unchecked=retiredUnchecked)
 
   {
     readModels: readModelDefs,

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

@@ -102,14 +102,18 @@ 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(", ");
@@ -139,9 +143,25 @@ 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"));
   }
 }
 
@@ -706,13 +726,28 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       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,
@@ -727,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,
@@ -742,7 +778,7 @@ 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,
@@ -757,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,
@@ -858,6 +895,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
   });
   checkDeclaredTransitions(name, stateChangeDefs.concat(aggregateDefs), lifecycleStatesByView);
   checkLifecycleTopology(name, stateChangeDefs.concat(aggregateDefs), lifecycleStatesByView);
+  reportRetiredStates(name, retiredFailures, retiredUnchecked);
   return {
     readModels: readModelDefs,
     stateViewSlices: stateViewDefs,
@@ -883,7 +921,9 @@ export {
   retiredFromStateSchema,
   retiredFieldFromStateSchema,
   retiredValuesFromStateSchema,
+  namedWhenRetiredFromStateSchema,
   checkRetiredValue,
+  reportRetiredStates,
   lifecycleStatesFromStateSchema,
   checkDeclaredTransitions,
   lifecycleTopologyFindings,

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/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"))
+  )
+})