@reventlessdev/reventless-spec 3.0.0-alpha.124 → 3.0.0-alpha.126

package/CHANGELOG.md

@@ -3,6 +3,39 @@
 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.126 (2026-09-01)
+
+**Note:** Version bump only for package @reventlessdev/reventless-spec
+
+
+
+
+
+# 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))

package/package.json

@@ -1,11 +1,14 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.124",
+  "version": "3.0.0-alpha.126",
   "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": [

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
@@ -225,10 +225,12 @@ 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 {
@@ -258,6 +260,11 @@ type Platform_ReadSideDef {
   visibility: String
 }
 
+type Platform_RequiredCapabilityDeclaration {
+  capability: String!
+  component: String!
+}
+
 type Platform_RequiredStoreDeclaration {
   annotation: String
   component: String!
@@ -265,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,27 @@ 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`, so
+      a component whose commands guard nothing needs no line; a host that writes
+      the switch by hand gets an exhaustive one over typed states. Refused rather
+      than injected when the command type splices, since a spliced command must
+      be answered for. 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`,
+      so a component whose commands guard nothing needs no line; a host that
+      writes the switch by hand 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>
 }
 
 /**

package/src/components/Plugin.res

@@ -137,10 +137,10 @@ type commandDef = {
   aggregateIdField: @s.matches(stringOptionSchema) option<string>,
   mutationField: string,
   references: array<fieldReference>,
-  /** The `@transition` *from* set — lifecycle states this command is meaningful in.
+  /** 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 `@transition` *to* state this command's handler writes. `None` with a
+  /** 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>,
   /** Whether the variant is exposed in the generated API (non-`@noApi`). */
@@ -380,6 +380,47 @@ type requiredStoreDeclaration = {
 let requiredStoreDeclarationArrayOptionSchema =
   S.array(requiredStoreDeclarationSchema)->S.nullAsOption
 
+/**
+One component's capability requirement, with its provenance.
+
+`capability` is `CapabilityNeed.toString` — a string rather than an enum so a
+plugin built against a newer framework still decodes here; `component` names the
+slice that declared it, so a diff can say which component added or removed the
+need. Unlike a store there is no field: what a `translate` reaches for is not
+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.
+
+Strings rather than the `Trait.t` variant for `posture`, on the same rule the
+capability above follows — a plugin built against a newer framework, naming a
+posture this one has never heard of, still decodes here rather than failing the
+whole structure.
+
+`component` is not declared by the trait or by the host: the structure fills it in
+while it walks the components, because it is the only party that knows which one
+carried the declaration. Nothing in this record is a string a developer typed.
+
+It records ORIGIN, not behaviour — a grafted file is the host's to edit
+afterwards. What answers "does it still behave like the trait" is the trait's own
+conformance suite, which runs in the consumer's build and is not this field.
+*/
+@schema
+type traitDeclaration = {
+  trait: string,
+  version: string,
+  posture: string,
+  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
@@ -409,6 +450,18 @@ type pluginStructure = {
       `requiredStores` is derived from it, so the two cannot disagree. */
   requiredStoreDeclarations: @s.matches(requiredStoreDeclarationArrayOptionSchema)
   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>>,
+  /** 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>>,
 }
 
 let pluginStructureOffloadSchema = Offload.optionSchema(~store="pluginStructures", pluginStructureSchema)

package/src/components/Plugin.res.mjs

@@ -240,6 +240,22 @@ let requiredStoreDeclarationSchema = Sury.$schema(s => ({
 
 let requiredStoreDeclarationArrayOptionSchema = Sury.$nullAsOption(Sury.array(requiredStoreDeclarationSchema));
 
+let requiredCapabilityDeclarationSchema = Sury.$schema(s => ({
+  capability: s.m(Sury.string),
+  component: s.m(Sury.string)
+}));
+
+let requiredCapabilityDeclarationArrayOptionSchema = Sury.$nullAsOption(Sury.array(requiredCapabilityDeclarationSchema));
+
+let traitDeclarationSchema = Sury.$schema(s => ({
+  trait: s.m(Sury.string),
+  version: s.m(Sury.string),
+  posture: s.m(Sury.string),
+  component: s.m(Sury.string)
+}));
+
+let traitDeclarationArrayOptionSchema = Sury.$nullAsOption(Sury.array(traitDeclarationSchema));
+
 let pluginStructureSchema = Sury.$schema(s => ({
   readModels: s.m(Sury.array(queryableDefSchema)),
   stateViewSlices: s.m(Sury.array(queryableDefSchema)),
@@ -251,7 +267,9 @@ let pluginStructureSchema = Sury.$schema(s => ({
   extensions: s.m(Sury.array(extensionDefSchema)),
   extensionPoints: s.m(extensionPointDefArrayOptionSchema),
   requiredStores: s.m(stringArrayOptionSchema),
-  requiredStoreDeclarations: s.m(requiredStoreDeclarationArrayOptionSchema)
+  requiredStoreDeclarations: s.m(requiredStoreDeclarationArrayOptionSchema),
+  requiredCapabilities: s.m(requiredCapabilityDeclarationArrayOptionSchema),
+  traitDeclarations: s.m(traitDeclarationArrayOptionSchema)
 }));
 
 let pluginStructureOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginStructures", undefined, pluginStructureSchema);
@@ -314,6 +332,10 @@ export {
   extensionPointDefArrayOptionSchema,
   requiredStoreDeclarationSchema,
   requiredStoreDeclarationArrayOptionSchema,
+  requiredCapabilityDeclarationSchema,
+  requiredCapabilityDeclarationArrayOptionSchema,
+  traitDeclarationSchema,
+  traitDeclarationArrayOptionSchema,
   pluginStructureSchema,
   pluginStructureOffloadSchema,
   pluginDefinitionSchema,

package/src/components/StateAnnotations.res

@@ -54,7 +54,7 @@ otherwise see the same negative marker on every record they can read.
   two-valued enum.
 - `Some(v)` — the **state** form. The row is retired when the field equals `v`,
   and the field is the record's `@lifecycle` field. One field then carries the
-  fact once instead of twice, and `@transition(([Deactivated]) => Active)` on the
+  fact once instead of twice, and `Moves([Deactivated], Active)` on the
   way-back command is enough to make a generated menu offer it there and nowhere
   else —
   because retirement is finally expressible in the vocabulary that stance is
@@ -158,7 +158,7 @@ type stateAnnotationSpec = {
   metric: array<(string, metricSpec)>,
   /**
   Field annotated `@lifecycle` on the state record (PPX-emitted) — the enum a
-  command's `@transition` is written in terms of, a board draws its columns
+  command's declared edge is written in terms of, a board draws its columns
   from and a state diagram renders. `Some(name)` when one such annotation
   exists; the PPX errors on duplicate `@lifecycle` annotations within the same
   record. Codegen consumes this to populate `queryableDef.lifecycleField`, and

package/src/components/StateChangeSlice.res

@@ -85,6 +85,28 @@ module type Spec = {
       `@@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`,
+      so a component whose commands guard nothing needs no line; a host that
+      writes the switch by hand 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>
+
   /** Decision-read consistency mode for this slice's optimistic-concurrency
       retry loop. Auto-injected by `@@reventless.spec` and on
       structurally-detected inline spec modules — defaults to