@reventlessdev/reventless-spec 3.0.0-alpha.123 → 3.0.0-alpha.125

package/CHANGELOG.md

@@ -3,6 +3,62 @@
 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.125 (2026-09-01)
+
+### Bug Fixes
+
+* **automation:** a mapping is handed the envelope's id ([9ee482c](https://github.com/ReventlessDev/reventless-core/commit/9ee482c5ad0aae09efd1259eeb7f39b781867b91))
+* **capabilities:** a plugin's geocoding need was declared nowhere and failed silently ([67917dd](https://github.com/ReventlessDev/reventless-core/commit/67917dd504b43fa78b7c6a51644c9eae656b7f6b))
+* feat(example)!: model product and category images as attachment sets ([6ae18d8](https://github.com/ReventlessDev/reventless-core/commit/6ae18d896215b448177ba0516e74bfda5f88d2db))
+### Features
+
+* **capabilities:** a plugin can send a message without naming a provider ([b001a1e](https://github.com/ReventlessDev/reventless-core/commit/b001a1e9361a0f4d0affe228cb4c08c38a5a995e))
+* **plugin:** the admin lifecycle commands name their argument ([ea552ec](https://github.com/ReventlessDev/reventless-core/commit/ea552ec64e5db0b3dc465c0d9a80cac89627f727))
+* **spec:** a command declares its lifecycle edge as a value ([40eee9f](https://github.com/ReventlessDev/reventless-core/commit/40eee9f7723dc05e418be680528f01967d074da4))
+* **spec:** a graft leaves a trace the deployed plugin can read ([c08ff6c](https://github.com/ReventlessDev/reventless-core/commit/c08ff6c0f6177d58603e7ae1e5cec392d9bac16a))
+* **spec:** graft-trait, a CLI that runs a trait's emitter ([1b87399](https://github.com/ReventlessDev/reventless-core/commit/1b87399987033765d6a1ee8ea22ab7f02056e9c0))
+* **traits:** a conformance run leaves something a machine can read ([cd9cb81](https://github.com/ReventlessDev/reventless-core/commit/cd9cb81aa643f8e30ccf072df458fdc136897746))
+* **traits:** a listing reads a trait instead of being told about it ([8a23219](https://github.com/ReventlessDev/reventless-core/commit/8a23219c5a69011ef9310ebf8bfcbf9315a577ba))
+
+### BREAKING CHANGES
+
+* ProductAdded/CategoryAdded lose their image field and
+ChangeProductImage/ChangeCategoryImage are replaced; the alpha event log is
+wiped on the next deploy.
+
+
+
+# 3.0.0-alpha.124 (2026-08-27)
+
+* feat(spec)!: reflect the command direction across a port, both halves ([f2fe258](https://github.com/ReventlessDev/reventless-core/commit/f2fe258d195b74f4a61488edee305665341020ea))
+* feat(spec)!: read the port's translation table off the mapping's arms ([956348a](https://github.com/ReventlessDev/reventless-core/commit/956348a9fcb256cfff9db51809bdc27d73360e6c))
+* feat(spec)!: keep the amount in minor units, and add times and allocate ([6ff6308](https://github.com/ReventlessDev/reventless-core/commit/6ff630875f9b126b2f87b980a4dbb56582f8aebe))
+* feat(spec)!: hold a money amount in the currency's own units ([94d3bba](https://github.com/ReventlessDev/reventless-core/commit/94d3bbaf0c47a639c20de6847c4615070ad51b38))
+
+### BREAKING CHANGES
+
+* `ExtensionPointMapping.Mapping` gains `acceptedCommands` and
+`ExtensionMapping.Mapping` gains `issuedCommands`; both are derived, so a
+mapping the ppx can read needs no source change, and one it cannot names itself
+at compile time. Definitions persisted before the two new def fields must be
+re-emitted before a consumer can read them as present — and until then they
+decode as None, which means unknown, not "issues nothing".
+* `ExtensionPointMapping.Mapping` requires `publishedEvents` and
+`ExtensionMapping.Mapping` requires `handledEvents`; the ppx injects both for
+mappings it can read, so app code must build against the matching ppx. Plugin
+definitions persisted before the new fields must be re-emitted before a consumer
+reads them as present.
+* reverts the wire shape to whole minor units, so a log written
+against the intervening commit reads a hundredfold low. Nothing released carried
+the decimal form.
+* stored amounts do not migrate. A log written before this holds
+minor units and now decodes a hundredfold high, cleanly and without complaint —
+a log that has to survive needs an upcaster written before this is deployed, and
+a demo log needs discarding and reseeding. A stored currency outside the ten no
+longer decodes; admit it in the generator or migrate the data.
+
+
+
 # 3.0.0-alpha.123 (2026-08-23)
 
 ### Features

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.123",
+  "version": "3.0.0-alpha.125",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
     "generate-plugin": "./run-generator.mjs",
-    "generate-platform": "./run-platform-generator.mjs"
+    "generate-platform": "./run-platform-generator.mjs",
+    "graft-trait": "./run-graft-trait.mjs",
+    "certify-trait": "./run-certify-trait.mjs",
+    "trait-manifest": "./run-trait-manifest.mjs"
   },
   "jest": {
     "testMatch": [
@@ -42,7 +45,6 @@
     "build": "rescript build",
     "start": "rescript start",
     "clean": "rescript clean",
-    "generate:currency": "node ./scripts/generate-currency.mjs",
     "test": "NODE_OPTIONS='--experimental-vm-modules' jest",
     "dev": "NODE_OPTIONS='--experimental-vm-modules' jest --watchAll"
   }

package/run-certify-trait.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./src/generator/CertifyTrait.res.mjs"

package/run-graft-trait.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./src/generator/GraftTrait.res.mjs"

package/run-trait-manifest.mjs

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+import "./src/generator/TraitManifestCli.res.mjs"

package/schema/platform-api.graphql

@@ -18,9 +18,9 @@ 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_Plugin_Activate(id: ID!, version: String!): CommandResult!
+  Platform_Plugin_Deactivate(id: ID!, version: String!): CommandResult!
+  Platform_Plugin_Retire(id: ID!, version: String!): CommandResult!
   Platform_UIFragmentDeregistered(pluginId: ID!): UIFragmentChangeEvent
   Platform_UIFragmentRegistered(manifest: String, pluginId: ID!): UIFragmentChangeEvent
   Platform_UIFragmentUpdated(manifest: String, pluginId: ID!): UIFragmentChangeEvent
@@ -37,6 +37,11 @@ type PageInfo {
   startCursor: String
 }
 
+type Platform_AcceptedCommandDef {
+  name: String!
+  toCommandTypes: [String!]!
+}
+
 type Platform_AutomationSliceDef {
   chapter: String
   consumedEventTypes: [String!]!
@@ -88,13 +93,17 @@ type Platform_ExtensionDef {
   commandTypes: [String!]!
   delegateNames: [String!]!
   eventTypes: [String!]!
+  handledEvents: [Platform_HandledEventDef!]
+  issuedCommands: [Platform_IssuedCommandDef!]
   name: String!
 }
 
 type Platform_ExtensionPointDef {
+  acceptedCommands: [Platform_AcceptedCommandDef!]
   commandTypes: [String!]
   delegateNames: [String!]!
   name: String!
+  publishedEvents: [Platform_PublishedEventDef!]
   sourceEventTypes: [String!]!
 }
 
@@ -104,6 +113,11 @@ type Platform_FieldReference {
   plugin: String
 }
 
+type Platform_HandledEventDef {
+  name: String!
+  toCommandTypes: [String!]!
+}
+
 type Platform_InboundTranslationSliceDef {
   chapter: String
   commandTypes: [String!]!
@@ -112,6 +126,11 @@ type Platform_InboundTranslationSliceDef {
   targetName: String
 }
 
+type Platform_IssuedCommandDef {
+  fromEventTypes: [String!]!
+  name: String!
+}
+
 type Platform_OutboundTranslationSliceDef {
   chapter: String
   consumedEventTypes: [String!]!
@@ -206,10 +225,17 @@ type Platform_PluginStructureEntry {
   outboundTranslationSlices: [Platform_OutboundTranslationSliceDef!]!
   pluginId: String!
   readModels: [Platform_ReadSideDef!]!
+  requiredCapabilities: [Platform_RequiredCapabilityDeclaration!]
   requiredStoreDeclarations: [Platform_RequiredStoreDeclaration!]
   requiredStores: [String!]
   stateChangeSlices: [Platform_WriteSideDef!]!
   stateViewSlices: [Platform_ReadSideDef!]!
+  traitDeclarations: [Platform_TraitDeclaration!]
+}
+
+type Platform_PublishedEventDef {
+  fromEventTypes: [String!]!
+  name: String!
 }
 
 type Platform_ReadSideDef {
@@ -234,6 +260,11 @@ type Platform_ReadSideDef {
   visibility: String
 }
 
+type Platform_RequiredCapabilityDeclaration {
+  capability: String!
+  component: String!
+}
+
 type Platform_RequiredStoreDeclaration {
   annotation: String
   component: String!
@@ -241,6 +272,13 @@ type Platform_RequiredStoreDeclaration {
   store: String!
 }
 
+type Platform_TraitDeclaration {
+  component: String!
+  posture: String!
+  trait: String!
+  version: String!
+}
+
 type Platform_UIFragmentEntry {
   pages: [Platform_UIPage!]!
   panels: [Platform_UIPanel!]!

package/src/components/Aggregate.res

@@ -61,4 +61,26 @@ module type Spec = {
       `AllowAuthenticated`; override at the file/module level with
       `@@reventless.authorize(<rule>)`. */
   let commandAuthorization: command => Authorization.permission
+
+  /** The lifecycle enum this component's commands move a row through — the
+      linked view's own, e.g. `type lifecycleState = Customers.accountStatus`.
+      Auto-injected as `unit` alongside the default below; a host that declares
+      `commandTransition` declares this too, and the pair is what makes every
+      edge name one lifecycle. */
+  type lifecycleState
+
+  /** The lifecycle edge each command owns, read while the plugin structure is
+      assembled. Auto-injected as `_ => Unrestricted` by `@@reventless.spec`,
+      which leaves `@transition` in charge; a host that writes the switch by
+      hand takes charge instead, and gets an exhaustive one over typed states.
+      See `Transition`. */
+  let commandTransition: command => Transition.t<lifecycleState>
+
+  /** The domain traits grafted into this component, as values the trait packages
+      export — `[TraitAttachments.Attachments.declaration]`. Auto-injected as `[]`
+      by `@@reventless.spec`, so a component that is nobody's graft says so without
+      a line. A graft names its trait here and the structure records it, which is
+      the only way a deployed plugin can answer "where did this come from". See
+      `Trait`. */
+  let traits: array<Trait.t>
 }

package/src/components/AutomationSlice.res

@@ -83,6 +83,16 @@ module type Spec = {
 // validation step run before each command publish. `process` remains shared in
 // the slice's `Automation` module since it operates on `todoItem` regardless of
 // the originating source.
+//
+// `collect` is handed `~sourceId` alongside the event, so a mapping over an
+// Aggregate source can key its todo item even though the payload does not repeat
+// the id that addressed it — `Registered({email, address})` is the case this
+// exists for. A DCB event usually names its own subject and can ignore it.
+//
+// An `OutboundTranslationSlice` remains the better shape for a relay that simply
+// forwards: its item completes when the command is published rather than when an
+// answering event arrives, so the target command is free to be idempotent instead
+// of having to emit a fact whose only job is closing the row.
 
 /**
 Ambient deployment context plumbed to every mapping function.
@@ -125,7 +135,15 @@ module type Mapping = {
   type command
   let sourceEventSchema: S.t<sourceEvent>
   let sourceName: string
-  let collect: (sourceEvent, context) => array<(string, todoItem)>
+  /**
+  `~sourceId` is the id of the entity the event was published for — the
+  envelope's `id`, not part of the event payload. A DCB event usually names its
+  own subject (`OrderPlaced({orderId, …})`) and can ignore this; an Aggregate's
+  event generally does not, because the aggregate id is what addressed it in the
+  first place. Without it a mapping over `Registered({email, address})` would
+  have no way to say which customer its todo item is for.
+  */
+  let collect: (sourceEvent, ~sourceId: string, context) => array<(string, todoItem)>
   let resolve: sourceEvent => option<string>
 }
 
@@ -199,7 +217,15 @@ module type MappingImpl = {
   type sourceEvent
   type todoItem
   type command
-  let collect: (sourceEvent, context) => array<(string, todoItem)>
+  /**
+  `~sourceId` is the id of the entity the event was published for — the
+  envelope's `id`, not part of the event payload. A DCB event usually names its
+  own subject (`OrderPlaced({orderId, …})`) and can ignore this; an Aggregate's
+  event generally does not, because the aggregate id is what addressed it in the
+  first place. Without it a mapping over `Registered({email, address})` would
+  have no way to say which customer its todo item is for.
+  */
+  let collect: (sourceEvent, ~sourceId: string, context) => array<(string, todoItem)>
   let resolve: sourceEvent => option<string>
 }
 
@@ -242,7 +268,7 @@ module FromOrderShipped = Reventless.AutomationSlice.Mapping.Make(
   OrderSpec,                    // Source: Aggregate spec module
   AutoFulfillmentSpec,          // Target: this slice's spec
   {
-    let collect = (event, _ctx) =>
+    let collect = (event, ~sourceId as _, _ctx) =>
       switch event {
       | OrderSpec.OrderShipped({orderId, productId}) =>
         [(orderId ++ ":" ++ productId, {AutoFulfillmentSpec.orderId, productId})]

package/src/components/CapabilityManifest.res

@@ -2,29 +2,38 @@
 The per-plugin capability manifest — `capabilities.json`, written beside the
 generated `Plugin.res` by the plugin package's build.
 
-Each entry states one capability the plugin's fields declare they need, keyed
-by the store's qualified `{plugin}.{store}` identity, with the declaring
-`(component, field)` sites as provenance. The keys are taken verbatim from
-`pluginStructure.requiredStores` — the manifest is a rendering of the
-structure, never a second scan of the sources, so the two cannot spell one
-fact differently.
+Each entry states one capability the plugin declares it needs, keyed by that
+capability's identity — the qualified `{plugin}.{store}` for an object store, the
+capability's own name for everything else — with the declaring sites as
+provenance. The keys are taken verbatim from `pluginStructure`: the manifest is a
+rendering of the structure, never a second scan of the sources, so the two cannot
+spell one fact differently.
 
 The platform generator unions these files across a deployment's plugins and
 emits the platform's capability list from them.
 */
 
 @schema
-type kind = ObjectStore
+type kind =
+  | ObjectStore
+  /** Address geocoding, reached through `Capabilities.geocode`. Declared by a
+      slice rather than by a field, so its entry carries no `field`. */
+  | Geocoding
+  /** Sending a message, reached through `Capabilities.messaging`. Slice-declared
+      like `Geocoding`, and for the same reason carries no `field`. */
+  | Messaging
 
-/** The declaration site: the component's spec name and the field carrying the
-    `@storageRef` annotation, plus the store exactly as that field spells it.
+/** The declaration site: the component's spec name, and — for a store — the field
+    carrying the `@storageRef` annotation plus the store exactly as that field
+    spells it.
 
-    `annotation` is optional only to keep reading a manifest emitted before it
-    existed: a plugin built earlier still parses, and a reader that cannot say
-    what the source says omits the claim rather than inventing one. Every
-    manifest emitted now carries it. */
+    `field` and `annotation` are optional. `annotation` because a manifest emitted
+    before it existed must still parse, and a reader that cannot say what the
+    source says omits the claim rather than inventing one; `field` because a
+    capability a slice declares has no declaring field, and naming one would be a
+    fiction. Every store entry emitted now carries both. */
 @schema
-type provenance = {component: string, field: string, annotation?: string}
+type provenance = {component: string, field?: string, annotation?: string}
 
 @schema
 type entry = {
@@ -39,17 +48,18 @@ type t = {capabilities: array<entry>}
 /**
 Build the manifest from a plugin's structure.
 
-Keys iterate `requiredStores` itself, so a manifest's key set is byte-identical
-to what the deployed plugin reports at runtime — the contract the deploy-time
-coverage assertion checks against. A structure with no declarations yields an
-empty `capabilities` list, not an absent file: "declares nothing" is a
-statement, and the generator reading the manifests must be able to tell it
-apart from "was never built".
+Store keys iterate `requiredStores` itself, so a manifest's key set is
+byte-identical to what the deployed plugin reports at runtime — the contract the
+deploy-time coverage assertion checks against. Capability entries follow, one per
+distinct capability, ordered by name so the file does not churn. A structure with
+no declarations yields an empty `capabilities` list, not an absent file:
+"declares nothing" is a statement, and the generator reading the manifests must
+be able to tell it apart from "was never built".
 */
 let fromStructure = (structure: Plugin.pluginStructure): t => {
   let declarations = structure.requiredStoreDeclarations->Option.getOr([])
-  {
-    capabilities: structure.requiredStores
+  let stores =
+    structure.requiredStores
     ->Option.getOr([])
     ->Array.map(key => {
       kind: ObjectStore,
@@ -59,8 +69,26 @@ let fromStructure = (structure: Plugin.pluginStructure): t => {
           ? Some({component: d.component, field: d.field, annotation: ?d.annotation})
           : None
       ),
-    }),
-  }
+    })
+  let needs = structure.requiredCapabilities->Option.getOr([])
+  let capabilityKeys =
+    needs->Array.map(d => d.capability)->Belt.Set.String.fromArray->Belt.Set.String.toArray
+  let capabilities = capabilityKeys->Array.filterMap(key =>
+    // An unrecognised capability is dropped rather than passed through: the
+    // generator downstream renders a real `Platform.capability` arm, and a name
+    // this build cannot map has no arm to render.
+    CapabilityNeed.fromString(key)->Option.map(need => {
+      kind: switch need {
+      | Geocoding => Geocoding
+      | Messaging => Messaging
+      },
+      key,
+      declaredBy: needs->Array.filterMap(d =>
+        d.capability == key ? Some({component: d.component}) : None
+      ),
+    })
+  )
+  {capabilities: Array.concat(stores, capabilities)}
 }
 
 /** Deterministic rendering: 2-space indent, trailing newline. Rebuilding with

package/src/components/CapabilityManifest.res.mjs

@@ -3,13 +3,19 @@
 import * as Sury from "sury";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Belt_SetString from "@rescript/runtime/lib/es6/Belt_SetString.js";
 import * as Util_Sury$Reventless from "../util/Util_Sury.res.mjs";
+import * as CapabilityNeed$Reventless from "../semantic/CapabilityNeed.res.mjs";
 
-let kindSchema = Sury.literal("ObjectStore");
+let kindSchema = Sury.union([
+  Sury.literal("ObjectStore"),
+  Sury.literal("Geocoding"),
+  Sury.literal("Messaging")
+]);
 
 let provenanceSchema = Sury.$schema(s => ({
   component: s.m(Sury.string),
-  field: s.m(Sury.string),
+  field: s.m(Sury.$option(Sury.string)),
   annotation: s.m(Sury.$option(Sury.string))
 }));
 
@@ -25,20 +31,38 @@ let schema = Sury.$schema(s => ({
 
 function fromStructure(structure) {
   let declarations = Stdlib_Option.getOr(structure.requiredStoreDeclarations, []);
-  return {
-    capabilities: Stdlib_Option.getOr(structure.requiredStores, []).map(key => ({
-      kind: "ObjectStore",
+  let stores = Stdlib_Option.getOr(structure.requiredStores, []).map(key => ({
+    kind: "ObjectStore",
+    key: key,
+    declaredBy: Stdlib_Array.filterMap(declarations, d => {
+      if (d.store === key) {
+        return {
+          component: d.component,
+          field: d.field,
+          annotation: d.annotation
+        };
+      }
+    })
+  }));
+  let needs = Stdlib_Option.getOr(structure.requiredCapabilities, []);
+  let capabilityKeys = Belt_SetString.toArray(Belt_SetString.fromArray(needs.map(d => d.capability)));
+  let capabilities = Stdlib_Array.filterMap(capabilityKeys, key => Stdlib_Option.map(CapabilityNeed$Reventless.fromString(key), need => {
+    let tmp;
+    tmp = need === "Geocoding" ? "Geocoding" : "Messaging";
+    return {
+      kind: tmp,
       key: key,
-      declaredBy: Stdlib_Array.filterMap(declarations, d => {
-        if (d.store === key) {
+      declaredBy: Stdlib_Array.filterMap(needs, d => {
+        if (d.capability === key) {
           return {
-            component: d.component,
-            field: d.field,
-            annotation: d.annotation
+            component: d.component
           };
         }
       })
-    }))
+    };
+  }));
+  return {
+    capabilities: stores.concat(capabilities)
   };
 }
 

package/src/components/InboundTranslationSlice.res

@@ -62,6 +62,20 @@ module type Spec = {
       on structurally-detected inline spec modules — defaults to
       `AllowAuthenticated`. */
   let commandAuthorization: command => Authorization.permission
+
+  /** The lifecycle enum this component's commands move a row through — the
+      linked view's own, e.g. `type lifecycleState = Customers.accountStatus`.
+      Auto-injected as `unit` alongside the default below; a host that declares
+      `commandTransition` declares this too, and the pair is what makes every
+      edge name one lifecycle. */
+  type lifecycleState
+
+  /** The lifecycle edge each command owns, read while the plugin structure is
+      assembled. Auto-injected as `_ => Unrestricted` by `@@reventless.spec`,
+      which leaves `@transition` in charge; a host that writes the switch by
+      hand takes charge instead, and gets an exhaustive one over typed states.
+      See `Transition`. */
+  let commandTransition: command => Transition.t<lifecycleState>
 }
 
 /**

package/src/components/OutboundTranslationSlice.res

@@ -106,6 +106,30 @@ module type Spec = {
       in the Event Graph / Context Map.
       Auto-injected by `@@reventless.spec` defaulting to `None` — set it to name the box. */
   let externalSystem: option<string>
+
+  /**
+  The platform capabilities this slice's `translate` reaches for.
+
+  `[]` — the common case — means `translate` calls a service the framework does
+  not broker, and the deployment provisions nothing on its behalf. Naming a
+  capability makes the need a checked fact: it reaches `capabilities.json`, the
+  platform's generated capability list, and the deploy-time gate, which refuses a
+  plugin whose platform provisions none of it.
+
+  Declared rather than inferred because what `translate` reads off
+  `Capabilities.t` is only visible in its body, and provisioning infrastructure
+  from a guess at a function body is not a service. A trait exports the value for
+  its host to name, so grafting one cannot leave the need unstated.
+  */
+  let capabilityNeeds: array<CapabilityNeed.t>
+
+  /** The domain traits grafted into this component, as values the trait packages
+      export — `[TraitAttachments.Attachments.declaration]`. Auto-injected as `[]`
+      by `@@reventless.spec`, so a component that is nobody's graft says so without
+      a line. A graft names its trait here and the structure records it, which is
+      the only way a deployed plugin can answer "where did this come from". See
+      `Trait`. */
+  let traits: array<Trait.t>
 }
 
 /**