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

package/src/plugin/component/Plugin_Structure.res

@@ -114,13 +114,13 @@ let retiredValuesFromStateSchema = (stateSchema: S.t<unknown>): option<array<str
 //
 // 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 — `@allowedStates` is written in
+// 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 =>
   switch retiredFromStateSchema(stateSchema) {
   | Some({field, values: Some(values)}) =>
-    let named = values->Array.joinWith(", ")
+    let named = values->Array.join(", ")
     let lifecycle = lifecycleFieldFromStateSchema(~entityName, stateSchema)
     if lifecycle != Some(field) {
       log.warn(
@@ -129,7 +129,7 @@ let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =
           ->Option.map(f => ` (that is "${f}")`)
           ->Option.getOr(
             " (it declares none)",
-          )}. A retirement state no command's @allowedStates can name loses the command filtering the state form exists for.`,
+          )}. A retirement state no command's @transition can name loses the command filtering the state form exists for.`,
       )
     }
     let declared = switch stateSchema {
@@ -155,7 +155,7 @@ let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =
       ->Array.forEach(v =>
         log.warn(
           ~comp="Plugin_Structure",
-          `${entityName}: @retired(${v}) names a state "${field}" does not declare — known values: ${declared->Array.joinWith(
+          `${entityName}: @retired(${v}) names a state "${field}" does not declare — known values: ${declared->Array.join(
               ", ",
             )}.`,
         )
@@ -164,6 +164,242 @@ let checkRetiredValue = (~entityName: string, stateSchema: S.t<unknown>): unit =
   | _ => ()
   }
 
+// 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
+// of. `None` means the record declares no lifecycle at all; `Some([])` means it
+// declares one whose shape carries no cases to compare against.
+let lifecycleStatesFromStateSchema = (
+  ~entityName: string,
+  stateSchema: S.t<unknown>,
+): 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) {
+        | Enum(_, values) => values
+        | Nullable(Enum(_, values)) => values
+        | _ => []
+        }
+      )
+    | _ => None
+    }
+  )
+
+// The other check the PPX cannot make, and the reason `@transition` is worth
+// more than a rename.
+//
+// A command declares the states it may run from and the state it lands in, but
+// those states belong to ANOTHER component's lifecycle enum. The PPX only ever
+// sees them as names — it strips the attribute before the typechecker, and a
+// synthetic reference to the constructor does not survive ReScript's pre-PPX
+// dependency walk. So a misspelled state compiles clean, ships, and produces a
+// command that is legal in a state no row is ever in: a menu entry that never
+// appears, with nothing anywhere saying why.
+//
+// Here both sides are in hand. This runs at plugin-structure assembly, which
+// happens in the deploy program and at local-platform start — never inside a
+// deployed Lambda, which reads a persisted structure rather than building one.
+// So raising is a failed deploy, not a dead function.
+//
+// Two severities, and the split is deliberate:
+//   - a state the linked views do not declare  → RAISE. The author named
+//     something that does not exist.
+//   - no resolvable linked view, or none declaring a lifecycle → warn. The
+//     metadata gap is real but hard-failing on it would turn "this plugin's
+//     views could not be resolved" into a deploy outage, and that population is
+//     broad.
+//
+// Checked against the UNION of the linked views' lifecycles rather than a single
+// view: a command whose slice feeds two views is not claiming which one, and
+// failing on an ambiguity the author never expressed would be a false positive
+// on correct code.
+let checkDeclaredTransitions = (
+  ~pluginName: string,
+  ~writables: array<Reventless.Plugin.writableDef>,
+  ~lifecycleStatesByView: dict<array<string>>,
+): unit => {
+  let unvalidated = ref(0)
+  let failures = []
+
+  writables->Array.forEach(w =>
+    w.commands->Array.forEach(cmd => {
+      let declared = Array.concat(
+        cmd.allowedStates->Option.getOr([]),
+        switch cmd.targetState {
+        | Some(t) => [t]
+        | None => []
+        },
+      )
+      if Array.length(declared) > 0 {
+        let known =
+          w.linkedViews->Array.reduce([], (acc, view) =>
+            switch lifecycleStatesByView->Dict.get(view) {
+            | Some(states) => Array.concat(acc, states)
+            | None => acc
+            }
+          )
+        if Array.length(known) == 0 {
+          unvalidated := unvalidated.contents + 1
+        } else {
+          declared
+          ->Array.filter(state => !(known->Array.includes(state)))
+          ->Array.forEach(state =>
+            failures
+            ->Array.push(
+              `${w.name}.${cmd.name}: @transition names "${state}", which none of its ` ++
+              `linked views declare — ${w.linkedViews->Array.join(
+                  ", ",
+                )} know ${known->Array.join(", ")}.`,
+            )
+            ->ignore
+          )
+        }
+      }
+    })
+  )
+
+  // Reported rather than silent: a plugin nothing could be checked against looks
+  // exactly like a plugin that passed, and that population is the one most
+  // likely to be carrying a stale name.
+  if unvalidated.contents > 0 {
+    log.warn(
+      ~comp="Plugin_Structure",
+      `${pluginName}: ${unvalidated.contents->Int.toString} command(s) declare a @transition ` ++
+      `but no linked view declares a lifecycle to check it against.`,
+    )
+  }
+
+  if Array.length(failures) > 0 {
+    JsError.throwWithMessage(
+      `${pluginName}: @transition names states that do not exist.\n` ++
+      failures->Array.join("\n"),
+    )
+  }
+}
+
+// Beyond "does this state exist" — does the declared graph make sense?
+//
+// A separate pass from the name check on purpose. That one asks whether a name
+// is a case of an enum, which is a question about one annotation in isolation.
+// These ask whether the annotations AGREE with each other across an entity, and
+// a graph can be built entirely out of valid names and still be wrong: a state
+// nothing reaches, or one nothing can leave that was never marked as an ending.
+//
+// Reported as warnings rather than raised. The name check fails a build because
+// a state that does not exist is unambiguously a mistake — there is no domain in
+// which it is what the author meant. These are weaker signals: a state with no
+// way out may be a genuine dead end nobody has marked yet, or a legitimate
+// terminal the model reaches by a route this metadata cannot see (an automation,
+// an external system). Failing a deploy on a modelling smell would be the wrong
+// trade, and a smell that stops a deploy gets silenced rather than fixed.
+// Pure, and returns its findings rather than logging them, so the rule can be
+// tested without reading a log. `checkLifecycleTopology` below is the thin part
+// that reports them.
+let lifecycleTopologyFindings = (
+  ~writables: array<Reventless.Plugin.writableDef>,
+  ~lifecycleStatesByView: dict<array<string>>,
+): array<(string, string)> => {
+  let findings = []
+  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) =>
+      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
+              }
+            ),
+          )
+        : acc
+    )
+    if Array.length(edges) > 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 {
+          findings
+          ->Array.push((
+            view,
+            `no command declares a transition INTO "${state}" — it is unreachable ` ++
+            `unless something outside this plugin's declarations puts a row there.`,
+          ))
+          ->ignore
+        }
+        // NOT checked: a state with no way out.
+        //
+        // The obvious second rule — "a dead end that is not `@retired` is
+        // suspicious" — was written, run against the shipped examples, and
+        // removed, because it is wrong twice over.
+        //
+        // It fires on correct models: `Shipped` and `Refunded` are terminal in
+        // the aggregates shop, as terminal states are in most lifecycles, and
+        // there is nothing to fix about either.
+        //
+        // Worse, its suggested fix is harmful. `@retired` does not mean
+        // "terminal" — it means WITHDRAWN FROM ORDINARY READS. Marking a shipped
+        // order retired to silence a lint would hide every shipped order from
+        // every caller who cannot widen their read. An ending and a withdrawal
+        // are different facts, and nothing in the vocabulary currently
+        // distinguishes an intentional terminal from an accidental one, so the
+        // check cannot tell them apart and should not pretend to.
+      })
+    }
+  })
+  findings
+}
+
+let checkLifecycleTopology = (
+  ~pluginName: string,
+  ~writables: array<Reventless.Plugin.writableDef>,
+  ~lifecycleStatesByView: dict<array<string>>,
+): unit =>
+  lifecycleTopologyFindings(~writables, ~lifecycleStatesByView)->Array.forEach(((view, message)) =>
+    log.warn(~comp="Plugin_Structure", `${pluginName}/${view}: ${message}`)
+  )
+
+// NOT here: the event-consumption completeness check.
+//
+// The failure it would catch is real and has already happened: a command emitted
+// an event, the slice that owned the opposite command folded it, and the view
+// that renders the entity did not — so the row kept rendering the state it was
+// in before, with every annotation in the plugin correct. That is a class of bug
+// no declaration check can see, because nothing declared is wrong.
+//
+// It is not computable from this metadata, and the reason is worth recording so
+// the attempt is not repeated. Two narrowings were needed and only one was
+// available:
+//
+//   1. The event must belong to the view's own entity, not merely be something a
+//      slice looked up. Available: require it to be PRODUCED by a writable
+//      linked to the same view. Without this the check fires on ordinary DCB —
+//      `AddProduct` folds `CategoryAdded` to check a category exists, and the
+//      `Products` view is right to ignore it.
+//
+//   2. The slice must be known to fold the event. NOT available:
+//      `consumedEventTypes` is built from `eventVariantNames`, which drops
+//      payload-less variants — and a lifecycle-moving event is usually
+//      payload-less in the slice that folds it. Measured on the shipped example:
+//      both order slices publish `consumedEventTypes: ["Ordering.OrderPlaced"]`
+//      and nothing else, though each folds three more.
+//
+// So the exact events the rule is about are the ones the metadata does not
+// record. Making it work means publishing the payload-less consumed variants,
+// which is a platform change with its own consequences, not a lint.
+
 // Which rung of the ladder below produced the label. Published on `queryableDef`
 // as `labelFieldSource`, because the four rungs are not equally believable and a
 // consumer with a name rule of its own has to rank the declaration against it:
@@ -338,7 +574,7 @@ let make = (
   // spec name has no entry (or lives directly under a kind-folder) carries no chapter
   // and renders flat. Keyed by `Spec.name`, which equals the source filename stem for
   // every graph-node kind, so the generator can build this map from the discovered
-  // file paths. See `Codegen.chapterOf` and docs/plans/deployed-chapter-grouping.md.
+  // file paths. See `Codegen.chapterOf` and docs/plans/done/deployed-chapter-grouping.md.
   ~componentChapters: dict<string>=Dict.make(),
 ): Reventless.Plugin.pluginStructure => {
   let chapterOf = (compName: string): option<string> => componentChapters->Dict.get(compName)
@@ -454,9 +690,9 @@ let make = (
       // 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 an @allowedStates annotation.
+      // None when the variant lacks a @transition annotation.
       let allowedStates = ApiAllowedStatesHelpers.getAllowedStates(parentSchema, ~variantName)
-      // Declared `@targetState` (the command's *to* status), read the same way
+      // 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)
@@ -824,6 +1060,17 @@ let make = (
     | 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()
+  let recordLifecycle = (~entityName, stateSchema) => {
+    switch lifecycleStatesFromStateSchema(~entityName, stateSchema) {
+    | Some(states) if Array.length(states) > 0 =>
+      lifecycleStatesByView->Dict.set(entityName, states)
+    | _ => ()
+    }
+  }
+
   let readModelDefs =
     readModels
     ->Array.map((
@@ -844,6 +1091,7 @@ let make = (
       // 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)
+      recordLifecycle(~entityName=R.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: R.Spec.name,
         queryField: qf.listFieldName,
@@ -882,6 +1130,7 @@ let make = (
         stateSchema,
       )
       checkRetiredValue(~entityName=SVS.Spec.name, stateSchema)
+      recordLifecycle(~entityName=SVS.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: SVS.Spec.name,
         queryField: qf.listFieldName,
@@ -1052,6 +1301,19 @@ let make = (
       commandTypes: Some(dedupe(cmds)),
     }: Reventless.Plugin.extensionPointDef))
 
+  // Second pass, on purpose: commands are built well before `linkedViews` is
+  // assembled, so the check cannot run inline where the defs are made.
+  checkDeclaredTransitions(
+    ~pluginName=name,
+    ~writables=Array.concat(stateChangeDefs, aggregateDefs),
+    ~lifecycleStatesByView,
+  )
+  checkLifecycleTopology(
+    ~pluginName=name,
+    ~writables=Array.concat(stateChangeDefs, aggregateDefs),
+    ~lifecycleStatesByView,
+  )
+
   {
     readModels: readModelDefs,
     stateViewSlices: stateViewDefs,

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

@@ -5,6 +5,7 @@ import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Belt_SetString from "@rescript/runtime/lib/es6/Belt_SetString.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Owner$Reventless from "@reventlessdev/reventless-spec/src/components/Owner.res.mjs";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
@@ -114,7 +115,7 @@ function checkRetiredValue(entityName, stateSchema) {
   let named = values.join(", ");
   let lifecycle = lifecycleFieldFromStateSchema(entityName, stateSchema);
   if (Primitive_object.notequal(lifecycle, field)) {
-    log.warn("Plugin_Structure", undefined, entityName + `: @retired(` + named + `) is on "` + field + `", which is not this record's lifecycle field` + Stdlib_Option.getOr(Stdlib_Option.map(lifecycle, f => ` (that is "` + f + `")`), " (it declares none)") + `. A retirement state no command's @allowedStates can name loses the command filtering the state form exists for.`);
+    log.warn("Plugin_Structure", undefined, entityName + `: @retired(` + named + `) is on "` + field + `", which is not this record's lifecycle field` + Stdlib_Option.getOr(Stdlib_Option.map(lifecycle, f => ` (that is "` + f + `")`), " (it declares none)") + `. A retirement state no command's @transition can name loses the command filtering the state form exists for.`);
   }
   let declared;
   declared = stateSchema.type === "object" ? Stdlib_Option.getOr(Stdlib_Option.map(stateSchema.items.find(item => item.location === field), item => {
@@ -144,6 +145,116 @@ function checkRetiredValue(entityName, stateSchema) {
   }
 }
 
+function lifecycleStatesFromStateSchema(entityName, stateSchema) {
+  return Stdlib_Option.flatMap(lifecycleFieldFromStateSchema(entityName, stateSchema), field => {
+    if (stateSchema.type === "object") {
+      return Stdlib_Option.map(stateSchema.items.find(item => item.location === field), item => {
+        let match = shapeOfItem(entityName, item);
+        if (typeof match !== "object") {
+          return [];
+        }
+        switch (match.TAG) {
+          case "Nullable" :
+            let match$1 = match._0;
+            if (typeof match$1 !== "object") {
+              return [];
+            } else if (match$1.TAG === "Enum") {
+              return match$1._1;
+            } else {
+              return [];
+            }
+          case "Enum" :
+            return match._1;
+          default:
+            return [];
+        }
+      });
+    }
+  });
+}
+
+function checkDeclaredTransitions(pluginName, writables, lifecycleStatesByView) {
+  let unvalidated = {
+    contents: 0
+  };
+  let failures = [];
+  writables.forEach(w => {
+    w.commands.forEach(cmd => {
+      let t = cmd.targetState;
+      let declared = Stdlib_Option.getOr(cmd.allowedStates, []).concat(t !== undefined ? [t] : []);
+      if (declared.length === 0) {
+        return;
+      }
+      let known = Stdlib_Array.reduce(w.linkedViews, [], (acc, view) => {
+        let states = lifecycleStatesByView[view];
+        if (states !== undefined) {
+          return acc.concat(states);
+        } else {
+          return acc;
+        }
+      });
+      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 + `: @transition names "` + state + `", which none of its ` + (`linked views declare — ` + w.linkedViews.join(", ") + ` know ` + known.join(", ") + `.`));
+        });
+      }
+    });
+  });
+  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 + `: @transition names states that do not exist.\n` + failures.join("\n"));
+  }
+}
+
+function lifecycleTopologyFindings(writables, lifecycleStatesByView) {
+  let findings = [];
+  Object.entries(lifecycleStatesByView).forEach(param => {
+    let states = param[1];
+    let view = param[0];
+    let edges = Stdlib_Array.reduce(writables, [], (acc, w) => {
+      if (w.linkedViews.includes(view)) {
+        return acc.concat(Stdlib_Array.reduce(w.commands, [], (inner, cmd) => {
+          let match = cmd.allowedStates;
+          let match$1 = cmd.targetState;
+          if (match !== undefined && match$1 !== undefined) {
+            return inner.concat(match.map(from => [
+              from,
+              match$1
+            ]));
+          } else {
+            return inner;
+          }
+        }));
+      } else {
+        return acc;
+      }
+    });
+    if (edges.length === 0) {
+      return;
+    }
+    let initial = states[0];
+    let reachable = edges.map(param => param[1]);
+    states.forEach(state => {
+      if (!reachable.includes(state) && Primitive_object.notequal(state, initial)) {
+        findings.push([
+          view,
+          `no command declares a transition INTO "` + state + `" — it is unreachable unless something outside this plugin's declarations puts a row there.`
+        ]);
+        return;
+      }
+    });
+  });
+  return findings;
+}
+
+function checkLifecycleTopology(pluginName, writables, lifecycleStatesByView) {
+  lifecycleTopologyFindings(writables, lifecycleStatesByView).forEach(param => log.warn("Plugin_Structure", undefined, pluginName + `/` + param[0] + `: ` + param[1]));
+}
+
 function labelFieldSourceToString(s) {
   switch (s) {
     case "Annotation" :
@@ -587,6 +698,14 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       return "Internal";
     }
   };
+  let lifecycleStatesByView = {};
+  let recordLifecycle = (entityName, stateSchema) => {
+    let states = lifecycleStatesFromStateSchema(entityName, stateSchema);
+    if (states !== undefined && states.length !== 0) {
+      lifecycleStatesByView[entityName] = states;
+      return;
+    }
+  };
   let readModelDefs = readModels.map(R => {
     let qf = Api_Naming$ReventlessCore.queryFieldNamesForReadModel(name, R.Spec.name, undefined);
     let stateSchema = R.Spec.stateSchema;
@@ -594,6 +713,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField(R.Spec.name, stateSchema);
     let consumed = qualify(name, R.consumedEventNames);
     checkRetiredValue(R.Spec.name, stateSchema);
+    recordLifecycle(R.Spec.name, stateSchema);
     return {
       name: R.Spec.name,
       queryField: qf.listFieldName,
@@ -623,6 +743,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let label = labelFieldsFromStateSchema(SVS.Spec.name, stateSchema);
     let keyField = GraphQL_FragmentGenerator$ReventlessCore.resolveKeyField(SVS.Spec.name, stateSchema);
     checkRetiredValue(SVS.Spec.name, stateSchema);
+    recordLifecycle(SVS.Spec.name, stateSchema);
     return {
       name: SVS.Spec.name,
       queryField: qf.listFieldName,
@@ -735,6 +856,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       commandTypes: Belt_SetString.toArray(Belt_SetString.fromArray(match[2]))
     };
   });
+  checkDeclaredTransitions(name, stateChangeDefs.concat(aggregateDefs), lifecycleStatesByView);
+  checkLifecycleTopology(name, stateChangeDefs.concat(aggregateDefs), lifecycleStatesByView);
   return {
     readModels: readModelDefs,
     stateViewSlices: stateViewDefs,
@@ -761,6 +884,10 @@ export {
   retiredFieldFromStateSchema,
   retiredValuesFromStateSchema,
   checkRetiredValue,
+  lifecycleStatesFromStateSchema,
+  checkDeclaredTransitions,
+  lifecycleTopologyFindings,
+  checkLifecycleTopology,
   labelFieldSourceToString,
   labelFieldsFromStateSchema,
   extractReferences,

package/src/plugin/connect/PluginExtensionPoint_UiFragment.res

@@ -1,5 +1,5 @@
 // Second mapping on the admin PluginExtensionPoint, routing UI-fragment lifecycle to the
-// admin UiFragmentRegistry StateChangeSlice (docs/plans/event-sourced-fragment-registries.md).
+// admin UiFragmentRegistry StateChangeSlice (docs/plans/done/event-sourced-fragment-registries.md).
 //
 // The EP runtime fans every incoming command through ALL mappings and flattens the results
 // (ExtensionPoint_Callback.mapIncomingCommands). This mapping's Delegate is the slice, so its

package/tests/aggregate/AggregateCacheTest.res

@@ -1,5 +1,5 @@
 // Tests for the Aggregate_Callback in-process replay cache (Phase 1 of
-// docs/plans/aggregate-snapshotting.md): a warm same-id command skips the
+// docs/plans/done/aggregate-snapshotting.md): a warm same-id command skips the
 // event-log replay and decides on the cached (state, sequenceNr); the OCC
 // append fences staleness — a stale cache conflicts, invalidates, and the
 // retry replays cold.

package/tests/aggregate/AggregateSnapshotTest.res

@@ -1,4 +1,4 @@
-// Step 5 of docs/plans/aggregate-snapshotting.md — the Aggregate_Callback
+// Step 5 of docs/plans/done/aggregate-snapshotting.md — the Aggregate_Callback
 // snapshot wiring: a snapshot-enabled behavior seeds cold replays from the
 // latest persisted snapshot (hash-gated) and writes a fresh one every
 // `interval` events, fire-and-forget. Snapshots never affect correctness — the

package/tests/commandgenerator/OwnerStampingTest.res

@@ -185,3 +185,60 @@ describe("@owner stamping on the command path:", () => {
     })
   })
 })
+
+// The schema is not only a validator, and the case below is the one that proves
+// it. Two AppSync-side call sites passed `S.json` in place of the command schema
+// — a defensible substitution while its only job was validation, since AppSync
+// has already checked the input against the SDL, and per-slice decoding happens
+// downstream anyway. Owner stamping then gave the same argument a second job:
+// it is where the `@owner` fields are read from. Handed a permissive schema the
+// lookup answers "no owner fields" for every command there is, and the write
+// keeps whatever owner the client sent — no error, no warning, a wrong row.
+//
+// Nothing about a single call site was wrong, which is why per-path tests could
+// not catch it. What was missing is a check on the RELATIONSHIP: a generator
+// built for a command whose spec marks an owner must be able to find it.
+describe("the schema a generator is built with must answer for its commands:", () => {
+  let permissive = CommandGenerator_Callback.makeGenerateCommand(
+    ~publishJsons=async cmds => published := published.contents->Array.concat(cmds),
+    ~serviceName="Ordering",
+    ~commandSchema=S.json->S.castToUnknown,
+    ~componentKind=CommandGenerator_Callback.StateChangeSlice,
+    ~stripIdFromParams=false,
+  )
+
+  testPromise("a permissive schema silently stamps nothing — the defect, pinned", async () => {
+    let _ =
+      await permissive(
+        placeOrder(~customerId="cust-B", ~identity=cognito(~userId="cust-A", ~groups=["User"])),
+      )->Effect.runPromise
+    // Not the behaviour we want anywhere — recorded so that a change making the
+    // permissive path stamp correctly is a deliberate one, and so the contrast
+    // with the case below cannot be read as incidental.
+    expect(lastPublished()->fieldOf("customerId"))->toEqual(Some(str("cust-B")))
+  })
+
+  testPromise("the real schema stamps, from the same payload and caller", async () => {
+    let _ =
+      await generate(
+        placeOrder(~customerId="cust-B", ~identity=cognito(~userId="cust-A", ~groups=["User"])),
+      )->Effect.runPromise
+    expect(lastPublished()->fieldOf("customerId"))->toEqual(Some(str("cust-A")))
+  })
+
+  // The check a call site can run against itself, and the one the DCB routing
+  // maps now satisfy by construction: every command a spec exposes resolves to
+  // its own owner fields through the schema that command will be dispatched
+  // with. Reading `[]` here is exactly the state that stamps nothing.
+  testPromise("every command of a spec resolves its owner fields through that spec's schema", async () => {
+    let schema = commandSchema->S.castToUnknown
+    expect(Reventless.Owner.variantFieldNames(schema, ~variant="PlaceOrder"))->toEqual([
+      "customerId",
+    ])
+    expect(Reventless.Owner.variantFieldNames(schema, ~variant="ImportProducts"))->toEqual([])
+    // The substitution, asked the same question.
+    expect(
+      Reventless.Owner.variantFieldNames(S.json->S.castToUnknown, ~variant="PlaceOrder"),
+    )->toEqual([])
+  })
+})

package/tests/commandgenerator/OwnerStampingTest.res.mjs

@@ -192,6 +192,25 @@ globalThis.describe("@owner stamping on the command path:", () => {
   });
 });
 
+globalThis.describe("the schema a generator is built with must answer for its commands:", () => {
+  let permissive = CommandGenerator_Callback$ReventlessCore.makeGenerateCommand(async cmds => {
+    published.contents = published.contents.concat(cmds);
+  }, undefined, "Ordering", S.json, "StateChangeSlice", false);
+  globalThis.test("a permissive schema silently stamps nothing — the defect, pinned", async () => {
+    await Effect.runPromise(permissive(placeOrder("cust-B", cognito("cust-A", ["User"]))));
+    globalThis.expect(fieldOf(published.contents[published.contents.length - 1 | 0], "customerId")).toEqual("cust-B");
+  });
+  globalThis.test("the real schema stamps, from the same payload and caller", async () => {
+    await Effect.runPromise(generate(placeOrder("cust-B", cognito("cust-A", ["User"]))));
+    globalThis.expect(fieldOf(published.contents[published.contents.length - 1 | 0], "customerId")).toEqual("cust-A");
+  });
+  globalThis.test("every command of a spec resolves its owner fields through that spec's schema", async () => {
+    globalThis.expect(Owner$Reventless.variantFieldNames(commandSchema, "PlaceOrder")).toEqual(["customerId"]);
+    globalThis.expect(Owner$Reventless.variantFieldNames(commandSchema, "ImportProducts")).toEqual([]);
+    globalThis.expect(Owner$Reventless.variantFieldNames(S.json, "PlaceOrder")).toEqual([]);
+  });
+});
+
 export {
   commandSchema,
   published,

package/tests/message/MessageTest.res

@@ -96,7 +96,7 @@ describe("Message should", () => {
   // Schema-migration-on-read: a VersionConnected event persisted before `kind` (and
   // before later pluginStructure fields like `events`/`chapter`) existed must still
   // decode — otherwise the one stale event bricks the whole lifecycle aggregate. See
-  // docs/plans/platform-infrastructure-in-plugin-list.md (durable fix option 2).
+  // docs/plans/done/platform-infrastructure-in-plugin-list.md (durable fix option 2).
   testSync("tolerantly decode a VersionConnected persisted before kind/structure fields existed", () => {
     open PluginSpec
     let def: Reventless.Plugin.pluginDefinition = {

package/tests/plugin/HeartbeatDisconnectGraceTest.res

@@ -7,7 +7,7 @@
 // (which drives CreateDisconnectSchedule). A deployed plugin once ran with schedule
 // rate(60min) but a Heartbeat(10) command (grace ~12min), so it reconnected for
 // ~12min after each hourly beat then sat Disconnected for the rest of the hour —
-// it flapped. See docs/plans/plugin-heartbeat-disconnect-margin-hardening.md.
+// it flapped. See docs/plans/done/plugin-heartbeat-disconnect-margin-hardening.md.
 //
 // These tests pin the two guarantees that the fix provides at this layer:
 //   1. the disconnect grace scales with the interval (large cadences keep headroom);