@reventlessdev/reventless-spec 3.0.0-alpha.115 → 3.0.0-alpha.116

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 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.116 (2026-08-16)
+
+### Features
+
+* **ppx:** declare a command's lifecycle edge once, as [@transition](https://github.com/transition) ([dd35130](https://github.com/ReventlessDev/reventless-core/commit/dd3513014f14b71879ee21263c6755d3c3d95096))
+
+
 # 3.0.0-alpha.115 (2026-08-16)
 
 ### Features

package/package.json

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

package/src/components/DcbScopeInference.res

@@ -8,7 +8,7 @@ each slice (variant names + `*Id`-shaped fields), never an `S.t` schema and neve
 a tag-metadata flag. That is precisely what we are replacing — so both the runtime
 (building shapes from `S.t` schemas, via `DcbTag.sliceShapeFromSchemas`) and the
 VS Code tooling (building shapes from parsed `.res` source) can feed the same
-`infer`. See `docs/plans/dcb-tag-scope-inference.md` § "Phase 1 design".
+`infer`. See `docs/plans/done/dcb-tag-scope-inference.md` § "Phase 1 design".
 
 The three rules (over the representation):
 

package/src/components/InboundTranslationSlice.res

@@ -53,7 +53,7 @@ module type Spec = {
 
   /** Optional display name of the foreign system this anti-corruption slice receives
       from (e.g. `"SupplierFeed"`). Drives the **external box** drawn outside the plugin
-      in the Event Graph / Context Map (see docs/plans/translation-external-boxes.md).
+      in the Event Graph / Context Map.
       Auto-injected by `@@reventless.spec` defaulting to `None` — set it to name the box. */
   let externalSystem: option<string>
 

package/src/components/OutboundTranslationSlice.res

@@ -103,7 +103,7 @@ module type Spec = {
 
   /** Optional display name of the foreign system this anti-corruption slice publishes
       to (e.g. `"EmailService"`). Drives the **external box** drawn outside the plugin
-      in the Event Graph / Context Map (see docs/plans/translation-external-boxes.md).
+      in the Event Graph / Context Map.
       Auto-injected by `@@reventless.spec` defaulting to `None` — set it to name the box. */
   let externalSystem: option<string>
 }

package/src/components/Plugin.res

@@ -180,11 +180,12 @@ type commandDef = {
   /**
   The single lifecycle state this command's handler writes — the command's *to*
   state, sibling of `allowedStates`' *from* set. Source: the
-  `@targetState("Shipped")` command-variant annotation. `None` (absent
-  annotation) is the back-compat default: AutoUI's board resolver then falls
-  back to its name-stem heuristic. `Some("Shipped")` lets the resolver move a
-  row by a declared transition instead of a guess. js_nullable for JSON safety,
-  same as `allowedStates`.
+  target of the `@transition(([Placed]) => Shipped)` command-variant annotation.
+  `Some("Shipped")` lets a resolver move a row by a declared transition instead
+  of a guess. `None` means no target was declared — and note that this is two
+  different statements depending on `allowedStates`: with a from-set present it
+  is the command declaring it does not move the row, and with none it is simply
+  an unannotated command. js_nullable for JSON safety, same as `allowedStates`.
   */
   targetState: @s.matches(stringOptionSchema) option<string>,
   /**
@@ -318,8 +319,8 @@ type queryableDef = {
   state schema: a client holding this def holds the whole predicate, and two places
   deriving one comparison is how they come to disagree about it.
 
-  The state form is also what lets `@allowedStates` answer command applicability
-  when retired, with no annotation beyond the two — retirement expressed in the
+  The state form is also what lets a command's `@transition` answer applicability
+  when retired, with no annotation beyond the one — retirement expressed in the
   vocabulary a command's stance is already written in.
   */
   retiredValues: @s.matches(stringArrayOptionSchema) option<array<string>>,

package/src/components/Snapshot.res

@@ -1,5 +1,5 @@
 // Per-aggregate persisted-snapshot configuration
-// (docs/plans/aggregate-snapshotting.md).
+// (docs/plans/done/aggregate-snapshotting.md).
 //
 // Snapshotting is opt-in and lives on the Behavior module (where `state` is
 // defined): `Behavior.T.snapshot = None` (the default, auto-injected by

package/src/components/StateAnnotations.res

@@ -52,8 +52,9 @@ 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 `@allowedStates([Deactivated])` on the way-back
-  command is enough to make a generated menu offer it there and nowhere else —
+  fact once instead of twice, and `@transition(([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
   already written in.
 
@@ -113,7 +114,7 @@ type stateAnnotationSpec = {
   metric: array<(string, metricSpec)>,
   /**
   Field annotated `@lifecycle` on the state record (PPX-emitted) — the enum a
-  command's `@allowedStates` is written in terms of, a board draws its columns
+  command's `@transition` 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/generator/Discovery.res

@@ -29,7 +29,7 @@ let folderToComponentType = ComponentKind.folderToKind
 // `None`. Uses the single-source `ComponentKind.isKindFolder`, so a chapter read
 // here (build time, disk) agrees with the authoring tool's identical heuristic and
 // with a chapter reflected off the deployed plugin structure. See
-// docs/plans/deployed-chapter-grouping.md.
+// docs/plans/done/deployed-chapter-grouping.md.
 let chapterOf = (relPath: string): option<string> => {
   let segments = relPath->String.split("/")
   // Need at least one directory segment before the filename.

package/src/types/Behavior.res

@@ -72,7 +72,7 @@ module type T = {
   */
   let decide: (state, Spec.command) => result<array<Spec.event>, Spec.error>
 
-  /** Persisted-snapshot configuration (docs/plans/aggregate-snapshotting.md).
+  /** Persisted-snapshot configuration (docs/plans/done/aggregate-snapshotting.md).
       `None` — the default, auto-injected by `@@reventless.behavior` — keeps
       full replay; `Some({interval, stateSchema})` writes a keep-one snapshot
       every `interval` events and seeds cold replays from the latest one.

package/src/types/Message.res

@@ -162,7 +162,7 @@ type commandJson = {
 // (clones via a JSON round-trip; never re-encodes through the schema), is idempotent on
 // valid data, and falls back to the ORIGINAL error when the fill doesn't resolve the
 // failure — so genuine corruption still surfaces.
-// See docs/plans/platform-infrastructure-in-plugin-list.md (durable fix option 2).
+// See docs/plans/done/platform-infrastructure-in-plugin-list.md (durable fix option 2).
 //
 // The scalar arm is the odd one out and is deliberately noisy. Every other fill is
 // *derived* — the schema states what an absent value means, and the fill supplies exactly