@reventlessdev/reventless-infra 3.0.0-alpha.151 → 3.0.0-alpha.153

package/CHANGELOG.md

@@ -3,6 +3,44 @@
 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.153 (2026-09-01)
+
+### Bug Fixes
+
+* **api:** [@no](https://github.com/no)Api was lost when a command variant was spliced into another type ([00403fb](https://github.com/ReventlessDev/reventless-core/commit/00403fb4b8873a68a69558829e598339a5012833))
+* **capabilities:** a plugin's geocoding need was declared nowhere and failed silently ([67917dd](https://github.com/ReventlessDev/reventless-core/commit/67917dd504b43fa78b7c6a51644c9eae656b7f6b))
+### Features
+
+* **capabilities:** a plugin can send a message without naming a provider ([b001a1e](https://github.com/ReventlessDev/reventless-core/commit/b001a1e9361a0f4d0affe228cb4c08c38a5a995e))
+* **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))
+
+
+# 3.0.0-alpha.152 (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)!: drop the plugin protocol's reconnect event, which nothing published ([7549db6](https://github.com/ReventlessDev/reventless-core/commit/7549db6aac6ad3f94dbb8d72dac4b4e783756ad1))
+* feat(spec)!: read the port's translation table off the mapping's arms ([956348a](https://github.com/ReventlessDev/reventless-core/commit/956348a9fcb256cfff9db51809bdc27d73360e6c))
+
+### 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".
+* `PluginExtensionPointSpec.event` no longer declares
+`PluginReconnected`. An extension matching on it was matching an event it could
+never receive; drop the arm.
+* `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.
+
+
+
 # 3.0.0-alpha.151 (2026-08-23)
 
 **Note:** Version bump only for package @reventlessdev/reventless-infra

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-infra",
-  "version": "3.0.0-alpha.151",
+  "version": "3.0.0-alpha.153",
   "description": "Infrastructure types for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -17,9 +17,9 @@
     "sury-ppx": "11.0.0-rc.2",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.123",
-    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.125",
+    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/components/Api.res

@@ -7,6 +7,18 @@ let noApiId: S.Metadata.Id.t<bool> = S.Metadata.Id.make(~namespace="api", ~name=
 let noApiVariantsId: S.Metadata.Id.t<Set.t<string>> =
   S.Metadata.Id.make(~namespace="api", ~name="noApiVariants")
 
+/** The same exclusion, carried by the excluded *member* rather than by the union
+    it sits in — so it survives a variant spread.
+
+    A spread splices members: the generated code concatenates the source union's
+    `anyOf` into the target's. Metadata on the source *union* is not part of that,
+    so an exclusion recorded only there vanishes on the way into the host, and the
+    host publishes a command its author marked internal. A mark on the member
+    travels, because the member is what is spliced — the host's union holds the
+    same schema object. */
+let noApiVariantId: S.Metadata.Id.t<bool> =
+  S.Metadata.Id.make(~namespace="api", ~name="noApiVariant")
+
 /** Internal sury metadata ID storing per-variant allowed-state lists for AutoUI command filtering.
     Maps variant name → set of status values under which the command is meaningful. */
 let allowedStatesId: S.Metadata.Id.t<dict<array<string>>> =
@@ -21,9 +33,60 @@ let targetStateId: S.Metadata.Id.t<dict<string>> =
 let markNoApi = (schema: S.t<'a>): S.t<'a> =>
   schema->S.Metadata.set(~id=noApiId, true)
 
-/** PPX helper: attaches variant-level exclusions to a command schema. Called by generated code. */
-let markNoApiVariants = (schema: S.t<'a>, variants: array<string>): S.t<'a> =>
-  schema->S.Metadata.set(~id=noApiVariantsId, Set.fromArray(variants))
+/** The constructor a union member stands for: the `TAG` literal of a
+    payload-bearing variant, or the bare literal a payload-less one compiles to. */
+let variantNameOf = (member: S.t<unknown>): option<string> =>
+  switch member {
+  | Object({properties}) =>
+    properties
+    ->Dict.get("TAG")
+    ->Option.flatMap(tag =>
+      switch tag {
+      | String({const: ?Some(name)}) => Some(name)
+      | _ => None
+      }
+    )
+  | String({const: ?Some(name)}) => Some(name)
+  | _ => None
+  }
+
+/**
+PPX helper: attaches variant-level exclusions to a command schema. Called by
+generated code.
+
+Recorded twice, on purpose. The set on the union is what every reader has always
+consulted; the per-member mark is what survives being spliced into another type.
+Writing only the second would break any reader holding a union whose members it
+did not build, and writing only the first is the defect this exists to close.
+
+The union is rebuilt from the marked members because sury metadata is immutable —
+setting it returns a new schema, so the members the original union holds would
+otherwise still be the unmarked ones. Sound here because the PPX calls this
+*first*, directly on the freshly built union, before any other metadata is
+attached: there is nothing on the parent yet to lose. A schema that is not a
+union, or that names no excluded variant, is left structurally untouched.
+*/
+let markNoApiVariants = (schema: S.t<'a>, variants: array<string>): S.t<'a> => {
+  let excluded = Set.fromArray(variants)
+  let marked = switch (variants, schema->S.castToUnknown) {
+  | ([], _) => schema
+  | (_, AnyOf({anyOf})) =>
+    anyOf
+    ->Array.map(member =>
+      switch variantNameOf(member) {
+      | Some(name) if excluded->Set.has(name) => member->S.Metadata.set(~id=noApiVariantId, true)
+      | _ => member
+      }
+    )
+    ->S.union
+    // The rebuilt union describes the same values as the one handed in — same
+    // members, same order, only metadata added. `S.union` cannot express that in
+    // the type, so the equivalence is carried here rather than by the compiler.
+    ->(Obj.magic: S.t<unknown> => S.t<'a>)
+  | (_, _) => schema
+  }
+  marked->S.Metadata.set(~id=noApiVariantsId, excluded)
+}
 
 /** PPX helper: attaches per-variant allowedStates to a command schema. Called by generated code
     emitted from the from-set of an @transition attribute. Each entry is (variantName, allowedStateNames). */

package/src/components/Api.res.mjs

@@ -1,11 +1,14 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Sury from "sury";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 
 let noApiId = Sury.$Metadata_Id_make("api", "noApi");
 
 let noApiVariantsId = Sury.$Metadata_Id_make("api", "noApiVariants");
 
+let noApiVariantId = Sury.$Metadata_Id_make("api", "noApiVariant");
+
 let allowedStatesId = Sury.$Metadata_Id_make("api", "allowedStates");
 
 let targetStateId = Sury.$Metadata_Id_make("api", "targetState");
@@ -14,8 +17,41 @@ function markNoApi(schema) {
   return Sury.$Metadata_set(schema, noApiId, true);
 }
 
+function variantNameOf(member) {
+  switch (member.type) {
+    case "string" :
+      let name = member.const;
+      if (name !== undefined) {
+        return name;
+      } else {
+        return;
+      }
+    case "object" :
+      return Stdlib_Option.flatMap(member.properties["TAG"], tag => {
+        if (tag.type !== "string") {
+          return;
+        }
+        let name = tag.const;
+        if (name !== undefined) {
+          return name;
+        }
+      });
+    default:
+      return;
+  }
+}
+
 function markNoApiVariants(schema, variants) {
-  return Sury.$Metadata_set(schema, noApiVariantsId, new Set(variants));
+  let excluded = new Set(variants);
+  let marked = variants.length !== 0 && schema.type === "anyOf" ? Sury.union(schema.anyOf.map(member => {
+      let name = variantNameOf(member);
+      if (name !== undefined && excluded.has(name)) {
+        return Sury.$Metadata_set(member, noApiVariantId, true);
+      } else {
+        return member;
+      }
+    })) : schema;
+  return Sury.$Metadata_set(marked, noApiVariantsId, excluded);
 }
 
 function markAllowedStates(schema, entries) {
@@ -29,9 +65,11 @@ function markTargetState(schema, entries) {
 export {
   noApiId,
   noApiVariantsId,
+  noApiVariantId,
   allowedStatesId,
   targetStateId,
   markNoApi,
+  variantNameOf,
   markNoApiVariants,
   markAllowedStates,
   markTargetState,

package/src/types/ExtensionMapping.res

@@ -1,8 +1,5 @@
-/**
-A pre-serialized command routed to a foreign extension point.
-Used when an extension needs to dispatch to an extension point it does not
-own — the command JSON is forwarded opaquely without re-encoding.
-*/
+/** A command routed to an extension point this extension does not own —
+    forwarded opaquely, without re-encoding. */
 type forwardCommand = {
   extensionPointName: string,
   id: string,
@@ -11,18 +8,9 @@ type forwardCommand = {
 
 type id = string
 
-/**
-Actions returned by an extension's `mapIncomingEvent` function.
-
-When an extension point emits an event, the extension's mapping can:
-- publish a command to the aggregate it wraps (`PublishAggregateCommand`)
-- publish a command to the StateChangeSlice it wraps (`PublishStateChangeSliceCommand`)
-  — no id argument; the framework derives the FIFO grouping id from the command's
-  `@partitionTag` (or `@compositePartitionTag`) field.
-- publish a command back to the extension point (`PublishExtensionPointCommand`)
-- forward a command to another extension point opaquely (`ForwardCommand`)
-- handle an extension-point-defined directive via an async handler (`HandleDirective`)
-*/
+/** What `mapIncomingEvent` can do with a published event: command the wrapped
+    aggregate or slice, command the extension point, forward, or run a directive.
+    The slice forms take no id — the FIFO group comes from `@partitionTag`. */
 type incomingCommandAction<'aggregateCommand, 'extensionPointCommand, 'directive> =
   | PublishAggregateCommand(id, 'aggregateCommand)
   | PublishAggregateCommandAsync(promise<(id, 'aggregateCommand)>)
@@ -34,26 +22,14 @@ type incomingCommandAction<'aggregateCommand, 'extensionPointCommand, 'directive
   | ForwardCommand(forwardCommand)
   | HandleDirective(Reventless.Handler.handler<'directive>, 'directive)
 
-/**
-Actions returned by an extension's `mapOutgoingEvent` function.
-
-When the wrapped aggregate emits an event, the extension can:
-- publish a command to the extension point (`PublishExtensionPointCommand`)
-- forward a command to another extension point opaquely (`ForwardCommand`)
-- handle an extension-point-defined directive via an async handler (`HandleDirective`)
-*/
+/** What `mapOutgoingEvent` can do with a delegate event: command the extension
+    point, forward, or run a directive. */
 type outgoingCommandAction<'extensionPointCommand, 'directive> =
   | PublishExtensionPointCommand(id, 'extensionPointCommand)
   | ForwardCommand(forwardCommand)
   | HandleDirective(Reventless.Handler.handler<'directive>, 'directive)
 
-/**
-Maps an extension point event to actions on the wrapped aggregate or extension point.
-
-Called when the extension point emits an event that this extension handles.
-Receives the entity ID, the event, message metadata, the plugin definition,
-and the query engine.
-*/
+/** Maps a published event to actions on the wrapped delegate or the extension point. */
 type mapIncomingEvent<
   'extensionPointEvent,
   'aggregateCommand,
@@ -69,12 +45,8 @@ type mapIncomingEvent<
   incomingCommandAction<'aggregateCommand, 'extensionPointCommand, 'extensionPointDirective>,
 >
 
-/**
-Maps an aggregate event to actions on the extension point.
-
-Optionally defined — return `None` if the aggregate's outgoing events do not
-need to be reflected back through the extension point.
-*/
+/** Maps a delegate event back to actions on the extension point. `None` when
+    nothing flows back. */
 type mapOutgoingEvent<'aggregateEvent, 'extensionPointCommand, 'extensionPointDirective> = (
   string,
   'aggregateEvent,
@@ -82,11 +54,8 @@ type mapOutgoingEvent<'aggregateEvent, 'extensionPointCommand, 'extensionPointDi
   Reventless.Plugin.pluginDefinition,
 ) => array<outgoingCommandAction<'extensionPointCommand, 'extensionPointDirective>>
 
-/**
-The extension point protocol that this `Extension` connects to.
-Mirrors `ExtensionPoint.Spec` so the extension can be type-checked
-against the extension point's command / event / directive types.
-*/
+/** The extension point protocol this `Extension` connects to — mirrors
+    `ExtensionPoint.Spec` so the mapping type-checks against it. */
 module type Spec = {
   let name: string
   let moduleUrl: string
@@ -99,30 +68,35 @@ module type Spec = {
   type directive
 }
 
-/**
-Application-level implementation of an extension's bidirectional mapping.
+/** One published event this extension handles and the commands it routes to —
+    the subscriber's half of `ExtensionPointMapping.publishedEvent`. Bare names,
+    resolved against the `Delegate`'s commands first, the EP's second. */
+type handledEvent = {
+  name: string,
+  toCommandTypes: array<string>,
+}
 
-- `ExtensionPoint` — the extension point protocol this extension connects to
-- `Delegate` — the component this extension delegates to (aggregate or DCB slice)
-- `mapIncomingEvent` — routes extension point events to delegate commands
-- `mapOutgoingEvent` — optionally routes delegate events back to the EP
-*/
+/** One command this extension sends back to the port and the `Delegate` events
+    producing it — the subscriber's half of `ExtensionPointMapping.acceptedCommand`.
+    Read off `mapOutgoingEvent` only: an EP command published from an arm of
+    `mapIncomingEvent` is an event→command edge and stays in `handledEvent`. */
+type issuedCommand = {
+  name: string,
+  fromEventTypes: array<string>,
+}
+
+/** An extension's bidirectional mapping between one extension point and one
+    delegate (aggregate or DCB slice). */
 module type Mapping = {
   module ExtensionPoint: Spec
   module Delegate: Reventless.Aggregate.Spec
 
-  // npm-style specifier of the user extension file (the module exporting this
-  // Mapping). Used by Plugin_Helpers + the bundled Plugin EventCollector entry
-  // point to dynamic-import the user mapping for runtime reconstruction of
-  // mapIncomingEvent / mapOutgoingEvent. PPX-injected on @@reventless.extension
-  // files as the same specifier as the file-level moduleUrl.
+  // The extension file's own url — dynamic-imported at runtime to reconstruct the
+  // two mapping functions. Injected by `@@reventless.extension`.
   let moduleUrl: string
 
-  // npm-style specifier of the Delegate's source module. Used by the bundled
-  // Plugin EventCollector entry point to dynamic-import the Delegate spec at
-  // cold start (Mapping.ExtensionPoint and Mapping.Delegate are erased in the
-  // compiled .res.mjs export). PPX-injected on @@reventless.extension files
-  // as `Delegate.moduleUrl`.
+  // The Delegate's url — the EventCollector imports its spec at cold start, since
+  // the compiled export erases `Mapping.Delegate`.
   let delegateModuleUrl: string
 
   let mapIncomingEvent: mapIncomingEvent<
@@ -135,12 +109,18 @@ module type Mapping = {
   let mapOutgoingEvent: option<
     mapOutgoingEvent<Delegate.event, ExtensionPoint.command, ExtensionPoint.directive>,
   >
+
+  /** Which published event routes to which commands — see `handledEvent`. Derived
+      by the PPX from `mapIncomingEvent`'s arms; hand-written only where it says
+      it cannot read them. */
+  let handledEvents: array<handledEvent>
+
+  /** Which commands travel back to the port — see `issuedCommand`. Derived from
+      `mapOutgoingEvent`'s arms, under the same rule. */
+  let issuedCommands: array<issuedCommand>
 }
 
-/**
-A dummy target used when an extension does not wrap a real aggregate or slice.
-Satisfies `Aggregate.Spec` with unit command / event / error types.
-*/
+/** A stand-in for an extension that wraps no aggregate or slice. */
 module NoDelegate = {
   let name = "NoDelegate"
 
@@ -167,6 +147,9 @@ module NoDelegate = {
   let moduleUrl: string = %raw(`import.meta.url`)
   let commandAuthorization = (_: command): Reventless.Authorization.permission =>
     AllowAuthenticated
+  type lifecycleState = unit
+  let commandTransition = (_: command): Reventless.Transition.t<lifecycleState> => Unrestricted
+  let traits: array<Reventless.Trait.t> = []
 }
 
 
@@ -193,6 +176,14 @@ module type T = {
 
   let delegateName: string
 
+  // All carried through the functor: `Plugin_Structure` sees an extension only
+  // compiled, and `T` erases the Delegate's types, so the checks against the two
+  // tables need its command and event names rather than its schemas.
+  let handledEvents: array<handledEvent>
+  let issuedCommands: array<issuedCommand>
+  let delegateCommandNames: array<string>
+  let delegateEventNames: array<string>
+
   let mapIncomingEvent: (
     Reventless.Message.event'<string, ExtensionPoint.event>,
     pluginDefinition,
@@ -217,21 +208,18 @@ module Make = (MappingImpl: Mapping): (
   module Delegate = MappingImpl.Delegate
   let delegateName = Delegate.name
   let extensionPointName = Spec.name
+  let handledEvents = MappingImpl.handledEvents
+  let issuedCommands = MappingImpl.issuedCommands
+  let delegateCommandNames = Reventless.DcbTag.extractAllVariantNames(Delegate.commandSchema)
 
-  // Variant TAGs the Delegate cares about — derived from the Delegate's event
-  // schema at functor instantiation. Used to pre-filter incoming envelopes:
-  // sibling variants on the source log (events the Delegate did not declare)
-  // are silently skipped without any decode attempt.
-  // extractAllVariantNames keeps payload-less variants (sury-compiled bare
-  // `S.literal("Name")` strings) — the JSON envelope's `event` TAG still
-  // carries the literal name, so the filter would otherwise drop them.
+  // Pre-filter for incoming envelopes: sibling variants the Delegate did not
+  // declare are skipped undecoded. Payload-less variants included — the
+  // envelope's `event` TAG still carries their name.
   let acceptedTags = Reventless.DcbTag.extractAllVariantNames(Delegate.eventSchema)
+  let delegateEventNames = acceptedTags
 
-  // Lazily-computed partition-tag derivation for `PublishStateChangeSliceCommand*`.
-  // Derived from the Delegate's command schema; throws if no `@partitionTag` /
-  // `@compositePartitionTag` annotation exists (i.e. the Delegate is an Aggregate,
-  // not a StateChangeSlice — in which case the user should use
-  // `PublishAggregateCommand` instead).
+  // Partition tag for `PublishStateChangeSliceCommand*`. Throws when the Delegate
+  // declares none — an Aggregate, where `PublishAggregateCommand` is the right form.
   let derivedPartitionTagLazy = ref(None)
   let getDerivedPartitionTag = () =>
     switch derivedPartitionTagLazy.contents {
@@ -253,10 +241,8 @@ module Make = (MappingImpl: Mapping): (
       Reventless.DcbTag.getCompositePartitionKeyValue(tags, spec)
     }
 
-  // Carry `comp` as a structured Effect log annotation — EffectLogger.install
-  // (in reventless-core, wired at Lambda startup) lifts it to the top-level
-  // JSON `comp` field. Without the unified logger installed, Effect's default
-  // logger still renders the annotation, just less prettily.
+  // `comp` as an Effect log annotation; EffectLogger.install lifts it to the
+  // top-level JSON field.
   let compLog = (comp, msg) =>
     Effect.logInfo(msg)->Effect.annotateLogs("comp", comp)->Effect.runSync
 
@@ -378,9 +364,7 @@ module Make = (MappingImpl: Mapping): (
 
   let doMapOutgoingEvent = (mapOutgoingEventImpl, targetEvent'Json, pluginDef) => {
     let tag = variantTagOfEnvelope(targetEvent'Json)
-    // Pre-filter by TAG: sibling variants from the source log that the Delegate
-    // did not declare are not this mapping's concern — skip silently with no
-    // decode attempt.
+    // Not this mapping's concern — skip without decoding.
     if !(acceptedTags->Array.includes(tag)) {
       []
     } else {

package/src/types/ExtensionMapping.res.mjs

@@ -32,6 +32,12 @@ function commandAuthorization() {
   return "AllowAuthenticated";
 }
 
+function commandTransition() {
+  return "Unrestricted";
+}
+
+let traits = [];
+
 let NoDelegate = {
   name: "NoDelegate",
   Id: Id,
@@ -39,7 +45,9 @@ let NoDelegate = {
   errorSchema: errorSchema,
   commandSchema: commandSchema,
   moduleUrl: moduleUrl,
-  commandAuthorization: commandAuthorization
+  commandAuthorization: commandAuthorization,
+  commandTransition: commandTransition,
+  traits: traits
 };
 
 function Make(MappingImpl) {
@@ -47,6 +55,7 @@ function Make(MappingImpl) {
   let Delegate = MappingImpl.Delegate;
   let delegateName = Delegate.name;
   let extensionPointName = Spec.name;
+  let delegateCommandNames = DcbTag$Reventless.extractAllVariantNames(Delegate.commandSchema);
   let acceptedTags = DcbTag$Reventless.extractAllVariantNames(Delegate.eventSchema);
   let derivedPartitionTagLazy = {
     contents: undefined
@@ -248,6 +257,10 @@ function Make(MappingImpl) {
   }));
   return {
     delegateName: delegateName,
+    handledEvents: MappingImpl.handledEvents,
+    issuedCommands: MappingImpl.issuedCommands,
+    delegateCommandNames: delegateCommandNames,
+    delegateEventNames: acceptedTags,
     mapIncomingEvent: mapIncomingEvent,
     mapOutgoingEvent: mapOutgoingEvent
   };

package/src/types/ExtensionPointMapping.res

@@ -1,10 +1,7 @@
 type extensionPointName = string
 
-/**
-An async handler for a typed extension-point directive. May call the scheduler
-or query engine as a side effect. Used as the handler argument in `HandleDirective`
-on both `commandAction` and `eventAction`.
-*/
+/** An async handler for a typed directive, used by `HandleDirective` on both
+    `commandAction` and `eventAction`. */
 type directiveHandler<'directive> = (
   Reventless.Schedule.create,
   Reventless.Schedule.delete,
@@ -12,37 +9,20 @@ type directiveHandler<'directive> = (
   'directive,
 ) => promise<unit>
 
-/**
-Actions returned by `mapIncomingCommand` — what to do when the extension point
-receives a command from an extension.
-
-- `PublishCommand(id, cmd)` — publish a command to the wrapped aggregate
-- `HandleDirective(handler, directive)` — invoke an async handler for an
-  extension-point-defined directive
-*/
-/* these actions are needed for Mapping */
+/** What `mapIncomingCommand` can do with a command an extension published:
+    publish one to the wrapped aggregate, or run a directive handler. */
 type commandAction<'command, 'directive> =
   | PublishCommand(string, 'command)
   | HandleDirective(directiveHandler<'directive>, 'directive)
 
-/**
-Actions returned by `mapOutgoingEvent` — what to do when the wrapped aggregate
-emits an event that should be reflected through the extension point.
-
-- `PublishEvent(id, event)` — synchronously emit an extension point event
-- `PublishEventAsync(promise)` — resolve a promise and emit the resulting event
-- `HandleDirective(handler, directive)` — invoke an async handler for an
-  extension-point-defined directive
-*/
+/** What `mapOutgoingEvent` can do with a Delegate event: publish an EP event,
+    publish one behind a promise, or run a directive handler. */
 type eventAction<'event, 'directive> =
   | PublishEvent(string, 'event)
   | PublishEventAsync(promise<(string, 'event)>)
   | HandleDirective(directiveHandler<'directive>, 'directive)
 
-/**
-The extension point protocol — defines the command, event, and directive types
-that extensions and aggregates exchange through this extension point.
-*/
+/** The extension point protocol: the command, event and directive types crossing it. */
 module type Spec = {
   let name: string
   let moduleUrl: string
@@ -55,26 +35,14 @@ module type Spec = {
   type directive
 }
 
-/**
-Maps an incoming extension point command to zero or more aggregate commands
-(or side-effect calls).
-
-Called when an extension publishes a command to this extension point.
-Receives the entity ID, the command, and the message metadata.
-*/
+/** Maps a command an extension published to zero or more aggregate commands. */
 type mapIncomingCommand<'extensionPointCommand, 'aggregateCommand, 'extensionPointDirective> = (
   string,
   'extensionPointCommand,
   Reventless.Message.meta,
 ) => array<commandAction<'aggregateCommand, 'extensionPointDirective>>
 
-/**
-Maps an aggregate outgoing event to zero or more extension point events
-(or side-effect calls).
-
-Called when the wrapped aggregate emits an event. Receives the entity ID,
-the event, message metadata, and the query engine.
-*/
+/** Maps an aggregate event to zero or more extension point events. */
 type mapOutgoingEvent<'aggregateEvent, 'extensionPointEvent, 'extensionPointDirective> = (
   string,
   'aggregateEvent,
@@ -82,22 +50,30 @@ type mapOutgoingEvent<'aggregateEvent, 'extensionPointEvent, 'extensionPointDire
   Reventless.QueryEngine.operations,
 ) => array<eventAction<'extensionPointEvent, 'extensionPointDirective>>
 
-/**
-Application-level implementation of the command / event mapping for one
-aggregate connected to an extension point.
+/** One published event of this port and the `Delegate` events producing it. Bare
+    constructor names, qualified downstream by `Plugin_Structure`. Per published
+    event, so many-to-one — the case a port exists for — reads naturally. */
+type publishedEvent = {
+  name: string,
+  fromEventTypes: array<string>,
+}
+
+/** The port's inbound half: one command this port takes and the `Delegate`
+    commands it routes to. Keyed by the arriving command, mirroring
+    `ExtensionMapping.handledEvent`. */
+type acceptedCommand = {
+  name: string,
+  toCommandTypes: array<string>,
+}
 
-Pass this to `ExtensionPointMapping.Make(Spec, Mapping)` to produce a compiled
-`ExtensionPointMapping.T` module.
-*/
+/** One aggregate's mapping to an extension point. Pass to
+    `ExtensionPointMapping.Make` for the compiled `T`. */
 module type Mapping = {
   module ExtensionPoint: Spec
   module Delegate: Reventless.Aggregate.Spec
 
-  // Module URL of the mapping file (e.g. catalog/src/ExtensionPoint/
-  // Products_ExtensionPointMapping.res.mjs). Distinct from ExtensionPoint.moduleUrl
-  // (the spec, in catalog-spec). Auto-injected by `@@reventless.spec` on
-  // ExtensionPointMapping files. The EventCollector runtime needs THIS url
-  // (not the spec's) to dynamic-import the mapping file's mapOutgoingEvent.
+  // The mapping file's own url, not the spec's — the EventCollector runtime
+  // dynamic-imports mapOutgoingEvent from it. Injected by `@@reventless.spec`.
   let moduleUrl: string
 
   let mapIncomingCommand: mapIncomingCommand<
@@ -109,10 +85,17 @@ module type Mapping = {
   let mapOutgoingEvent: option<
     mapOutgoingEvent<Delegate.event, ExtensionPoint.event, ExtensionPoint.directive>,
   >
+
+  /** The port's translation table — see `publishedEvent`. Derived by the PPX from
+      `mapOutgoingEvent`'s own arms; write it by hand only where it says it cannot. */
+  let publishedEvents: array<publishedEvent>
+
+  /** The same for the command direction — see `acceptedCommand`. Derived from
+      `mapIncomingCommand`'s arms, under the same rule. */
+  let acceptedCommands: array<acceptedCommand>
 }
 
-// Internal pre-compiled action types used by the ExtensionPoint runtime.
-// Created by ExtensionPointMapping.Make (in reventless); consumed by ExtensionPoint_Callback
+// Pre-compiled action types: made by Make, consumed by ExtensionPoint_Callback
 // and ExtensionPoint_Operations.
 
 /** Internal runtime action produced after pre-encoding a `commandAction`. Not for direct use. */
@@ -126,25 +109,15 @@ type abstractEventAction<'extensionPointEvent> =
   | AbstractPublishEventAsync(promise<(string, Reventless.Message.meta, JSON.t)>)
   | AbstractHandleDirective(unit => promise<unit>)
 
-/**
-A pre-compiled mapping module produced by `ExtensionPointMapping.Make(Spec, Mapping)`.
-
-The runtime uses `mapIncomingCommands` and `mapOutgoingEvent` to dispatch commands
-and events without knowing the concrete extension point or aggregate types.
-Application developers call `Make` themselves; the result satisfies this type.
-*/
-// Pre-compiled mapping module type. Created by ExtensionPointMapping.Make(Spec, Mapping).
-// App developers call Make themselves; the result satisfies this type.
+/** A compiled mapping, produced by `Make`. Lets the runtime dispatch without
+    knowing the concrete extension point or aggregate types. */
 module type T = {
   module ExtensionPoint: Spec
 
   /** Name of the target this mapping connects to the extension point. */
   let delegateName: string
 
-  /**
-  Converts a batch of typed extension point commands into pre-encoded abstract actions.
-  Called by the extension point runtime for each incoming command batch.
-  */
+  /** Pre-encodes a batch of typed EP commands for the runtime. */
   let mapIncomingCommands: (
     array<CommandTopic.topicItem<Reventless.Message.command'<Reventless.Id.String.t, ExtensionPoint.command>>>,
     Reventless.Schedule.create,
@@ -152,10 +125,7 @@ module type T = {
     Reventless.QueryEngine.operations,
   ) => array<abstractCommandAction>
 
-  /**
-  Converts a raw aggregate event JSON into pre-encoded abstract event actions.
-  `None` if this mapping does not produce outgoing extension point events.
-  */
+  /** Pre-encodes a raw aggregate event JSON. `None` if nothing is published out. */
   let mapOutgoingEvent: option<
     (
       JSON.t,
@@ -174,20 +144,13 @@ module Make = (MappingImpl: Mapping): (
   let delegateName = Delegate.name
   let extensionPointName = Spec.name
 
-  // Variant TAGs the Delegate cares about — derived from the Delegate's event
-  // schema at functor instantiation. Used to pre-filter incoming envelopes:
-  // sibling variants on the source log (events the Delegate did not declare)
-  // are silently skipped without any decode attempt.
-  // Pre-filter incoming envelopes against the Delegate's full constructor
-  // set — includes payload-less variants (e.g. UnknownPluginDetected
-  // compiled to `S.literal("…")`) since the JSON envelope's `event` TAG
-  // still carries the literal name even when the variant has no payload.
+  // Pre-filter for incoming envelopes: sibling variants the Delegate did not
+  // declare are skipped undecoded. Payload-less variants included — the
+  // envelope's `event` TAG still carries their name.
   let acceptedTags = Reventless.DcbTag.extractAllVariantNames(Delegate.eventSchema)
 
-  // Carry `comp` as a structured Effect log annotation — EffectLogger.install
-  // (in reventless-core, wired at Lambda startup) lifts it to the top-level
-  // JSON `comp` field. Without the unified logger installed, Effect's default
-  // logger still renders the annotation, just less prettily.
+  // `comp` as an Effect log annotation; EffectLogger.install lifts it to the
+  // top-level JSON field.
   let compLog = (comp, msg) =>
     Effect.logInfo(msg)->Effect.annotateLogs("comp", comp)->Effect.runSync
 
@@ -248,9 +211,7 @@ module Make = (MappingImpl: Mapping): (
     queryEngine,
   ) => {
     let tag = variantTagOfEnvelope(targetEventJson')
-    // Pre-filter by TAG: sibling variants from the source log that the Delegate
-    // did not declare are not this mapping's concern — skip silently with no
-    // decode attempt.
+    // Not this mapping's concern — skip without decoding.
     if !(acceptedTags->Array.includes(tag)) {
       []
     } else {

package/src/types/Platform.res

@@ -109,6 +109,7 @@ store, and reaching another plugin's store is the qualified form.
 type capability =
   | ObjectStore({plugin: string, store: string})
   | Geocoding
+  | Messaging
 
 // A provisioned geocoding place index, as returned by the framework's geocoding
 // capability helper. A record rather than a bare name so the handle can grow
@@ -181,6 +182,20 @@ type bakedManifest = {
 
 type geocoderIndex = {indexName: Pulumi.Input.t<string>}
 
+/**
+A provisioned messaging sender, as returned by the framework's messaging
+capability helper.
+
+`emailSender` is the verified address messages are sent *from* — a provider-side
+identity, not something an application picks per message, which is why it is a
+deploy-time handle rather than a field on `Messaging.message`. Absent when the
+deployment provisions no email channel.
+
+The channel set is derived from which senders are present rather than declared
+beside them, so a handle carrying no sender at all cannot claim a channel.
+*/
+type messagingSender = {emailSender?: Pulumi.Input.t<string>}
+
 // Options for the shell's map view mode. Written to config.json flat, beside
 // `viewModes`, because that is where the shell reads them; carried on the arm
 // here so a style set with the map off is unrepresentable.
@@ -426,6 +441,12 @@ module type T = {
     // on the platform API — and exports the index name for the unattended slice
     // path. Unset ⇒ no resolver, no export. In-memory platforms ignore this.
     geocoderPlaceIndex?: geocoderIndex,
+    // Optional messaging sender. When set, the deploy exports the verified
+    // sender address for the unattended slice path and grants those Lambdas the
+    // right to send from it. No client door — a browser has no business sending
+    // from the deployment's identity. Unset ⇒ no export, no grant. In-memory
+    // platforms ignore this.
+    messagingSender?: messagingSender,
     // Optional object store for direct-to-store uploads. When set, the deploy
     // provisions a presign service against it, threads that service's URL into
     // config.json as `uploadEndpoint`, and serves the store read-only from the

package/src/types/PluginExtensionPointSpec.res

@@ -37,8 +37,10 @@ type event =
   // Emitted when a connecting plugin declared incompatible protocol versions.
   // The plugin is still connected; this event gives operators visibility.
   | IncompatiblePlugin(pluginDefinition)
+  // One fact for both arrivals, because the Plugin aggregate has one: per-version
+  // tracking made `VersionConnected` replace Connected/Reconnected, and a
+  // subscriber does the same work either way.
   | PluginConnected(pluginDefinition)
-  | PluginReconnected(pluginDefinition)
   | PluginDisconnected(pluginDefinition)
   | PluginDeactivated(pluginDefinition)
   | PluginActivated(pluginDefinition)

package/src/types/PluginExtensionPointSpec.res.mjs

@@ -45,10 +45,6 @@ let eventSchema = Sury.union([
     TAG: "PluginConnected",
     _0: s.m(Plugin$Reventless.pluginDefinitionSchema)
   })),
-  Sury.$schema(s => ({
-    TAG: "PluginReconnected",
-    _0: s.m(Plugin$Reventless.pluginDefinitionSchema)
-  })),
   Sury.$schema(s => ({
     TAG: "PluginDisconnected",
     _0: s.m(Plugin$Reventless.pluginDefinitionSchema)
@@ -153,6 +149,22 @@ let outboundTranslationSliceDefSchema = Plugin$Reventless.outboundTranslationSli
 
 let inboundTranslationSliceDefSchema = Plugin$Reventless.inboundTranslationSliceDefSchema;
 
+let publishedEventDefSchema = Plugin$Reventless.publishedEventDefSchema;
+
+let publishedEventDefArrayOptionSchema = Plugin$Reventless.publishedEventDefArrayOptionSchema;
+
+let acceptedCommandDefSchema = Plugin$Reventless.acceptedCommandDefSchema;
+
+let acceptedCommandDefArrayOptionSchema = Plugin$Reventless.acceptedCommandDefArrayOptionSchema;
+
+let handledEventDefSchema = Plugin$Reventless.handledEventDefSchema;
+
+let handledEventDefArrayOptionSchema = Plugin$Reventless.handledEventDefArrayOptionSchema;
+
+let issuedCommandDefSchema = Plugin$Reventless.issuedCommandDefSchema;
+
+let issuedCommandDefArrayOptionSchema = Plugin$Reventless.issuedCommandDefArrayOptionSchema;
+
 let extensionDefSchema = Plugin$Reventless.extensionDefSchema;
 
 let extensionPointDefSchema = Plugin$Reventless.extensionPointDefSchema;
@@ -163,6 +175,14 @@ let requiredStoreDeclarationSchema = Plugin$Reventless.requiredStoreDeclarationS
 
 let requiredStoreDeclarationArrayOptionSchema = Plugin$Reventless.requiredStoreDeclarationArrayOptionSchema;
 
+let requiredCapabilityDeclarationSchema = Plugin$Reventless.requiredCapabilityDeclarationSchema;
+
+let requiredCapabilityDeclarationArrayOptionSchema = Plugin$Reventless.requiredCapabilityDeclarationArrayOptionSchema;
+
+let traitDeclarationSchema = Plugin$Reventless.traitDeclarationSchema;
+
+let traitDeclarationArrayOptionSchema = Plugin$Reventless.traitDeclarationArrayOptionSchema;
+
 let pluginStructureSchema = Plugin$Reventless.pluginStructureSchema;
 
 let pluginStructureOffloadSchema = Plugin$Reventless.pluginStructureOffloadSchema;
@@ -200,11 +220,23 @@ export {
   automationSliceDefSchema,
   outboundTranslationSliceDefSchema,
   inboundTranslationSliceDefSchema,
+  publishedEventDefSchema,
+  publishedEventDefArrayOptionSchema,
+  acceptedCommandDefSchema,
+  acceptedCommandDefArrayOptionSchema,
+  handledEventDefSchema,
+  handledEventDefArrayOptionSchema,
+  issuedCommandDefSchema,
+  issuedCommandDefArrayOptionSchema,
   extensionDefSchema,
   extensionPointDefSchema,
   extensionPointDefArrayOptionSchema,
   requiredStoreDeclarationSchema,
   requiredStoreDeclarationArrayOptionSchema,
+  requiredCapabilityDeclarationSchema,
+  requiredCapabilityDeclarationArrayOptionSchema,
+  traitDeclarationSchema,
+  traitDeclarationArrayOptionSchema,
   pluginStructureSchema,
   pluginStructureOffloadSchema,
   pluginDefinitionSchema,