@reventlessdev/reventless-spec 3.0.0-alpha.128 → 3.0.0-alpha.130

package/src/components/Plugin.res

@@ -73,13 +73,13 @@ type apiSchemaFragment = {encoded: string, protocol: string}
 @schema
 type apiTarget = Domain | Platform
 
-// js_nullable (T | null) is the only optional that passes jsonableValidation inside
-// union variant payloads; nullableAsOption adds `undefined` and fails it.
+// Every optional below carries sury's default `option` encoding: the key is omitted,
+// never written as `null`. That is the shape the rest of the repo already uses
+// (`Message.meta`, `storedEvent.tags`), so there is one optional form on the wire and
+// nothing to annotate. The `T | null` these fields used to carry worked around a sury
+// bug — undefined failing jsonableValidation inside a union variant payload — fixed in
+// 11.0.0-alpha.11. `Offload` below is not an optional wrapper but an either-or codec.
 let apiSchemaFragmentOffloadSchema = Offload.optionSchema(~store="pluginApiFragments", apiSchemaFragmentSchema)
-let dcbEventLogOptionSchema = dcbEventLogDefinitionSchema->S.nullAsOption
-let stringOptionSchema = S.string->S.nullAsOption
-let stringArrayOptionSchema = S.array(S.string)->S.nullAsOption
-let boolOptionSchema = S.bool->S.nullAsOption
 
 // ── UI fragment manifest types ────────────────────────────────────────────────
 
@@ -89,14 +89,14 @@ type panelManifestEntry = {
   title: string,
   description: string,
   positions: array<string>,
-  requiredAccess: @s.matches(stringOptionSchema) option<string>,
+  requiredAccess: option<string>,
 }
 
 @schema
 type menuEntry = {
   label: string,
-  icon: @s.matches(stringOptionSchema) option<string>,
-  group: @s.matches(stringOptionSchema) option<string>,
+  icon: option<string>,
+  group: option<string>,
   sortOrder: int,
 }
 
@@ -105,7 +105,7 @@ type pageManifestEntry = {
   fragmentId: string,
   title: string,
   menuEntry: menuEntry,
-  requiredAccess: @s.matches(stringOptionSchema) option<string>,
+  requiredAccess: option<string>,
 }
 
 @schema
@@ -115,18 +115,44 @@ type uiFragmentManifest = {
   pages: array<pageManifestEntry>,
 }
 
-let uiFragmentManifestOptionSchema = uiFragmentManifestSchema->S.nullAsOption
+let uiFragmentManifestOptionSchema = S.option(uiFragmentManifestSchema)
 
 // ── Plugin structure types (component metadata for Auto UI and event graph) ──
 
 @schema
 type commandLevel = Collection | Instance
 
+/** One command's lifecycle edge as the component's own scenarios describe it:
+    where a scenario shows the command taking effect, where those scenarios land,
+    and whether it brings a row into existence or acts on one.
+
+    Harvested from the GWT corpus by `check:lifecycle` and committed beside the
+    plugin as `src/LifecycleModel.res`, so structure assembly reads a value rather
+    than the test tree — which is not published with a plugin package.
+
+    No `@schema`: nothing serialises this. It is read once, while the structure is
+    assembled, and what leaves is the `commandDef` fields it resolved. */
+type derivedEdge = {
+  /** The writable's `Spec.name`, which is what the structure knows it by. */
+  component: string,
+  command: string,
+  /** Absent where the corpus could not label a history — the honest answer when
+      the linked views declare no lifecycle field, and the reason the name-stem
+      guess is still there to fall back to. */
+  level?: commandLevel,
+  /** States a scenario shows the command taking effect from. Empty means the
+      corpus said nothing, NOT that the command belongs nowhere. */
+  allowedStates: array<string>,
+  /** States those scenarios land in. More than one is an edge a single
+      `targetState` cannot carry, so it is left to the declaration. */
+  targets: array<string>,
+}
+
 @schema
 type fieldReference = {
   fieldName: string,
   entity: string,
-  plugin: @s.matches(stringOptionSchema) option<string>,
+  plugin: option<string>,
 }
 
 @schema
@@ -134,23 +160,40 @@ type commandDef = {
   name: string,
   schema: string,
   level: commandLevel,
-  aggregateIdField: @s.matches(stringOptionSchema) option<string>,
+  aggregateIdField: option<string>,
   mutationField: string,
   references: array<fieldReference>,
-  /** The declared *from* set — lifecycle states this command is meaningful in.
-      `None` means always available; `Some([])` means never show. */
-  allowedStates: @s.matches(stringArrayOptionSchema) option<array<string>>,
-  /** The declared *to* state this command's handler writes. `None` with a
-      from-set present means the command does not move the row. */
-  targetState: @s.matches(stringOptionSchema) option<string>,
+  /** The *from* set — lifecycle states this command is meaningful in. `None`
+      means always available; `Some([])` means never show. */
+  allowedStates: option<array<string>>,
+  /** The *to* state this command's handler writes. `None` with a from-set present
+      means the command does not move the row. */
+  targetState: option<string>,
+  /** Where the from-set came from, ranking an inherited edge against an authored
+      one the way `queryableDef.labelFieldSource` does for its field:
+
+      - `"derived"` — the component's own scenarios.
+      - `"declared"` — its `commandTransition` switch.
+      - `"unrestricted"` — the switch declares the command legal in *every*
+        state, so there is no from-set to publish and `allowedStates` is absent.
+
+      Absent means the command names no states to come from and nothing said that
+      was deliberate — a spec that wrote no switch, or one whose command creates
+      the row. So a consumer drawing a state machine can tell an edge left
+      unconstrained on purpose from one that simply has no from-set.
+
+      It speaks for the from-set only. The two halves of an edge are reported
+      separately because they fail separately: a corpus routinely shows a command
+      taking effect without ever showing where it lands. */
+  allowedStatesSource?: string,
   /** Whether the variant is exposed in the generated API (non-`@noApi`). */
-  apiExposed: @s.matches(boolOptionSchema) option<bool>,
+  apiExposed: option<bool>,
   /** Access keys — any one of them — a caller needs to be *offered* this command.
       A hint derived from the server's rule, never the refusal itself. */
-  requiredAccess: @s.matches(stringArrayOptionSchema) option<array<string>>,
+  requiredAccess: option<array<string>>,
   /** The `@owner` command field the server stamps with the caller's identity; a
       client omits it from a form, since whatever it collects is discarded. */
-  ownerField: @s.matches(stringOptionSchema) option<string>,
+  ownerField: option<string>,
 }
 
 @schema
@@ -168,41 +211,41 @@ type queryableDef = {
   searchableFields: array<string>,
   /** Which rung produced `labelField`, so a consumer can rank it against its own
       rule: `"annotation"` | `"convention"` | `"position"` | `"fallback"`. */
-  labelFieldSource: @s.matches(stringOptionSchema) option<string>,
+  labelFieldSource: option<string>,
   /** The state field holding the row's lifecycle, paired with
       `commandDef.allowedStates`. From `@lifecycle`, else an enum named `lifecycle`. */
-  lifecycleField: @s.matches(stringOptionSchema) option<string>,
+  lifecycleField: option<string>,
   /** The `@owner` state field. Reads of this view are narrowed server-side to a
       non-elevated caller's own rows. */
-  ownerField: @s.matches(stringOptionSchema) option<string>,
+  ownerField: option<string>,
   /** The `@retired` state field withdrawing a row from ordinary reads. From the
       annotation only — no fallback by name, since guessing hides data. */
-  retiredField: @s.matches(stringOptionSchema) option<string>,
+  retiredField: option<string>,
   /** The states a row is retired *in* (state form of `@retired`); `None` is the
       boolean form, where the excluded value is always `true`. */
-  retiredValues: @s.matches(stringArrayOptionSchema) option<array<string>>,
+  retiredValues: option<array<string>>,
   /** Whether the view publishes the by-ids reference door that names a retired row
       to any caller holding a pointer (`@namedWhenRetired`). Never true without
       `retiredField`. */
-  namedWhenRetired: @s.matches(boolOptionSchema) option<bool>,
+  namedWhenRetired: option<bool>,
   /** `@@reventless.visibility`. `Some("Internal")` hides the component from AutoUI;
       it is still carried here for developer tooling. `None` means Public. */
-  visibility: @s.matches(stringOptionSchema) option<string>,
+  visibility: option<string>,
   /** Intra-plugin grouping band, the first non-kind path segment under `src/`.
       `None` renders flat. */
-  chapter: @s.matches(stringOptionSchema) option<string>,
+  chapter: option<string>,
   /** The singular counterpart of `queryField` (`Plugin_Order`), also the prefix of
       the generated input types. Not derivable without `Api_Naming.singularize`. */
-  singleQueryField: @s.matches(stringOptionSchema) option<string>,
+  singleQueryField: option<string>,
   /** The state field identifying a row, as opposed to a reference to another entity.
       `None` means unresolved — no key-derived filter or sort until `@id` is declared. */
-  idField: @s.matches(stringOptionSchema) option<string>,
+  idField: option<string>,
   /** Which rung produced `idField`, as `labelFieldSource` does: `"annotation"` |
       `"convention"` | `"sole"`. */
-  idFieldSource: @s.matches(stringOptionSchema) option<string>,
+  idFieldSource: option<string>,
   /** Access keys — any one of them — a caller needs to be *offered* this view. A
       denied read comes back empty rather than erroring, hence the hint. */
-  requiredAccess: @s.matches(stringArrayOptionSchema) option<array<string>>,
+  requiredAccess: option<array<string>>,
 }
 
 /** One emitted event of a write side. `name` is the variant name, `schema` its
@@ -230,7 +273,7 @@ type writableDef = {
   producedEventTypes: array<string>,
   consumedEventTypes: array<string>,
   linkedViews: array<string>,
-  consistencyRead: @s.matches(stringOptionSchema) option<string>,
+  consistencyRead: option<string>,
   /** Emitted-event field schemas; `[]` when there are none. */
   events: array<eventDef>,
   /** Declared-error field schemas. Required, but a persisted structure predating a
@@ -238,7 +281,7 @@ type writableDef = {
       `[]` on read, and a new one must be added there too. */
   errors: array<errorDef>,
   /** Chapter grouping band — see `queryableDef.chapter`. */
-  chapter: @s.matches(stringOptionSchema) option<string>,
+  chapter: option<string>,
 }
 
 @schema
@@ -248,7 +291,7 @@ type automationSliceDef = {
   producedCommandTypes: array<string>,
   targetName: string,
   /** Chapter grouping band — see `queryableDef.chapter`. */
-  chapter: @s.matches(stringOptionSchema) option<string>,
+  chapter: option<string>,
 }
 
 @schema
@@ -256,11 +299,11 @@ type outboundTranslationSliceDef = {
   name: string,
   consumedEventTypes: array<string>,
   inboundCommandTypes: array<string>,
-  targetName: @s.matches(stringOptionSchema) option<string>,
+  targetName: option<string>,
   // Foreign system this slice publishes to — drives the external box (Event Graph).
-  externalSystem: @s.matches(stringOptionSchema) option<string>,
+  externalSystem: option<string>,
   /** Chapter grouping band — see `queryableDef.chapter`. */
-  chapter: @s.matches(stringOptionSchema) option<string>,
+  chapter: option<string>,
   /** The topics this slice subscribes to, as `Spec.sourceNames` declares them —
       an Aggregate's `Spec.name` or a DCB source name. `Some([])` is the declared
       default and means this plugin's own DCB log; `None` is an older structure
@@ -268,7 +311,7 @@ type outboundTranslationSliceDef = {
       which names event types and not where they came from — two topics carrying
       an event of the same name are indistinguishable there. Optional so an older
       reader ignores it. */
-  consumedSources: @s.matches(stringArrayOptionSchema) option<array<string>>,
+  consumedSources: option<array<string>>,
 }
 
 @schema
@@ -277,9 +320,9 @@ type inboundTranslationSliceDef = {
   commandTypes: array<string>,
   targetName: string,
   // Foreign system this slice receives from — drives the external box (Event Graph).
-  externalSystem: @s.matches(stringOptionSchema) option<string>,
+  externalSystem: option<string>,
   /** Chapter grouping band — see `queryableDef.chapter`. */
-  chapter: @s.matches(stringOptionSchema) option<string>,
+  chapter: option<string>,
 }
 
 /** A published event of an extension point and the internal events producing it.
@@ -291,8 +334,6 @@ type publishedEventDef = {
   fromEventTypes: array<string>,
 }
 
-let publishedEventDefArrayOptionSchema = S.array(publishedEventDefSchema)->S.nullAsOption
-
 /** The command direction's producer half: a command an extension point takes and
     the delegate commands it routes to. `name` is EP-qualified, `toCommandTypes`
     plugin-qualified. */
@@ -302,8 +343,6 @@ type acceptedCommandDef = {
   toCommandTypes: array<string>,
 }
 
-let acceptedCommandDefArrayOptionSchema = S.array(acceptedCommandDefSchema)->S.nullAsOption
-
 /** The subscriber's half: a published event and the commands it routes to. A
     delegate command is plugin-qualified, one sent back to the EP is EP-qualified. */
 @schema
@@ -312,8 +351,6 @@ type handledEventDef = {
   toCommandTypes: array<string>,
 }
 
-let handledEventDefArrayOptionSchema = S.array(handledEventDefSchema)->S.nullAsOption
-
 /** The command direction's subscriber half: a command sent back to the port and
     the internal events producing it. `name` is EP-qualified, `fromEventTypes`
     plugin-qualified. */
@@ -323,21 +360,19 @@ type issuedCommandDef = {
   fromEventTypes: array<string>,
 }
 
-let issuedCommandDefArrayOptionSchema = S.array(issuedCommandDefSchema)->S.nullAsOption
-
 @schema
 type extensionDef = {
   name: string,
   delegateNames: array<string>,
   eventTypes: array<string>,
   commandTypes: array<string>,
-  /** Which published event routes to which commands. js_nullable like
+  /** Which published event routes to which commands. Optional like
       `extensionPointDef.commandTypes`; re-emit definitions persisted before it. */
-  handledEvents: @s.matches(handledEventDefArrayOptionSchema) option<array<handledEventDef>>,
+  handledEvents: option<array<handledEventDef>>,
   /** Which internal event sends which command back to the port. `None` means a
       definition persisted before the field, NOT an extension that issues nothing —
       a reader joining the two halves must keep them apart. */
-  issuedCommands: @s.matches(issuedCommandDefArrayOptionSchema) option<array<issuedCommandDef>>,
+  issuedCommands: option<array<issuedCommandDef>>,
 }
 
 /**
@@ -346,28 +381,21 @@ An extension point owned by a plugin, from the producer side.
 `sourceEventTypes` are the `Delegate`'s events feeding the published protocol,
 plugin-qualified to match `writableDef.producedEventTypes`. `commandTypes` is the
 EP's inbound protocol — None (read as []) for a `command = unit` EP, which routes
-nothing. js_nullable is the only JSON-safe optional here (this def is nested in the
-lifecycle Message union); definitions persisted before a field must be re-emitted.
+nothing. Definitions persisted before a field was added must be re-emitted.
 */
 @schema
 type extensionPointDef = {
   name: string,
   delegateNames: array<string>,
   sourceEventTypes: array<string>,
-  commandTypes: @s.matches(stringArrayOptionSchema) option<array<string>>,
+  commandTypes: option<array<string>>,
   /** Which internal event becomes which published event. */
-  publishedEvents: @s.matches(publishedEventDefArrayOptionSchema)
-  option<array<publishedEventDef>>,
+  publishedEvents: option<array<publishedEventDef>>,
   /** Which arriving command becomes which delegate command. `None` means a
       definition persisted before the field, NOT a port that accepts nothing. */
-  acceptedCommands: @s.matches(acceptedCommandDefArrayOptionSchema)
-  option<array<acceptedCommandDef>>,
+  acceptedCommands: option<array<acceptedCommandDef>>,
 }
 
-// js_nullable creates `array | null` (not `| undefined`), which passes sury's
-// jsonableValidation inside the pluginStructure union variant payload.
-let extensionPointDefArrayOptionSchema = S.array(extensionPointDefSchema)->S.nullAsOption
-
 /**
 One field's store requirement, with its provenance.
 
@@ -382,12 +410,9 @@ type requiredStoreDeclaration = {
   store: string,
   component: string,
   field: string,
-  annotation: @s.matches(stringOptionSchema) option<string>,
+  annotation: option<string>,
 }
 
-let requiredStoreDeclarationArrayOptionSchema =
-  S.array(requiredStoreDeclarationSchema)->S.nullAsOption
-
 /**
 One component's capability requirement, with its provenance.
 
@@ -400,9 +425,6 @@ expressible as an annotation on one, which is why the need is declared.
 @schema
 type requiredCapabilityDeclaration = {capability: string, component: string}
 
-let requiredCapabilityDeclarationArrayOptionSchema =
-  S.array(requiredCapabilityDeclarationSchema)->S.nullAsOption
-
 /**
 One graft's provenance: which trait, at which version, on which component.
 
@@ -427,14 +449,13 @@ type traitDeclaration = {
   component: string,
 }
 
-let traitDeclarationArrayOptionSchema = S.array(traitDeclarationSchema)->S.nullAsOption
-
 /**
 Adding a field here? It must be a shape a stale event can be healed into — the
 lifecycle aggregate replays its own log before every decision, so one event that
-fails to decode freezes that plugin's registration. `Message.parseJsonTolerant`
-heals `T | null`, arrays, enums and nested objects; a bare scalar is fabricated
-and warned about. Prefer `js_nullable`. Regression suite:
+fails to decode freezes that plugin's registration. Make it `option`, which
+`Message.parseJsonTolerant` heals to `None` whatever the inner type is. A required
+array heals to `[]` and a required enum to its first variant; a required *scalar*
+is fabricated and warned about, so it is the one shape to avoid. Regression suite:
 `PluginLifecycleCorpusTest` — if it goes red, re-shape the field, not the fixtures.
 */
 @schema
@@ -449,27 +470,23 @@ type pluginStructure = {
   extensions: array<extensionDef>,
   // Extension points owned by this plugin (producer side). Optional so older
   // definitions still decode (absent → None, read as []).
-  extensionPoints: @s.matches(extensionPointDefArrayOptionSchema)
-  option<array<extensionPointDef>>,
+  extensionPoints: option<array<extensionPointDef>>,
   /** The object stores this plugin's fields declare they need, deduplicated and
       qualified as `{plugin}.{store}` even for the same-plugin case. */
-  requiredStores: @s.matches(stringArrayOptionSchema) option<array<string>>,
+  requiredStores: option<array<string>>,
   /** Provenance for `requiredStores`: one entry per declaring `(component, field)`.
       `requiredStores` is derived from it, so the two cannot disagree. */
-  requiredStoreDeclarations: @s.matches(requiredStoreDeclarationArrayOptionSchema)
-  option<array<requiredStoreDeclaration>>,
+  requiredStoreDeclarations: option<array<requiredStoreDeclaration>>,
   /** The platform capabilities this plugin's components declare they need, one
       entry per declaring component. Object stores are not here — a store need is
       a field's, and travels as `requiredStores`. Absent → None, read as []. */
-  requiredCapabilities: @s.matches(requiredCapabilityDeclarationArrayOptionSchema)
-  option<array<requiredCapabilityDeclaration>>,
+  requiredCapabilities: option<array<requiredCapabilityDeclaration>>,
   /** The domain traits grafted into this plugin, one entry per declaring
       component. Absent → None, read as []. The only signal a graft leaves that
       survives into a deployed plugin — every other one (the dependency, the
       variant spread, the rules alias, the conformance binding) is source-side.
       A claim about origin, never about behaviour: see `Trait`. */
-  traitDeclarations: @s.matches(traitDeclarationArrayOptionSchema)
-  option<array<traitDeclaration>>,
+  traitDeclarations: option<array<traitDeclaration>>,
 }
 
 let pluginStructureOffloadSchema = Offload.optionSchema(~store="pluginStructures", pluginStructureSchema)
@@ -496,15 +513,15 @@ type pluginDefinition = {
   apiSchemaFragment: @s.matches(apiSchemaFragmentOffloadSchema) option<Offload.payload<apiSchemaFragment>>,
   // Schema routing in split-API mode: None/"Domain" → DomainApi, Some("Platform") →
   // PlatformApi (and excluded from the DomainApi runtime schema).
-  apiTarget: @s.matches(stringOptionSchema) option<string>,
+  apiTarget: option<string>,
   // Component graph metadata, offloadable like apiSchemaFragment. Absent for older
   // protocol versions.
   structure: @s.matches(pluginStructureOffloadSchema) option<Offload.payload<pluginStructure>>,
   // EventTopic ARN of a bundled DcbEventLog, so the admin can subscribe peer
   // EventCollectors to it. None for plugins without one.
-  dcbEventLog: @s.matches(dcbEventLogOptionSchema) option<dcbEventLogDefinition>,
+  dcbEventLog: option<dcbEventLogDefinition>,
   // Mandatory; `Domain` is resolved as the default in Plugin_Builder. Payload-less
-  // variant → a bare JSON string, so JSON-safe without js_nullable.
+  // variant → a bare JSON string.
   kind: pluginKind,
 }