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

package/CHANGELOG.md

@@ -3,6 +3,31 @@
 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.127 (2026-09-02)
+
+* feat(aws)!: the messaging sender is configuration, and a stack can choose to only log ([23b8b4b](https://github.com/ReventlessDev/reventless-core/commit/23b8b4bfe9c70555de4d74266ca686cb427485ca))
+### Features
+
+* **dcb:** a boundary that cannot derive its scope says so ([db79969](https://github.com/ReventlessDev/reventless-core/commit/db79969df36bd90607425f6a22b4624227cfc4a0))
+
+### BREAKING CHANGES
+
+* `Capability_Messaging_Ses.make` is replaced by
+`Capability_Messaging.make(~name)`, which reads the transport and the address
+from config; the SES module keeps only `emailSender`. A deployment that named its
+sender in code must move it to `platform:messagingEmailSender` or the deploy is
+refused.
+
+
+
+# 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

package/package.json

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

package/src/components/Aggregate.res

@@ -70,10 +70,11 @@ module type Spec = {
   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`. */
+      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

package/src/components/DcbScopeInference.res

@@ -130,6 +130,40 @@ let foreignConsumedKeys = (s: sliceShape): array<string> => {
   )
 }
 
+/**
+Which consumed arms cost a slice its partition — the actionable half of the
+"no own partition key" ambiguity.
+
+Rule 1 subtracts `foreignConsumedKeys` from `producedKeys`, so a slice whose only
+produced key is also declared on a consumed arm it does not itself produce is left
+with nothing. In practice that is almost always one mistake: a *lifecycle* arm
+naming the id it is already partitioned by (`ProductAdded({productId})` on a slice
+whose every event carries `productId`), which reads as "this id comes from a
+foreign producer" when it is in fact this slice's own partition.
+
+The ambiguity message can only say a partition was not found. This says which arm
+to delete, which is the whole difference between a diagnostic and a puzzle — so it
+is here, beside the rule that produces the ambiguity, rather than duplicated by
+each surface that reports one.
+
+Returns one entry per produced key that a foreign arm claims, naming those arms.
+Empty when the slice has a partition (nothing to explain) or when the produced
+keys are simply too many (a different ambiguity, answered by `@partitionTag`).
+*/
+let partitionBlockers = (s: sliceShape): array<(string, array<string>)> => {
+  let foreign = foreignConsumedKeys(s)
+  let ownProduced = Set.make()
+  s.produced->Array.forEach(e => ownProduced->Set.add(e.eventType))
+  producedKeys(s)
+  ->Array.filter(k => foreign->Array.includes(k))
+  ->Array.map(k => (
+    k,
+    s.consumed
+    ->Array.filter(e => !(ownProduced->Set.has(e.eventType)) && e->keysOfEvent->Array.includes(k))
+    ->Array.map(e => e.eventType),
+  ))
+}
+
 /**
 Per-slice cross-partition keys for the test harness, which has no global owner
 map: a foreign-read key that is not the slice's own partition is read across
@@ -169,9 +203,16 @@ let infer = (slices: array<sliceShape>): derived => {
       switch produced->Array.filter(k => !(foreign->Array.includes(k))) {
       | [single] => partitionBySlice->Dict.set(s.sliceName, single)
       | [] =>
+        // Name the arms that took the key. Almost always a lifecycle arm
+        // declaring the id the slice is already partitioned by, where the fix is
+        // to drop the field rather than to annotate around it.
+        let blame =
+          partitionBlockers(s)
+          ->Array.map(((key, arms)) => `${arms->Array.join("/")} declares ${key}`)
+          ->Array.join("; ")
         let _ = ambiguities->Array.push((
           s.sliceName,
-          "no own partition key — every produced *Id is read from a foreign producer (pure join?); add an explicit @partitionTag",
+          `no own partition key — every produced *Id is read from a foreign producer (${blame}). If that field is this slice's own partition, remove it from the consumed arm; if the slice really is a pure join, add an explicit @partitionTag`,
         ))
       | many =>
         let _ = ambiguities->Array.push((

package/src/components/DcbScopeInference.res.mjs

@@ -50,6 +50,24 @@ function foreignConsumedKeys(s) {
   }));
 }
 
+function partitionBlockers(s) {
+  let foreign = foreignConsumedKeys(s);
+  let ownProduced = new Set();
+  s.produced.forEach(e => {
+    ownProduced.add(e.eventType);
+  });
+  return producedKeys(s).filter(k => foreign.includes(k)).map(k => [
+    k,
+    s.consumed.filter(e => {
+      if (ownProduced.has(e.eventType)) {
+        return false;
+      } else {
+        return e.idFields.map(tagKeyOf).includes(k);
+      }
+    }).map(e => e.eventType)
+  ]);
+}
+
 function crossPartitionForSlice(s) {
   let foreign = foreignConsumedKeys(s);
   let scalar = commandScalarKeys(s);
@@ -93,12 +111,13 @@ function infer(slices) {
           s.sliceName,
           `multiple candidate partition keys (` + many.join(", ") + `) — add an explicit @partitionTag`
         ]);
-      } else {
-        ambiguities.push([
-          s.sliceName,
-          "no own partition key — every produced *Id is read from a foreign producer (pure join?); add an explicit @partitionTag"
-        ]);
+        return;
       }
+      let blame = partitionBlockers(s).map(param => param[1].join("/") + ` declares ` + param[0]).join("; ");
+      ambiguities.push([
+        s.sliceName,
+        `no own partition key — every produced *Id is read from a foreign producer (` + blame + `). If that field is this slice's own partition, remove it from the consumed arm; if the slice really is a pure join, add an explicit @partitionTag`
+      ]);
       return;
     }
     let single = many[0];
@@ -171,6 +190,7 @@ export {
   consumedKeys,
   commandScalarKeys,
   foreignConsumedKeys,
+  partitionBlockers,
   crossPartitionForSlice,
   infer,
 }

package/src/components/DcbTag.res

@@ -1008,6 +1008,15 @@ The DCB decision-read scope threaded into every StateChangeSlice callback:
 type effectiveScope = {
   crossPartitionTagKeys: array<string>,
   tagKeysByEventType: dict<array<string>>,
+  /** Slices whose partition did not resolve, as `(slice, reason)` — non-empty
+      means the two fields above are the *annotated* fallback, not the derivation. */
+  ambiguities: array<(string, string)>,
+  /** Cross-partition keys the inference found that the fallback does not carry.
+      Non-empty is the harmful case and only that: a reference read silently
+      narrows to its own partition, so a slice decides against events it cannot
+      see and rejects a command whose facts are in the log. Empty (even with
+      ambiguities) means the fallback happens to agree and nothing is lost. */
+  droppedCrossPartitionTagKeys: array<string>,
 }
 
 /**
@@ -1023,6 +1032,12 @@ the runtime decision query cannot diverge from the storage/GSI scope. Before thi
 existed the entry point re-derived scope from annotations alone, silently dropping
 inferred cross-partition reference reads — see
 `docs/analysis/dcb-runtime-scope-annotation-drift.md`.
+
+The fallback reports itself. `ambiguities` says it happened and
+`droppedCrossPartitionTagKeys` says whether it cost anything, so a caller can
+distinguish a fallback that agrees with the derivation from one that quietly
+narrows a reference read — the second is a wrong answer waiting for the first
+command that needs the key, and callers are expected to raise it.
 */
 let deriveEffectiveScope = (slices: array<sliceSchemas>): effectiveScope => {
   let producedSchemas = slices->Array.map(s => s.eventSchema)
@@ -1055,6 +1070,10 @@ let deriveEffectiveScope = (slices: array<sliceSchemas>): effectiveScope => {
   {
     crossPartitionTagKeys: useInferred ? inferred.crossPartitionTagKeys : annotatedCross,
     tagKeysByEventType: useInferred ? inferred.tagKeysByEventType : annotatedTagKeys,
+    ambiguities: inferred.ambiguities,
+    droppedCrossPartitionTagKeys: useInferred
+      ? []
+      : inferred.crossPartitionTagKeys->Array.filter(k => !(annotatedCross->Array.includes(k))),
   }
 }
 

package/src/components/DcbTag.res.mjs

@@ -636,7 +636,9 @@ function deriveEffectiveScope(slices) {
   let useInferred = inferred.ambiguities.length === 0;
   return {
     crossPartitionTagKeys: useInferred ? inferred.crossPartitionTagKeys : annotatedCross,
-    tagKeysByEventType: useInferred ? inferred.tagKeysByEventType : annotatedTagKeys
+    tagKeysByEventType: useInferred ? inferred.tagKeysByEventType : annotatedTagKeys,
+    ambiguities: inferred.ambiguities,
+    droppedCrossPartitionTagKeys: useInferred ? [] : inferred.crossPartitionTagKeys.filter(k => !annotatedCross.includes(k))
   };
 }
 

package/src/components/InboundTranslationSlice.res

@@ -72,8 +72,8 @@ module type Spec = {
 
   /** 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.
+      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/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`). */

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

@@ -94,8 +94,8 @@ module type Spec = {
 
   /** 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.
+      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/generator/Codegen.res

@@ -608,6 +608,27 @@ let renderComposition = (
     pluginNameToEnvBase(config.name) ++
     "_UI_BUNDLE_URL\"",
   )
+  // The DCB boundary's slices as schemas, outside `Make` because the scope they
+  // determine is a property of the specs and not of any platform. Emitted rather
+  // than hand-listed so a slice added tomorrow is in it: this is the only value
+  // from which the whole boundary's scope can be derived without applying the
+  // functor, which is what lets a test — and the repo's scope check — assert that
+  // it resolves. A per-slice test cannot: one slice never has a boundary.
+  if resolved.stateChangeSlices->Array.length > 0 {
+    lines->Array.push("")
+    lines->Array.push("let dcbSliceSchemas: array<Reventless.DcbTag.sliceSchemas> = [")
+    resolved.stateChangeSlices->Array.forEach(stem =>
+      lines->Array.push(
+        "  {" ++
+        `name: ${stem}.name, ` ++
+        `commandSchema: ${stem}.commandSchema->S.castToUnknown, ` ++
+        `consumedEventSchema: ${stem}.consumedEventSchema->S.castToUnknown, ` ++
+        `eventSchema: ${stem}.eventSchema->S.castToUnknown` ++ "},",
+      )
+    )
+    lines->Array.push("]")
+  }
+
   lines->Array.push("")
   lines->Array.push("module Make = (Platform: ReventlessInfra.Platform.T) => {")
 

package/src/generator/Codegen.res.mjs

@@ -399,6 +399,14 @@ function renderComposition(config, resolved, componentChapters) {
   lines.push("// AUTO-GENERATED — do not edit. Run `npm run generate` to update.");
   lines.push("");
   lines.push("@val external uiBundleUrl: option<string> = \"process.env." + pluginNameToEnvBase(config.name) + "_UI_BUNDLE_URL\"");
+  if (resolved.stateChangeSlices.length !== 0) {
+    lines.push("");
+    lines.push("let dcbSliceSchemas: array<Reventless.DcbTag.sliceSchemas> = [");
+    resolved.stateChangeSlices.forEach(stem => {
+      lines.push("  {" + (`name: ` + stem + `.name, `) + (`commandSchema: ` + stem + `.commandSchema->S.castToUnknown, `) + (`consumedEventSchema: ` + stem + `.consumedEventSchema->S.castToUnknown, `) + (`eventSchema: ` + stem + `.eventSchema->S.castToUnknown`) + "},");
+    });
+    lines.push("]");
+  }
   lines.push("");
   lines.push("module Make = (Platform: ReventlessInfra.Platform.T) => {");
   let push = sectionLines => {

package/src/semantic/Messaging.res

@@ -45,6 +45,30 @@ let channelToString = (channel: channel): string =>
   | Push => "Push"
   }
 
+/**
+The `From:` header a deployment's email sender presents as: the bare address, or
+a display name in front of it.
+
+Provider-neutral for the reason everything else here is — the header is the
+RFC's, not a transport's, and two backends formatting it apart would present the
+same deployment under two names. It is applied where the sender is *provisioned*
+rather than at the send, so a transport receives one string and never has to know
+whether a name was configured.
+
+Quoted and escaped unconditionally rather than only when the name looks like it
+needs it. The unquoted form excludes characters an ordinary shop name carries — a
+comma above all, which would otherwise split the header into two addresses — and a
+rule applied only where it looks necessary is a rule that gets the exceptions
+wrong.
+*/
+let fromHeader = (~displayName: option<string>, ~address: string): string =>
+  switch displayName {
+  | None => address
+  | Some(name) =>
+    let escaped = name->String.replaceAll("\\", "\\\\")->String.replaceAll("\"", "\\\"")
+    `"${escaped}" <${address}>`
+  }
+
 /**
 What to say.
 

package/src/semantic/Messaging.res.mjs

@@ -23,6 +23,14 @@ function channelToString(channel) {
   }
 }
 
+function fromHeader(displayName, address) {
+  if (displayName === undefined) {
+    return address;
+  }
+  let escaped = displayName.replaceAll("\\", "\\\\").replaceAll("\"", "\\\"");
+  return `"` + escaped + `" <` + address + `>`;
+}
+
 function retriable(failure) {
   switch (failure.TAG) {
     case "Unavailable" :
@@ -50,6 +58,7 @@ function supports(provider, recipient) {
 export {
   channelOf,
   channelToString,
+  fromHeader,
   retriable,
   failureReason,
   supports,

package/src/types/Transition.res

@@ -1,13 +1,12 @@
 // The lifecycle edge a command owns, declared as a value rather than as an
 // attribute on the constructor.
 //
-// `@transition([Orders.Placed] => Orders.Shipped)` says the same thing and is
-// still the shorter spelling for a command a host declares itself. It cannot say
-// it for a command a host did NOT declare: a variant spread splices members,
-// while the annotation lowers to a dict on the parent union, so a spliced
-// command arrives carrying no edge at all. Nor can the annotation be checked —
-// the PPX extracts leaf identifiers as strings, and the states belong to another
-// component's enum, so a misspelling survives to the plugin structure.
+// The attribute this replaces could not say it for a command a host did NOT
+// declare: a variant spread splices members, while the attribute lowered to a
+// dict on the parent union, so a spliced command arrived carrying no edge at
+// all. Nor could it be checked — the PPX extracts leaf identifiers as strings,
+// and the states belong to another component's enum, so a misspelling survived
+// to the plugin structure.
 //
 // A `command => t<'state>` switch answers both. It is exhaustive, so a spliced
 // constructor is a compile error until the host says what it does; and `'state`