@reventlessdev/reventless-spec 3.0.0-alpha.114 → 3.0.0-alpha.115

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.115 (2026-08-16)
+
+### Features
+
+* **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))
+* **spec:** classify a caller against a view's retirement flag ([5031ce5](https://github.com/ReventlessDev/reventless-core/commit/5031ce573ce56d2407888c7777274e5580c4fb51))
+
+
 # 3.0.0-alpha.114 (2026-08-15)
 
 **Note:** Version bump only for package @reventlessdev/reventless-spec

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.114",
+  "version": "3.0.0-alpha.115",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/schema/platform-api.graphql

@@ -212,15 +212,17 @@ type Platform_ReadSideDef {
   idFieldSource: String
   labelField: String!
   labelFieldSource: String
+  lifecycleField: String
   linkedWriteSide: [String!]!
   name: String!
   ownerField: String
   queryField: String!
   requiredAccess: [String!]
+  retiredField: String
+  retiredValues: [String!]
   schema: String!
   searchableFields: [String!]!
   singleQueryField: String
-  statusField: String
   visibility: String
 }
 
@@ -290,7 +292,7 @@ type Query {
   Platform_ComponentDefinitions: [Platform_ComponentDefinitionEntry!]!
   Platform_Plugin(id: ID!): Platform_Plugin
   Platform_PluginStructures: [Platform_PluginStructureEntry!]!
-  Platform_Plugins(after: String, before: String, filter: Platform_PluginFilter, first: Int, last: Int): Platform_PluginConnection!
+  Platform_Plugins(after: String, before: String, filter: Platform_PluginFilter, first: Int, includeRetired: Boolean, last: Int): Platform_PluginConnection!
   Platform_PluginsByIds(ids: [String!]!): [Platform_Plugin!]!
   Platform_UIFragments: [Platform_UIFragmentEntry!]!
 }

package/src/components/Plugin.res

@@ -170,14 +170,15 @@ type commandDef = {
   mutationField: string,
   references: array<fieldReference>,
   /**
-  Status values under which this command is meaningful. `None` means the command
+  Lifecycle states under which this command is meaningful. `None` means the command
   is always available (back-compat default). `Some([…])` lets AutoUI hide the
-  command on rows whose status field is not in the set — see `queryableDef.statusField`
-  for how the row's status is located. `Some([])` is the defensive "never show" form.
+  command on rows whose lifecycle field is not in the set — see
+  `queryableDef.lifecycleField` for how the row's state is located. `Some([])` is
+  the defensive "never show" form.
   */
   allowedStates: @s.matches(stringArrayOptionSchema) option<array<string>>,
   /**
-  The single status value this command's handler writes — the command's *to*
+  The single lifecycle state this command's handler writes — the command's *to*
   state, sibling of `allowedStates`' *from* set. Source: the
   `@targetState("Shipped")` command-variant annotation. `None` (absent
   annotation) is the back-compat default: AutoUI's board resolver then falls
@@ -262,17 +263,17 @@ type queryableDef = {
   `None` means not stated — defs persisted before this field existed, and
   hand-rolled defs that decline to say. Distinct from `Some("fallback")`, which
   is this side stating that it looked. js_nullable for the same JSON-safety
-  reason as `statusField`.
+  reason as `lifecycleField`.
   */
   labelFieldSource: @s.matches(stringOptionSchema) option<string>,
   /**
-  Name of the state field whose value identifies the row's lifecycle status, used
-  by AutoUI together with `commandDef.allowedStates` to filter the per-row command
-  menu. Resolution order (codegen): (1) field annotated `@status`; (2) a field
-  literally named `"status"`; (3) `None`. Spec authors that hand-roll a
-  `queryableDef` set this explicitly.
+  Name of the state field whose value identifies the row's lifecycle, used by
+  AutoUI together with `commandDef.allowedStates` to filter the per-row command
+  menu. Resolution order (codegen): (1) field annotated `@lifecycle`; (2) a field
+  literally named `"lifecycle"` whose shape is an enum; (3) `None`. Spec authors
+  that hand-roll a `queryableDef` set this explicitly.
   */
-  statusField: @s.matches(stringOptionSchema) option<string>,
+  lifecycleField: @s.matches(stringOptionSchema) option<string>,
   /**
   Name of the state field that ties a row to the principal owning it (`@owner`),
   when the view declares one. Two consequences for a client: reads of this view
@@ -285,6 +286,44 @@ type queryableDef = {
   */
   ownerField: @s.matches(stringOptionSchema) option<string>,
   /**
+  Name of the boolean state field that withdraws a row from ordinary reads
+  (`@retired`), when the view declares one. Reads of this view exclude rows whose
+  flag is true for callers outside `OwnerScope.elevatedGroups`, on the list door
+  and the single-entity door alike; an exempt caller reaches them by asking for
+  them.
+
+  Derived from the annotation and from nothing else — deliberately no fallback to
+  a conventionally-named boolean, unlike `lifecycleField`. A field named `archived`
+  that nobody annotated must not start hiding rows the day this ships, and the
+  cost of guessing wrong here is data disappearing rather than a menu filtering
+  oddly.
+
+  The label the flag reads as is not here. It travels on the state schema, which
+  every consumer of this def already holds, and a second copy is a second thing
+  to keep in step.
+  */
+  retiredField: @s.matches(stringOptionSchema) option<string>,
+  /**
+  The states a row is retired *in*, when the view declares the state form of
+  `@retired` — `Some(["Archived", "Discontinued"])` beside
+  `retiredField: Some("shelfStatus")`. `None` is the boolean form, where the
+  excluded value is always `true` and naming it would be a field that can only
+  hold one thing.
+
+  A set: a lifecycle may be withdrawn by more than one state, which exclude
+  identically and differ only in the way back. Retired iff the field's value is in
+  it, and one member is the ordinary case rather than a special one.
+
+  Published beside the field rather than left for a consumer to re-derive from the
+  state schema: a client holding this def holds the whole predicate, and two places
+  deriving one comparison is how they come to disagree about it.
+
+  The state form is also what lets `@allowedStates` answer command applicability
+  when retired, with no annotation beyond the two — retirement expressed in the
+  vocabulary a command's stance is already written in.
+  */
+  retiredValues: @s.matches(stringArrayOptionSchema) option<array<string>>,
+  /**
   Component visibility hint (`@@reventless.visibility`). `Some("Internal")` marks a
   ReadModel / StateViewSlice that the deployed AutoUI hides from its menu, drill-down
   pages, web event graph and cross-plugin edges. `None` (absent) means Public. Internal
@@ -323,7 +362,7 @@ type queryableDef = {
 
   `None` means not stated — defs persisted before this field existed, and
   hand-rolled defs that decline to say; a consumer falls back to its own
-  derivation there. js_nullable for the same JSON-safety reason as `statusField`.
+  derivation there. js_nullable for the same JSON-safety reason as `lifecycleField`.
   */
   singleQueryField: @s.matches(stringOptionSchema) option<string>,
   /**
@@ -334,7 +373,7 @@ type queryableDef = {
   `None` means unresolved: a state with several `*Id` fields and no name match,
   or with none at all. Such a component gets no key-derived filter or sort until
   its spec declares `@id`. Also `None` on defs persisted before this field
-  existed. js_nullable for the same JSON-safety reason as `statusField`.
+  existed. js_nullable for the same JSON-safety reason as `lifecycleField`.
   */
   idField: @s.matches(stringOptionSchema) option<string>,
   /**

package/src/components/Plugin.res.mjs

@@ -118,8 +118,10 @@ let queryableDefSchema = S.schema(s => ({
   labelField: s.m(S.string),
   searchableFields: s.m(S.array(S.string)),
   labelFieldSource: s.m(stringOptionSchema),
-  statusField: s.m(stringOptionSchema),
+  lifecycleField: s.m(stringOptionSchema),
   ownerField: s.m(stringOptionSchema),
+  retiredField: s.m(stringOptionSchema),
+  retiredValues: s.m(stringArrayOptionSchema),
   visibility: s.m(stringOptionSchema),
   chapter: s.m(stringOptionSchema),
   singleQueryField: s.m(stringOptionSchema),

package/src/components/StateAnnotations.res

@@ -5,7 +5,7 @@ Spec describing the structural annotations declared on the fields of an
 `@compositeId`, `@subId`, `@compositeSubId`, `@index`), a visibility
 annotation (`@hidden`, `@summary`), a hierarchical-rendering annotation
 (`@drillTarget`, `@collapsed`), a server-query opt-in annotation
-(`@scan`, `@scanSort`), a UI-list annotation (`@status`, `@groupBy`), or a
+(`@scan`, `@scanSort`), a UI-list annotation (`@lifecycle`, `@groupBy`), or a
 type-level live-updates annotation (`@live` on the `state` declaration).
 Downstream consumers (UI, MCP, codegen) read the
 spec to surface field roles in JSON Schema as `x-reventless-*` extension
@@ -34,6 +34,54 @@ KPI label, or `""` to let the UI derive one from the field name.
 */
 type metricSpec = {aggregate: string, label: string}
 
+/**
+The field declared `@retired`, and how a consumer should title it.
+
+`field` names what withdraws the row from ordinary use — a deactivated customer,
+an archived category. `label` is what that state is called ("Archived"), or `""`
+to let a consumer derive one from the field name. `showWhenFalse` asks a consumer
+to surface the flag in its negative state too; the default is false, because a
+caller who is not exempt from the narrowing never receives a retired row and would
+otherwise see the same negative marker on every record they can read.
+
+`value` is what decides which of the two forms this is:
+
+- `None` — the **boolean** form. The row is retired when the field is `true`. The
+  right shape for a record whose retirement genuinely is a flag: a `Products` view
+  with an `archived` boolean and no lifecycle should not have to invent a
+  two-valued enum.
+- `Some(v)` — the **state** form. The row is retired when the field equals `v`,
+  and the field is the record's `@lifecycle` field. One field then carries the
+  fact once instead of twice, and `@allowedStates([Deactivated])` on the way-back
+  command is enough to make a generated menu offer it there and nowhere else —
+  because retirement is finally expressible in the vocabulary that stance is
+  already written in.
+
+The narrowing itself is not described here. This spec carries what the field
+*means*; who still sees a retired row is one deployment-wide rule
+(`OwnerScope.elevatedGroups`), resolved where the query is answered.
+*/
+type retiredSpec = {
+  field: string,
+  label: string,
+  showWhenFalse: bool,
+  /**
+  The states that withdraw the row, or `None` for the boolean form.
+
+  A **set**, because a lifecycle may end in more than one way — a product is
+  withdrawn `Archived` or `Discontinued`, by different routes and with different
+  ways back — and one field carries all of them. Retired iff the field's value is
+  in the set; a single-element set is the ordinary case rather than a special one.
+
+  The `option` is the **form discriminator** and is load-bearing. `None` is the
+  boolean form, where the row is retired when the field is `true`. Flattened to a
+  bare array, `[]` would mean both "boolean form" and "state form naming no
+  states", and every consumer's boolean-form handling — the column suppression
+  most visibly — would stop firing on a value that looks merely empty.
+  */
+  values: option<array<string>>,
+}
+
 type stateAnnotationSpec = {
   ids: array<string>,
   compositeIds: array<string>,
@@ -64,13 +112,16 @@ type stateAnnotationSpec = {
   */
   metric: array<(string, metricSpec)>,
   /**
-  Field annotated `@status` on the state record (PPX-emitted). `Some(name)`
-  when one such annotation exists; the PPX errors on duplicate `@status`
-  annotations within the same record. Codegen consumes this to populate
-  `queryableDef.statusField` (with a fallback to a field literally named
-  `"status"` when this annotation is absent).
+  Field annotated `@lifecycle` on the state record (PPX-emitted) — the enum a
+  command's `@allowedStates` is written in terms of, a board draws its columns
+  from and a state diagram renders. `Some(name)` when one such annotation
+  exists; the PPX errors on duplicate `@lifecycle` annotations within the same
+  record. Codegen consumes this to populate `queryableDef.lifecycleField`, and
+  falls back to a field literally named `"lifecycle"` whose shape is an enum
+  when this annotation is absent — so a record whose field can honestly be
+  called `lifecycle` declares one without ceremony.
   */
-  status: option<string>,
+  lifecycle: option<string>,
   /**
   Field annotated `@groupBy` on the state record (PPX-emitted). `Some(name)`
   when one such annotation exists; the PPX errors on duplicate `@groupBy`
@@ -96,6 +147,22 @@ type stateAnnotationSpec = {
   control is offered (`true`) or hidden (`false`) for the view.
   */
   live: option<bool>,
+  /**
+  Field annotated `@retired` on the state record (PPX-emitted). `Some(spec)` when
+  one such annotation exists; the PPX errors on duplicates and on a non-boolean
+  field. `SuryToJsonSchema.deriveObjectSchema` emits `x-reventless-retired:
+  {label?, showWhenFalse}` on the named field.
+
+  `option<retiredSpec>` rather than an array: at most one per record. Two
+  retirement flags are not a stricter rule but an unanswered one — the read
+  predicate would have to guess whether they conjoin or disjoin, and the query
+  layer narrows on a single field.
+
+  Both the boolean and the state form ride this one key. `x-reventless-retired`
+  carries `value` only in the state form, on the same omit-rather-than-write-empty
+  rule `label` already follows.
+  */
+  retired: option<retiredSpec>,
 }
 
 /** Sury metadata ID used to attach a `stateAnnotationSpec` to a state schema. */

package/src/types/OwnerScope.res

@@ -225,3 +225,108 @@ let scopeOf = (decision: decision): option<(string, string)> =>
   | ScopeTo(field, required) => Some((field, required))
   | Unscoped | RefuseOwned => None
   }
+
+/**
+What `@retired` does to one read of one view.
+
+Deliberately in this module rather than beside the annotation. Owner scoping and
+retirement narrowing are two rules over the same question — which rows does this
+caller get — and they resolve the caller with the same `resolve`, against the
+same deployment-wide `elevatedGroups`. Written apart, they could disagree about
+who an operator is, and the disagreement would be invisible until a caller
+elevated for one rule turned out to be scoped by the other.
+
+`ExcludeRetired` carries the whole predicate — the field and, for the state form
+of `@retired`, every state that retires the row. `values: None` is the boolean
+form, where the excluded value is always `true`; naming it there would be a
+parameter that can only hold one thing, and a parameter a call site can pass
+wrongly.
+
+Both halves travel together for the reason the pair exists at all: a field
+without its values is half a comparison, and an adapter left to fetch the other
+half from the schema is an adapter that can disagree with the one next to it
+about which rows a caller may see.
+*/
+type retiredScope = {
+  field: string,
+  values: option<array<string>>,
+}
+
+type retiredDecision =
+  | RetiredVisible
+  | ExcludeRetired(retiredScope)
+
+/**
+Combine a view's declared retirement flag with the caller behind the request.
+
+`~asked` is the caller's `includeRetired` request, honoured only where the
+caller was going to see those rows anyway. Reading it before classifying would
+make the argument the decision rather than a request.
+
+`Unidentified` excludes rather than refuses, which is where this parts company
+with `decide`. An owner-scoped read of an unidentified caller has no value to
+match, so scoping it would be indistinguishable from an empty view and a refusal
+says more. Retirement has no such value — the predicate is the same for every
+non-exempt caller — so the fail-closed action is simply the narrow read.
+*/
+let decideRetired = (
+  identity: Identity.t,
+  ~retiredField: option<string>,
+  ~retiredValues: option<array<string>>=?,
+  ~asked: bool=false,
+  ~elevated: array<string>=elevatedGroups(),
+): retiredDecision =>
+  switch retiredField {
+  | None => RetiredVisible
+  | Some(field) =>
+    let scope = {field, values: retiredValues}
+    switch resolve(identity, ~elevated) {
+    | System | Elevated(_) => asked ? RetiredVisible : ExcludeRetired(scope)
+    | Owned(_) | Unidentified(_) => ExcludeRetired(scope)
+    }
+  }
+
+/**
+The field a read excludes on, or `None` when it excludes nothing.
+
+Note that an exempt caller who did not ask still gets `Some`: retired rows are
+withheld from everyone by default, and elevation buys the ability to ask for
+them rather than a standing exemption. An archive that is always underfoot is
+not an archive.
+*/
+let retiredScopeOf = (decision: retiredDecision): option<retiredScope> =>
+  switch decision {
+  | ExcludeRetired(scope) => Some(scope)
+  | RetiredVisible => None
+  }
+
+/**
+Whether a row's value in the retirement field is a retiring one.
+
+The single place the two forms differ, so every reader asks one question rather
+than branching on the form itself. The state form is a membership test: a
+lifecycle may be withdrawn by several states, and they exclude identically —
+what differs between them is the way back, which commands express and this does
+not need to know.
+
+`None` — the field absent from the row — answers false in both, which is the
+mirror image of the owner rule and lands the opposite way for the same reason: an
+owner-scoped read excludes a row that states no owner, because such a row belongs
+to nobody in particular, while a retirement read KEEPS a row that states no flag,
+because absent means not retired. That is what a row written before the
+annotation existed is, and excluding those would empty the view the day the
+annotation lands.
+
+A state form naming no states excludes nothing, which is the same reading one
+step further: no state has been declared to withdraw a row, so no row is.
+*/
+let isRetiredValue = (scope: retiredScope, cell: option<JSON.t>): bool =>
+  switch (scope.values, cell) {
+  | (_, None) => false
+  | (None, Some(v)) => v->JSON.Decode.bool->Option.getOr(false)
+  | (Some(states), Some(v)) =>
+    switch v->JSON.Decode.string {
+    | None => false
+    | Some(s) => states->Array.includes(s)
+    }
+  }

package/src/types/OwnerScope.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Identity$Reventless from "./Identity.res.mjs";
@@ -155,6 +156,70 @@ function scopeOf(decision) {
   }
 }
 
+function decideRetired(identity, retiredField, retiredValues, askedOpt, elevatedOpt) {
+  let asked = askedOpt !== undefined ? askedOpt : false;
+  let elevated = elevatedOpt !== undefined ? elevatedOpt : elevatedGroups();
+  if (retiredField === undefined) {
+    return "RetiredVisible";
+  }
+  let scope = {
+    field: retiredField,
+    values: retiredValues
+  };
+  let match = resolve(identity, elevated);
+  if (typeof match !== "object") {
+    if (asked) {
+      return "RetiredVisible";
+    } else {
+      return {
+        TAG: "ExcludeRetired",
+        _0: scope
+      };
+    }
+  }
+  switch (match.TAG) {
+    case "Elevated" :
+      if (asked) {
+        return "RetiredVisible";
+      } else {
+        return {
+          TAG: "ExcludeRetired",
+          _0: scope
+        };
+      }
+    case "Owned" :
+    case "Unidentified" :
+      return {
+        TAG: "ExcludeRetired",
+        _0: scope
+      };
+  }
+}
+
+function retiredScopeOf(decision) {
+  if (typeof decision !== "object") {
+    return;
+  } else {
+    return decision._0;
+  }
+}
+
+function isRetiredValue(scope, cell) {
+  let match = scope.values;
+  if (cell === undefined) {
+    return false;
+  }
+  if (match === undefined) {
+    return Stdlib_Option.getOr(Stdlib_JSON.Decode.bool(cell), false);
+  }
+  let s = Stdlib_JSON.Decode.string(cell);
+  if (s !== undefined) {
+    return match.includes(s);
+  } else {
+    return false;
+  }
+}
+
 export {
   isJsString,
   systemProviders,
@@ -169,5 +234,8 @@ export {
   isExempt,
   decide,
   scopeOf,
+  decideRetired,
+  retiredScopeOf,
+  isRetiredValue,
 }
 /* Identity-Reventless Not a pure module */