@reventlessdev/reventless-spec 3.0.0-alpha.110 → 3.0.0-alpha.111

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 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.111 (2026-08-12)
+
+### Features
+
+* **scripts:** publish the platform SDL instead of copying it by hand ([3f28ceb](https://github.com/ReventlessDev/reventless-core/commit/3f28cebe7f9f947894105592d7ff7e5c07043d8f))
+
+
 # 3.0.0-alpha.110 (2026-08-12)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.110",
+  "version": "3.0.0-alpha.111",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/schema/README.md

@@ -0,0 +1,41 @@
+# The platform admin API contract
+
+`platform-api.graphql` is the SDL of the platform admin API — the `Platform_*`
+half of what a UI shell talks to. It is **published with this package**, and a
+shell compiles its Relay queries against it as a dependency rather than keeping a
+copy of its own.
+
+That is the whole point of it living here. A snapshot copied by hand into another
+repo rots silently: the copy keeps compiling green against a schema no server
+serves, and the shell fails only against a real backend. A snapshot that arrives
+by dependency bump cannot get out of step with a version. Lerna versions this
+repo off conventional commits, so this package bumps exactly when its contents
+change — **the version a shell pins is the contract version it compiles
+against.**
+
+That also keeps a shell from running ahead of a platform. A hand-written GraphQL
+document is a lockstep change, not an additive one: the server rejects the whole
+document when it selects a field the schema does not declare, so a shell ahead of
+its platform boots to nothing rather than degrading. Pinning a published version
+means the contract a shell compiles against is one that exists.
+
+## It is generated, not written
+
+Written by `pnpm run check:graphql` from the repo root, which boots the hybrid
+example's local platform and introspects it. Do not edit it by hand.
+
+The example is only a vehicle — nothing example-specific reaches this file. Every
+type in it is `Platform_*` or framework-level (`CommandResult`, `PageInfo`,
+`SortOrder`, …); no plugin of that example contributes anything. Its sibling
+golden, `domain-api.graphql`, is the plugin-generated half and stays with the
+example that produces it.
+
+Sorted through `lexicographicSortSchema`, so it is a function of the schema alone
+— the platform builds its type map from dicts, and unsorted output would diff on
+iteration order rather than on a real contract change.
+
+## Changing it
+
+Change the platform, then run `pnpm run check:graphql:update` and commit this
+file alongside the change that moved it. The diff is the review artifact for a
+wire-shape change.

package/schema/platform-api.graphql

@@ -0,0 +1,318 @@
+type CommandAccepted {
+  entityId: ID
+  eventCount: Int!
+  msgId: ID!
+}
+
+type CommandPending {
+  msgId: ID!
+}
+
+type CommandRejected {
+  errorCode: String!
+  errorDetail: String
+  msgId: ID!
+}
+
+union CommandResult = CommandAccepted | CommandPending | CommandRejected
+
+type Mutation {
+  Platform_PluginStatusChanged(pluginId: ID!, status: PluginStatus!): PluginStatusChangeEvent
+  Platform_Plugin_Activate(_0: String!, id: ID!): CommandResult!
+  Platform_Plugin_Deactivate(_0: String!, id: ID!): CommandResult!
+  Platform_Plugin_Retire(_0: String!, id: ID!): CommandResult!
+  Platform_UIFragmentDeregistered(pluginId: ID!): UIFragmentChangeEvent
+  Platform_UIFragmentRegistered(manifest: String, pluginId: ID!): UIFragmentChangeEvent
+  Platform_UIFragmentUpdated(manifest: String, pluginId: ID!): UIFragmentChangeEvent
+}
+
+interface Node {
+  id: ID!
+}
+
+type PageInfo {
+  endCursor: String
+  hasNextPage: Boolean!
+  hasPreviousPage: Boolean!
+  startCursor: String
+}
+
+type Platform_AutomationSliceDef {
+  chapter: String
+  consumedEventTypes: [String!]!
+  name: String!
+  producedCommandTypes: [String!]!
+  targetName: String
+}
+
+type Platform_CommandDef {
+  aggregateIdField: String
+  allowedStates: [String!]
+  apiExposed: Boolean
+  level: String!
+  mutationField: String!
+  name: String!
+  ownerField: String
+  references: [Platform_FieldReference!]!
+  requiredAccess: [String!]
+  schema: String!
+  targetState: String
+}
+
+type Platform_ComponentDefinitionEntry {
+  aggregates: [Platform_WriteSideDef!]!
+  automationSlices: [Platform_AutomationSliceDef!]!
+  extensions: [Platform_ExtensionDef!]!
+  inboundTranslationSlices: [Platform_InboundTranslationSliceDef!]!
+  internalQueryables: [Platform_ReadSideDef!]!
+  outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!
+  pluginId: String!
+  readModels: [Platform_ReadSideDef!]!
+  stateChangeSlices: [Platform_WriteSideDef!]!
+  stateViewSlices: [Platform_ReadSideDef!]!
+}
+
+type Platform_ErrorDef {
+  name: String!
+  references: [Platform_FieldReference!]!
+  schema: String!
+}
+
+type Platform_EventDef {
+  name: String!
+  references: [Platform_FieldReference!]!
+  schema: String!
+}
+
+type Platform_ExtensionDef {
+  commandTypes: [String!]!
+  delegateNames: [String!]!
+  eventTypes: [String!]!
+  name: String!
+}
+
+type Platform_ExtensionPointDef {
+  commandTypes: [String!]
+  delegateNames: [String!]!
+  name: String!
+  sourceEventTypes: [String!]!
+}
+
+type Platform_FieldReference {
+  entity: String!
+  fieldName: String!
+  plugin: String
+}
+
+type Platform_InboundTranslationSliceDef {
+  chapter: String
+  commandTypes: [String!]!
+  externalSystem: String
+  name: String!
+  targetName: String
+}
+
+type Platform_OutboundTranslationSliceDef {
+  chapter: String
+  consumedEventTypes: [String!]!
+  externalSystem: String
+  inboundCommandTypes: [String!]!
+  name: String!
+  targetName: String
+}
+
+type Platform_Plugin implements Node {
+  apiSchemaFragment: String
+  apiTarget: String
+  dcbEventLog: Platform_PluginDcbEventLog
+  extensionPoints: [Platform_PluginExtensionPoints!]!
+  extensions: [Platform_PluginExtensions!]!
+  id: ID!
+  kind: Platform_PluginKind
+  name: String!
+  otherConnectedVersions: [String!]!
+  status: Platform_PluginStatus!
+  statusChange: Platform_PluginStatusChange!
+  structure: String
+  version: String!
+}
+
+type Platform_PluginConnection {
+  edges: [Platform_PluginEdge!]!
+  pageInfo: PageInfo!
+}
+
+type Platform_PluginDcbEventLog {
+  eventTopicArn: String!
+  name: String!
+}
+
+type Platform_PluginEdge {
+  cursor: String!
+  node: Platform_Plugin!
+}
+
+type Platform_PluginExtensionPoints {
+  commandTopic: String!
+  eventTopic: String!
+  name: String!
+}
+
+type Platform_PluginExtensions {
+  dcbSources: [String!]!
+  extensionPointName: String!
+  name: String!
+}
+
+input Platform_PluginFilter {
+  ids: [ID!]
+  kindEq: String
+  search: String
+  searchPrefix: String
+}
+
+enum Platform_PluginKind {
+  Commercial
+  Domain
+  Marketplace
+  PlatformInfrastructure
+}
+
+enum Platform_PluginStatus {
+  Connected
+  Disconnected
+  Inactive
+  Retired
+}
+
+type Platform_PluginStatusChange {
+  at: String!
+  by: String!
+}
+
+type Platform_PluginStructureEntry {
+  aggregates: [Platform_WriteSideDef!]!
+  automationSlices: [Platform_AutomationSliceDef!]!
+  extensionPoints: [Platform_ExtensionPointDef!]
+  extensions: [Platform_ExtensionDef!]!
+  inboundTranslationSlices: [Platform_InboundTranslationSliceDef!]!
+  outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!
+  pluginId: String!
+  readModels: [Platform_ReadSideDef!]!
+  requiredStoreDeclarations: [Platform_RequiredStoreDeclaration!]
+  requiredStores: [String!]
+  stateChangeSlices: [Platform_WriteSideDef!]!
+  stateViewSlices: [Platform_ReadSideDef!]!
+}
+
+type Platform_ReadSideDef {
+  chapter: String
+  consumedEventTypes: [String!]!
+  idField: String
+  idFieldSource: String
+  labelField: String!
+  labelFieldSource: String
+  linkedWriteSide: [String!]!
+  name: String!
+  ownerField: String
+  queryField: String!
+  requiredAccess: [String!]
+  schema: String!
+  searchableFields: [String!]!
+  singleQueryField: String
+  statusField: String
+  visibility: String
+}
+
+type Platform_RequiredStoreDeclaration {
+  annotation: String
+  component: String!
+  field: String!
+  store: String!
+}
+
+type Platform_UIFragmentEntry {
+  pages: [Platform_UIPage!]!
+  panels: [Platform_UIPanel!]!
+  pluginId: String!
+  registeredAt: String!
+  remoteEntryUrl: String!
+  updatedAt: String!
+}
+
+type Platform_UIMenuEntry {
+  group: String
+  icon: String
+  label: String!
+  sortOrder: Int!
+}
+
+type Platform_UIPage {
+  fragmentId: String!
+  menuEntry: Platform_UIMenuEntry!
+  requiredAccess: String
+  title: String!
+}
+
+type Platform_UIPanel {
+  description: String!
+  fragmentId: String!
+  positions: [String!]!
+  requiredAccess: String
+  title: String!
+}
+
+type Platform_WriteSideDef {
+  chapter: String
+  commands: [Platform_CommandDef!]!
+  consistencyRead: String
+  consumedEventTypes: [String!]!
+  errors: [Platform_ErrorDef!]!
+  events: [Platform_EventDef!]!
+  linkedViews: [String!]!
+  name: String!
+  producedEventTypes: [String!]!
+}
+
+enum PluginStatus {
+  Connected
+  Disconnected
+  Inactive
+  Retired
+}
+
+type PluginStatusChangeEvent {
+  pluginId: ID!
+  status: PluginStatus!
+}
+
+type Query {
+  Platform_ComponentDefinitions: [Platform_ComponentDefinitionEntry!]!
+  Platform_Plugin(id: ID!): Platform_Plugin
+  Platform_PluginStructures: [Platform_PluginStructureEntry!]!
+  Platform_Plugins(after: String, before: String, filter: Platform_PluginFilter, first: Int, last: Int): Platform_PluginConnection!
+  Platform_PluginsByIds(ids: [String!]!): [Platform_Plugin!]!
+  Platform_UIFragments: [Platform_UIFragmentEntry!]!
+}
+
+enum SortOrder {
+  ASC
+  DESC
+}
+
+type Subscription {
+  onPluginStatusChange: PluginStatusChangeEvent
+  onUIFragmentChange: UIFragmentChangeEvent
+}
+
+type UIFragmentChangeEvent {
+  changeKind: UIFragmentChangeKind!
+  manifest: String
+  pluginId: ID!
+}
+
+enum UIFragmentChangeKind {
+  Deregistered
+  Registered
+  Updated
+}