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

package/CHANGELOG.md

@@ -3,6 +3,38 @@
 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.224 (2026-08-11)
+
+### Bug Fixes
+
+* **api:** one id contract across the read-side query doors ([c52fac2](https://github.com/ReventlessDev/reventless-core/commit/c52fac2bee87b3dd1fa33b4970a74f3cd3866280))
+* feat(core)!: name semantic composites once instead of once per field ([09536ba](https://github.com/ReventlessDev/reventless-core/commit/09536badf338f898b24d749270acd5c7df851ddb))
+### Features
+
+* **api:** infer a queryable's key field and publish its provenance ([c835a42](https://github.com/ReventlessDev/reventless-core/commit/c835a42a0da07cdc4a3f010212e1f340a4a0ca27))
+* **plugin:** publish singleQueryField on queryableDef ([a724ab5](https://github.com/ReventlessDev/reventless-core/commit/a724ab573614792c0615d68b6486b94da14f9f82))
+
+### BREAKING CHANGES
+
+* generated GraphQL type names change. A price field is now
+`MoneyInput!` in a command and `Money!` in a read model, where it was named
+after the field that carried it (`Catalog_AddProductPriceCurrency`,
+`Ordering_SyncNewProductPriceCurrency`, …). AutoUI builds its queries at
+runtime from the component-definitions manifest and adapts on its own; a client
+naming the old types in a hand-written query does not.
+
+
+
+# 3.0.0-alpha.223 (2026-08-10)
+
+### Bug Fixes
+
+* **core:** collect [@ref](https://github.com/ref) declared on an array field ([6f9e2fe](https://github.com/ReventlessDev/reventless-core/commit/6f9e2fef2568ad57a8bf2efbaa9cd4830a947f26))
+### Features
+
+* **admin:** carry Internal queryables on their own manifest field ([f5aa03d](https://github.com/ReventlessDev/reventless-core/commit/f5aa03d60b0b2554d116fe9b3784d30f2c4ef356))
+
+
 # 3.0.0-alpha.222 (2026-08-10)
 
 **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.222",
+  "version": "3.0.0-alpha.224",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,16 +29,16 @@
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
-    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.3",
+    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.4",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.3",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.4",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
-    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.132",
-    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.3",
+    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.4",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.106"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.134",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.108",
+    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/admin/Platform_Admin_Structure.res

@@ -121,6 +121,16 @@ let pluginReadModel: queryableDef = {
   statusField: Some("status"),
   visibility: None,
   chapter: None,
+  // The admin fragment hand-declares its query names rather than deriving them from
+  // the read-model name, so the singular is taken from the same call
+  // `PluginBaseFragment.queryNames.singleFieldName` makes — not singularised here.
+  singleQueryField: Some(Api_Naming.adminField(~name="Plugin")),
+  // No key field to name: the row id is `name@version` (`Plugin.makeId`), and the
+  // state carries the two halves separately rather than the composed key. `None`
+  // is the honest answer — the same one the resolver ladder reaches for a state
+  // with no `*Id` field.
+  idField: None,
+  idFieldSource: None,
 }
 
 let structure: pluginStructure = {

package/src/admin/Platform_Admin_Structure.res.mjs

@@ -135,6 +135,8 @@ let pluginReadModel_labelFieldSource = "convention";
 
 let pluginReadModel_statusField = "status";
 
+let pluginReadModel_singleQueryField = Api_Naming$ReventlessCore.adminField("Plugin");
+
 let pluginReadModel = {
   name: "Plugins",
   queryField: pluginReadModel_queryField,
@@ -146,7 +148,10 @@ let pluginReadModel = {
   labelFieldSource: pluginReadModel_labelFieldSource,
   statusField: pluginReadModel_statusField,
   visibility: undefined,
-  chapter: undefined
+  chapter: undefined,
+  singleQueryField: pluginReadModel_singleQueryField,
+  idField: undefined,
+  idFieldSource: undefined
 };
 
 let structure_readModels = [pluginReadModel];

package/src/admin/Platform_ComponentDefinitionsApi.res

@@ -25,12 +25,23 @@ let sdlTypes: array<string> = [
   // with, and the two lists must stay independently evolvable.
   `type Platform_ErrorDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   `type Platform_WriteSideDef {\n  name: String!\n  commands: [Platform_CommandDef!]!\n  linkedViews: [String!]!\n  consistencyRead: String\n  producedEventTypes: [String!]!\n  consumedEventTypes: [String!]!\n  events: [Platform_EventDef!]!\n  errors: [Platform_ErrorDef!]!\n  chapter: String\n}`,
-  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n}`,
+  // `singleQueryField` / `idField` / `idFieldSource` are nullable, not `String!`:
+  // structures persisted before the fields existed decode as `None`, a hand-rolled
+  // def may decline to state them, and a state whose key cannot be resolved has no
+  // `idField` to report.
+  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n  targetName: String\n  chapter: String\n}`,
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_InboundTranslationSliceDef {\n  name: String!\n  commandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_ExtensionDef {\n  name: String!\n  delegateNames: [String!]!\n  eventTypes: [String!]!\n  commandTypes: [String!]!\n}`,
-  `type Platform_ComponentDefinitionEntry {\n  pluginId: String!\n  readModels: [Platform_ReadSideDef!]!\n  stateViewSlices: [Platform_ReadSideDef!]!\n  stateChangeSlices: [Platform_WriteSideDef!]!\n  aggregates: [Platform_WriteSideDef!]!\n  automationSlices: [Platform_AutomationSliceDef!]!\n  outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!\n  inboundTranslationSlices: [Platform_InboundTranslationSliceDef!]!\n  extensions: [Platform_ExtensionDef!]!\n}`,
+  // `internalQueryables` is the complement of the `readModels` / `stateViewSlices`
+  // filter, not an addition to either: it carries exactly the components the
+  // filter removed. A consumer enumerating surfaces reads the two filtered lists
+  // and is structurally unable to turn an Internal view into a page; a consumer
+  // resolving a reference target reads all three. Keeping it a separate field is
+  // what makes that separation structural rather than a filter every enumeration
+  // site has to remember.
+  `type Platform_ComponentDefinitionEntry {\n  pluginId: String!\n  readModels: [Platform_ReadSideDef!]!\n  stateViewSlices: [Platform_ReadSideDef!]!\n  internalQueryables: [Platform_ReadSideDef!]!\n  stateChangeSlices: [Platform_WriteSideDef!]!\n  aggregates: [Platform_WriteSideDef!]!\n  automationSlices: [Platform_AutomationSliceDef!]!\n  outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!\n  inboundTranslationSlices: [Platform_InboundTranslationSliceDef!]!\n  extensions: [Platform_ExtensionDef!]!\n}`,
 ]
 
 let sdlQueryField: string = `  Platform_ComponentDefinitions: [Platform_ComponentDefinitionEntry!]!`
@@ -75,6 +86,13 @@ let encodeCommandDef = (c: commandDef): JSON.t =>
 // Internal ReadModels / StateViewSlices are carried in pluginStructure for developer
 // tooling but must stay out of the deployed AutoUI — the menu, drill-down pages and
 // queryable defs are all derived from this response, so filter them here.
+//
+// Hidden from the menu is not the same question as denied as a reference target: a
+// denormalised lookup view is precisely the thing an author wants referenceable but
+// not navigable. The filtered lists answer the first question, `internalQueryables`
+// (below) answers the second. Neither is a security boundary — an Internal view
+// keeps its resolver and stays queryable, so naming it here publishes a fact the
+// caller is already entitled to.
 let isPublicQueryable = (q: queryableDef): bool => q.visibility != Some("Internal")
 
 let encodeQueryableDef = (r: queryableDef): JSON.t =>
@@ -97,6 +115,12 @@ let encodeQueryableDef = (r: queryableDef): JSON.t =>
     // survives the filter anyway.
     ("visibility", r.visibility->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
     ("chapter", r.chapter->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    (
+      "singleQueryField",
+      r.singleQueryField->Option.mapOr(JSON.Encode.null, JSON.Encode.string),
+    ),
+    ("idField", r.idField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    ("idFieldSource", r.idFieldSource->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
   ])->JSON.Encode.object
 
 let encodeEventDef = (e: eventDef): JSON.t =>
@@ -190,6 +214,13 @@ let encodePluginStructureEntry = (~pluginId: string, def: pluginStructure): JSON
       ->Array.map(encodeQueryableDef)
       ->JSON.Encode.array,
     ),
+    (
+      "internalQueryables",
+      Array.concat(def.readModels, def.stateViewSlices)
+      ->Array.filter(q => !isPublicQueryable(q))
+      ->Array.map(encodeQueryableDef)
+      ->JSON.Encode.array,
+    ),
     ("stateChangeSlices", def.stateChangeSlices->Array.map(encodeWritableDef)->JSON.Encode.array),
     ("aggregates", def.aggregates->Array.map(encodeWritableDef)->JSON.Encode.array),
     (

package/src/admin/Platform_ComponentDefinitionsApi.res.mjs

@@ -10,12 +10,12 @@ let sdlTypes = [
   `type Platform_EventDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   `type Platform_ErrorDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   `type Platform_WriteSideDef {\n  name: String!\n  commands: [Platform_CommandDef!]!\n  linkedViews: [String!]!\n  consistencyRead: String\n  producedEventTypes: [String!]!\n  consumedEventTypes: [String!]!\n  events: [Platform_EventDef!]!\n  errors: [Platform_ErrorDef!]!\n  chapter: String\n}`,
-  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n}`,
+  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n  targetName: String\n  chapter: String\n}`,
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_InboundTranslationSliceDef {\n  name: String!\n  commandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_ExtensionDef {\n  name: String!\n  delegateNames: [String!]!\n  eventTypes: [String!]!\n  commandTypes: [String!]!\n}`,
-  `type Platform_ComponentDefinitionEntry {\n  pluginId: String!\n  readModels: [Platform_ReadSideDef!]!\n  stateViewSlices: [Platform_ReadSideDef!]!\n  stateChangeSlices: [Platform_WriteSideDef!]!\n  aggregates: [Platform_WriteSideDef!]!\n  automationSlices: [Platform_AutomationSliceDef!]!\n  outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!\n  inboundTranslationSlices: [Platform_InboundTranslationSliceDef!]!\n  extensions: [Platform_ExtensionDef!]!\n}`
+  `type Platform_ComponentDefinitionEntry {\n  pluginId: String!\n  readModels: [Platform_ReadSideDef!]!\n  stateViewSlices: [Platform_ReadSideDef!]!\n  internalQueryables: [Platform_ReadSideDef!]!\n  stateChangeSlices: [Platform_WriteSideDef!]!\n  aggregates: [Platform_WriteSideDef!]!\n  automationSlices: [Platform_AutomationSliceDef!]!\n  outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!\n  inboundTranslationSlices: [Platform_InboundTranslationSliceDef!]!\n  extensions: [Platform_ExtensionDef!]!\n}`
 ];
 
 function encodeStrings(ss) {
@@ -132,6 +132,18 @@ function encodeQueryableDef(r) {
     [
       "chapter",
       Stdlib_Option.mapOr(r.chapter, null, prim => prim)
+    ],
+    [
+      "singleQueryField",
+      Stdlib_Option.mapOr(r.singleQueryField, null, prim => prim)
+    ],
+    [
+      "idField",
+      Stdlib_Option.mapOr(r.idField, null, prim => prim)
+    ],
+    [
+      "idFieldSource",
+      Stdlib_Option.mapOr(r.idFieldSource, null, prim => prim)
     ]
   ]);
 }
@@ -325,6 +337,10 @@ function encodePluginStructureEntry(pluginId, def) {
       "stateViewSlices",
       def.stateViewSlices.filter(isPublicQueryable).map(encodeQueryableDef)
     ],
+    [
+      "internalQueryables",
+      def.readModels.concat(def.stateViewSlices).filter(q => !Primitive_object.notequal(q.visibility, "Internal")).map(encodeQueryableDef)
+    ],
     [
       "stateChangeSlices",
       def.stateChangeSlices.map(encodeWritableDef)

package/src/components/Api/Api_Ids.res

@@ -0,0 +1,63 @@
+/**
+The one place that knows how a row's GraphQL `id` relates to its storage key.
+
+A read-side row is reachable through several id-accepting doors — the typed
+`X(id: ID!)` query, `XsByIds(ids:)`, the list `filter.ids`, and Relay's
+`node(id:)`. They used to disagree about which form they took, so the obvious
+client call `X(id: row.id)` silently returned `null`: the door took the storage
+key while the row advertised the Relay global id. The rule below is what
+`QueryDbListQuery.passIds` already applied to `filter.ids` — lifted out so every
+door applies it, and so provider adapters share one definition rather than three.
+
+Provider-neutral on purpose: the contract belongs to neither the local platform
+nor AWS.
+*/
+
+@val external btoa: string => string = "btoa"
+@val external atob: string => string = "atob"
+
+/** `btoa("<TypeName>:<localId>")` — the Relay global id for a row. */
+let encode = (~typeName: string, ~localId: string): string => btoa(`${typeName}:${localId}`)
+
+/**
+The `(typeName, localId)` pair inside a global id, or `None` when the string is
+not one. `atob` throws on non-base64 input; a decoded value with no `:` (or a
+leading one, which would mean an empty type name) is not a global id either.
+*/
+let decode = (globalId: string): option<(string, string)> =>
+  try {
+    let decoded = atob(globalId)
+    let idx = decoded->String.indexOf(":")
+    if idx > 0 {
+      Some((
+        decoded->String.slice(~start=0, ~end=idx),
+        decoded->String.slice(~start=idx + 1, ~end=decoded->String.length),
+      ))
+    } else {
+      None
+    }
+  } catch {
+  | _ => None
+  }
+
+/**
+The storage key a global id wraps, or `None` if the string is not one.
+
+Deliberately NOT a `string => string` that "normalises" an id: a raw key that
+happens to be valid base64 would be silently rewritten into something that
+matches nothing. Callers look the raw id up first and fall back to this — see
+`alternateKey`.
+*/
+let toLocalId = (id: string): option<string> => decode(id)->Option.map(((_, localId)) => localId)
+
+/**
+The other key worth trying when a lookup by `id` found nothing: the storage key
+inside it, if it was a global id. Ordering matters — the raw id is always tried
+first, so a key that merely looks like base64 keeps resolving to its own row and
+this only ever runs on a miss.
+*/
+let alternateKey = (id: string): option<string> =>
+  switch toLocalId(id) {
+  | Some(localId) if localId != id => Some(localId)
+  | _ => None
+  }

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

@@ -0,0 +1,43 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+function encode(typeName, localId) {
+  return btoa(typeName + `:` + localId);
+}
+
+function decode(globalId) {
+  try {
+    let decoded = atob(globalId);
+    let idx = decoded.indexOf(":");
+    if (idx > 0) {
+      return [
+        decoded.slice(0, idx),
+        decoded.slice(idx + 1 | 0, decoded.length)
+      ];
+    } else {
+      return;
+    }
+  } catch (exn) {
+    return;
+  }
+}
+
+function toLocalId(id) {
+  return Stdlib_Option.map(decode(id), param => param[1]);
+}
+
+function alternateKey(id) {
+  let localId = toLocalId(id);
+  if (localId !== undefined && localId !== id) {
+    return localId;
+  }
+}
+
+export {
+  encode,
+  decode,
+  toLocalId,
+  alternateKey,
+}
+/* No side effect */

package/src/components/Api/GraphQL_FragmentGenerator.res

@@ -62,10 +62,28 @@ let rec fromSchemaType = (
       collectedTypes->Array.push(`enum ${name} {\n  ${valuesStr}\n}`)
     }
     `${name}${bang}`
-  // GraphQL carries the value's shape, not its meaning: a storage ref is a
-  // String on the wire exactly as it is in the event log. The semantic reaches
-  // the UI through the field's JSON Schema, which is the channel that can
-  // express it.
+  // A semantic composite is one named type rather than one per field that uses
+  // it. The name comes from the semantic rather than the field path, so every
+  // plugin emits a byte-identical definition — which is what lets AppSync union
+  // the copies from each source API back into one, the way it already does for
+  // the `Node` / `PageInfo` / `SortOrder` base types.
+  //
+  // GraphQL forbids one name serving as both an object and an input, so the
+  // input position takes an `Input` suffix. Only these types are suffixed:
+  // positionally-named objects can't collide, since their names already carry
+  // the command or read model they belong to.
+  | Semantic({id}, ObjectRef(name, fields)) if SchemaType.canonicalName(id)->Option.isSome =>
+    let typeName = asInput ? name ++ "Input" : name
+    if !(seenTypes->Set.has(typeName)) {
+      seenTypes->Set.add(typeName)
+      let typeDef = objectRefToGraphQL(~asInput, typeName, fields, collectedTypes, seenTypes)
+      collectedTypes->Array.push(typeDef)
+    }
+    `${typeName}${bang}`
+  // Every other semantic carries the value's shape, not its meaning: a storage
+  // ref is a String on the wire exactly as it is in the event log. The semantic
+  // reaches the UI through the field's JSON Schema, which is the channel that
+  // can express it.
   | Semantic(_, inner) => fromSchemaType(~required, ~asInput, inner, collectedTypes, seenTypes)
   | Unknown => `String${bang}`
   }
@@ -187,30 +205,93 @@ let rec scalarOfSchemaType = (st: SchemaType.schemaType): string =>
   | _ => "String"
   }
 
-let deriveServerCapability = (schema: S.t<unknown>): serverCapability => {
+// A `*Id`-suffixed field name, case-sensitively. Deliberately NOT
+// `SchemaType.isIdFieldName`, which lowercases before testing the suffix and so
+// accepts `paid` and `valid` — harmless where it is used, but here it would
+// nominate an ordinary word as a row's key.
+let isKeyFieldName = (name: string): bool =>
+  name->String.length > 2 && name->String.endsWith("Id")
+
+/**
+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`). A guess, but one that can only fire on a field
+  that is actually there.
+- `"sole"` — the state has exactly one `*Id` field, so there is nothing else it
+  could be (`AvailableProducts` → `productId`).
+
+`None` is the honest answer for a state with several `*Id` fields and no name
+match (`ProductDemand`: `productId` + `categoryId`), or with none at all — those
+need `@id`. Convention outranks sole so a view carrying one foreign key and no
+key of its own is not keyed by the foreign key.
+*/
+let resolveKeyField = (~entityName: string, schema: S.t<unknown>): option<(string, string)> => {
+  let declared = switch Reventless.StateAnnotations.getSpec(schema) {
+  | Some({ids}) => ids->Array.get(0)
+  | None => None
+  }
+  switch declared {
+  | Some(field) => Some((field, "annotation"))
+  | None =>
+    let candidates =
+      SchemaType.fromSuryObject(~typeName="", schema)
+      ->Option.getOr(Dict.make())
+      ->Dict.keysToArray
+      ->Array.filter(isKeyFieldName)
+    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) {
+      Some((conventional, "convention"))
+    } else if candidates->Array.length == 1 {
+      Some((candidates->Array.getUnsafe(0), "sole"))
+    } else {
+      None
+    }
+  }
+}
+
+// The component name the key-field convention is read against. `specName` is the
+// read model's own `Spec.name`; without it, `returnTypeName` minus its plugin
+// prefix is the same string (`Catalog_Product` → `Product`).
+let entityNameOf = (entry: ReventlessInfra.Api.querySchemaEntry): string =>
+  switch entry.specName {
+  | Some(n) => n
+  | None =>
+    switch entry.returnTypeName->String.lastIndexOf("_") {
+    | -1 => entry.returnTypeName
+    | i =>
+      entry.returnTypeName->String.slice(~start=i + 1, ~end=entry.returnTypeName->String.length)
+    }
+  }
+
+let deriveServerCapability = (~entityName: string, schema: S.t<unknown>): serverCapability => {
+  let fieldTypes = SchemaType.fromSuryObject(~typeName="", schema)->Option.getOr(Dict.make())
+  let scalarOf = (fieldName: string): string =>
+    fieldTypes->Dict.get(fieldName)->Option.mapOr("String", scalarOfSchemaType)
+
+  let filterFields: array<filterField> = []
+  let sortFields: array<string> = []
+  let seenFilter: Set.t<string> = Set.make()
+  let seenSort: Set.t<string> = Set.make()
+
+  let pushFilter = (name, ~range) =>
+    if !(seenFilter->Set.has(name)) {
+      seenFilter->Set.add(name)
+      filterFields->Array.push({name, gqlType: scalarOf(name), range})
+    }
+  let pushSort = name =>
+    if !(seenSort->Set.has(name)) {
+      seenSort->Set.add(name)
+      sortFields->Array.push(name)
+    }
+
   switch Reventless.StateAnnotations.getSpec(schema) {
-  | None => emptyCapability
+  | None => ()
   | Some(spec) =>
-    let fieldTypes = SchemaType.fromSuryObject(~typeName="", schema)->Option.getOr(Dict.make())
-    let scalarOf = (fieldName: string): string =>
-      fieldTypes->Dict.get(fieldName)->Option.mapOr("String", scalarOfSchemaType)
-
-    let filterFields: array<filterField> = []
-    let sortFields: array<string> = []
-    let seenFilter: Set.t<string> = Set.make()
-    let seenSort: Set.t<string> = Set.make()
-
-    let pushFilter = (name, ~range) =>
-      if !(seenFilter->Set.has(name)) {
-        seenFilter->Set.add(name)
-        filterFields->Array.push({name, gqlType: scalarOf(name), range})
-      }
-    let pushSort = name =>
-      if !(seenSort->Set.has(name)) {
-        seenSort->Set.add(name)
-        sortFields->Array.push(name)
-      }
-
     spec.ids->Array.forEach(name => {
       pushFilter(name, ~range=false)
       pushSort(name)
@@ -234,9 +315,21 @@ let deriveServerCapability = (schema: S.t<unknown>): serverCapability => {
     // path is needed here.
     spec.scan->Array.forEach(name => pushFilter(name, ~range=false))
     spec.scanSort->Array.forEach(name => pushSort(name))
+  }
 
-    {filterFields, sortFields}
+  // A state that declares nothing structural used to land here with an empty
+  // capability — no per-field filter and no order-by at all, so every narrowing
+  // 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) {
+  | Some((field, _rung)) =>
+    pushFilter(field, ~range=false)
+    pushSort(field)
+  | None => ()
   }
+
+  {filterFields, sortFields}
 }
 
 // Returns one warning per `@scanSort` field that is NOT also a sort key of the
@@ -564,7 +657,7 @@ let generate = (
         deriveConnectionTypes(~singularTypeName=entry.returnTypeName)
         ->Array.forEach(t => types->Array.push(t))
       }
-      let capability = deriveServerCapability(entry.stateSchema)
+      let capability = deriveServerCapability(~entityName=entityNameOf(entry), entry.stateSchema)
       let connectionFilterTypeName = entry.returnTypeName ++ "Filter"
       if !(seenTypes->Set.has(connectionFilterTypeName)) {
         seenTypes->Set.add(connectionFilterTypeName)