@reventlessdev/reventless-spec 3.0.0-alpha.129 → 3.0.0-alpha.130

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.130 (2026-09-07)
+
+* feat(dcb)!: a record inside an array is still a reference and a key ([bcb9b13](https://github.com/ReventlessDev/reventless-core/commit/bcb9b13958323d8319d7fcf25c055800e84150f3))
+### Features
+
+* **core:** a command's lifecycle edge comes from its scenarios, not its claim ([1879d05](https://github.com/ReventlessDev/reventless-core/commit/1879d0570a981e7fae5bcd3808f8a36e898bd0fd))
+
+### BREAKING CHANGES
+
+* an `int` field is now `Int` in the generated SDL and
+`"integer"` in JSON Schema, where it was `Float`/`"number"`. A client
+declaring `$retryCount: Float!` against one of these fields must move to
+`Int!`.
+
+
+
 # 3.0.0-alpha.129 (2026-09-04)
 
 ### Bug Fixes

package/package.json

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

package/schema/platform-api.graphql

@@ -53,6 +53,7 @@ type Platform_AutomationSliceDef {
 type Platform_CommandDef {
   aggregateIdField: String
   allowedStates: [String!]
+  allowedStatesSource: String
   apiExposed: Boolean
   level: String!
   mutationField: String!

package/src/components/DcbTag.res

@@ -273,6 +273,56 @@ let isTaggedArray = (fieldSchema: S.t<unknown>) =>
   | _ => false
   }
 
+/**
+The properties of the record a field's value holds, when it holds records rather
+than scalars — `record`, `option<record>`, `array<record>`, `option<array<record>>`
+— with `true` for the array forms, which fan out into one contribution per element.
+
+This is the single wrapper walk the nested-marker walks share, so a marker means
+the same thing whichever of them finds it. It follows exactly the wrappers a
+field's own value can wear and stops at the first record: a marker two records
+deep is a shape no domain here has, and reaching it is a different and much more
+expensive walk than this one.
+*/
+let nestedRecordProperties = (fieldSchema: S.t<unknown>): option<(dict<S.t<unknown>>, bool)> => {
+  let unwrapped = fieldSchema->Semantic.unwrapOptional->Option.getOr(fieldSchema)
+  let (candidate, isList) = switch unwrapped {
+  | Array({additionalItems: Schema(item)}) => (
+      item->Semantic.unwrapOptional->Option.getOr(item),
+      true,
+    )
+  | other => (other, false)
+  }
+  switch candidate {
+  | Object({properties}) => Some((properties, isList))
+  | _ => None
+  }
+}
+
+/** Returns `true` if a record's own properties carry at least one DCB tag. */
+let propertiesCarryTags = (properties: dict<S.t<unknown>>): bool =>
+  properties->Dict.toArray->Array.some(((_, s)) => isTagged(s) || isTaggedArray(s))
+
+/**
+Returns `true` if the schema is an array of records at least one of whose fields
+is DCB-tagged — `array<lineItem>` where `lineItem` carries a `@ref` or a `*Id`.
+
+Distinguished from [`hasNestedTags`] because an array is the case that *fans out*:
+it decides the query mode, exactly as a tagged scalar array does.
+*/
+let isTaggedRecordArray = (fieldSchema: S.t<unknown>): bool =>
+  switch nestedRecordProperties(fieldSchema) {
+  | Some((properties, true)) => propertiesCarryTags(properties)
+  | _ => false
+  }
+
+/** Returns `true` if the schema holds a record — in an array or not — carrying tags. */
+let hasNestedTags = (fieldSchema: S.t<unknown>): bool =>
+  switch nestedRecordProperties(fieldSchema) {
+  | Some((properties, _)) => propertiesCarryTags(properties)
+  | None => false
+  }
+
 /** Returns `true` if the schema was annotated with `DcbTag.partition`. */
 let isPartitionTag = (fieldSchema: S.t<unknown>) =>
   S.Metadata.get(fieldSchema, ~id=dcbPartitionTagId)->Option.isSome
@@ -318,25 +368,127 @@ let jsonValueToString = json =>
   | _ => json->JSON.stringify
   }
 
+/**
+Collapses repeated `(key, value)` pairs, keeping the first of each.
+
+Two order lines for the same product carry the same tag twice. A flat field could
+never produce that, which is why nothing downstream guards against it: a repeated
+clause in a decision query and a repeated entry in a write index are both created
+here, so both are collapsed here. The key is JSON-quoted before the value is
+appended, so the boundary between the two is unambiguous.
+*/
+let dedupeTags = (tags: array<tag>): array<tag> => {
+  let seen = Set.make()
+  tags->Array.filter(({key, value}) => {
+    let identity = key->JSON.Encode.string->JSON.stringify ++ value
+    if seen->Set.has(identity) {
+      false
+    } else {
+      seen->Set.add(identity)
+      true
+    }
+  })
+}
+
+/**
+The tags one object's *own* properties carry: every scalar tagged field, and one
+tag per element of every tagged scalar array.
+
+Shared by the top-level expanded walk and by the nested-record descent below, so
+a marker means the same thing at either depth.
+*/
+let flatFieldTagsExpanded = (
+  fieldName: string,
+  fieldSchema: S.t<unknown>,
+  jsonDict: dict<JSON.t>,
+): array<tag> =>
+  if isTagged(fieldSchema) {
+    switch jsonDict->Dict.get(fieldName) {
+    | Some(jsonValue) => [
+        {key: resolveTagKey(fieldName, fieldSchema), value: jsonValue->jsonValueToString},
+      ]
+    | None => []
+    }
+  } else if isTaggedArray(fieldSchema) {
+    switch jsonDict->Dict.get(fieldName) {
+    | Some(JSON.Array(elements)) =>
+      let tagKey = resolveArrayTagKey(fieldName, fieldSchema)
+      elements->Array.map(element => {key: tagKey, value: element->jsonValueToString})
+    | _ => []
+    }
+  } else {
+    []
+  }
+
+let flatTagsExpanded = (properties: dict<S.t<unknown>>, jsonDict: dict<JSON.t>): array<tag> =>
+  properties
+  ->Dict.toArray
+  ->Array.flatMap(((fieldName, fieldSchema)) =>
+    flatFieldTagsExpanded(fieldName, fieldSchema, jsonDict)
+  )
+
+/**
+The tags carried by the records a field holds — one contribution per element for
+an array, one for a plain nested record.
+
+**The key comes from the nested field's name, never the enclosing one.**
+`lineItems[].productId` produces `productId`, which is what makes it the *same*
+tag the catalog's own events write. A key derived from `lineItems` would name a
+tag no producer has ever written, and the decision read would come back empty —
+the identical symptom to extracting no tags at all, from a different cause. An
+author who wants another key still writes `DcbTag.stringForKey` on the nested
+field, which `resolveTagKey` honours here as it does at the top level.
+*/
+let nestedRecordTags = (fieldSchema: S.t<unknown>, jsonValue: JSON.t): array<tag> =>
+  switch nestedRecordProperties(fieldSchema) {
+  | None => []
+  | Some((properties, isList)) =>
+    let ofObject = json =>
+      switch json->JSON.Decode.object {
+      | Some(elementDict) => flatTagsExpanded(properties, elementDict)
+      | None => []
+      }
+    if isList {
+      switch jsonValue {
+      | JSON.Array(elements) => elements->Array.flatMap(ofObject)
+      | _ => []
+      }
+    } else {
+      ofObject(jsonValue)
+    }
+  }
+
 /**
 Extracts tags from a flat JSON object given a map of field schemas.
 Only fields whose schema is tagged (via `DcbTag.string` / `DcbTag.int`) are extracted.
+
+A field holding *records* is descended into, and this is the one case where this
+walk and [`extractTagsFromPropertiesExpanded`] agree: they differ on a scalar
+array (one stringified tag here, one tag per element there) because a stringified
+array is at least a value, whereas a stringified line-item list is nothing any
+producer could match. A reader must not generalise the difference.
 */
 let extractTagsFromProperties = (properties: dict<S.t<unknown>>, jsonDict: dict<JSON.t>) =>
   properties
   ->Dict.toArray
-  ->Array.filterMap(((fieldName, fieldSchema)) =>
+  ->Array.flatMap(((fieldName, fieldSchema)) =>
     if isTagged(fieldSchema) {
-      jsonDict
-      ->Dict.get(fieldName)
-      ->Option.map(jsonValue => {
-        key: resolveTagKey(fieldName, fieldSchema),
-        value: jsonValue->jsonValueToString,
-      })
+      switch jsonDict->Dict.get(fieldName) {
+      | Some(jsonValue) => [
+          {key: resolveTagKey(fieldName, fieldSchema), value: jsonValue->jsonValueToString},
+        ]
+      | None => []
+      }
+    } else if hasNestedTags(fieldSchema) {
+      switch jsonDict->Dict.get(fieldName) {
+      | Some(jsonValue) => nestedRecordTags(fieldSchema, jsonValue)
+      | None => []
+      }
     } else {
-      None
+      []
     }
   )
+  ->dedupeTags
 
 // Extract the discriminating TAG constructor name from a variant Object schema's
 // `properties`. sury (11) compiles a record-payload variant `Foo({...})` to an
@@ -517,6 +669,10 @@ For scalar tagged fields, behaves identically to `extractTagsFromProperties`.
 For array tagged fields, produces one tag per element. Tag keys honour an optional
 `DcbTag.stringForKey(~key=...)` override on the (inner) schema; otherwise the field
 name is used.
+
+Fields holding records are descended into on the same terms as in
+`extractTagsFromProperties` — the two walks agree there and differ only on scalar
+arrays; see that function.
 */
 let extractTagsFromPropertiesExpanded = (
   properties: dict<S.t<unknown>>,
@@ -525,25 +681,18 @@ let extractTagsFromPropertiesExpanded = (
   properties
   ->Dict.toArray
   ->Array.flatMap(((fieldName, fieldSchema)) =>
-    if isTagged(fieldSchema) {
+    if isTagged(fieldSchema) || isTaggedArray(fieldSchema) {
+      flatFieldTagsExpanded(fieldName, fieldSchema, jsonDict)
+    } else if hasNestedTags(fieldSchema) {
       switch jsonDict->Dict.get(fieldName) {
-      | Some(jsonValue) => [
-          {key: resolveTagKey(fieldName, fieldSchema), value: jsonValue->jsonValueToString},
-        ]
+      | Some(jsonValue) => nestedRecordTags(fieldSchema, jsonValue)
       | None => []
       }
-    } else if isTaggedArray(fieldSchema) {
-      switch jsonDict->Dict.get(fieldName) {
-      | Some(JSON.Array(elements)) => {
-          let tagKey = resolveArrayTagKey(fieldName, fieldSchema)
-          elements->Array.map(element => {key: tagKey, value: element->jsonValueToString})
-        }
-      | _ => []
-      }
     } else {
       []
     }
   )
+  ->dedupeTags
 
 /**
 Extracts DCB tags from an event JSON value, expanding array values into per-element tags.
@@ -605,8 +754,9 @@ let extractTagsExpanded = (schema: S.t<'a>, value: 'a): array<tag> =>
 // --- Automatic query construction from command schema ---
 
 /**
-Returns `true` if any field in the schema is a tagged array
-(`array<@s.matches(DcbTag.string) string>`).
+Returns `true` if any field in the schema fans out into several tags — a tagged
+scalar array (`array<@s.matches(DcbTag.string) string>`) or an array of records
+carrying tags (`array<lineItem>`).
 Used to automatically determine whether to build single-clause or multi-clause queries.
 */
 let hasTaggedArrayFields = (schema: S.t<'a>): bool =>
@@ -615,21 +765,30 @@ let hasTaggedArrayFields = (schema: S.t<'a>): bool =>
     anyOf->Array.some(variantSchema =>
       switch variantSchema {
       | Object({properties}) =>
-        properties->Dict.toArray->Array.some(((_, fieldSchema)) => isTaggedArray(fieldSchema))
+        properties
+        ->Dict.toArray
+        ->Array.some(((_, fieldSchema)) =>
+          isTaggedArray(fieldSchema) || isTaggedRecordArray(fieldSchema)
+        )
       | _ => false
       }
     )
   | Object({properties}) =>
-    properties->Dict.toArray->Array.some(((_, fieldSchema)) => isTaggedArray(fieldSchema))
+    properties
+    ->Dict.toArray
+    ->Array.some(((_, fieldSchema)) =>
+      isTaggedArray(fieldSchema) || isTaggedRecordArray(fieldSchema)
+    )
   | _ => false
   }
 
 /**
 Collects the produced tag keys of one event-schema variant: the resolved tag key
-of every scalar tagged field plus the resolved (override-aware) tag key of every
-tagged-array field.
+of every scalar tagged field, the resolved (override-aware) tag key of every
+tagged-array field, and the keys of the tagged fields of any records the variant
+holds — under the nested field's own name, as the extraction resolves them.
 */
-let tagKeysOfProperties = (properties: dict<S.t<unknown>>): array<string> =>
+let flatTagKeysOfProperties = (properties: dict<S.t<unknown>>): array<string> =>
   properties
   ->Dict.toArray
   ->Array.filterMap(((fieldName, fieldSchema)) =>
@@ -642,6 +801,22 @@ let tagKeysOfProperties = (properties: dict<S.t<unknown>>): array<string> =>
     }
   )
 
+let tagKeysOfProperties = (properties: dict<S.t<unknown>>): array<string> =>
+  properties
+  ->Dict.toArray
+  ->Array.flatMap(((fieldName, fieldSchema)) =>
+    if isTagged(fieldSchema) {
+      [resolveTagKey(fieldName, fieldSchema)]
+    } else if isTaggedArray(fieldSchema) {
+      [resolveArrayTagKey(fieldName, fieldSchema)]
+    } else {
+      switch nestedRecordProperties(fieldSchema) {
+      | Some((nested, _)) => flatTagKeysOfProperties(nested)
+      | None => []
+      }
+    }
+  )
+
 /**
 Maps each event-type (variant constructor name) to the set of DCB tag keys that
 type can carry, read from a *produced* event-log schema.
@@ -882,21 +1057,43 @@ let extractCrossPartitionTagKeys = (schema: S.t<'event>): array<string> => {
 Collects the `*Id` / `*Ids`-shaped fields of one object-variant's properties as
 `DcbScopeInference.idField`s — by **name**, independent of any DCB tag flag. This
 is the un-annotated structural view the scope inference consumes.
+
+A field holding records contributes the `*Id`-shaped fields of those records
+under their **own** names, and a field reached through an array is reported as a
+list whichever container it came from: the inference reasons about keys, and a
+key reached per line fans out exactly as a key reached per array element does.
+Reporting it as single-valued would derive the wrong partition for the slice.
+
+That `DcbScopeInference.idField` needs no change to carry this is the evidence
+the boundary was drawn in the right place — the descent is a fact about schemas,
+which is this module's half of the split.
 */
-let idFieldsOfProperties = (properties: dict<S.t<unknown>>): array<DcbScopeInference.idField> =>
+let idFieldsOfProperties = (properties: dict<S.t<unknown>>): array<DcbScopeInference.idField> => {
+  let isIdName = (name: string) => name->String.endsWith("Ids") || name->String.endsWith("Id")
   properties
   ->Dict.toArray
-  ->Array.filterMap(((name, fieldSchema)) =>
-    if name->String.endsWith("Ids") || name->String.endsWith("Id") {
+  ->Array.flatMap(((name, fieldSchema)) =>
+    if isIdName(name) {
       let isList = switch fieldSchema {
       | Array(_) => true
       | _ => false
       }
-      Some({DcbScopeInference.name, isList})
+      [{DcbScopeInference.name, isList}]
     } else {
-      None
+      switch nestedRecordProperties(fieldSchema) {
+      | Some((nested, nestedIsList)) =>
+        nested
+        ->Dict.toArray
+        ->Array.filterMap(((nestedName, _)) =>
+          isIdName(nestedName)
+            ? Some({DcbScopeInference.name: nestedName, isList: nestedIsList})
+            : None
+        )
+      | None => []
+      }
     }
   )
+}
 
 /**
 Extracts the `DcbScopeInference.eventShape`s (variant name + `*Id` fields) from a

package/src/components/DcbTag.res.mjs

@@ -8,6 +8,7 @@ import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.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 Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
 import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
 import * as DcbScopeInference$Reventless from "./DcbScopeInference.res.mjs";
 
@@ -86,6 +87,62 @@ function isTaggedArray(fieldSchema) {
   }
 }
 
+function nestedRecordProperties(fieldSchema) {
+  let unwrapped = Stdlib_Option.getOr(Semantic$Reventless.unwrapOptional(fieldSchema), fieldSchema);
+  let match;
+  if (unwrapped.type === "array") {
+    let item = unwrapped.additionalItems;
+    match = item === "strip" || item === "strict" ? [
+        unwrapped,
+        false
+      ] : [
+        Stdlib_Option.getOr(Semantic$Reventless.unwrapOptional(item), item),
+        true
+      ];
+  } else {
+    match = [
+      unwrapped,
+      false
+    ];
+  }
+  let candidate = match[0];
+  if (candidate.type === "object") {
+    return [
+      candidate.properties,
+      match[1]
+    ];
+  }
+}
+
+function propertiesCarryTags(properties) {
+  return Object.entries(properties).some(param => {
+    let s = param[1];
+    if (Stdlib_Option.isSome(Sury.$Metadata_get(s, dcbTagId))) {
+      return true;
+    } else {
+      return isTaggedArray(s);
+    }
+  });
+}
+
+function isTaggedRecordArray(fieldSchema) {
+  let match = nestedRecordProperties(fieldSchema);
+  if (match !== undefined && match[1]) {
+    return propertiesCarryTags(match[0]);
+  } else {
+    return false;
+  }
+}
+
+function hasNestedTags(fieldSchema) {
+  let match = nestedRecordProperties(fieldSchema);
+  if (match !== undefined) {
+    return propertiesCarryTags(match[0]);
+  } else {
+    return false;
+  }
+}
+
 function isPartitionTag(fieldSchema) {
   return Stdlib_Option.isSome(Sury.$Metadata_get(fieldSchema, dcbPartitionTagId));
 }
@@ -139,17 +196,102 @@ function jsonValueToString(json) {
   }
 }
 
+function dedupeTags(tags) {
+  let seen = new Set();
+  return tags.filter(param => {
+    let identity = JSON.stringify(param.key) + param.value;
+    if (seen.has(identity)) {
+      return false;
+    } else {
+      seen.add(identity);
+      return true;
+    }
+  });
+}
+
+function flatFieldTagsExpanded(fieldName, fieldSchema, jsonDict) {
+  if (Stdlib_Option.isSome(Sury.$Metadata_get(fieldSchema, dcbTagId))) {
+    let jsonValue = jsonDict[fieldName];
+    if (jsonValue !== undefined) {
+      return [{
+          key: resolveTagKey(fieldName, fieldSchema),
+          value: jsonValueToString(jsonValue)
+        }];
+    } else {
+      return [];
+    }
+  }
+  if (!isTaggedArray(fieldSchema)) {
+    return [];
+  }
+  let match = jsonDict[fieldName];
+  if (match === undefined) {
+    return [];
+  }
+  if (!Array.isArray(match)) {
+    return [];
+  }
+  let tagKey = resolveArrayTagKey(fieldName, fieldSchema);
+  return match.map(element => ({
+    key: tagKey,
+    value: jsonValueToString(element)
+  }));
+}
+
+function flatTagsExpanded(properties, jsonDict) {
+  return Object.entries(properties).flatMap(param => flatFieldTagsExpanded(param[0], param[1], jsonDict));
+}
+
+function nestedRecordTags(fieldSchema, jsonValue) {
+  let match = nestedRecordProperties(fieldSchema);
+  if (match === undefined) {
+    return [];
+  }
+  let properties = match[0];
+  let ofObject = json => {
+    let elementDict = Stdlib_JSON.Decode.object(json);
+    if (elementDict !== undefined) {
+      return flatTagsExpanded(properties, elementDict);
+    } else {
+      return [];
+    }
+  };
+  if (match[1]) {
+    if (Array.isArray(jsonValue)) {
+      return jsonValue.flatMap(ofObject);
+    } else {
+      return [];
+    }
+  } else {
+    return ofObject(jsonValue);
+  }
+}
+
 function extractTagsFromProperties(properties, jsonDict) {
-  return Stdlib_Array.filterMap(Object.entries(properties), param => {
+  return dedupeTags(Object.entries(properties).flatMap(param => {
     let fieldSchema = param[1];
     let fieldName = param[0];
     if (Stdlib_Option.isSome(Sury.$Metadata_get(fieldSchema, dcbTagId))) {
-      return Stdlib_Option.map(jsonDict[fieldName], jsonValue => ({
-        key: resolveTagKey(fieldName, fieldSchema),
-        value: jsonValueToString(jsonValue)
-      }));
+      let jsonValue = jsonDict[fieldName];
+      if (jsonValue !== undefined) {
+        return [{
+            key: resolveTagKey(fieldName, fieldSchema),
+            value: jsonValueToString(jsonValue)
+          }];
+      } else {
+        return [];
+      }
     }
-  });
+    if (!hasNestedTags(fieldSchema)) {
+      return [];
+    }
+    let jsonValue$1 = jsonDict[fieldName];
+    if (jsonValue$1 !== undefined) {
+      return nestedRecordTags(fieldSchema, jsonValue$1);
+    } else {
+      return [];
+    }
+  }));
 }
 
 function variantTagName(properties) {
@@ -275,36 +417,22 @@ function isVariantPayloadBearing(schema, name) {
 }
 
 function extractTagsFromPropertiesExpanded(properties, jsonDict) {
-  return Object.entries(properties).flatMap(param => {
+  return dedupeTags(Object.entries(properties).flatMap(param => {
     let fieldSchema = param[1];
     let fieldName = param[0];
-    if (Stdlib_Option.isSome(Sury.$Metadata_get(fieldSchema, dcbTagId))) {
-      let jsonValue = jsonDict[fieldName];
-      if (jsonValue !== undefined) {
-        return [{
-            key: resolveTagKey(fieldName, fieldSchema),
-            value: jsonValueToString(jsonValue)
-          }];
-      } else {
-        return [];
-      }
-    }
-    if (!isTaggedArray(fieldSchema)) {
-      return [];
+    if (Stdlib_Option.isSome(Sury.$Metadata_get(fieldSchema, dcbTagId)) || isTaggedArray(fieldSchema)) {
+      return flatFieldTagsExpanded(fieldName, fieldSchema, jsonDict);
     }
-    let match = jsonDict[fieldName];
-    if (match === undefined) {
+    if (!hasNestedTags(fieldSchema)) {
       return [];
     }
-    if (!Array.isArray(match)) {
+    let jsonValue = jsonDict[fieldName];
+    if (jsonValue !== undefined) {
+      return nestedRecordTags(fieldSchema, jsonValue);
+    } else {
       return [];
     }
-    let tagKey = resolveArrayTagKey(fieldName, fieldSchema);
-    return match.map(element => ({
-      key: tagKey,
-      value: jsonValueToString(element)
-    }));
-  });
+  }));
 }
 
 function extractTagsFromJsonExpanded(schema, json) {
@@ -352,11 +480,25 @@ function extractTagsExpanded(schema, value) {
 function hasTaggedArrayFields(schema) {
   switch (schema.type) {
     case "object" :
-      return Object.entries(schema.properties).some(param => isTaggedArray(param[1]));
+      return Object.entries(schema.properties).some(param => {
+        let fieldSchema = param[1];
+        if (isTaggedArray(fieldSchema)) {
+          return true;
+        } else {
+          return isTaggedRecordArray(fieldSchema);
+        }
+      });
     case "anyOf" :
       return schema.anyOf.some(variantSchema => {
         if (variantSchema.type === "object") {
-          return Object.entries(variantSchema.properties).some(param => isTaggedArray(param[1]));
+          return Object.entries(variantSchema.properties).some(param => {
+            let fieldSchema = param[1];
+            if (isTaggedArray(fieldSchema)) {
+              return true;
+            } else {
+              return isTaggedRecordArray(fieldSchema);
+            }
+          });
         } else {
           return false;
         }
@@ -366,7 +508,7 @@ function hasTaggedArrayFields(schema) {
   }
 }
 
-function tagKeysOfProperties(properties) {
+function flatTagKeysOfProperties(properties) {
   return Stdlib_Array.filterMap(Object.entries(properties), param => {
     let fieldSchema = param[1];
     let fieldName = param[0];
@@ -380,6 +522,25 @@ function tagKeysOfProperties(properties) {
   });
 }
 
+function tagKeysOfProperties(properties) {
+  return Object.entries(properties).flatMap(param => {
+    let fieldSchema = param[1];
+    let fieldName = param[0];
+    if (Stdlib_Option.isSome(Sury.$Metadata_get(fieldSchema, dcbTagId))) {
+      return [resolveTagKey(fieldName, fieldSchema)];
+    }
+    if (isTaggedArray(fieldSchema)) {
+      return [resolveArrayTagKey(fieldName, fieldSchema)];
+    }
+    let match = nestedRecordProperties(fieldSchema);
+    if (match !== undefined) {
+      return flatTagKeysOfProperties(match[0]);
+    } else {
+      return [];
+    }
+  });
+}
+
 function extractTagKeysByEventType(schema) {
   let result = {};
   let addVariant = variantSchema => {
@@ -530,17 +691,38 @@ function extractCrossPartitionTagKeys(schema) {
 }
 
 function idFieldsOfProperties(properties) {
-  return Stdlib_Array.filterMap(Object.entries(properties), param => {
+  let isIdName = name => {
+    if (name.endsWith("Ids")) {
+      return true;
+    } else {
+      return name.endsWith("Id");
+    }
+  };
+  return Object.entries(properties).flatMap(param => {
+    let fieldSchema = param[1];
     let name = param[0];
-    if (!(name.endsWith("Ids") || name.endsWith("Id"))) {
-      return;
+    if (isIdName(name)) {
+      let isList;
+      isList = fieldSchema.type === "array";
+      return [{
+          name: name,
+          isList: isList
+        }];
     }
-    let isList;
-    isList = param[1].type === "array";
-    return {
-      name: name,
-      isList: isList
-    };
+    let match = nestedRecordProperties(fieldSchema);
+    if (match === undefined) {
+      return [];
+    }
+    let nestedIsList = match[1];
+    return Stdlib_Array.filterMap(Object.entries(match[0]), param => {
+      let nestedName = param[0];
+      if (isIdName(nestedName)) {
+        return {
+          name: nestedName,
+          isList: nestedIsList
+        };
+      }
+    });
   });
 }
 
@@ -862,12 +1044,20 @@ export {
   derivedPartitionTagSchema,
   isTagged,
   isTaggedArray,
+  nestedRecordProperties,
+  propertiesCarryTags,
+  isTaggedRecordArray,
+  hasNestedTags,
   isPartitionTag,
   isCrossPartitionTag,
   isCrossPartitionTaggedArray,
   resolveTagKey,
   resolveArrayTagKey,
   jsonValueToString,
+  dedupeTags,
+  flatFieldTagsExpanded,
+  flatTagsExpanded,
+  nestedRecordTags,
   extractTagsFromProperties,
   variantTagName,
   extractTagsFromJson,
@@ -879,6 +1069,7 @@ export {
   extractTagsFromJsonExpanded,
   extractTagsExpanded,
   hasTaggedArrayFields,
+  flatTagKeysOfProperties,
   tagKeysOfProperties,
   extractTagKeysByEventType,
   mergeTagKeysByEventType,

package/src/components/Plugin.res

@@ -122,6 +122,32 @@ let uiFragmentManifestOptionSchema = S.option(uiFragmentManifestSchema)
 @schema
 type commandLevel = Collection | Instance
 
+/** One command's lifecycle edge as the component's own scenarios describe it:
+    where a scenario shows the command taking effect, where those scenarios land,
+    and whether it brings a row into existence or acts on one.
+
+    Harvested from the GWT corpus by `check:lifecycle` and committed beside the
+    plugin as `src/LifecycleModel.res`, so structure assembly reads a value rather
+    than the test tree — which is not published with a plugin package.
+
+    No `@schema`: nothing serialises this. It is read once, while the structure is
+    assembled, and what leaves is the `commandDef` fields it resolved. */
+type derivedEdge = {
+  /** The writable's `Spec.name`, which is what the structure knows it by. */
+  component: string,
+  command: string,
+  /** Absent where the corpus could not label a history — the honest answer when
+      the linked views declare no lifecycle field, and the reason the name-stem
+      guess is still there to fall back to. */
+  level?: commandLevel,
+  /** States a scenario shows the command taking effect from. Empty means the
+      corpus said nothing, NOT that the command belongs nowhere. */
+  allowedStates: array<string>,
+  /** States those scenarios land in. More than one is an edge a single
+      `targetState` cannot carry, so it is left to the declaration. */
+  targets: array<string>,
+}
+
 @schema
 type fieldReference = {
   fieldName: string,
@@ -137,12 +163,29 @@ type commandDef = {
   aggregateIdField: option<string>,
   mutationField: string,
   references: array<fieldReference>,
-  /** The declared *from* set — lifecycle states this command is meaningful in.
-      `None` means always available; `Some([])` means never show. */
+  /** The *from* set — lifecycle states this command is meaningful in. `None`
+      means always available; `Some([])` means never show. */
   allowedStates: option<array<string>>,
-  /** The declared *to* state this command's handler writes. `None` with a
-      from-set present means the command does not move the row. */
+  /** The *to* state this command's handler writes. `None` with a from-set present
+      means the command does not move the row. */
   targetState: option<string>,
+  /** Where the from-set came from, ranking an inherited edge against an authored
+      one the way `queryableDef.labelFieldSource` does for its field:
+
+      - `"derived"` — the component's own scenarios.
+      - `"declared"` — its `commandTransition` switch.
+      - `"unrestricted"` — the switch declares the command legal in *every*
+        state, so there is no from-set to publish and `allowedStates` is absent.
+
+      Absent means the command names no states to come from and nothing said that
+      was deliberate — a spec that wrote no switch, or one whose command creates
+      the row. So a consumer drawing a state machine can tell an edge left
+      unconstrained on purpose from one that simply has no from-set.
+
+      It speaks for the from-set only. The two halves of an edge are reported
+      separately because they fail separately: a corpus routinely shows a command
+      taking effect without ever showing where it lands. */
+  allowedStatesSource?: string,
   /** Whether the variant is exposed in the generated API (non-`@noApi`). */
   apiExposed: option<bool>,
   /** Access keys — any one of them — a caller needs to be *offered* this command.

package/src/components/Plugin.res.mjs

@@ -99,6 +99,7 @@ let commandDefSchema = Sury.$schema(s => ({
   references: s.m(Sury.array(fieldReferenceSchema)),
   allowedStates: s.m(Sury.$option(Sury.array(Sury.string))),
   targetState: s.m(Sury.$option(Sury.string)),
+  allowedStatesSource: s.m(Sury.$option(Sury.string)),
   apiExposed: s.m(Sury.$option(Sury.bool)),
   requiredAccess: s.m(Sury.$option(Sury.array(Sury.string))),
   ownerField: s.m(Sury.$option(Sury.string))

package/src/components/Reference.res

@@ -62,6 +62,11 @@ Only wrappers around the field's own value are followed — the optional union a
 the array element, to any depth. Object properties are not: a reference declared
 on a nested record's field belongs to that field, and attributing it to the
 enclosing one would name the wrong field.
+
+That is still the right answer to the question this asks. A caller collecting
+*every* reference a command or event declares — including the ones on the fields
+of records it holds — wants [`collectFieldTargets`], which names each one by its
+own path.
 */
 let rec getFieldTarget = (schema: S.t<unknown>): option<target> =>
   switch getTarget(schema) {
@@ -75,6 +80,49 @@ let rec getFieldTarget = (schema: S.t<unknown>): option<target> =>
     }
   }
 
+/**
+Every reference a field declares, each paired with the path that names it.
+
+A reference on the field's own value keeps the bare field name (`customerId`), so
+nothing that reads today's paths has to learn the new form to go on working. One
+declared on a field of a record the field holds is named by its path:
+`lineItems[].productId` — `[]` for "each element of", `.` for "property of", and
+no index, because a marker lives on the element *schema* and so applies to every
+element or to none.
+
+⚠️ A path is a **widened** contract, not a compatible one, for a consumer that
+uses the name as a dictionary key into a value's properties: such a consumer
+simply misses a nested reference and falls back to whatever it does for an
+unreferenced field. That degradation is the correct one, but it is a degradation.
+
+Only one record deep, matching [`DcbTag.nestedRecordProperties`], which is the
+walk shared with the tag extraction so a marker is found in the same places by
+both.
+*/
+let collectFieldTargets = (
+  fieldName: string,
+  schema: S.t<unknown>,
+): array<(string, target)> =>
+  switch getFieldTarget(schema) {
+  | Some(target) => [(fieldName, target)]
+  | None =>
+    switch DcbTag.nestedRecordProperties(schema) {
+    | None => []
+    | Some((properties, isList)) =>
+      let prefix = isList ? fieldName ++ "[]" : fieldName
+      properties
+      ->Dict.toArray
+      ->Array.filterMap(((propName, propSchema)) =>
+        propName === "TAG"
+          ? None
+          : getFieldTarget(propSchema)->Option.map(target => (
+              `${prefix}.${propName}`,
+              target,
+            ))
+      )
+    }
+  }
+
 /**
 Like `to_` but does not imply DCB tag semantics.
 Use with `@ref("Entity") @noDcbTag` when the field references another entity

package/src/components/Reference.res.mjs

@@ -1,6 +1,7 @@
 // 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 "./DcbTag.res.mjs";
 import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
@@ -53,6 +54,32 @@ function getFieldTarget(_schema) {
   };
 }
 
+function collectFieldTargets(fieldName, schema) {
+  let target = getFieldTarget(schema);
+  if (target !== undefined) {
+    return [[
+        fieldName,
+        target
+      ]];
+  }
+  let match = DcbTag$Reventless.nestedRecordProperties(schema);
+  if (match === undefined) {
+    return [];
+  }
+  let prefix = match[1] ? fieldName + "[]" : fieldName;
+  return Stdlib_Array.filterMap(Object.entries(match[0]), param => {
+    let propName = param[0];
+    if (propName === "TAG") {
+      return;
+    } else {
+      return Stdlib_Option.map(getFieldTarget(param[1]), target => [
+        prefix + `.` + propName,
+        target
+      ]);
+    }
+  });
+}
+
 function toWithoutDcbTag(plugin, entity) {
   return Semantic$Reventless.mark(Sury.string, Semantic$Reventless.Id.reference, {
     TAG: "ReferenceTo",
@@ -67,6 +94,7 @@ export {
   to_,
   getTarget,
   getFieldTarget,
+  collectFieldTargets,
   toWithoutDcbTag,
 }
 /* sury Not a pure module */

package/src/generator/Codegen.res

@@ -350,6 +350,7 @@ let renderPluginStructureCall = (
   ~extensions: array<string>,
   ~extensionPoints: array<Pairing.extensionPointDef>,
   ~componentChapters: array<(string, string)>,
+  ~hasLifecycleModel: bool,
 ): option<array<string>> => {
   // The structure call carries the EP *mapping* files (one per Delegate
   // connection), not the wrapped ExtensionPoint module — Plugin_Structure reads
@@ -428,6 +429,15 @@ let renderPluginStructureCall = (
         )
       ls->Array.push("    ~componentChapters=Dict.fromArray([" ++ entries->Array.join(", ") ++ "]),")
     }
+    // What the plugin's own scenarios say about each command's lifecycle edge.
+    // Written by `check:lifecycle:update`, not here: the sidecars it harvests are
+    // produced by the build this generator runs *before*, so a generator-written
+    // model would always be one build stale and a cold clone would have none at
+    // all. Referenced only when the file is on disk, so a plugin that has never
+    // been harvested keeps a byte-identical generated Plugin.res.
+    if hasLifecycleModel {
+      ls->Array.push("    ~lifecycleModel=LifecycleModel.model,")
+    }
     ls->Array.push("  )")
     Some(ls)
   }
@@ -595,6 +605,7 @@ let renderComposition = (
   ~config: Config.config,
   ~resolved: Pairing.resolved,
   ~componentChapters: array<(string, string)>,
+  ~hasLifecycleModel: bool,
 ): string => {
   let lines: array<string> = []
 
@@ -740,6 +751,7 @@ let renderComposition = (
     ~extensions=resolved.extensions,
     ~extensionPoints=resolved.extensionPoints,
     ~componentChapters,
+    ~hasLifecycleModel,
   )
   let hasPluginStructure = pluginStructureLines->Option.isSome
   switch pluginStructureLines {
@@ -833,6 +845,7 @@ let render = (
   ~config: Config.config,
   ~resolved: Pairing.resolved,
   ~discovered: array<Discovery.discoveredFile>,
+  ~hasLifecycleModel: bool=false,
 ): string => {
   validateUniqueSpecStems(~discovered)
   validateSliceTargets(~resolved)
@@ -858,6 +871,6 @@ let render = (
     )
   switch config.variant {
   | Aws({compositionNamespace}) => renderAwsWrapper(~compositionNamespace)
-  | Composition => renderComposition(~config, ~resolved, ~componentChapters)
+  | Composition => renderComposition(~config, ~resolved, ~componentChapters, ~hasLifecycleModel)
   }
 }

package/src/generator/Codegen.res.mjs

@@ -239,7 +239,7 @@ function renderTaskMakeParam(tasks) {
   return "      ~tasks=[" + entries.join(", ") + "],";
 }
 
-function renderPluginStructureCall(name, aggregates, readModels, stateViewSlices, stateViewSlicesStream, stateChangeSlices, automationSlices, outboundTranslationSlices, inboundTranslationSlices, extensions, extensionPoints, componentChapters) {
+function renderPluginStructureCall(name, aggregates, readModels, stateViewSlices, stateViewSlicesStream, stateChangeSlices, automationSlices, outboundTranslationSlices, inboundTranslationSlices, extensions, extensionPoints, componentChapters, hasLifecycleModel) {
   let epMappingStems = extensionPoints.flatMap(param => param.mappings);
   let hasComponents = aggregates.length !== 0 || readModels.length !== 0 || stateViewSlices.length !== 0 || stateViewSlicesStream.length !== 0 || stateChangeSlices.length !== 0 || automationSlices.length !== 0 || outboundTranslationSlices.length !== 0 || inboundTranslationSlices.length !== 0 || extensions.length !== 0 || epMappingStems.length !== 0;
   if (!hasComponents) {
@@ -295,6 +295,9 @@ function renderPluginStructureCall(name, aggregates, readModels, stateViewSlices
     let entries$8 = componentChapters.map(param => "(\"" + param[0] + "\", \"" + param[1] + "\")");
     ls.push("    ~componentChapters=Dict.fromArray([" + entries$8.join(", ") + "]),");
   }
+  if (hasLifecycleModel) {
+    ls.push("    ~lifecycleModel=LifecycleModel.model,");
+  }
   ls.push("  )");
   return ls;
 }
@@ -394,7 +397,7 @@ function renderAwsWrapper(compositionNamespace) {
   ].join("\n");
 }
 
-function renderComposition(config, resolved, componentChapters) {
+function renderComposition(config, resolved, componentChapters, hasLifecycleModel) {
   let lines = [];
   lines.push("// AUTO-GENERATED — do not edit. Run `npm run generate` to update.");
   lines.push("");
@@ -459,7 +462,7 @@ function renderComposition(config, resolved, componentChapters) {
     lines.push("  // Extensions");
     push(renderExtensions(resolved.extensions));
   }
-  let pluginStructureLines = renderPluginStructureCall(config.name, resolved.aggregates, resolved.readModels, resolved.stateViewSlices, resolved.stateViewSlicesStream, resolved.stateChangeSlices, resolved.automationSlices, resolved.outboundTranslationSlices, resolved.inboundTranslationSlices, resolved.extensions, resolved.extensionPoints, componentChapters);
+  let pluginStructureLines = renderPluginStructureCall(config.name, resolved.aggregates, resolved.readModels, resolved.stateViewSlices, resolved.stateViewSlicesStream, resolved.stateChangeSlices, resolved.automationSlices, resolved.outboundTranslationSlices, resolved.inboundTranslationSlices, resolved.extensions, resolved.extensionPoints, componentChapters, hasLifecycleModel);
   let hasPluginStructure = Stdlib_Option.isSome(pluginStructureLines);
   if (pluginStructureLines !== undefined) {
     pluginStructureLines.forEach(l => {
@@ -517,7 +520,8 @@ function renderComposition(config, resolved, componentChapters) {
   return lines.join("\n");
 }
 
-function render(config, resolved, discovered) {
+function render(config, resolved, discovered, hasLifecycleModelOpt) {
+  let hasLifecycleModel = hasLifecycleModelOpt !== undefined ? hasLifecycleModelOpt : false;
   validateUniqueSpecStems(discovered);
   validateSliceTargets(resolved);
   let componentStems = [
@@ -533,7 +537,7 @@ function render(config, resolved, discovered) {
   let componentChapters = Discovery$Reventless.chaptersByStem(discovered).filter(param => componentStems.includes(param[0]));
   let match = config.variant;
   if (typeof match !== "object") {
-    return renderComposition(config, resolved, componentChapters);
+    return renderComposition(config, resolved, componentChapters, hasLifecycleModel);
   } else {
     return renderAwsWrapper(match.compositionNamespace);
   }

package/src/generator/PluginGenerator.res

@@ -34,7 +34,10 @@ let () = {
     let config = {...Config.read(~srcDir), variant}
     let discovered = Discovery.scan(~srcDir, ~exclude=config.exclude)
     let resolved = Pairing.resolve(discovered, ~srcDir)
-    let source = Codegen.render(~config, ~resolved, ~discovered)
+    // Sits at the src root rather than in a kind folder, so `Discovery` never
+    // sees it and it is not a component. Its presence is the whole question.
+    let hasLifecycleModel = NodePath.join([srcDir, "LifecycleModel.res"])->NodeFs.existsSync
+    let source = Codegen.render(~config, ~resolved, ~discovered, ~hasLifecycleModel)
 
     let outputDir = switch variant {
     | Config.Composition => srcDir

package/src/generator/PluginGenerator.res.mjs

@@ -56,7 +56,8 @@ if (srcDirArg === "") {
   };
   let discovered = Discovery$Reventless.scan(srcDir, config_exclude);
   let resolved = Pairing$Reventless.resolve(discovered, srcDir);
-  let source = Codegen$Reventless.render(config, resolved, discovered);
+  let hasLifecycleModel = Nodefs.existsSync(Nodepath.join(srcDir, "LifecycleModel.res"));
+  let source = Codegen$Reventless.render(config, resolved, discovered, hasLifecycleModel);
   let outputDir;
   outputDir = typeof variant !== "object" ? srcDir : Nodepath.join(process.cwd(), "src");
   let pluginPath = Nodepath.join(outputDir, "Plugin.res");

package/src/types/Transition.res

@@ -36,10 +36,23 @@
 // plugin structure is assembled, and what leaves is the pair of names the
 // structure already carried.
 type t<'state> =
-  /** No edge declared: legal in every state, moves the row nowhere. The honest
-      answer for a report a slice publishes, which must not be refused because
-      the row moved on while the report was in flight. */
+  /** Legal in every state, and moves the row nowhere. The honest answer for a
+      report a slice publishes, which must not be refused because the row moved
+      on while the report was in flight. A claim, not an omission — see
+      `Undeclared`, which is the omission. */
   | Unrestricted
+  /** The spec wrote no switch, and the ppx injected this. Never write it: say
+      `Unrestricted` if you mean the command is legal everywhere.
+
+      It reads exactly like `Unrestricted` — no from-set, no target — everywhere
+      but one place, and that place is why it exists. The harvested lifecycle
+      model may answer for silence; it may not narrow a claim. A corpus only
+      covers the states somebody wrote a scenario for, so letting it answer for
+      `Unrestricted` would shrink "legal in every state" down to an accident of
+      coverage, and the command would quietly stop being offered on the rows
+      nobody tested. With the two spelled apart, that shrinkage cannot happen and
+      a scenario that genuinely refutes the claim is a contradiction instead. */
+  | Undeclared
   /** Brings the row into existence, so there is no state it could come from.
       Distinct from `Unrestricted`, which draws no edge at all. */
   | Creates('state)
@@ -54,6 +67,7 @@ type t<'state> =
     tells apart. */
 let allowedStates = (transition: t<'state>): option<array<'state>> =>
   switch transition {
+  | Undeclared
   | Unrestricted
   | Creates(_) => None
   | Guards(states)
@@ -63,8 +77,21 @@ let allowedStates = (transition: t<'state>): option<array<'state>> =>
 /** The state the command's handler writes, or `None` for one that moves nothing. */
 let targetState = (transition: t<'state>): option<'state> =>
   switch transition {
+  | Undeclared
   | Unrestricted
   | Guards(_) => None
   | Creates(state)
   | Moves(_, state) => Some(state)
   }
+
+/** Whether the command is claimed legal in every state, as opposed to nothing
+    being claimed at all. The two erase to the same pair of `None`s above, so this
+    is the only thing that can tell a reader of the erased form which it holds. */
+let isUnrestricted = (transition: t<'state>): bool =>
+  switch transition {
+  | Unrestricted => true
+  | Undeclared
+  | Creates(_)
+  | Guards(_)
+  | Moves(_, _) => false
+  }

package/src/types/Transition.res.mjs

@@ -7,11 +7,11 @@ function allowedStates(transition) {
     return;
   }
   switch (transition.TAG) {
-    case "Creates" :
-      return;
     case "Guards" :
     case "Moves" :
       return transition._0;
+    default:
+      return;
   }
 }
 
@@ -22,15 +22,24 @@ function targetState(transition) {
   switch (transition.TAG) {
     case "Creates" :
       return Primitive_option.some(transition._0);
-    case "Guards" :
-      return;
     case "Moves" :
       return Primitive_option.some(transition._1);
+    default:
+      return;
+  }
+}
+
+function isUnrestricted(transition) {
+  if (typeof transition !== "object") {
+    return transition === "Unrestricted";
+  } else {
+    return false;
   }
 }
 
 export {
   allowedStates,
   targetState,
+  isUnrestricted,
 }
 /* No side effect */