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

package/src/components/Plugin.res

@@ -105,13 +105,12 @@ type apiTarget = Domain | Platform
 // Sury's nullableAsOption creates T | undefined | null which fails jsonableValidation
 // inside union variant payloads. js_nullable creates T | null (no undefined) which is
 // JSON-safe and passes jsonableValidation in all contexts.
-@module("sury/src/Sury.res.mjs") external _jsNullable: (S.t<'a>, unit) => S.t<option<'a>> = "js_nullable"
 let apiSchemaFragmentOffloadSchema = Offload.optionSchema(~store="pluginApiFragments", apiSchemaFragmentSchema)
-let dcbEventLogOptionSchema = _jsNullable(dcbEventLogDefinitionSchema, ())
+let dcbEventLogOptionSchema = dcbEventLogDefinitionSchema->S.nullAsOption
 // js_nullable creates T | null which passes sury's jsonableValidation inside union variant payloads.
-let stringOptionSchema = _jsNullable(S.string, ())
-let stringArrayOptionSchema = _jsNullable(S.array(S.string), ())
-let boolOptionSchema = _jsNullable(S.bool, ())
+let stringOptionSchema = S.string->S.nullAsOption
+let stringArrayOptionSchema = S.array(S.string)->S.nullAsOption
+let boolOptionSchema = S.bool->S.nullAsOption
 
 // ── UI fragment manifest types ────────────────────────────────────────────────
 
@@ -147,7 +146,7 @@ type uiFragmentManifest = {
   pages: array<pageManifestEntry>,
 }
 
-let uiFragmentManifestOptionSchema = _jsNullable(uiFragmentManifestSchema, ())
+let uiFragmentManifestOptionSchema = uiFragmentManifestSchema->S.nullAsOption
 
 // ── Plugin structure types (component metadata for Auto UI and event graph) ──
 
@@ -325,6 +324,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
@@ -546,7 +565,7 @@ type extensionPointDef = {
 
 // js_nullable creates `array | null` (not `| undefined`), which passes sury's
 // jsonableValidation inside the pluginStructure union variant payload.
-let extensionPointDefArrayOptionSchema = _jsNullable(S.array(extensionPointDefSchema), ())
+let extensionPointDefArrayOptionSchema = S.array(extensionPointDefSchema)->S.nullAsOption
 
 /**
 One field's store requirement, with its provenance.
@@ -584,10 +603,8 @@ type requiredStoreDeclaration = {
   annotation: @s.matches(stringOptionSchema) option<string>,
 }
 
-let requiredStoreDeclarationArrayOptionSchema = _jsNullable(
-  S.array(requiredStoreDeclarationSchema),
-  (),
-)
+let requiredStoreDeclarationArrayOptionSchema =
+  S.array(requiredStoreDeclarationSchema)->S.nullAsOption
 
 /**
 Adding a field here? It has to be a shape a stale event can be healed into.

package/src/components/Plugin.res.mjs

@@ -1,107 +1,110 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
 import * as Offload$Reventless from "../semantic/Offload.res.mjs";
-import * as SuryResMjs from "sury/src/Sury.res.mjs";
 
-let pluginKindSchema = S.union([
-  S.literal("Domain"),
-  S.literal("PlatformInfrastructure"),
-  S.literal("Commercial"),
-  S.literal("Marketplace")
+let nameSchema = Sury.string;
+
+let versionSchema = Sury.string;
+
+let pluginKindSchema = Sury.union([
+  Sury.literal("Domain"),
+  Sury.literal("PlatformInfrastructure"),
+  Sury.literal("Commercial"),
+  Sury.literal("Marketplace")
 ]);
 
-let extensionPointDefinitionSchema = S.schema(s => ({
-  name: s.m(S.string),
-  commandTopic: s.m(S.string),
-  eventTopic: s.m(S.string)
+let extensionPointDefinitionSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  commandTopic: s.m(Sury.string),
+  eventTopic: s.m(Sury.string)
 }));
 
-let extensionDefinitionSchema = S.schema(s => ({
-  name: s.m(S.string),
-  extensionPointName: s.m(S.string),
-  dcbSources: s.m(S.array(S.string))
+let extensionDefinitionSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  extensionPointName: s.m(Sury.string),
+  dcbSources: s.m(Sury.array(Sury.string))
 }));
 
-let dcbEventLogDefinitionSchema = S.schema(s => ({
-  name: s.m(S.string),
-  eventTopicArn: s.m(S.string)
+let dcbEventLogDefinitionSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  eventTopicArn: s.m(Sury.string)
 }));
 
-let extensionProtocolSchema = S.schema(s => ({
-  extensionPointName: s.m(S.string),
-  commandVersion: s.m(S.string),
-  eventVersion: s.m(S.string)
+let extensionProtocolSchema = Sury.$schema(s => ({
+  extensionPointName: s.m(Sury.string),
+  commandVersion: s.m(Sury.string),
+  eventVersion: s.m(Sury.string)
 }));
 
-let apiSchemaFragmentSchema = S.schema(s => ({
-  encoded: s.m(S.string),
-  protocol: s.m(S.string)
+let apiSchemaFragmentSchema = Sury.$schema(s => ({
+  encoded: s.m(Sury.string),
+  protocol: s.m(Sury.string)
 }));
 
-let apiTargetSchema = S.union([
-  S.literal("Domain"),
-  S.literal("Platform")
+let apiTargetSchema = Sury.union([
+  Sury.literal("Domain"),
+  Sury.literal("Platform")
 ]);
 
 let apiSchemaFragmentOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginApiFragments", undefined, apiSchemaFragmentSchema);
 
-let dcbEventLogOptionSchema = SuryResMjs.js_nullable(dcbEventLogDefinitionSchema);
+let dcbEventLogOptionSchema = Sury.$nullAsOption(dcbEventLogDefinitionSchema);
 
-let stringOptionSchema = SuryResMjs.js_nullable(S.string);
+let stringOptionSchema = Sury.$nullAsOption(Sury.string);
 
-let stringArrayOptionSchema = SuryResMjs.js_nullable(S.array(S.string));
+let stringArrayOptionSchema = Sury.$nullAsOption(Sury.array(Sury.string));
 
-let boolOptionSchema = SuryResMjs.js_nullable(S.bool);
+let boolOptionSchema = Sury.$nullAsOption(Sury.bool);
 
-let panelManifestEntrySchema = S.schema(s => ({
-  fragmentId: s.m(S.string),
-  title: s.m(S.string),
-  description: s.m(S.string),
-  positions: s.m(S.array(S.string)),
+let panelManifestEntrySchema = Sury.$schema(s => ({
+  fragmentId: s.m(Sury.string),
+  title: s.m(Sury.string),
+  description: s.m(Sury.string),
+  positions: s.m(Sury.array(Sury.string)),
   requiredAccess: s.m(stringOptionSchema)
 }));
 
-let menuEntrySchema = S.schema(s => ({
-  label: s.m(S.string),
+let menuEntrySchema = Sury.$schema(s => ({
+  label: s.m(Sury.string),
   icon: s.m(stringOptionSchema),
   group: s.m(stringOptionSchema),
-  sortOrder: s.m(S.int)
+  sortOrder: s.m(Sury.int)
 }));
 
-let pageManifestEntrySchema = S.schema(s => ({
-  fragmentId: s.m(S.string),
-  title: s.m(S.string),
+let pageManifestEntrySchema = Sury.$schema(s => ({
+  fragmentId: s.m(Sury.string),
+  title: s.m(Sury.string),
   menuEntry: s.m(menuEntrySchema),
   requiredAccess: s.m(stringOptionSchema)
 }));
 
-let uiFragmentManifestSchema = S.schema(s => ({
-  remoteEntryUrl: s.m(S.string),
-  panels: s.m(S.array(panelManifestEntrySchema)),
-  pages: s.m(S.array(pageManifestEntrySchema))
+let uiFragmentManifestSchema = Sury.$schema(s => ({
+  remoteEntryUrl: s.m(Sury.string),
+  panels: s.m(Sury.array(panelManifestEntrySchema)),
+  pages: s.m(Sury.array(pageManifestEntrySchema))
 }));
 
-let uiFragmentManifestOptionSchema = SuryResMjs.js_nullable(uiFragmentManifestSchema);
+let uiFragmentManifestOptionSchema = Sury.$nullAsOption(uiFragmentManifestSchema);
 
-let commandLevelSchema = S.union([
-  S.literal("Collection"),
-  S.literal("Instance")
+let commandLevelSchema = Sury.union([
+  Sury.literal("Collection"),
+  Sury.literal("Instance")
 ]);
 
-let fieldReferenceSchema = S.schema(s => ({
-  fieldName: s.m(S.string),
-  entity: s.m(S.string),
+let fieldReferenceSchema = Sury.$schema(s => ({
+  fieldName: s.m(Sury.string),
+  entity: s.m(Sury.string),
   plugin: s.m(stringOptionSchema)
 }));
 
-let commandDefSchema = S.schema(s => ({
-  name: s.m(S.string),
-  schema: s.m(S.string),
+let commandDefSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  schema: s.m(Sury.string),
   level: s.m(commandLevelSchema),
   aggregateIdField: s.m(stringOptionSchema),
-  mutationField: s.m(S.string),
-  references: s.m(S.array(fieldReferenceSchema)),
+  mutationField: s.m(Sury.string),
+  references: s.m(Sury.array(fieldReferenceSchema)),
   allowedStates: s.m(stringArrayOptionSchema),
   targetState: s.m(stringOptionSchema),
   apiExposed: s.m(boolOptionSchema),
@@ -109,19 +112,20 @@ let commandDefSchema = S.schema(s => ({
   ownerField: s.m(stringOptionSchema)
 }));
 
-let queryableDefSchema = S.schema(s => ({
-  name: s.m(S.string),
-  queryField: s.m(S.string),
-  schema: s.m(S.string),
-  consumedEventTypes: s.m(S.array(S.string)),
-  linkedWriteSide: s.m(S.array(S.string)),
-  labelField: s.m(S.string),
-  searchableFields: s.m(S.array(S.string)),
+let queryableDefSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  queryField: s.m(Sury.string),
+  schema: s.m(Sury.string),
+  consumedEventTypes: s.m(Sury.array(Sury.string)),
+  linkedWriteSide: s.m(Sury.array(Sury.string)),
+  labelField: s.m(Sury.string),
+  searchableFields: s.m(Sury.array(Sury.string)),
   labelFieldSource: s.m(stringOptionSchema),
   lifecycleField: s.m(stringOptionSchema),
   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),
@@ -130,89 +134,89 @@ let queryableDefSchema = S.schema(s => ({
   requiredAccess: s.m(stringArrayOptionSchema)
 }));
 
-let eventDefSchema = S.schema(s => ({
-  name: s.m(S.string),
-  schema: s.m(S.string),
-  references: s.m(S.array(fieldReferenceSchema))
+let eventDefSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  schema: s.m(Sury.string),
+  references: s.m(Sury.array(fieldReferenceSchema))
 }));
 
-let errorDefSchema = S.schema(s => ({
-  name: s.m(S.string),
-  schema: s.m(S.string),
-  references: s.m(S.array(fieldReferenceSchema))
+let errorDefSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  schema: s.m(Sury.string),
+  references: s.m(Sury.array(fieldReferenceSchema))
 }));
 
-let writableDefSchema = S.schema(s => ({
-  name: s.m(S.string),
-  commands: s.m(S.array(commandDefSchema)),
-  producedEventTypes: s.m(S.array(S.string)),
-  consumedEventTypes: s.m(S.array(S.string)),
-  linkedViews: s.m(S.array(S.string)),
+let writableDefSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  commands: s.m(Sury.array(commandDefSchema)),
+  producedEventTypes: s.m(Sury.array(Sury.string)),
+  consumedEventTypes: s.m(Sury.array(Sury.string)),
+  linkedViews: s.m(Sury.array(Sury.string)),
   consistencyRead: s.m(stringOptionSchema),
-  events: s.m(S.array(eventDefSchema)),
-  errors: s.m(S.array(errorDefSchema)),
+  events: s.m(Sury.array(eventDefSchema)),
+  errors: s.m(Sury.array(errorDefSchema)),
   chapter: s.m(stringOptionSchema)
 }));
 
-let automationSliceDefSchema = S.schema(s => ({
-  name: s.m(S.string),
-  consumedEventTypes: s.m(S.array(S.string)),
-  producedCommandTypes: s.m(S.array(S.string)),
-  targetName: s.m(S.string),
+let automationSliceDefSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  consumedEventTypes: s.m(Sury.array(Sury.string)),
+  producedCommandTypes: s.m(Sury.array(Sury.string)),
+  targetName: s.m(Sury.string),
   chapter: s.m(stringOptionSchema)
 }));
 
-let outboundTranslationSliceDefSchema = S.schema(s => ({
-  name: s.m(S.string),
-  consumedEventTypes: s.m(S.array(S.string)),
-  inboundCommandTypes: s.m(S.array(S.string)),
+let outboundTranslationSliceDefSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  consumedEventTypes: s.m(Sury.array(Sury.string)),
+  inboundCommandTypes: s.m(Sury.array(Sury.string)),
   targetName: s.m(stringOptionSchema),
   externalSystem: s.m(stringOptionSchema),
   chapter: s.m(stringOptionSchema)
 }));
 
-let inboundTranslationSliceDefSchema = S.schema(s => ({
-  name: s.m(S.string),
-  commandTypes: s.m(S.array(S.string)),
-  targetName: s.m(S.string),
+let inboundTranslationSliceDefSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  commandTypes: s.m(Sury.array(Sury.string)),
+  targetName: s.m(Sury.string),
   externalSystem: s.m(stringOptionSchema),
   chapter: s.m(stringOptionSchema)
 }));
 
-let extensionDefSchema = S.schema(s => ({
-  name: s.m(S.string),
-  delegateNames: s.m(S.array(S.string)),
-  eventTypes: s.m(S.array(S.string)),
-  commandTypes: s.m(S.array(S.string))
+let extensionDefSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  delegateNames: s.m(Sury.array(Sury.string)),
+  eventTypes: s.m(Sury.array(Sury.string)),
+  commandTypes: s.m(Sury.array(Sury.string))
 }));
 
-let extensionPointDefSchema = S.schema(s => ({
-  name: s.m(S.string),
-  delegateNames: s.m(S.array(S.string)),
-  sourceEventTypes: s.m(S.array(S.string)),
+let extensionPointDefSchema = Sury.$schema(s => ({
+  name: s.m(Sury.string),
+  delegateNames: s.m(Sury.array(Sury.string)),
+  sourceEventTypes: s.m(Sury.array(Sury.string)),
   commandTypes: s.m(stringArrayOptionSchema)
 }));
 
-let extensionPointDefArrayOptionSchema = SuryResMjs.js_nullable(S.array(extensionPointDefSchema));
+let extensionPointDefArrayOptionSchema = Sury.$nullAsOption(Sury.array(extensionPointDefSchema));
 
-let requiredStoreDeclarationSchema = S.schema(s => ({
-  store: s.m(S.string),
-  component: s.m(S.string),
-  field: s.m(S.string),
+let requiredStoreDeclarationSchema = Sury.$schema(s => ({
+  store: s.m(Sury.string),
+  component: s.m(Sury.string),
+  field: s.m(Sury.string),
   annotation: s.m(stringOptionSchema)
 }));
 
-let requiredStoreDeclarationArrayOptionSchema = SuryResMjs.js_nullable(S.array(requiredStoreDeclarationSchema));
-
-let pluginStructureSchema = S.schema(s => ({
-  readModels: s.m(S.array(queryableDefSchema)),
-  stateViewSlices: s.m(S.array(queryableDefSchema)),
-  stateChangeSlices: s.m(S.array(writableDefSchema)),
-  aggregates: s.m(S.array(writableDefSchema)),
-  automationSlices: s.m(S.array(automationSliceDefSchema)),
-  outboundTranslationSlices: s.m(S.array(outboundTranslationSliceDefSchema)),
-  inboundTranslationSlices: s.m(S.array(inboundTranslationSliceDefSchema)),
-  extensions: s.m(S.array(extensionDefSchema)),
+let requiredStoreDeclarationArrayOptionSchema = Sury.$nullAsOption(Sury.array(requiredStoreDeclarationSchema));
+
+let pluginStructureSchema = Sury.$schema(s => ({
+  readModels: s.m(Sury.array(queryableDefSchema)),
+  stateViewSlices: s.m(Sury.array(queryableDefSchema)),
+  stateChangeSlices: s.m(Sury.array(writableDefSchema)),
+  aggregates: s.m(Sury.array(writableDefSchema)),
+  automationSlices: s.m(Sury.array(automationSliceDefSchema)),
+  outboundTranslationSlices: s.m(Sury.array(outboundTranslationSliceDefSchema)),
+  inboundTranslationSlices: s.m(Sury.array(inboundTranslationSliceDefSchema)),
+  extensions: s.m(Sury.array(extensionDefSchema)),
   extensionPoints: s.m(extensionPointDefArrayOptionSchema),
   requiredStores: s.m(stringArrayOptionSchema),
   requiredStoreDeclarations: s.m(requiredStoreDeclarationArrayOptionSchema)
@@ -220,14 +224,14 @@ let pluginStructureSchema = S.schema(s => ({
 
 let pluginStructureOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginStructures", undefined, pluginStructureSchema);
 
-let pluginDefinitionSchema = S.schema(s => ({
-  id: s.m(S.string),
-  name: s.m(S.string),
-  version: s.m(S.string),
-  extensionPoints: s.m(S.array(extensionPointDefinitionSchema)),
-  extensions: s.m(S.array(extensionDefinitionSchema)),
-  eventCollector: s.m(S.string),
-  extensionProtocols: s.m(S.array(extensionProtocolSchema)),
+let pluginDefinitionSchema = Sury.$schema(s => ({
+  id: s.m(Sury.string),
+  name: s.m(nameSchema),
+  version: s.m(versionSchema),
+  extensionPoints: s.m(Sury.array(extensionPointDefinitionSchema)),
+  extensions: s.m(Sury.array(extensionDefinitionSchema)),
+  eventCollector: s.m(Sury.string),
+  extensionProtocols: s.m(Sury.array(extensionProtocolSchema)),
   apiSchemaFragment: s.m(apiSchemaFragmentOffloadSchema),
   apiTarget: s.m(stringOptionSchema),
   structure: s.m(pluginStructureOffloadSchema),
@@ -235,10 +239,6 @@ let pluginDefinitionSchema = S.schema(s => ({
   kind: s.m(pluginKindSchema)
 }));
 
-let nameSchema = S.string;
-
-let versionSchema = S.string;
-
 export {
   nameSchema,
   versionSchema,
@@ -278,4 +278,4 @@ export {
   pluginStructureOffloadSchema,
   pluginDefinitionSchema,
 }
-/* pluginKindSchema Not a pure module */
+/* nameSchema Not a pure module */

package/src/components/Reference.res.mjs

@@ -1,12 +1,12 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as DcbTag$Reventless from "./DcbTag.res.mjs";
 import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
 
 function to_(plugin, key, entity) {
-  let base = Semantic$Reventless.mark(S.Metadata.set(S.string, DcbTag$Reventless.dcbTagId, true), Semantic$Reventless.Id.reference, {
+  let base = Semantic$Reventless.mark(Sury.$Metadata_set(Sury.string, DcbTag$Reventless.dcbTagId, true), Semantic$Reventless.Id.reference, {
     TAG: "ReferenceTo",
     _0: {
       entity: entity,
@@ -14,7 +14,7 @@ function to_(plugin, key, entity) {
     }
   });
   if (key !== undefined) {
-    return S.Metadata.set(base, DcbTag$Reventless.dcbTagKeyOverrideId, key);
+    return Sury.$Metadata_set(base, DcbTag$Reventless.dcbTagKeyOverrideId, key);
   } else {
     return base;
   }
@@ -54,7 +54,7 @@ function getFieldTarget(_schema) {
 }
 
 function toWithoutDcbTag(plugin, entity) {
-  return Semantic$Reventless.mark(S.string, Semantic$Reventless.Id.reference, {
+  return Semantic$Reventless.mark(Sury.string, Semantic$Reventless.Id.reference, {
     TAG: "ReferenceTo",
     _0: {
       entity: entity,
@@ -69,4 +69,4 @@ export {
   getFieldTarget,
   toWithoutDcbTag,
 }
-/* S Not a pure module */
+/* sury Not a pure module */

package/src/components/StateAnnotations.res

@@ -15,6 +15,8 @@ Each list contains the source field names; `indexes` carries `(fieldName,
 indexName)` pairs where `indexName` is `""` for unnamed `@index` annotations.
 `hidden` lists fields the UI should suppress from summary/list views;
 `summary` lists fields the UI should always include in summary/list views.
+`internal` lists fields that are not on the GraphQL surface at all — see the
+field's own note below; it is a different kind of claim from `hidden`.
 `drillTargets` carries `(fieldName, sliceName)` pairs naming the slice/view
 the UI should navigate to instead of expanding the field inline;
 `drillTargetKeys` carries `(fieldName, keyPath)` pairs for fields whose
@@ -81,6 +83,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 = {
@@ -91,6 +114,27 @@ type stateAnnotationSpec = {
   indexes: array<(string, string)>,
   hidden: array<string>,
   summary: array<string>,
+  /**
+  Fields annotated `@internal` — present in the record and in storage, absent
+  from the generated SDL type and from the published state schema.
+
+  A different claim from `hidden`, and the distinction is the point. `hidden`
+  says "do not show this": the field is on the API and any client may ask for
+  it. `internal` says "this is not on the API", so nothing can ask and nothing
+  needs to be told not to show it. That is why the two are separate lists rather
+  than one flag with a mode — a consumer reading `hidden` is deciding what to
+  render, and a consumer reading this is deciding what exists.
+
+  **Not a security boundary** — the same caveat `visibility` carries. It shapes
+  the generated surface; `@owner` and `@retired` remain the enforcement markers.
+  The PPX rejects `@internal` beside either of them, and beside every other
+  marker that keys a door, because a door cannot be keyed on a field the SDL
+  does not have.
+
+  Optional so a state schema annotated by a PPX that predates the marker still
+  reads: absent and empty mean the same thing to every consumer.
+  */
+  internal?: array<string>,
   drillTargets: array<(string, string)>,
   drillTargetKeys: array<(string, string)>,
   collapsed: array<string>,

package/src/components/StateAnnotations.res.mjs

@@ -1,11 +1,11 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
+import * as Sury from "sury";
 
-let stateAnnotationsId = S.Metadata.Id.make("reventless", "stateAnnotations");
+let stateAnnotationsId = Sury.$Metadata_Id_make("reventless", "stateAnnotations");
 
 function getSpec(schema) {
-  return S.Metadata.get(schema, stateAnnotationsId);
+  return Sury.$Metadata_get(schema, stateAnnotationsId);
 }
 
 export {

package/src/generator/PlatformCodegen.res

@@ -73,17 +73,16 @@ let splitKey = (key: string): option<(string, string)> =>
     key->String.slice(~start=i + 1),
   ))
 
-// The provenance comment quotes the annotation as its author wrote it — taken
-// from the manifest, which recorded it at the one place the owning plugin was
+// The provenance comment names the store as the field spells it — taken from
+// the manifest, which recorded it at the one place the owning plugin was
 // unambiguous. Inferring it here is what this replaced: the manifest carries a
 // deploy-manifest entry name and the key carries the registered name, and no
 // rule relates the two (`platform-inspector` against `PlatformInspector` is an
-// ordinary pairing), so any comparison here eventually quotes a string that is
+// ordinary pairing), so any comparison here eventually names a string that is
 // in no source file.
 //
-// A site with no recorded annotation predates the recording. It still names the
-// field, which is the comment's job; it just makes no claim about the source
-// text it cannot see.
+// A site with no recorded store predates the recording. It still names the
+// field, which is the comment's job; it just makes no claim it cannot support.
 let renderEntry = (entry: unionEntry): result<array<string>, string> =>
   switch splitKey(entry.key) {
   | None =>
@@ -94,8 +93,13 @@ let renderEntry = (entry: unionEntry): result<array<string>, string> =>
       let comments =
         entry.declaredBy->Array.map(site => {
           let site_ = `  // ${site.pluginName}: ${site.component}.${site.field}`
+          // `→ store` rather than `@storageRef("store")`: a field may name its
+          // store by annotation *or* by being named, and the manifest carries
+          // the store either way without saying which. Naming the annotation
+          // would send a reader looking for source text a derived field has not
+          // got.
           switch site.annotation {
-          | Some(annotation) => `${site_} @storageRef(${quote(annotation)})`
+          | Some(annotation) => `${site_} → ${annotation}`
           | None => site_
           }
         })
@@ -115,13 +119,12 @@ aggregate is keyed by the registered name — so a second plugin registering an
 existing name is not rejected but read as a **new version of the first**, and
 silently supersedes it in the registry.
 
-Ownership is read from the annotation as authored, which is the one signal that
-separates a duplicate from legitimate sharing: an **unqualified**
-`@storageRef("productImages")` means "a store of my own plugin", so the
-deployable that wrote it is the plugin the key names. A **qualified**
-`@storageRef("Catalog.productImages")` points at someone else's store and says
-nothing about who owns it — that is the sanctioned cross-plugin form and must not
-trip this.
+Ownership is read from the store as the field states it, which is the one signal
+that separates a duplicate from legitimate sharing: an **unqualified**
+`productImages` means "a store of my own plugin", so the deployable that stated
+it is the plugin the key names. A **qualified** `Catalog.productImages` points at
+someone else's store and says nothing about who owns it — that is the sanctioned
+cross-plugin form and must not trip this.
 
 Partial by construction: it can only see plugins that declare a store, because
 capability manifests are the only per-plugin input the generator reads. A

package/src/generator/PlatformCodegen.res.mjs

@@ -59,7 +59,7 @@ function renderEntry(entry) {
     let site_ = `  // ` + site.pluginName + `: ` + site.component + `.` + site.field;
     let annotation = site.annotation;
     if (annotation !== undefined) {
-      return site_ + ` @storageRef(` + JSON.stringify(annotation) + `)`;
+      return site_ + ` → ` + annotation;
     } else {
       return site_;
     }

package/src/generator/PlatformGenerator.res

@@ -95,7 +95,7 @@ let () = {
               )
               let manifest = try NodeFs.readFileSync(path)
               ->JSON.parseOrThrow
-              ->S.parseOrThrow(CapabilityManifest.schema) catch {
+              ->S.parseOrThrow(~to=CapabilityManifest.schema) catch {
               | _ => {
                   fail(`could not parse ${path} as a capability manifest`)
                   ({capabilities: []}: CapabilityManifest.t)