@reventlessdev/reventless-core 3.0.0-alpha.256 → 3.0.0-alpha.258

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,

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

@@ -29,6 +29,8 @@ import * as GraphQL_FragmentGenerator$ReventlessCore from "../../components/Api/
 
 let log = Logger$ReventlessCore.fromEnv();
 
+let declaredTransitionsOnly = Stdlib_Option.isSome(process.env.REVENTLESS_DECLARED_TRANSITIONS_ONLY);
+
 function isLabelShape(_t) {
   while (true) {
     let t = _t;
@@ -342,18 +344,20 @@ function checkDeclaredTransitions(pluginName, writables, lifecycleStatesByView)
       });
       if (known.length === 0) {
         unvalidated.contents = unvalidated.contents + 1 | 0;
-      } else {
-        declared.filter(state => !known.includes(state)).forEach(state => {
-          failures.push(w.name + `.` + cmd.name + ` declares state "` + state + `", which none of its ` + (`linked views declare — ` + w.linkedViews.join(", ") + ` know ` + known.join(", ") + `.`));
-        });
+        return;
       }
+      let match = cmd.allowedStatesSource;
+      let hint = match === "derived" ? " This edge came from the component's own scenarios, so the committed lifecycle model is stale." : "";
+      declared.filter(state => !known.includes(state)).forEach(state => {
+        failures.push(w.name + `.` + cmd.name + ` declares state "` + state + `", which none of its ` + (`linked views declare — ` + w.linkedViews.join(", ") + ` know ` + known.join(", ") + `.` + hint));
+      });
     });
   });
   if (unvalidated.contents > 0) {
     log.warn("Plugin_Structure", undefined, pluginName + `: ` + unvalidated.contents.toString() + ` command(s) declare a transition but no linked view declares a lifecycle to check it against.`);
   }
   if (failures.length !== 0) {
-    return Stdlib_JsError.throwWithMessage(pluginName + `: a declared transition names states that do not exist.\n` + failures.join("\n"));
+    return Stdlib_JsError.throwWithMessage(pluginName + `: a transition names states that do not exist.\n` + failures.join("\n"));
   }
 }
 
@@ -449,14 +453,14 @@ function labelFieldsFromStateSchema(entityName, stateSchema) {
 }
 
 function extractReferences(properties) {
-  return Stdlib_Array.filterMap(Object.entries(properties), param => {
-    let fieldName = param[0];
-    return Stdlib_Option.map(Reference$Reventless.getFieldTarget(param[1]), target => ({
-      fieldName: fieldName,
+  return Object.entries(properties).flatMap(param => Reference$Reventless.collectFieldTargets(param[0], param[1]).map(param => {
+    let target = param[1];
+    return {
+      fieldName: param[0],
       entity: target.entity,
       plugin: target.plugin
-    }));
-  });
+    };
+  }));
 }
 
 function toEventDef(v) {
@@ -464,7 +468,7 @@ function toEventDef(v) {
     let references = extractReferences(properties);
     return {
       name: variantName,
-      schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(v)),
+      schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(undefined, undefined, v)),
       references: references
     };
   };
@@ -592,7 +596,7 @@ function annotateArgTypes(schema, argTypes) {
   return schema;
 }
 
-function toCommandDef(isAggregate, mutationFieldFor, parentSchema, commandAuthorization, commandTransition, v) {
+function toCommandDef(isAggregate, mutationFieldFor, parentSchema, commandAuthorization, commandTransition, derivedEdgeFor, v) {
   let mkDef = (variantName, properties) => {
     let match = commandLevelAndId(isAggregate, variantName, properties);
     let references = extractReferences(properties);
@@ -600,8 +604,36 @@ function toCommandDef(isAggregate, mutationFieldFor, parentSchema, commandAuthor
         TAG: variantName
       }) : variantName;
     let declared = commandTransition(syntheticCommand);
-    let allowedStates = Transition$Reventless.allowedStates(declared);
-    let targetState = Transition$Reventless.targetState(declared);
+    let derived = derivedEdgeFor(variantName);
+    let unrestricted = Transition$Reventless.isUnrestricted(declared);
+    let match$1 = unrestricted ? undefined : Stdlib_Option.flatMap(derived, d => {
+        if (d.allowedStates.length !== 0) {
+          return d.allowedStates;
+        }
+      });
+    let match$2 = Transition$Reventless.allowedStates(declared);
+    let match$3 = match$1 !== undefined ? [
+        match$1,
+        "derived"
+      ] : (
+        match$2 !== undefined ? [
+            match$2,
+            "declared"
+          ] : [
+            undefined,
+            unrestricted ? "unrestricted" : undefined
+          ]
+      );
+    let observed = Stdlib_Option.flatMap(derived, d => {
+      let match = d.targets;
+      if (match.length !== 1) {
+        return;
+      } else {
+        return match[0];
+      }
+    });
+    let targetState = observed !== undefined ? observed : Transition$Reventless.targetState(declared);
+    let level = Stdlib_Option.getOr(Stdlib_Option.flatMap(derived, d => d.level), match[0]);
     let apiExposed = false;
     if (!ApiNoApiHelpers$ReventlessCore.isNoApi(parentSchema)) {
       let excluded = ApiNoApiHelpers$ReventlessCore.getExcludedVariants(parentSchema);
@@ -609,17 +641,18 @@ function toCommandDef(isAggregate, mutationFieldFor, parentSchema, commandAuthor
     }
     let requiredAccess = accessKeysFor(commandAuthorization(syntheticCommand));
     let mutationField = apiExposed ? mutationFieldFor(variantName) : "";
-    let jsonSchema = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(v);
+    let jsonSchema = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(apiExposed, mutationField, v);
     let annotatedSchema = apiExposed ? Stdlib_Option.mapOr(GraphQL_FragmentGenerator$ReventlessCore.mutationArgTypes(mutationField, v), jsonSchema, __x => annotateArgTypes(jsonSchema, __x)) : jsonSchema;
     return {
       name: variantName,
       schema: JSON.stringify(annotatedSchema),
-      level: match[0],
+      level: level,
       aggregateIdField: match[1],
       mutationField: mutationField,
       references: references,
-      allowedStates: allowedStates,
+      allowedStates: match$3[0],
       targetState: targetState,
+      allowedStatesSource: match$3[1],
       apiExposed: apiExposed,
       requiredAccess: requiredAccess,
       ownerField: Owner$Reventless.fieldNamesOfProperties(properties)[0]
@@ -649,11 +682,12 @@ function toCommandDef(isAggregate, mutationFieldFor, parentSchema, commandAuthor
   }
 }
 
-function extractCommandDefs(isAggregate, mutationFieldFor, commandAuthorization, commandTransition, commandSchema) {
+function extractCommandDefs(isAggregate, mutationFieldFor, commandAuthorization, commandTransition, derivedEdgeForOpt, commandSchema) {
+  let derivedEdgeFor = derivedEdgeForOpt !== undefined ? derivedEdgeForOpt : param => {};
   if (commandSchema.type === "anyOf") {
-    return Stdlib_Array.filterMap(commandSchema.anyOf, v => toCommandDef(isAggregate, mutationFieldFor, commandSchema, commandAuthorization, commandTransition, v));
+    return Stdlib_Array.filterMap(commandSchema.anyOf, v => toCommandDef(isAggregate, mutationFieldFor, commandSchema, commandAuthorization, commandTransition, derivedEdgeFor, v));
   } else {
-    return Stdlib_Option.mapOr(toCommandDef(isAggregate, mutationFieldFor, commandSchema, commandAuthorization, commandTransition, commandSchema), [], def => [def]);
+    return Stdlib_Option.mapOr(toCommandDef(isAggregate, mutationFieldFor, commandSchema, commandAuthorization, commandTransition, derivedEdgeFor, commandSchema), [], def => [def]);
   }
 }
 
@@ -675,7 +709,7 @@ function queryableDefFromSpec(plugin, name, stateSchema, authorization, visibili
   return {
     name: name,
     queryField: qf.listFieldName,
-    schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(stateSchema)),
+    schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(undefined, undefined, stateSchema)),
     consumedEventTypes: consumedEventTypes,
     linkedWriteSide: linkedWriteSide,
     labelField: label.field,
@@ -695,7 +729,7 @@ function queryableDefFromSpec(plugin, name, stateSchema, authorization, visibili
   };
 }
 
-function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChangeSlicesOpt, automationSlicesOpt, outboundTranslationSlicesOpt, inboundTranslationSlicesOpt, extensionsOpt, extensionPointsOpt, componentChaptersOpt) {
+function make(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 : [];
@@ -706,6 +740,15 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
   let extensions = extensionsOpt !== undefined ? extensionsOpt : [];
   let extensionPoints = extensionPointsOpt !== undefined ? extensionPointsOpt : [];
   let componentChapters = componentChaptersOpt !== undefined ? componentChaptersOpt : ({});
+  let lifecycleModel = lifecycleModelOpt !== undefined ? lifecycleModelOpt : [];
+  let model = declaredTransitionsOnly ? [] : lifecycleModel;
+  let derivedEdgeFor = (component, command) => model.find(e => {
+    if (e.component === component) {
+      return e.command === command;
+    } else {
+      return false;
+    }
+  });
   let qualify = (prefix, names) => names.map(n => prefix + "." + n);
   let scsProduced = stateChangeSlices.map(SCS => [
     SCS.Spec.name,
@@ -975,7 +1018,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     return {
       name: R.Spec.name,
       queryField: qf.listFieldName,
-      schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(stateSchema)),
+      schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(undefined, undefined, stateSchema)),
       consumedEventTypes: consumed,
       linkedWriteSide: linkedWriteSideFor(consumed),
       labelField: label.field,
@@ -1007,7 +1050,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     return {
       name: SVS.Spec.name,
       queryField: qf.listFieldName,
-      schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(stateSchema)),
+      schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(undefined, undefined, stateSchema)),
       consumedEventTypes: consumed,
       linkedWriteSide: linkedWriteSideFor(consumed),
       labelField: label.field,
@@ -1033,7 +1076,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let consumed = match$1[1];
     return {
       name: SCS.Spec.name,
-      commands: extractCommandDefs(false, variantName => Api_Naming$ReventlessCore.sliceMutationFieldFor(name, SCS.Spec.name, SCS.Spec.commandSchema, variantName), SCS.Spec.commandAuthorization, SCS.Spec.commandTransition, SCS.Spec.commandSchema),
+      commands: extractCommandDefs(false, variantName => Api_Naming$ReventlessCore.sliceMutationFieldFor(name, SCS.Spec.name, SCS.Spec.commandSchema, variantName), SCS.Spec.commandAuthorization, SCS.Spec.commandTransition, extra => derivedEdgeFor(SCS.Spec.name, extra), SCS.Spec.commandSchema),
       producedEventTypes: produced,
       consumedEventTypes: consumed,
       linkedViews: linkedSvsFor(produced),
@@ -1048,7 +1091,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let produced = match[1];
     return {
       name: A.Spec.name,
-      commands: extractCommandDefs(true, variantName => Api_Naming$ReventlessCore.aggregateMutationField(name, A.Spec.name, variantName), A.Spec.commandAuthorization, A.Spec.commandTransition, A.Spec.commandSchema),
+      commands: extractCommandDefs(true, variantName => Api_Naming$ReventlessCore.aggregateMutationField(name, A.Spec.name, variantName), A.Spec.commandAuthorization, A.Spec.commandTransition, extra => derivedEdgeFor(A.Spec.name, extra), A.Spec.commandSchema),
       producedEventTypes: produced,
       consumedEventTypes: [],
       linkedViews: linkedSvsFor(produced).concat(linkedReadModelsFor(A.Spec.name)),
@@ -1342,6 +1385,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
 
 export {
   log,
+  declaredTransitionsOnly,
   isLabelShape,
   isLifecycleShape,
   conventionalLabelNames,

package/src/util/Validation.res

@@ -31,7 +31,7 @@ let merge: (t<'a, 'b>, t<'a, 'b>) => t<'a, 'b> = (v1, v2) => {
 }
 
 let defaultErrorHandler = err => {
-  EffectLogger.logError(~comp=__MODULE__, err->JSON.stringifyAny->Option.getOr("unknown"))->Effect.runSync
+  EffectLogger.logError(~comp=__MODULE__, err->Reventless.Util_Sury.exnMessage)->Effect.runSync
   Failure("Couldn't resolve promise.")
 }
 

package/src/util/Validation.res.mjs

@@ -1,8 +1,8 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect from "effect/Effect";
 import * as Stdlib_Promise from "@rescript/runtime/lib/es6/Stdlib_Promise.js";
+import * as Util_Sury$Reventless from "@reventlessdev/reventless-spec/src/util/Util_Sury.res.mjs";
 import * as EffectLogger$ReventlessCore from "./EffectLogger.res.mjs";
 
 function merge(v1, v2) {
@@ -105,7 +105,7 @@ function merge(v1, v2) {
 }
 
 function defaultErrorHandler(err) {
-  Effect.runSync(EffectLogger$ReventlessCore.logError("Validation-ReventlessCore", undefined, Stdlib_Option.getOr(JSON.stringify(err), "unknown")));
+  Effect.runSync(EffectLogger$ReventlessCore.logError("Validation-ReventlessCore", undefined, Util_Sury$Reventless.exnMessage(err, undefined)));
   return {
     TAG: "Failure",
     _0: "Couldn't resolve promise."

package/tests/adapter/MonitoringTest.res

@@ -6,10 +6,49 @@ open JestGlobals
 let stubResource: ReventlessInfra.Adapter.resource = %raw(`{}`)
 
 describe("Monitoring", () => {
-  testSync("Noop default: notify is silent and does not throw", () => {
-    // No backend registered — the default Noop backend swallows the call.
+  testSync("no backend registered: notify is silent and does not throw", () => {
     Monitoring.notify(~kind=CommandHandler, ~name="before", ~component=stubResource)
     expect(true)->toBe(true)
+    Monitoring.reset()
+  })
+
+  // The case the dead-letter sink is: a module that provisions at import time announces
+  // itself before any statement of the deploy program has run, so it is *always* earlier
+  // than the `use` call. Dropping those announcements made that one unit unmonitorable no
+  // matter what a backend did.
+  testSync("an announcement made before any backend is registered reaches the first one", () => {
+    let recorded: array<(Monitoring.unitKind, string, option<string>)> = []
+    module Late: Monitoring.Backend = {
+      let onProvisioned = (~kind, ~name, ~component as _, ~plugin, ~platform as _, ~logLocator as _) =>
+        recorded->Array.push((kind, name, plugin))
+    }
+
+    // Provisioned at import time, inside a construct scope that is long gone by the time
+    // anyone registers — so the owner must be captured now, not at delivery.
+    let prev = ResourceAttribution.enter(~platform="online-shop", ~plugin="Ordering")
+    Monitoring.notify(~kind=DeadLetterSink, ~name="DeadLetterQueue", ~component=stubResource)
+    ResourceAttribution.restore(prev)
+    Monitoring.notify(~kind=Scheduler, ~name="Heartbeat", ~component=stubResource)
+
+    expect(recorded)->toEqual([])
+
+    Monitoring.use(module(Late: Monitoring.Backend))
+
+    expect(recorded)->toEqual([
+      (Monitoring.DeadLetterSink, "DeadLetterQueue", Some("Ordering")),
+      (Monitoring.Scheduler, "Heartbeat", None),
+    ])
+
+    // Drained: a second registration does not receive them again.
+    let second: array<string> = []
+    module Other: Monitoring.Backend = {
+      let onProvisioned = (~kind as _, ~name, ~component as _, ~plugin as _, ~platform as _, ~logLocator as _) =>
+        second->Array.push(name)
+    }
+    Monitoring.use(module(Other: Monitoring.Backend))
+    expect(second)->toEqual([])
+
+    Monitoring.reset()
   })
 
   testSync("use registers a backend that receives every notify, role and name", () => {
@@ -32,8 +71,8 @@ describe("Monitoring", () => {
       (Monitoring.Other("Counter"), "ProductCounter"),
     ])
 
-    // Restore the default so registry state doesn't leak to other cases.
-    Monitoring.use(module(Monitoring.Noop))
+    // Restore the initial state so registry and buffer don't leak to other cases.
+    Monitoring.reset()
   })
 
   testSync("notify forwards the static name and component resource to the backend", () => {
@@ -50,7 +89,7 @@ describe("Monitoring", () => {
     | None => expect("no notify received")->toBe("a notify")
     }
 
-    Monitoring.use(module(Monitoring.Noop))
+    Monitoring.reset()
   })
 
   testSync("notify delivers the ambient plugin/platform inside a construct scope, None outside", () => {
@@ -78,7 +117,7 @@ describe("Monitoring", () => {
       (None, None),
     ])
 
-    Monitoring.use(module(Monitoring.Noop))
+    Monitoring.reset()
   })
 
   // Unlike the owner, the locator is not ambient — the seam only forwards what the provisioning
@@ -105,6 +144,6 @@ describe("Monitoring", () => {
 
     expect(seen)->toEqual([true, false])
 
-    Monitoring.use(module(Monitoring.Noop))
+    Monitoring.reset()
   })
 })

package/tests/adapter/MonitoringTest.res.mjs

@@ -7,9 +7,51 @@ import * as ResourceAttribution$ReventlessCore from "../../src/ResourceAttributi
 let stubResource = {};
 
 globalThis.describe("Monitoring", () => {
-  globalThis.test("Noop default: notify is silent and does not throw", () => {
+  globalThis.test("no backend registered: notify is silent and does not throw", () => {
     Monitoring$ReventlessCore.notify("CommandHandler", "before", stubResource, undefined);
     globalThis.expect(true).toBe(true);
+    Monitoring$ReventlessCore.reset();
+  });
+  globalThis.test("an announcement made before any backend is registered reaches the first one", () => {
+    let recorded = [];
+    let onProvisioned = (kind, name, param, plugin, param$1, param$2) => {
+      recorded.push([
+        kind,
+        name,
+        plugin
+      ]);
+    };
+    let Late = {
+      onProvisioned: onProvisioned
+    };
+    let prev = ResourceAttribution$ReventlessCore.enter("online-shop", "Ordering");
+    Monitoring$ReventlessCore.notify("DeadLetterSink", "DeadLetterQueue", stubResource, undefined);
+    ResourceAttribution$ReventlessCore.restore(prev);
+    Monitoring$ReventlessCore.notify("Scheduler", "Heartbeat", stubResource, undefined);
+    globalThis.expect(recorded).toEqual([]);
+    Monitoring$ReventlessCore.use(Late);
+    globalThis.expect(recorded).toEqual([
+      [
+        "DeadLetterSink",
+        "DeadLetterQueue",
+        "Ordering"
+      ],
+      [
+        "Scheduler",
+        "Heartbeat",
+        undefined
+      ]
+    ]);
+    let second = [];
+    let onProvisioned$1 = (param, name, param$1, param$2, param$3, param$4) => {
+      second.push(name);
+    };
+    let Other = {
+      onProvisioned: onProvisioned$1
+    };
+    Monitoring$ReventlessCore.use(Other);
+    globalThis.expect(second).toEqual([]);
+    Monitoring$ReventlessCore.reset();
   });
   globalThis.test("use registers a backend that receives every notify, role and name", () => {
     let recorded = [];
@@ -51,7 +93,7 @@ globalThis.describe("Monitoring", () => {
         "ProductCounter"
       ]
     ]);
-    Monitoring$ReventlessCore.use(Monitoring$ReventlessCore.Noop);
+    Monitoring$ReventlessCore.reset();
   });
   globalThis.test("notify forwards the static name and component resource to the backend", () => {
     let seen = {
@@ -74,7 +116,7 @@ globalThis.describe("Monitoring", () => {
     } else {
       globalThis.expect("no notify received").toBe("a notify");
     }
-    Monitoring$ReventlessCore.use(Monitoring$ReventlessCore.Noop);
+    Monitoring$ReventlessCore.reset();
   });
   globalThis.test("notify delivers the ambient plugin/platform inside a construct scope, None outside", () => {
     let seen = [];
@@ -107,7 +149,7 @@ globalThis.describe("Monitoring", () => {
         undefined
       ]
     ]);
-    Monitoring$ReventlessCore.use(Monitoring$ReventlessCore.Noop);
+    Monitoring$ReventlessCore.reset();
   });
   globalThis.test("notify forwards the log locator when given one, None when omitted", () => {
     let stubLocator = {};
@@ -125,7 +167,7 @@ globalThis.describe("Monitoring", () => {
       true,
       false
     ]);
-    Monitoring$ReventlessCore.use(Monitoring$ReventlessCore.Noop);
+    Monitoring$ReventlessCore.reset();
   });
 });