@reventlessdev/reventless-core 3.0.0-alpha.238 → 3.0.0-alpha.240

package/src/plugin/component/Plugin_Structure.res

@@ -41,8 +41,8 @@ let rec isLifecycleShape = (t: SchemaType.schemaType): bool =>
 // and *exactly*: `customerName` holds a customer's name, not this record's.
 let conventionalLabelNames = ["name", "title", "label", "displayname"]
 
-let shapeOfItem = (~entityName: string, item: S.item): SchemaType.schemaType =>
-  SchemaType.fromSury(~parentName=entityName, ~fieldName=item.location, item.schema)
+let shapeOfField = (~entityName: string, ~name: string, schema: S.t<unknown>): SchemaType.schemaType =>
+  SchemaType.fromSury(~parentName=entityName, ~fieldName=name, schema)
 
 // Resolve the field that holds the entity's lifecycle, used to filter a per-row
 // command menu against each command's `allowedStates`. Resolution order:
@@ -69,12 +69,14 @@ let lifecycleFieldFromStateSchema = (
   | Some(_) as some => some
   | None =>
     switch stateSchema {
-    | Object({items}) =>
-      items
-      ->Array.find(item =>
-        item.location == "lifecycle" && isLifecycleShape(shapeOfItem(~entityName, item))
+    | Object({properties}) =>
+      properties
+      ->Dict.get("lifecycle")
+      ->Option.flatMap(schema =>
+        isLifecycleShape(shapeOfField(~entityName, ~name="lifecycle", schema))
+          ? Some("lifecycle")
+          : None
       )
-      ->Option.map(item => item.location)
     | _ => None
     }
   }
@@ -108,17 +110,55 @@ let retiredFieldFromStateSchema = (stateSchema: S.t<unknown>): option<string> =>
 let retiredValuesFromStateSchema = (stateSchema: S.t<unknown>): option<array<string>> =>
   retiredFromStateSchema(stateSchema)->Option.flatMap(r => r.values)
 
+// Whether a reference to a retired row of this view still resolves its name —
+// `@namedWhenRetired`. Read off the retirement rather than from a second
+// annotation, so a record cannot declare the reach of a retirement it does not
+// have; the PPX refuses that pairing, and reading it here from the same place
+// keeps the two halves agreeing by construction rather than by review.
+let namedWhenRetiredFromStateSchema = (stateSchema: S.t<unknown>): bool =>
+  retiredFromStateSchema(stateSchema)->Option.mapOr(false, r => r.namedWhenRetired)
+
+// What one record's `@retired` declaration could be told about its own field.
+//
+// Three outcomes rather than a bool, because "nothing to check" and "could not
+// check" are different facts and only the second is worth a plugin's attention.
+type retiredCheck =
+  | NotDeclared
+  // Why the names could not be compared. A fatal rule that is invisible when it
+  // does not run is the failure mode the transition check spends a counter to
+  // avoid, so this is reported rather than skipped in silence.
+  | Unchecked(string)
+  | Checked(array<string>)
+
 // The check the PPX cannot make, in the one place that can: the payload is a
 // constructor reference the PPX only ever sees as a name, and whether that name
 // is a case of the field's enum needs the schema.
 //
-// Two rules, and the second is the one the form exists for. A `value` on a field
-// that is not the record's lifecycle would keep the read narrowing while silently
-// losing the command filtering that motivates it — `@transition` is written in
-// terms of the lifecycle field, so a retirement state anywhere else is a state no
-// command can name.
-let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =>
+// Two rules, and they are held to different standards on purpose.
+//
+// **A name the field's enum does not declare is unambiguously wrong** — no domain
+// means it — and the symptom is a data-exposure bug: the retirement predicate
+// compares every row against a state no row is ever in, so every row stays
+// visible to every caller while the annotation sits on the schema looking like
+// enforcement. That is returned as a failure for the caller to raise on.
+//
+// It is the same fault the PPX already refuses to compile when the enum is
+// declared in the same file, and the PPX says so in its own message. This is the
+// residue that a per-file pass cannot reach: field form, enum imported from
+// elsewhere. Two rungs of one ladder — until this was promoted, which rung you
+// landed on decided whether a data-exposure bug stopped the build, and the
+// arbiter was where the enum happened to be declared.
+//
+// **A `value` on a field that is not the record's lifecycle stays a warning.**
+// It would keep the read narrowing while silently losing the command filtering
+// that motivates it — `@transition` is written in terms of the lifecycle field,
+// so a retirement state anywhere else is a state no command can name. That is a
+// modelling judgement rather than a wrong name, and judgement calls are what the
+// withdrawn dead-end rule taught us not to hard-fail on.
+let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): retiredCheck =>
   switch retiredFromStateSchema(stateSchema) {
+  // The boolean form names no state, so there is nothing to compare. Not a skip.
+  | None | Some({values: None}) => NotDeclared
   | Some({field, values: Some(values)}) =>
     let named = values->Array.join(", ")
     let lifecycle = lifecycleFieldFromStateSchema(~entityName, stateSchema)
@@ -133,11 +173,11 @@ let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =
       )
     }
     let declared = switch stateSchema {
-    | Object({items}) =>
-      items
-      ->Array.find(item => item.location == field)
-      ->Option.map(item =>
-        switch shapeOfItem(~entityName, item) {
+    | Object({properties}) =>
+      properties
+      ->Dict.get(field)
+      ->Option.map(schema =>
+        switch shapeOfField(~entityName, ~name=field, schema) {
         | Enum(_, values) => values
         | Nullable(Enum(_, values)) => values
         | _ => []
@@ -146,24 +186,56 @@ let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =
       ->Option.getOr([])
     | _ => []
     }
-    // Reported per state rather than as a set: one wrong entry among three still
-    // narrows something, so the symptom is a subset of rows leaking rather than
-    // all of them — which is harder to spot than the single-value case was.
-    if Array.length(declared) > 0 {
-      values
-      ->Array.filter(v => !(declared->Array.includes(v)))
-      ->Array.forEach(v =>
-        log.warn(
-          ~comp="Plugin_Structure",
-          `${entityName}: @retired(${v}) names a state "${field}" does not declare — known values: ${declared->Array.join(
-              ", ",
-            )}.`,
-        )
+    if Array.length(declared) == 0 {
+      Unchecked(
+        `${entityName}: @retired(${named}) is on "${field}", whose shape carries no cases to check the names against.`,
+      )
+    } else {
+      // Reported per state rather than as a set: one wrong entry among three still
+      // narrows something, so the symptom is a subset of rows leaking rather than
+      // all of them — which is harder to spot than the single-value case was.
+      Checked(
+        values
+        ->Array.filter(v => !(declared->Array.includes(v)))
+        ->Array.map(
+          v =>
+            `${entityName}: @retired(${v}) names a state "${field}" does not declare — known values: ${declared->Array.join(
+                ", ",
+              )}.`,
+        ),
       )
     }
-  | _ => ()
   }
 
+// Raised together, after every view has been walked, so an author sees every bad
+// name at once rather than the first one and then a rebuild.
+//
+// Retroactive in a way the transition check was not: `@transition` was new when
+// its check landed, so nothing deployed could carry a stale name, while `@retired`
+// has been shipping. A deployed plugin holding a misspelled retired value gets a
+// red build on its next deploy — which is the point, and is why the examples were
+// swept before this was promoted.
+let reportRetiredStates = (
+  ~pluginName: string,
+  ~failures: array<string>,
+  ~unchecked: array<string>,
+): unit => {
+  if Array.length(unchecked) > 0 {
+    log.warn(
+      ~comp="Plugin_Structure",
+      `${pluginName}: ${unchecked
+        ->Array.length
+        ->Int.toString} @retired declaration(s) could not be checked.\n` ++
+      unchecked->Array.join("\n"),
+    )
+  }
+  if Array.length(failures) > 0 {
+    JsError.throwWithMessage(
+      `${pluginName}: @retired names states that do not exist.\n` ++ failures->Array.join("\n"),
+    )
+  }
+}
+
 // The states a record's lifecycle field can hold. The same extraction
 // `checkRetiredValue` does, keyed on the declared lifecycle field rather than the
 // retired one — which is the field a command's `@transition` is written in terms
@@ -175,11 +247,11 @@ let lifecycleStatesFromStateSchema = (
 ): option<array<string>> =>
   lifecycleFieldFromStateSchema(~entityName, stateSchema)->Option.flatMap(field =>
     switch stateSchema {
-    | Object({items}) =>
-      items
-      ->Array.find(item => item.location == field)
-      ->Option.map(item =>
-        switch shapeOfItem(~entityName, item) {
+    | Object({properties}) =>
+      properties
+      ->Dict.get(field)
+      ->Option.map(schema =>
+        switch shapeOfField(~entityName, ~name=field, schema) {
         | Enum(_, values) => values
         | Nullable(Enum(_, values)) => values
         | _ => []
@@ -307,27 +379,21 @@ let lifecycleTopologyFindings = (
   lifecycleStatesByView
   ->Dict.toArray
   ->Array.forEach(((view, states)) => {
-    // Every edge any command declares into or out of this view's lifecycle.
-    let edges = writables->Array.reduce([], (acc, w) =>
+    // Every state some command declares a transition INTO. The question this
+    // check asks is only about arrival, so it reads the target and never the
+    // from-set — which is what lets a creating command (`@transition(() => X)`,
+    // a target and no from-set, because it runs from no row) count towards
+    // reachability the same way an edge out of another state does.
+    let reachable = writables->Array.reduce([], (acc, w) =>
       w.linkedViews->Array.includes(view)
-        ? Array.concat(
-            acc,
-            w.commands->Array.reduce([], (inner, cmd) =>
-              switch (cmd.allowedStates, cmd.targetState) {
-              | (Some(froms), Some(to)) =>
-                Array.concat(inner, froms->Array.map(from => (from, to)))
-              | _ => inner
-              }
-            ),
-          )
+        ? Array.concat(acc, w.commands->Array.filterMap(cmd => cmd.targetState))
         : acc
     )
-    if Array.length(edges) > 0 {
+    if Array.length(reachable) > 0 {
       // Rows start in the first declared state — the same convention the
       // lifecycle diagram uses — so nothing pointing at it is expected rather
       // than suspicious.
       let initial = states->Array.get(0)
-      let reachable = edges->Array.map(((_, to)) => to)
 
       states->Array.forEach(state => {
         if !(reachable->Array.includes(state)) && Some(state) != initial {
@@ -453,26 +519,26 @@ let labelFieldsFromStateSchema = (
   | Some(spec) => {field: "displayName", searchableFields: spec.fields, source: Annotation}
   | None =>
     let candidates = switch stateSchema {
-    | Object({items}) =>
-      items->Array.filter(item =>
-        item.location != "TAG" &&
-        item.location != "id" &&
-        isLabelShape(shapeOfItem(~entityName, item))
+    | Object({properties}) =>
+      properties
+      ->Dict.toArray
+      ->Array.filter(((name, schema)) =>
+        name != "TAG" && name != "id" && isLabelShape(shapeOfField(~entityName, ~name, schema))
       )
     | _ => []
     }
-    let conventional = candidates->Array.find(item => {
-      let lower = item.location->String.toLowerCase
+    let conventional = candidates->Array.find(((name, _)) => {
+      let lower = name->String.toLowerCase
       conventionalLabelNames->Array.some(n => n == lower)
     })
     let picked = switch conventional {
-    | Some(item) => Some((item, Convention))
-    | None => candidates->Array.get(0)->Option.map(item => (item, Position))
+    | Some((name, _)) => Some((name, Convention))
+    | None => candidates->Array.get(0)->Option.map(((name, _)) => (name, Position))
     }
     switch picked {
-    | Some((item, source)) => {
-        field: item.location,
-        searchableFields: [item.location],
+    | Some((name, source)) => {
+        field: name,
+        searchableFields: [name],
         source,
       }
     | None =>
@@ -543,7 +609,7 @@ let toEventDef = (v: S.t<unknown>): option<Reventless.Plugin.eventDef> => {
 
 let extractEventDefs = (eventSchema: S.t<unknown>): array<Reventless.Plugin.eventDef> =>
   switch eventSchema {
-  | Union({anyOf}) => anyOf->Array.filterMap(toEventDef)
+  | AnyOf({anyOf}) => anyOf->Array.filterMap(toEventDef)
   | _ => toEventDef(eventSchema)->Option.mapOr([], def => [def])
   }
 
@@ -557,6 +623,302 @@ let extractErrorDefs = (errorSchema: S.t<unknown>): array<Reventless.Plugin.erro
     {name, schema, references}: Reventless.Plugin.errorDef
   ))
 
+// The command walk, module-level for the same reason as the event walk above:
+// the synthetic Platform_Admin structure cannot reach `make` — it has no
+// `module(Aggregate.T)` to hand it — and hand-writing a second copy of this walk
+// is what let its command metadata drift from the SDL generated off the same
+// schema.
+
+// Aggregate commands that initialize a new aggregate instance are Collection-level
+// (shown as table-top buttons); all others are Instance-level (shown per-row).
+let isCreateCommandName = name =>
+  ["Add", "Create", "Register", "Open", "Initialize", "Submit", "Start", "Place"]->Array.some(p =>
+    name->String.startsWith(p)
+  )
+
+let commandLevelAndId = (~isAggregate, ~variantName, properties: dict<S.t<unknown>>) =>
+  if isAggregate {
+    if isCreateCommandName(variantName) {
+      (Reventless.Plugin.Collection, None)
+    } else {
+      (Reventless.Plugin.Instance, None)
+    }
+  } else {
+    let taggedFields =
+      properties
+      ->Dict.toArray
+      ->Array.filter(((fieldName, fieldSchema)) =>
+        fieldName != "TAG" &&
+          (Reventless.DcbTag.isTagged(fieldSchema) ||
+            Reventless.DcbTag.isTaggedArray(fieldSchema))
+      )
+    let taggedField =
+      taggedFields
+      ->Array.find(((_, fieldSchema)) => Reventless.DcbTag.isPartitionTag(fieldSchema))
+      ->Option.orElse(taggedFields->Array.get(0))
+    switch taggedField {
+    | Some((fieldName, _)) =>
+      if isCreateCommandName(variantName) {
+        // Creation command: Collection-level, but UUID is injected into the tagged ID field.
+        (Reventless.Plugin.Collection, Some(fieldName))
+      } else {
+        (Reventless.Plugin.Instance, Some(fieldName))
+      }
+    | None => (Reventless.Plugin.Collection, None)
+    }
+  }
+
+// A rule the server enforces, expressed as the keys a client checks against
+// `identity.groups ++ config.accessTiers`. `AllowGroups` is satisfied by ANY of
+// its groups (`Authorization.isAllowed` is `some`, not `every`), so the array is
+// an any-of and a client must read it that way.
+//
+// `AllowAuthenticated` / `AllowAnonymous` ask for nothing a client can check —
+// anyone holding a session already satisfies them — so they publish no keys
+// rather than a key everyone holds.
+//
+// `DenyAll` also publishes none, deliberately. An unsatisfiable key would render
+// as locked-with-upsell in a tiered shell: a surface advertised as purchasable
+// that no purchase unlocks. A component nobody may call belongs in no menu, and
+// that is an omission for the enumerating side to make, not a key to invent here.
+let accessKeysFor = (rule: Reventless.Authorization.permission): option<array<string>> =>
+  switch rule {
+  | AllowGroups(groups) if groups->Array.length > 0 => Some(groups)
+  | AllowGroups(_) | AllowAuthenticated | AllowAnonymous | DenyAll => None
+  }
+
+// Write each mutation argument's rendered GraphQL type onto the property it
+// belongs to, so a consumer assembling its own mutation document declares the
+// variable the server actually expects instead of guessing `String!`.
+//
+// Mutates the freshly derived schema in place — `deriveObjectSchema` has just
+// built it and nothing else holds it yet. A property with no matching
+// argument is left alone rather than annotated with a guess.
+let annotateArgTypes = (schema: JSON.t, argTypes: dict<string>): JSON.t => {
+  schema
+  ->JSON.Decode.object
+  ->Option.flatMap(o => o->Dict.get("properties"))
+  ->Option.flatMap(JSON.Decode.object)
+  ->Option.forEach(props =>
+    props
+    ->Dict.toArray
+    ->Array.forEach(((key, prop)) =>
+      switch (argTypes->Dict.get(key), prop->JSON.Decode.object) {
+      | (Some(gqlType), Some(p)) =>
+        p->Dict.set("x-reventless-graphql-type", JSON.Encode.string(gqlType))
+      | _ => ()
+      }
+    )
+  )
+  schema
+}
+
+let toCommandDef = (
+  ~isAggregate,
+  ~mutationFieldFor: string => string,
+  ~parentSchema: S.t<unknown>,
+  // The PPX-generated `command => permission`. Per VARIANT, not per component:
+  // one aggregate carries commands with very different audiences, and a
+  // component-level shortcut would gate `AddProduct` and `PlaceOrder` alike.
+  ~commandAuthorization: unknown => Reventless.Authorization.permission,
+  v: S.t<unknown>,
+): option<Reventless.Plugin.commandDef> => {
+  // Build a commandDef for one variant. `properties` is the variant's field dict —
+  // empty for a payload-less variant (e.g. `| Archive`), which compiles to a bare
+  // `S.literal("Archive")` string rather than an `{TAG, ...}` object.
+  let mkDef = (~variantName, ~properties) => {
+    let (level, aggregateIdField) = commandLevelAndId(~isAggregate, ~variantName, properties)
+    let references = extractReferences(properties)
+    // Per-variant `allowedStates` lives on the *parent* command schema
+    // (the PPX attaches a single dict<variantName, [|states|]> via
+    // markAllowedStates). Look it up by variant name; back-compat
+    // None when the variant lacks a @transition annotation.
+    let allowedStates = ApiAllowedStatesHelpers.getAllowedStates(parentSchema, ~variantName)
+    // The `@transition` target (the command's *to* status), read the same way
+    // as allowedStates. None ⇒ AutoUI's board resolver falls back to its
+    // name-stem heuristic.
+    let targetState = ApiTargetStateHelpers.getTargetState(parentSchema, ~variantName)
+    // API-exposed iff the whole command isn't @noApi and this variant
+    // isn't in its @noApi-variants set — mirrors the API-generation filter
+    // (Plugin_Helpers / PluginBaseFragment). Drives the event-graph API badge.
+    let apiExposed =
+      !ApiNoApiHelpers.isNoApi(parentSchema) &&
+      switch ApiNoApiHelpers.getExcludedVariants(parentSchema) {
+      | Some(excluded) => !(excluded->Set.has(variantName))
+      | None => true
+      }
+    // Evaluated against a synthetic value per constructor, the same shape the
+    // resolver builds at call time: a payload-bearing variant compiles to
+    // `{TAG, ...}`, a payload-less one to a bare string.
+    let syntheticCommand: unknown =
+      Reventless.DcbTag.isVariantPayloadBearing(parentSchema, variantName)
+        ? {"TAG": variantName}->Obj.magic
+        : variantName->Obj.magic
+    let requiredAccess = accessKeysFor(commandAuthorization(syntheticCommand))
+    // See the note on the record's `mutationField` for why a non-exposed
+    // variant gets the empty sentinel. It has no callable field, and the
+    // argument type names are composed *from* that field name, so there is
+    // nothing to publish for it either.
+    let mutationField = apiExposed ? mutationFieldFor(variantName) : ""
+    let jsonSchema = v->SuryToJsonSchema.deriveObjectSchema
+    let annotatedSchema = if apiExposed {
+      GraphQL_FragmentGenerator.mutationArgTypes(~fieldName=mutationField, v)->Option.mapOr(
+        jsonSchema,
+        annotateArgTypes(jsonSchema, _),
+      )
+    } else {
+      jsonSchema
+    }
+    ({
+      Reventless.Plugin.name: variantName,
+      // The derived schema, not sury's raw one: `S.toJSONSchema` carries the
+      // shape and drops every `x-reventless-*` marker the PPX put on the
+      // fields, so a command's `@storageRef`/`@semantic`/`@ref` reached the
+      // wire on the read side and nowhere on the write side. A reader that
+      // matches a field against its setter — or picks the upload endpoint of
+      // the store a command argument declares — then has nothing to match on.
+      // `MCP_SchemaGenerator` already derives these same variant schemas.
+      //
+      // Carries `x-reventless-graphql-type` per property — see
+      // `annotateArgTypes`.
+      schema: annotatedSchema->JSON.stringify,
+      level,
+      aggregateIdField,
+      // A non-exposed (`@noApi`) variant has no callable mutation field. For a
+      // single-exposed-command slice, `mutationFieldFor` resolves *every*
+      // variant — including the `@noApi` one — to the slice's one mutation
+      // field, so emitting it here would hand the non-exposed variant a
+      // sibling's callable-looking field (e.g. `ReopenOrder` →
+      // `Ordering_CancelOrder`). Emit an empty sentinel instead; the variant
+      // stays listed with `apiExposed: false` for the event-graph badge, but
+      // no consumer can mistake it for a callable field. Exposed variants are
+      // byte-identical.
+      mutationField,
+      references,
+      allowedStates,
+      targetState,
+      apiExposed: Some(apiExposed),
+      requiredAccess,
+      // Resolved from this constructor's own properties, not the union's: two
+      // commands in one slice can disagree about whether they record an owner,
+      // and the write path stamps per constructor for the same reason.
+      ownerField: Reventless.Owner.fieldNamesOfProperties(properties)->Array.get(0),
+    }: Reventless.Plugin.commandDef)
+  }
+  switch v {
+  | Object({properties}) =>
+    properties
+    ->Dict.get("TAG")
+    ->Option.flatMap(tagSchema =>
+      switch tagSchema {
+      | String({const: ?Some(variantName)}) => Some(mkDef(~variantName, ~properties))
+      | _ => None
+      }
+    )
+  // Payload-less command variants (`| Archive`) compile to a bare string literal,
+  // not an `{TAG, ...}` object. They still get a generated mutation (API generation
+  // walks the schema via extractAllVariantNames), so surface them here too —
+  // otherwise the event graph hides a command the API actually exposes.
+  | String({const: ?Some(variantName)}) => Some(mkDef(~variantName, ~properties=Dict.make()))
+  | _ => None
+  }
+}
+
+let extractCommandDefs = (
+  ~isAggregate,
+  ~mutationFieldFor: string => string,
+  ~commandAuthorization: unknown => Reventless.Authorization.permission,
+  commandSchema: S.t<unknown>,
+): array<Reventless.Plugin.commandDef> =>
+  switch commandSchema {
+  | AnyOf({anyOf}) =>
+    anyOf->Array.filterMap(v =>
+      toCommandDef(
+        ~isAggregate,
+        ~mutationFieldFor,
+        ~parentSchema=commandSchema,
+        ~commandAuthorization,
+        v,
+      )
+    )
+  | _ =>
+    // Single-variant command types compile to a bare Object schema, not a Union.
+    toCommandDef(
+      ~isAggregate,
+      ~mutationFieldFor,
+      ~parentSchema=commandSchema,
+      ~commandAuthorization,
+      commandSchema,
+    )->Option.mapOr([], def => [def])
+  }
+
+// Omitted for the default `Public` so a published def stays compact: absent and
+// "public" are the same answer, and writing one would make every ordinary view
+// carry a word that says nothing.
+let visibilityTag = (v: Reventless.Visibility.t): option<string> =>
+  switch v {
+  | Public => None
+  | Internal => Some("Internal")
+  }
+
+/**
+ A read model's published `queryableDef`, assembled from its **spec** rather than
+ from a built component.
+
+ `make` cannot serve the platform's own components: it takes
+ `module(ReadModel.T)` values, and the platform has no built module to hand
+ itself at structure-assembly time — the components it is describing are the ones
+ being assembled. That is a real constraint and this routes around it rather than
+ pretending it away, by taking the schemas the extractors actually need.
+
+ Everything here is the same helper `make` calls on the same schema, so the
+ platform's own view is described by the mechanism that describes everyone
+ else's. The alternative — a hand-written record — is what let the admin's
+ metadata drift from the SDL generated off the same spec, four times over.
+
+ `queryField` and `singleQueryField` come from `Api_Naming`, which is the only
+ place that decides how a name singularises. For the admin these are
+ byte-identical to the names it used to hand-write; `singularize` already handled
+ the plural-spec-name / singular-type shape that looked bespoke.
+ */
+let queryableDefFromSpec = (
+  ~plugin: string,
+  ~name: string,
+  ~stateSchema: S.t<unknown>,
+  ~authorization: Reventless.Authorization.permission,
+  ~visibility: Reventless.Visibility.t=Public,
+  ~consumedEventTypes: array<string>=[],
+  ~linkedWriteSide: array<string>=[],
+  ~chapter: option<string>=?,
+): Reventless.Plugin.queryableDef => {
+  let qf = Api_Naming.queryFieldNamesForReadModel(~plugin, ~name)
+  let label = labelFieldsFromStateSchema(~entityName=name, stateSchema)
+  // The same call the capability deriver makes, so the published key and the key
+  // the generated filter/order-by is built from cannot disagree.
+  let keyField = GraphQL_FragmentGenerator.resolveKeyField(~entityName=name, stateSchema)
+  {
+    Reventless.Plugin.name: name,
+    queryField: qf.listFieldName,
+    schema: stateSchema->SuryToJsonSchema.deriveObjectSchema->JSON.stringify,
+    consumedEventTypes,
+    linkedWriteSide,
+    labelField: label.field,
+    searchableFields: label.searchableFields,
+    labelFieldSource: Some(labelFieldSourceToString(label.source)),
+    lifecycleField: lifecycleFieldFromStateSchema(~entityName=name, stateSchema),
+    ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
+    retiredField: retiredFieldFromStateSchema(stateSchema),
+    retiredValues: retiredValuesFromStateSchema(stateSchema),
+    namedWhenRetired: Some(namedWhenRetiredFromStateSchema(stateSchema)),
+    visibility: visibilityTag(visibility),
+    chapter,
+    singleQueryField: Some(qf.singleFieldName),
+    idField: keyField->Option.map(((f, _)) => f),
+    idFieldSource: keyField->Option.map(((_, rung)) => rung),
+    requiredAccess: accessKeysFor(authorization),
+  }
+}
+
 let make = (
   type api role,
   ~name: string,
@@ -587,229 +949,6 @@ let make = (
   let commandVariantNames = schema => Reventless.DcbTag.extractAllVariantNames(schema)
   let qualify = (~prefix, names) => names->Array.map(n => prefix ++ "." ++ n)
 
-  // Aggregate commands that initialize a new aggregate instance are Collection-level
-  // (shown as table-top buttons); all others are Instance-level (shown per-row).
-  let isCreateCommandName = name =>
-    ["Add", "Create", "Register", "Open", "Initialize", "Submit", "Start", "Place"]->Array.some(p =>
-      name->String.startsWith(p)
-    )
-
-  let commandLevelAndId = (~isAggregate, ~variantName, properties: dict<S.t<unknown>>) =>
-    if isAggregate {
-      if isCreateCommandName(variantName) {
-        (Reventless.Plugin.Collection, None)
-      } else {
-        (Reventless.Plugin.Instance, None)
-      }
-    } else {
-      let taggedFields =
-        properties
-        ->Dict.toArray
-        ->Array.filter(((fieldName, fieldSchema)) =>
-          fieldName != "TAG" &&
-            (Reventless.DcbTag.isTagged(fieldSchema) ||
-              Reventless.DcbTag.isTaggedArray(fieldSchema))
-        )
-      let taggedField =
-        taggedFields
-        ->Array.find(((_, fieldSchema)) => Reventless.DcbTag.isPartitionTag(fieldSchema))
-        ->Option.orElse(taggedFields->Array.get(0))
-      switch taggedField {
-      | Some((fieldName, _)) =>
-        if isCreateCommandName(variantName) {
-          // Creation command: Collection-level, but UUID is injected into the tagged ID field.
-          (Reventless.Plugin.Collection, Some(fieldName))
-        } else {
-          (Reventless.Plugin.Instance, Some(fieldName))
-        }
-      | None => (Reventless.Plugin.Collection, None)
-      }
-    }
-
-  // A rule the server enforces, expressed as the keys a client checks against
-  // `identity.groups ++ config.accessTiers`. `AllowGroups` is satisfied by ANY of
-  // its groups (`Authorization.isAllowed` is `some`, not `every`), so the array is
-  // an any-of and a client must read it that way.
-  //
-  // `AllowAuthenticated` / `AllowAnonymous` ask for nothing a client can check —
-  // anyone holding a session already satisfies them — so they publish no keys
-  // rather than a key everyone holds.
-  //
-  // `DenyAll` also publishes none, deliberately. An unsatisfiable key would render
-  // as locked-with-upsell in a tiered shell: a surface advertised as purchasable
-  // that no purchase unlocks. A component nobody may call belongs in no menu, and
-  // that is an omission for the enumerating side to make, not a key to invent here.
-  let accessKeysFor = (rule: Reventless.Authorization.permission): option<array<string>> =>
-    switch rule {
-    | AllowGroups(groups) if groups->Array.length > 0 => Some(groups)
-    | AllowGroups(_) | AllowAuthenticated | AllowAnonymous | DenyAll => None
-    }
-
-  // Write each mutation argument's rendered GraphQL type onto the property it
-  // belongs to, so a consumer assembling its own mutation document declares the
-  // variable the server actually expects instead of guessing `String!`.
-  //
-  // Mutates the freshly derived schema in place — `deriveObjectSchema` has just
-  // built it and nothing else holds it yet. A property with no matching
-  // argument is left alone rather than annotated with a guess.
-  let annotateArgTypes = (schema: JSON.t, argTypes: dict<string>): JSON.t => {
-    schema
-    ->JSON.Decode.object
-    ->Option.flatMap(o => o->Dict.get("properties"))
-    ->Option.flatMap(JSON.Decode.object)
-    ->Option.forEach(props =>
-      props
-      ->Dict.toArray
-      ->Array.forEach(((key, prop)) =>
-        switch (argTypes->Dict.get(key), prop->JSON.Decode.object) {
-        | (Some(gqlType), Some(p)) =>
-          p->Dict.set("x-reventless-graphql-type", JSON.Encode.string(gqlType))
-        | _ => ()
-        }
-      )
-    )
-    schema
-  }
-
-  let toCommandDef = (
-    ~isAggregate,
-    ~mutationFieldFor: string => string,
-    ~parentSchema: S.t<unknown>,
-    // The PPX-generated `command => permission`. Per VARIANT, not per component:
-    // one aggregate carries commands with very different audiences, and a
-    // component-level shortcut would gate `AddProduct` and `PlaceOrder` alike.
-    ~commandAuthorization: unknown => Reventless.Authorization.permission,
-    v: S.t<unknown>,
-  ): option<Reventless.Plugin.commandDef> => {
-    // Build a commandDef for one variant. `properties` is the variant's field dict —
-    // empty for a payload-less variant (e.g. `| Archive`), which compiles to a bare
-    // `S.literal("Archive")` string rather than an `{TAG, ...}` object.
-    let mkDef = (~variantName, ~properties) => {
-      let (level, aggregateIdField) = commandLevelAndId(~isAggregate, ~variantName, properties)
-      let references = extractReferences(properties)
-      // Per-variant `allowedStates` lives on the *parent* command schema
-      // (the PPX attaches a single dict<variantName, [|states|]> via
-      // markAllowedStates). Look it up by variant name; back-compat
-      // None when the variant lacks a @transition annotation.
-      let allowedStates = ApiAllowedStatesHelpers.getAllowedStates(parentSchema, ~variantName)
-      // The `@transition` target (the command's *to* status), read the same way
-      // as allowedStates. None ⇒ AutoUI's board resolver falls back to its
-      // name-stem heuristic.
-      let targetState = ApiTargetStateHelpers.getTargetState(parentSchema, ~variantName)
-      // API-exposed iff the whole command isn't @noApi and this variant
-      // isn't in its @noApi-variants set — mirrors the API-generation filter
-      // (Plugin_Helpers / PluginBaseFragment). Drives the event-graph API badge.
-      let apiExposed =
-        !ApiNoApiHelpers.isNoApi(parentSchema) &&
-        switch ApiNoApiHelpers.getExcludedVariants(parentSchema) {
-        | Some(excluded) => !(excluded->Set.has(variantName))
-        | None => true
-        }
-      // Evaluated against a synthetic value per constructor, the same shape the
-      // resolver builds at call time: a payload-bearing variant compiles to
-      // `{TAG, ...}`, a payload-less one to a bare string.
-      let syntheticCommand: unknown =
-        Reventless.DcbTag.isVariantPayloadBearing(parentSchema, variantName)
-          ? {"TAG": variantName}->Obj.magic
-          : variantName->Obj.magic
-      let requiredAccess = accessKeysFor(commandAuthorization(syntheticCommand))
-      // See the note on the record's `mutationField` for why a non-exposed
-      // variant gets the empty sentinel. It has no callable field, and the
-      // argument type names are composed *from* that field name, so there is
-      // nothing to publish for it either.
-      let mutationField = apiExposed ? mutationFieldFor(variantName) : ""
-      let jsonSchema = v->SuryToJsonSchema.deriveObjectSchema
-      let annotatedSchema = if apiExposed {
-        GraphQL_FragmentGenerator.mutationArgTypes(~fieldName=mutationField, v)->Option.mapOr(
-          jsonSchema,
-          annotateArgTypes(jsonSchema, _),
-        )
-      } else {
-        jsonSchema
-      }
-      ({
-        Reventless.Plugin.name: variantName,
-        // The derived schema, not sury's raw one: `S.toJSONSchema` carries the
-        // shape and drops every `x-reventless-*` marker the PPX put on the
-        // fields, so a command's `@storageRef`/`@semantic`/`@ref` reached the
-        // wire on the read side and nowhere on the write side. A reader that
-        // matches a field against its setter — or picks the upload endpoint of
-        // the store a command argument declares — then has nothing to match on.
-        // `MCP_SchemaGenerator` already derives these same variant schemas.
-        //
-        // Carries `x-reventless-graphql-type` per property — see
-        // `annotateArgTypes`.
-        schema: annotatedSchema->JSON.stringify,
-        level,
-        aggregateIdField,
-        // A non-exposed (`@noApi`) variant has no callable mutation field. For a
-        // single-exposed-command slice, `mutationFieldFor` resolves *every*
-        // variant — including the `@noApi` one — to the slice's one mutation
-        // field, so emitting it here would hand the non-exposed variant a
-        // sibling's callable-looking field (e.g. `ReopenOrder` →
-        // `Ordering_CancelOrder`). Emit an empty sentinel instead; the variant
-        // stays listed with `apiExposed: false` for the event-graph badge, but
-        // no consumer can mistake it for a callable field. Exposed variants are
-        // byte-identical.
-        mutationField,
-        references,
-        allowedStates,
-        targetState,
-        apiExposed: Some(apiExposed),
-        requiredAccess,
-        // Resolved from this constructor's own properties, not the union's: two
-        // commands in one slice can disagree about whether they record an owner,
-        // and the write path stamps per constructor for the same reason.
-        ownerField: Reventless.Owner.fieldNamesOfProperties(properties)->Array.get(0),
-      }: Reventless.Plugin.commandDef)
-    }
-    switch v {
-    | Object({properties}) =>
-      properties
-      ->Dict.get("TAG")
-      ->Option.flatMap(tagSchema =>
-        switch tagSchema {
-        | String({const: ?Some(variantName)}) => Some(mkDef(~variantName, ~properties))
-        | _ => None
-        }
-      )
-    // Payload-less command variants (`| Archive`) compile to a bare string literal,
-    // not an `{TAG, ...}` object. They still get a generated mutation (API generation
-    // walks the schema via extractAllVariantNames), so surface them here too —
-    // otherwise the event graph hides a command the API actually exposes.
-    | String({const: ?Some(variantName)}) => Some(mkDef(~variantName, ~properties=Dict.make()))
-    | _ => None
-    }
-  }
-
-  let extractCommandDefs = (
-    ~isAggregate,
-    ~mutationFieldFor: string => string,
-    ~commandAuthorization: unknown => Reventless.Authorization.permission,
-    commandSchema: S.t<unknown>,
-  ): array<Reventless.Plugin.commandDef> =>
-    switch commandSchema {
-    | Union({anyOf}) =>
-      anyOf->Array.filterMap(v =>
-        toCommandDef(
-          ~isAggregate,
-          ~mutationFieldFor,
-          ~parentSchema=commandSchema,
-          ~commandAuthorization,
-          v,
-        )
-      )
-    | _ =>
-      // Single-variant command types compile to a bare Object schema, not a Union.
-      toCommandDef(
-        ~isAggregate,
-        ~mutationFieldFor,
-        ~parentSchema=commandSchema,
-        ~commandAuthorization,
-        commandSchema,
-      )->Option.mapOr([], def => [def])
-    }
-
   // ── Per-component event type extraction ────────────────────────────────────
 
   let scsProduced =
@@ -965,7 +1104,7 @@ let make = (
       | _ => []
       }
     switch schema {
-    | Union({anyOf}) => anyOf->Array.flatMap(fromVariant)
+    | AnyOf({anyOf}) => anyOf->Array.flatMap(fromVariant)
     | other => fromVariant(other)
     }
   }
@@ -1037,6 +1176,18 @@ let make = (
     ->Belt.Set.String.fromArray
     ->Belt.Set.String.toArray
 
+  // Two stores one edit apart are a typo that would provision twice. A hard
+  // failure, unlike the heuristic lint below: nothing downstream can see the
+  // mistake, and by deploy time both buckets exist.
+  switch Capability_Inference.collisions(requiredStoreDeclarations) {
+  | [] => ()
+  | found =>
+    JsError.throwWithMessage(
+      `${name}: two declared object stores look like one store misspelled.\n` ++
+      found->Array.map(Capability_Inference.collisionMessage)->Array.join("\n"),
+    )
+  }
+
   // Heuristic-only matches — a field *named* like a stored-object ref with no
   // `@storageRef` — warn and provision nothing. Declaration outranks inference;
   // the warning names the annotation that would settle it.
@@ -1054,12 +1205,6 @@ let make = (
   // graph and dead-code analysis — read them so an Internal view still shows up there. The
   // deployed AutoUI's consumers (Platform_ComponentDefinitionsApi menu/pages) re-filter on
   // the tag so the live UI keeps hiding them — see Visibility.res, which documents this contract.
-  let visibilityTag = (v: Reventless.Visibility.t): option<string> =>
-    switch v {
-    | Public => None
-    | Internal => Some("Internal")
-    }
-
   // View name -> the states its lifecycle field can hold, collected as the view
   // defs are built so the transition check below has both sides in one place.
   let lifecycleStatesByView: dict<array<string>> = Dict.make()
@@ -1071,6 +1216,17 @@ let make = (
     }
   }
 
+  // Collected as the view defs are built and reported once, so a plugin with
+  // three bad names fails naming three rather than one at a time.
+  let retiredFailures = []
+  let retiredUnchecked = []
+  let recordRetired = (~entityName, stateSchema) =>
+    switch checkRetiredValue(~entityName, stateSchema) {
+    | NotDeclared => ()
+    | Unchecked(why) => retiredUnchecked->Array.push(why)->ignore
+    | Checked(failures) => failures->Array.forEach(f => retiredFailures->Array.push(f)->ignore)
+    }
+
   let readModelDefs =
     readModels
     ->Array.map((
@@ -1090,7 +1246,7 @@ let make = (
       // edges for any event reaching the read model via a DCB-log-sourced mapping (a classic
       // aggregate→view link is also drawn from the producer's linkedViews, deduped downstream).
       let consumed = qualify(~prefix=name, R.consumedEventNames)
-      checkRetiredValue(~entityName=R.Spec.name, stateSchema)
+      recordRetired(~entityName=R.Spec.name, stateSchema)
       recordLifecycle(~entityName=R.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: R.Spec.name,
@@ -1107,6 +1263,7 @@ let make = (
         ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
         retiredField: retiredFieldFromStateSchema(stateSchema),
         retiredValues: retiredValuesFromStateSchema(stateSchema),
+        namedWhenRetired: Some(namedWhenRetiredFromStateSchema(stateSchema)),
         visibility: visibilityTag(R.Spec.visibility),
         chapter: chapterOf(R.Spec.name),
         // Taken from the `qf` record, never re-derived: `Api_Naming` is the only
@@ -1129,7 +1286,7 @@ let make = (
         ~entityName=SVS.Spec.name,
         stateSchema,
       )
-      checkRetiredValue(~entityName=SVS.Spec.name, stateSchema)
+      recordRetired(~entityName=SVS.Spec.name, stateSchema)
       recordLifecycle(~entityName=SVS.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: SVS.Spec.name,
@@ -1144,6 +1301,7 @@ let make = (
         ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
         retiredField: retiredFieldFromStateSchema(stateSchema),
         retiredValues: retiredValuesFromStateSchema(stateSchema),
+        namedWhenRetired: Some(namedWhenRetiredFromStateSchema(stateSchema)),
         visibility: visibilityTag(SVS.Spec.visibility),
         chapter: chapterOf(SVS.Spec.name),
         singleQueryField: Some(qf.singleFieldName),
@@ -1313,6 +1471,10 @@ let make = (
     ~writables=Array.concat(stateChangeDefs, aggregateDefs),
     ~lifecycleStatesByView,
   )
+  // Also a second pass, for a different reason: the failures are gathered per
+  // view as those defs are built, and raising inline would report the first bad
+  // name and hide the rest.
+  reportRetiredStates(~pluginName=name, ~failures=retiredFailures, ~unchecked=retiredUnchecked)
 
   {
     readModels: readModelDefs,