@reventlessdev/reventless-core 3.0.0-alpha.265 → 3.0.0-alpha.267

package/src/plugin/component/Plugin_Structure.res

@@ -587,31 +587,92 @@ let labelFieldsFromStateSchema = (
 // Mirrors the command walk for emitted events. Module-level so Platform_Admin,
 // whose components never pass through `make`, derives its defs the same way.
 
+/**
+The plugin's views by the identity each is keyed by, which is what lets a typed
+id find the view that lists it without an `@ref`. `report` says where the type
+cannot decide: several views keyed by the identity, none, or an `@ref` naming a
+view keyed by another.
+*/
+type identityViews = {
+  viewsByKey: dict<array<string>>,
+  viewNames: array<string>,
+  report: string => unit,
+}
+
+// The reference a typed id implies, and the check on one it declares.
+let identityReference = (
+  identityViews: identityViews,
+  ~fieldName,
+  fieldSchema: S.t<unknown>,
+  declared: array<(string, Reventless.Reference.target)>,
+): array<(string, Reventless.Reference.target)> =>
+  switch Reventless.Semantic.fieldIdentityKey(fieldSchema) {
+  | None => declared
+  | Some(key) =>
+    let keyed = identityViews.viewsByKey->Dict.get(key)->Option.getOr([])
+    switch declared {
+    | [] =>
+      switch keyed {
+      | [view] => [(fieldName, {Reventless.Semantic.entity: view, plugin: None, identity: key})]
+      | [] =>
+        identityViews.report(
+          `${fieldName} is a ${key}, and no view in this plugin is keyed by it, so it references nothing. List the identity in a view, or reference another plugin's with @ref("Plugin.View").`,
+        )
+        []
+      | several =>
+        identityViews.report(
+          `${fieldName} is a ${key}, and ${several->Array.join(
+              " and ",
+            )} are all keyed by it. Say which it references with @ref.`,
+        )
+        []
+      }
+    | _ =>
+      declared->Array.forEach(((_, target)) =>
+        if (
+          target.plugin->Option.isNone &&
+          identityViews.viewNames->Array.includes(target.entity) &&
+          !(keyed->Array.includes(target.entity))
+        ) {
+          identityViews.report(
+            `${fieldName} is a ${key}, and its @ref names ${target.entity}, which is not keyed by it.`,
+          )
+        }
+      )
+      declared
+    }
+  }
+
 // A variant's cross-entity references, shared by the command and event walks.
 // `getFieldTarget`, not `getTarget`: an `array<string>` field declares it on the
 // element schema.
-let extractReferences = (properties: dict<S.t<unknown>>): array<Reventless.Plugin.fieldReference> =>
+let extractReferences = (
+  ~identityViews: option<identityViews>=?,
+  properties: dict<S.t<unknown>>,
+): array<Reventless.Plugin.fieldReference> =>
   properties
   ->Dict.toArray
-  ->Array.flatMap(((fieldName, fieldSchema)) =>
+  ->Array.flatMap(((fieldName, fieldSchema)) => {
     // `collectFieldTargets`, not `getFieldTarget`: a reference declared on a field
     // of a record the field holds (an order line's `productId`) is one this
     // command declares, and it arrives named by its own path. Commands and events
     // both come through here, which is what stops one of them learning about
     // nesting and the other not.
-    Reventless.Reference.collectFieldTargets(fieldName, fieldSchema)->Array.map(((
-      path,
-      target,
-    )): Reventless.Plugin.fieldReference => {
+    let declared = Reventless.Reference.collectFieldTargets(fieldName, fieldSchema)
+    let targets = switch identityViews {
+    | Some(views) => identityReference(views, ~fieldName, fieldSchema, declared)
+    | None => declared
+    }
+    targets->Array.map(((path, target)): Reventless.Plugin.fieldReference => {
       Reventless.Plugin.fieldName: path,
       entity: target.entity,
       plugin: target.plugin,
     })
-  )
+  })
 
-let toEventDef = (v: S.t<unknown>): option<Reventless.Plugin.eventDef> => {
+let toEventDef = (~identityViews=?, v: S.t<unknown>): option<Reventless.Plugin.eventDef> => {
   let mkDef = (~variantName, ~properties) => {
-    let references = extractReferences(properties)
+    let references = extractReferences(~identityViews?, properties)
 
     (
       {
@@ -640,10 +701,12 @@ let toEventDef = (v: S.t<unknown>): option<Reventless.Plugin.eventDef> => {
   }
 }
 
-let extractEventDefs = (eventSchema: S.t<unknown>): array<Reventless.Plugin.eventDef> =>
+let extractEventDefs = (~identityViews=?, eventSchema: S.t<unknown>): array<
+  Reventless.Plugin.eventDef,
+> =>
   switch eventSchema {
-  | AnyOf({anyOf}) => anyOf->Array.filterMap(toEventDef)
-  | _ => toEventDef(eventSchema)->Option.mapOr([], def => [def])
+  | AnyOf({anyOf}) => anyOf->Array.filterMap(v => toEventDef(~identityViews?, v))
+  | _ => toEventDef(~identityViews?, eventSchema)->Option.mapOr([], def => [def])
   }
 
 // Errors walk identically to events; only the def type differs, so a consumer
@@ -750,6 +813,7 @@ let annotateArgTypes = (schema: JSON.t, argTypes: dict<string>): JSON.t => {
 }
 
 let toCommandDef = (
+  ~identityViews: option<identityViews>=?,
   ~isAggregate,
   ~partitionKey: option<string>=?,
   ~mutationFieldFor: string => string,
@@ -785,7 +849,7 @@ let toCommandDef = (
       ~variantName,
       properties,
     )
-    let references = extractReferences(properties)
+    let references = extractReferences(~identityViews?, properties)
     // Evaluated against a synthetic value per constructor, the same shape the
     // resolver builds at call time: a payload-bearing variant compiles to
     // `{TAG, ...}`, a payload-less one to a bare string.
@@ -923,6 +987,7 @@ let toCommandDef = (
 }
 
 let extractCommandDefs = (
+  ~identityViews: option<identityViews>=?,
   ~isAggregate,
   ~partitionKey: option<string>=?,
   ~mutationFieldFor: string => string,
@@ -935,6 +1000,7 @@ let extractCommandDefs = (
   | AnyOf({anyOf}) =>
     anyOf->Array.filterMap(v =>
       toCommandDef(
+        ~identityViews?,
         ~isAggregate,
         ~partitionKey?,
         ~mutationFieldFor,
@@ -948,6 +1014,7 @@ let extractCommandDefs = (
   | _ =>
     // Single-variant command types compile to a bare Object schema, not a Union.
     toCommandDef(
+      ~identityViews?,
       ~isAggregate,
       ~partitionKey?,
       ~mutationFieldFor,
@@ -986,9 +1053,12 @@ let queryableDefFromSpec = (
 ): Reventless.Plugin.queryableDef => {
   let qf = Api_Naming.queryFieldNamesForReadModel(~plugin, ~name)
   let label = labelFieldsFromStateSchema(~entityName=name, stateSchema)
-  // The same call the capability deriver makes, so the published key and the key
-  // the generated filter/order-by is built from cannot disagree.
-  let keyField = GraphQL_FragmentGenerator.resolveKeyField(~entityName=name, stateSchema)
+  // The published key is always filterable; not every filterable field is the key.
+  let keyField = GraphQL_FragmentGenerator.resolveKeyField(
+    ~rowKeying=RowKeyedByEnvelope,
+    ~entityName=name,
+    stateSchema,
+  )
   {
     Reventless.Plugin.name,
     queryField: qf.listFieldName,
@@ -1414,8 +1484,8 @@ let make = (
 
   // Warned rather than refused: an unkeyed view still answers, just without a
   // filter or an ordering, and a lint that stops a deploy gets silenced.
-  let recordKeyField = (~entityName, stateSchema) =>
-    GraphQL_FragmentGenerator.classifyKeyField(~entityName, stateSchema)
+  let recordKeyField = (~rowKeying, ~entityName, stateSchema) =>
+    GraphQL_FragmentGenerator.classifyKeyField(~rowKeying, ~entityName, stateSchema)
     ->GraphQL_FragmentGenerator.keyFieldGapMessage
     ->Option.forEach(why => log.warn(~comp="Plugin_Structure", `${name}/${entityName} ${why}`))
 
@@ -1425,14 +1495,17 @@ let make = (
     let qf = Api_Naming.queryFieldNamesForReadModel(~plugin=name, ~name=R.Spec.name)
     let stateSchema = R.Spec.stateSchema->S.castToUnknown
     let label = labelFieldsFromStateSchema(~entityName=R.Spec.name, stateSchema)
-    // The same call the capability deriver makes, so the published key and the
-    // key the generated filter/order-by is built from cannot disagree.
-    let keyField = GraphQL_FragmentGenerator.resolveKeyField(~entityName=R.Spec.name, stateSchema)
+    // The published key is always filterable; not every filterable field is the key.
+    let keyField = GraphQL_FragmentGenerator.resolveKeyField(
+      ~rowKeying=RowKeyedByEnvelope,
+      ~entityName=R.Spec.name,
+      stateSchema,
+    )
     // Qualified to the plugin's event ids so they match the producers' nodes.
     let consumed = qualify(~prefix=name, R.consumedEventNames)
     recordRetired(~entityName=R.Spec.name, stateSchema)
     recordLifecycle(~entityName=R.Spec.name, stateSchema)
-    recordKeyField(~entityName=R.Spec.name, stateSchema)
+    recordKeyField(~rowKeying=RowKeyedByEnvelope, ~entityName=R.Spec.name, stateSchema)
 
     (
       {
@@ -1471,12 +1544,13 @@ let make = (
       let stateSchema = SVS.Spec.stateSchema->S.castToUnknown
       let label = labelFieldsFromStateSchema(~entityName=SVS.Spec.name, stateSchema)
       let keyField = GraphQL_FragmentGenerator.resolveKeyField(
+        ~rowKeying=RowKeyedByStateField,
         ~entityName=SVS.Spec.name,
         stateSchema,
       )
       recordRetired(~entityName=SVS.Spec.name, stateSchema)
       recordLifecycle(~entityName=SVS.Spec.name, stateSchema)
-      recordKeyField(~entityName=SVS.Spec.name, stateSchema)
+      recordKeyField(~rowKeying=RowKeyedByStateField, ~entityName=SVS.Spec.name, stateSchema)
 
       (
         {
@@ -1529,6 +1603,53 @@ let make = (
   }
   let partitionFailures = []
 
+  // Each view's key as an identity: a read model's `Spec.Id` when it is one, else
+  // the key field's type, else the key field's name, so a view keyed by an untyped
+  // `productId` still lists the `productId` identity.
+  let keyIdentityOf = (stateSchema: S.t<unknown>, idField: option<string>) =>
+    idField->Option.map(field =>
+      switch stateSchema {
+      | Object({properties}) =>
+        properties->Dict.get(field)->Option.flatMap(Reventless.Semantic.identityKey)
+      | _ => None
+      }->Option.getOr(field)
+    )
+  let viewKeys = Array.concat(
+    readModels->Array.mapWithIndex((
+      module(R: ReventlessInfra.ReadModel.T with type api = api and type role = role),
+      i,
+    ) => {
+      let def = readModelDefs->Array.getUnsafe(i)
+      let key = switch R.Spec.Id.schema->Reventless.Semantic.identityKey {
+      | Some(_) as declared => declared
+      | None => keyIdentityOf(R.Spec.stateSchema->S.castToUnknown, def.idField)
+      }
+      (R.Spec.name, key)
+    }),
+    stateViewSlices->Array.mapWithIndex((module(SVS: ReventlessInfra.StateViewSlice.T), i) => {
+      let def = stateViewDefs->Array.getUnsafe(i)
+      (SVS.Spec.name, keyIdentityOf(SVS.Spec.stateSchema->S.castToUnknown, def.idField))
+    }),
+  )
+  let viewsByKey: dict<array<string>> = Dict.make()
+  viewKeys->Array.forEach(((view, key)) =>
+    key->Option.forEach(k =>
+      viewsByKey->Dict.set(k, viewsByKey->Dict.get(k)->Option.getOr([])->Array.concat([view]))
+    )
+  )
+  // Warned rather than refused, like the key-field gap: the field still decodes,
+  // it just links nowhere. Once per message, since a field recurs across variants.
+  let reported: Set.t<string> = Set.make()
+  let identityViews = {
+    viewsByKey,
+    viewNames: viewKeys->Array.map(((view, _)) => view),
+    report: message =>
+      if !(reported->Set.has(message)) {
+        reported->Set.add(message)
+        log.warn(~comp="Plugin_Structure", `${name}: ${message}`)
+      },
+  }
+
   let stateChangeDefs =
     stateChangeSlices->Array.mapWithIndex((module(SCS: ReventlessInfra.StateChangeSlice.T), i) => {
       let (_, produced) = scsProduced->Array.getUnsafe(i)
@@ -1538,6 +1659,7 @@ let make = (
         {
           Reventless.Plugin.name: SCS.Spec.name,
           commands: extractCommandDefs(
+            ~identityViews,
             ~isAggregate=false,
             ~partitionKey=?partitionBySlice->Dict.get(SCS.Spec.name),
             ~mutationFieldFor=variantName =>
@@ -1556,7 +1678,7 @@ let make = (
           consumedEventTypes: consumed,
           linkedViews: linkedSvsFor(produced),
           consistencyRead: consistencyReadFor(consumed),
-          events: extractEventDefs(SCS.Spec.eventSchema->S.castToUnknown),
+          events: extractEventDefs(~identityViews, SCS.Spec.eventSchema->S.castToUnknown),
           errors: extractErrorDefs(SCS.Spec.errorSchema->S.castToUnknown),
           chapter: chapterOf(SCS.Spec.name),
         }: Reventless.Plugin.writableDef
@@ -1573,6 +1695,7 @@ let make = (
       {
         Reventless.Plugin.name: A.Spec.name,
         commands: extractCommandDefs(
+          ~identityViews,
           ~isAggregate=true,
           ~mutationFieldFor=variantName =>
             Api_Naming.aggregateMutationField(
@@ -1589,7 +1712,7 @@ let make = (
         consumedEventTypes: [],
         linkedViews: Array.concat(linkedSvsFor(produced), linkedReadModelsFor(A.Spec.name)),
         consistencyRead: None,
-        events: extractEventDefs(A.Spec.eventSchema->S.castToUnknown),
+        events: extractEventDefs(~identityViews, A.Spec.eventSchema->S.castToUnknown),
         errors: extractErrorDefs(A.Spec.errorSchema->S.castToUnknown),
         chapter: chapterOf(A.Spec.name),
       }: Reventless.Plugin.writableDef

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

@@ -12,6 +12,7 @@ import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js
 import * as Trait$Reventless from "@reventlessdev/reventless-spec/src/types/Trait.res.mjs";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as Message$Reventless from "@reventlessdev/reventless-spec/src/types/Message.res.mjs";
+import * as Semantic$Reventless from "@reventlessdev/reventless-spec/src/semantic/Semantic.res.mjs";
 import * as Lifecycle$Reventless from "@reventlessdev/reventless-spec/src/types/Lifecycle.res.mjs";
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
@@ -444,20 +445,62 @@ function labelFieldsFromStateSchema(entityName, stateSchema) {
   };
 }
 
-function extractReferences(properties) {
-  return Object.entries(properties).flatMap(param => Reference$Reventless.collectFieldTargets(param[0], param[1]).map(param => {
-    let target = param[1];
-    return {
-      fieldName: param[0],
-      entity: target.entity,
-      plugin: target.plugin
-    };
-  }));
+function identityReference(identityViews, fieldName, fieldSchema, declared) {
+  let key = Semantic$Reventless.fieldIdentityKey(fieldSchema);
+  if (key === undefined) {
+    return declared;
+  }
+  let keyed = Stdlib_Option.getOr(identityViews.viewsByKey[key], []);
+  if (declared.length !== 0) {
+    declared.forEach(param => {
+      let target = param[1];
+      if (Stdlib_Option.isNone(target.plugin) && identityViews.viewNames.includes(target.entity) && !keyed.includes(target.entity)) {
+        return identityViews.report(fieldName + ` is a ` + key + `, and its @ref names ` + target.entity + `, which is not keyed by it.`);
+      }
+    });
+    return declared;
+  }
+  let len = keyed.length;
+  if (len !== 1) {
+    if (len !== 0) {
+      identityViews.report(fieldName + ` is a ` + key + `, and ` + keyed.join(" and ") + ` are all keyed by it. Say which it references with @ref.`);
+      return [];
+    } else {
+      identityViews.report(fieldName + ` is a ` + key + `, and no view in this plugin is keyed by it, so it references nothing. List the identity in a view, or reference another plugin's with @ref("Plugin.View").`);
+      return [];
+    }
+  }
+  let view = keyed[0];
+  return [[
+      fieldName,
+      {
+        entity: view,
+        plugin: undefined,
+        identity: key
+      }
+    ]];
 }
 
-function toEventDef(v) {
+function extractReferences(identityViews, properties) {
+  return Object.entries(properties).flatMap(param => {
+    let fieldSchema = param[1];
+    let fieldName = param[0];
+    let declared = Reference$Reventless.collectFieldTargets(fieldName, fieldSchema);
+    let targets = identityViews !== undefined ? identityReference(identityViews, fieldName, fieldSchema, declared) : declared;
+    return targets.map(param => {
+      let target = param[1];
+      return {
+        fieldName: param[0],
+        entity: target.entity,
+        plugin: target.plugin
+      };
+    });
+  });
+}
+
+function toEventDef(identityViews, v) {
   let mkDef = (variantName, properties) => {
-    let references = extractReferences(properties);
+    let references = extractReferences(identityViews, properties);
     return {
       name: variantName,
       schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(undefined, undefined, v)),
@@ -488,16 +531,16 @@ function toEventDef(v) {
   }
 }
 
-function extractEventDefs(eventSchema) {
+function extractEventDefs(identityViews, eventSchema) {
   if (eventSchema.type === "anyOf") {
-    return Stdlib_Array.filterMap(eventSchema.anyOf, toEventDef);
+    return Stdlib_Array.filterMap(eventSchema.anyOf, v => toEventDef(identityViews, v));
   } else {
-    return Stdlib_Option.mapOr(toEventDef(eventSchema), [], def => [def]);
+    return Stdlib_Option.mapOr(toEventDef(identityViews, eventSchema), [], def => [def]);
   }
 }
 
 function extractErrorDefs(errorSchema) {
-  return extractEventDefs(errorSchema).map(param => ({
+  return extractEventDefs(undefined, errorSchema).map(param => ({
     name: param.name,
     schema: param.schema,
     references: param.references
@@ -597,10 +640,10 @@ function annotateArgTypes(schema, argTypes) {
   return schema;
 }
 
-function toCommandDef(isAggregate, partitionKey, mutationFieldFor, parentSchema, commandAuthorization, commandTransition, derivedEdgeFor, v) {
+function toCommandDef(identityViews, isAggregate, partitionKey, mutationFieldFor, parentSchema, commandAuthorization, commandTransition, derivedEdgeFor, v) {
   let mkDef = (variantName, properties) => {
     let match = commandLevelAndId(isAggregate, partitionKey, variantName, properties);
-    let references = extractReferences(properties);
+    let references = extractReferences(identityViews, properties);
     let syntheticCommand = DcbTag$Reventless.isVariantPayloadBearing(parentSchema, variantName) ? ({
         TAG: variantName
       }) : variantName;
@@ -683,12 +726,12 @@ function toCommandDef(isAggregate, partitionKey, mutationFieldFor, parentSchema,
   }
 }
 
-function extractCommandDefs(isAggregate, partitionKey, mutationFieldFor, commandAuthorization, commandTransition, derivedEdgeForOpt, commandSchema) {
+function extractCommandDefs(identityViews, isAggregate, partitionKey, mutationFieldFor, commandAuthorization, commandTransition, derivedEdgeForOpt, commandSchema) {
   let derivedEdgeFor = derivedEdgeForOpt !== undefined ? derivedEdgeForOpt : param => {};
   if (commandSchema.type === "anyOf") {
-    return Stdlib_Array.filterMap(commandSchema.anyOf, v => toCommandDef(isAggregate, partitionKey, mutationFieldFor, commandSchema, commandAuthorization, commandTransition, derivedEdgeFor, v));
+    return Stdlib_Array.filterMap(commandSchema.anyOf, v => toCommandDef(identityViews, isAggregate, partitionKey, mutationFieldFor, commandSchema, commandAuthorization, commandTransition, derivedEdgeFor, v));
   } else {
-    return Stdlib_Option.mapOr(toCommandDef(isAggregate, partitionKey, mutationFieldFor, commandSchema, commandAuthorization, commandTransition, derivedEdgeFor, commandSchema), [], def => [def]);
+    return Stdlib_Option.mapOr(toCommandDef(identityViews, isAggregate, partitionKey, mutationFieldFor, commandSchema, commandAuthorization, commandTransition, derivedEdgeFor, commandSchema), [], def => [def]);
   }
 }
 
@@ -706,7 +749,7 @@ function queryableDefFromSpec(plugin, name, stateSchema, authorization, visibili
   let linkedWriteSide = linkedWriteSideOpt !== undefined ? linkedWriteSideOpt : [];
   let qf = Api_Naming$ReventlessCore.queryFieldNamesForReadModel(plugin, name, undefined);
   let label = labelFieldsFromStateSchema(name, stateSchema);
-  let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField(name, stateSchema);
+  let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByEnvelope", name, stateSchema);
   return {
     name: name,
     queryField: qf.listFieldName,
@@ -1006,16 +1049,16 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       retiredFailures.push(f);
     });
   };
-  let recordKeyField = (entityName, stateSchema) => Stdlib_Option.forEach(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField(entityName, stateSchema)), why => log.warn("Plugin_Structure", undefined, name + `/` + entityName + ` ` + why));
+  let recordKeyField = (rowKeying, entityName, stateSchema) => Stdlib_Option.forEach(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField(rowKeying, entityName, stateSchema)), why => log.warn("Plugin_Structure", undefined, name + `/` + entityName + ` ` + why));
   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 keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByEnvelope", R.Spec.name, stateSchema);
     let consumed = qualify(name, R.consumedEventNames);
     recordRetired(R.Spec.name, stateSchema);
     recordLifecycle(R.Spec.name, stateSchema);
-    recordKeyField(R.Spec.name, stateSchema);
+    recordKeyField("RowKeyedByEnvelope", R.Spec.name, stateSchema);
     return {
       name: R.Spec.name,
       queryField: qf.listFieldName,
@@ -1044,10 +1087,10 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let consumed = match[1];
     let stateSchema = SVS.Spec.stateSchema;
     let label = labelFieldsFromStateSchema(SVS.Spec.name, stateSchema);
-    let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField(SVS.Spec.name, stateSchema);
+    let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByStateField", SVS.Spec.name, stateSchema);
     recordRetired(SVS.Spec.name, stateSchema);
     recordLifecycle(SVS.Spec.name, stateSchema);
-    recordKeyField(SVS.Spec.name, stateSchema);
+    recordKeyField("RowKeyedByStateField", SVS.Spec.name, stateSchema);
     return {
       name: SVS.Spec.name,
       queryField: qf.listFieldName,
@@ -1101,6 +1144,46 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     };
   }
   let partitionFailures = [];
+  let keyIdentityOf = (stateSchema, idField) => Stdlib_Option.map(idField, field => {
+    let tmp;
+    tmp = stateSchema.type === "object" ? Stdlib_Option.flatMap(stateSchema.properties[field], Semantic$Reventless.identityKey) : undefined;
+    return Stdlib_Option.getOr(tmp, field);
+  });
+  let viewKeys = readModels.map((R, i) => {
+    let def = readModelDefs[i];
+    let declared = Semantic$Reventless.identityKey(R.Spec.Id.schema);
+    let key = declared !== undefined ? declared : keyIdentityOf(R.Spec.stateSchema, def.idField);
+    return [
+      R.Spec.name,
+      key
+    ];
+  }).concat(stateViewSlices.map((SVS, i) => {
+    let def = stateViewDefs[i];
+    return [
+      SVS.Spec.name,
+      keyIdentityOf(SVS.Spec.stateSchema, def.idField)
+    ];
+  }));
+  let viewsByKey = {};
+  viewKeys.forEach(param => {
+    let view = param[0];
+    Stdlib_Option.forEach(param[1], k => {
+      viewsByKey[k] = Stdlib_Option.getOr(viewsByKey[k], []).concat([view]);
+    });
+  });
+  let reported = new Set();
+  let identityViews_viewNames = viewKeys.map(param => param[0]);
+  let identityViews_report = message => {
+    if (!reported.has(message)) {
+      reported.add(message);
+      return log.warn("Plugin_Structure", undefined, name + `: ` + message);
+    }
+  };
+  let identityViews = {
+    viewsByKey: viewsByKey,
+    viewNames: identityViews_viewNames,
+    report: identityViews_report
+  };
   let stateChangeDefs = stateChangeSlices.map((SCS, i) => {
     let match = scsProduced[i];
     let produced = match[1];
@@ -1108,12 +1191,12 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let consumed = match$1[1];
     return {
       name: SCS.Spec.name,
-      commands: extractCommandDefs(false, partitionBySlice[SCS.Spec.name], variantName => Api_Naming$ReventlessCore.sliceMutationFieldFor(name, SCS.Spec.name, SCS.Spec.commandSchema, variantName), SCS.Spec.commandAuthorization, SCS.Spec.commandTransition, extra => derivedEdgeFor(SCS.Spec.name, extra), SCS.Spec.commandSchema),
+      commands: extractCommandDefs(identityViews, false, partitionBySlice[SCS.Spec.name], variantName => Api_Naming$ReventlessCore.sliceMutationFieldFor(name, SCS.Spec.name, SCS.Spec.commandSchema, variantName), SCS.Spec.commandAuthorization, SCS.Spec.commandTransition, extra => derivedEdgeFor(SCS.Spec.name, extra), SCS.Spec.commandSchema),
       producedEventTypes: produced,
       consumedEventTypes: consumed,
       linkedViews: linkedSvsFor(produced),
       consistencyRead: consistencyReadFor(consumed),
-      events: extractEventDefs(SCS.Spec.eventSchema),
+      events: extractEventDefs(identityViews, SCS.Spec.eventSchema),
       errors: extractErrorDefs(SCS.Spec.errorSchema),
       chapter: componentChapters[SCS.Spec.name]
     };
@@ -1123,12 +1206,12 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let produced = match[1];
     return {
       name: A.Spec.name,
-      commands: extractCommandDefs(true, undefined, variantName => Api_Naming$ReventlessCore.aggregateMutationField(name, A.Spec.name, variantName), A.Spec.commandAuthorization, A.Spec.commandTransition, extra => derivedEdgeFor(A.Spec.name, extra), A.Spec.commandSchema),
+      commands: extractCommandDefs(identityViews, true, undefined, variantName => Api_Naming$ReventlessCore.aggregateMutationField(name, A.Spec.name, variantName), A.Spec.commandAuthorization, A.Spec.commandTransition, extra => derivedEdgeFor(A.Spec.name, extra), A.Spec.commandSchema),
       producedEventTypes: produced,
       consumedEventTypes: [],
       linkedViews: linkedSvsFor(produced).concat(linkedReadModelsFor(A.Spec.name)),
       consistencyRead: undefined,
-      events: extractEventDefs(A.Spec.eventSchema),
+      events: extractEventDefs(identityViews, A.Spec.eventSchema),
       errors: extractErrorDefs(A.Spec.errorSchema),
       chapter: componentChapters[A.Spec.name]
     };
@@ -1452,6 +1535,7 @@ export {
   checkLifecycleTopology,
   labelFieldSourceToString,
   labelFieldsFromStateSchema,
+  identityReference,
   extractReferences,
   toEventDef,
   extractEventDefs,

package/tests/api/GraphQL_FragmentGeneratorTest.res

@@ -1,5 +1,12 @@
 open JestGlobals
 
+module OrderId = Reventless.Id.Make({
+  let key = "orderId"
+})
+module CustomerId = Reventless.Id.Make({
+  let key = "customerId"
+})
+
 // A multi-variant command union serializes as a sury `Union`, the same shape an
 // aggregate command produces. The generator must decide whether to inject the
 // aggregate-style `id: ID!` argument from the entry's `injectIdArg` flag, not
@@ -94,7 +101,11 @@ describe("GraphQL_FragmentGenerator slice TODO rows", () => {
 // 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)
+    GraphQL_FragmentGenerator.resolveKeyField(
+      ~rowKeying=RowKeyedByStateField,
+      ~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)})
@@ -137,12 +148,65 @@ describe("resolveKeyField — the ladder", () => {
   })
 })
 
+// A read model's row is keyed by the envelope id of the events it folds, so its
+// lone `*Id` field is a foreign id: `Orders = {customerId, …}` is not keyed by the
+// customer.
+describe("resolveKeyField — a read model is keyed by its envelope", () => {
+  let keyFor = (~entityName, schema) =>
+    GraphQL_FragmentGenerator.resolveKeyField(
+      ~rowKeying=RowKeyedByEnvelope,
+      ~entityName,
+      schema->S.castToUnknown,
+    )
+
+  testSync("a lone foreign `*Id` field does not name the key", () => {
+    let schema = S.schema(
+      s => {"customerId": s.matches(S.string), "lifecycle": s.matches(S.string)},
+    )
+    expect(keyFor(~entityName="Orders", schema))->toEqual(None)
+  })
+
+  testSync("the convention rung still names it", () => {
+    let schema = S.schema(s => {"orderId": s.matches(S.string), "customerId": s.matches(S.string)})
+    expect(keyFor(~entityName="Orders", schema))->toEqual(Some(("orderId", "convention")))
+  })
+
+  // The key is read off the type where there is one: a field typed as the view's
+  // own identity keys it whatever it is called, and one typed as another
+  // identity never does, whatever it is called.
+  testSync("a field typed as the view's identity is its key", () => {
+    let schema = S.schema(
+      s => {"order": s.matches(OrderId.schema), "customerId": s.matches(CustomerId.schema)},
+    )
+    expect(keyFor(~entityName="Orders", schema))->toEqual(Some(("order", "convention")))
+  })
+
+  testSync("a field named for the view but typed as another identity is not", () => {
+    let schema = S.schema(s => {"orderId": s.matches(CustomerId.schema)})
+    expect(keyFor(~entityName="Orders", schema))->toEqual(None)
+  })
+
+  testSync("several foreign `*Id` fields are not a gap worth a warning", () => {
+    let schema = S.schema(
+      s => {"productId": s.matches(S.string), "categoryId": s.matches(S.string)},
+    )
+    expect(
+      GraphQL_FragmentGenerator.classifyKeyField(
+        ~rowKeying=RowKeyedByEnvelope,
+        ~entityName="ProductDemand",
+        schema->S.castToUnknown,
+      )->GraphQL_FragmentGenerator.keyFieldGapMessage,
+    )->toEqual(None)
+  })
+})
+
 // Losing the key is invisible — the view keeps every field and every row, and
 // drops its `<field>Eq` filter and its whole `orderBy` from the SDL. These pin
 // which of the two ways to lose it is worth saying out loud.
 describe("keyFieldGapMessage — which gap is worth a warning", () => {
   let gapFor = (~entityName, schema) =>
     GraphQL_FragmentGenerator.classifyKeyField(
+      ~rowKeying=RowKeyedByStateField,
       ~entityName,
       schema->S.castToUnknown,
     )->GraphQL_FragmentGenerator.keyFieldGapMessage
@@ -197,6 +261,17 @@ describe("deriveServerCapability — inferred keys reach the SDL surface", () =>
     expect(c.sortFields)->toEqual(["orderId"])
   })
 
+  // Not the key of a read model, but filterable all the same: removing a
+  // generated filter is an SDL break.
+  testSync("a lone foreign `*Id` field stays filterable and sortable", () => {
+    let schema = S.schema(
+      s => {"customerId": s.matches(S.string), "lifecycle": s.matches(S.string)},
+    )
+    let c = capabilityFor(~entityName="Orders", schema)
+    expect(c.filterFields->Array.map(f => f.name))->toEqual(["customerId"])
+    expect(c.sortFields)->toEqual(["customerId"])
+  })
+
   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)