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

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 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.117 (2026-08-18)
+
+### Bug Fixes
+
+* **api:** declare the reference door in the SDL every backend is built from ([5c1857e](https://github.com/ReventlessDev/reventless-core/commit/5c1857ea90ff40305a1c44a9e57043528e6a93aa))
+### Features
+
+* **core:** let a reference name a retired row, and let an elevated caller open one ([9e2623a](https://github.com/ReventlessDev/reventless-core/commit/9e2623a4b22487561607fcc0ca19d51726069ee4))
+
+
+# 3.0.0-alpha.116 (2026-08-16)
+
+### Features
+
+* **ppx:** declare a command's lifecycle edge once, as [@transition](https://github.com/transition) ([dd35130](https://github.com/ReventlessDev/reventless-core/commit/dd3513014f14b71879ee21263c6755d3c3d95096))
+
+
 # 3.0.0-alpha.115 (2026-08-16)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.115",
+  "version": "3.0.0-alpha.117",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -21,7 +21,7 @@
     "sury": "11.0.0-alpha.4",
     "sury-ppx": "11.0.0-alpha.2",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.7"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.8"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/schema/platform-api.graphql

@@ -178,6 +178,13 @@ enum Platform_PluginKind {
   PlatformInfrastructure
 }
 
+type Platform_PluginRef {
+  id: ID!
+  label: String!
+  retired: Boolean!
+  retiredState: String
+}
+
 enum Platform_PluginStatus {
   Connected
   Disconnected
@@ -215,6 +222,7 @@ type Platform_ReadSideDef {
   lifecycleField: String
   linkedWriteSide: [String!]!
   name: String!
+  namedWhenRetired: Boolean!
   ownerField: String
   queryField: String!
   requiredAccess: [String!]
@@ -290,10 +298,11 @@ type PluginStatusChangeEvent {
 
 type Query {
   Platform_ComponentDefinitions: [Platform_ComponentDefinitionEntry!]!
-  Platform_Plugin(id: ID!): Platform_Plugin
+  Platform_Plugin(id: ID!, includeRetired: Boolean): Platform_Plugin
   Platform_PluginStructures: [Platform_PluginStructureEntry!]!
   Platform_Plugins(after: String, before: String, filter: Platform_PluginFilter, first: Int, includeRetired: Boolean, last: Int): Platform_PluginConnection!
-  Platform_PluginsByIds(ids: [String!]!): [Platform_Plugin!]!
+  Platform_PluginsByIds(ids: [String!]!, includeRetired: Boolean): [Platform_Plugin!]!
+  Platform_PluginsRefs(ids: [ID!]!): [Platform_PluginRef!]!
   Platform_UIFragments: [Platform_UIFragmentEntry!]!
 }
 

package/src/components/DcbScopeInference.res

@@ -8,7 +8,7 @@ each slice (variant names + `*Id`-shaped fields), never an `S.t` schema and neve
 a tag-metadata flag. That is precisely what we are replacing — so both the runtime
 (building shapes from `S.t` schemas, via `DcbTag.sliceShapeFromSchemas`) and the
 VS Code tooling (building shapes from parsed `.res` source) can feed the same
-`infer`. See `docs/plans/dcb-tag-scope-inference.md` § "Phase 1 design".
+`infer`. See `docs/plans/done/dcb-tag-scope-inference.md` § "Phase 1 design".
 
 The three rules (over the representation):
 

package/src/components/InboundTranslationSlice.res

@@ -53,7 +53,7 @@ module type Spec = {
 
   /** Optional display name of the foreign system this anti-corruption slice receives
       from (e.g. `"SupplierFeed"`). Drives the **external box** drawn outside the plugin
-      in the Event Graph / Context Map (see docs/plans/translation-external-boxes.md).
+      in the Event Graph / Context Map.
       Auto-injected by `@@reventless.spec` defaulting to `None` — set it to name the box. */
   let externalSystem: option<string>
 

package/src/components/OutboundTranslationSlice.res

@@ -103,7 +103,7 @@ module type Spec = {
 
   /** Optional display name of the foreign system this anti-corruption slice publishes
       to (e.g. `"EmailService"`). Drives the **external box** drawn outside the plugin
-      in the Event Graph / Context Map (see docs/plans/translation-external-boxes.md).
+      in the Event Graph / Context Map.
       Auto-injected by `@@reventless.spec` defaulting to `None` — set it to name the box. */
   let externalSystem: option<string>
 }

package/src/components/Plugin.res

@@ -180,11 +180,12 @@ type commandDef = {
   /**
   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
-  back to its name-stem heuristic. `Some("Shipped")` lets the resolver move a
-  row by a declared transition instead of a guess. js_nullable for JSON safety,
-  same as `allowedStates`.
+  target of the `@transition(([Placed]) => Shipped)` command-variant annotation.
+  `Some("Shipped")` lets a resolver move a row by a declared transition instead
+  of a guess. `None` means no target was declared — and note that this is two
+  different statements depending on `allowedStates`: with a from-set present it
+  is the command declaring it does not move the row, and with none it is simply
+  an unannotated command. js_nullable for JSON safety, same as `allowedStates`.
   */
   targetState: @s.matches(stringOptionSchema) option<string>,
   /**
@@ -318,12 +319,32 @@ type queryableDef = {
   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
+  The state form is also what lets a command's `@transition` answer applicability
+  when retired, with no annotation beyond the one — retirement expressed in the
   vocabulary a command's stance is already written in.
   */
   retiredValues: @s.matches(stringArrayOptionSchema) option<array<string>>,
   /**
+  Whether this view publishes a **reference door**: the by-ids read that names a
+  retired row for any caller holding a pointer to it, projected to the row's id,
+  its `labelField` and the value of `retiredField`. Declared with
+  `@namedWhenRetired` on the state record.
+
+  Published so a client knows the door exists without probing for it — a query
+  against a field the schema does not have is a validation error, not an empty
+  answer, so "ask and see" is not a usable fallback here.
+
+  Nullable rather than a bare required bool, which is the rule this schema's own
+  tripwire enforces: a definition stored before the field existed would otherwise
+  decode with an invented value and a runtime warning. Absent and `false` mean the
+  same thing to every reader — the archive stays shut — but only one of them is
+  something the platform actually said.
+
+  It is never `true` without `retiredField`: the PPX refuses the annotation on a
+  record with no retirement.
+  */
+  namedWhenRetired: @s.matches(boolOptionSchema) option<bool>,
+  /**
   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

package/src/components/Plugin.res.mjs

@@ -122,6 +122,7 @@ let queryableDefSchema = S.schema(s => ({
   ownerField: s.m(stringOptionSchema),
   retiredField: s.m(stringOptionSchema),
   retiredValues: s.m(stringArrayOptionSchema),
+  namedWhenRetired: s.m(boolOptionSchema),
   visibility: s.m(stringOptionSchema),
   chapter: s.m(stringOptionSchema),
   singleQueryField: s.m(stringOptionSchema),

package/src/components/Snapshot.res

@@ -1,5 +1,5 @@
 // Per-aggregate persisted-snapshot configuration
-// (docs/plans/aggregate-snapshotting.md).
+// (docs/plans/done/aggregate-snapshotting.md).
 //
 // Snapshotting is opt-in and lives on the Behavior module (where `state` is
 // defined): `Behavior.T.snapshot = None` (the default, auto-injected by

package/src/components/StateAnnotations.res

@@ -52,8 +52,9 @@ otherwise see the same negative marker on every record they can read.
   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 —
+  fact once instead of twice, and `@transition(([Deactivated]) => Active)` 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.
 
@@ -80,6 +81,27 @@ type retiredSpec = {
   most visibly — would stop firing on a value that looks merely empty.
   */
   values: option<array<string>>,
+  /**
+  Whether a reference to a retired row of this record still resolves — the
+  `@namedWhenRetired` opt-in on the `@schema type state` declaration.
+
+  Retirement withholds a row from every door at once, which is the right answer
+  to "what may this caller browse" and an unasked answer to "what is the row this
+  caller is already holding a reference to called". An order names a product it
+  bought; archiving the product should not unname it on the order.
+
+  `true` opens exactly one door: a retired row answers a by-ids reference read
+  with its id, its label field and the value of `field` — and nothing else, for
+  any caller. It does not widen the list, the single-entity read, the index reads
+  or the live frame, and it does not touch the owner rule: a retired row that is
+  owner-scoped still resolves for its owner alone.
+
+  Inside `retiredSpec` rather than beside it, because it is a rule about withheld
+  rows and there are none without a retirement — the PPX errors on the annotation
+  when the record declares no `@retired`, so the nesting states a guarantee rather
+  than a convention.
+  */
+  namedWhenRetired: bool,
 }
 
 type stateAnnotationSpec = {
@@ -113,7 +135,7 @@ type stateAnnotationSpec = {
   metric: array<(string, metricSpec)>,
   /**
   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
+  command's `@transition` 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

package/src/generator/Discovery.res

@@ -29,7 +29,7 @@ let folderToComponentType = ComponentKind.folderToKind
 // `None`. Uses the single-source `ComponentKind.isKindFolder`, so a chapter read
 // here (build time, disk) agrees with the authoring tool's identical heuristic and
 // with a chapter reflected off the deployed plugin structure. See
-// docs/plans/deployed-chapter-grouping.md.
+// docs/plans/done/deployed-chapter-grouping.md.
 let chapterOf = (relPath: string): option<string> => {
   let segments = relPath->String.split("/")
   // Need at least one directory segment before the filename.

package/src/types/Behavior.res

@@ -72,7 +72,7 @@ module type T = {
   */
   let decide: (state, Spec.command) => result<array<Spec.event>, Spec.error>
 
-  /** Persisted-snapshot configuration (docs/plans/aggregate-snapshotting.md).
+  /** Persisted-snapshot configuration (docs/plans/done/aggregate-snapshotting.md).
       `None` — the default, auto-injected by `@@reventless.behavior` — keeps
       full replay; `Some({interval, stateSchema})` writes a keep-one snapshot
       every `interval` events and seeds cold replays from the latest one.

package/src/types/Message.res

@@ -162,7 +162,7 @@ type commandJson = {
 // (clones via a JSON round-trip; never re-encodes through the schema), is idempotent on
 // valid data, and falls back to the ORIGINAL error when the fill doesn't resolve the
 // failure — so genuine corruption still surfaces.
-// See docs/plans/platform-infrastructure-in-plugin-list.md (durable fix option 2).
+// See docs/plans/done/platform-infrastructure-in-plugin-list.md (durable fix option 2).
 //
 // The scalar arm is the odd one out and is deliberately noisy. Every other fill is
 // *derived* — the schema states what an absent value means, and the fill supplies exactly