@reventlessdev/reventless-spec 3.0.0-alpha.61

package/src/components/Plugin.res

@@ -0,0 +1,373 @@
+/** The logical name of a plugin (serializable as JSON). */
+@schema
+type name = string
+
+/** The semantic version string of a plugin release. */
+@schema
+type version = string
+
+/**
+Describes an extension point exported by a plugin.
+Included in the plugin's `pluginDefinition` for use by the gateway / host.
+*/
+@schema
+type extensionPointDefinition = {
+  name: string,
+  commandTopic: string,
+  eventTopic: string,
+}
+
+/**
+Describes an extension imported by a plugin (i.e. a connection to a host plugin's
+extension point).
+Included in the plugin's `pluginDefinition` for use by the host.
+*/
+@schema
+type extensionDefinition = {
+  name: string,
+  extensionPointName: string,
+  /**
+  DCB EventLog source names this extension consumes. Convention: each entry is
+  the `name` field of a peer plugin's `dcbEventLogDefinition` (i.e. `${peer}DcbEventLog`).
+  The admin uses these to provision cross-plugin SNS subscriptions from peer DCB
+  EventTopics → this plugin's EventCollector. `[]` for extensions that only consume
+  ExtensionPoint EventTopics.
+  */
+  dcbSources: array<string>,
+}
+
+/**
+Describes a DCB EventLog exposed by a plugin.
+Included in the plugin's `pluginDefinition` so the admin can provision SNS
+subscriptions from this plugin's DCB EventTopic to any peer plugin whose
+extension references the DCB log by name.
+*/
+@schema
+type dcbEventLogDefinition = {
+  /** Service name carried in event meta — convention: `${plugin.name}DcbEventLog`. */
+  name: string,
+  /** SNS topic ARN for the DCB EventLog's EventTopic. */
+  eventTopicArn: string,
+}
+
+/**
+Protocol version declaration for a single extension point connection.
+
+Carried in the `ConnectPlugin` handshake so the host can validate schema
+compatibility before accepting the extension. Use `[]` when version
+negotiation is not needed.
+*/
+// Protocol version declaration for a single extension point connection.
+// Carried in the ConnectPlugin handshake so the host can validate compatibility.
+@schema
+type extensionProtocol = {
+  extensionPointName: string,
+  /** SemVer of the command schema the extension was compiled against. */
+  commandVersion: string,
+  /** SemVer of the event schema the extension was compiled against. */
+  eventVersion: string,
+}
+
+/**
+A GraphQL schema fragment contributed by a plugin.
+Encoded as JSON for transport; protocol identifies the schema format (e.g. "graphql").
+*/
+@schema
+type apiSchemaFragment = {encoded: string, protocol: string}
+
+// 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 apiSchemaFragmentOptionSchema = _jsNullable(apiSchemaFragmentSchema, ())
+let dcbEventLogOptionSchema = _jsNullable(dcbEventLogDefinitionSchema, ())
+// 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, ())
+
+// ── UI fragment manifest types ────────────────────────────────────────────────
+
+@schema
+type panelManifestEntry = {
+  fragmentId: string,
+  title: string,
+  description: string,
+  positions: array<string>,
+  requiredAccess: @s.matches(stringOptionSchema) option<string>,
+}
+
+@schema
+type menuEntry = {
+  label: string,
+  icon: @s.matches(stringOptionSchema) option<string>,
+  group: @s.matches(stringOptionSchema) option<string>,
+  sortOrder: int,
+}
+
+@schema
+type pageManifestEntry = {
+  fragmentId: string,
+  title: string,
+  menuEntry: menuEntry,
+  requiredAccess: @s.matches(stringOptionSchema) option<string>,
+}
+
+@schema
+type uiFragmentManifest = {
+  remoteEntryUrl: string,
+  panels: array<panelManifestEntry>,
+  pages: array<pageManifestEntry>,
+}
+
+let uiFragmentManifestOptionSchema = _jsNullable(uiFragmentManifestSchema, ())
+
+// ── Plugin structure types (component metadata for Auto UI and event graph) ──
+
+@schema
+type commandLevel = Collection | Instance
+
+@schema
+type fieldReference = {
+  fieldName: string,
+  entity: string,
+  plugin: @s.matches(stringOptionSchema) option<string>,
+}
+
+@schema
+type commandDef = {
+  name: string,
+  schema: string,
+  level: commandLevel,
+  aggregateIdField: @s.matches(stringOptionSchema) option<string>,
+  mutationField: string,
+  references: array<fieldReference>,
+  /**
+  Status values 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.
+  */
+  allowedStates: @s.matches(stringArrayOptionSchema) option<array<string>>,
+  /**
+  Whether this command variant is exposed in the generated API (a non-`@noApi`
+  variant of a non-`@noApi` command). Dev tooling badges API-exposed commands in
+  the event graph. js_nullable (T | null) so it stays JSON-safe inside the
+  persisted/lifecycle payloads; absent on defs written before this field existed
+  (read as None) — those stores must be reset. See [[sury-optional-field-absent-vs-null]].
+  */
+  apiExposed: @s.matches(boolOptionSchema) option<bool>,
+}
+
+@schema
+type queryableDef = {
+  name: string,
+  queryField: string,
+  schema: string,
+  consumedEventTypes: array<string>,
+  linkedWriteSide: array<string>,
+  /**
+  The field on this entity that carries the human-readable label.
+  When the entity's state schema declares one or more `@displayName` annotations,
+  this resolves to `"displayName"` (the projected column). Otherwise it falls back
+  to the first non-`id` string property, or `"id"` as a last resort.
+  */
+  labelField: string,
+  /**
+  Fields appropriate for label-oriented text search.
+  Mirrors `labelField` when the entity uses the fallback or single-field label.
+  For composite `@displayName` annotations, lists the *raw* underlying source
+  fields (so clients with substring indexes can target them directly).
+  */
+  searchableFields: array<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.
+  */
+  statusField: @s.matches(stringOptionSchema) option<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
+  components are still CARRIED in `pluginStructure` (tagged here) so developer tools — the
+  `reventless-gwt` / VSCode domain graph and dead-code analysis — can see them, per
+  Visibility.res. Optional for back-compat: definitions persisted before this field
+  existed decode as `None` (Public).
+  */
+  visibility: @s.matches(stringOptionSchema) option<string>,
+}
+
+/**
+One emitted event of a write side, with its field schema. Mirrors `commandDef`
+but for the past-tense facts a write side produces: `name` is the event variant
+name (e.g. `OrderPlaced`), `schema` is the JSON Schema of that variant's payload
+(same `S.toJSONSchema` serialization as `commandDef.schema`, incl. `x-reventless-*`
+extensions and the `TAG` const), `references` its cross-entity field links.
+Carried so developer tools (the `reventless-dev` / VSCode domain graph) can show
+event field rows — AutoUI ignores it. */
+@schema
+type eventDef = {
+  name: string,
+  schema: string,
+  references: array<fieldReference>,
+}
+
+@schema
+type writableDef = {
+  name: string,
+  commands: array<commandDef>,
+  producedEventTypes: array<string>,
+  consumedEventTypes: array<string>,
+  linkedViews: array<string>,
+  consistencyRead: @s.matches(stringOptionSchema) option<string>,
+  /** Emitted-event field schemas (Phase 6.3). Required like the other write-side
+  arrays; `[]` when there are none. The structure is re-derived on every build/
+  deploy, so no persisted-data back-compat shim is needed. */
+  events: array<eventDef>,
+}
+
+@schema
+type automationSliceDef = {
+  name: string,
+  consumedEventTypes: array<string>,
+  producedCommandTypes: array<string>,
+  targetName: string,
+}
+
+@schema
+type outboundTranslationSliceDef = {
+  name: string,
+  consumedEventTypes: array<string>,
+  inboundCommandTypes: array<string>,
+  targetName: @s.matches(stringOptionSchema) option<string>,
+}
+
+@schema
+type inboundTranslationSliceDef = {
+  name: string,
+  commandTypes: array<string>,
+  targetName: string,
+}
+
+@schema
+type extensionDef = {
+  name: string,
+  delegateNames: array<string>,
+  eventTypes: array<string>,
+  commandTypes: array<string>,
+}
+
+/**
+Describes an extension point owned by a plugin, from the *producer* side.
+
+`sourceEventTypes` are the owner-plugin internal events (the `Delegate`'s events)
+that feed this extension point's published protocol — plugin-qualified to match
+`writableDef.producedEventTypes`, so the event graph can link a producing
+write-side to the extension point it ultimately feeds. `delegateNames` are the
+connected targets (one per `ExtensionPointMapping`).
+
+`commandTypes` are the EP's *inbound* command protocol (the variants of its
+`command` type). It is empty (None, read as []) when the EP declares
+`command = unit` — a notification-only, events-out boundary that accepts nothing
+inward. The event graph uses this to decide whether the EP routes any command (an
+empty list means no `routesTo` edge: there is nothing for the EP to route).
+
+Optional (None for a `command = unit` EP). Uses the `js_nullable` pattern (T | null).
+A sury field cannot be BOTH absent-tolerant on decode AND JSON-encodable (proven:
+S.option = `T|undefined`, nullableAsOption = `T|undefined|null` both decode an absent
+key but fail jsonableValidation; js_nullable = `T|null` is the only JSON-safe form but
+rejects an absent key). This def is nested in the JSON-encoded lifecycle Message union
+(Connect/Heartbeat), so jsonability wins → js_nullable. It always writes the field
+(None → null), so it is present-required on decode; a plugin definition persisted
+before this field existed must be reset/re-emitted. Read with `->Option.getOr([])`.
+*/
+@schema
+type extensionPointDef = {
+  name: string,
+  delegateNames: array<string>,
+  sourceEventTypes: array<string>,
+  commandTypes: @s.matches(stringArrayOptionSchema) option<array<string>>,
+}
+
+// js_nullable creates `array | null` (not `| undefined`), which passes sury's
+// jsonableValidation inside the pluginStructure union variant payload.
+let extensionPointDefArrayOptionSchema = _jsNullable(S.array(extensionPointDefSchema), ())
+
+@schema
+type pluginStructure = {
+  readModels: array<queryableDef>,
+  stateViewSlices: array<queryableDef>,
+  stateChangeSlices: array<writableDef>,
+  aggregates: array<writableDef>,
+  automationSlices: array<automationSliceDef>,
+  outboundTranslationSlices: array<outboundTranslationSliceDef>,
+  inboundTranslationSlices: array<inboundTranslationSliceDef>,
+  extensions: array<extensionDef>,
+  // Extension points owned by this plugin (producer side). Optional so plugin
+  // definitions persisted before this field existed still decode (absent → None,
+  // read as []). js_nullable keeps it JSON-safe inside union variant payloads.
+  extensionPoints: @s.matches(extensionPointDefArrayOptionSchema)
+  option<array<extensionPointDef>>,
+}
+
+let pluginStructureOptionSchema = _jsNullable(pluginStructureSchema, ())
+
+// ── Event graph types (cross-plugin component graph) ──────────────────────────
+
+@schema
+type graphNode = {pluginName: string, componentName: string, kind: string}
+
+@schema
+type graphEdge = {
+  source: graphNode,
+  target: graphNode,
+  mechanism: string,
+  viaEvents: array<string>,
+  implicit: bool,
+}
+
+@schema
+type platformEventGraph = {nodes: array<graphNode>, edges: array<graphEdge>}
+
+/**
+The self-description of a deployed plugin, persisted in the plugin's event store.
+
+Used by the gateway to discover extension points, extensions, and protocol versions.
+The `eventCollector` field is mutable so it can be set after the heartbeat lambda
+registers its own ARN.
+*/
+@schema
+type pluginDefinition = {
+  id: string,
+  name: name,
+  version: version,
+  extensionPoints: array<extensionPointDefinition>,
+  extensions: array<extensionDefinition>,
+  mutable eventCollector: string,
+  // Protocol version declarations for each extension point this plugin connects to.
+  // Use [] when the plugin does not need version negotiation.
+  extensionProtocols: array<extensionProtocol>,
+  // GraphQL schema fragment contributed by this plugin (optional, set at build time).
+  // Uses @s.matches(apiSchemaFragmentOptionSchema) — js_nullable creates T | null
+  // (not T | undefined | null), which passes sury's jsonableValidation inside union variants.
+  apiSchemaFragment: @s.matches(apiSchemaFragmentOptionSchema) option<apiSchemaFragment>,
+  // API target for schema routing in split-API mode.
+  // None/"Domain" → fragment goes to the DomainApi (default).
+  // Some("Platform") → fragment goes to the PlatformApi; excluded from DomainApi runtime schema.
+  // Uses @s.matches(stringOptionSchema) — js_nullable creates string | null (not string | undefined),
+  // which passes sury's jsonableValidation inside union variant payloads.
+  apiTarget: @s.matches(stringOptionSchema) option<string>,
+  // UI fragment manifest contributed by this plugin (optional, absent for pure backend plugins).
+  uiFragments: @s.matches(uiFragmentManifestOptionSchema) option<uiFragmentManifest>,
+  // Component graph metadata — populated by makePluginDefinition; absent for older protocol versions.
+  structure: @s.matches(pluginStructureOptionSchema) option<pluginStructure>,
+  // DCB EventLog definition for plugins that bundle a DcbEventLog component.
+  // Carries the EventTopic ARN so the admin can provision cross-plugin SNS
+  // subscriptions from this plugin's DCB topic → peer EventCollectors.
+  // None for plugins without a DCB EventLog.
+  dcbEventLog: @s.matches(dcbEventLogOptionSchema) option<dcbEventLogDefinition>,
+}
+

package/src/components/Plugin.res.mjs

@@ -0,0 +1,249 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as SuryResMjs from "sury/src/Sury.res.mjs";
+
+let extensionPointDefinitionSchema = S.schema(s => ({
+  name: s.m(S.string),
+  commandTopic: s.m(S.string),
+  eventTopic: s.m(S.string)
+}));
+
+let extensionDefinitionSchema = S.schema(s => ({
+  name: s.m(S.string),
+  extensionPointName: s.m(S.string),
+  dcbSources: s.m(S.array(S.string))
+}));
+
+let dcbEventLogDefinitionSchema = S.schema(s => ({
+  name: s.m(S.string),
+  eventTopicArn: s.m(S.string)
+}));
+
+let extensionProtocolSchema = S.schema(s => ({
+  extensionPointName: s.m(S.string),
+  commandVersion: s.m(S.string),
+  eventVersion: s.m(S.string)
+}));
+
+let apiSchemaFragmentSchema = S.schema(s => ({
+  encoded: s.m(S.string),
+  protocol: s.m(S.string)
+}));
+
+let apiSchemaFragmentOptionSchema = SuryResMjs.js_nullable(apiSchemaFragmentSchema);
+
+let dcbEventLogOptionSchema = SuryResMjs.js_nullable(dcbEventLogDefinitionSchema);
+
+let stringOptionSchema = SuryResMjs.js_nullable(S.string);
+
+let stringArrayOptionSchema = SuryResMjs.js_nullable(S.array(S.string));
+
+let boolOptionSchema = SuryResMjs.js_nullable(S.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)),
+  requiredAccess: s.m(stringOptionSchema)
+}));
+
+let menuEntrySchema = S.schema(s => ({
+  label: s.m(S.string),
+  icon: s.m(stringOptionSchema),
+  group: s.m(stringOptionSchema),
+  sortOrder: s.m(S.int)
+}));
+
+let pageManifestEntrySchema = S.schema(s => ({
+  fragmentId: s.m(S.string),
+  title: s.m(S.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 uiFragmentManifestOptionSchema = SuryResMjs.js_nullable(uiFragmentManifestSchema);
+
+let commandLevelSchema = S.union([
+  S.literal("Collection"),
+  S.literal("Instance")
+]);
+
+let fieldReferenceSchema = S.schema(s => ({
+  fieldName: s.m(S.string),
+  entity: s.m(S.string),
+  plugin: s.m(stringOptionSchema)
+}));
+
+let commandDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  schema: s.m(S.string),
+  level: s.m(commandLevelSchema),
+  aggregateIdField: s.m(stringOptionSchema),
+  mutationField: s.m(S.string),
+  references: s.m(S.array(fieldReferenceSchema)),
+  allowedStates: s.m(stringArrayOptionSchema),
+  apiExposed: s.m(boolOptionSchema)
+}));
+
+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)),
+  statusField: s.m(stringOptionSchema),
+  visibility: s.m(stringOptionSchema)
+}));
+
+let eventDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  schema: s.m(S.string),
+  references: s.m(S.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)),
+  consistencyRead: s.m(stringOptionSchema),
+  events: s.m(S.array(eventDefSchema))
+}));
+
+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 outboundTranslationSliceDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  consumedEventTypes: s.m(S.array(S.string)),
+  inboundCommandTypes: s.m(S.array(S.string)),
+  targetName: 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 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 extensionPointDefSchema = S.schema(s => ({
+  name: s.m(S.string),
+  delegateNames: s.m(S.array(S.string)),
+  sourceEventTypes: s.m(S.array(S.string)),
+  commandTypes: s.m(stringArrayOptionSchema)
+}));
+
+let extensionPointDefArrayOptionSchema = SuryResMjs.js_nullable(S.array(extensionPointDefSchema));
+
+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)),
+  extensionPoints: s.m(extensionPointDefArrayOptionSchema)
+}));
+
+let pluginStructureOptionSchema = SuryResMjs.js_nullable(pluginStructureSchema);
+
+let graphNodeSchema = S.schema(s => ({
+  pluginName: s.m(S.string),
+  componentName: s.m(S.string),
+  kind: s.m(S.string)
+}));
+
+let graphEdgeSchema = S.schema(s => ({
+  source: s.m(graphNodeSchema),
+  target: s.m(graphNodeSchema),
+  mechanism: s.m(S.string),
+  viaEvents: s.m(S.array(S.string)),
+  implicit: s.m(S.bool)
+}));
+
+let platformEventGraphSchema = S.schema(s => ({
+  nodes: s.m(S.array(graphNodeSchema)),
+  edges: s.m(S.array(graphEdgeSchema))
+}));
+
+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)),
+  apiSchemaFragment: s.m(apiSchemaFragmentOptionSchema),
+  apiTarget: s.m(stringOptionSchema),
+  uiFragments: s.m(uiFragmentManifestOptionSchema),
+  structure: s.m(pluginStructureOptionSchema),
+  dcbEventLog: s.m(dcbEventLogOptionSchema)
+}));
+
+let nameSchema = S.string;
+
+let versionSchema = S.string;
+
+export {
+  nameSchema,
+  versionSchema,
+  extensionPointDefinitionSchema,
+  extensionDefinitionSchema,
+  dcbEventLogDefinitionSchema,
+  extensionProtocolSchema,
+  apiSchemaFragmentSchema,
+  apiSchemaFragmentOptionSchema,
+  dcbEventLogOptionSchema,
+  stringOptionSchema,
+  stringArrayOptionSchema,
+  boolOptionSchema,
+  panelManifestEntrySchema,
+  menuEntrySchema,
+  pageManifestEntrySchema,
+  uiFragmentManifestSchema,
+  uiFragmentManifestOptionSchema,
+  commandLevelSchema,
+  fieldReferenceSchema,
+  commandDefSchema,
+  queryableDefSchema,
+  eventDefSchema,
+  writableDefSchema,
+  automationSliceDefSchema,
+  outboundTranslationSliceDefSchema,
+  inboundTranslationSliceDefSchema,
+  extensionDefSchema,
+  extensionPointDefSchema,
+  extensionPointDefArrayOptionSchema,
+  pluginStructureSchema,
+  pluginStructureOptionSchema,
+  graphNodeSchema,
+  graphEdgeSchema,
+  platformEventGraphSchema,
+  pluginDefinitionSchema,
+}
+/* extensionPointDefinitionSchema Not a pure module */