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

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";
@@ -39,7 +40,7 @@ function isLabelShape(_t) {
   };
 }
 
-function isStatusShape(_t) {
+function isLifecycleShape(_t) {
   while (true) {
     let t = _t;
     if (typeof t !== "object") {
@@ -68,15 +69,15 @@ function shapeOfItem(entityName, item) {
   return SchemaType$ReventlessCore.fromSury(entityName, item.location, item.schema);
 }
 
-function statusFieldFromStateSchema(entityName, stateSchema) {
+function lifecycleFieldFromStateSchema(entityName, stateSchema) {
   let spec = StateAnnotations$Reventless.getSpec(stateSchema);
-  let annotated = spec !== undefined ? spec.status : undefined;
+  let annotated = spec !== undefined ? spec.lifecycle : undefined;
   if (annotated !== undefined) {
     return annotated;
   } else if (stateSchema.type === "object") {
     return Stdlib_Option.map(stateSchema.items.find(item => {
-      if (item.location === "status") {
-        return isStatusShape(shapeOfItem(entityName, item));
+      if (item.location === "lifecycle") {
+        return isLifecycleShape(shapeOfItem(entityName, item));
       } else {
         return false;
       }
@@ -86,6 +87,174 @@ function statusFieldFromStateSchema(entityName, stateSchema) {
   }
 }
 
+function retiredFromStateSchema(stateSchema) {
+  let spec = StateAnnotations$Reventless.getSpec(stateSchema);
+  if (spec !== undefined) {
+    return spec.retired;
+  }
+}
+
+function retiredFieldFromStateSchema(stateSchema) {
+  return Stdlib_Option.map(retiredFromStateSchema(stateSchema), r => r.field);
+}
+
+function retiredValuesFromStateSchema(stateSchema) {
+  return Stdlib_Option.flatMap(retiredFromStateSchema(stateSchema), r => r.values);
+}
+
+function checkRetiredValue(entityName, stateSchema) {
+  let match = retiredFromStateSchema(stateSchema);
+  if (match === undefined) {
+    return;
+  }
+  let values = match.values;
+  if (values === undefined) {
+    return;
+  }
+  let field = match.field;
+  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 @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 => {
+      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 [];
+      }
+    }), []) : [];
+  if (declared.length !== 0) {
+    values.filter(v => !declared.includes(v)).forEach(v => log.warn("Plugin_Structure", undefined, entityName + `: @retired(` + v + `) names a state "` + field + `" does not declare — known values: ` + declared.join(", ") + `.`));
+    return;
+  }
+}
+
+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" :
@@ -529,12 +698,22 @@ 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;
     let label = labelFieldsFromStateSchema(R.Spec.name, stateSchema);
     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,
@@ -544,8 +723,10 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       labelField: label.field,
       searchableFields: label.searchableFields,
       labelFieldSource: labelFieldSourceToString(label.source),
-      statusField: statusFieldFromStateSchema(R.Spec.name, stateSchema),
+      lifecycleField: lifecycleFieldFromStateSchema(R.Spec.name, stateSchema),
       ownerField: Owner$Reventless.fieldNames(stateSchema)[0],
+      retiredField: retiredFieldFromStateSchema(stateSchema),
+      retiredValues: retiredValuesFromStateSchema(stateSchema),
       visibility: visibilityTag(R.Spec.visibility),
       chapter: componentChapters[R.Spec.name],
       singleQueryField: qf.singleFieldName,
@@ -561,6 +742,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
     let stateSchema = SVS.Spec.stateSchema;
     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,
@@ -570,8 +753,10 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       labelField: label.field,
       searchableFields: label.searchableFields,
       labelFieldSource: labelFieldSourceToString(label.source),
-      statusField: statusFieldFromStateSchema(SVS.Spec.name, stateSchema),
+      lifecycleField: lifecycleFieldFromStateSchema(SVS.Spec.name, stateSchema),
       ownerField: Owner$Reventless.fieldNames(stateSchema)[0],
+      retiredField: retiredFieldFromStateSchema(stateSchema),
+      retiredValues: retiredValuesFromStateSchema(stateSchema),
       visibility: visibilityTag(SVS.Spec.visibility),
       chapter: componentChapters[SVS.Spec.name],
       singleQueryField: qf.singleFieldName,
@@ -671,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,
@@ -689,10 +876,18 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
 export {
   log,
   isLabelShape,
-  isStatusShape,
+  isLifecycleShape,
   conventionalLabelNames,
   shapeOfItem,
-  statusFieldFromStateSchema,
+  lifecycleFieldFromStateSchema,
+  retiredFromStateSchema,
+  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/src/plugin/lifecycle/PluginsReadModelSpec.res.mjs

@@ -48,10 +48,11 @@ let stateSchema$1 = S.Metadata.set(stateSchema, StateAnnotations$Reventless.stat
   scanSort: [],
   semantic: [],
   metric: [],
-  status: undefined,
+  lifecycle: undefined,
   groupBy: "kind",
   visibility: undefined,
-  live: undefined
+  live: undefined,
+  retired: undefined
 });
 
 let name = "Plugins";

package/tests/admin/Platform_Admin_StructureTest.res

@@ -0,0 +1,49 @@
+// The platform's own admin components, as `Platform_ComponentDefinitions` serves
+// them. The Plugins read model is a framework-generated queryable: its field names
+// are chosen here and read by every client, so the rule that applies to it is the
+// opposite of the one that applies to an authored record.
+//
+// An authored record may follow the convention — name the field `lifecycle` and
+// write no annotation. A generated row cannot, because its field name is a
+// published wire name: `status` in the SDL, in stored QueryDb rows, and in any
+// client selecting it. Renaming it to satisfy a convention would move the
+// contract, break selecting clients and require re-projection. So it declares
+// instead, and the declaration is what this asserts — the failure mode otherwise
+// is silent (a board loses its columns, a command menu stops filtering, and
+// nothing fails to compile).
+
+open JestGlobals
+open Reventless.Plugin
+
+describe("the Plugins read model declares its lifecycle", () => {
+  let rm: queryableDef = Platform_Admin_Structure.pluginReadModel
+
+  testSync("names the field commands branch on", () =>
+    expect(rm.lifecycleField)->toEqual(Some("status"))
+  )
+
+  testSync("and the published wire name is unchanged by the rename", () => {
+    // Stated as its own assertion rather than folded into the one above: the two
+    // say different things. That the field is declared is the fix; that it is
+    // still called `status` is the constraint the fix had to respect.
+    let sdlDeclaresStatus =
+      rm.lifecycleField->Option.mapOr(false, f => f == "status") &&
+        rm.queryField->String.startsWith("Platform_")
+    expect(sdlDeclaresStatus)->toEqual(true)
+  })
+
+  testSync("is served on the encoded def under the new key", () => {
+    let json =
+      rm->Platform_ComponentDefinitionsApi.encodeQueryableDef->JSON.stringify
+    expect(json->String.includes(`"lifecycleField":"status"`))->toEqual(true)
+  })
+
+  testSync("and never under the old one", () =>
+    expect(
+      rm
+      ->Platform_ComponentDefinitionsApi.encodeQueryableDef
+      ->JSON.stringify
+      ->String.includes(`"statusField"`),
+    )->toEqual(false)
+  )
+})

package/tests/admin/Platform_Admin_StructureTest.res.mjs

@@ -0,0 +1,24 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Platform_Admin_Structure$ReventlessCore from "../../src/admin/Platform_Admin_Structure.res.mjs";
+import * as Platform_ComponentDefinitionsApi$ReventlessCore from "../../src/admin/Platform_ComponentDefinitionsApi.res.mjs";
+
+globalThis.describe("the Plugins read model declares its lifecycle", () => {
+  globalThis.test("names the field commands branch on", () => {
+    globalThis.expect(Platform_Admin_Structure$ReventlessCore.pluginReadModel.lifecycleField).toEqual("status");
+  });
+  globalThis.test("and the published wire name is unchanged by the rename", () => {
+    let sdlDeclaresStatus = Stdlib_Option.mapOr(Platform_Admin_Structure$ReventlessCore.pluginReadModel.lifecycleField, false, f => f === "status") && Platform_Admin_Structure$ReventlessCore.pluginReadModel.queryField.startsWith("Platform_");
+    globalThis.expect(sdlDeclaresStatus).toEqual(true);
+  });
+  globalThis.test("is served on the encoded def under the new key", () => {
+    let json = JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodeQueryableDef(Platform_Admin_Structure$ReventlessCore.pluginReadModel));
+    globalThis.expect(json.includes(`"lifecycleField":"status"`)).toEqual(true);
+  });
+  globalThis.test("and never under the old one", () => {
+    globalThis.expect(JSON.stringify(Platform_ComponentDefinitionsApi$ReventlessCore.encodeQueryableDef(Platform_Admin_Structure$ReventlessCore.pluginReadModel)).includes(`"statusField"`)).toEqual(false);
+  });
+});
+
+/*  Not a pure module */

package/tests/admin/Platform_BakedManifestTest.res

@@ -15,7 +15,7 @@ let queryable = (~name, ~visibility=?, ~ownerField=?, ()): queryableDef => {
   labelField: "displayName",
   searchableFields: ["displayName"],
   labelFieldSource: None,
-  statusField: None,
+  lifecycleField: None,
   visibility,
   chapter: None,
   singleQueryField: Some(`Ordering_${name}Single`),
@@ -23,6 +23,8 @@ let queryable = (~name, ~visibility=?, ~ownerField=?, ()): queryableDef => {
   idFieldSource: Some("convention"),
   requiredAccess: None,
   ownerField,
+  retiredField: None,
+  retiredValues: None,
 }
 
 let command = (~name, ~references=[], ~ownerField=?, ()): commandDef => {

package/tests/admin/Platform_BakedManifestTest.res.mjs

@@ -18,8 +18,10 @@ function queryable(name, visibility, ownerField, param) {
     labelField: "displayName",
     searchableFields: ["displayName"],
     labelFieldSource: undefined,
-    statusField: undefined,
+    lifecycleField: undefined,
     ownerField: ownerField,
+    retiredField: undefined,
+    retiredValues: undefined,
     visibility: visibility,
     chapter: undefined,
     singleQueryField: `Ordering_` + name + `Single`,

package/tests/admin/Platform_ComponentDefinitionsApiTest.res

@@ -30,7 +30,7 @@ let qbl: queryableDef = {
   labelField: "displayName",
   searchableFields: ["displayName"],
   labelFieldSource: Some("annotation"),
-  statusField: None,
+  lifecycleField: None,
   visibility: None,
   chapter: None,
   singleQueryField: Some("Catalog_Product"),
@@ -38,6 +38,8 @@ let qbl: queryableDef = {
   idFieldSource: Some("convention"),
   requiredAccess: None,
   ownerField: None,
+  retiredField: None,
+  retiredValues: None,
 }
 
 let wbl: writableDef = {
@@ -162,8 +164,8 @@ describe("encodePluginStructureEntry", () => {
     expect(json->String.includes("\"apiExposed\":true"))->toEqual(true)
   )
 
-  testSync("encodes None statusField as null", () =>
-    expect(json->String.includes("\"statusField\":null"))->toEqual(true)
+  testSync("encodes None lifecycleField as null", () =>
+    expect(json->String.includes("\"lifecycleField\":null"))->toEqual(true)
   )
 
   // Phase 6.3: write-side emitted-event field schemas.
@@ -256,7 +258,7 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
     labelField: "name",
     searchableFields: ["name"],
     labelFieldSource: Some("convention"),
-    statusField: None,
+    lifecycleField: None,
     visibility: Some("Internal"),
     chapter: None,
     singleQueryField: Some("Ordering_AvailableProduct"),
@@ -264,6 +266,8 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
     idFieldSource: Some("sole"),
     requiredAccess: None,
       ownerField: None,
+      retiredField: None,
+      retiredValues: None,
   }
   // A distinct name per source array: the complement has to be fed by both, and
   // reusing one def would hide a version that only walks `readModels`.
@@ -329,7 +333,7 @@ describe("visibility filtering (deployed AutoUI hides Internal)", () => {
   })
 })
 
-describe("allowedStates + statusField populated", () => {
+describe("allowedStates + lifecycleField populated", () => {
   let cmdWithStates: commandDef = {
     name: "Activate",
     schema: "{}",
@@ -353,7 +357,7 @@ describe("allowedStates + statusField populated", () => {
     labelField: "name",
     searchableFields: ["name"],
     labelFieldSource: Some("convention"),
-    statusField: Some("status"),
+    lifecycleField: Some("status"),
     visibility: None,
     chapter: None,
     singleQueryField: Some("Platform_Plugin"),
@@ -361,6 +365,8 @@ describe("allowedStates + statusField populated", () => {
     idFieldSource: None,
     requiredAccess: None,
       ownerField: None,
+      retiredField: None,
+      retiredValues: None,
   }
 
   let wblWithStates: writableDef = {
@@ -402,8 +408,8 @@ describe("allowedStates + statusField populated", () => {
     expect(json->String.includes("\"targetState\":\"Active\""))->toEqual(true)
   )
 
-  testSync("encodes populated statusField as the field name string", () =>
-    expect(json->String.includes("\"statusField\":\"status\""))->toEqual(true)
+  testSync("encodes populated lifecycleField as the field name string", () =>
+    expect(json->String.includes("\"lifecycleField\":\"status\""))->toEqual(true)
   )
 
   // "declares no errors" is an empty list, never null — the SDL types `errors` as

package/tests/admin/Platform_ComponentDefinitionsApiTest.res.mjs

@@ -51,8 +51,10 @@ let qbl = {
   labelField: "displayName",
   searchableFields: qbl_searchableFields,
   labelFieldSource: qbl_labelFieldSource,
-  statusField: undefined,
+  lifecycleField: undefined,
   ownerField: undefined,
+  retiredField: undefined,
+  retiredValues: undefined,
   visibility: undefined,
   chapter: undefined,
   singleQueryField: qbl_singleQueryField,
@@ -198,8 +200,8 @@ globalThis.describe("encodePluginStructureEntry", () => {
   globalThis.test("encodes the command's apiExposed flag (drives the event-graph API badge)", () => {
     globalThis.expect(json.includes("\"apiExposed\":true")).toEqual(true);
   });
-  globalThis.test("encodes None statusField as null", () => {
-    globalThis.expect(json.includes("\"statusField\":null")).toEqual(true);
+  globalThis.test("encodes None lifecycleField as null", () => {
+    globalThis.expect(json.includes("\"lifecycleField\":null")).toEqual(true);
   });
   globalThis.test("encodes writableDef events", () => {
     globalThis.expect(json.includes("\"events\":[{\"name\":\"ProductAdded\"")).toEqual(true);
@@ -282,8 +284,10 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     labelField: "name",
     searchableFields: internalQbl_searchableFields,
     labelFieldSource: internalQbl_labelFieldSource,
-    statusField: undefined,
+    lifecycleField: undefined,
     ownerField: undefined,
+    retiredField: undefined,
+    retiredValues: undefined,
     visibility: internalQbl_visibility,
     chapter: undefined,
     singleQueryField: internalQbl_singleQueryField,
@@ -308,8 +312,10 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
     labelField: "name",
     searchableFields: internalSlice_searchableFields,
     labelFieldSource: internalSlice_labelFieldSource,
-    statusField: undefined,
+    lifecycleField: undefined,
     ownerField: undefined,
+    retiredField: undefined,
+    retiredValues: undefined,
     visibility: internalSlice_visibility,
     chapter: undefined,
     singleQueryField: internalSlice_singleQueryField,
@@ -378,7 +384,7 @@ globalThis.describe("visibility filtering (deployed AutoUI hides Internal)", ()
   });
 });
 
-globalThis.describe("allowedStates + statusField populated", () => {
+globalThis.describe("allowedStates + lifecycleField populated", () => {
   let cmdWithStates_aggregateIdField = "id";
   let cmdWithStates_references = [];
   let cmdWithStates_allowedStates = ["Inactive"];
@@ -401,7 +407,7 @@ globalThis.describe("allowedStates + statusField populated", () => {
   let qblWithStatus_linkedWriteSide = ["Plugin"];
   let qblWithStatus_searchableFields = ["name"];
   let qblWithStatus_labelFieldSource = "convention";
-  let qblWithStatus_statusField = "status";
+  let qblWithStatus_lifecycleField = "status";
   let qblWithStatus_singleQueryField = "Platform_Plugin";
   let qblWithStatus = {
     name: "Plugin",
@@ -412,8 +418,10 @@ globalThis.describe("allowedStates + statusField populated", () => {
     labelField: "name",
     searchableFields: qblWithStatus_searchableFields,
     labelFieldSource: qblWithStatus_labelFieldSource,
-    statusField: qblWithStatus_statusField,
+    lifecycleField: qblWithStatus_lifecycleField,
     ownerField: undefined,
+    retiredField: undefined,
+    retiredValues: undefined,
     visibility: undefined,
     chapter: undefined,
     singleQueryField: qblWithStatus_singleQueryField,
@@ -466,8 +474,8 @@ globalThis.describe("allowedStates + statusField populated", () => {
   globalThis.test("round-trips a declared targetState as the status string", () => {
     globalThis.expect(json.includes("\"targetState\":\"Active\"")).toEqual(true);
   });
-  globalThis.test("encodes populated statusField as the field name string", () => {
-    globalThis.expect(json.includes("\"statusField\":\"status\"")).toEqual(true);
+  globalThis.test("encodes populated lifecycleField as the field name string", () => {
+    globalThis.expect(json.includes("\"lifecycleField\":\"status\"")).toEqual(true);
   });
   globalThis.test("encodes a component with no declared errors as an empty array, not null", () => {
     globalThis.expect(json.includes("\"errors\":[]")).toEqual(true);
@@ -491,8 +499,10 @@ globalThis.describe("singleQueryField reaches the caller", () => {
           labelField: "displayName",
           searchableFields: qbl_searchableFields,
           labelFieldSource: "annotation",
-          statusField: undefined,
+          lifecycleField: undefined,
           ownerField: undefined,
+          retiredField: undefined,
+          retiredValues: undefined,
           visibility: undefined,
           chapter: undefined,
           singleQueryField: undefined,
@@ -536,8 +546,10 @@ globalThis.describe("idField / idFieldSource reach the caller", () => {
           labelField: "displayName",
           searchableFields: qbl_searchableFields,
           labelFieldSource: "annotation",
-          statusField: undefined,
+          lifecycleField: undefined,
           ownerField: undefined,
+          retiredField: undefined,
+          retiredValues: undefined,
           visibility: undefined,
           chapter: undefined,
           singleQueryField: "Catalog_Product",

package/tests/admin/Platform_PluginStructuresApiTest.res

@@ -16,7 +16,7 @@ let publicRm: queryableDef = {
   labelField: "displayName",
   searchableFields: ["displayName"],
   labelFieldSource: Some("annotation"),
-  statusField: None,
+  lifecycleField: None,
   visibility: None,
   chapter: Some("Inventory"),
   singleQueryField: Some("Catalog_Product"),
@@ -24,6 +24,8 @@ let publicRm: queryableDef = {
   idFieldSource: Some("convention"),
   requiredAccess: None,
   ownerField: None,
+  retiredField: None,
+  retiredValues: None,
 }
 
 // The component `Platform_ComponentDefinitions` drops and this query must keep.

package/tests/admin/Platform_PluginStructuresApiTest.res.mjs

@@ -31,8 +31,10 @@ let publicRm = {
   labelField: "displayName",
   searchableFields: publicRm_searchableFields,
   labelFieldSource: publicRm_labelFieldSource,
-  statusField: undefined,
+  lifecycleField: undefined,
   ownerField: undefined,
+  retiredField: undefined,
+  retiredValues: undefined,
   visibility: undefined,
   chapter: publicRm_chapter,
   singleQueryField: publicRm_singleQueryField,
@@ -68,8 +70,10 @@ let internalRm = {
   labelField: "displayName",
   searchableFields: internalRm_searchableFields,
   labelFieldSource: internalRm_labelFieldSource,
-  statusField: undefined,
+  lifecycleField: undefined,
   ownerField: undefined,
+  retiredField: undefined,
+  retiredValues: undefined,
   visibility: internalRm_visibility,
   chapter: internalRm_chapter,
   singleQueryField: internalRm_singleQueryField,

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.