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

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 3.0.0-alpha.237 (2026-08-16)
+
+### Features
+
+* **core:** exclude retired rows from reads a caller may not widen ([662f31a](https://github.com/ReventlessDev/reventless-core/commit/662f31abb717bda5154199d349da6dcf8e2d3e78))
+* **core:** let [@retired](https://github.com/retired) name a lifecycle state, not only a boolean ([6bb346b](https://github.com/ReventlessDev/reventless-core/commit/6bb346b4f6a5f33826fc24537953482a76067177))
+* **core:** mark the state that retires a row, and allow more than one ([cb1461f](https://github.com/ReventlessDev/reventless-core/commit/cb1461f024d3ca3b53fd9c8b010a054e3fcc4555))
+* **core:** publish queryableDef.retiredField from the [@retired](https://github.com/retired) annotation ([b44436a](https://github.com/ReventlessDev/reventless-core/commit/b44436a997b6c4ff0531f0b07d793cc858eef94a))
+* **spec:** [@retired](https://github.com/retired) state-field annotation and its schema emission ([2d8234b](https://github.com/ReventlessDev/reventless-core/commit/2d8234b6b3dd8f479031a67eb5b4b47b5c0c2ff9))
+
+
 # 3.0.0-alpha.236 (2026-08-15)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.236",
+  "version": "3.0.0-alpha.237",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,21 +29,21 @@
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
-    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.7",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.7",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.7",
+    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.7",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-ssh2": "2.0.0-alpha.7",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.142",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.143",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.31",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.114"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.115"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.66"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.67"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/admin/Platform_Admin_Structure.res

@@ -122,7 +122,9 @@ let pluginReadModel: queryableDef = {
   // Hand-rolled rather than resolved, but the rung is the same one
   // `labelFieldsFromStateSchema` would report for a field literally named `name`.
   labelFieldSource: Some("convention"),
-  statusField: Some("status"),
+  // The published wire name stays `status` — it is what the SDL declares and what
+  // stored rows carry. Only the key naming it moved.
+  lifecycleField: Some("status"),
   visibility: None,
   chapter: None,
   // The admin fragment hand-declares its query names rather than deriving them from
@@ -137,6 +139,8 @@ let pluginReadModel: queryableDef = {
   idFieldSource: None,
   requiredAccess: None,
   ownerField: None,
+  retiredField: None,
+  retiredValues: None,
 }
 
 let structure: pluginStructure = {

package/src/admin/Platform_Admin_Structure.res.mjs

@@ -137,7 +137,7 @@ let pluginReadModel_searchableFields = ["name"];
 
 let pluginReadModel_labelFieldSource = "convention";
 
-let pluginReadModel_statusField = "status";
+let pluginReadModel_lifecycleField = "status";
 
 let pluginReadModel_singleQueryField = Api_Naming$ReventlessCore.adminField("Plugin");
 
@@ -150,8 +150,10 @@ let pluginReadModel = {
   labelField: "name",
   searchableFields: pluginReadModel_searchableFields,
   labelFieldSource: pluginReadModel_labelFieldSource,
-  statusField: pluginReadModel_statusField,
+  lifecycleField: pluginReadModel_lifecycleField,
   ownerField: undefined,
+  retiredField: undefined,
+  retiredValues: undefined,
   visibility: undefined,
   chapter: undefined,
   singleQueryField: pluginReadModel_singleQueryField,

package/src/admin/Platform_ComponentDefinitionsApi.res

@@ -29,7 +29,7 @@ let sdlTypes: array<string> = [
   // structures persisted before the fields existed decode as `None`, a hand-rolled
   // def may decline to state them, and a state whose key cannot be resolved has no
   // `idField` to report.
-  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n  requiredAccess: [String!]\n  ownerField: String\n}`,
+  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  lifecycleField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n  requiredAccess: [String!]\n  ownerField: String\n  retiredField: String\n  retiredValues: [String!]\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n  targetName: String\n  chapter: String\n}`,
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_InboundTranslationSliceDef {\n  name: String!\n  commandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
@@ -113,7 +113,7 @@ let encodeQueryableDef = (r: queryableDef): JSON.t =>
       "labelFieldSource",
       r.labelFieldSource->Option.mapOr(JSON.Encode.null, JSON.Encode.string),
     ),
-    ("statusField", r.statusField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    ("lifecycleField", r.lifecycleField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
     // Carried rather than only filtered on: a tooling consumer reading the
     // unfiltered structure needs to know WHICH components are Internal, and a
     // consumer of the filtered query reads null here because nothing Internal
@@ -128,6 +128,8 @@ let encodeQueryableDef = (r: queryableDef): JSON.t =>
     ("idFieldSource", r.idFieldSource->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
     ("requiredAccess", r.requiredAccess->Option.mapOr(JSON.Encode.null, encodeStrings)),
     ("ownerField", r.ownerField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    ("retiredField", r.retiredField->Option.mapOr(JSON.Encode.null, JSON.Encode.string)),
+    ("retiredValues", r.retiredValues->Option.mapOr(JSON.Encode.null, encodeStrings)),
   ])->JSON.Encode.object
 
 let encodeEventDef = (e: eventDef): JSON.t =>

package/src/admin/Platform_ComponentDefinitionsApi.res.mjs

@@ -10,7 +10,7 @@ let sdlTypes = [
   `type Platform_EventDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   `type Platform_ErrorDef {\n  name: String!\n  schema: String!\n  references: [Platform_FieldReference!]!\n}`,
   `type Platform_WriteSideDef {\n  name: String!\n  commands: [Platform_CommandDef!]!\n  linkedViews: [String!]!\n  consistencyRead: String\n  producedEventTypes: [String!]!\n  consumedEventTypes: [String!]!\n  events: [Platform_EventDef!]!\n  errors: [Platform_ErrorDef!]!\n  chapter: String\n}`,
-  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  statusField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n  requiredAccess: [String!]\n  ownerField: String\n}`,
+  `type Platform_ReadSideDef {\n  name: String!\n  queryField: String!\n  schema: String!\n  consumedEventTypes: [String!]!\n  linkedWriteSide: [String!]!\n  labelField: String!\n  searchableFields: [String!]!\n  labelFieldSource: String\n  lifecycleField: String\n  visibility: String\n  chapter: String\n  singleQueryField: String\n  idField: String\n  idFieldSource: String\n  requiredAccess: [String!]\n  ownerField: String\n  retiredField: String\n  retiredValues: [String!]\n}`,
   `type Platform_AutomationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  producedCommandTypes: [String!]!\n  targetName: String\n  chapter: String\n}`,
   `type Platform_OutboundTranslationSliceDef {\n  name: String!\n  consumedEventTypes: [String!]!\n  inboundCommandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
   `type Platform_InboundTranslationSliceDef {\n  name: String!\n  commandTypes: [String!]!\n  targetName: String\n  externalSystem: String\n  chapter: String\n}`,
@@ -130,8 +130,8 @@ function encodeQueryableDef(r) {
       Stdlib_Option.mapOr(r.labelFieldSource, null, prim => prim)
     ],
     [
-      "statusField",
-      Stdlib_Option.mapOr(r.statusField, null, prim => prim)
+      "lifecycleField",
+      Stdlib_Option.mapOr(r.lifecycleField, null, prim => prim)
     ],
     [
       "visibility",
@@ -160,6 +160,14 @@ function encodeQueryableDef(r) {
     [
       "ownerField",
       Stdlib_Option.mapOr(r.ownerField, null, prim => prim)
+    ],
+    [
+      "retiredField",
+      Stdlib_Option.mapOr(r.retiredField, null, prim => prim)
+    ],
+    [
+      "retiredValues",
+      Stdlib_Option.mapOr(r.retiredValues, null, encodeStrings)
     ]
   ]);
 }

package/src/components/Api/GraphQL_FragmentGenerator.res

@@ -436,6 +436,19 @@ let deriveByIdsQueryField = (
 ): string =>
   `  ${listFieldName}ByIds(ids: [String!]!): [${returnTypeName}!]!`
 
+// `includeRetired` sits beside the paging arguments rather than inside `filter`,
+// and that placement is the point. `filter` is the caller's description of the
+// rows they want; this is a request to lift a restriction the server placed on
+// them, which the server grants or ignores on its own terms. Putting it in the
+// filter input would also require the field to be a declared filter field, which
+// would publish `<field>Eq` to callers who can only ever get an empty page from
+// it.
+//
+// Emitted unconditionally, on every connection field, whether or not the view
+// declares a retirement flag. A view that declares none ignores it, and the
+// alternative — an argument that appears and disappears with the annotation —
+// makes adding `@retired` a breaking schema change for every client that had
+// already learned the field's shape.
 let deriveConnectionQueryField = (
   ~listFieldName: string,
   ~singularTypeName: string,
@@ -443,7 +456,7 @@ let deriveConnectionQueryField = (
   ~hasOrderBy: bool=false,
 ): string => {
   let orderByArg = hasOrderBy ? `, orderBy: ${singularTypeName}OrderBy` : ""
-  `  ${listFieldName}(filter: ${filterTypeName}${orderByArg}, first: Int, after: String, last: Int, before: String): ${singularTypeName}Connection!`
+  `  ${listFieldName}(filter: ${filterTypeName}${orderByArg}, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): ${singularTypeName}Connection!`
 }
 
 // ── Mutation field derivation ──────────────────────────────────────────────

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

@@ -374,7 +374,7 @@ function deriveByIdsQueryField(listFieldName, returnTypeName) {
 function deriveConnectionQueryField(listFieldName, singularTypeName, filterTypeName, hasOrderByOpt) {
   let hasOrderBy = hasOrderByOpt !== undefined ? hasOrderByOpt : false;
   let orderByArg = hasOrderBy ? `, orderBy: ` + singularTypeName + `OrderBy` : "";
-  return `  ` + listFieldName + `(filter: ` + filterTypeName + orderByArg + `, first: Int, after: String, last: Int, before: String): ` + singularTypeName + `Connection!`;
+  return `  ` + listFieldName + `(filter: ` + filterTypeName + orderByArg + `, first: Int, after: String, last: Int, before: String, includeRetired: Boolean): ` + singularTypeName + `Connection!`;
 }
 
 function deriveMutationFieldFromObject(fieldName, collectedTypes, seenTypes, variantSchema) {

package/src/components/Api/QueryDbListQuery.res

@@ -35,6 +35,17 @@ let getId = (item: JSON.t): string =>
 // String form of a field for comparison / cursor purposes: the string itself,
 // or a number rendered via Float.toString, else None. The push-down must render
 // the same string in SQL (CAST … AS TEXT) for cursor/order parity.
+// A boolean field's value, or None when the row does not carry one. Separate
+// from `getFieldString` rather than reusing it: JSON `true` stringifies to
+// nothing useful, and a retirement predicate read off a coerced string would
+// treat `"false"` — a legitimate value for a field someone stored as text — as
+// truthy and hide the row.
+let getFieldBool = (item: JSON.t, field: string): option<bool> =>
+  item
+  ->JSON.Decode.object
+  ->Option.flatMap(d => d->Dict.get(field))
+  ->Option.flatMap(JSON.Decode.bool)
+
 let getFieldString = (item: JSON.t, field: string): option<string> =>
   item
   ->JSON.Decode.object
@@ -97,6 +108,7 @@ let run = (
   ~labelField: string,
   ~decodeLocalId: string => option<string>=Api_Ids.toLocalId,
   ~ownerScope: option<(string, string)>=?,
+  ~retiredScope: option<Reventless.OwnerScope.retiredScope>=?,
 ): JSON.t => {
   let filterDict =
     argsDict->Dict.get("filter")->Option.flatMap(JSON.Decode.object)->Option.getOr(Dict.make())
@@ -185,7 +197,19 @@ let run = (
       getFieldString(item, field)->Option.mapOr(false, v => v == required)
     | None => true
     }
-    passSearch && passPrefix && passIds && passPerField && passOwner
+    // The missing-field rule lives in `OwnerScope.isRetiredValue`, beside the two
+    // forms it has to answer for; the note on why it lands the opposite way from
+    // `passOwner` is there.
+    let passRetired = switch retiredScope {
+    | Some(scope) =>
+      !(
+        scope->Reventless.OwnerScope.isRetiredValue(
+          item->JSON.Decode.object->Option.flatMap(d => d->Dict.get(scope.field)),
+        )
+      )
+    | None => true
+    }
+    passSearch && passPrefix && passIds && passPerField && passOwner && passRetired
   })
 
   let orderByDict = argsDict->Dict.get("orderBy")->Option.flatMap(JSON.Decode.object)

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

@@ -5,6 +5,7 @@ import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Stdlib_Nullable from "@rescript/runtime/lib/es6/Stdlib_Nullable.js";
 import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as OwnerScope$Reventless from "@reventlessdev/reventless-spec/src/types/OwnerScope.res.mjs";
 import * as Api_Ids$ReventlessCore from "./Api_Ids.res.mjs";
 
 function encodeCursor(value) {
@@ -19,6 +20,10 @@ function getId(item) {
   return Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d["id"]), Stdlib_JSON.Decode.string), "");
 }
 
+function getFieldBool(item, field) {
+  return Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d[field]), Stdlib_JSON.Decode.bool);
+}
+
 function getFieldString(item, field) {
   return Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d[field]), v => {
     let s = Stdlib_JSON.Decode.string(v);
@@ -48,7 +53,7 @@ function buildConnection(pageItems, hasNextPage, hasPreviousPage, cursorValueOf)
   };
 }
 
-function run(items, argsDict, capability, labelField, decodeLocalIdOpt, ownerScope) {
+function run(items, argsDict, capability, labelField, decodeLocalIdOpt, ownerScope, retiredScope) {
   let decodeLocalId = decodeLocalIdOpt !== undefined ? decodeLocalIdOpt : Api_Ids$ReventlessCore.toLocalId;
   let filterDict = Stdlib_Option.getOr(Stdlib_Option.flatMap(argsDict["filter"], Stdlib_JSON.Decode.object), {});
   let search = Stdlib_Option.flatMap(filterDict["search"], Stdlib_JSON.Decode.string);
@@ -102,8 +107,9 @@ function run(items, argsDict, capability, labelField, decodeLocalIdOpt, ownerSco
     } else {
       passOwner = true;
     }
-    if (passSearch && passPrefix && passIds && passPerField) {
-      return passOwner;
+    let passRetired = retiredScope !== undefined ? !OwnerScope$Reventless.isRetiredValue(retiredScope, Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d[retiredScope.field])) : true;
+    if (passSearch && passPrefix && passIds && passPerField && passOwner) {
+      return passRetired;
     } else {
       return false;
     }
@@ -214,8 +220,9 @@ export {
   decodeCursor,
   defaultListPageSize,
   getId,
+  getFieldBool,
   getFieldString,
   buildConnection,
   run,
 }
-/* No side effect */
+/* OwnerScope-Reventless Not a pure module */

package/src/components/Api/SuryToJsonSchema.res

@@ -101,6 +101,45 @@ let mergeAnnotations = (
       }
     | None => ()
     }
+    switch spec.retired {
+    | Some(r) if r.field === fieldName =>
+      // `x-reventless-retired: {label?, showWhenFalse, values?, value?}`. The
+      // label is omitted when empty, the way `x-reventless-metric` omits its own,
+      // so a consumer deriving one from the field name can tell "not stated" from
+      // "stated as empty". `showWhenFalse` always travels: it is a decision the
+      // annotation author made either way, and its default is not the consumer's
+      // to pick.
+      //
+      // `values` follows the same omit-rather-than-write-empty rule, and its
+      // absence is what says which form this is: absent ⇒ the row is retired when
+      // the field is `true`; present ⇒ retired when the field's value is in the
+      // set, and the field is the record's lifecycle.
+      //
+      // The singular `value` rides alongside for one release, and only where the
+      // set has exactly one member — there is no singular reading of two. It
+      // exists to close a window, not to support two shapes: a consumer pinned
+      // before the set degrades to nothing at all rather than to a missing badge.
+      // Enforcement never depended on it — the resolvers exclude retired rows
+      // whatever the consumer understands — so the whole of the lag is cosmetic.
+      // Drop it once no consumer predating the set can be reached.
+      let entries = [("showWhenFalse", JSON.Encode.bool(r.showWhenFalse))]
+      let entries = switch r.values {
+      | Some(vs) =>
+        let entries = Array.concat(
+          entries,
+          [("values", JSON.Encode.array(vs->Array.map(JSON.Encode.string)))],
+        )
+        switch vs {
+        | [only] => Array.concat(entries, [("value", JSON.Encode.string(only))])
+        | _ => entries
+        }
+      | None => entries
+      }
+      let entries =
+        r.label === "" ? entries : Array.concat([("label", JSON.Encode.string(r.label))], entries)
+      obj->Dict.set("x-reventless-retired", JSON.Encode.object(Dict.fromArray(entries)))
+    | _ => ()
+    }
     switch spec.metric->Array.find(((field, _)) => field === fieldName) {
     | Some((_, m)) =>
       // `x-reventless-metric: {aggregate, label}`. Omit an empty label so the

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

@@ -90,18 +90,49 @@ function mergeAnnotations(fieldSchema, fieldName, spec) {
       obj["x-reventless-semantic"] = semanticId;
     }
   }
+  let r = spec.retired;
+  if (r !== undefined && r.field === fieldName) {
+    let entries = [[
+        "showWhenFalse",
+        r.showWhenFalse
+      ]];
+    let vs = r.values;
+    let entries$1;
+    if (vs !== undefined) {
+      let entries$2 = entries.concat([[
+          "values",
+          vs.map(prim => prim)
+        ]]);
+      if (vs.length !== 1) {
+        entries$1 = entries$2;
+      } else {
+        let only = vs[0];
+        entries$1 = entries$2.concat([[
+            "value",
+            only
+          ]]);
+      }
+    } else {
+      entries$1 = entries;
+    }
+    let entries$3 = r.label === "" ? entries$1 : [[
+          "label",
+          r.label
+        ]].concat(entries$1);
+    obj["x-reventless-retired"] = Object.fromEntries(entries$3);
+  }
   let match$4 = spec.metric.find(param => param[0] === fieldName);
   if (match$4 !== undefined) {
     let m = match$4[1];
-    let entries = [[
+    let entries$4 = [[
         "aggregate",
         m.aggregate
       ]];
-    let entries$1 = m.label === "" ? entries : entries.concat([[
+    let entries$5 = m.label === "" ? entries$4 : entries$4.concat([[
           "label",
           m.label
         ]]);
-    obj["x-reventless-metric"] = Object.fromEntries(entries$1);
+    obj["x-reventless-metric"] = Object.fromEntries(entries$5);
   }
   return obj;
 }

package/src/plugin/component/Plugin_Structure.res

@@ -26,13 +26,13 @@ let rec isLabelShape = (t: SchemaType.schemaType): bool =>
   | _ => false
   }
 
-// Whether a field can hold a lifecycle status: a closed set of values, or an
-// optional one. A free-text `status: string` is not a lifecycle — filtering a
-// command menu against `allowedStates` needs states to compare with.
-let rec isStatusShape = (t: SchemaType.schemaType): bool =>
+// Whether a field can hold a lifecycle: a closed set of values, or an optional
+// one. A free-text `lifecycle: string` is not a lifecycle — filtering a command
+// menu against `allowedStates` needs states to compare with.
+let rec isLifecycleShape = (t: SchemaType.schemaType): bool =>
   switch t {
   | Enum(_, _) => true
-  | Nullable(inner) => isStatusShape(inner)
+  | Nullable(inner) => isLifecycleShape(inner)
   | _ => false
   }
 
@@ -44,18 +44,25 @@ let conventionalLabelNames = ["name", "title", "label", "displayname"]
 let shapeOfItem = (~entityName: string, item: S.item): SchemaType.schemaType =>
   SchemaType.fromSury(~parentName=entityName, ~fieldName=item.location, item.schema)
 
-// Resolve the field that holds the entity's lifecycle status, used to filter a
-// per-row command menu against each command's `allowedStates`. Resolution order:
-//   1. Field annotated `@status` (PPX-emitted; see StateAnnotations).
-//   2. Field literally named `"status"` whose IR shape is an enum (convention;
+// Resolve the field that holds the entity's lifecycle, used to filter a per-row
+// command menu against each command's `allowedStates`. Resolution order:
+//   1. Field annotated `@lifecycle` (PPX-emitted; see StateAnnotations).
+//   2. Field literally named `"lifecycle"` whose IR shape is an enum (convention;
 //      mirrors how labelField falls back to a conventionally-named field).
 //   3. None — filter is inert for this read model.
-let statusFieldFromStateSchema = (
+//
+// The convention rung is keyed on `lifecycle` rather than `status` deliberately:
+// `status` is a promiscuous name — geocoding progress, todo-queue progress and
+// translation audit outcome all wear it — so a convention keyed on it guesses,
+// and guesses often. `lifecycle` is a word nobody types by accident, so matching
+// it is closer to a declaration written in the field name. A record whose field
+// is honestly called something else annotates instead.
+let lifecycleFieldFromStateSchema = (
   ~entityName: string,
   stateSchema: S.t<unknown>,
 ): option<string> => {
   let annotated = switch Reventless.StateAnnotations.getSpec(stateSchema) {
-  | Some(spec) => spec.status
+  | Some(spec) => spec.lifecycle
   | None => None
   }
   switch annotated {
@@ -65,7 +72,7 @@ let statusFieldFromStateSchema = (
     | Object({items}) =>
       items
       ->Array.find(item =>
-        item.location == "status" && isStatusShape(shapeOfItem(~entityName, item))
+        item.location == "lifecycle" && isLifecycleShape(shapeOfItem(~entityName, item))
       )
       ->Option.map(item => item.location)
     | _ => None
@@ -73,6 +80,90 @@ let statusFieldFromStateSchema = (
   }
 }
 
+// The field whose truth withdraws a row from ordinary reads. Annotation-only:
+// there is no convention rung here, and its absence is the point. `lifecycleField`
+// may fall back to a field literally named "lifecycle" because guessing wrong makes
+// a command menu filter oddly; guessing wrong here makes rows vanish for every
+// caller who is not elevated, so a boolean named `archived` that nobody annotated
+// stays exactly as visible as it was.
+let retiredFromStateSchema = (
+  stateSchema: S.t<unknown>,
+): option<Reventless.StateAnnotations.retiredSpec> =>
+  switch Reventless.StateAnnotations.getSpec(stateSchema) {
+  | Some(spec) => spec.retired
+  | None => None
+  }
+
+let retiredFieldFromStateSchema = (stateSchema: S.t<unknown>): option<string> =>
+  retiredFromStateSchema(stateSchema)->Option.map(r => r.field)
+
+// The states a row is retired *in*, for the enum form. `None` is the boolean
+// form, where the value is always `true` and naming it would be a parameter that
+// can only hold one thing. A set, because a lifecycle may be withdrawn by more
+// than one state, and a one-member set is the ordinary case.
+//
+// Published beside `retiredField` rather than left for a consumer to dig out of
+// the schema: a client that has the def in hand has the whole predicate, and two
+// places deriving one comparison is how they come to disagree about it.
+let retiredValuesFromStateSchema = (stateSchema: S.t<unknown>): option<array<string>> =>
+  retiredFromStateSchema(stateSchema)->Option.flatMap(r => r.values)
+
+// The check the PPX cannot make, in the one place that can: the payload is a
+// constructor reference the PPX only ever sees as a name, and whether that name
+// is a case of the field's enum needs the schema.
+//
+// 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
+// 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 lifecycle = lifecycleFieldFromStateSchema(~entityName, stateSchema)
+    if lifecycle != Some(field) {
+      log.warn(
+        ~comp="Plugin_Structure",
+        `${entityName}: @retired(${named}) is on "${field}", which is not this record's lifecycle field${lifecycle
+          ->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.`,
+      )
+    }
+    let declared = 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
+        | _ => []
+        }
+      )
+      ->Option.getOr([])
+    | _ => []
+    }
+    // Reported per state rather than as a set: one wrong entry among three still
+    // narrows something, so the symptom is a subset of rows leaking rather than
+    // all of them — which is harder to spot than the single-value case was.
+    if Array.length(declared) > 0 {
+      values
+      ->Array.filter(v => !(declared->Array.includes(v)))
+      ->Array.forEach(v =>
+        log.warn(
+          ~comp="Plugin_Structure",
+          `${entityName}: @retired(${v}) names a state "${field}" does not declare — known values: ${declared->Array.joinWith(
+              ", ",
+            )}.`,
+        )
+      )
+    }
+  | _ => ()
+  }
+
 // 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:
@@ -752,6 +843,7 @@ let make = (
       // edges for any event reaching the read model via a DCB-log-sourced mapping (a classic
       // 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)
       ({
         Reventless.Plugin.name: R.Spec.name,
         queryField: qf.listFieldName,
@@ -761,10 +853,12 @@ let make = (
         labelField: label.field,
         searchableFields: label.searchableFields,
         labelFieldSource: Some(labelFieldSourceToString(label.source)),
-        statusField: statusFieldFromStateSchema(~entityName=R.Spec.name, stateSchema),
-        // Same schema `statusField` reads, so the two cannot disagree about which
+        lifecycleField: lifecycleFieldFromStateSchema(~entityName=R.Spec.name, stateSchema),
+        // Same schema `lifecycleField` reads, so the two cannot disagree about which
         // fields this view has.
         ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
+        retiredField: retiredFieldFromStateSchema(stateSchema),
+        retiredValues: retiredValuesFromStateSchema(stateSchema),
         visibility: visibilityTag(R.Spec.visibility),
         chapter: chapterOf(R.Spec.name),
         // Taken from the `qf` record, never re-derived: `Api_Naming` is the only
@@ -787,6 +881,7 @@ let make = (
         ~entityName=SVS.Spec.name,
         stateSchema,
       )
+      checkRetiredValue(~entityName=SVS.Spec.name, stateSchema)
       ({
         Reventless.Plugin.name: SVS.Spec.name,
         queryField: qf.listFieldName,
@@ -796,8 +891,10 @@ let make = (
         labelField: label.field,
         searchableFields: label.searchableFields,
         labelFieldSource: Some(labelFieldSourceToString(label.source)),
-        statusField: statusFieldFromStateSchema(~entityName=SVS.Spec.name, stateSchema),
+        lifecycleField: lifecycleFieldFromStateSchema(~entityName=SVS.Spec.name, stateSchema),
         ownerField: Reventless.Owner.fieldNames(stateSchema)->Array.get(0),
+        retiredField: retiredFieldFromStateSchema(stateSchema),
+        retiredValues: retiredValuesFromStateSchema(stateSchema),
         visibility: visibilityTag(SVS.Spec.visibility),
         chapter: chapterOf(SVS.Spec.name),
         singleQueryField: Some(qf.singleFieldName),