@reventlessdev/reventless-gwt 1.0.0-alpha.247 → 1.0.0-alpha.249

package/src/Delegate_GWT.res

@@ -3,7 +3,7 @@ open ReventlessCore
 // Delegate_GWT — GWT for ExtensionPoint mappings and Extension delegates.
 //
 // Both are pure input → published-actions translations and form the one
-// cross-plugin behavioural seam (per `.claude/rules/app-developer.md`). Each
+// cross-plugin behavioral seam (per `.claude/rules/app-developer.md`). Each
 // mapping has TWO directions, and each adapter drives both:
 //
 //   * an ExtensionPoint mapping turns an internal `Delegate` event into public

package/src/EventMapping_GWT.res

@@ -2,20 +2,20 @@ open ReventlessCore
 
 // Stage 5 — `EventMapping_GWT` is now a thin alias over `Mapping_GWT`
 // specialised for the Aggregate → Aggregate case. New tests should use
-// `Mapping_GWT.Make` directly with `Mapping_GWT.FromBehavior` adapters; this
+// `Mapping_GWT.Make` directly with `Mapping_GWT.FromDecision` adapters; this
 // wrapper is retained for migration backward-compat with consumers that were
-// already calling `EventMapping_GWT.Make(Source, SourceBehavior, Target,
-// TargetBehavior, EventMapping)` before Stage 5 landed.
+// already calling `EventMapping_GWT.Make(Source, SourceDecision, Target,
+// TargetDecision, EventMapping)` before Stage 5 landed.
 
 module Make = (
   Source: Reventless.Aggregate.Spec,
-  SourceBehavior: Behavior.T with module Spec = Source,
+  SourceDecision: Decision.T with module Spec = Source,
   Target: Reventless.Aggregate.Spec,
-  TargetBehavior: Behavior.T with module Spec = Target,
+  TargetDecision: Decision.T with module Spec = Target,
   EventMapping: Reventless.EventMapping.T with module Source = Source and module Target = Target,
 ) => {
-  module AdaptedSource = Mapping_GWT.FromBehavior(Source, SourceBehavior)
-  module AdaptedTarget = Mapping_GWT.FromBehavior(Target, TargetBehavior)
+  module AdaptedSource = Mapping_GWT.FromDecision(Source, SourceDecision)
+  module AdaptedTarget = Mapping_GWT.FromDecision(Target, TargetDecision)
 
   module BoundMapping = {
     module Source = AdaptedSource

package/src/EventMapping_GWT.res.mjs

@@ -3,9 +3,9 @@
 import * as Mapping_GWT$ReventlessGwt from "./Mapping_GWT.res.mjs";
 
 function Make(Source) {
-  return SourceBehavior => (Target => (TargetBehavior => (EventMapping => {
-    let AdaptedSource = Mapping_GWT$ReventlessGwt.FromBehavior(Source)(SourceBehavior);
-    let AdaptedTarget = Mapping_GWT$ReventlessGwt.FromBehavior(Target)(TargetBehavior);
+  return SourceDecision => (Target => (TargetDecision => (EventMapping => {
+    let AdaptedSource = Mapping_GWT$ReventlessGwt.FromDecision(Source)(SourceDecision);
+    let AdaptedTarget = Mapping_GWT$ReventlessGwt.FromDecision(Target)(TargetDecision);
     let map = EventMapping.map;
     let BoundMapping = {
       Source: undefined,

package/src/Flow_GWT.res

@@ -13,15 +13,15 @@ open ReventlessCore
 // each step folds the slice's own `decide`/`evolve`/`collect`/`project` over
 // the shared log. The log is JSON-erased (each step (de)serialises through its
 // own spec's schema, exactly as the runtime routes a DCB event log), and each
-// command step honours DCB tag filtering so downstream deciders never see
+// command step honors DCB tag filtering so downstream deciders never see
 // phantom cross-entity events.
 //
 // The chain is built from per-step functors (one per slice), threaded with
 // pipe-first so it reads top-to-bottom:
 //
-//   module Place = Flow_GWT.CommandStep(PlaceOrder, PlaceOrder_Behavior)
+//   module Place = Flow_GWT.CommandStep(PlaceOrder, PlaceOrder_Decision)
 //   module Auto  = Flow_GWT.AutomationSlice(AutoShipOrder, AutoShipOrder_Automation)
-//   module Ship  = Flow_GWT.CommandStep(ShipOrder, ShipOrder_Behavior)
+//   module Ship  = Flow_GWT.CommandStep(ShipOrder, ShipOrder_Decision)
 //   module View  = Flow_GWT.ViewStep(Orders, Orders_Projection)
 //
 //   start
@@ -279,8 +279,8 @@ let thenBoundaryScopeResolves = async (
 // -- CommandStep: a StateChangeSlice / Aggregate decider ---------------------
 
 module CommandStep = (
-  Spec: Behavior_GWT.BehaviorSpec,
-  Behavior: Behavior_GWT.Behavior with module Spec := Spec,
+  Spec: Decision_GWT.DecisionSpec,
+  Decision: Decision_GWT.Decision with module Spec := Spec,
 ) => {
   let consumedDecoder = Reventless.DcbDecode.makeDecoder(Spec.consumedEventSchema)
   let consumedEventTypes = consumedDecoder.eventTypes
@@ -335,8 +335,8 @@ module CommandStep = (
       ~payloadTagKeys,
     )
     let history = decodeMatching(s.log, consumedDecoder, query)
-    let state = history->Array.reduce(Behavior.initialState, Behavior.evolve)
-    switch Behavior.decide(state, command) {
+    let state = history->Array.reduce(Decision.initialState, Decision.evolve)
+    switch Decision.decide(state, command) {
     | Ok(events) => {
         ...s,
         log: s.log->appendEvents(events, Spec.eventSchema),
@@ -390,8 +390,8 @@ module CommandStep = (
 
 // -- AggregateCommandStep: an Aggregate decider partitioned by aggregate-ID --
 //
-// Mirror of `CommandStep` for `Reventless.Behavior.T` (the aggregate-flavor
-// behavior). Differences from the slice form:
+// Mirror of `CommandStep` for `Reventless.Decision.T` (the aggregate-flavor
+// decision). Differences from the slice form:
 //   * No `consumedEvent` distinction — aggregates fold their own `event`
 //     stream; the decoder uses `Spec.eventSchema`.
 //   * No DCB tag inference — `~id` partitions the history. `givenEvents` and
@@ -404,8 +404,8 @@ module CommandStep = (
 // histories isolated (a `Place` on `o2` does not see the events of `o1`).
 
 module AggregateCommandStep = (
-  Spec: Behavior_GWT.AggregateSpec,
-  Behavior: Reventless.Behavior.T with module Spec = Spec,
+  Spec: Decision_GWT.AggregateSpec,
+  Decision: Reventless.Decision.T with module Spec = Spec,
 ) => {
   let aggregateDecoder = Reventless.DcbDecode.makeDecoder(Spec.eventSchema)
 
@@ -422,8 +422,8 @@ module AggregateCommandStep = (
   let whenCommand = async (flowP: flow, ~id: string, command: Spec.command) => {
     let s = await flowP
     let history = decodeAggregateMatching(s.log, ~id, aggregateDecoder)
-    let state = history->Array.reduce(Behavior.initialState, Behavior.evolve)
-    switch Behavior.decide(state, command) {
+    let state = history->Array.reduce(Decision.initialState, Decision.evolve)
+    switch Decision.decide(state, command) {
     | Ok(events) => {
         ...s,
         log: s.log->appendAggregateEvents(~id, events, Spec.eventSchema),
@@ -717,7 +717,7 @@ module ExtensionPointStep = (M: EPMapping.Mapping) => {
   // Aggregate-style EP mappings address the source aggregate's identity via
   // the first arg (e.g. catalog Product → ProductBecameAvailable uses it as
   // `productId`). DCB upstreams don't set `lastAggregateId` and fall back to
-  // the synthetic `gwt-id` so existing DCB Flow tests keep their behaviour.
+  // the synthetic `gwt-id` so existing DCB Flow tests keep their behavior.
   let runMapping = async (sourceId: string, events: array<M.Delegate.event>): array<
     M.ExtensionPoint.event,
   > =>

package/src/Flow_GWT.res.mjs

@@ -171,7 +171,7 @@ async function thenBoundaryScopeResolves(flowP, name, slices) {
 }
 
 function CommandStep(Spec) {
-  return Behavior => {
+  return Decision => {
     let consumedDecoder = DcbDecode$Reventless.makeDecoder(Spec.consumedEventSchema);
     let consumedEventTypes = consumedDecoder.eventTypes;
     let givenEvents = async (flowP, events) => {
@@ -207,8 +207,8 @@ function CommandStep(Spec) {
       let s = await flowP;
       let query = DcbTag$Reventless.buildQueryFromCommand(consumedEventTypes, Spec.commandSchema, command, tagKeysByEventType, crossPartitionTagKeys, payloadTagKeys);
       let history = decodeMatching(s.log, consumedDecoder, query);
-      let state = Stdlib_Array.reduce(history, Behavior.initialState, Behavior.evolve);
-      let events = Behavior.decide(state, command);
+      let state = Stdlib_Array.reduce(history, Decision.initialState, Decision.evolve);
+      let events = Decision.decide(state, command);
       if (events.TAG !== "Ok") {
         return {
           log: s.log,
@@ -288,7 +288,7 @@ function CommandStep(Spec) {
 }
 
 function AggregateCommandStep(Spec) {
-  return Behavior => {
+  return Decision => {
     let aggregateDecoder = DcbDecode$Reventless.makeDecoder(Spec.eventSchema);
     let givenEvents = async (flowP, id, events) => {
       let s = await flowP;
@@ -306,8 +306,8 @@ function AggregateCommandStep(Spec) {
     let whenCommand = async (flowP, id, command) => {
       let s = await flowP;
       let history = decodeAggregateMatching(s.log, id, aggregateDecoder);
-      let state = Stdlib_Array.reduce(history, Behavior.initialState, Behavior.evolve);
-      let events = Behavior.decide(state, command);
+      let state = Stdlib_Array.reduce(history, Decision.initialState, Decision.evolve);
+      let events = Decision.decide(state, command);
       if (events.TAG !== "Ok") {
         return {
           log: s.log,

package/src/Hint.res

@@ -5,7 +5,7 @@
 // See `docs/analysis/given-when-then-specifications.md` §3.2 (locus table)
 // and §3.3 (JSON `hint` field).
 //
-// `locus` is a dotted pointer like "CategoryBehavior.decide" filled in by
+// `locus` is a dotted pointer like "CategoryDecision.decide" filled in by
 // the DSL at `then*` call time when the slice module name is in scope, else a
 // generic pointer. A `StateMismatch` names its fold, so a view's points at
 // `project` rather than `evolve`.

package/src/Mapping_GWT.res

@@ -3,7 +3,7 @@ open ReventlessCore
 // Stage 5 — cross-pattern mapping GWT.
 //
 // Generalises `EventMapping_GWT` so both the source and target of a mapping
-// can be an Aggregate (Behavior) or a StateChangeSlice. Covers all four
+// can be an Aggregate (Decision) or a StateChangeSlice. Covers all four
 // producer/consumer combinations: Aggr→Aggr, Aggr→DCB, DCB→Aggr, DCB→DCB.
 // See `docs/plans/done/reventless-gwt.md` Stage 5 for the migration plan.
 //
@@ -54,20 +54,20 @@ module type Mapping = {
 
 // -- Adapter functors --------------------------------------------------------
 
-// Adapter: any `Aggregate.Spec` + matching `Behavior.T` becomes a `GwtSource`.
+// Adapter: any `Aggregate.Spec` + matching `Decision.T` becomes a `GwtSource`.
 // Aggregates evolve their own events, so `consumedEvent = event`.
-module FromBehavior = (
+module FromDecision = (
   Spec: Reventless.Aggregate.Spec,
-  Behavior: Behavior.T with module Spec = Spec,
+  Decision: Decision.T with module Spec = Spec,
 ) => {
   let name = Spec.name
   module Id = Spec.Id
-  type state = Behavior.state
-  let initialState = Behavior.initialState
+  type state = Decision.state
+  let initialState = Decision.initialState
 
   type consumedEvent = Spec.event
   let consumedEventSchema = Spec.eventSchema
-  let evolve = Behavior.evolve
+  let evolve = Decision.evolve
 
   type command = Spec.command
   let commandSchema = Spec.commandSchema
@@ -78,7 +78,7 @@ module FromBehavior = (
   type error = Spec.error
   let errorSchema = Spec.errorSchema
 
-  let decide = Behavior.decide
+  let decide = Decision.decide
 }
 
 // Adapter: a StateChangeSlice spec becomes a `GwtSource`/`GwtTarget`. DCB

package/src/Mapping_GWT.res.mjs

@@ -9,17 +9,17 @@ import * as Outcome$ReventlessGwt from "./Outcome.res.mjs";
 import * as JestBind$ReventlessGwt from "./JestBind.res.mjs";
 import * as Message$ReventlessCore from "@reventlessdev/reventless-core/src/Message.res.mjs";
 
-function FromBehavior(Spec) {
-  return Behavior => ({
+function FromDecision(Spec) {
+  return Decision => ({
     name: Spec.name,
     Id: Spec.Id,
-    initialState: Behavior.initialState,
+    initialState: Decision.initialState,
     consumedEventSchema: Spec.eventSchema,
-    evolve: Behavior.evolve,
+    evolve: Decision.evolve,
     commandSchema: Spec.commandSchema,
     eventSchema: Spec.eventSchema,
     errorSchema: Spec.errorSchema,
-    decide: Behavior.decide
+    decide: Decision.decide
   });
 }
 
@@ -313,7 +313,7 @@ function Make(M) {
 }
 
 export {
-  FromBehavior,
+  FromDecision,
   FromStateChangeSlice,
   Make,
 }

package/src/Outcome.res

@@ -8,7 +8,7 @@
 // shape and §3.3 for the JSON rendering. Stage 7 adds sury-aware rendering and
 // structural `fieldDiff`. Stage 4 added `AppendConditionMismatch`.
 
-// The function whose fold produced a state: a behavior's `evolve`, or a view's
+// The function whose fold produced a state: a decision's `evolve`, or a view's
 // `project`. Absent means `Evolve`, so a harness that does not say keeps its hint.
 type fold = Evolve | Project
 

package/src/Query_GWT.res

@@ -12,7 +12,7 @@
 // `subIdConfig`), so both kinds of consumers use the same combinator set.
 // Adapter functors `FromReadModel` and `FromStateViewSlice` lift their
 // respective specs into the shared shape — mirroring how `Mapping_GWT` lifts
-// `Aggregate.Spec`/`StateChangeSlice.Spec` via `FromBehavior`/`FromStateChangeSlice`.
+// `Aggregate.Spec`/`StateChangeSlice.Spec` via `FromDecision`/`FromStateChangeSlice`.
 
 // -- Unified spec shape ------------------------------------------------------
 

package/src/RunnerHook.res

@@ -30,7 +30,7 @@ type sink = {
   ) => unit,
 }
 
-// The currently-registered sink, if any. `None` → plain Jest behaviour.
+// The currently-registered sink, if any. `None` → plain Jest behavior.
 let current: ref<option<sink>> = ref(None)
 
 let register = (s: sink) => current := Some(s)

package/src/ScenarioRecorder.res

@@ -0,0 +1,182 @@
+// Decision scenarios as they run, written as sidecars `check-lifecycle` reads.
+//
+// The PPX writes a `.gwt.json` sidecar from a `_GWT.res` file's source, so it can only name what
+// the source spells out: a literal constructor in a step. A suite written against a binding (a
+// trait's conformance suite, whose `B.request(…)` is whatever the host's binding builds) names
+// nothing in its source, and the host's file that registers it has no `describe` of its own, so
+// no sidecar is written and `check-lifecycle` sees none of its scenarios. The run has the values,
+// and the spec's schemas name them; this records them.
+//
+// Only with `REVENTLESS_EMIT_SIDECAR` set in the test process, the switch the PPX reads at build
+// time; otherwise every call is a no-op. A test file whose sidecar the PPX wrote is left alone:
+// read from source, it carries values and ids a run cannot.
+
+type entry = {kind: string, element: string}
+
+type scenario = {
+  title: string,
+  given: array<entry>,
+  when_: array<entry>,
+  then_: array<entry>,
+}
+
+let enabled = () =>
+  switch NodeProcess.env->Dict.get("REVENTLESS_EMIT_SIDECAR") {
+  | Some("1" | "true" | "TRUE") => true
+  | _ => false
+  }
+
+// The scenario of the test running now, if one is being recorded.
+let current: ref<option<scenario>> = ref(None)
+
+// The test file an external runner says it is running; Jest says it itself.
+let fileOverride: ref<option<string>> = ref(None)
+
+/** Names the test file an external runner (registered through `RunnerHook`) is about to run, so
+    what its tests record lands beside it. */
+let setFile = (path: string) => fileOverride := Some(path)
+
+// The running test's file under Jest, while a test runs.
+let jestTestPath: unit => option<string> = %raw(`function () {
+  try {
+    const state = globalThis.expect && globalThis.expect.getState && globalThis.expect.getState();
+    return state && typeof state.testPath === "string" ? state.testPath : undefined;
+  } catch (_) { return undefined; }
+}`)
+
+let testFile = () =>
+  switch fileOverride.contents {
+  | Some(f) => Some(f)
+  | None => jestTestPath()
+  }
+
+// What has been recorded in this process, per sidecar path: the spec it names and its scenarios.
+let recorded: Map.t<string, (string, array<scenario>)> = Map.make()
+
+// Per test file, the specs recorded from it in order, the first owning `<File>_GWT.gwt.json`.
+let specsOf: Map.t<string, array<string>> = Map.make()
+
+// Sidecar paths found written by the PPX: never written over.
+let foreign: Set.t<string> = Set.make()
+
+// `…/X_GWT.res.mjs` (or `.res`, `.mjs`, `.js`) → `…/X_GWT`.
+let baseOf = (file: string) =>
+  [".res.mjs", ".res.js", ".res", ".mjs", ".js"]->Array.reduce(file, (f, ext) =>
+    f->String.endsWith(ext)
+      ? f->String.slice(~start=0, ~end=String.length(f) - String.length(ext))
+      : f
+  )
+
+let sidecarFor = (~file: string, ~spec: string) => {
+  let specs = specsOf->Map.get(file)->Option.getOr([])
+  if !(specs->Array.includes(spec)) {
+    specs->Array.push(spec)
+    specsOf->Map.set(file, specs)
+  }
+  specs->Array.indexOf(spec) == 0 ? `${baseOf(file)}.gwt.json` : `${baseOf(file)}.${spec}.gwt.json`
+}
+
+// Whether a sidecar at `path` is the PPX's: present and not marked recorded.
+let writtenByPpx = (path: string) =>
+  switch NodeFs.existsSync(path) {
+  | false => false
+  | true =>
+    switch NodeFs.readFileSync(path)->JSON.parseOrThrow {
+    | Object(d) => d->Dict.get("recorded") != Some(Boolean(true))
+    | _ => true
+    | exception _ => true
+    }
+  }
+
+let entryJson = (e: entry) => JSON.Object(
+  Dict.fromArray([
+    ("kind", JSON.String(e.kind)),
+    ("element", JSON.String(e.element)),
+    ("values", JSON.Array([])),
+  ]),
+)
+
+let write = (~path: string, ~file: string, ~spec: string, scenarios: array<scenario>) => {
+  let json = JSON.Object(
+    Dict.fromArray([
+      ("specName", JSON.String(`${spec} (recorded)`)),
+      // What `check-lifecycle` takes the file's component from.
+      ("stem", JSON.String(spec)),
+      ("file", JSON.String(file)),
+      ("componentKind", JSON.String("Decision")),
+      ("recorded", JSON.Boolean(true)),
+      (
+        "scenarios",
+        JSON.Array(
+          scenarios->Array.map(s => JSON.Object(
+            Dict.fromArray([
+              ("title", JSON.String(s.title)),
+              ("given", JSON.Array(s.given->Array.map(entryJson))),
+              ("when", JSON.Array(s.when_->Array.map(entryJson))),
+              ("then", JSON.Array(s.then_->Array.map(entryJson))),
+            ]),
+          )),
+        ),
+      ),
+    ]),
+  )
+  NodeFs.writeFileSync(path, JSON.stringifyAny(json, ~space=2)->Option.getOr("{}") ++ "\n")
+}
+
+/** Runs one test's `body`, recording its steps when recording is on, and adds the scenario to
+    its file's sidecar. `spec` is the spec the test runs against, the component the sidecar names. */
+let around = (~spec: string, title: string, body: unit => 'outcome): 'outcome =>
+  if !enabled() {
+    body()
+  } else {
+    current := Some({title, given: [], when_: [], then_: []})
+    let finish = () => {
+      let scenario = current.contents
+      current := None
+      switch (scenario, testFile()) {
+      | (Some(s), Some(file)) =>
+        let path = sidecarFor(~file, ~spec)
+        if !(foreign->Set.has(path)) && !(recorded->Map.has(path)) && writtenByPpx(path) {
+          foreign->Set.add(path)
+        }
+        if !(foreign->Set.has(path)) {
+          let (_, scenarios) = recorded->Map.get(path)->Option.getOr((spec, []))
+          let scenarios = scenarios->Array.filter(o => o.title != s.title)->Array.concat([s])
+          recorded->Map.set(path, (spec, scenarios))
+          write(~path, ~file, ~spec, scenarios)
+        }
+      | _ => ()
+      }
+    }
+    switch body() {
+    | outcome =>
+      finish()
+      outcome
+    | exception e =>
+      finish()
+      throw(e)
+    }
+  }
+
+/** Whether a test is being recorded now: the steps name what they get only then. */
+let recording = () => current.contents->Option.isSome
+
+let push = (pick: scenario => array<entry>, entries: array<entry>) =>
+  current.contents->Option.forEach(s => entries->Array.forEach(e => pick(s)->Array.push(e)))
+
+/** The history a command is decided on, by event name. */
+let given = (names: array<string>) =>
+  push(s => s.given, names->Array.map(element => {kind: "event", element}))
+
+/** The command a test sends. */
+let whenCommand = (name: string) => push(s => s.when_, [{kind: "command", element: name}])
+
+/** What a test expects: these events. */
+let thenEvents = (names: array<string>) =>
+  push(s => s.then_, names->Array.map(element => {kind: "event", element}))
+
+/** What a test expects: this error. */
+let thenError = (name: string) => push(s => s.then_, [{kind: "error", element: name}])
+
+/** What a test expects: no event. */
+let thenNoEvent = () => push(s => s.then_, [{kind: "noEvent", element: ""}])