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

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.266 (2026-09-21)
+
+### Bug Fixes
+
+* **core:** an aggregate read model is not keyed by a foreign id ([0dfed74](https://github.com/ReventlessDev/reventless-core/commit/0dfed747c4182b1fc58675b42f5d3cb3eb6309c7))
+### Features
+
+* **spec:** one Id type per identity ([203be38](https://github.com/ReventlessDev/reventless-core/commit/203be389b9047db0a7a0294fe3c1c04ba5119965))
+* **spec:** the runtime reads identities ([417c5f6](https://github.com/ReventlessDev/reventless-core/commit/417c5f613b031a08c7849a81c75de6a8bbeb841b))
+
+
 # 3.0.0-alpha.265 (2026-09-20)
 
 **Note:** Version bump only for package @reventlessdev/reventless-core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.265",
+  "version": "3.0.0-alpha.266",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,16 +29,16 @@
     "sury": "11.0.0-rc.2",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.33",
-    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.12",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
+    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.12",
     "@reventlessdev/rescript-node": "2.0.0-alpha.12",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.21",
     "@reventlessdev/rescript-ssh2": "2.0.0-alpha.12",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.166",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.138",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.37"
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.37",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.167",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.139"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/components/Api/GraphQL_FragmentGenerator.res

@@ -316,19 +316,32 @@ type keyFieldResolution =
   | Ambiguous({candidates: array<string>, conventional: string})
   | NoCandidate
 
+/** Where a view's row key lives. A read model's row is keyed by the envelope id of
+    the events it folds, so a `*Id` field in its state is somebody else's id unless
+    it is declared or named as the view's own. A StateViewSlice keys its row by a
+    state field. */
+type rowKeying = RowKeyedByEnvelope | RowKeyedByStateField
+
 /**
 The field that identifies a row, and which rung answered:
 
 - `"annotation"` — the state declares `@id`. Nothing outranks it.
-- `"convention"` — a field named `<singular entity name>Id` exists
-  (`Products` → `productId`).
-- `"sole"` — the state has exactly one `*Id` field (`AvailableProducts`).
+- `"convention"` — a field keyed `<singular entity name>Id` exists
+  (`Products` → `productId`): named so, or typed as that identity.
+- `"sole"` — the state has exactly one `*Id` field (`AvailableProducts`). Only for
+  `RowKeyedByStateField`: a read model's lone `*Id` is a foreign id (`Orders` →
+  `customerId`), and having none of its own is its ordinary shape, so neither
+  that nor several `*Id` fields is a gap.
 
 Convention outranks sole so a view carrying one foreign key and no key of its own
 is not keyed by the foreign key. `resolveKeyField` is this, with both gaps
 flattened to `None`.
 */
-let classifyKeyField = (~entityName: string, schema: S.t<unknown>): keyFieldResolution => {
+let classifyKeyField = (
+  ~rowKeying: rowKeying,
+  ~entityName: string,
+  schema: S.t<unknown>,
+): keyFieldResolution => {
   let declared = switch Reventless.StateAnnotations.getSpec(schema) {
   | Some({ids}) => ids->Array.get(0)
   | None => None
@@ -336,29 +349,45 @@ let classifyKeyField = (~entityName: string, schema: S.t<unknown>): keyFieldReso
   switch declared {
   | Some(field) => Resolved({field, rung: "annotation"})
   | None =>
+    // A field is a candidate by its name or by its type, and its key is its
+    // identity when it has one: `orderId: CustomerId.t` never keys `Orders`, and
+    // `order: OrderId.t` does.
+    let properties = switch schema {
+    | Object({properties}) => properties
+    | _ => Dict.make()
+    }
+    let keyOf = field =>
+      properties->Dict.get(field)->Option.flatMap(Reventless.Semantic.identityKey)
     let candidates =
       SchemaType.fromSuryObject(~typeName="", schema)
       ->Option.getOr(Dict.make())
       ->Dict.keysToArray
-      ->Array.filter(isKeyFieldName)
+      ->Array.filter(field => isKeyFieldName(field) || keyOf(field)->Option.isSome)
     let singular = entityName->Api_Naming.stripViewSuffix->Api_Naming.singularize
     let conventional =
       singular->String.slice(~start=0, ~end=1)->String.toLowerCase ++
       singular->String.slice(~start=1, ~end=singular->String.length) ++ "Id"
-    if candidates->Array.includes(conventional) {
-      Resolved({field: conventional, rung: "convention"})
-    } else if candidates->Array.length == 1 {
-      Resolved({field: candidates->Array.getUnsafe(0), rung: "sole"})
-    } else if Array.length(candidates) == 0 {
-      NoCandidate
-    } else {
-      Ambiguous({candidates, conventional})
+    switch candidates->Array.find(field => keyOf(field)->Option.getOr(field) == conventional) {
+    | Some(field) => Resolved({field, rung: "convention"})
+    | None =>
+      if rowKeying == RowKeyedByEnvelope {
+        NoCandidate
+      } else if candidates->Array.length == 1 {
+        Resolved({field: candidates->Array.getUnsafe(0), rung: "sole"})
+      } else if Array.length(candidates) == 0 {
+        NoCandidate
+      } else {
+        Ambiguous({candidates, conventional})
+      }
     }
   }
 }
 
-let resolveKeyField = (~entityName: string, schema: S.t<unknown>): option<(string, string)> =>
-  switch classifyKeyField(~entityName, schema) {
+let resolveKeyField = (~rowKeying: rowKeying, ~entityName: string, schema: S.t<unknown>): option<(
+  string,
+  string,
+)> =>
+  switch classifyKeyField(~rowKeying, ~entityName, schema) {
   | Resolved({field, rung}) => Some((field, rung))
   | Ambiguous(_) | NoCandidate => None
   }
@@ -457,7 +486,9 @@ let deriveServerCapability = (~entityName: string, schema: S.t<unknown>): server
   // a client asked for happened client-side over one page. Its key is knowable
   // without the annotation in the common cases; take it. Pushed last, and both
   // pushes dedupe, so a declared `@id` keeps its position and this is a no-op.
-  switch resolveKeyField(~entityName, schema) {
+  // Read as a state-field key for every view: a read model's lone foreign id is
+  // not its key, but it stays filterable, since dropping it would break the SDL.
+  switch resolveKeyField(~rowKeying=RowKeyedByStateField, ~entityName, schema) {
   | Some((field, _rung)) =>
     pushFilter(field, ~range=false)
     pushSort(field)

package/src/components/Api/GraphQL_FragmentGenerator.res.mjs

@@ -5,6 +5,7 @@ import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_String from "@rescript/runtime/lib/es6/Stdlib_String.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as Semantic$Reventless from "@reventlessdev/reventless-spec/src/semantic/Semantic.res.mjs";
 import * as ReadModel$Reventless from "@reventlessdev/reventless-spec/src/components/ReadModel.res.mjs";
 import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
 import * as Api_Naming$ReventlessCore from "./Api_Naming.res.mjs";
@@ -256,7 +257,7 @@ function isKeyFieldName(name) {
   }
 }
 
-function classifyKeyField(entityName, schema) {
+function classifyKeyField(rowKeying, entityName, schema) {
   let match = StateAnnotations$Reventless.getSpec(schema);
   let declared = match !== undefined ? match.ids[0] : undefined;
   if (declared !== undefined) {
@@ -266,15 +267,27 @@ function classifyKeyField(entityName, schema) {
       rung: "annotation"
     };
   }
-  let candidates = Object.keys(Stdlib_Option.getOr(SchemaType$ReventlessCore.fromSuryObject("", schema), {})).filter(isKeyFieldName);
+  let properties;
+  properties = schema.type === "object" ? schema.properties : ({});
+  let keyOf = field => Stdlib_Option.flatMap(properties[field], Semantic$Reventless.identityKey);
+  let candidates = Object.keys(Stdlib_Option.getOr(SchemaType$ReventlessCore.fromSuryObject("", schema), {})).filter(field => {
+    if (isKeyFieldName(field)) {
+      return true;
+    } else {
+      return Stdlib_Option.isSome(keyOf(field));
+    }
+  });
   let singular = Api_Naming$ReventlessCore.singularize(Api_Naming$ReventlessCore.stripViewSuffix(entityName));
   let conventional = singular.slice(0, 1).toLowerCase() + singular.slice(1, singular.length) + "Id";
-  if (candidates.includes(conventional)) {
+  let field = candidates.find(field => Stdlib_Option.getOr(keyOf(field), field) === conventional);
+  if (field !== undefined) {
     return {
       TAG: "Resolved",
-      field: conventional,
+      field: field,
       rung: "convention"
     };
+  } else if (rowKeying === "RowKeyedByEnvelope") {
+    return "NoCandidate";
   } else if (candidates.length === 1) {
     return {
       TAG: "Resolved",
@@ -292,8 +305,8 @@ function classifyKeyField(entityName, schema) {
   }
 }
 
-function resolveKeyField(entityName, schema) {
-  let match = classifyKeyField(entityName, schema);
+function resolveKeyField(rowKeying, entityName, schema) {
+  let match = classifyKeyField(rowKeying, entityName, schema);
   if (typeof match !== "object" || match.TAG !== "Resolved") {
     return;
   } else {
@@ -373,7 +386,7 @@ function deriveServerCapability(entityName, schema) {
     spec.scan.forEach(name => pushFilter(name, false));
     spec.scanSort.forEach(pushSort);
   }
-  let match = resolveKeyField(entityName, schema);
+  let match = resolveKeyField("RowKeyedByStateField", entityName, schema);
   if (match !== undefined) {
     let field = match[0];
     pushFilter(field, false);

package/src/components/Api/SchemaType.res

@@ -45,6 +45,14 @@ let isTagged = Reventless.DcbTag.isTagged
 let isDateTime = Reventless.DateTime.isDateTime
 let isCalendarDate = Reventless.CalendarDate.isCalendarDate
 
+// On the schema itself, not through `option<…>` as `Semantic.get` reads: the
+// optional wrapper then reaches the `AnyOf` branch and stays `Nullable`.
+let isIdentity = (schema: S.t<unknown>): bool =>
+  switch schema->S.Metadata.get(~id=Reventless.Semantic.semanticId) {
+  | Some({id}) => id === Reventless.Semantic.Id.identity
+  | None => false
+  }
+
 let isIdFieldName = (name: string): bool => {
   let lower = String.toLowerCase(name)
   let len = String.length(lower)
@@ -123,12 +131,14 @@ and withoutDefault = (
 }
 
 and shapeOf = (~parentName: string, ~fieldName: string, schema: S.t<unknown>): schemaType => {
-  // Two independent facts, checked independently. A DCB-tagged field is an
+  // Three independent facts, checked independently. A DCB-tagged field is an
   // entity id because it routes; a reference field is one because it points at
-  // an entity. Neither implies the other — a `@partitionTag` field carries no
+  // an entity; an identity-typed field is one whatever it is called. Neither implies the other — a `@partitionTag` field carries no
   // reference, and `Reference.toWithoutDcbTag` carries no tag — so collapsing
   // these into one test would silently reclassify whichever case it dropped.
-  if isTagged(schema) || Reventless.Reference.getTarget(schema)->Option.isSome {
+  if (
+    isTagged(schema) || Reventless.Reference.getTarget(schema)->Option.isSome || isIdentity(schema)
+  ) {
     EntityId
   } else {
     switch schema {

package/src/components/Api/SchemaType.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Sury from "sury";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
@@ -11,6 +12,15 @@ import * as TaggedUnion$Reventless from "@reventlessdev/reventless-spec/src/comp
 import * as CalendarDate$Reventless from "@reventlessdev/reventless-spec/src/semantic/CalendarDate.res.mjs";
 import * as FieldDefault$Reventless from "@reventlessdev/reventless-spec/src/components/FieldDefault.res.mjs";
 
+function isIdentity(schema) {
+  let match = Sury.$Metadata_get(schema, Semantic$Reventless.semanticId);
+  if (match !== undefined) {
+    return match.id === Semantic$Reventless.Id.identity;
+  } else {
+    return false;
+  }
+}
+
 function isIdFieldName(name) {
   let lower = name.toLowerCase();
   let len = lower.length;
@@ -87,7 +97,7 @@ function withoutDefault(parentName, fieldName, schema) {
 }
 
 function shapeOf(parentName, fieldName, schema) {
-  if (DcbTag$Reventless.isTagged(schema) || Stdlib_Option.isSome(Reference$Reventless.getTarget(schema))) {
+  if (DcbTag$Reventless.isTagged(schema) || Stdlib_Option.isSome(Reference$Reventless.getTarget(schema)) || isIdentity(schema)) {
     return "EntityId";
   }
   switch (schema.type) {
@@ -425,6 +435,7 @@ export {
   isTagged,
   isDateTime,
   isCalendarDate,
+  isIdentity,
   isIdFieldName,
   isIdsFieldName,
   semanticCompositeNames,
@@ -439,4 +450,4 @@ export {
   trailShape,
   fromSuryObject,
 }
-/* DcbTag-Reventless Not a pure module */
+/* sury Not a pure module */

package/src/components/Api/SuryToJsonSchema.res

@@ -310,11 +310,15 @@ and withSemantic = (fieldSchema: JSON.t, sem: Reventless.Semantic.t): JSON.t =>
     obj->Dict.set("x-reventless-semantic-source", str("type"))
     switch sem.payload {
     | Plain => ()
-    | ReferenceTo({entity, plugin}) =>
-      obj->Dict.set(
-        "x-reventless-semantic-target",
-        jsonObject(withOptionalPlugin([("entity", str(entity))], plugin)),
-      )
+    | ReferenceTo({entity, plugin, ?identity}) =>
+      let pairs = withOptionalPlugin([("entity", str(entity))], plugin)
+      let pairs = switch identity {
+      | Some(key) => Array.concat(pairs, [("identity", str(key))])
+      | None => pairs
+      }
+      obj->Dict.set("x-reventless-semantic-target", jsonObject(pairs))
+    | IdentityOf({key}) =>
+      obj->Dict.set("x-reventless-semantic-target", jsonObject([("key", str(key))]))
     | StoredIn({plugin, store}) =>
       // An absent plugin means "this plugin's own store" — omit the key rather
       // than writing an empty string, so a reader never has to tell those apart.

package/src/components/Api/SuryToJsonSchema.res.mjs

@@ -355,10 +355,16 @@ function withSemantic(fieldSchema, sem) {
     switch (match.TAG) {
       case "ReferenceTo" :
         let match$1 = match._0;
-        obj["x-reventless-semantic-target"] = Object.fromEntries(withOptionalPlugin([[
+        let identity = match$1.identity;
+        let pairs = withOptionalPlugin([[
             "entity",
             match$1.entity
-          ]], match$1.plugin));
+          ]], match$1.plugin);
+        let pairs$1 = identity !== undefined ? pairs.concat([[
+              "identity",
+              identity
+            ]]) : pairs;
+        obj["x-reventless-semantic-target"] = Object.fromEntries(pairs$1);
         break;
       case "StoredIn" :
         let match$2 = match._0;
@@ -384,6 +390,12 @@ function withSemantic(fieldSchema, sem) {
             match$3.field
           ]], match$3.plugin), "view", match$3.view), "content", match$3.content));
         break;
+      case "IdentityOf" :
+        obj["x-reventless-semantic-target"] = Object.fromEntries([[
+            "key",
+            match.key
+          ]]);
+        break;
     }
   }
   return obj;

package/src/plugin/component/Plugin_Structure.res

@@ -986,9 +986,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 +1417,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 +1428,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 +1477,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)
 
       (
         {

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

@@ -706,7 +706,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 +1006,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 +1044,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,

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)

package/tests/api/GraphQL_FragmentGeneratorTest.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Sury from "sury";
+import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.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";
@@ -9,6 +10,14 @@ import * as GraphQL_FragmentGenerator$ReventlessCore from "../../src/components/
 import * as PsInternalFieldsReadModel$ReventlessCore from "./PsInternalFieldsReadModel.res.mjs";
 import * as OutboundTranslationSlice_Callback$ReventlessCore from "../../src/components/OutboundTranslationSlice/OutboundTranslationSlice_Callback.res.mjs";
 
+let OrderId = Id$Reventless.Make({
+  key: "orderId"
+});
+
+let CustomerId = Id$Reventless.Make({
+  key: "customerId"
+});
+
 let commandSchema = Sury.union([
   Sury.$schema(s => ({
     TAG: "CancelOrder",
@@ -100,7 +109,7 @@ globalThis.describe("resolveKeyField — the ladder", () => {
       productId: s.m(Sury.string),
       name: s.m(Sury.string)
     }));
-    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("AvailableProducts", schema)).toEqual([
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByStateField", "AvailableProducts", schema)).toEqual([
       "productId",
       "sole"
     ]);
@@ -110,7 +119,7 @@ globalThis.describe("resolveKeyField — the ladder", () => {
       productId: s.m(Sury.string),
       categoryId: s.m(Sury.string)
     }));
-    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("Products", schema)).toEqual([
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByStateField", "Products", schema)).toEqual([
       "productId",
       "convention"
     ]);
@@ -120,7 +129,7 @@ globalThis.describe("resolveKeyField — the ladder", () => {
       categoryId: s.m(Sury.string),
       ownerId: s.m(Sury.string)
     }));
-    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("Categories", schema)).toEqual([
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByStateField", "Categories", schema)).toEqual([
       "categoryId",
       "convention"
     ]);
@@ -130,53 +139,94 @@ globalThis.describe("resolveKeyField — the ladder", () => {
       productId: s.m(Sury.string),
       categoryId: s.m(Sury.string)
     }));
-    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("ProductDemand", schema)).toEqual(undefined);
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByStateField", "ProductDemand", schema)).toEqual(undefined);
   });
   globalThis.test("no `*Id` field at all declines", () => {
     let schema = Sury.$schema(s => ({
       email: s.m(Sury.string),
       address: s.m(Sury.string)
     }));
-    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("Customers", schema)).toEqual(undefined);
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByStateField", "Customers", schema)).toEqual(undefined);
   });
   globalThis.test("a word merely ending in `id` is not a key", () => {
     let schema = Sury.$schema(s => ({
       paid: s.m(Sury.string),
       valid: s.m(Sury.string)
     }));
-    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("Invoices", schema)).toEqual(undefined);
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByStateField", "Invoices", schema)).toEqual(undefined);
+  });
+});
+
+globalThis.describe("resolveKeyField — a read model is keyed by its envelope", () => {
+  globalThis.test("a lone foreign `*Id` field does not name the key", () => {
+    let schema = Sury.$schema(s => ({
+      customerId: s.m(Sury.string),
+      lifecycle: s.m(Sury.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByEnvelope", "Orders", schema)).toEqual(undefined);
+  });
+  globalThis.test("the convention rung still names it", () => {
+    let schema = Sury.$schema(s => ({
+      orderId: s.m(Sury.string),
+      customerId: s.m(Sury.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByEnvelope", "Orders", schema)).toEqual([
+      "orderId",
+      "convention"
+    ]);
+  });
+  globalThis.test("a field typed as the view's identity is its key", () => {
+    let schema = Sury.$schema(s => ({
+      order: s.m(OrderId.schema),
+      customerId: s.m(CustomerId.schema)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByEnvelope", "Orders", schema)).toEqual([
+      "order",
+      "convention"
+    ]);
+  });
+  globalThis.test("a field named for the view but typed as another identity is not", () => {
+    let schema = Sury.$schema(s => ({
+      orderId: s.m(CustomerId.schema)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField("RowKeyedByEnvelope", "Orders", schema)).toEqual(undefined);
+  });
+  globalThis.test("several foreign `*Id` fields are not a gap worth a warning", () => {
+    let schema = Sury.$schema(s => ({
+      productId: s.m(Sury.string),
+      categoryId: s.m(Sury.string)
+    }));
+    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField("RowKeyedByEnvelope", "ProductDemand", schema))).toEqual(undefined);
   });
 });
 
 globalThis.describe("keyFieldGapMessage — which gap is worth a warning", () => {
+  let gapFor = (entityName, schema) => GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField("RowKeyedByStateField", entityName, schema));
   globalThis.test("a second `*Id` field taking the key away is named, with both fields", () => {
     let schema = Sury.$schema(s => ({
       productId: s.m(Sury.string),
       categoryId: s.m(Sury.string)
     }));
-    let message = Stdlib_Option.getOr(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField("ProductDemand", schema)), "");
+    let message = Stdlib_Option.getOr(gapFor("ProductDemand", schema), "");
     globalThis.expect(message.includes("productId, categoryId")).toBe(true);
     globalThis.expect(message.includes("productDemandId")).toBe(true);
   });
   globalThis.test("a state with no `*Id` field at all is silent, not warned about", () => {
-    let schema = Sury.$schema(s => ({
+    globalThis.expect(gapFor("Customers", Sury.$schema(s => ({
       email: s.m(Sury.string),
       address: s.m(Sury.string)
-    }));
-    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField("Customers", schema))).toEqual(undefined);
+    })))).toEqual(undefined);
   });
   globalThis.test("a resolved key says nothing", () => {
-    let schema = Sury.$schema(s => ({
+    globalThis.expect(gapFor("Orders", Sury.$schema(s => ({
       orderId: s.m(Sury.string)
-    }));
-    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField("Orders", schema))).toEqual(undefined);
+    })))).toEqual(undefined);
   });
   globalThis.test("an @id-less view whose name picks one of its `*Id` fields is fine", () => {
-    let schema = Sury.$schema(s => ({
+    globalThis.expect(gapFor("Products", Sury.$schema(s => ({
       productId: s.m(Sury.string),
       categoryId: s.m(Sury.string)
-    }));
-    globalThis.expect(GraphQL_FragmentGenerator$ReventlessCore.keyFieldGapMessage(GraphQL_FragmentGenerator$ReventlessCore.classifyKeyField("Products", schema))).toEqual(undefined);
+    })))).toEqual(undefined);
   });
 });
 
@@ -190,6 +240,15 @@ globalThis.describe("deriveServerCapability — inferred keys reach the SDL surf
     globalThis.expect(c.filterFields.map(f => f.name)).toEqual(["orderId"]);
     globalThis.expect(c.sortFields).toEqual(["orderId"]);
   });
+  globalThis.test("a lone foreign `*Id` field stays filterable and sortable", () => {
+    let schema = Sury.$schema(s => ({
+      customerId: s.m(Sury.string),
+      lifecycle: s.m(Sury.string)
+    }));
+    let c = GraphQL_FragmentGenerator$ReventlessCore.deriveServerCapability("Orders", schema);
+    globalThis.expect(c.filterFields.map(f => f.name)).toEqual(["customerId"]);
+    globalThis.expect(c.sortFields).toEqual(["customerId"]);
+  });
   globalThis.test("an unresolvable key still yields nothing — the old behaviour, now narrowed", () => {
     let schema = Sury.$schema(s => ({
       email: s.m(Sury.string)
@@ -668,6 +727,8 @@ globalThis.describe("@resolves / @resolvesMany reach the SDL", () => {
 });
 
 export {
+  OrderId,
+  CustomerId,
   OrderSliceCmd,
   mutationFor,
   GeocodeItem,
@@ -680,4 +741,4 @@ export {
   refDoorFragment,
   ResolvedFields,
 }
-/* commandSchema Not a pure module */
+/* OrderId Not a pure module */

package/tests/api/IdentitySemanticTest.res

@@ -0,0 +1,77 @@
+// An identity-typed field is an id whatever it is called: `buyer: CustomerId.t`
+// must reach the SDL as `ID!` and carry its key on the JSON Schema, or a field
+// that is neither tagged nor referenced loses its id-ness on the wire.
+
+open JestGlobals
+
+module OrderId = Reventless.Id.Make({
+  let key = "orderId"
+})
+module CustomerId = Reventless.Id.Make({
+  let key = "customerId"
+})
+
+@schema
+type order = {
+  buyer: CustomerId.t,
+  previous: option<OrderId.t>,
+  related: array<OrderId.t>,
+  note: string,
+}
+
+let property = (json: JSON.t, name: string): option<JSON.t> =>
+  json
+  ->JSON.Decode.object
+  ->Option.flatMap(o => o->Dict.get("properties"))
+  ->Option.flatMap(JSON.Decode.object)
+  ->Option.flatMap(p => p->Dict.get(name))
+
+let key = (json: option<JSON.t>, name: string): option<JSON.t> =>
+  json->Option.flatMap(JSON.Decode.object)->Option.flatMap(o => o->Dict.get(name))
+
+describe("the identity semantic on the JSON Schema", () => {
+  let json = SuryToJsonSchema.deriveObjectSchema(orderSchema->S.castToUnknown)
+
+  testSync("names the semantic and its key", () => {
+    let buyer = json->property("buyer")
+    expect(buyer->key("x-reventless-semantic"))->toEqual(Some(JSON.Encode.string("identity")))
+    expect(buyer->key("x-reventless-semantic-target"))->toEqual(
+      Some(JSON.Encode.object(Dict.fromArray([("key", JSON.Encode.string("customerId"))]))),
+    )
+  })
+
+  testSync("reaches an array's elements", () =>
+    expect(
+      json
+      ->property("related")
+      ->key("items")
+      ->key("x-reventless-semantic-target")
+      ->key("key"),
+    )->toEqual(Some(JSON.Encode.string("orderId")))
+  )
+
+  testSync("leaves a plain string alone", () =>
+    expect(json->property("note")->key("x-reventless-semantic"))->toEqual(None)
+  )
+})
+
+describe("the identity semantic in the SDL", () => {
+  let sdl =
+    GraphQL_FragmentGenerator.deriveObjectTypeWithNested(
+      ~typeName="Ordering_Order",
+      ~includeIdParam=false,
+      orderSchema->S.castToUnknown,
+    )->Array.join("\n")
+
+  testSync("an identity field not named `*Id` is an ID", () =>
+    expect(sdl->String.includes("buyer: ID!"))->toBe(true)
+  )
+
+  testSync("an optional identity keeps its optionality", () =>
+    expect(sdl->String.includes("previous: ID\n"))->toBe(true)
+  )
+
+  testSync("an array of identities is a list of IDs", () =>
+    expect(sdl->String.includes("related: [ID!]!"))->toBe(true)
+  )
+})

package/tests/api/IdentitySemanticTest.res.mjs

@@ -0,0 +1,71 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as SuryToJsonSchema$ReventlessCore from "../../src/components/Api/SuryToJsonSchema.res.mjs";
+import * as GraphQL_FragmentGenerator$ReventlessCore from "../../src/components/Api/GraphQL_FragmentGenerator.res.mjs";
+
+let OrderId = Id$Reventless.Make({
+  key: "orderId"
+});
+
+let CustomerId = Id$Reventless.Make({
+  key: "customerId"
+});
+
+let orderSchema = Sury.$schema(s => ({
+  buyer: s.m(CustomerId.schema),
+  previous: s.m(Sury.$option(OrderId.schema)),
+  related: s.m(Sury.array(OrderId.schema)),
+  note: s.m(Sury.string)
+}));
+
+function property(json, name) {
+  return Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(json), o => o["properties"]), Stdlib_JSON.Decode.object), p => p[name]);
+}
+
+function key(json, name) {
+  return Stdlib_Option.flatMap(Stdlib_Option.flatMap(json, Stdlib_JSON.Decode.object), o => o[name]);
+}
+
+globalThis.describe("the identity semantic on the JSON Schema", () => {
+  let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(undefined, undefined, orderSchema);
+  globalThis.test("names the semantic and its key", () => {
+    let buyer = property(json, "buyer");
+    globalThis.expect(key(buyer, "x-reventless-semantic")).toEqual("identity");
+    globalThis.expect(key(buyer, "x-reventless-semantic-target")).toEqual(Object.fromEntries([[
+        "key",
+        "customerId"
+      ]]));
+  });
+  globalThis.test("reaches an array's elements", () => {
+    globalThis.expect(key(key(key(property(json, "related"), "items"), "x-reventless-semantic-target"), "key")).toEqual("orderId");
+  });
+  globalThis.test("leaves a plain string alone", () => {
+    globalThis.expect(key(property(json, "note"), "x-reventless-semantic")).toEqual(undefined);
+  });
+});
+
+globalThis.describe("the identity semantic in the SDL", () => {
+  let sdl = GraphQL_FragmentGenerator$ReventlessCore.deriveObjectTypeWithNested("Ordering_Order", undefined, false, undefined, orderSchema).join("\n");
+  globalThis.test("an identity field not named `*Id` is an ID", () => {
+    globalThis.expect(sdl.includes("buyer: ID!")).toBe(true);
+  });
+  globalThis.test("an optional identity keeps its optionality", () => {
+    globalThis.expect(sdl.includes("previous: ID\n")).toBe(true);
+  });
+  globalThis.test("an array of identities is a list of IDs", () => {
+    globalThis.expect(sdl.includes("related: [ID!]!")).toBe(true);
+  });
+});
+
+export {
+  OrderId,
+  CustomerId,
+  orderSchema,
+  property,
+  key,
+}
+/* OrderId Not a pure module */