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

package/tests/plugin/PluginStructureTest.res

@@ -144,6 +144,29 @@ module PsReserveStockSlice: ReventlessInfra.StateChangeSlice.T = {
   let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
 }
 
+module PsDispatchShipmentSlice: ReventlessInfra.StateChangeSlice.T = {
+  module Spec = PsDispatchShipment
+  module Behavior = {
+    type state = PsDispatchShipment.state
+    let initialState = PsDispatchShipment.initialState
+    let evolve = PsDispatchShipment.evolve
+    let decide = PsDispatchShipment.decide
+    let moduleUrl = PsDispatchShipment.moduleUrl
+  }
+  let isAsync = false
+  type component = scsComponent
+  let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
+}
+module PsShipmentsViewSlice: ReventlessInfra.StateViewSlice.T = {
+  module Spec = PsShipmentsView
+  module Projection = {
+    let project = PsShipmentsView.project
+    let moduleUrl = PsShipmentsView.moduleUrl
+  }
+  type component = svsComponent
+  let make = (~dcbEventLog as _, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
+}
+
 let structure = Plugin_Structure.make(
   ~name="TestPlugin",
   ~stateChangeSlices=[module(PsPlaceOrderSlice), module(PsShipOrderSlice)],
@@ -155,6 +178,132 @@ let structure = Plugin_Structure.make(
   ],
 )
 
+describe("lifecycle topology", () => {
+  let ordersStates = Dict.fromArray([("Orders", ["Placed", "Shipped", "Cancelled"])])
+  let writableWith = (commands): Reventless.Plugin.writableDef => {
+    name: "Ordering",
+    commands,
+    producedEventTypes: [],
+    consumedEventTypes: [],
+    linkedViews: ["Orders"],
+    consistencyRead: None,
+    events: [],
+    errors: [],
+    chapter: None,
+  }
+  let command = (~name, ~allowedStates=?, ~targetState=?, ()): Reventless.Plugin.commandDef => {
+    name,
+    schema: "",
+    level: Instance,
+    aggregateIdField: None,
+    mutationField: "",
+    references: [],
+    allowedStates,
+    targetState,
+    apiExposed: None,
+    requiredAccess: None,
+    ownerField: None,
+  }
+
+  testSync("names a state no command can reach", () => {
+    // `Cancelled` is in the enum and nothing declares an edge into it.
+    let findings = Plugin_Structure.lifecycleTopologyFindings(
+      ~writables=[
+        writableWith([command(~name="Ship", ~allowedStates=["Placed"], ~targetState="Shipped", ())]),
+      ],
+      ~lifecycleStatesByView=ordersStates,
+    )
+    expect(findings->Array.map(((_, m)) => m->String.includes("Cancelled")))->toEqual([true])
+  })
+
+  testSync("says nothing when every state is reachable", () => {
+    let findings = Plugin_Structure.lifecycleTopologyFindings(
+      ~writables=[
+        writableWith([
+          command(~name="Ship", ~allowedStates=["Placed"], ~targetState="Shipped", ()),
+          command(~name="Cancel", ~allowedStates=["Placed"], ~targetState="Cancelled", ()),
+        ]),
+      ],
+      ~lifecycleStatesByView=ordersStates,
+    )
+    expect(findings->Array.length)->toBe(0)
+  })
+
+  // The first declared state is where rows begin, so nothing pointing at it is
+  // expected rather than suspicious.
+  testSync("does not call the initial state unreachable", () => {
+    let findings = Plugin_Structure.lifecycleTopologyFindings(
+      ~writables=[
+        writableWith([
+          command(~name="Ship", ~allowedStates=["Placed"], ~targetState="Shipped", ()),
+          command(~name="Cancel", ~allowedStates=["Placed"], ~targetState="Cancelled", ()),
+        ]),
+      ],
+      ~lifecycleStatesByView=ordersStates,
+    )
+    expect(findings->Array.map(((_, m)) => m->String.includes("Placed")))->toEqual([])
+  })
+
+  // A terminal state is not a finding. `Shipped` and `Refunded` have no way out
+  // in the shipped aggregates example, and both are correct — which is why the
+  // "dead end" rule this pass was going to carry was dropped rather than
+  // silenced. See the comment in Plugin_Structure.
+  testSync("does not report a state with no way out", () => {
+    let findings = Plugin_Structure.lifecycleTopologyFindings(
+      ~writables=[
+        writableWith([
+          command(~name="Ship", ~allowedStates=["Placed"], ~targetState="Shipped", ()),
+          command(~name="Cancel", ~allowedStates=["Placed"], ~targetState="Cancelled", ()),
+        ]),
+      ],
+      ~lifecycleStatesByView=ordersStates,
+    )
+    expect(findings->Array.length)->toBe(0)
+  })
+})
+
+describe("@transition cross-check", () => {
+  // The exit criterion: a state no linked view declares stops the build, and the
+  // message says which command, which state, and what it was checked against.
+  // `DispatchShipment` produces `ShipmentDispatched`, which the `Shipments` view
+  // consumes — so the two are linked, the view's lifecycle is in hand, and
+  // "Dispatchd" has somewhere to be wrong.
+  let buildBad = () =>
+    try {
+      Plugin_Structure.make(
+        ~name="TransitionPlugin",
+        ~stateChangeSlices=[module(PsDispatchShipmentSlice)],
+        ~stateViewSlices=[module(PsShipmentsViewSlice)],
+      )->ignore
+      None
+    } catch {
+    | Exn.Error(e) => Some(Exn.message(e)->Option.getOr(""))
+    | _ => Some("")
+    }
+
+  testSync("a state no linked view declares fails the build", () => {
+    expect(buildBad()->Option.isSome)->toBe(true)
+  })
+
+  testSync("the failure names the command, the state and the view", () => {
+    let message = buildBad()->Option.getOr("")
+    expect((
+      message->String.includes("DispatchShipment"),
+      message->String.includes("Dispatchd"),
+      message->String.includes("Shipments"),
+      message->String.includes("Booked"),
+    ))->toEqual((true, true, true, true))
+  })
+
+  // The other half of the rule: a correctly-spelled edge passes, and a command
+  // whose linked views declare no lifecycle is warned about rather than failed —
+  // `PsShipOrder` is exactly that shape, and the suite's main `structure` above
+  // builds without throwing, which is that path already exercised.
+  testSync("a plugin whose views declare no lifecycle still builds", () => {
+    expect(structure.stateChangeSlices->Array.length)->toBe(2)
+  })
+})
+
 describe("Plugin_Structure.make — Phase 2 graph fields", () => {
   describe("stateChangeSlices", () => {
     testSync("produces two SCS entries in declaration order", () => {
@@ -233,8 +382,8 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       ))->toEqual((Some(true), Some(false)))
     })
 
-    testSync("ShipOrder: @targetState(\"Shipped\") flows through the PPX to commandDef.targetState", () => {
-      // End-to-end: the reventless-ppx @targetState annotation → markTargetState
+    testSync("ShipOrder: @transition's target flows through the PPX to commandDef.targetState", () => {
+      // End-to-end: the reventless-ppx @transition annotation → markTargetState
       // metadata → ApiTargetStateHelpers.getTargetState → commandDef. The
       // un-annotated CancelShipment carries None (resolver falls back to
       // name-stem).
@@ -246,6 +395,18 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       ))->toEqual((Some("Shipped"), None))
     })
 
+    testSync("ShipOrder: @transition's from-set flows through to commandDef.allowedStates", () => {
+      // The other half of the same annotation, which the removed pair spelled
+      // separately: one attribute now fills both fields, so a command that
+      // declares a target cannot end up without the states it may run from.
+      let shipOrder = structure.stateChangeSlices->Array.getUnsafe(1)
+      let byName = name => shipOrder.commands->Array.find(c => c.name == name)
+      expect((
+        byName("ShipOrder")->Option.flatMap(c => c.allowedStates),
+        byName("CancelShipment")->Option.flatMap(c => c.allowedStates),
+      ))->toEqual((Some(["Placed"]), None))
+    })
+
     testSync("ShipOrder: the @noApi variant carries no callable mutation field (no sibling leak)", () => {
       // Regression: for a single-exposed-command slice, `mutationFieldFor`
       // resolves every variant — including the @noApi one — to the slice's one
@@ -777,7 +938,7 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
           groupBy: None,
           visibility: None,
           live: None,
-          retired: Some({field, label: "", showWhenFalse: false, values: None}),
+          retired: Some({field, label: "", showWhenFalse: false, values: None, namedWhenRetired: false}),
         },
       )
 
@@ -812,6 +973,7 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
               label: "",
               showWhenFalse: false,
               values: Some(["Deactivated", "Closed"]),
+              namedWhenRetired: false,
             }),
           },
         )
@@ -856,6 +1018,108 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
     })
   })
 
+  // A misspelled retirement state used to be fatal or merely logged depending on
+  // where the enum happened to be declared — the PPX refuses it when the enum is
+  // in the same file, and this pass, which sees the resolved schema, only warned.
+  // File layout is not a defensible arbiter of whether a data-exposure bug stops
+  // a build, so this rung was raised to match the other.
+  describe("@retired state names are checked against the field's own enum", () => {
+    let withRetiredStates = (schema, ~field, ~lifecycle, ~values) =>
+      schema->S.castToUnknown->S.Metadata.set(
+        ~id=Reventless.StateAnnotations.stateAnnotationsId,
+        {
+          ids: [],
+          compositeIds: [],
+          subIds: [],
+          compositeSubIds: [],
+          indexes: [],
+          hidden: [],
+          summary: [],
+          drillTargets: [],
+          drillTargetKeys: [],
+          collapsed: [],
+          scan: [],
+          scanSort: [],
+          semantic: [],
+          metric: [],
+          lifecycle,
+          groupBy: None,
+          visibility: None,
+          live: None,
+          retired: Some({field, label: "", showWhenFalse: false, values, namedWhenRetired: false}),
+        },
+      )
+
+    let shelf = values =>
+      S.schema(s =>
+        {
+          "shelf": s.matches(S.union([S.literal("Listed"), S.literal("Archived")])),
+        }
+      )->withRetiredStates(~field="shelf", ~lifecycle=Some("shelf"), ~values=Some(values))
+
+    let check = schema => Plugin_Structure.checkRetiredValue(~entityName="Products", schema)
+
+    testSync("a declared state passes", () => {
+      expect(check(shelf(["Archived"])))->toEqual(Plugin_Structure.Checked([]))
+    })
+
+    // Reported per state rather than as a set: one wrong entry among several
+    // still narrows something, so the symptom is a subset of rows leaking.
+    testSync("each undeclared state is reported on its own", () => {
+      switch check(shelf(["Archived", "Discontinud", "Withdrawn"])) {
+      | Checked(failures) =>
+        expect(failures->Array.length)->toBe(2)
+        expect(failures->Array.some(f => f->String.includes("Discontinud")))->toBe(true)
+        expect(failures->Array.some(f => f->String.includes("Withdrawn")))->toBe(true)
+        // Naming what the field does declare is what turns the failure into a fix.
+        expect(failures->Array.every(f => f->String.includes("Listed, Archived")))->toBe(true)
+      | other => expect(other)->toEqual(Plugin_Structure.Checked([]))
+      }
+    })
+
+    // The condition that came with promoting this: a fatal rule that is silent
+    // when it cannot run looks exactly like one that passed.
+    testSync("a field with no cases to compare against says so instead of passing", () => {
+      let schema =
+        S.schema(s => {"shelf": s.matches(S.string)})->withRetiredStates(
+          ~field="shelf",
+          ~lifecycle=Some("shelf"),
+          ~values=Some(["Archived"]),
+        )
+      switch check(schema) {
+      | Unchecked(why) => expect(why->String.includes("no cases"))->toBe(true)
+      | other => expect(other)->toEqual(Plugin_Structure.Unchecked(""))
+      }
+    })
+
+    // The boolean form names no state, so there is nothing to compare — which is
+    // not the same as having failed to compare it.
+    testSync("the boolean form is not a skip", () => {
+      let schema =
+        S.schema(s => {"archived": s.matches(S.bool)})->withRetiredStates(
+          ~field="archived",
+          ~lifecycle=None,
+          ~values=None,
+        )
+      expect(Plugin_Structure.checkRetiredValue(~entityName="Products", schema))->toEqual(
+        Plugin_Structure.NotDeclared,
+      )
+    })
+
+    // The second rule stays a warning: retirement still works, and which field
+    // carries it is a modelling judgement rather than a name that is wrong.
+    testSync("a state on a non-lifecycle field is not a failure", () => {
+      let schema =
+        S.schema(s =>
+          {
+            "shelf": s.matches(S.union([S.literal("Listed"), S.literal("Archived")])),
+            "lifecycle": s.matches(S.union([S.literal("Draft"), S.literal("Live")])),
+          }
+        )->withRetiredStates(~field="shelf", ~lifecycle=Some("lifecycle"), ~values=Some(["Archived"]))
+      expect(check(schema))->toEqual(Plugin_Structure.Checked([]))
+    })
+  })
+
   // Shared by the read-side and write-side schema cases below, which ask the
   // same question of the same emitter.
   let getProperty = (json: JSON.t, key: string): option<JSON.t> =>
@@ -962,7 +1226,7 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
   // The generator captures each component's chapter (source-folder grouping band)
   // and passes it as ~componentChapters; Plugin_Structure looks it up by Spec.name
   // and threads it onto every def, so a deployed-graph consumer can render chapter
-  // bands without workspace access. See docs/plans/deployed-chapter-grouping.md.
+  // bands without workspace access. See docs/plans/done/deployed-chapter-grouping.md.
   describe("componentChapters threading", () => {
     let chaptered = Plugin_Structure.make(
       ~name="TestPlugin",

package/tests/plugin/PluginStructureTest.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_Exn from "@rescript/runtime/lib/es6/Stdlib_Exn.js";
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
@@ -8,6 +9,7 @@ import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as DateTime$Reventless from "@reventlessdev/reventless-spec/src/types/DateTime.res.mjs";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
 import * as StorageRef$Reventless from "@reventlessdev/reventless-spec/src/semantic/StorageRef.res.mjs";
 import * as Api_Naming$ReventlessCore from "../../src/components/Api/Api_Naming.res.mjs";
@@ -22,8 +24,10 @@ import * as PsUploadAvatar$ReventlessCore from "./StateChangeSlice/PsUploadAvata
 import * as PsAnnotatedView$ReventlessCore from "./StateViewSlice/PsAnnotatedView.res.mjs";
 import * as PsAttachInvoice$ReventlessCore from "./StateChangeSlice/PsAttachInvoice.res.mjs";
 import * as PsCustomersView$ReventlessCore from "./StateViewSlice/PsCustomersView.res.mjs";
+import * as PsShipmentsView$ReventlessCore from "./StateViewSlice/PsShipmentsView.res.mjs";
 import * as Plugin_Structure$ReventlessCore from "../../src/plugin/component/Plugin_Structure.res.mjs";
 import * as PsCategoriesView$ReventlessCore from "./StateViewSlice/PsCategoriesView.res.mjs";
+import * as PsDispatchShipment$ReventlessCore from "./StateChangeSlice/PsDispatchShipment.res.mjs";
 import * as Capability_Inference$ReventlessCore from "../../src/plugin/component/Capability_Inference.res.mjs";
 import * as PsAvailableProductsView$ReventlessCore from "./StateViewSlice/PsAvailableProductsView.res.mjs";
 
@@ -337,6 +341,62 @@ let PsReserveStockSlice = {
   make: make$10
 };
 
+let Behavior$6 = {
+  initialState: false,
+  evolve: PsDispatchShipment$ReventlessCore.evolve,
+  decide: PsDispatchShipment$ReventlessCore.decide,
+  moduleUrl: PsDispatchShipment$ReventlessCore.moduleUrl
+};
+
+function make$11(param, param$1, param$2, param$3, param$4, param$5) {
+  return 0;
+}
+
+let PsDispatchShipmentSlice_Spec = {
+  name: PsDispatchShipment$ReventlessCore.name,
+  moduleUrl: PsDispatchShipment$ReventlessCore.moduleUrl,
+  Id: Id$Reventless.$$String,
+  consumedEventSchema: PsDispatchShipment$ReventlessCore.consumedEventSchema,
+  errorSchema: PsDispatchShipment$ReventlessCore.errorSchema,
+  eventSchema: PsDispatchShipment$ReventlessCore.eventSchema,
+  commandSchema: PsDispatchShipment$ReventlessCore.commandSchema,
+  commandAuthorization: PsDispatchShipment$ReventlessCore.commandAuthorization,
+  readConsistency: PsDispatchShipment$ReventlessCore.readConsistency
+};
+
+let PsDispatchShipmentSlice = {
+  Spec: PsDispatchShipmentSlice_Spec,
+  Behavior: Behavior$6,
+  isAsync: false,
+  make: make$11
+};
+
+let Projection$5 = {
+  project: PsShipmentsView$ReventlessCore.project,
+  moduleUrl: PsShipmentsView$ReventlessCore.moduleUrl
+};
+
+function make$12(param, param$1, param$2) {
+  return 0;
+}
+
+let PsShipmentsViewSlice_Spec = {
+  name: PsShipmentsView$ReventlessCore.name,
+  moduleUrl: PsShipmentsView$ReventlessCore.moduleUrl,
+  stateSchema: PsShipmentsView$ReventlessCore.stateSchema,
+  consumedEventSchema: PsShipmentsView$ReventlessCore.consumedEventSchema,
+  config: PsShipmentsView$ReventlessCore.config,
+  subIdConfig: undefined,
+  authorization: PsShipmentsView$ReventlessCore.authorization,
+  visibility: PsShipmentsView$ReventlessCore.visibility
+};
+
+let PsShipmentsViewSlice = {
+  Spec: PsShipmentsViewSlice_Spec,
+  Projection: Projection$5,
+  make: make$12
+};
+
 let structure = Plugin_Structure$ReventlessCore.make("TestPlugin", undefined, undefined, [
   PsOrdersViewSlice,
   PsAvailableProductsViewSlice,
@@ -347,6 +407,102 @@ let structure = Plugin_Structure$ReventlessCore.make("TestPlugin", undefined, un
   PsShipOrderSlice
 ], undefined, undefined, undefined, undefined, undefined, undefined);
 
+globalThis.describe("lifecycle topology", () => {
+  let ordersStates = Object.fromEntries([[
+      "Orders",
+      [
+        "Placed",
+        "Shipped",
+        "Cancelled"
+      ]
+    ]]);
+  let writableWith = commands => ({
+    name: "Ordering",
+    commands: commands,
+    producedEventTypes: [],
+    consumedEventTypes: [],
+    linkedViews: ["Orders"],
+    consistencyRead: undefined,
+    events: [],
+    errors: [],
+    chapter: undefined
+  });
+  let command = (name, allowedStates, targetState, param) => ({
+    name: name,
+    schema: "",
+    level: "Instance",
+    aggregateIdField: undefined,
+    mutationField: "",
+    references: [],
+    allowedStates: allowedStates,
+    targetState: targetState,
+    apiExposed: undefined,
+    requiredAccess: undefined,
+    ownerField: undefined
+  });
+  globalThis.test("names a state no command can reach", () => {
+    let findings = Plugin_Structure$ReventlessCore.lifecycleTopologyFindings([writableWith([command("Ship", ["Placed"], "Shipped", undefined)])], ordersStates);
+    globalThis.expect(findings.map(param => param[1].includes("Cancelled"))).toEqual([true]);
+  });
+  globalThis.test("says nothing when every state is reachable", () => {
+    let findings = Plugin_Structure$ReventlessCore.lifecycleTopologyFindings([writableWith([
+        command("Ship", ["Placed"], "Shipped", undefined),
+        command("Cancel", ["Placed"], "Cancelled", undefined)
+      ])], ordersStates);
+    globalThis.expect(findings.length).toBe(0);
+  });
+  globalThis.test("does not call the initial state unreachable", () => {
+    let findings = Plugin_Structure$ReventlessCore.lifecycleTopologyFindings([writableWith([
+        command("Ship", ["Placed"], "Shipped", undefined),
+        command("Cancel", ["Placed"], "Cancelled", undefined)
+      ])], ordersStates);
+    globalThis.expect(findings.map(param => param[1].includes("Placed"))).toEqual([]);
+  });
+  globalThis.test("does not report a state with no way out", () => {
+    let findings = Plugin_Structure$ReventlessCore.lifecycleTopologyFindings([writableWith([
+        command("Ship", ["Placed"], "Shipped", undefined),
+        command("Cancel", ["Placed"], "Cancelled", undefined)
+      ])], ordersStates);
+    globalThis.expect(findings.length).toBe(0);
+  });
+});
+
+globalThis.describe("@transition cross-check", () => {
+  let buildBad = () => {
+    try {
+      Plugin_Structure$ReventlessCore.make("TransitionPlugin", undefined, undefined, [PsShipmentsViewSlice], [PsDispatchShipmentSlice], undefined, undefined, undefined, undefined, undefined, undefined);
+      return;
+    } catch (raw_e) {
+      let e = Primitive_exceptions.internalToException(raw_e);
+      if (e.RE_EXN_ID === Stdlib_Exn.$$Error) {
+        return Stdlib_Option.getOr(e._1.message, "");
+      } else {
+        return "";
+      }
+    }
+  };
+  globalThis.test("a state no linked view declares fails the build", () => {
+    globalThis.expect(Stdlib_Option.isSome(buildBad())).toBe(true);
+  });
+  globalThis.test("the failure names the command, the state and the view", () => {
+    let message = Stdlib_Option.getOr(buildBad(), "");
+    globalThis.expect([
+      message.includes("DispatchShipment"),
+      message.includes("Dispatchd"),
+      message.includes("Shipments"),
+      message.includes("Booked")
+    ]).toEqual([
+      true,
+      true,
+      true,
+      true
+    ]);
+  });
+  globalThis.test("a plugin whose views declare no lifecycle still builds", () => {
+    globalThis.expect(structure.stateChangeSlices.length).toBe(2);
+  });
+});
+
 globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
   globalThis.describe("stateChangeSlices", () => {
     globalThis.test("produces two SCS entries in declaration order", () => {
@@ -424,7 +580,7 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
         false
       ]);
     });
-    globalThis.test("ShipOrder: @targetState(\"Shipped\") flows through the PPX to commandDef.targetState", () => {
+    globalThis.test("ShipOrder: @transition's target flows through the PPX to commandDef.targetState", () => {
       let shipOrder = structure.stateChangeSlices[1];
       let byName = name => shipOrder.commands.find(c => c.name === name);
       globalThis.expect([
@@ -435,6 +591,17 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
         undefined
       ]);
     });
+    globalThis.test("ShipOrder: @transition's from-set flows through to commandDef.allowedStates", () => {
+      let shipOrder = structure.stateChangeSlices[1];
+      let byName = name => shipOrder.commands.find(c => c.name === name);
+      globalThis.expect([
+        Stdlib_Option.flatMap(byName("ShipOrder"), c => c.allowedStates),
+        Stdlib_Option.flatMap(byName("CancelShipment"), c => c.allowedStates)
+      ]).toEqual([
+        ["Placed"],
+        undefined
+      ]);
+    });
     globalThis.test("ShipOrder: the @noApi variant carries no callable mutation field (no sibling leak)", () => {
       let shipOrder = structure.stateChangeSlices[1];
       let byName = name => shipOrder.commands.find(c => c.name === name);
@@ -886,7 +1053,8 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
         field: field,
         label: "",
         showWhenFalse: false,
-        values: undefined
+        values: undefined,
+        namedWhenRetired: false
       }
     });
     globalThis.test("publishes the retirement state beside the field", () => {
@@ -916,7 +1084,8 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
           values: [
             "Deactivated",
             "Closed"
-          ]
+          ],
+          namedWhenRetired: false
         }
       });
       let schema = withState(S.schema(s => ({
@@ -959,6 +1128,116 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       globalThis.expect(Plugin_Structure$ReventlessCore.retiredFieldFromStateSchema(schema)).toEqual(undefined);
     });
   });
+  globalThis.describe("@retired state names are checked against the field's own enum", () => {
+    let withRetiredStates = (schema, field, lifecycle, values) => S.Metadata.set(schema, StateAnnotations$Reventless.stateAnnotationsId, {
+      ids: [],
+      compositeIds: [],
+      subIds: [],
+      compositeSubIds: [],
+      indexes: [],
+      hidden: [],
+      summary: [],
+      drillTargets: [],
+      drillTargetKeys: [],
+      collapsed: [],
+      scan: [],
+      scanSort: [],
+      semantic: [],
+      metric: [],
+      lifecycle: lifecycle,
+      groupBy: undefined,
+      visibility: undefined,
+      live: undefined,
+      retired: {
+        field: field,
+        label: "",
+        showWhenFalse: false,
+        values: values,
+        namedWhenRetired: false
+      }
+    });
+    let shelf = values => withRetiredStates(S.schema(s => ({
+      shelf: s.m(S.union([
+        S.literal("Listed"),
+        S.literal("Archived")
+      ]))
+    })), "shelf", "shelf", values);
+    globalThis.test("a declared state passes", () => {
+      globalThis.expect(Plugin_Structure$ReventlessCore.checkRetiredValue("Products", shelf(["Archived"]))).toEqual({
+        TAG: "Checked",
+        _0: []
+      });
+    });
+    globalThis.test("each undeclared state is reported on its own", () => {
+      let failures = Plugin_Structure$ReventlessCore.checkRetiredValue("Products", shelf([
+        "Archived",
+        "Discontinud",
+        "Withdrawn"
+      ]));
+      if (typeof failures !== "object") {
+        globalThis.expect(failures).toEqual({
+          TAG: "Checked",
+          _0: []
+        });
+        return;
+      }
+      if (failures.TAG === "Unchecked") {
+        globalThis.expect(failures).toEqual({
+          TAG: "Checked",
+          _0: []
+        });
+        return;
+      }
+      let failures$1 = failures._0;
+      globalThis.expect(failures$1.length).toBe(2);
+      globalThis.expect(failures$1.some(f => f.includes("Discontinud"))).toBe(true);
+      globalThis.expect(failures$1.some(f => f.includes("Withdrawn"))).toBe(true);
+      globalThis.expect(failures$1.every(f => f.includes("Listed, Archived"))).toBe(true);
+    });
+    globalThis.test("a field with no cases to compare against says so instead of passing", () => {
+      let schema = withRetiredStates(S.schema(s => ({
+        shelf: s.m(S.string)
+      })), "shelf", "shelf", ["Archived"]);
+      let why = Plugin_Structure$ReventlessCore.checkRetiredValue("Products", schema);
+      if (typeof why !== "object") {
+        globalThis.expect(why).toEqual({
+          TAG: "Unchecked",
+          _0: ""
+        });
+        return;
+      }
+      if (why.TAG === "Unchecked") {
+        globalThis.expect(why._0.includes("no cases")).toBe(true);
+        return;
+      }
+      globalThis.expect(why).toEqual({
+        TAG: "Unchecked",
+        _0: ""
+      });
+    });
+    globalThis.test("the boolean form is not a skip", () => {
+      let schema = withRetiredStates(S.schema(s => ({
+        archived: s.m(S.bool)
+      })), "archived", undefined, undefined);
+      globalThis.expect(Plugin_Structure$ReventlessCore.checkRetiredValue("Products", schema)).toEqual("NotDeclared");
+    });
+    globalThis.test("a state on a non-lifecycle field is not a failure", () => {
+      let schema = withRetiredStates(S.schema(s => ({
+        shelf: s.m(S.union([
+          S.literal("Listed"),
+          S.literal("Archived")
+        ])),
+        lifecycle: s.m(S.union([
+          S.literal("Draft"),
+          S.literal("Live")
+        ]))
+      })), "shelf", "lifecycle", ["Archived"]);
+      globalThis.expect(Plugin_Structure$ReventlessCore.checkRetiredValue("Products", schema)).toEqual({
+        TAG: "Checked",
+        _0: []
+      });
+    });
+  });
   let getProperty = (json, key) => {
     let obj = Stdlib_JSON.Decode.object(json);
     if (obj !== undefined) {
@@ -1275,6 +1554,8 @@ export {
   PsUploadAvatarSlice,
   PsChangePhotoSlice,
   PsReserveStockSlice,
+  PsDispatchShipmentSlice,
+  PsShipmentsViewSlice,
   structure,
 }
 /* structure Not a pure module */