@reventlessdev/reventless-spec 3.0.0-alpha.169 → 3.0.0-alpha.171

package/src/components/StateChangeSlice.res

@@ -9,7 +9,7 @@ on no concurrent changes to the same entities.
 Plan 02 splits the merged spec into two module types:
 
 - `Spec` — types, identity, schemas. The structural contract.
-- `Behavior` — `state`, `initialState`, `evolve`, `decide`. The state machine.
+- `Decision` — `state`, `initialState`, `evolve`, `decide`. The state machine.
 
 @example
 ```rescript
@@ -43,7 +43,7 @@ let decide = (state, command) => switch command {
 */
 /**
 The lean Spec for a StateChangeSlice — types and schemas. State and
-state-evolution functions live in the sibling `Behavior` module type. A slice has
+state-evolution functions live in the sibling `Decision` module type. A slice has
 no identity of its own: it decides about the one its partition field carries.
 */
 module type Spec = {
@@ -119,12 +119,13 @@ module type Spec = {
 }
 
 /**
-The Behavior — pure state machine that decides commands and folds events.
+The Decision — pure state machine that decides commands and folds events, in
+the shape of the decider pattern. Its file is `<Slice>_Decision.res`.
 
 `module Spec: Spec` shares the lean Spec's types so `evolve` references
 `Spec.consumedEvent`, `decide` references `Spec.command`/`Spec.event`/`Spec.error`.
 */
-module type Behavior = {
+module type Decision = {
   module Spec: Spec
 
   /**
@@ -148,6 +149,6 @@ module type Behavior = {
   */
   let decide: (state, Spec.command) => result<array<Spec.event>, Spec.error>
 
-  /** File URL of this Behavior module (`import.meta.url`). */
+  /** File URL of this Decision module (`import.meta.url`). */
   let moduleUrl: string
 }

package/src/components/StateViewSlice.res

@@ -53,11 +53,11 @@ module type Spec = {
 
   /**
   What a row is keyed by. `Id.StringPure` (a plain `string`) unless the view
-  declares its identity — `module Key = OrderId` — in which case a projection
+  declares its identity — `module Id = OrderId` — in which case a projection
   that keys a row by another entity's id does not compile. Auto-injected by
   `@@reventless.spec` in a `StateView/` folder.
   */
-  module Key: Id.T
+  module Id: Id.T
 
   /**
   Events this view slice projects. Only needs the fields required for the projection —
@@ -125,7 +125,7 @@ module type Projection = {
   Receives the event wrapped in a `consumed` envelope (event + `meta` +
   `recordedAt`); only events declared in `Spec.consumedEvent` — no wildcard needed.
   */
-  let project: consumed<Spec.consumedEvent> => array<Projection.action<Spec.Key.t, Spec.state>>
+  let project: consumed<Spec.consumedEvent> => array<Projection.action<Spec.Id.t, Spec.state>>
 
   /** File URL of this Projection module (`import.meta.url`). */
   let moduleUrl: string

package/src/components/TaggedUnion.res

@@ -19,7 +19,7 @@ the declaration by `named` — the ppx does it for a variant a state record uses
 and a framework type carrying a union does it beside its `Semantic.mark`.
 
 A union with no name is not emitted as one. It falls through to the IR's
-`Unknown`, which is a `String` in the SDL — the behaviour that predates this
+`Unknown`, which is a `String` in the SDL — the behavior that predates this
 module — except that it is now reported at deploy time instead of silently.
 */
 let unionNameId: S.Metadata.Id.t<string> = S.Metadata.Id.make(

package/src/generator/Codegen.res

@@ -67,13 +67,13 @@ let renderAutomationSlices = (stems: array<string>): array<string> =>
   )
 
 let renderAggregates = (aggregates: array<Pairing.aggregateDef>): array<string> =>
-  aggregates->Array.flatMap(({spec, behavior, eventMappings, isAsync}) => {
+  aggregates->Array.flatMap(({spec, decision, eventMappings, isAsync}) => {
     let em = eventMappings->Option.getOr("ReventlessInfra.NoEventMappings.Make(" ++ spec ++ ")")
     let factory = isAsync ? "MakeAsync" : "Make"
     [
       "  module " ++ spec ++ "Aggregate = Platform.Aggregate." ++ factory ++ "(",
       "    " ++ spec ++ ",",
-      "    " ++ behavior ++ ",",
+      "    " ++ decision ++ ",",
       "    " ++ em ++ ",",
       "  )",
     ]
@@ -159,7 +159,7 @@ let renderExtensions = (extensions: array<string>): array<string> =>
     "  module " ++ stem ++ " = Platform.Extension.Make(" ++ stem ++ ".Mapping)"
   )
 
-// AWS-specific renderers were removed in favour of the canonical ones — the
+// AWS-specific renderers were removed in favor of the canonical ones — the
 // AWS Plugin.res now emits `open <Namespace>` so bare stems resolve, and the
 // AWS Platform.{Aggregate,ReadModel}.Make functors delegate to the
 // `*_Builder_Single` strategy under the hood (see reventless-aws/src/Platform.res).
@@ -630,7 +630,7 @@ let renderComposition = (
   // Header
   lines->Array.push("// AUTO-GENERATED — do not edit. Run `npm run generate` to update.")
   // Federation override URL — empty/unset means Auto UI renders every fragment.
-  // Read once at module init; same env var is honoured by the AWS wrapper.
+  // Read once at module init; same env var is honored by the AWS wrapper.
   lines->Array.push("")
   lines->Array.push(
     "@val external uiBundleUrl: option<string> = \"process.env." ++
@@ -877,7 +877,7 @@ let render = (
   validateSliceTargets(~resolved)
   // Chapter map, keyed by each component's spec stem (= its `Spec.name` for every
   // graph-node kind, which is how `Plugin_Structure` looks the chapter up). Filtered
-  // to the actual component stems so body files (`_Behavior`, `_Projections`, …) —
+  // to the actual component stems so body files (`_Decision`, `_Projections`, …) —
   // which `Discovery` also surfaces and which share their component's chapter — don't
   // leak noise entries into the generated call. Tasks / extensions / extension points
   // carry no chapter field, so they are excluded too.

package/src/generator/Codegen.res.mjs

@@ -42,7 +42,7 @@ function renderAggregates(aggregates) {
     return [
       "  module " + spec + "Aggregate = Platform.Aggregate." + factory + "(",
       "    " + spec + ",",
-      "    " + param.behavior + ",",
+      "    " + param.decision + ",",
       "    " + em + ",",
       "  )"
     ];

package/src/generator/Discovery.res

@@ -28,7 +28,7 @@ type discoveredFile = {
 let folderToComponentType = ComponentKind.folderToKind
 
 // The intra-plugin grouping band ("chapter") a file belongs to, derived from its
-// path relative to `src/`: the first directory segment that is not a recognised
+// path relative to `src/`: the first directory segment that is not a recognized
 // kind-folder. `src/<Chapter>/<Kind>/<Component>.res` → `Some("<Chapter>")`; a file
 // directly under a kind-folder (`src/<Kind>/<Component>.res`) or at the src root →
 // `None`. Uses the single-source `ComponentKind.isKindFolder`, so a chapter read
@@ -52,7 +52,7 @@ let chapterOf = (relPath: string): option<string> => {
 // Deduplicated (stem → chapter) pairs across the discovered files, sorted by stem
 // for deterministic codegen. Only files that carry a chapter are included; stems are
 // unique within a plugin (validated), so keying by stem cannot collide. Body files
-// (`_Behavior`, `_Projections`, …) share their component's chapter but are never
+// (`_Decision`, `_Projections`, …) share their component's chapter but are never
 // looked up by `Spec.name`, so their presence is harmless.
 let chaptersByStem = (discovered: array<discoveredFile>): array<(string, string)> => {
   let byStem: Dict.t<string> = Dict.make()
@@ -116,7 +116,7 @@ let isSkipped = (stem: string): bool =>
   // `_EventMappings` and `_Mappings` files in per-entity Aggregate/ folders
   // are picked up by the dedicated [Pairing.findEventMappings] walker;
   // treating them as Aggregate specs would hunt for a non-existent
-  // `_EventMappingsBehavior` / `_MappingsBehavior`.
+  // `_EventMappings_Decision` / `_Mappings_Decision`.
   stem->String.endsWith("_EventMappings") ||
   stem->String.endsWith("_Mappings")
 

package/src/generator/Pairing.res

@@ -1,10 +1,10 @@
 // Applies pairing rules to discovered files.
-// - Aggregates: pairs Foo + FooBehavior; finds Foo_EventMappings if present
+// - Aggregates: pairs Foo + Foo_Decision; finds Foo_EventMappings if present
 // - ReadModels: pairs FooReadModel + FooProjections; extracts mapping module names from projections file
 // - Slices (Plan 02): pair X + X_<Kind> where Kind is the implementation
 //   suffix matching the slice's folder. The slice arrays carry only spec
 //   stems; the corresponding impl stem is `<stem>_<implSuffix>`.
-//     * StateChangeSlice / StateViewSlice  → Behavior / Projection
+//     * StateChangeSlice / StateViewSlice  → Decision / Projection
 //     * AutomationSlice                    → Automation
 //     * In/OutboundTranslationSlice        → Translation
 // - ExtensionPoints: groups by epGroup, counts mappings, selects Make variant
@@ -12,7 +12,7 @@
 // Implementation-file suffix per slice kind. Used to filter impl files out
 // of the slice arrays (they're paired with their spec stems via this
 // suffix at codegen time) and to compute the impl module reference.
-let implSuffixForStateChange = "_Behavior"
+let implSuffixForStateChange = "_Decision"
 let implSuffixForStateView = "_Projection"
 let implSuffixForAutomation = "_Automation"
 let implSuffixForTranslation = "_Translation"
@@ -27,7 +27,7 @@ let isImplStem = (stem: string): bool =>
   stem->String.endsWith(implSuffixForTranslation) ||
   stem->String.endsWith(mappingsSuffixForAutomation)
 
-type aggregateDef = {spec: string, behavior: string, eventMappings: option<string>, isAsync: bool}
+type aggregateDef = {spec: string, decision: string, eventMappings: option<string>, isAsync: bool}
 // readModelDef pairs a ReadModel spec with its sibling `_Projections.res`
 // file. Codegen emits `Platform.ReadModel.Make(<spec>, <projections>)` and
 // expects the projections file to declare `let mappings` via
@@ -252,7 +252,37 @@ let groupExtensionPoints = (epFiles: array<Discovery.discoveredFile>): array<ext
   extensionPoints
 }
 
+// The logic file's former name. One beside its spec is refused rather than
+// read as a component of its own.
+let retiredSuffix = "_Behavior"
+
+let retiredBehaviorFile = (discovered: array<Discovery.discoveredFile>): option<
+  Discovery.discoveredFile,
+> => {
+  let stems = discovered->Array.map(({stem}) => stem)
+  discovered->Array.find(({stem}) =>
+    stem->String.endsWith(retiredSuffix) ||
+      (stem->String.endsWith("Behavior") &&
+        stems->Array.includes(stem->String.slice(~start=0, ~end=String.length(stem) - 8)))
+  )
+}
+
+let refuseBehaviorFiles = (discovered: array<Discovery.discoveredFile>) =>
+  switch retiredBehaviorFile(discovered) {
+  | None => ()
+  | Some({stem, relPath}) =>
+    let spec =
+      stem->String.endsWith(retiredSuffix)
+        ? stem->String.slice(~start=0, ~end=String.length(stem) - 9)
+        : stem->String.slice(~start=0, ~end=String.length(stem) - 8)
+    JsError.throwWithMessage(
+      `Generator: ${relPath} uses the former name. The logic file is now ` ++
+      `${spec}_Decision.res, annotated @@reventless.decision: rename it ` ++ `(or run reventless-rename-to-decision).`,
+    )
+  }
+
 let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): resolved => {
+  refuseBehaviorFiles(discovered)
   let eventMappings = findEventMappings(~srcDir)
 
   let stateChangeSlices = []
@@ -270,7 +300,7 @@ let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): re
   let stateChangeSliceRelPaths: Dict.t<string> = Dict.make()
   // Shared by StateViewSlice and StateViewSliceStream (stems are unique).
   let stateViewSliceRelPaths: Dict.t<string> = Dict.make()
-  let aggregateBehaviors: array<string> = []
+  let aggregateDecisions: array<string> = []
   let readModelStems: array<string> = []
   // Stream-enabled read model spec stems (the `ReadModelStream/` folder).
   let readModelStreamStems: array<string> = []
@@ -282,7 +312,7 @@ let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): re
   let extensions = []
 
   // Classify discovered files by component type. For the five slice
-  // families, impl files (X_Behavior / X_Projection / X_Automation /
+  // families, impl files (X_Decision / X_Projection / X_Automation /
   // X_Translation) are filtered out: they're paired with their spec stems
   // at codegen time via the `_<ImplKind>` suffix convention.
   discovered->Array.forEach(({stem, componentType, epGroup, relPath}) => {
@@ -318,8 +348,8 @@ let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): re
         outboundTranslationSliceRelPaths->Dict.set(stem, relPath)
       }
     | Aggregate =>
-      if stem->String.endsWith("Behavior") {
-        aggregateBehaviors->Array.push(stem)
+      if stem->String.endsWith("Decision") {
+        aggregateDecisions->Array.push(stem)
       } else {
         aggregateSpecs->Array.push(stem)
         aggregateSpecRelPaths->Dict.set(stem, relPath)
@@ -343,30 +373,29 @@ let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): re
   })
 
   // ── Aggregate pairing ──────────────────────────────────────────────────────
-  // Tries the post-Phase-3.1 `<Spec>_Behavior` form first, then falls back
-  // to the legacy `<Spec>Behavior` (no underscore).
+  // Tries `<Spec>_Decision` first, then `<Spec>Decision` (no underscore).
   let aggregates =
     aggregateSpecs
     ->sortedStems
     ->Array.filterMap(spec => {
-      let underscored = spec ++ "_Behavior"
-      let bare = spec ++ "Behavior"
-      let behaviorStem = if aggregateBehaviors->Array.includes(underscored) {
+      let underscored = spec ++ "_Decision"
+      let bare = spec ++ "Decision"
+      let decisionStem = if aggregateDecisions->Array.includes(underscored) {
         Some(underscored)
-      } else if aggregateBehaviors->Array.includes(bare) {
+      } else if aggregateDecisions->Array.includes(bare) {
         Some(bare)
       } else {
         None
       }
-      switch behaviorStem {
-      | Some(behavior) =>
+      switch decisionStem {
+      | Some(decision) =>
         let isAsync = switch Dict.get(aggregateSpecRelPaths, spec) {
         | None => false
         | Some(relPath) => hasAsyncAttribute(NodePath.join([srcDir, relPath]))
         }
         Some({
           spec,
-          behavior,
+          decision,
           eventMappings: Dict.get(eventMappings, spec),
           isAsync,
         })
@@ -386,7 +415,7 @@ let resolve = (discovered: array<Discovery.discoveredFile>, ~srcDir: string): re
   // ── ReadModel pairing ──────────────────────────────────────────────────────
   // Pairs spec `<Plural>` with impl `<Plural>_Projections.res`. The legacy
   // unpaired forms (`<Plural>ReadModel.res` / `<Plural>Projections.res`) are
-  // no longer recognised — see PR3-5 of the close-ppx-gaps-and-unify-naming
+  // no longer recognized — see PR3-5 of the close-ppx-gaps-and-unify-naming
   // plan for the migration; downstream codebases should rename to the
   // underscored form.
   let pairReadModel = (~stream: bool, rm: string): option<readModelDef> => {

package/src/generator/Pairing.res.mjs

@@ -4,9 +4,10 @@ import * as Nodefs from "node:fs";
 import * as Nodepath from "node:path";
 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 Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Generator_Node$Reventless from "./Generator_Node.res.mjs";
 
-let implSuffixForStateChange = "_Behavior";
+let implSuffixForStateChange = "_Decision";
 
 let implSuffixForStateView = "_Projection";
 
@@ -197,7 +198,34 @@ function groupExtensionPoints(epFiles) {
   return extensionPoints;
 }
 
+let retiredSuffix = "_Behavior";
+
+function retiredBehaviorFile(discovered) {
+  let stems = discovered.map(param => param.stem);
+  return discovered.find(param => {
+    let stem = param.stem;
+    if (stem.endsWith(retiredSuffix)) {
+      return true;
+    } else if (stem.endsWith("Behavior")) {
+      return stems.includes(stem.slice(0, stem.length - 8 | 0));
+    } else {
+      return false;
+    }
+  });
+}
+
+function refuseBehaviorFiles(discovered) {
+  let match = retiredBehaviorFile(discovered);
+  if (match === undefined) {
+    return;
+  }
+  let stem = match.stem;
+  let spec = stem.endsWith(retiredSuffix) ? stem.slice(0, stem.length - 9 | 0) : stem.slice(0, stem.length - 8 | 0);
+  Stdlib_JsError.throwWithMessage(`Generator: ` + match.relPath + ` uses the former name. The logic file is now ` + (spec + `_Decision.res, annotated @@reventless.decision: rename it `) + `(or run reventless-rename-to-decision).`);
+}
+
 function resolve(discovered, srcDir) {
+  refuseBehaviorFiles(discovered);
   let eventMappings = findEventMappings(srcDir);
   let stateChangeSlices = [];
   let stateViewSlices = [];
@@ -212,7 +240,7 @@ function resolve(discovered, srcDir) {
   let aggregateSpecRelPaths = {};
   let stateChangeSliceRelPaths = {};
   let stateViewSliceRelPaths = {};
-  let aggregateBehaviors = [];
+  let aggregateDecisions = [];
   let readModelStems = [];
   let readModelStreamStems = [];
   let projectionsByRelPath = {};
@@ -273,8 +301,8 @@ function resolve(discovered, srcDir) {
           return;
         }
       case "Aggregate" :
-        if (stem.endsWith("Behavior")) {
-          aggregateBehaviors.push(stem);
+        if (stem.endsWith("Decision")) {
+          aggregateDecisions.push(stem);
         } else {
           aggregateSpecs.push(stem);
           aggregateSpecRelPaths[stem] = relPath;
@@ -311,17 +339,17 @@ function resolve(discovered, srcDir) {
     }
   });
   let aggregates = Stdlib_Array.filterMap(sortedStems(aggregateSpecs), spec => {
-    let underscored = spec + "_Behavior";
-    let bare = spec + "Behavior";
-    let behaviorStem = aggregateBehaviors.includes(underscored) ? underscored : (
-        aggregateBehaviors.includes(bare) ? bare : undefined
+    let underscored = spec + "_Decision";
+    let bare = spec + "Decision";
+    let decisionStem = aggregateDecisions.includes(underscored) ? underscored : (
+        aggregateDecisions.includes(bare) ? bare : undefined
       );
-    if (behaviorStem !== undefined) {
+    if (decisionStem !== undefined) {
       let relPath = aggregateSpecRelPaths[spec];
       let isAsync = relPath !== undefined ? hasFileAttribute(Nodepath.join(srcDir, relPath), "@@reventless.async") : false;
       return {
         spec: spec,
-        behavior: behaviorStem,
+        decision: decisionStem,
         eventMappings: eventMappings[spec],
         isAsync: isAsync
       };
@@ -410,6 +438,9 @@ export {
   hasSystemCallableAttribute,
   effectiveSpecName,
   groupExtensionPoints,
+  retiredSuffix,
+  retiredBehaviorFile,
+  refuseBehaviorFiles,
   resolve,
 }
 /* node:fs Not a pure module */

package/src/lifecycle/CheckLifecycleModel.res

@@ -3,7 +3,7 @@ The lifecycle model each example's own scenarios describe, and what it says abou
 the edges each command declares beside them.
 
 `Moves([Placed], Shipped)` is authored, and until now nothing compared it to
-behaviour. The compiler resolves the state constructors and the platform checks
+behavior. The compiler resolves the state constructors and the platform checks
 they belong to the linked view — both much weaker properties than agreement: a
 command can declare `Moves([Deactivated], Active)` while its `decide` accepts an
 active row, or emit an event the view folds into something else, and every static
@@ -595,7 +595,8 @@ let lifecycleMapFor = (
 
 // ── Rule 2 and 3: the relation a command's own scenarios describe ───────────
 
-type outcome = Emitted | NoChange | Refused
+// `Rejected`: the decision rejected the command, the sidecar's `"error"`.
+type outcome = Emitted | NoChange | Rejected
 
 type observation = {
   title: string,
@@ -646,7 +647,7 @@ let outcomeOf = (s: scenario): outcome =>
   // `thenNoEvent`, and the empty `then` an older sidecar wrote for the same
   // thing. Accepted, and nothing happened.
   | "noEvent" | "" => NoChange
-  | "error" => Refused
+  | "error" => Rejected
   // A `then` this harvest has no reading for — a side effect, a published
   // command. Not an effect on this row either way.
   | _ => NoChange
@@ -694,7 +695,7 @@ let observe = (
 
   scenarios->Array.filterMap(s =>
     switch s.whenElements->Array.get(0) {
-    // `thenRefused`: the caller did not own the row, which says nothing about
+    // `thenForbidden`: the caller did not own the row, which says nothing about
     // the states the command is legal in.
     | Some(_) if s.thenKind == "forbidden" => None
     | Some(command) if s.whenKind == "command" =>
@@ -739,7 +740,7 @@ let deriveCommands = (
         mine->Array.filterMap(o => o.outcome == Emitted || o.from == noRow ? None : Some(o.from)),
       ),
       refusedStates: sortedUnique(
-        mine->Array.filterMap(o => o.outcome == Refused && o.from != noRow ? Some(o.from) : None),
+        mine->Array.filterMap(o => o.outcome == Rejected && o.from != noRow ? Some(o.from) : None),
       ),
       targets: sortedUnique(
         effective->Array.filterMap(o => o.to == o.from || o.to == noRow ? None : Some(o.to)),
@@ -935,10 +936,10 @@ let compare = (
     // effect somewhere agrees with that rather than narrowing it — the corpus
     // covers the states somebody wrote a scenario for, and silence about the
     // rest is not refusal. What DOES refute the claim is a state the command was
-    // exercised in and **refused**: that is the switch and the behaviour
+    // exercised in and **refused**: that is the switch and the behavior
     // disagreeing about the same row.
     //
-    // 🚨 **Refused, not merely inert.** `Unrestricted` claims the command is
+    // 🚨 **Rejected, not merely inert.** `Unrestricted` claims the command is
     // never refused — it does not claim the command always emits. A state where a
     // scenario shows it accepted and silent AGREES with that: returning `Ok([])`
     // for a command that would change nothing is this codebase's idempotency

package/src/lifecycle/CheckLifecycleModel.res.mjs

@@ -470,7 +470,7 @@ function outcomeOf(s) {
   let match = s.thenKind;
   switch (match) {
     case "error" :
-      return "Refused";
+      return "Rejected";
     case "event" :
       return "Emitted";
     default:
@@ -561,7 +561,7 @@ function deriveCommands(component, observations, labelled) {
         }
       })),
       refusedStates: sortedUnique(Stdlib_Array.filterMap(mine, o => {
-        if (o.outcome === "Refused" && o.from !== noRow) {
+        if (o.outcome === "Rejected" && o.from !== noRow) {
           return o.from;
         }
       })),

package/src/semantic/Capabilities.res

@@ -41,9 +41,9 @@ type t = {
 /**
 The capability set of a platform that provisions nothing.
 
-Every capability here answers `Unavailable`, which is a *modelled* outcome:
+Every capability here answers `Unavailable`, which is a *modeled* outcome:
 `translate` maps it to `Error`, the item is retried and the sweep surfaces it.
-That is the behaviour wanted for a deployment that simply has no geocoder — the
+That is the behavior wanted for a deployment that simply has no geocoder — the
 work stays queued and visible rather than being written off as a verdict on the
 address, which is what `NoMatch` would mean.
 

package/src/semantic/CapabilityNeed.res

@@ -47,7 +47,7 @@ let toString = (need: t): string =>
 
 /** The inverse, for readers of a persisted structure or a committed manifest.
     `None` for a capability this build does not know — a newer plugin's need is
-    reported as unrecognised, never silently dropped into a known arm. */
+    reported as unrecognized, never silently dropped into a known arm. */
 let fromString = (name: string): option<t> =>
   switch name {
   | "Geocoding" => Some(Geocoding)
@@ -65,13 +65,13 @@ Declared capability needs a platform does not provision.
 
 `declared` is `pluginStructure.requiredCapabilities` as persisted: `(capability,
 component)` pairs whose capability is a string, because a structure is replayed
-from an event log. A name this build does not recognise is **skipped** — it
+from an event log. A name this build does not recognize is **skipped** — it
 belongs to a newer framework, and refusing a deploy over a capability this code
 cannot evaluate would be a guess dressed as a check.
 
 Only what was declared. A plugin that declares nothing is unaffected: an
 unprovisioned capability it never named degrades exactly as it always has, which
-is the modelled outcome for a deployment that simply does not have one.
+is the modeled outcome for a deployment that simply does not have one.
 */
 let unmet = (~declared: array<(string, string)>, ~provisioned: array<t>): array<unmet> =>
   declared->Array.filterMap(((capability, component)) =>

package/src/semantic/Color.res

@@ -1,15 +1,15 @@
 /**
-Marks a `string` field as a colour, written as a hex triplet.
+Marks a `string` field as a color, written as a hex triplet.
 
 ## Why hex only
 
 A field carrying this semantic is rendered as a swatch by setting the value as a
-CSS `background`. CSS accepts far more than a colour there — `url(…)`, gradients,
-`var(…)` — so "any CSS colour" would make a colour field a way to write arbitrary
+CSS `background`. CSS accepts far more than a color there — `url(…)`, gradients,
+`var(…)` — so "any CSS colour" would make a color field a way to write arbitrary
 CSS into a log that cannot be edited afterwards. Hex is the form that is a
-colour and nothing else, and it is what a colour picker emits anyway.
+color and nothing else, and it is what a color picker emits anyway.
 
-Named colours (`rebeccapurple`) and functional forms (`rgb(…)`, `oklch(…)`) are
+Named colors (`rebeccapurple`) and functional forms (`rgb(…)`, `oklch(…)`) are
 rejected for the same reason, not because they are worse notation.
 
 ## The grammar
@@ -26,7 +26,7 @@ full triplet, and the triplet with alpha. Case is not significant.
     })
 ```
 */
-/** The colour's representation. Transparent `string`; see `Email.t`. */
+/** The color's representation. Transparent `string`; see `Email.t`. */
 type t = string
 
 external unsafe: string => t = "%identity"
@@ -34,7 +34,7 @@ external toString: t => string = "%identity"
 
 let hex = /^#([0-9a-fA-F]{3,4}|[0-9a-fA-F]{6}|[0-9a-fA-F]{8})$/
 
-/** Validate a raw string as a hex colour, saying why when it is not one. */
+/** Validate a raw string as a hex color, saying why when it is not one. */
 let fromString = (raw: string): result<t, string> =>
   if hex->RegExp.test(raw) {
     Ok(raw)
@@ -46,5 +46,5 @@ let fromString = (raw: string): result<t, string> =>
     )
   }
 
-/** The sury schema for a colour field. Use with `@s.matches(Reventless.Color.schema)`. */
+/** The sury schema for a color field. Use with `@s.matches(Reventless.Color.schema)`. */
 let schema: S.t<t> = S.string->Semantic.refined(~id=Semantic.Id.color, ~check=fromString)

package/src/semantic/IdentityProvider.res

@@ -38,7 +38,7 @@ surface. Collapsing them either loses accounts to a transient blip or retries
 forever against a password policy.
 */
 type failure =
-  /** The contact is already a principal. A modelled answer, not an exception —
+  /** The contact is already a principal. A modeled answer, not an exception —
         which is what a silent idempotent sign-up throws away. */
   | Conflict
   /** The provider is down or unreachable. The domain fact stands; retry. */

package/src/semantic/Messaging.res

@@ -142,7 +142,7 @@ type message = {subject?: string, body: string}
 
 /** The provider accepted the message. `ref` is its own id for it — what a
     support conversation about a missing message is conducted with, and the only
-    thing a caller can record that the provider will recognise. */
+    thing a caller can record that the provider will recognize. */
 type receipt = {ref: string}
 
 /**
@@ -203,7 +203,7 @@ type send = (~recipient: recipient, ~message: message) => promise<result<receipt
 The capability as a slice receives it: what can be attempted, and how.
 
 `channels` is here because a recipient cannot be offered a choice the deployment
-cannot honour. A platform provisions email only, or email and SMS; a preference
+cannot honor. A platform provisions email only, or email and SMS; a preference
 centre that listed all three would collect a subscription every send then answers
 `UnsupportedChannel` for. Published rather than inferred from a failed send,
 because discovering a channel by failing on it costs a real message.

package/src/types/{Behavior.res → Decision.res}

@@ -1,11 +1,15 @@
-// Behavior module type for aggregate business logic.
-// Lives in reventless-spec so application domain code can define behaviors
+// Decision module type for an aggregate's write-side logic.
+// Lives in reventless-spec so application domain code can define decisions
 // without importing the reventless implementation package.
 
 /**
-Module type that application code must implement to define aggregate business logic.
+Module type that application code must implement to define an aggregate's
+write-side logic: whether a command goes through, and what it emits.
 
-A `Behavior.T` module contains the `Spec` (command / event / error types), the
+It implements the *decider* pattern: `initialState`, `evolve` and `decide`.
+The file is `<Entity>_Decision.res`, annotated `@@reventless.decision`.
+
+A `Decision.T` module contains the `Spec` (command / event / error types), the
 aggregate `state`, and two pure functions plus an initial state value:
 
 - `initialState` — the starting state before any events (represents "not yet created")
@@ -14,7 +18,7 @@ aggregate `state`, and two pure functions plus an initial state value:
 
 @example
 ```rescript
-// CategoryBehavior.res
+// Category_Decision.res
 module Spec = Category
 
 @schema
@@ -73,7 +77,7 @@ module type T = {
   let decide: (state, Spec.command) => result<array<Spec.event>, Spec.error>
 
   /** Persisted-snapshot configuration (docs/plans/done/aggregate-snapshotting.md).
-      `None` — the default, auto-injected by `@@reventless.behavior` — keeps
+      `None` — the default, auto-injected by `@@reventless.decision` — keeps
       full replay; `Some({interval, stateSchema})` writes a keep-one snapshot
       every `interval` events and seeds cold replays from the latest one.
       Enable with `@@reventless.snapshots(<interval>)` (requires

package/src/types/Message.res

@@ -76,7 +76,7 @@ type meta = {
 /**
 Context passed into command handlers, carrying the aggregate ID and envelope metadata.
 
-Passed as the second argument to `Behavior.T.create` and `Behavior.T.execute`
+Passed as the second argument to `Decision.T.create` and `Decision.T.execute`
 so business logic can read the caller identity or propagate correlation IDs.
 */
 @schema