@reventlessdev/reventless-core 3.0.0-alpha.255 → 3.0.0-alpha.257

package/src/components/Api/SuryToJsonSchema.res

@@ -176,33 +176,72 @@ let rec isNullableType = (st: SchemaType.schemaType): bool =>
   | _ => false
   }
 
-let rec fromSchemaType = (st: SchemaType.schemaType): JSON.t =>
+// The GraphQL **input** type name an object is declared under, written onto the
+// object's own JSON Schema wherever it occurs.
+//
+// A client that assembles a mutation must name its variables' types, and for a
+// *top-level* argument `x-reventless-graphql-type` already publishes the rendered
+// reference (`[Ordering_PlaceOrderLineItems!]!`, wrappers and all). That one is
+// keyed by argument name and so stops at the first level; this one travels with
+// the object, which is what a reader reaching an element schema inside a list has.
+//
+// The name is taken from the `ObjectRef` the SDL emitter names the type from, so
+// there is one source and the two cannot drift — but only when the caller rooted
+// the walk at the same prefix the emitter uses. That is what `inputNames` gates:
+// a schema walked from an unknown root would publish a name the SDL never
+// declares, and a plausible wrong name is worse than none.
+let withGraphqlInput = (schema: JSON.t, name: string): JSON.t =>
+  switch schema->JSON.Decode.object {
+  | None => schema
+  | Some(obj) =>
+    obj->Dict.set("x-reventless-graphql-input", str(name))
+    JSON.Encode.object(obj)
+  }
+
+let rec fromSchemaType = (~inputNames: bool=false, st: SchemaType.schemaType): JSON.t =>
   switch st {
   | ScalarString => jsonObject([("type", str("string"))])
   | ScalarNumber => jsonObject([("type", str("number"))])
+  | ScalarInt => jsonObject([("type", str("integer"))])
   | ScalarBoolean => jsonObject([("type", str("boolean"))])
   | ScalarBigInt => jsonObject([("type", str("integer"))])
   | EntityId => jsonObject([("type", str("string")), ("format", str("uuid"))])
   | DateTime => jsonObject([("type", str("string")), ("format", str("date-time"))])
   | Nullable(inner) =>
-    let innerSchema = fromSchemaType(inner)
+    let innerSchema = fromSchemaType(~inputNames, inner)
     jsonObject([("oneOf", JSON.Encode.array([innerSchema, jsonObject([("type", str("null"))])]))])
   | ArrayOf(item) =>
-    jsonObject([("type", str("array")), ("items", fromSchemaType(item))])
-  | ObjectRef(_, fields) => objectRefToJsonSchema(fields)
+    jsonObject([("type", str("array")), ("items", fromSchemaType(~inputNames, item))])
+  | ObjectRef(name, fields) =>
+    let base = objectRefToJsonSchema(~inputNames, fields)
+    inputNames ? base->withGraphqlInput(name) : base
   | Enum(_, values) =>
     jsonObject([
       ("type", str("string")),
       ("enum", JSON.Encode.array(values->Array.map(JSON.Encode.string))),
     ])
-  | Semantic(sem, inner) => fromSchemaType(inner)->withSemantic(sem)
+  // A semantic composite is one named type wherever it appears, and GraphQL
+  // forbids one name serving as both an object and an input — so in input
+  // position it is the `Input`-suffixed name that exists in the SDL, which is
+  // the one a client can paste into a variable declaration. Positionally-named
+  // objects take no suffix, so the `ObjectRef` branch above already published
+  // the right string for them.
+  | Semantic(sem, inner) =>
+    let base = fromSchemaType(~inputNames, inner)
+    let base = switch (inputNames, SchemaType.canonicalName(sem.id), inner) {
+    | (true, Some(name), ObjectRef(_, _)) => base->withGraphqlInput(name ++ "Input")
+    | _ => base
+    }
+    base->withSemantic(sem)
+  // A union has no input form — see the fragment generator, which emits `String`
+  // and says so — hence no name to publish on either arm.
   // A union is `oneOf` its arms, each an object carrying the `TAG` const it is
   // discriminated by. The discriminator is what tells a union apart from a
   // nullable object, which is also a `oneOf` of objects — a reader that misses
   // it selects one arm's fields as though they were the field's own and produces
   // a query that looks plausible and is invalid.
   | TaggedUnion(name, arms) =>
-    let members = arms->Array.map(((tag, armType)) => armToJsonSchema(~tag, armType))
+    let members = arms->Array.map(((tag, armType)) => armToJsonSchema(~inputNames, ~tag, armType))
     jsonObject([("oneOf", JSON.Encode.array(members)), ("x-reventless-union", str(name))])
   | Unknown => jsonObject([("type", str("string"))])
   }
@@ -212,10 +251,14 @@ let rec fromSchemaType = (st: SchemaType.schemaType): JSON.t =>
 // the payload that says which arm this is. The GraphQL member type name rides
 // alongside so a reader mapping a raw payload to a selection does not have to
 // re-derive the naming rule in a second repo.
-and armToJsonSchema = (~tag: string, armType: SchemaType.schemaType): JSON.t =>
+and armToJsonSchema = (
+  ~inputNames: bool=false,
+  ~tag: string,
+  armType: SchemaType.schemaType,
+): JSON.t =>
   switch armType {
   | ObjectRef(memberName, fields) =>
-    let base = objectRefToJsonSchema(fields)
+    let base = objectRefToJsonSchema(~inputNames, fields)
     switch base->JSON.Decode.object {
     | Some(obj) =>
       switch obj->Dict.get("properties")->Option.flatMap(JSON.Decode.object) {
@@ -232,7 +275,7 @@ and armToJsonSchema = (~tag: string, armType: SchemaType.schemaType): JSON.t =>
       JSON.Encode.object(obj)
     | None => base
     }
-  | other => fromSchemaType(other)
+  | other => fromSchemaType(~inputNames, other)
   }
 
 // Attach a type-carried semantic to a field's JSON Schema.
@@ -313,11 +356,17 @@ and withSemantic = (fieldSchema: JSON.t, sem: Reventless.Semantic.t): JSON.t =>
 // way — off the sury schema by the caller. What it marks is a field whose value
 // must not be rendered into content somebody receives, which is a property of
 // the domain model rather than of the field's shape.
+// `inputNames` says which side of the wire this schema describes. It changes only
+// the name a semantic composite is published under — `MoneyInput` where a command
+// takes one, `Money` where a view returns one — because GraphQL forbids one name
+// serving as both. Emitting the input name on a view would name a type that need
+// not exist in the SDL at all.
 and objectRefToJsonSchema = (
   ~annotations: option<Reventless.StateAnnotations.stateAnnotationSpec>=?,
   ~optional: array<string>=[],
   ~owners: array<string>=[],
   ~sensitive: array<string>=[],
+  ~inputNames: bool=false,
   fields: dict<SchemaType.schemaType>,
 ): JSON.t => {
   let props = Dict.make()
@@ -336,7 +385,7 @@ and objectRefToJsonSchema = (
   ->Dict.toArray
   ->Array.filter(((fieldName, _)) => !(internal->Array.includes(fieldName)))
   ->Array.forEach(((fieldName, fieldType)) => {
-    let baseSchema = fromSchemaType(fieldType)
+    let baseSchema = fromSchemaType(~inputNames, fieldType)
     let withAnnotations = switch annotations {
     | Some(spec) => mergeAnnotations(baseSchema, fieldName, spec)
     | None => baseSchema
@@ -394,8 +443,16 @@ and objectRefToJsonSchema = (
 
 // ── Public API (sury → JSON Schema via SchemaType) ───────────────────────
 
-let deriveObjectSchema = (schema: S.t<unknown>): JSON.t =>
-  switch SchemaType.fromSuryObject(~typeName="", schema) {
+// `typeName` roots the walk where the SDL emitter roots its own — the mutation
+// field name for a command — so the nested type names this publishes are the
+// ones the SDL declares. It is only consulted when `inputNames` asks for those
+// names; every other caller leaves both alone and gets today's schema exactly.
+let deriveObjectSchema = (
+  ~inputNames: bool=false,
+  ~typeName: string="",
+  schema: S.t<unknown>,
+): JSON.t =>
+  switch SchemaType.fromSuryObject(~typeName, schema) {
   | Some(fields) =>
     let annotations = Reventless.StateAnnotations.getSpec(schema)
     let objSchema = objectRefToJsonSchema(
@@ -403,6 +460,7 @@ let deriveObjectSchema = (schema: S.t<unknown>): JSON.t =>
       ~optional=SchemaType.optionalFieldNames(schema),
       ~owners=Reventless.Owner.fieldNames(schema),
       ~sensitive=Reventless.Sensitive.fieldNames(schema),
+      ~inputNames,
       fields,
     )
     // Surface component-level hints on the top-level object schema.

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

@@ -160,7 +160,18 @@ function isNullableType(_st) {
   };
 }
 
-function fromSchemaType(st) {
+function withGraphqlInput(schema, name) {
+  let obj = Stdlib_JSON.Decode.object(schema);
+  if (obj !== undefined) {
+    obj["x-reventless-graphql-input"] = name;
+    return obj;
+  } else {
+    return schema;
+  }
+}
+
+function fromSchemaType(inputNamesOpt, st) {
+  let inputNames = inputNamesOpt !== undefined ? inputNamesOpt : false;
   if (typeof st !== "object") {
     switch (st) {
       case "ScalarNumber" :
@@ -173,6 +184,7 @@ function fromSchemaType(st) {
             "type",
             "boolean"
           ]]);
+      case "ScalarInt" :
       case "ScalarBigInt" :
         return Object.fromEntries([[
             "type",
@@ -210,7 +222,7 @@ function fromSchemaType(st) {
   } else {
     switch (st.TAG) {
       case "Nullable" :
-        let innerSchema = fromSchemaType(st._0);
+        let innerSchema = fromSchemaType(inputNames, st._0);
         return Object.fromEntries([[
             "oneOf",
             [
@@ -229,11 +241,16 @@ function fromSchemaType(st) {
           ],
           [
             "items",
-            fromSchemaType(st._0)
+            fromSchemaType(inputNames, st._0)
           ]
         ]);
       case "ObjectRef" :
-        return objectRefToJsonSchema(undefined, undefined, undefined, undefined, st._1);
+        let base = objectRefToJsonSchema(undefined, undefined, undefined, undefined, inputNames, st._1);
+        if (inputNames) {
+          return withGraphqlInput(base, st._0);
+        } else {
+          return base;
+        }
       case "Enum" :
         return Object.fromEntries([
           [
@@ -246,9 +263,14 @@ function fromSchemaType(st) {
           ]
         ]);
       case "Semantic" :
-        return withSemantic(fromSchemaType(st._1), st._0);
+        let inner = st._1;
+        let sem = st._0;
+        let base$1 = fromSchemaType(inputNames, inner);
+        let match = SchemaType$ReventlessCore.canonicalName(sem.id);
+        let base$2 = inputNames && match !== undefined && typeof inner === "object" && inner.TAG === "ObjectRef" ? withGraphqlInput(base$1, match + "Input") : base$1;
+        return withSemantic(base$2, sem);
       case "TaggedUnion" :
-        let members = st._1.map(param => armToJsonSchema(param[0], param[1]));
+        let members = st._1.map(param => armToJsonSchema(inputNames, param[0], param[1]));
         return Object.fromEntries([
           [
             "oneOf",
@@ -263,14 +285,15 @@ function fromSchemaType(st) {
   }
 }
 
-function armToJsonSchema(tag, armType) {
+function armToJsonSchema(inputNamesOpt, tag, armType) {
+  let inputNames = inputNamesOpt !== undefined ? inputNamesOpt : false;
   if (typeof armType !== "object") {
-    return fromSchemaType(armType);
+    return fromSchemaType(inputNames, armType);
   }
   if (armType.TAG !== "ObjectRef") {
-    return fromSchemaType(armType);
+    return fromSchemaType(inputNames, armType);
   }
-  let base = objectRefToJsonSchema(undefined, undefined, undefined, undefined, armType._1);
+  let base = objectRefToJsonSchema(undefined, undefined, undefined, undefined, inputNames, armType._1);
   let obj = Stdlib_JSON.Decode.object(base);
   if (obj === undefined) {
     return base;
@@ -341,17 +364,18 @@ function withSemantic(fieldSchema, sem) {
   return obj;
 }
 
-function objectRefToJsonSchema(annotations, optionalOpt, ownersOpt, sensitiveOpt, fields) {
+function objectRefToJsonSchema(annotations, optionalOpt, ownersOpt, sensitiveOpt, inputNamesOpt, fields) {
   let optional = optionalOpt !== undefined ? optionalOpt : [];
   let owners = ownersOpt !== undefined ? ownersOpt : [];
   let sensitive = sensitiveOpt !== undefined ? sensitiveOpt : [];
+  let inputNames = inputNamesOpt !== undefined ? inputNamesOpt : false;
   let props = {};
   let required = [];
   let internal = Stdlib_Option.getOr(Stdlib_Option.flatMap(annotations, spec => spec.internal), []);
   Object.entries(fields).filter(param => !internal.includes(param[0])).forEach(param => {
     let fieldType = param[1];
     let fieldName = param[0];
-    let baseSchema = fromSchemaType(fieldType);
+    let baseSchema = fromSchemaType(inputNames, fieldType);
     let withAnnotations = annotations !== undefined ? mergeAnnotations(baseSchema, fieldName, annotations) : baseSchema;
     let withAnnotations$1;
     if (owners.includes(fieldName)) {
@@ -401,8 +425,10 @@ function objectRefToJsonSchema(annotations, optionalOpt, ownersOpt, sensitiveOpt
   return Object.fromEntries(entries);
 }
 
-function deriveObjectSchema(schema) {
-  let fields = SchemaType$ReventlessCore.fromSuryObject("", schema);
+function deriveObjectSchema(inputNamesOpt, typeNameOpt, schema) {
+  let inputNames = inputNamesOpt !== undefined ? inputNamesOpt : false;
+  let typeName = typeNameOpt !== undefined ? typeNameOpt : "";
+  let fields = SchemaType$ReventlessCore.fromSuryObject(typeName, schema);
   if (fields === undefined) {
     return Object.fromEntries([[
         "type",
@@ -410,7 +436,7 @@ function deriveObjectSchema(schema) {
       ]]);
   }
   let annotations = StateAnnotations$Reventless.getSpec(schema);
-  let objSchema = objectRefToJsonSchema(annotations, SchemaType$ReventlessCore.optionalFieldNames(schema), Owner$Reventless.fieldNames(schema), Sensitive$Reventless.fieldNames(schema), fields);
+  let objSchema = objectRefToJsonSchema(annotations, SchemaType$ReventlessCore.optionalFieldNames(schema), Owner$Reventless.fieldNames(schema), Sensitive$Reventless.fieldNames(schema), inputNames, fields);
   if (annotations === undefined) {
     return objSchema;
   }
@@ -434,7 +460,7 @@ function deriveObjectSchema(schema) {
 }
 
 function toJsonSchema(schema) {
-  return fromSchemaType(SchemaType$ReventlessCore.fromSury("", "", schema));
+  return fromSchemaType(undefined, SchemaType$ReventlessCore.fromSury("", "", schema));
 }
 
 export {
@@ -444,6 +470,7 @@ export {
   withOptionalPlugin,
   mergeAnnotations,
   isNullableType,
+  withGraphqlInput,
   fromSchemaType,
   armToJsonSchema,
   withSemantic,

package/src/components/StateChangeSlice/StateChangeSlice_Callback.res

@@ -37,8 +37,8 @@ module Make = (
     // Encode through the event schema (like the Aggregate path's Message.encode),
     // NOT JSON.stringifyAny: the runtime representation drops `None` option
     // fields entirely, while the consumer side (DcbDecode) parses with the sury
-    // schema — a js_nullable option field would reject the missing key and the
-    // event would be dropped as schema drift.
+    // schema — an encoding that writes `null` for an absent field would reject the
+    // missing key and the event would be dropped as schema drift.
     let json = event->Reventless.Util_Sury.toJson(Spec.eventSchema)
     let (eventType, data) = json->Message.splitMessage
     // Use `extractTagsExpanded` (not `extractTags`) so per-element tags on
@@ -313,9 +313,14 @@ module Make = (
         )
       })
       ->Effect.flatMap(((state, headPosition, _)) =>
+        // Identity, not content: the decision model folds the whole matched
+        // history, so serialising it here makes the line's size a function of
+        // how long the entity has been in use.
         EffectLogger.logDebug(
           ~comp,
-          `deciding on state: ${state->JSON.stringifyAny->Option.getOr("<unserializable>")}`,
+          `deciding: id=${entityId->Option.getOr("-")} head=${headPosition->Option.getOr(
+              "-",
+            )} cmd=${cmdJson->LogFormat.cmdName}`,
         )->Effect.flatMap(_ =>
           switch Behavior.decide(state, command'.command) {
           | Ok(newEvents) if newEvents->Array.length == 0 =>

package/src/components/StateChangeSlice/StateChangeSlice_Callback.res.mjs

@@ -164,7 +164,7 @@ function Make(Spec) {
         }), param => {
           let headPosition = param[1];
           let state = param[0];
-          return Effect.flatMap(EffectLogger$ReventlessCore.logDebug(comp, undefined, `deciding on state: ` + Stdlib_Option.getOr(JSON.stringify(state), "<unserializable>")), () => {
+          return Effect.flatMap(EffectLogger$ReventlessCore.logDebug(comp, undefined, `deciding: id=` + Stdlib_Option.getOr(entityId, "-") + ` head=` + Stdlib_Option.getOr(headPosition, "-") + ` cmd=` + LogFormat$ReventlessCore.cmdName(cmdJson)), () => {
             let newEvents = Behavior.decide(state, command$p.command);
             if (newEvents.TAG === "Ok") {
               let newEvents$1 = newEvents._0;

package/src/plugin/component/Plugin.res

@@ -52,6 +52,7 @@ module type T = {
     ~extensions: array<module(ReventlessInfra.Extension.Blueprint)>=?,
     ~extensionPoints: array<module(ReventlessInfra.ExtensionPointMapping.Mapping)>=?,
     ~componentChapters: dict<string>=?,
+    ~lifecycleModel: array<Reventless.Plugin.derivedEdge>=?,
   ) => Reventless.Plugin.pluginStructure
 }
 

package/src/plugin/component/Plugin_Builder.res

@@ -1104,6 +1104,7 @@ module Make = (
     ~extensions: array<module(ReventlessInfra.Extension.Blueprint)>=[],
     ~extensionPoints: array<module(ReventlessInfra.ExtensionPointMapping.Mapping)>=[],
     ~componentChapters: dict<string>=Dict.make(),
+    ~lifecycleModel: array<Reventless.Plugin.derivedEdge>=[],
   ): Reventless.Plugin.pluginStructure =>
     Plugin_Structure.make(
       ~name,
@@ -1117,6 +1118,7 @@ module Make = (
       ~extensions,
       ~extensionPoints,
       ~componentChapters,
+      ~lifecycleModel,
     )
 
   let make = (

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

@@ -95,7 +95,7 @@ function Make(Spec) {
         pages: pages
       };
     };
-    let makePluginDefinition = (name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChangeSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, extensionsOpt, extensionPointsOpt, componentChaptersOpt) => {
+    let makePluginDefinition = (name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChangeSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, extensionsOpt, extensionPointsOpt, componentChaptersOpt, lifecycleModelOpt) => {
       let aggregates = aggregatesOpt !== undefined ? aggregatesOpt : [];
       let readModels = readModelsOpt !== undefined ? readModelsOpt : [];
       let stateViewSlices = stateViewSlicesOpt !== undefined ? stateViewSlicesOpt : [];
@@ -106,7 +106,8 @@ function Make(Spec) {
       let extensions = extensionsOpt !== undefined ? extensionsOpt : [];
       let extensionPoints = extensionPointsOpt !== undefined ? extensionPointsOpt : [];
       let componentChapters = componentChaptersOpt !== undefined ? componentChaptersOpt : ({});
-      return Plugin_Structure$ReventlessCore.make(name, aggregates, readModels, stateViewSlices, stateChangeSlices, automationSlices, outboundTranslationSlices, inboundTranslationSlices, extensions, extensionPoints, componentChapters);
+      let lifecycleModel = lifecycleModelOpt !== undefined ? lifecycleModelOpt : [];
+      return Plugin_Structure$ReventlessCore.make(name, aggregates, readModels, stateViewSlices, stateChangeSlices, automationSlices, outboundTranslationSlices, inboundTranslationSlices, extensions, extensionPoints, componentChapters, lifecycleModel);
     };
     let make = (name, heartbeatInterval, extensionPointsOpt, extensionsOpt, aggregatesOpt, readModelsOpt, tasksOpt, stateChangeSlicesOpt, stateViewSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, systemCallableComponentsOpt, componentRuntimeOpt, uiFragments, pluginStructure, opts) => {
       let extensionPoints = extensionPointsOpt !== undefined ? extensionPointsOpt : [];

package/src/plugin/component/Plugin_Structure.res

@@ -4,6 +4,10 @@
 
 let log = Logger.fromEnv()
 
+// Set by `check:lifecycle`, and by nothing else. See the note where it is read.
+@val external _declaredTransitionsOnly: option<string> = "process.env.REVENTLESS_DECLARED_TRANSITIONS_ONLY"
+let declaredTransitionsOnly = _declaredTransitionsOnly->Option.isSome
+
 // Whether a field can name a record, stated over `SchemaType`'s IR so every
 // shape it grows is excluded before it exists. `Nullable` unwraps; a `Semantic`
 // wrapper is refused — a bucket key or URL is not prose.
@@ -413,6 +417,15 @@ let checkDeclaredTransitions = (
         if Array.length(known) == 0 {
           unvalidated := unvalidated.contents + 1
         } else {
+          // Said, because the two are fixed differently: an authored edge is
+          // edited, a harvested one is re-derived. A harvested state the view no
+          // longer declares means the committed model went stale, and stopping is
+          // right — published, it would offer the command on no row at all.
+          let hint = switch cmd.allowedStatesSource {
+          | Some("derived") =>
+            " This edge came from the component's own scenarios, so the committed lifecycle model is stale."
+          | _ => ""
+          }
           declared
           ->Array.filter(state => !(known->Array.includes(state)))
           ->Array.forEach(state =>
@@ -421,7 +434,7 @@ let checkDeclaredTransitions = (
               `${w.name}.${cmd.name} declares state "${state}", which none of its ` ++
               `linked views declare — ${w.linkedViews->Array.join(
                   ", ",
-                )} know ${known->Array.join(", ")}.`,
+                )} know ${known->Array.join(", ")}.${hint}`,
             )
             ->ignore
           )
@@ -443,7 +456,7 @@ let checkDeclaredTransitions = (
 
   if Array.length(failures) > 0 {
     JsError.throwWithMessage(
-      `${pluginName}: a declared transition names states that do not exist.\n` ++
+      `${pluginName}: a transition names states that do not exist.\n` ++
       failures->Array.join("\n"),
     )
   }
@@ -580,10 +593,18 @@ let extractReferences = (properties: dict<S.t<unknown>>): array<
 > =>
   properties
   ->Dict.toArray
-  ->Array.filterMap(((fieldName, fieldSchema)) =>
-    Reventless.Reference.getFieldTarget(fieldSchema)->Option.map(target => (
+  ->Array.flatMap(((fieldName, fieldSchema)) =>
+    // `collectFieldTargets`, not `getFieldTarget`: a reference declared on a field
+    // of a record the field holds (an order line's `productId`) is one this
+    // command declares, and it arrives named by its own path. Commands and events
+    // both come through here, which is what stops one of them learning about
+    // nesting and the other not.
+    Reventless.Reference.collectFieldTargets(fieldName, fieldSchema)->Array.map(((
+      path,
+      target,
+    )) => (
       {
-        Reventless.Plugin.fieldName,
+        Reventless.Plugin.fieldName: path,
         entity: target.entity,
         plugin: target.plugin,
       }: Reventless.Plugin.fieldReference
@@ -637,6 +658,10 @@ let extractErrorDefs = (errorSchema: S.t<unknown>): array<Reventless.Plugin.erro
 
 // Aggregate commands that initialize a new aggregate instance are Collection-level
 // (shown as table-top buttons); all others are Instance-level (shown per-row).
+//
+// A guess from the command's name stem, and it misreads `Enroll`, `Provision`,
+// `Onboard`. It answers only where the harvested model does not: a plugin with no
+// corpus, or one whose linked views declare no lifecycle to label a history with.
 let isCreateCommandName = name =>
   ["Add", "Create", "Register", "Open", "Initialize", "Submit", "Start", "Place"]->Array.some(p =>
     name->String.startsWith(p)
@@ -724,13 +749,17 @@ let toCommandDef = (
   // (see the call sites below), so `Transition` itself asserts nothing about
   // representation and stays parameterised all the way down.
   ~commandTransition: unknown => Reventless.Transition.t<string>,
+  // What this component's own scenarios say about each command, harvested at
+  // build time and committed beside the plugin. `None` for a command no corpus
+  // covers, which is most of them in a plugin that ships no tests.
+  ~derivedEdgeFor: string => option<Reventless.Plugin.derivedEdge>,
   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 (guessedLevel, aggregateIdField) = commandLevelAndId(~isAggregate, ~variantName, properties)
     let references = extractReferences(properties)
     // Evaluated against a synthetic value per constructor, the same shape the
     // resolver builds at call time: a payload-bearing variant compiles to
@@ -742,12 +771,57 @@ let toCommandDef = (
     // The spec's own switch, which is exhaustive — so it also speaks for a
     // constructor the host did not declare but spliced from a trait.
     //
-    // An edge is ONE declaration, so the two fields are read off it together.
     // `targetState: None` ⇒ AutoUI's board resolver falls back to its name-stem
     // heuristic.
     let declared = commandTransition(syntheticCommand)
-    let allowedStates = Reventless.Transition.allowedStates(declared)
-    let targetState = Reventless.Transition.targetState(declared)
+    let derived = derivedEdgeFor(variantName)
+
+    // Where the scenarios answer, they answer; where they are silent, the
+    // annotation stands. The halves are resolved separately because they are
+    // silent separately — a corpus routinely shows a command taking effect
+    // without ever showing where it lands — and because an empty derivation is
+    // not a derivation: `Some([])` matches no row's lifecycle tag, so publishing
+    // one offers the command on no row at all while the annotation that would
+    // have been right sits unread beside it.
+    //
+    // The one claim the scenarios may not answer for is `Unrestricted`: it says
+    // the command is legal in EVERY state, and a corpus only covers the states
+    // somebody wrote a scenario for, so deriving a from-set there would shrink a
+    // deliberate claim to an accident of coverage and withdraw the command from
+    // the rows nobody tested. `Undeclared` — the ppx's injected default — erases
+    // to the same pair of `None`s and is silence, which the scenarios may answer.
+    let unrestricted = Reventless.Transition.isUnrestricted(declared)
+    let (allowedStates, allowedStatesSource) = switch (
+      unrestricted
+        ? None
+        : derived->Option.flatMap(d =>
+            Array.length(d.allowedStates) > 0 ? Some(d.allowedStates) : None
+          ),
+      Reventless.Transition.allowedStates(declared),
+    ) {
+    | (Some(observed), _) => (Some(observed), Some("derived"))
+    | (None, Some(states)) => (Some(states), Some("declared"))
+    | (None, None) => (None, unrestricted ? Some("unrestricted") : None)
+    }
+    // The target is not protected the same way, because the two halves fail
+    // differently: a from-set RESTRICTS, and narrowing one wrongly takes a
+    // command away from rows it belongs on, while a target only tells a diagram
+    // where an edge lands. Supplying one the author left unstated adds
+    // information and withdraws nothing — which is what `Customer.Register`'s
+    // "the row's status is the view's to derive" asks for.
+    let targetState = switch derived->Option.flatMap(d =>
+      // Two observed targets are an edge `targetState` cannot express. Reported
+      // as a contradiction by the harvest; here the declaration is left to speak
+      // rather than one of the two picked.
+      switch d.targets {
+      | [only] => Some(only)
+      | _ => None
+      }
+    ) {
+    | Some(observed) => Some(observed)
+    | None => Reventless.Transition.targetState(declared)
+    }
+    let level = derived->Option.flatMap(d => d.level)->Option.getOr(guessedLevel)
     // 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.
@@ -763,7 +837,12 @@ let toCommandDef = (
     // 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
+    // Rooted at the mutation field, and asking for the input type names, so an
+    // object nested inside an argument (an order line inside `lineItems`) carries
+    // the name the SDL declares it under — which `x-reventless-graphql-type`, keyed
+    // by top-level argument, has no place to put.
+    let jsonSchema =
+      v->SuryToJsonSchema.deriveObjectSchema(~inputNames=apiExposed, ~typeName=mutationField)
     let annotatedSchema = if apiExposed {
       GraphQL_FragmentGenerator.mutationArgTypes(~fieldName=mutationField, v)->Option.mapOr(
         jsonSchema,
@@ -785,6 +864,7 @@ let toCommandDef = (
       references,
       allowedStates,
       targetState,
+      allowedStatesSource: ?allowedStatesSource,
       apiExposed: Some(apiExposed),
       requiredAccess,
       // Resolved from this constructor's own properties, not the union's: two
@@ -817,6 +897,7 @@ let extractCommandDefs = (
   ~mutationFieldFor: string => string,
   ~commandAuthorization: unknown => Reventless.Authorization.permission,
   ~commandTransition: unknown => Reventless.Transition.t<string>,
+  ~derivedEdgeFor: string => option<Reventless.Plugin.derivedEdge>=_ => None,
   commandSchema: S.t<unknown>,
 ): array<Reventless.Plugin.commandDef> =>
   switch commandSchema {
@@ -828,6 +909,7 @@ let extractCommandDefs = (
         ~parentSchema=commandSchema,
         ~commandAuthorization,
         ~commandTransition,
+        ~derivedEdgeFor,
         v,
       )
     )
@@ -839,6 +921,7 @@ let extractCommandDefs = (
       ~parentSchema=commandSchema,
       ~commandAuthorization,
       ~commandTransition,
+      ~derivedEdgeFor,
       commandSchema,
     )->Option.mapOr([], def => [def])
   }
@@ -911,8 +994,18 @@ let make = (
   // Component name → chapter, captured from each component's source folder by the
   // plugin generator. Keyed by `Spec.name`; no entry renders flat.
   ~componentChapters: dict<string>=Dict.make(),
+  // What the plugin's own scenarios say about each command's lifecycle edge,
+  // harvested by `check:lifecycle` and committed as `src/LifecycleModel.res`.
+  ~lifecycleModel: array<Reventless.Plugin.derivedEdge>=[],
 ): Reventless.Plugin.pluginStructure => {
   let chapterOf = (compName: string): option<string> => componentChapters->Dict.get(compName)
+  // The harvest compares its own reading of the corpus with the DECLARATION, so
+  // it needs a structure the model has not already been folded into. Reading a
+  // derived value back as though it were the claim would confirm every edge and
+  // hide exactly the disagreements the check exists to find.
+  let model = declaredTransitionsOnly ? [] : lifecycleModel
+  let derivedEdgeFor = (~component: string, command: string) =>
+    model->Array.find(e => e.component == component && e.command == command)
   // Payload-less variants dropped: the graph must not claim an edge a DCB lookup
   // cannot WHERE-clause on.
   let eventVariantNames = schema => Reventless.DcbTag.extractVariantNames(schema)
@@ -1391,6 +1484,7 @@ let make = (
             ),
           ~commandAuthorization=SCS.Spec.commandAuthorization->Obj.magic,
           ~commandTransition=SCS.Spec.commandTransition->Obj.magic,
+          ~derivedEdgeFor=derivedEdgeFor(~component=SCS.Spec.name, ...),
           SCS.Spec.commandSchema->S.castToUnknown,
         ),
         producedEventTypes: produced,
@@ -1416,6 +1510,7 @@ let make = (
           ~mutationFieldFor=variantName => Api_Naming.aggregateMutationField(~plugin=name, ~aggregate=A.Spec.name, ~command=variantName),
           ~commandAuthorization=A.Spec.commandAuthorization->Obj.magic,
           ~commandTransition=A.Spec.commandTransition->Obj.magic,
+          ~derivedEdgeFor=derivedEdgeFor(~component=A.Spec.name, ...),
           A.Spec.commandSchema->S.castToUnknown,
         ),
         producedEventTypes: produced,