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

package/CHANGELOG.md

@@ -3,6 +3,16 @@
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.116",
+  "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/Plugin.res

@@ -325,6 +325,26 @@ type queryableDef = {
   */
   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/StateAnnotations.res

@@ -81,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 = {