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

package/CHANGELOG.md

@@ -3,6 +3,38 @@
 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.171 (2026-10-21)
+
+* feat!: a state view's row key is module Id ([08c9726](https://github.com/ReventlessDev/reventless-core/commit/08c972659a3d689a39fd5e2f2026597155e92210))
+* feat!: a plugin structure's component definitions are read-side and write-side defs ([ea2ab69](https://github.com/ReventlessDev/reventless-core/commit/ea2ab69e928ba16d7e640e4c66ab0e9ba034fe5c))
+
+### BREAKING CHANGES
+
+* a state view spec declares its row key as module Id. A
+hand-written module Key in a spec under StateView/ or StateViewStream/
+fails the build with "A state view's row key is `module Id`, not
+`module Key`".
+* Plugin.queryableDef, Plugin.writableDef, their schemas,
+isPublicQueryable and encodeQueryableDef no longer exist; a reader names
+readSideDef, writeSideDef, isPublicReadSide and encodeReadSideDef. There
+are no aliases, so the compiler lists every reader.
+
+
+
+# 3.0.0-alpha.170 (2026-10-21)
+
+* feat!: the write-side logic module is called the decision, and a codemod moves an app over ([cb573ff](https://github.com/ReventlessDev/reventless-core/commit/cb573ff5b928c7d7f3e75988dfaa65066f8c95eb))
+
+### BREAKING CHANGES
+
+* <Spec>_Behavior.res, @@reventless.behavior,
+Reventless.Behavior.T, StateChangeSlice.Behavior, Behavior_GWT and
+thenRefused no longer exist. Run `npx reventless-rename-to-decision` at an
+app's root, then rebuild; comments are not rewritten. The PPX must be the
+matching release.
+
+
+
 # 3.0.0-alpha.169 (2026-10-19)
 
 ### Features

package/README.md

@@ -11,7 +11,7 @@ The **specification layer** of [Reventless](https://docs.reventless.dev) — a
 spec-driven, event-sourced CQRS framework written in [ReScript](https://rescript-lang.org).
 This package holds the type specifications and module-type interfaces that the rest of the
 framework is built on: the contracts application domain code implements (commands, events,
-behaviors, projections) and the component-kind vocabulary the whole framework shares. It
+decisions, projections) and the component-kind vocabulary the whole framework shares. It
 has **no** runtime, cloud, or storage dependency, so domain code can declare its shape
 against `reventless-spec` without pulling in an implementation. Modules are exposed under
 the `Reventless` namespace.
@@ -24,8 +24,9 @@ ReScript modules, consumed by adding the package to your `rescript.json` `depend
 
 - **`Message`** — the envelope metadata carried by every event and command (`meta`,
   `event'<>`, `command'<>`), used for audit, correlation, tracing, and routing.
-- **`Behavior`** — the module type application code implements to define aggregate business
-  logic: `initialState`, `evolve(state, event)`, and `decide(command, state)`.
+- **`Decision`** — the module type application code implements to define an aggregate's
+  write-side logic (the decider pattern): `initialState`, `evolve(state, event)`, and
+  `decide(state, command)`. Its file is `<Entity>_Decision.res`.
 - **`Projection`** — `Source` / `Target` module types describing a read model projected
   from an aggregate's events.
 - **`Handler`** — function signatures for handling commands, events, and errors.
@@ -62,6 +63,19 @@ generate-plugin src/          # generate src/Plugin.res from the src/ folder
 Wire it into your build via a `prebuild` script so it runs before `rescript build`. The
 generated `Plugin.res` is committed to git, so CI compiles it directly.
 
+**`reventless-rename-to-decision` CLI**
+
+Moves an application from the logic module's former name, *behavior*, to *decision*:
+it renames every `*_Behavior.res` to `*_Decision.res` (with `git mv` inside a work tree)
+and rewrites `@@reventless.behavior`, `Behavior_GWT`, `Reventless.Behavior`,
+`thenRefused` and `<Spec>_Behavior` references in `.res` files. The framework refuses the
+old spellings, so a bump is this command plus a build.
+
+```bash
+reventless-rename-to-decision --dry-run   # print what would change under .
+reventless-rename-to-decision             # rename; skips node_modules and lib
+```
+
 ## Where it fits
 
 `reventless-spec` is the foundation package in the Reventless framework:

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.169",
+  "version": "3.0.0-alpha.171",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -10,7 +10,8 @@
     "certify-trait": "./run-certify-trait.mjs",
     "trait-manifest": "./run-trait-manifest.mjs",
     "check-lifecycle": "./run-check-lifecycle.mjs",
-    "prepare-accounts": "./run-prepare-accounts.mjs"
+    "prepare-accounts": "./run-prepare-accounts.mjs",
+    "reventless-rename-to-decision": "./run-rename-to-decision.mjs"
   },
   "jest": {
     "testMatch": [
@@ -26,11 +27,11 @@
     "sury": "11.0.0",
     "sury-ppx": "11.0.0",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.22"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.23"
   },
   "devDependencies": {
     "rescript": "12.3.1",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.12"
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.13"
   },
   "peerDependencies": {
     "rescript": "^12.3.1"

package/run-rename-to-decision.mjs

@@ -0,0 +1,3 @@
+#!/usr/bin/env node
+import { main } from "./src/codemod/RenameToDecision.res.mjs"
+await main()

package/src/AnsiStyle.res

@@ -5,7 +5,7 @@
 
     This is the lowest layer in the logging stack — LogPrefix and Logger
     depend on it, so the sink decision lives here as the single source of
-    truth. `useAnsi()` ⇒ TTY text mode (colour/bold); `isJsonSink()` ⇒
+    truth. `useAnsi()` ⇒ TTY text mode (color/bold); `isJsonSink()` ⇒
     structured JSON for any non-TTY collector (CloudWatch, Datadog, …). */
 @val external _isTty: option<bool> = "process.stdout.isTTY"
 @val external _logFormat: option<string> = "process.env.REVENTLESS_LOG_FORMAT"
@@ -38,7 +38,7 @@ let _format = ref(_resolveFormat())
 /** Declares what this runtime is, for the pipe case the TTY probe gets wrong.
     Call it at module init, before anything logs. An explicit
     REVENTLESS_LOG_FORMAT still wins, so a developer can always ask for the other
-    one. A runtime that says nothing keeps the TTY behaviour. */
+    one. A runtime that says nothing keeps the TTY behavior. */
 let setDefaultFormat = (format: [#text | #json]) => {
   _default :=
     Some(
@@ -56,7 +56,7 @@ let reload = () => _format := _resolveFormat()
 /** True when output should be structured JSON (non-TTY sink). */
 let isJsonSink = () => _format.contents == "json"
 
-/** True when output should carry ANSI colour/bold (TTY text mode). */
+/** True when output should carry ANSI color/bold (TTY text mode). */
 let useAnsi = () => _format.contents == "text"
 
 /** Wrap a string in ANSI bold escape codes — no-op in a JSON sink. */

package/src/CliArgs.res

@@ -1,7 +1,7 @@
 /***
 How every command-line tool in this repository reads `process.argv`: through
 Node's `parseArgs`, with mistakes worded the way these tools word them, and one
-behaviour on `--help`, on a usage mistake and on a bare invocation (see [run]).
+behavior on `--help`, on a usage mistake and on a bare invocation (see [run]).
 Non-strict with tokens rather than strict mode, because strict mode names the
 offending argument only inside English prose.
 */

package/src/LogPrefix.res

@@ -164,7 +164,7 @@ let fmtPlainPrefix = (~comp=?, ()) => {
 // no trailing space between `[Plugin]` and `[Comp]`.
 //
 // Sink-aware: in a non-TTY/JSON sink it falls back to `fmtPlainPrefix` so no
-// ANSI colour or bold leaks into structured logs. This makes every caller that
+// ANSI color or bold leaks into structured logs. This makes every caller that
 // pre-formats a prefix before reaching `Logger.emit` (EffectLogger.withComp,
 // the infra-layer `compLog`s) correct without per-call-site changes.
 let fmtComp = (~comp=?, ()) =>

package/src/codemod/RenameToDecision.res

@@ -0,0 +1,207 @@
+// Move an application from the write-side logic module's former name, *behavior*,
+// to *decision*: `X_Behavior.res` becomes `X_Decision.res`, and the spellings that
+// name it in `.res` sources follow.
+//
+// The framework accepts none of the former spellings, so a consumer's bump is this
+// command plus a build. Everything is planned before anything changes: a target
+// that already exists stops the run with nothing touched.
+
+let usage = `Usage: reventless-rename-to-decision [--dry-run] [<dir>]
+
+  <dir>      where to start; the default is the current directory
+  --dry-run  print what would change, change nothing
+
+  Renames every *_Behavior.res to *_Decision.res (git mv inside a git work tree,
+  with its compiled output beside it), and in every .res and .resi file:
+  @@reventless.behavior -> @@reventless.decision, Behavior_GWT -> Decision_GWT,
+  Reventless.Behavior -> Reventless.Decision, thenRefused -> thenForbidden, and
+  <Spec>_Behavior -> <Spec>_Decision. Skips node_modules and lib.`
+
+type args = {dir: string, dryRun: bool}
+
+let parseArgs = (argv: array<string>): result<args, string> =>
+  CliArgs.parse(~bools=["dry-run"], argv)
+  ->Result.flatMap(a => a->CliArgs.atMost(1))
+  ->Result.map(a => {
+    dir: a->CliArgs.positionals->Array.get(0)->Option.getOr("."),
+    dryRun: a->CliArgs.bool("dry-run"),
+  })
+
+let cli: CliArgs.cli<args> = {bin: "reventless-rename-to-decision", usage, parse: parseArgs}
+
+// ── The text ─────────────────────────────────────────────────────────────────
+
+// In order: the qualified forms before the bare module names they contain.
+let replacements: array<(RegExp.t, string)> = [
+  (/@@reventless\.behavior\b/g, "@@reventless.decision"),
+  (/\bBehavior_GWT\.BehaviorSpec\b/g, "Decision_GWT.DecisionSpec"),
+  (/\bBehavior_GWT\.Behavior\b/g, "Decision_GWT.Decision"),
+  (/\bBehavior_GWT\b/g, "Decision_GWT"),
+  (/\bReventless\.Behavior\b/g, "Reventless.Decision"),
+  (/\bStateChangeSlice\.Behavior\b/g, "StateChangeSlice.Decision"),
+  (/\bMapping_GWT\.FromBehavior\b/g, "Mapping_GWT.FromDecision"),
+  (/\bthenRefused\b/g, "thenForbidden"),
+  (/\b([A-Z][A-Za-z0-9]*)_Behavior\b/g, "$1_Decision"),
+]
+
+// A trait's conformance binding names the decision module `Behavior`; where a
+// file binds it, its uses in that file follow.
+let localBinding = /^(\s*)module Behavior = /m
+
+let rewrite = (source: string): string => {
+  let text =
+    replacements->Array.reduce(source, (text, (pattern, replacement)) =>
+      text->String.replaceRegExp(pattern, replacement)
+    )
+  if localBinding->RegExp.test(text) {
+    text
+    ->String.replaceRegExp(/^(\s*)module Behavior = /gm, "$1module Decision = ")
+    ->String.replaceRegExp(/\bBehavior\./g, "Decision.")
+  } else {
+    text
+  }
+}
+
+// ── The tree ─────────────────────────────────────────────────────────────────
+
+type move = {from: string, to_: string}
+type edit = {path: string, contents: string}
+type plan = {moves: array<move>, edits: array<edit>}
+
+let skippedDirs = ["node_modules", "lib", ".git"]
+
+let isSource = (name: string) => name->String.endsWith(".res") || name->String.endsWith(".resi")
+
+// A moved source takes its compiled output and interface along.
+let companions = [".res", ".resi", ".res.mjs", ".res.js", ".res.cjs"]
+
+let rec walk = (dir: string, files: array<string>) =>
+  NodeFs.readdirSync(dir, {withFileTypes: true})->Array.forEach(entry => {
+    let name = entry->NodeFs.direntName
+    let path = NodePath.join([dir, name])
+    if entry->NodeFs.isDirectory {
+      if !(skippedDirs->Array.includes(name)) {
+        walk(path, files)
+      }
+    } else if entry->NodeFs.isFile {
+      files->Array.push(path)
+    }
+  })
+
+let byPath = (a: string, b: string) => String.compare(a, b)
+
+/** What the run would do under `dir`, or why it cannot. */
+let plan = (~dir: string): result<plan, string> => {
+  let files = []
+  walk(dir, files)
+  files->Array.sort(byPath)
+  let present = Set.fromArray(files)
+
+  let moves =
+    files
+    ->Array.filter(path => path->String.endsWith("_Behavior.res"))
+    ->Array.flatMap(source => {
+      let stem = source->String.slice(~start=0, ~end=String.length(source) - 13)
+      companions->Array.filterMap(suffix => {
+        let from = stem ++ "_Behavior" ++ suffix
+        present->Set.has(from) ? Some({from, to_: stem ++ "_Decision" ++ suffix}) : None
+      })
+    })
+
+  let edits = files->Array.filterMap(path =>
+    if path->NodePath.basename->isSource {
+      let contents = NodeFs.readFileSync(path)
+      let rewritten = rewrite(contents)
+      rewritten == contents ? None : Some({path, contents: rewritten})
+    } else {
+      None
+    }
+  )
+
+  switch moves->Array.find(({to_}) => present->Set.has(to_)) {
+  | Some({from, to_}) =>
+    Error(`${to_} already exists, so ${from} cannot take its name. Nothing was changed.`)
+  | None => Ok({moves, edits})
+  }
+}
+
+// ── Applying it ──────────────────────────────────────────────────────────────
+
+let git = (~cwd: string, args: array<string>) =>
+  NodeChildProcess.spawnSync(
+    "git",
+    args,
+    {cwd, encoding: "utf8", stdio: ["ignore", "pipe", "pipe"]},
+  )
+
+let succeeded = (result: NodeChildProcess.spawnSyncResult) =>
+  result.status->Nullable.toOption == Some(0)
+
+let isTracked = (path: string) =>
+  git(
+    ~cwd=NodePath.dirname(path),
+    ["ls-files", "--error-unmatch", "--", NodePath.basename(path)],
+  )->succeeded
+
+let moveFile = ({from, to_}: move): result<unit, string> =>
+  if isTracked(from) {
+    let result = git(
+      ~cwd=NodePath.dirname(from),
+      ["mv", "--", NodePath.basename(from), NodePath.basename(to_)],
+    )
+    result->succeeded
+      ? Ok()
+      : Error(`git mv ${from}: ${result.stderr->Nullable.toOption->Option.getOr("")->String.trim}`)
+  } else {
+    try {
+      NodeFs.renameSync(from, to_)
+      Ok()
+    } catch {
+    | JsExn(e) => Error(`rename ${from}: ${e->JsExn.message->Option.getOr("failed")}`)
+    }
+  }
+
+/** Edits are written at the old paths, then the files move, so a moved file
+    keeps both its history and its new contents. */
+let apply = ({moves, edits}: plan): result<unit, string> => {
+  edits->Array.forEach(({path, contents}) => NodeFs.writeFileSync(path, contents))
+  moves->Array.reduce(Ok(), (done, move) => done->Result.flatMap(() => moveFile(move)))
+}
+
+let describe = ({moves, edits}: plan, ~dryRun: bool): array<string> => {
+  let verb = dryRun ? "would " : ""
+  let lines = [
+    ...moves->Array.map(({from, to_}) => `${verb}move  ${from} -> ${to_}`),
+    ...edits->Array.map(({path}) => `${verb}edit  ${path}`),
+  ]
+  let movedSources = moves->Array.filter(({from}) => from->String.endsWith(".res"))->Array.length
+  lines->Array.push(
+    `${dryRun ? "Would rename" : "Renamed"} ${movedSources->Int.toString} file(s) and ${dryRun
+        ? "edit"
+        : "edited"} ${edits->Array.length->Int.toString}.`,
+  )
+  lines
+}
+
+/** The whole run without a process: the lines it prints, or why it failed. */
+let execute = ({dir, dryRun}: args): result<array<string>, string> =>
+  if !(dir->NodeFs.existsSync) {
+    Error(`${dir} does not exist.`)
+  } else {
+    plan(~dir)->Result.flatMap(plan =>
+      dryRun ? Ok(describe(plan, ~dryRun)) : apply(plan)->Result.map(() => describe(plan, ~dryRun))
+    )
+  }
+
+let main = () =>
+  CliArgs.run(cli, async args =>
+    switch execute(args) {
+    | Ok(lines) => lines->Array.forEach(line => Console.log(line))
+    | Error(message) =>
+      Console.error(`reventless-rename-to-decision: ${message}`)
+      NodeProcess.exit(1)
+    }
+  )
+
+// No top-level call: `../../run-rename-to-decision.mjs` invokes [main], so a test
+// can import this module.