@reventlessdev/reventless-spec 3.0.0-alpha.138 → 3.0.0-alpha.140

package/CHANGELOG.md

@@ -3,6 +3,30 @@
 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.140 (2026-09-21)
+
+* feat(spec)!: typed projection keys ([fc6a018](https://github.com/ReventlessDev/reventless-core/commit/fc6a01811ba788f3289e84a435a09f77fa627e1a))
+### Features
+
+* **core:** references derived from identities, and identity checks ([7cb1376](https://github.com/ReventlessDev/reventless-core/commit/7cb1376e56cdb4e4d5ab5954cd97fd37fd3ba258))
+
+### BREAKING CHANGES
+
+* a projection that keys a row by a payload `string`, or uses
+the envelope id as a `string`, converts explicitly with
+`Target.Id.makeFromString` / `Source.Id.toString`. `StateChangeSlice.Spec` no
+longer requires `module Id`.
+
+
+
+# 3.0.0-alpha.139 (2026-09-21)
+
+### 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.138 (2026-09-20)
 
 * fix(spec)!: let an explicit partition tag declare an identity the name cannot ([01d82c0](https://github.com/ReventlessDev/reventless-core/commit/01d82c0714a31f31d55c466eae9100cf4dcc85f0))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.138",
+  "version": "3.0.0-alpha.140",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/components/DcbScopeInference.res

@@ -49,7 +49,13 @@ The three rules (over the representation):
     It is carried rather than folded in because removing the annotation removes
     the identity, which is exactly what the redundancy check has to know: a hint
     inference cannot reach without it is never redundant. */
-type idField = {name: string, isList: bool, byTag?: bool}
+type idField = {
+  name: string,
+  isList: bool,
+  byTag?: bool,
+  /** The tag key, when the field's type says it (an identity) rather than its name. */
+  key?: string,
+}
 
 /** One variant arm: its constructor name and the `*Id` fields it carries. */
 type eventShape = {eventType: string, idFields: array<idField>}
@@ -97,10 +103,13 @@ type derived = {
 /**
 The tag key for a `*Id`-shaped field. A plural `*Ids: array<string>` shares the
 singular producer's key (trailing `s` stripped — `productIds` -> `productId`);
-a scalar `*Id` uses the field name verbatim. Mirrors the PPX's `*Ids` rule.
+a scalar `*Id` uses the field name verbatim. Mirrors the PPX's `*Ids` rule. An
+identity-typed field carries its key, whatever it is called.
 */
 let tagKeyOf = (f: idField): string =>
-  if f.isList && f.name->String.endsWith("s") {
+  if f.key->Option.isSome {
+    f.key->Option.getUnsafe
+  } else if f.isList && f.name->String.endsWith("s") {
     f.name->String.slice(~start=0, ~end=f.name->String.length - 1)
   } else {
     f.name

package/src/components/DcbScopeInference.res.mjs

@@ -6,7 +6,9 @@ import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 
 function tagKeyOf(f) {
-  if (f.isList && f.name.endsWith("s")) {
+  if (Stdlib_Option.isSome(f.key)) {
+    return f.key;
+  } else if (f.isList && f.name.endsWith("s")) {
     return f.name.slice(0, f.name.length - 1 | 0);
   } else {
     return f.name;

package/src/components/DcbTag.res

@@ -126,6 +126,23 @@ let dcbTagKeyOverrideId: S.Metadata.Id.t<string> = S.Metadata.Id.make(
   ~name="tagKeyOverride",
 )
 
+/**
+Type-preserving forms of the markers below, for a field whose schema is not a
+bare `S.string` — an identity (`OrderId.schema->DcbTag.mark`) keeps its type and
+its semantic, and the tag key follows the identity unless `markForKey` says
+otherwise.
+*/
+let mark = (schema: S.t<'a>): S.t<'a> => schema->S.Metadata.set(~id=dcbTagId, true)
+
+let markForKey = (schema: S.t<'a>, ~key: string): S.t<'a> =>
+  schema->mark->S.Metadata.set(~id=dcbTagKeyOverrideId, key)
+
+let markPartition = (schema: S.t<'a>): S.t<'a> =>
+  schema->mark->S.Metadata.set(~id=dcbPartitionTagId, true)
+
+let markCrossPartition = (schema: S.t<'a>): S.t<'a> =>
+  schema->mark->S.Metadata.set(~id=dcbCrossPartitionId, true)
+
 /**
 A sury string schema annotated as a DCB tag field.
 
@@ -148,7 +165,7 @@ and array element types.
 ```
 */
 let string: S.t<string> =
-  S.string->S.Metadata.set(~id=dcbTagId, true)
+  S.string->mark
 
 /**
 A sury string schema annotated as a DCB tag field with an explicit tag-key override.
@@ -171,8 +188,7 @@ annotations carrying a string payload.
 // productIds: ["p1", "p2"] → tags [{key: "productId", value: "p1"}, {key: "productId", value: "p2"}]
 ```
 */
-let stringForKey = (~key: string): S.t<string> =>
-  S.string->S.Metadata.set(~id=dcbTagId, true)->S.Metadata.set(~id=dcbTagKeyOverrideId, key)
+let stringForKey = (~key: string): S.t<string> => S.string->markForKey(~key)
 
 /**
 A sury int schema annotated as a DCB tag field.
@@ -198,7 +214,7 @@ optional (auto-selected) when only one tagged field exists.
 ```
 */
 let partition: S.t<string> =
-  S.string->S.Metadata.set(~id=dcbTagId, true)->S.Metadata.set(~id=dcbPartitionTagId, true)
+  S.string->markPartition
 
 /**
 A sury string schema annotated as a DCB tag field with *cross-partition* read
@@ -224,7 +240,7 @@ entities but can be partitioned by only one (course-subscription capacity,
 ```
 */
 let crossPartition: S.t<string> =
-  S.string->S.Metadata.set(~id=dcbTagId, true)->S.Metadata.set(~id=dcbCrossPartitionId, true)
+  S.string->markCrossPartition
 
 /**
 A sury string schema marking a field as a composite partition key member.
@@ -355,19 +371,21 @@ let isCrossPartitionTaggedArray = (fieldSchema: S.t<unknown>) =>
 
 /**
 Resolves the tag key for a scalar tagged field: the explicit override metadata if
-present, otherwise the field name.
+present, else the field's identity, otherwise the field name.
 */
 let resolveTagKey = (fieldName: string, fieldSchema: S.t<unknown>): string =>
-  S.Metadata.get(fieldSchema, ~id=dcbTagKeyOverrideId)->Option.getOr(fieldName)
+  switch S.Metadata.get(fieldSchema, ~id=dcbTagKeyOverrideId) {
+  | Some(key) => key
+  | None => fieldSchema->Semantic.identityKey->Option.getOr(fieldName)
+  }
 
 /**
-Resolves the tag key for an array tagged field. The override metadata sits on the
-inner element schema; falls back to the field name when no override is set.
+Resolves the tag key for an array tagged field. The override metadata and the
+identity sit on the inner element schema; falls back to the field name.
 */
 let resolveArrayTagKey = (fieldName: string, fieldSchema: S.t<unknown>): string =>
   switch fieldSchema {
-  | Array({additionalItems: Schema(itemSchema)}) =>
-    S.Metadata.get(itemSchema, ~id=dcbTagKeyOverrideId)->Option.getOr(fieldName)
+  | Array({additionalItems: Schema(itemSchema)}) => resolveTagKey(fieldName, itemSchema)
   | _ => fieldName
   }
 
@@ -970,51 +988,33 @@ let buildQueryFromCommand = (
 // --- Extract tagged field names from event schema ---
 
 /**
-Extracts the names of all DCB-tagged fields across all variants of an event schema.
-
-Returns a sorted, deduplicated list of field names annotated with
-`@s.matches(DcbTag.string)` or `@s.matches(DcbTag.int)`.
+The tag keys of all DCB-tagged fields across all variants of an event schema,
+resolved as the tags themselves are, so an index is named after the key its tags
+carry. Sorted and deduplicated.
 
 For `CatalogEventLog.event` returns `["categoryId", "productId"]`.
 */
 let extractTaggedFields = (schema: S.t<'event>): array<string> => {
-  switch schema->toUnknownSchema {
-  | AnyOf({anyOf}) =>
-    // For union types, collect tagged fields from all variants
-    let allFields = anyOf->Array.flatMap(variantSchema =>
-      switch variantSchema {
-      | Object({properties}) =>
-        properties
-        ->Dict.toArray
-        ->Array.filterMap(((fieldName, fieldSchema)) =>
-          if isTagged(fieldSchema) {
-            Some(fieldName)
-          } else {
-            None
-          }
-        )
-      | _ => []
-      }
-    )
-    // Deduplicate field names using Set
-    let fieldSet = Set.make()
-    allFields->Array.forEach(field => fieldSet->Set.add(field))
-    Array.fromIterator(fieldSet->Set.values)->Array.toSorted((a, b) => String.compare(a, b))
-
-  | Object({properties}) =>
+  let ofProperties = properties =>
     properties
     ->Dict.toArray
     ->Array.filterMap(((fieldName, fieldSchema)) =>
-      if isTagged(fieldSchema) {
-        Some(fieldName)
-      } else {
-        None
+      isTagged(fieldSchema) ? Some(resolveTagKey(fieldName, fieldSchema)) : None
+    )
+  let keys = switch schema->toUnknownSchema {
+  | AnyOf({anyOf}) =>
+    anyOf->Array.flatMap(variantSchema =>
+      switch variantSchema {
+      | Object({properties}) => ofProperties(properties)
+      | _ => []
       }
     )
-    ->Array.toSorted((a, b) => String.compare(a, b))
-
+  | Object({properties}) => ofProperties(properties)
   | _ => []
   }
+  let seen = Set.make()
+  keys->Array.forEach(k => seen->Set.add(k))
+  Array.fromIterator(seen->Set.values)->Array.toSorted((a, b) => String.compare(a, b))
 }
 
 /**
@@ -1091,7 +1091,16 @@ let idFieldsOfProperties = (properties: dict<S.t<unknown>>): array<DcbScopeInfer
   // for every field except the ones that need it. Flagged, not folded in: taking
   // the annotation away takes the identity with it, which is what the redundancy
   // check has to be able to tell.
-  let identity = (name, fieldSchema, isList) =>
+  // A field's type outranks its name: `buyer: CustomerId.t` is keyed `customerId`,
+  // and so is `orderId: CustomerId.t`. An explicit `@dcbTag("k")` still wins.
+  let typedKey = (fieldSchema: S.t<unknown>, isList) => {
+    let valueSchema = switch (isList, fieldSchema) {
+    | (true, Array({additionalItems: Schema(item)})) => item
+    | _ => fieldSchema
+    }
+    valueSchema->Semantic.identityKey->Option.map(_ => resolveTagKey("", valueSchema))
+  }
+  let untypedIdentity = (name, fieldSchema, isList) =>
     if isIdName(name) {
       Some({DcbScopeInference.name, isList})
     } else if isPartitionTag(fieldSchema) {
@@ -1099,6 +1108,11 @@ let idFieldsOfProperties = (properties: dict<S.t<unknown>>): array<DcbScopeInfer
     } else {
       None
     }
+  let identity = (name, fieldSchema, isList) =>
+    switch typedKey(fieldSchema, isList) {
+    | Some(key) => Some({DcbScopeInference.name, isList, key})
+    | None => untypedIdentity(name, fieldSchema, isList)
+    }
   properties
   ->Dict.toArray
   ->Array.flatMap(((name, fieldSchema)) => {
@@ -1148,7 +1162,8 @@ let eventShapesOfSchema = (schema: S.t<'a>): array<DcbScopeInference.eventShape>
 // --- Partition tag derivation ---
 
 /**
-Extracts field names annotated with `@s.matches(DcbTag.partition)` from an event schema.
+Extracts the tag keys of fields annotated with `@s.matches(DcbTag.partition)` from an
+event schema: the field name, unless an override or an identity says otherwise.
 */
 let extractPartitionTagFields = (schema: S.t<'event>): array<string> => {
   switch schema->toUnknownSchema {
@@ -1160,7 +1175,7 @@ let extractPartitionTagFields = (schema: S.t<'event>): array<string> => {
         ->Dict.toArray
         ->Array.filterMap(((fieldName, fieldSchema)) =>
           if isPartitionTag(fieldSchema) {
-            Some(fieldName)
+            Some(resolveTagKey(fieldName, fieldSchema))
           } else {
             None
           }
@@ -1177,7 +1192,7 @@ let extractPartitionTagFields = (schema: S.t<'event>): array<string> => {
     ->Dict.toArray
     ->Array.filterMap(((fieldName, fieldSchema)) =>
       if isPartitionTag(fieldSchema) {
-        Some(fieldName)
+        Some(resolveTagKey(fieldName, fieldSchema))
       } else {
         None
       }

package/src/components/DcbTag.res.mjs

@@ -32,17 +32,33 @@ let dcbCompositePartitionMemberId = Sury.$Metadata_Id_make("dcb", "compositePart
 
 let dcbTagKeyOverrideId = Sury.$Metadata_Id_make("dcb", "tagKeyOverride");
 
+function mark(schema) {
+  return Sury.$Metadata_set(schema, dcbTagId, true);
+}
+
+function markForKey(schema, key) {
+  return Sury.$Metadata_set(Sury.$Metadata_set(schema, dcbTagId, true), dcbTagKeyOverrideId, key);
+}
+
+function markPartition(schema) {
+  return Sury.$Metadata_set(Sury.$Metadata_set(schema, dcbTagId, true), dcbPartitionTagId, true);
+}
+
+function markCrossPartition(schema) {
+  return Sury.$Metadata_set(Sury.$Metadata_set(schema, dcbTagId, true), dcbCrossPartitionId, true);
+}
+
 let string = Sury.$Metadata_set(Sury.string, dcbTagId, true);
 
 function stringForKey(key) {
-  return Sury.$Metadata_set(Sury.$Metadata_set(Sury.string, dcbTagId, true), dcbTagKeyOverrideId, key);
+  return markForKey(Sury.string, key);
 }
 
 let int = Sury.$Metadata_set(Sury.int, dcbTagId, true);
 
-let partition = Sury.$Metadata_set(Sury.$Metadata_set(Sury.string, dcbTagId, true), dcbPartitionTagId, true);
+let partition = markPartition(Sury.string);
 
-let crossPartition = Sury.$Metadata_set(Sury.$Metadata_set(Sury.string, dcbTagId, true), dcbCrossPartitionId, true);
+let crossPartition = markCrossPartition(Sury.string);
 
 function compositePartitionMember(position, sepOpt) {
   let sep = sepOpt !== undefined ? sepOpt : "/";
@@ -169,7 +185,12 @@ function isCrossPartitionTaggedArray(fieldSchema) {
 }
 
 function resolveTagKey(fieldName, fieldSchema) {
-  return Stdlib_Option.getOr(Sury.$Metadata_get(fieldSchema, dcbTagKeyOverrideId), fieldName);
+  let key = Sury.$Metadata_get(fieldSchema, dcbTagKeyOverrideId);
+  if (key !== undefined) {
+    return key;
+  } else {
+    return Stdlib_Option.getOr(Semantic$Reventless.identityKey(fieldSchema), fieldName);
+  }
 }
 
 function resolveArrayTagKey(fieldName, fieldSchema) {
@@ -180,7 +201,7 @@ function resolveArrayTagKey(fieldName, fieldSchema) {
   if (itemSchema === "strip" || itemSchema === "strict") {
     return fieldName;
   } else {
-    return Stdlib_Option.getOr(Sury.$Metadata_get(itemSchema, dcbTagKeyOverrideId), fieldName);
+    return resolveTagKey(fieldName, itemSchema);
   }
 }
 
@@ -627,33 +648,34 @@ function buildQueryFromCommand(eventTypes, schema, value, tagKeysByEventTypeOpt,
 }
 
 function extractTaggedFields(schema) {
+  let ofProperties = properties => Stdlib_Array.filterMap(Object.entries(properties), param => {
+    let fieldSchema = param[1];
+    if (Stdlib_Option.isSome(Sury.$Metadata_get(fieldSchema, dcbTagId))) {
+      return resolveTagKey(param[0], fieldSchema);
+    }
+  });
+  let keys;
   switch (schema.type) {
     case "object" :
-      return Stdlib_Array.filterMap(Object.entries(schema.properties), param => {
-        if (Stdlib_Option.isSome(Sury.$Metadata_get(param[1], dcbTagId))) {
-          return param[0];
-        }
-      }).toSorted(Primitive_string.compare);
+      keys = ofProperties(schema.properties);
+      break;
     case "anyOf" :
-      let allFields = schema.anyOf.flatMap(variantSchema => {
+      keys = schema.anyOf.flatMap(variantSchema => {
         if (variantSchema.type === "object") {
-          return Stdlib_Array.filterMap(Object.entries(variantSchema.properties), param => {
-            if (Stdlib_Option.isSome(Sury.$Metadata_get(param[1], dcbTagId))) {
-              return param[0];
-            }
-          });
+          return ofProperties(variantSchema.properties);
         } else {
           return [];
         }
       });
-      let fieldSet = new Set();
-      allFields.forEach(field => {
-        fieldSet.add(field);
-      });
-      return Array.from(fieldSet.values()).toSorted(Primitive_string.compare);
+      break;
     default:
-      return [];
+      keys = [];
   }
+  let seen = new Set();
+  keys.forEach(k => {
+    seen.add(k);
+  });
+  return Array.from(seen.values()).toSorted(Primitive_string.compare);
 }
 
 function crossPartitionKeysOfProperties(properties) {
@@ -703,8 +725,25 @@ function idFieldsOfProperties(properties) {
       return name.endsWith("Id");
     }
   };
+  let typedKey = (fieldSchema, isList) => {
+    let valueSchema;
+    if (isList && fieldSchema.type === "array") {
+      let item = fieldSchema.additionalItems;
+      valueSchema = item === "strip" || item === "strict" ? fieldSchema : item;
+    } else {
+      valueSchema = fieldSchema;
+    }
+    return Stdlib_Option.map(Semantic$Reventless.identityKey(valueSchema), param => resolveTagKey("", valueSchema));
+  };
   let identity = (name, fieldSchema, isList) => {
-    if (isIdName(name)) {
+    let key = typedKey(fieldSchema, isList);
+    if (key !== undefined) {
+      return {
+        name: name,
+        isList: isList,
+        key: key
+      };
+    } else if (isIdName(name)) {
       return {
         name: name,
         isList: isList
@@ -773,16 +812,18 @@ function extractPartitionTagFields(schema) {
   switch (schema.type) {
     case "object" :
       return Stdlib_Array.filterMap(Object.entries(schema.properties), param => {
-        if (Stdlib_Option.isSome(Sury.$Metadata_get(param[1], dcbPartitionTagId))) {
-          return param[0];
+        let fieldSchema = param[1];
+        if (Stdlib_Option.isSome(Sury.$Metadata_get(fieldSchema, dcbPartitionTagId))) {
+          return resolveTagKey(param[0], fieldSchema);
         }
       });
     case "anyOf" :
       let allFields = schema.anyOf.flatMap(variantSchema => {
         if (variantSchema.type === "object") {
           return Stdlib_Array.filterMap(Object.entries(variantSchema.properties), param => {
-            if (Stdlib_Option.isSome(Sury.$Metadata_get(param[1], dcbPartitionTagId))) {
-              return param[0];
+            let fieldSchema = param[1];
+            if (Stdlib_Option.isSome(Sury.$Metadata_get(fieldSchema, dcbPartitionTagId))) {
+              return resolveTagKey(param[0], fieldSchema);
             }
           });
         } else {
@@ -1043,6 +1084,10 @@ export {
   dcbCrossPartitionId,
   dcbCompositePartitionMemberId,
   dcbTagKeyOverrideId,
+  mark,
+  markForKey,
+  markPartition,
+  markCrossPartition,
   string,
   stringForKey,
   int,

package/src/components/IdentityCheck.res

@@ -0,0 +1,110 @@
+/**
+Where a plugin's ids and their types disagree. Needs the whole plugin, not one
+file: whether `orderId` names an identity depends on whether any field is typed
+`OrderId.t`, which is also what makes adoption opt-in per plugin — a plugin that
+types nothing is never reported.
+
+- **A field named for one identity and typed as another** (`orderId: CustomerId.t`):
+  the mix-up the types exist to catch. A role name that is no identity of its own
+  (`sellerId: CustomerId.t`) is fine.
+- **An untyped `*Id` whose key has an identity** (`productId: string` beside a
+  `ProductId.t`): the half-migrated state, where the compiler guards some uses and
+  not others.
+*/
+type finding = {sliceName: string, message: string}
+
+// The identity key a `*Id` / `*Ids` name gives by convention.
+let nameKey = (name: string): option<string> =>
+  if name->String.endsWith("Ids") {
+    Some(name->String.slice(~start=0, ~end=name->String.length - 1))
+  } else if name->String.length > 2 && name->String.endsWith("Id") {
+    Some(name)
+  } else {
+    None
+  }
+
+let fieldsOf = (schema: S.t<unknown>): array<(string, S.t<unknown>)> => {
+  let ofObject = (v: S.t<unknown>) =>
+    switch v {
+    | Object({properties}) => properties->Dict.toArray->Array.filter(((n, _)) => n != "TAG")
+    | _ => []
+    }
+  switch schema {
+  | AnyOf({anyOf}) => anyOf->Array.flatMap(ofObject)
+  | other => ofObject(other)
+  }
+}
+
+let slicesFields = (slice: DcbTag.sliceSchemas) =>
+  [slice.commandSchema, slice.consumedEventSchema, slice.eventSchema]->Array.flatMap(fieldsOf)
+
+let check = (slices: array<DcbTag.sliceSchemas>): array<finding> => {
+  let declared: Set.t<string> = Set.make()
+  slices->Array.forEach(slice =>
+    slice
+    ->slicesFields
+    ->Array.forEach(((_, schema)) =>
+      Semantic.fieldIdentityKey(schema)->Option.forEach(k => declared->Set.add(k))
+    )
+  )
+  let seen: Set.t<string> = Set.make()
+  let findings = []
+  slices->Array.forEach(slice =>
+    slice
+    ->slicesFields
+    ->Array.forEach(((name, schema)) => {
+      let message = switch (Semantic.fieldIdentityKey(schema), nameKey(name)) {
+      | (Some(key), Some(named)) if named != key && declared->Set.has(named) =>
+        Some(
+          `${name} is typed as a ${key}, but ${named} is an identity of its own in this plugin. Type it as ${named}'s identity, or rename the field.`,
+        )
+      | (None, Some(named)) if declared->Set.has(named) =>
+        Some(
+          `${name} is a plain string, but ${named} has an identity in this plugin. Type the field with it, so the compiler guards every use.`,
+        )
+      | _ => None
+      }
+      message->Option.forEach(
+        message => {
+          let id = slice.name ++ "\n" ++ message
+          if !(seen->Set.has(id)) {
+            seen->Set.add(id)
+            findings->Array.push({sliceName: slice.name, message})
+          }
+        },
+      )
+    })
+  )
+  findings
+}
+
+/**
+A slice partitioned by an identity another chapter declares: `categoryId`
+partitioning a slice under `Product/`. The chapter is the default home of the
+identity its slices decide about, so the two disagreeing usually means the slice
+or the identity is in the wrong folder. `identityChapters` maps a key to the
+chapter whose folder declares it; an identity declared in another package has
+none and is not checked.
+*/
+let checkChapters = (
+  ~identityChapters: dict<string>,
+  ~partitionBySlice: dict<string>,
+  slices: array<DcbTag.sliceSchemas>,
+): array<finding> =>
+  slices->Array.filterMap(slice =>
+    switch (
+      partitionBySlice->Dict.get(slice.name),
+      slice.moduleUrl->Option.flatMap(DcbTag.chapterOfModuleUrl),
+    ) {
+    | (Some(key), Some(chapter)) =>
+      switch identityChapters->Dict.get(key) {
+      | Some(home) if home != chapter =>
+        Some({
+          sliceName: slice.name,
+          message: `is partitioned by ${key}, which ${home}/ declares, but sits in ${chapter}/. Move the slice or the identity so they share a chapter.`,
+        })
+      | _ => None
+      }
+    | _ => None
+    }
+  )

package/src/components/IdentityCheck.res.mjs

@@ -0,0 +1,103 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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 "./DcbTag.res.mjs";
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
+
+function nameKey(name) {
+  if (name.endsWith("Ids")) {
+    return name.slice(0, name.length - 1 | 0);
+  } else if (name.length > 2 && name.endsWith("Id")) {
+    return name;
+  } else {
+    return;
+  }
+}
+
+function fieldsOf(schema) {
+  let ofObject = v => {
+    if (v.type === "object") {
+      return Object.entries(v.properties).filter(param => param[0] !== "TAG");
+    } else {
+      return [];
+    }
+  };
+  if (schema.type === "anyOf") {
+    return schema.anyOf.flatMap(ofObject);
+  } else {
+    return ofObject(schema);
+  }
+}
+
+function slicesFields(slice) {
+  return [
+    slice.commandSchema,
+    slice.consumedEventSchema,
+    slice.eventSchema
+  ].flatMap(fieldsOf);
+}
+
+function check(slices) {
+  let declared = new Set();
+  slices.forEach(slice => {
+    slicesFields(slice).forEach(param => Stdlib_Option.forEach(Semantic$Reventless.fieldIdentityKey(param[1]), k => {
+      declared.add(k);
+    }));
+  });
+  let seen = new Set();
+  let findings = [];
+  slices.forEach(slice => {
+    slicesFields(slice).forEach(param => {
+      let name = param[0];
+      let match = Semantic$Reventless.fieldIdentityKey(param[1]);
+      let match$1 = nameKey(name);
+      let message = match !== undefined ? (
+          match$1 !== undefined && match$1 !== match && declared.has(match$1) ? name + ` is typed as a ` + match + `, but ` + match$1 + ` is an identity of its own in this plugin. Type it as ` + match$1 + `'s identity, or rename the field.` : undefined
+        ) : (
+          match$1 !== undefined && declared.has(match$1) ? name + ` is a plain string, but ` + match$1 + ` has an identity in this plugin. Type the field with it, so the compiler guards every use.` : undefined
+        );
+      Stdlib_Option.forEach(message, message => {
+        let id = slice.name + "\n" + message;
+        if (!seen.has(id)) {
+          seen.add(id);
+          findings.push({
+            sliceName: slice.name,
+            message: message
+          });
+          return;
+        }
+      });
+    });
+  });
+  return findings;
+}
+
+function checkChapters(identityChapters, partitionBySlice, slices) {
+  return Stdlib_Array.filterMap(slices, slice => {
+    let match = partitionBySlice[slice.name];
+    let match$1 = Stdlib_Option.flatMap(slice.moduleUrl, DcbTag$Reventless.chapterOfModuleUrl);
+    if (match === undefined) {
+      return;
+    }
+    if (match$1 === undefined) {
+      return;
+    }
+    let home = identityChapters[match];
+    if (home !== undefined && home !== match$1) {
+      return {
+        sliceName: slice.name,
+        message: `is partitioned by ` + match + `, which ` + home + `/ declares, but sits in ` + match$1 + `/. Move the slice or the identity so they share a chapter.`
+      };
+    }
+  });
+}
+
+export {
+  nameKey,
+  fieldsOf,
+  slicesFields,
+  check,
+  checkChapters,
+}
+/* DcbTag-Reventless Not a pure module */

package/src/components/Reference.res

@@ -39,6 +39,32 @@ let to_ = (~plugin=?, ~key=?, entity: string): S.t<string> => {
   }
 }
 
+/**
+`to_` for a field whose schema is not a bare `S.string`: the schema keeps its
+type, and an identity it carries moves onto the reference's target rather than
+being overwritten.
+*/
+let mark = (schema: S.t<'a>, ~plugin=?, ~key=?, entity: string): S.t<'a> => {
+  let identity = Semantic.identityKey(schema)
+  let base =
+    schema
+    ->S.Metadata.set(~id=DcbTag.dcbTagId, true)
+    ->Semantic.mark(~id=Semantic.Id.reference, ~payload=ReferenceTo({entity, plugin, ?identity}))
+  switch key {
+  | Some(k) => base->S.Metadata.set(~id=DcbTag.dcbTagKeyOverrideId, k)
+  | None => base
+  }
+}
+
+/** `toWithoutDcbTag` for a field whose schema is not a bare `S.string`. */
+let markWithoutDcbTag = (schema: S.t<'a>, ~plugin=?, entity: string): S.t<'a> => {
+  let identity = Semantic.identityKey(schema)
+  schema->Semantic.mark(
+    ~id=Semantic.Id.reference,
+    ~payload=ReferenceTo({entity, plugin, ?identity}),
+  )
+}
+
 /** Returns the reference target if the schema carries `Reference.to_(...)` metadata. */
 let getTarget = (schema: S.t<unknown>): option<target> =>
   switch Semantic.get(schema) {

package/src/components/Reference.res.mjs

@@ -21,6 +21,35 @@ function to_(plugin, key, entity) {
   }
 }
 
+function mark(schema, plugin, key, entity) {
+  let identity = Semantic$Reventless.identityKey(schema);
+  let base = Semantic$Reventless.mark(Sury.$Metadata_set(schema, DcbTag$Reventless.dcbTagId, true), Semantic$Reventless.Id.reference, {
+    TAG: "ReferenceTo",
+    _0: {
+      entity: entity,
+      plugin: plugin,
+      identity: identity
+    }
+  });
+  if (key !== undefined) {
+    return Sury.$Metadata_set(base, DcbTag$Reventless.dcbTagKeyOverrideId, key);
+  } else {
+    return base;
+  }
+}
+
+function markWithoutDcbTag(schema, plugin, entity) {
+  let identity = Semantic$Reventless.identityKey(schema);
+  return Semantic$Reventless.mark(schema, Semantic$Reventless.Id.reference, {
+    TAG: "ReferenceTo",
+    _0: {
+      entity: entity,
+      plugin: plugin,
+      identity: identity
+    }
+  });
+}
+
 function getTarget(schema) {
   let match = Semantic$Reventless.get(schema);
   if (match === undefined) {
@@ -92,6 +121,8 @@ function toWithoutDcbTag(plugin, entity) {
 
 export {
   to_,
+  mark,
+  markWithoutDcbTag,
   getTarget,
   getFieldTarget,
   collectFieldTargets,

package/src/components/StateChangeSlice.res

@@ -42,17 +42,15 @@ let decide = (state, command) => switch command {
 ```
 */
 /**
-The lean Spec for a StateChangeSlice — types, identity, schemas. State and
-state-evolution functions live in the sibling `Behavior` module type.
+The lean Spec for a StateChangeSlice — types and schemas. State and
+state-evolution functions live in the sibling `Behavior` module type. A slice has
+no identity of its own: it decides about the one its partition field carries.
 */
 module type Spec = {
   /** Logical name of this slice (used as a command topic prefix). */
   let name: string
   let moduleUrl: string
 
-  /** Identity type — always `Id.String` for DCB slices. */
-  module Id: Id.T
-
   /**
   Events this slice reads to build its decision model (in `evolve`).
   Only needs the fields required for the decision — no tag annotations needed.

package/src/components/StateViewSlice.res

@@ -51,6 +51,14 @@ module type Spec = {
   /** Sury schema for the state type — generated automatically by `@schema`. */
   let stateSchema: S.t<state>
 
+  /**
+  What a row is keyed by. `Id.StringPure` (a plain `string`) unless the view
+  declares its identity — `module Key = OrderId` — in which case a projection
+  that keys a row by another entity's id does not compile. Auto-injected by
+  `@@reventless.spec` in a `StateView/` folder.
+  */
+  module Key: Id.T
+
   /**
   Events this view slice projects. Only needs the fields required for the projection —
   no tag annotations needed. May be payload-less where only existence matters.
@@ -114,7 +122,7 @@ module type Projection = {
   Receives the event wrapped in a `consumed` envelope (event + `meta` +
   `recordedAt`); only events declared in `Spec.consumedEvent` — no wildcard needed.
   */
-  let project: consumed<Spec.consumedEvent> => array<Projection.action<string, Spec.state>>
+  let project: consumed<Spec.consumedEvent> => array<Projection.action<Spec.Key.t, Spec.state>>
 
   /** File URL of this Projection module (`import.meta.url`). */
   let moduleUrl: string

package/src/semantic/Semantic.res

@@ -10,7 +10,7 @@ The payload is a typed variant because the vocabulary is framework-owned and
 closed — which also keeps `Reference.getTarget` total.
 */
 /** Which entity a reference field points to. */
-type referenceTarget = {entity: string, plugin: option<string>}
+type referenceTarget = {entity: string, plugin: option<string>, identity?: string}
 
 /** Which object store the value lives in. `plugin` is absent for the declaring
     plugin's own store; `threshold` is `@offload`'s per-field byte cut, `None`
@@ -50,6 +50,8 @@ type payload =
   | ReferenceTo(referenceTarget)
   | StoredIn(storeTarget)
   | MemberOf(memberTarget)
+  /** Which identity an id is: named by its key (`orderId`). */
+  | IdentityOf({key: string})
 
 /** A field's semantic: the vocabulary id, plus its detail. */
 type t = {id: string, payload: payload}
@@ -111,6 +113,10 @@ module Id = {
   // The first composite that is a union rather than an object. Collapses fields,
   // so adopting it changes the wire and rebuilds a derived view.
   let geolocation = "geolocation"
+
+  // Which entity an id names, carried by the type `Id.Make` produces. A string on
+  // the wire, so adopting one changes nothing stored.
+  let identity = "identity"
 }
 
 /** One transparent-string semantic: a `semantic/` module whose `type t` is a
@@ -242,6 +248,27 @@ let rec getFrom = (schema: S.t<unknown>): option<t> =>
 
 let get = (fieldSchema: S.t<'a>): option<t> => fieldSchema->S.castToUnknown->getFrom
 
+/** The identity a field's value is (`orderId`), read through `option<…>`. A
+    reference to an identity carries it on its target, since a schema holds one
+    semantic. */
+let identityKey = (fieldSchema: S.t<'a>): option<string> =>
+  switch get(fieldSchema) {
+  | Some({payload: IdentityOf({key})}) => Some(key)
+  | Some({payload: ReferenceTo({?identity})}) => identity
+  | _ => None
+  }
+
+/** The identity a field names, on its own value or on an array's elements. */
+let rec fieldIdentityKey = (fieldSchema: S.t<unknown>): option<string> =>
+  switch identityKey(fieldSchema) {
+  | Some(_) as found => found
+  | None =>
+    switch fieldSchema->unwrapOptional->Option.getOr(fieldSchema) {
+    | Array({additionalItems: Schema(item)}) => fieldIdentityKey(item)
+    | _ => None
+    }
+  }
+
 /** Whether a field's schema carries this specific semantic. */
 let has = (fieldSchema: S.t<'a>, ~id: string): bool =>
   switch get(fieldSchema) {

package/src/semantic/Semantic.res.mjs

@@ -51,7 +51,8 @@ let Id = {
   dateRange: "dateRange",
   geoPoint: "geoPoint",
   lifecycleTrail: "lifecycleTrail",
-  geolocation: "geolocation"
+  geolocation: "geolocation",
+  identity: "identity"
 };
 
 let brandedStrings = [
@@ -205,6 +206,45 @@ function getFrom(schema) {
 
 let get = getFrom;
 
+function identityKey(fieldSchema) {
+  let match = getFrom(fieldSchema);
+  if (match === undefined) {
+    return;
+  }
+  let match$1 = match.payload;
+  if (typeof match$1 !== "object") {
+    return;
+  }
+  switch (match$1.TAG) {
+    case "ReferenceTo" :
+      return match$1._0.identity;
+    case "IdentityOf" :
+      return match$1.key;
+    default:
+      return;
+  }
+}
+
+function fieldIdentityKey(_fieldSchema) {
+  while (true) {
+    let fieldSchema = _fieldSchema;
+    let found = identityKey(fieldSchema);
+    if (found !== undefined) {
+      return found;
+    }
+    let match = Stdlib_Option.getOr(unwrapOptional(fieldSchema), fieldSchema);
+    if (match.type !== "array") {
+      return;
+    }
+    let item = match.additionalItems;
+    if (item === "strip" || item === "strict") {
+      return;
+    }
+    _fieldSchema = item;
+    continue;
+  };
+}
+
 function has(fieldSchema, id) {
   let s = getFrom(fieldSchema);
   if (s !== undefined) {
@@ -225,6 +265,8 @@ export {
   unionVariant,
   getFrom,
   get,
+  identityKey,
+  fieldIdentityKey,
   has,
 }
 /* semanticId Not a pure module */

package/src/types/Id.res

@@ -2,8 +2,9 @@
 Module type for aggregate and read model identifiers.
 
 Every Reventless component declares its own `Id` module satisfying this type.
-The abstract `type t` prevents accidentally mixing identifiers from different
-aggregates at compile time.
+The abstract `type t` keeps ids apart from plain strings, but not from each
+other: every alias of `Id.String` (which is what the ppx injects) is the same
+type. Only `Id.Make` gives an entity an id type of its own.
 
 @example
 ```rescript
@@ -62,8 +63,9 @@ module StringPure = {
 /**
 A sealed string-based `Id.T` implementation for use in production aggregate specs.
 
-Unlike `StringPure`, the `t` type is abstract, preventing accidental cross-aggregate
-ID mixing. Use `Id.StringPure` in tests when string literals are needed.
+Unlike `StringPure`, the `t` type is abstract, so an id is not a plain string. It is
+sealed once, so every alias shares one type; use `Id.Make` for an id type per
+entity. Use `Id.StringPure` in tests when string literals are needed.
 
 @example
 ```rescript
@@ -73,3 +75,31 @@ let name = "Category"
 ```
 */
 module String: T = StringPure
+
+/** An `Id.T` that names one entity, by its key (`orderId`). */
+module type Identity = {
+  include T with type input = string
+  let key: string
+}
+
+/**
+One distinct type per identity. Each application yields a fresh abstract `t`, so
+an `OrderId.t` cannot be passed where a `CustomerId.t` is expected. A string on
+the wire; the schema carries the `identity` semantic, which is how the runtime
+knows which entity a field names whatever the field is called.
+
+@example
+```rescript
+// src/Order/OrderId.res
+include Reventless.Id.Make({let key = "orderId"})
+```
+*/
+module Make = (
+  K: {
+    let key: string
+  },
+): Identity => {
+  include StringPure
+  let key = K.key
+  let schema = schema->Semantic.mark(~id=Semantic.Id.identity, ~payload=IdentityOf({key: K.key}))
+}

package/src/types/Id.res.mjs

@@ -2,6 +2,7 @@
 
 import * as Sury from "sury";
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
 
 let schema = Sury.string;
 
@@ -12,6 +13,21 @@ let StringPure = {
   cmp: cmp
 };
 
+function Make(K) {
+  let schema$1 = Semantic$Reventless.mark(schema, Semantic$Reventless.Id.identity, {
+    TAG: "IdentityOf",
+    key: K.key
+  });
+  return {
+    schema: schema$1,
+    make: prim => prim,
+    makeFromString: prim => prim,
+    toString: prim => prim,
+    cmp: cmp,
+    key: K.key
+  };
+}
+
 function String_make(prim) {
   return prim;
 }
@@ -35,5 +51,6 @@ let $$String = {
 export {
   StringPure,
   $$String,
+  Make,
 }
 /* schema Not a pure module */

package/src/types/Projection.res

@@ -79,23 +79,60 @@ type action<'id, 'state> =
   /** No-op. Return this when an event should not affect the read model. */
   | Ignore
 
+/**
+The same action keyed by another representation of its ids. `to_` converts the
+ids the action carries; `from` converts back the ids its callbacks receive. The
+storage edge uses it to turn a typed row key into the string a table is keyed by.
+*/
+let mapActionId = (action: action<'a, 's>, ~to_: 'a => 'b, ~from: 'b => 'a): action<'b, 's> =>
+  switch action {
+  | Create(id, state) => Create(to_(id), state)
+  | CreateMany(rows) => CreateMany(rows->Array.map(((id, state)) => (to_(id), state)))
+  | Update(id, f) => Update(to_(id), f)
+  | UpdateMany(ids, f) => UpdateMany(ids->Array.map(to_), (id, state) => f(from(id), state))
+  | UpdateWithDefault(id, default, f) => UpdateWithDefault(to_(id), default, f)
+  | UpdateManyWithDefault(ids, default, f) =>
+    UpdateManyWithDefault(
+      ids->Array.map(to_),
+      id => default(from(id)),
+      (id, state) => f(from(id), state),
+    )
+  | Set(id, state) => Set(to_(id), state)
+  | SetMany(ids, f) => SetMany(ids->Array.map(to_), id => f(from(id)))
+  | Delete(id) => Delete(to_(id))
+  | DeleteMany(ids) => DeleteMany(ids->Array.map(to_))
+  | DeleteIf(id, p) => DeleteIf(to_(id), p)
+  | DeleteManyIf(ids, p) => DeleteManyIf(ids->Array.map(to_), (id, state) => p(from(id), state))
+  | CreateMultiState(id, states) => CreateMultiState(to_(id), states)
+  | UpdateMultiState(id, f) => UpdateMultiState(to_(id), f)
+  | UpdateManyMultiStates(ids, f) =>
+    UpdateManyMultiStates(ids->Array.map(to_), (id, states) => f(from(id), states))
+  | Ignore => Ignore
+  }
+
 /**
 A compiled single-source-to-single-target mapping.
 
 Created by `Projection.Mapping.Make(Source, Target, MappingImpl)`.
 The `project` function receives a full `Message.event'` envelope and returns
-one `action` value.
+one `action` value. Both ends are typed: the envelope id is the source's `Id.t`
+and the row key the target's, so a projection that keys a view by another
+entity's id does not compile. A mapping between different ids converts
+explicitly (`Target.Id.makeFromString`), which marks the seam.
 */
 module type Mapping = {
   //module Source: Source
   //module Target: Target // NOTE: to be destructive substituted
   module SourceId: Id.T
+  type targetId
   @schema
   type sourceEvent
   @schema
   type targetState
 
-  let project: Message.event'<string, sourceEvent> => action<string, targetState>
+  let project: Message.event'<SourceId.t, sourceEvent> => action<targetId, targetState>
+  let targetIdToString: targetId => string
+  let targetIdFromString: string => targetId
   let sourceEventSchema: S.t<sourceEvent>
   let sourceName: string
   let subIdConfig: option<ReadModel.subIdConfig<targetState>>
@@ -116,9 +153,11 @@ module type Mappings = {
 }
 
 module type MappingImpl = {
+  type sourceId
+  type targetId
   type sourceEvent
   type targetState
-  let project: Message.event'<string, sourceEvent> => action<string, targetState>
+  let project: Message.event'<sourceId, sourceEvent> => action<targetId, targetState>
 }
 
 /**
@@ -147,7 +186,9 @@ module Mapping = {
     Target: Target,
     MappingImpl: MappingImpl
       with type sourceEvent := Source.event
-      and type targetState := Target.state,
+      and type targetState := Target.state
+      and type sourceId := Source.Id.t
+      and type targetId := Target.Id.t,
   ): (
     Mapping
       with type targetState = Target.state
@@ -155,11 +196,14 @@ module Mapping = {
       and module SourceId = Source.Id
   ) => {
     module SourceId = Source.Id
+    type targetId = Target.Id.t
     @schema
     type sourceEvent = Source.event
     @schema
     type targetState = Target.state
     let project = MappingImpl.project
+    let targetIdToString = Target.Id.toString
+    let targetIdFromString = Target.Id.makeFromString
     let sourceName = Source.name
     let subIdConfig = Target.subIdConfig
   }

package/src/types/Projection.res.mjs

@@ -1,15 +1,127 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 
+function mapActionId(action, to_, from) {
+  if (typeof action !== "object") {
+    return "Ignore";
+  }
+  switch (action.TAG) {
+    case "Create" :
+      return {
+        TAG: "Create",
+        _0: to_(action._0),
+        _1: action._1
+      };
+    case "CreateMany" :
+      return {
+        TAG: "CreateMany",
+        _0: action._0.map(param => [
+          to_(param[0]),
+          param[1]
+        ])
+      };
+    case "Update" :
+      return {
+        TAG: "Update",
+        _0: to_(action._0),
+        _1: action._1
+      };
+    case "UpdateMany" :
+      let f = action._1;
+      return {
+        TAG: "UpdateMany",
+        _0: action._0.map(to_),
+        _1: (id, state) => f(from(id), state)
+      };
+    case "UpdateWithDefault" :
+      return {
+        TAG: "UpdateWithDefault",
+        _0: to_(action._0),
+        _1: action._1,
+        _2: action._2
+      };
+    case "UpdateManyWithDefault" :
+      let f$1 = action._2;
+      let $$default = action._1;
+      return {
+        TAG: "UpdateManyWithDefault",
+        _0: action._0.map(to_),
+        _1: id => $$default(from(id)),
+        _2: (id, state) => f$1(from(id), state)
+      };
+    case "Set" :
+      return {
+        TAG: "Set",
+        _0: to_(action._0),
+        _1: action._1
+      };
+    case "SetMany" :
+      let f$2 = action._1;
+      return {
+        TAG: "SetMany",
+        _0: action._0.map(to_),
+        _1: id => f$2(from(id))
+      };
+    case "Delete" :
+      return {
+        TAG: "Delete",
+        _0: to_(action._0)
+      };
+    case "DeleteMany" :
+      return {
+        TAG: "DeleteMany",
+        _0: action._0.map(to_)
+      };
+    case "DeleteIf" :
+      return {
+        TAG: "DeleteIf",
+        _0: to_(action._0),
+        _1: action._1
+      };
+    case "DeleteManyIf" :
+      let p = action._1;
+      return {
+        TAG: "DeleteManyIf",
+        _0: action._0.map(to_),
+        _1: (id, state) => p(from(id), state)
+      };
+    case "CreateMultiState" :
+      return {
+        TAG: "CreateMultiState",
+        _0: to_(action._0),
+        _1: action._1
+      };
+    case "UpdateMultiState" :
+      return {
+        TAG: "UpdateMultiState",
+        _0: to_(action._0),
+        _1: action._1
+      };
+    case "UpdateManyMultiStates" :
+      let f$3 = action._1;
+      return {
+        TAG: "UpdateManyMultiStates",
+        _0: action._0.map(to_),
+        _1: (id, states) => f$3(from(id), states)
+      };
+  }
+}
+
 function Make(Source) {
-  return Target => (MappingImpl => ({
-    SourceId: Source.Id,
-    project: MappingImpl.project,
-    sourceEventSchema: Source.eventSchema,
-    sourceName: Source.name,
-    subIdConfig: Target.subIdConfig,
-    targetStateSchema: Target.stateSchema
-  }));
+  return Target => (MappingImpl => {
+    let targetIdToString = Target.Id.toString;
+    let targetIdFromString = Target.Id.makeFromString;
+    return {
+      SourceId: Source.Id,
+      project: MappingImpl.project,
+      targetIdToString: targetIdToString,
+      targetIdFromString: targetIdFromString,
+      sourceEventSchema: Source.eventSchema,
+      sourceName: Source.name,
+      subIdConfig: Target.subIdConfig,
+      targetStateSchema: Target.stateSchema
+    };
+  });
 }
 
 let Mapping = {
@@ -37,6 +149,7 @@ let DcbSource = {
 };
 
 export {
+  mapActionId,
   Mapping,
   Mappings,
   DcbSource,