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

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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
+
+* **ppx:** let a field say [@owner](https://github.com/owner) instead of spelling out its schema ([3bb0a4b](https://github.com/ReventlessDev/reventless-core/commit/3bb0a4bf3e5823fa929815fbe6f47203ba7958d7))
+
+
 # 3.0.0-alpha.109 (2026-08-12)
 
 ### Features

package/package.json

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

package/src/components/Owner.res

@@ -20,25 +20,47 @@ the field goes unstamped and the view goes unscoped, silently. That is why
 why it exists at all rather than leaving each consumer to look the marker up
 itself.
 
-There is no `@owner` ppx shorthand yet — `@s.matches(Owner.string)` is the
-authoring form, not a workaround for one. The shorthand is sugar over exactly
-this, the way `@ref` is sugar over `Reference.to_`, so it can be added without
-changing what any reader here does; until it exists, prefer the explicit form
-over inventing an attribute the ppx will reject.
+`@owner` is the authoring form and is sugar over the constructors below, the way
+`@ref` is sugar over `Reference.to_`. Write `@s.matches(Owner.string)` by hand
+only where the ppx shorthand cannot reach — a file with no `@@reventless.spec`
+annotation, where the attribute would survive into the compiler as an unknown
+one.
 
 @example
 ```rescript
 @schema type command =
   PlaceOrder({
     @partitionTag orderId: string,
-    customerId: @s.matches(Owner.string) string,
+    @owner customerId: string,
   })
 ```
 */
 let ownerId: S.Metadata.Id.t<bool> = S.Metadata.Id.make(~namespace="reventless", ~name="owner")
 
+/**
+Layers the owner marker onto a schema that already says something else.
+
+Owner-ness is independent of everything else a field declares: the same field
+may be a DCB tag, a partition key, or a reference, and none of those implies or
+is implied by owning. But a field carries at most one `@s.matches`, so the
+shorthand composes by *wrapping* whatever schema the field already resolved to
+rather than replacing it — replacing would silently drop the field's DCB tag,
+and a dropped tag is a decision read that quietly misses events.
+*/
+let mark = (schema: S.t<'a>): S.t<'a> => schema->S.Metadata.set(~id=ownerId, true)
+
 /** A string field declared as the record's owner. */
-let string: S.t<string> = S.string->S.Metadata.set(~id=ownerId, true)
+let string: S.t<string> = S.string->mark
+
+/**
+An `option<string>` field declared as the record's owner.
+
+Needed because `@s.matches` on an explicitly-`option`-typed field must supply
+the whole field schema, wrapper included. The `f?: string` form needs nothing
+extra: sury wraps the annotated inner schema itself, and `isFieldOwner` looks
+through that wrapper either way.
+*/
+let optionString: S.t<option<string>> = S.option(string)
 
 /** Whether this exact schema carries the marker. Does not look through wrappers. */
 let isOwner = (schema: S.t<unknown>): bool =>

package/src/components/Owner.res.mjs

@@ -7,7 +7,13 @@ import * as Semantic$Reventless from "../semantic/Semantic.res.mjs";
 
 let ownerId = S.Metadata.Id.make("reventless", "owner");
 
-let string = S.Metadata.set(S.string, ownerId, true);
+function mark(schema) {
+  return S.Metadata.set(schema, ownerId, true);
+}
+
+let string = mark(S.string);
+
+let optionString = S.option(string);
 
 function isOwner(schema) {
   return Stdlib_Option.getOr(S.Metadata.get(schema, ownerId), false);
@@ -86,7 +92,9 @@ function variantFieldNames(schema, variant) {
 
 export {
   ownerId,
+  mark,
   string,
+  optionString,
   isOwner,
   isFieldOwner,
   fieldNamesOfProperties,