@reventlessdev/reventless-gwt 1.0.0-alpha.231 → 1.0.0-alpha.233

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 1.0.0-alpha.233 (2026-10-01)
+
+* feat!: roles a plugin declares, groups a platform provides ([43daace](https://github.com/ReventlessDev/reventless-core/commit/43daace6ca588afe22562d079af1e6f1da81942e))
+
+### BREAKING CHANGES
+
+* AllowGroups and AdminGroup are removed — write AllowRoles over
+the plugin's Roles.t, and use Role.admin / Platform.adminGroup(). Spec module
+types declare `type role`, and their rules are Authorization.rule<role>; a spec
+that writes its own rule declares `type role` (Reventless.Role.name for a rule
+over Authorization.permission). Role.name is a private string: make one from a
+string with Role.make.
+
+
+
+# 1.0.0-alpha.232 (2026-10-01)
+
+### Features
+
+* **spec, core, gwt, ppx:** a command acts only on what its caller owns ([2636f0e](https://github.com/ReventlessDev/reventless-core/commit/2636f0ee44797ee2c0b0c40a7107cf306113173f))
+
+
 # 1.0.0-alpha.231 (2026-09-29)
 
 **Note:** Version bump only for package @reventlessdev/reventless-gwt

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-gwt",
-  "version": "1.0.0-alpha.231",
+  "version": "1.0.0-alpha.233",
   "description": "Given-When-Then DSLs and test harness for Reventless slice testing",
   "license": "Apache-2.0",
   "jest": {
@@ -16,15 +16,15 @@
     "sury": "11.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.34",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.11",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.182",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.154",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.284",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.20"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.20",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.184",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.286",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.156"
   },
   "devDependencies": {
     "rescript": "12.3.1",
     "sury-ppx": "11.0.0",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.95"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.96"
   },
   "peerDependencies": {
     "rescript": "^12.3.1"

package/src/Behavior_GWT.res

@@ -22,6 +22,204 @@ open ReventlessCore
 // and slice users *cannot* use [MakeFromAggregate] (their Spec/Behavior shape
 // differs). Pick the matching entry point.
 
+// ---------------------------------------------------------------------------
+// Who issues the command. `asCaller` names the caller before `whenCmd`; the
+// command is then checked as production checks it: its `@authorize` rule against
+// the caller's roles, then — for slices and aggregates that mark `@owner` on the
+// events they decide on — against the owners the given events record. Without
+// `asCaller` the command carries no caller claim, which the handler reads as the
+// platform acting for itself — so every scenario written before this existed is
+// unchanged.
+// ---------------------------------------------------------------------------
+module Caller = {
+  external unsafeAsString: 'a => string = "%identity"
+
+  type t = {
+    claim: Message.CallerClaim.t,
+    /** The roles held, by name. A scenario names them by its plugin's own
+        `Roles.t`, whose cases are their names at run time. */
+    roles: array<Reventless.Role.name>,
+    signedIn: bool,
+  }
+
+  // A plugin's roles are payload-less variants, strings at run time; anything
+  // else would be compared with a rule's role names and never match.
+  let roleNames = (roles: array<'role>): array<Reventless.Role.name> =>
+    roles->Array.map(role =>
+      if Reventless.OwnerScope.isJsString(role) {
+        Reventless.Role.make(role->unsafeAsString)
+      } else {
+        JsError.throwWithMessage(
+          "Caller: expected roles of the plugin's Roles.t (payload-less, so strings at runtime)",
+        )
+      }
+    )
+
+  /**
+  A caller who owns only what records their id, holding `roles` (none by default).
+
+  Takes the id as the scenario has it — `Caller.owner(c1)` with `c1: CustomerId.t`,
+  or a plain string — because every `Id.Make` identity is a string on the wire.
+  The type is not checked, and need not be: an id of the wrong entity matches no
+  recorded owner, so it can only be refused, which fails the scenario that
+  expected the owner to act. A value that is not a string at all is refused here.
+  */
+  let owner = (id: 'id, ~roles: array<'role>=[]): t =>
+    if Reventless.OwnerScope.isJsString(id) {
+      {claim: Owned({userId: id->unsafeAsString}), roles: roleNames(roles), signedIn: true}
+    } else {
+      JsError.throwWithMessage(
+        "Caller.owner: expected an id (a string at runtime, such as an Id.Make identity)",
+      )
+    }
+
+  /** A signed-in caller holding `roles`, who owns nothing the given events record. */
+  let inRoles = (roles: array<'role>): t => {
+    claim: Owned({userId: "caller-in-roles"}),
+    roles: roleNames(roles),
+    signedIn: true,
+  }
+
+  /** A caller exempt from ownership rules, acting on anyone's behalf. Holds no
+      role: elevation does not grant a command whose rule the caller fails. */
+  let operator: t = {claim: Exempt, roles: [], signedIn: true}
+  /** A caller with no identity. */
+  let anonymous: t = {claim: Unidentified, roles: [], signedIn: false}
+}
+
+/** `Caller` as a scenario sees it: roles typed by the spec's own `role`, so they
+    are written bare (`Caller.inRoles([Merchandiser])`) and another plugin's role
+    does not compile. */
+module type Callers = {
+  type role
+  type t = Caller.t
+  let owner: ('id, ~roles: array<role>=?) => t
+  let inRoles: array<role> => t
+  let operator: t
+  let anonymous: t
+}
+
+module Callers = (
+  R: {
+    type role
+  },
+): (Callers with type role = R.role) => {
+  type role = R.role
+  type t = Caller.t
+  let owner = (id, ~roles: array<role>=[]) => Caller.owner(id, ~roles)
+  let inRoles = (roles: array<role>) => Caller.inRoles(roles)
+  let operator = Caller.operator
+  let anonymous = Caller.anonymous
+}
+
+module type ActingSpec = {
+  let name: string
+  @schema
+  type history
+  @schema
+  type command
+  type role
+  let commandAuthorization: command => Reventless.Authorization.rule<role>
+}
+
+module Acting = (Spec: ActingSpec) => {
+  let caller: ref<option<Caller.t>> = ref(None)
+  let refusal: ref<option<CommandTopic_Helpers.rejectedResult>> = ref(None)
+
+  let ownerFieldsByEventType = Reventless.Owner.fieldNamesByVariant(
+    Spec.historySchema->S.castToUnknown,
+  )
+
+  let asCaller = (history, who: Caller.t) => {
+    caller := Some(who)
+    history
+  }
+
+  let commandName = command =>
+    command->Message.encode(Spec.commandSchema)->Message.variantNameOfJson
+
+  // The rule first, as production checks it, against the roles alone: which group
+  // a role maps to is a deployment's fact, not the scenario's.
+  let refusedByRule = (who: Caller.t, command: Spec.command): bool =>
+    if (
+      Spec.commandAuthorization(command)
+      ->Reventless.Authorization.named
+      ->Reventless.Authorization.admits(~signedIn=who.signedIn, ~holds=role =>
+        who.roles->Array.includes(role)
+      )
+    ) {
+      false
+    } else {
+      refusal :=
+        Some({
+          errorCode: "Forbidden",
+          errorDetail: `${Spec.name}.${commandName(
+              command,
+            )}: the caller holds no role this command's rule admits`,
+        })
+      true
+    }
+
+  // Every given event is the command's own history here, so all of them count.
+  // The caller is consumed: the next scenario starts with no claim.
+  let refuses = (history: array<Spec.history>, command: Spec.command): bool => {
+    let who = caller.contents
+    caller := None
+    refusal := None
+    let claim = who->Option.map(w => w.claim)
+    if who->Option.mapOr(false, refusedByRule(_, command)) {
+      true
+    } else if ownerFieldsByEventType->Dict.keysToArray->Array.length == 0 {
+      false
+    } else {
+      let owners = history->Array.reduce([], (owners, event) => {
+        let (eventType, data) = event->Message.encode(Spec.historySchema)->Message.splitMessage
+        switch ownerFieldsByEventType->Dict.get(eventType) {
+        | Some(fields) => owners->Reventless.OwnerScope.recordOwners(~fields, data)
+        | None => owners
+        }
+      })
+      refusal :=
+        Reventless.OwnerScope.decideActing(~claim, ~recordedOwners=Some(owners))
+        ->CommandTopic_Helpers.ownershipRefusal(~component=Spec.name, ~command=commandName(command))
+        ->Option.map(r => r.rejected)
+      refusal.contents->Option.isSome
+    }
+  }
+
+  let encRefusal = (r: CommandTopic_Helpers.rejectedResult) =>
+    JSON.Encode.object(
+      Dict.fromArray([
+        ("errorCode", JSON.Encode.string(r.errorCode)),
+        ("errorDetail", JSON.Encode.string(r.errorDetail)),
+      ]),
+    )
+
+  // Any other `then*` after a refused command fails: `decide` never ran, so
+  // there is nothing for it to compare.
+  let unexpectedRefusal = (): option<Outcome.outcome> =>
+    refusal.contents->Option.map(r =>
+      Outcome.fail(
+        ErrorMismatch({expected: JSON.Encode.null, actual: Some(encRefusal(r)), actualEvents: []}),
+      )
+    )
+
+  let thenRefused = (~encEvents, ~decided: option<JSON.t>, events) =>
+    switch refusal.contents {
+    | Some(_) => Outcome.pass
+    | None =>
+      Outcome.fail(
+        ErrorMismatch({
+          expected: JSON.Encode.object(
+            Dict.fromArray([("errorCode", JSON.Encode.string("Forbidden"))]),
+          ),
+          actual: decided,
+          actualEvents: encEvents(events),
+        }),
+      )
+    }
+}
+
 // ---------------------------------------------------------------------------
 // Slice form — replaces the legacy `StateChangeSlice_GWT`.
 // ---------------------------------------------------------------------------
@@ -40,6 +238,9 @@ module type BehaviorSpec = {
 
   @schema
   type event
+
+  type role
+  let commandAuthorization: command => Reventless.Authorization.rule<role>
 }
 
 module type Behavior = {
@@ -60,6 +261,10 @@ module type T = {
 
   let givenEvents: array<Spec.consumedEvent> => array<Spec.consumedEvent>
 
+  // Who issues the next `whenCmd`; see `Caller`.
+  module Caller: Callers with type role = Spec.role
+  let asCaller: (array<Spec.consumedEvent>, Caller.t) => array<Spec.consumedEvent>
+
   let whenCmd: (array<Spec.consumedEvent>, Spec.command) => array<Spec.event>
 
   let thenEvent: (array<Spec.event>, Spec.event) => Outcome.outcome
@@ -68,6 +273,9 @@ module type T = {
   let thenEventWithError: (array<Spec.event>, Spec.event, Spec.error) => Outcome.outcome
   let thenEventsWithError: (array<Spec.event>, array<Spec.event>, Spec.error) => Outcome.outcome
   let thenError: (array<Spec.event>, Spec.error) => Outcome.outcome
+  // Refused before `decide`: by the command's rule, or because the caller does not
+  // own what it acts on.
+  let thenRefused: array<Spec.event> => Outcome.outcome
 
   // DCB optimistic-concurrency assertions.
   let thenAppendsConditionedOn: (array<Spec.event>, Reventless.DcbTag.query) => Outcome.outcome
@@ -242,6 +450,20 @@ module Make = (Spec: BehaviorSpec, Behavior: Behavior with module Spec := Spec):
   module Core = AssertionCore(Spec)
   let errors = Core.errors
 
+  module Caller = Callers({
+    type role = Spec.role
+  })
+  module Guard = Acting({
+    let name = Spec.name
+    type history = Spec.consumedEvent
+    let historySchema = Spec.consumedEventSchema
+    type command = Spec.command
+    let commandSchema = Spec.commandSchema
+    type role = Spec.role
+    let commandAuthorization = Spec.commandAuthorization
+  })
+  let asCaller = Guard.asCaller
+
   // DCB append-condition derived inside [whenCmd]; [None] until first call.
   let derivedCondition: ref<option<Reventless.DcbTag.appendCondition>> = ref(None)
 
@@ -379,12 +601,15 @@ module Make = (Spec: BehaviorSpec, Behavior: Behavior with module Spec := Spec):
       }
     }
 
-    let state = currentState(history)
-    switch Behavior.decide(state, command) {
-    | Ok(events) => events
-    | Error(error) =>
-      errors := [error]
+    if Guard.refuses(history, command) {
       []
+    } else {
+      switch Behavior.decide(currentState(history), command) {
+      | Ok(events) => events
+      | Error(error) =>
+        errors := [error]
+        []
+      }
     }
   }
 
@@ -392,7 +617,17 @@ module Make = (Spec: BehaviorSpec, Behavior: Behavior with module Spec := Spec):
   let whenCmd = (history, cmd) => history->exec(cmd)
 
   let checkAppendCondition = (): option<Outcome.outcome> =>
-    appendConditionFailure.contents->Option.map(m => Outcome.fail(m))
+    switch appendConditionFailure.contents {
+    | Some(m) => Some(Outcome.fail(m))
+    | None => Guard.unexpectedRefusal()
+    }
+
+  let thenRefused = events =>
+    Guard.thenRefused(
+      ~encEvents=Core.encEvents,
+      ~decided=errors.contents->Array.get(0)->Option.map(Core.encError),
+      events,
+    )
 
   // The append-condition footgun is surfaced before the shared comparison core
   // runs; `thenAppends*` below bypass it deliberately.
@@ -493,6 +728,8 @@ module type AggregateSpec = {
   type event
   @schema
   type error
+  type role
+  let commandAuthorization: command => Reventless.Authorization.rule<role>
 }
 
 module type AggregateT = {
@@ -503,6 +740,10 @@ module type AggregateT = {
 
   let givenEvents: array<Spec.event> => array<Spec.event>
 
+  // Who issues the next `whenCmd`; see `Caller`.
+  module Caller: Callers with type role = Spec.role
+  let asCaller: (array<Spec.event>, Caller.t) => array<Spec.event>
+
   let whenCmd: (array<Spec.event>, Spec.command) => array<Spec.event>
 
   let thenEvent: (array<Spec.event>, Spec.event) => Outcome.outcome
@@ -521,6 +762,9 @@ module type AggregateT = {
   ) => Outcome.outcome
   let thenEventsWithError: (array<Spec.event>, array<Spec.event>, Spec.error) => Outcome.outcome
   let thenError: (array<Spec.event>, Spec.error) => Outcome.outcome
+  // Refused before `decide`: by the command's rule, or because the caller does not
+  // own what it acts on.
+  let thenRefused: array<Spec.event> => Outcome.outcome
 }
 
 module MakeFromAggregate = (Spec: AggregateSpec, Behavior: Behavior.T with module Spec = Spec): (
@@ -536,14 +780,31 @@ module MakeFromAggregate = (Spec: AggregateSpec, Behavior: Behavior.T with modul
   module Core = AssertionCore(Spec)
   let errors = Core.errors
 
+  module Caller = Callers({
+    type role = Spec.role
+  })
+  module Guard = Acting({
+    let name = Spec.name
+    type history = Spec.event
+    let historySchema = Spec.eventSchema
+    type command = Spec.command
+    let commandSchema = Spec.commandSchema
+    type role = Spec.role
+    let commandAuthorization = Spec.commandAuthorization
+  })
+  let asCaller = Guard.asCaller
+
   let exec = (history, command): array<Spec.event> => {
     errors := []
-    let state = currentState(history)
-    switch Behavior.decide(state, command) {
-    | Ok(events) => events
-    | Error(error) =>
-      errors := [error]
+    if Guard.refuses(history, command) {
       []
+    } else {
+      switch Behavior.decide(currentState(history), command) {
+      | Ok(events) => events
+      | Error(error) =>
+        errors := [error]
+        []
+      }
     }
   }
 
@@ -551,20 +812,34 @@ module MakeFromAggregate = (Spec: AggregateSpec, Behavior: Behavior.T with modul
   let whenCmd = (history, cmd) => history->exec(cmd)
 
   // The aggregate flavour has no append-condition footgun, so the shared core's
-  // comparisons are exposed directly; only `thenCompare*` (custom equality) is
-  // specific to this surface.
-  let thenEvents = Core.compareEvents
-  let thenCompareEvents = Core.compareEventsWith
+  // comparisons are exposed directly once a refusal has been ruled out; only
+  // `thenCompare*` (custom equality) is specific to this surface.
+  let unlessRefused = (events, compare) =>
+    switch Guard.unexpectedRefusal() {
+    | Some(o) => o
+    | None => compare(events)
+    }
+  let thenEvents = (events, expected) => events->unlessRefused(Core.compareEvents(_, expected))
+  let thenCompareEvents = (events, expected, cmp) =>
+    events->unlessRefused(Core.compareEventsWith(_, expected, cmp))
   let thenEvent = (events, expectedEvent) => thenEvents(events, [expectedEvent])
   let thenCompareEvent = (events, expectedEvent, cmp) =>
     thenCompareEvents(events, [expectedEvent], cmp)
-  let thenNoEvent = Core.compareNoEvent
+  let thenNoEvent = events => events->unlessRefused(Core.compareNoEvent)
 
-  let thenError = (events, expectedError) => Core.matchesError(events, [], expectedError)
+  let thenError = (events, expectedError) =>
+    events->unlessRefused(Core.matchesError(_, [], expectedError))
 
   let thenEventWithError = (events, expectedEvent, expectedError) =>
-    Core.matchesError(events, [expectedEvent], expectedError)
+    events->unlessRefused(Core.matchesError(_, [expectedEvent], expectedError))
 
   let thenEventsWithError = (events, expectedEvents, expectedError) =>
-    Core.matchesError(events, expectedEvents, expectedError)
+    events->unlessRefused(Core.matchesError(_, expectedEvents, expectedError))
+
+  let thenRefused = events =>
+    Guard.thenRefused(
+      ~encEvents=Core.encEvents,
+      ~decided=errors.contents->Array.get(0)->Option.map(Core.encError),
+      events,
+    )
 }