@reventlessdev/reventless-core 3.0.0-alpha.284 → 3.0.0-alpha.286

package/CHANGELOG.md

@@ -3,6 +3,29 @@
 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.286 (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.
+
+
+
+# 3.0.0-alpha.285 (2026-10-01)
+
+### Features
+
+* **spec, aws, core, local:** an app declares its environments, and every deployment records its commit ([c7cc925](https://github.com/ReventlessDev/reventless-core/commit/c7cc92573e97742b681a9000cea0bdfd6e9a33fc))
+* **spec, core, gwt, ppx:** a command acts only on what its caller owns ([2636f0e](https://github.com/ReventlessDev/reventless-core/commit/2636f0ee44797ee2c0b0c40a7107cf306113173f))
+
+
 # 3.0.0-alpha.284 (2026-09-29)
 
 **Note:** Version bump only for package @reventlessdev/reventless-core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.284",
+  "version": "3.0.0-alpha.286",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -30,20 +30,20 @@
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.34",
     "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.20",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.20",
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.15",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.11",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.20",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.22",
-    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.15",
     "@reventlessdev/rescript-ssh2": "2.0.0-alpha.21",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.182",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.38",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.1",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.154"
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.38",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.156",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.184"
   },
   "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/Message.res.mjs

@@ -381,6 +381,8 @@ function combineMessage(typ, data) {
 
 let serviceSchema = Message$Reventless.serviceSchema;
 
+let CallerClaim = Message$Reventless.CallerClaim;
+
 let metaSchema = Message$Reventless.metaSchema;
 
 let contextSchema = Message$Reventless.contextSchema;
@@ -402,6 +404,7 @@ let InvalidEvent = Message$Reventless.InvalidEvent;
 export {
   logger,
   serviceSchema,
+  CallerClaim,
   metaSchema,
   contextSchema,
   statusChangeSchema,

package/src/Roles.res

@@ -0,0 +1,3 @@
+// The roles the platform's own components require. `Admin` is `Reventless.Role.admin`,
+// joined by name like any plugin's role.
+type t = Admin

package/src/Roles.res.mjs

@@ -0,0 +1,2 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+/* This output is empty. Its source's type definitions, externals and/or unused code got optimized away. */

package/src/admin/Platform_AdminGroup.res

@@ -0,0 +1,12 @@
+// The administrator group as the host shell reads it from `config.json`: the
+// group the platform gates its admin API on, from the same role-to-group
+// resolution as the server, so the two cannot disagree. Written only where the
+// deployment maps the administrator role away from its own name; the shell
+// reads an absent key as `Admin`, so a default deployment's file is unchanged.
+
+let configKey = "adminGroup"
+
+let configEntry = (): option<(string, JSON.t)> => {
+  let group = Reventless.Role.adminGroup()
+  group == (Reventless.Role.admin :> string) ? None : Some((configKey, JSON.Encode.string(group)))
+}

package/src/admin/Platform_AdminGroup.res.mjs

@@ -0,0 +1,23 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Role$Reventless from "@reventlessdev/reventless-spec/src/types/Role.res.mjs";
+
+let configKey = "adminGroup";
+
+function configEntry() {
+  let group = Role$Reventless.adminGroup();
+  if (group === Role$Reventless.admin) {
+    return;
+  } else {
+    return [
+      configKey,
+      group
+    ];
+  }
+}
+
+export {
+  configKey,
+  configEntry,
+}
+/* Role-Reventless Not a pure module */

package/src/admin/Platform_Admin_Structure.res

@@ -37,7 +37,8 @@ let pluginCommands: array<commandDef> = Plugin_Structure.extractCommandDefs(
   ~isAggregate=true,
   ~mutationFieldFor=variantName =>
     Api_Naming.adminField(~name=PluginSpec.name ++ "_" ++ variantName),
-  ~commandAuthorization=PluginSpec.commandAuthorization->Obj.magic,
+  ~commandAuthorization=command =>
+    PluginSpec.commandAuthorization(command->Obj.magic)->Reventless.Authorization.named,
   ~commandTransition=PluginSpec.commandTransition->Obj.magic,
   commandSchema,
 )
@@ -57,16 +58,19 @@ let pluginAggregate: writableDef = {
   chapter: None,
 }
 
-let pluginReadModel: queryableDef = Plugin_Structure.queryableDefFromSpec(
-  ~plugin=pluginId,
-  ~name=PluginsReadModelSpec.name,
-  ~stateSchema=PluginsReadModelSpec.stateSchema->S.castToUnknown,
-  ~authorization=PluginsReadModelSpec.authorization,
-  ~linkedWriteSide=["Plugin"],
-)
+// Functions, not values: the view's access keys are the group the platform maps
+// the administrator role to, and this module is evaluated before a root maps it.
+let pluginReadModel = (): queryableDef =>
+  Plugin_Structure.queryableDefFromSpec(
+    ~plugin=pluginId,
+    ~name=PluginsReadModelSpec.name,
+    ~stateSchema=PluginsReadModelSpec.stateSchema->S.castToUnknown,
+    ~authorization=PluginsReadModelSpec.authorization->Reventless.Authorization.named,
+    ~linkedWriteSide=["Plugin"],
+  )
 
-let structure: pluginStructure = {
-  readModels: [pluginReadModel],
+let structure = (): pluginStructure => {
+  readModels: [pluginReadModel()],
   stateViewSlices: [],
   stateChangeSlices: [],
   aggregates: [pluginAggregate],

package/src/admin/Platform_Admin_Structure.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Authorization$Reventless from "@reventlessdev/reventless-spec/src/types/Authorization.res.mjs";
 import * as Api_Naming$ReventlessCore from "../components/Api/Api_Naming.res.mjs";
 import * as PluginSpec$ReventlessCore from "../plugin/lifecycle/PluginSpec.res.mjs";
 import * as Plugin_Structure$ReventlessCore from "../plugin/component/Plugin_Structure.res.mjs";
@@ -7,7 +8,7 @@ import * as PluginsReadModelSpec$ReventlessCore from "../plugin/lifecycle/Plugin
 
 let pluginId = "Platform";
 
-let pluginCommands = Plugin_Structure$ReventlessCore.extractCommandDefs(undefined, true, undefined, variantName => Api_Naming$ReventlessCore.adminField(PluginSpec$ReventlessCore.name + "_" + variantName), PluginSpec$ReventlessCore.commandAuthorization, PluginSpec$ReventlessCore.commandTransition, undefined, PluginSpec$ReventlessCore.commandSchema);
+let pluginCommands = Plugin_Structure$ReventlessCore.extractCommandDefs(undefined, true, undefined, variantName => Api_Naming$ReventlessCore.adminField(PluginSpec$ReventlessCore.name + "_" + variantName), command => Authorization$Reventless.named(PluginSpec$ReventlessCore.commandAuthorization(command)), PluginSpec$ReventlessCore.commandTransition, undefined, PluginSpec$ReventlessCore.commandSchema);
 
 let pluginAggregate_producedEventTypes = [];
 
@@ -31,39 +32,27 @@ let pluginAggregate = {
   chapter: undefined
 };
 
-let pluginReadModel = Plugin_Structure$ReventlessCore.queryableDefFromSpec(pluginId, PluginsReadModelSpec$ReventlessCore.name, PluginsReadModelSpec$ReventlessCore.stateSchema, PluginsReadModelSpec$ReventlessCore.authorization, undefined, undefined, ["Plugin"], undefined);
-
-let structure_readModels = [pluginReadModel];
-
-let structure_stateViewSlices = [];
-
-let structure_stateChangeSlices = [];
-
-let structure_aggregates = [pluginAggregate];
-
-let structure_automationSlices = [];
-
-let structure_outboundTranslationSlices = [];
-
-let structure_inboundTranslationSlices = [];
-
-let structure_extensions = [];
+function pluginReadModel() {
+  return Plugin_Structure$ReventlessCore.queryableDefFromSpec(pluginId, PluginsReadModelSpec$ReventlessCore.name, PluginsReadModelSpec$ReventlessCore.stateSchema, Authorization$Reventless.named(PluginsReadModelSpec$ReventlessCore.authorization), undefined, undefined, ["Plugin"], undefined);
+}
 
-let structure = {
-  readModels: structure_readModels,
-  stateViewSlices: structure_stateViewSlices,
-  stateChangeSlices: structure_stateChangeSlices,
-  aggregates: structure_aggregates,
-  automationSlices: structure_automationSlices,
-  outboundTranslationSlices: structure_outboundTranslationSlices,
-  inboundTranslationSlices: structure_inboundTranslationSlices,
-  extensions: structure_extensions,
-  extensionPoints: undefined,
-  requiredStores: undefined,
-  requiredStoreDeclarations: undefined,
-  requiredCapabilities: undefined,
-  traitDeclarations: undefined
-};
+function structure() {
+  return {
+    readModels: [pluginReadModel()],
+    stateViewSlices: [],
+    stateChangeSlices: [],
+    aggregates: [pluginAggregate],
+    automationSlices: [],
+    outboundTranslationSlices: [],
+    inboundTranslationSlices: [],
+    extensions: [],
+    extensionPoints: undefined,
+    requiredStores: undefined,
+    requiredStoreDeclarations: undefined,
+    requiredCapabilities: undefined,
+    traitDeclarations: undefined
+  };
+}
 
 let internalPluginDefinition = {
   id: pluginId + "@INTERNAL",

package/src/components/Aggregate/Aggregate_Callback.res

@@ -57,10 +57,29 @@ module Make = (
   let updateMeta = (command': Message.command'<'id, 'command>) =>
     Message.deriveMeta(~parent=command'.meta)
 
+  // The events whose `@owner` field names who owns this aggregate. Empty for an
+  // aggregate that marks none, and then nothing is enforced.
+  let ownerFieldsByEventType = Reventless.Owner.fieldNamesByVariant(
+    Spec.eventSchema->S.castToUnknown,
+  )
+  let actsOnOwned = ownerFieldsByEventType->Dict.keysToArray->Array.length > 0
+
+  let recordEventOwners = (owners, event: Spec.event) =>
+    if actsOnOwned {
+      let (eventType, data) = event->Message.encode(Spec.eventSchema)->Message.splitMessage
+      switch ownerFieldsByEventType->Dict.get(eventType) {
+      | Some(fields) => owners->Reventless.OwnerScope.recordOwners(~fields, data)
+      | None => owners
+      }
+    } else {
+      owners
+    }
+
   // Per-command outcome carried through the fold, paired with the originating reference and meta.
   type cmdOutcome =
     | CmdOk(array<Spec.event>)
     | CmdRejected({errorCode: string, errorDetail: string})
+    | CmdRefused(CommandTopic_Helpers.ownershipRefusal)
 
   // Folds a single command into the running accumulator: (currentState, perCommandOutcomes).
   // A domain rejection from Behavior.decide is recorded as `CmdRejected` (no state change,
@@ -69,9 +88,16 @@ module Make = (
   //
   // `~seq` is the replayed sequence number the batch decides from, carried in so
   // the line below can name the state rather than serialise it.
+  //
+  // `owners` are the distinct owners the stream records so far, including any a
+  // command earlier in the same batch just recorded.
   let processCommand = (~seq: int) =>
     (
-      (state, outcomes): (Behavior.state, array<(string, cmdOutcome, Message.meta)>),
+      (state, owners, outcomes): (
+        Behavior.state,
+        array<string>,
+        array<(string, cmdOutcome, Message.meta)>,
+      ),
       topicItem: CommandTopic.topicItem<Message.command'<Spec.Id.t, Spec.command>>,
     ) => {
       let {reference, command: command'} = topicItem
@@ -81,33 +107,57 @@ module Make = (
       // history, so serialising it here makes the line's size a function of how
       // long the system has been in use. The state at decision time is a
       // debugger's subject, not a log's.
-      let cmdName =
-        command'.command
-        ->Message.encode(Spec.commandSchema)
-        ->Message.variantNameOfJson
-        ->LogFormat.bold
+      let cmdVariant =
+        command'.command->Message.encode(Spec.commandSchema)->Message.variantNameOfJson
+      let cmdName = cmdVariant->LogFormat.bold
       EffectLogger.logDebug(
         ~comp,
         `deciding: id=${id} seq=${seq->Int.toString} cmd=${cmdName}`,
       )->Effect.runSync
-      switch Behavior.decide(state, command'.command) {
-      | Ok(generatedEvents) =>
-        let newState = generatedEvents->Array.reduce(state, Behavior.evolve)
-        (newState, Array.concat(outcomes, [(reference, CmdOk(generatedEvents), meta)]))
-      | Error(error) =>
-        let errorJson = error->Message.encode(Spec.errorSchema)
-        let errorCode = errorJson->Message.variantNameOfJson
-        // Strip the TAG so detail carries only the rejection payload (empty for unit errors).
-        let (_, payloadDict) = errorJson->Message.splitMessage
-        let errorDetail =
-          payloadDict->Dict.toArray->Array.length == 0
-            ? ""
-            : payloadDict->JSON.Encode.object->JSON.stringify
-        EffectLogger.logError(
-          ~comp,
-          `decide rejected: ${errorCode} ${errorDetail} id=${id}`,
+      // Before `decide`: an owner-marked aggregate refuses a caller who does not
+      // own the stream.
+      let refusal = actsOnOwned
+        ? Reventless.OwnerScope.decideActing(
+            ~claim=command'.meta.callerClaim,
+            ~recordedOwners=Some(owners),
+          )->CommandTopic_Helpers.ownershipRefusal(~component=Spec.name, ~command=cmdVariant)
+        : None
+      switch refusal {
+      | Some(refused) =>
+        let line = `refused: ${refused.rejected.errorDetail} id=${id}`
+
+        (
+          refused.isDefect ? EffectLogger.logError(~comp, line) : EffectLogger.logWarn(~comp, line)
         )->Effect.runSync
-        (state, Array.concat(outcomes, [(reference, CmdRejected({errorCode, errorDetail}), meta)]))
+        (state, owners, Array.concat(outcomes, [(reference, CmdRefused(refused), meta)]))
+      | None =>
+        switch Behavior.decide(state, command'.command) {
+        | Ok(generatedEvents) =>
+          let newState = generatedEvents->Array.reduce(state, Behavior.evolve)
+          (
+            newState,
+            generatedEvents->Array.reduce(owners, recordEventOwners),
+            Array.concat(outcomes, [(reference, CmdOk(generatedEvents), meta)]),
+          )
+        | Error(error) =>
+          let errorJson = error->Message.encode(Spec.errorSchema)
+          let errorCode = errorJson->Message.variantNameOfJson
+          // Strip the TAG so detail carries only the rejection payload (empty for unit errors).
+          let (_, payloadDict) = errorJson->Message.splitMessage
+          let errorDetail =
+            payloadDict->Dict.toArray->Array.length == 0
+              ? ""
+              : payloadDict->JSON.Encode.object->JSON.stringify
+          EffectLogger.logError(
+            ~comp,
+            `decide rejected: ${errorCode} ${errorDetail} id=${id}`,
+          )->Effect.runSync
+          (
+            state,
+            owners,
+            Array.concat(outcomes, [(reference, CmdRejected({errorCode, errorDetail}), meta)]),
+          )
+        }
       }
     }
 
@@ -115,8 +165,8 @@ module Make = (
 
   // In-process replay cache (per warm Lambda instance, per aggregate — the
   // functor instance owns the cache, so the event log is implicit and the key
-  // is just the aggregate id). Holds the `(state, sequenceNr)` the previous
-  // command batch for that id left behind.
+  // is just the aggregate id). Holds the `(state, sequenceNr, owners)` the
+  // previous command batch for that id left behind.
   //
   // On a hit, `replayProcessAppend` skips the event-log replay entirely and
   // decides on the cached state; after a successful append it stores the
@@ -129,7 +179,9 @@ module Make = (
   // the fixed capacity (a per-aggregate knob is a future refinement — see
   // docs/plans/done/aggregate-snapshotting.md).
   let replayCacheCapacity = 100
-  let replayCache: Lru.t<string, (Behavior.state, int)> = Lru.make(~capacity=replayCacheCapacity)
+  let replayCache: Lru.t<string, (Behavior.state, int, array<string>)> = Lru.make(
+    ~capacity=replayCacheCapacity,
+  )
 
   let resetCache = () => replayCache->Lru.clear
 
@@ -139,7 +191,17 @@ module Make = (
   // one every `interval` events. Snapshots are a read optimization only — the
   // OCC append remains the sole consistency primitive, so a missing, drifted,
   // or corrupt snapshot degrades silently to full replay.
-  let snapshotConfig = Behavior.snapshot
+  //
+  // Off for an owner-marked aggregate: a snapshot holds the state alone, so a
+  // replay seeded from one would never see the event that recorded the owner,
+  // and the ownership check would pass every caller.
+  let snapshotConfig = actsOnOwned ? None : Behavior.snapshot
+  if actsOnOwned && Behavior.snapshot->Option.isSome {
+    EffectLogger.logWarn(
+      ~comp,
+      "snapshots disabled: this aggregate records an @owner, which a snapshot does not carry",
+    )->Effect.runSync
+  }
 
   // Structural hash of the state schema, computed once. Stored on every written
   // snapshot and compared on read: a snapshot whose hash differs from the
@@ -183,8 +245,8 @@ module Make = (
 
   // Cold read (in-process cache miss): when snapshots are enabled, seed from the
   // latest persisted snapshot (hash-gated) and replay only the events after it;
-  // otherwise replay full history from seq 0. Returns `(state, sequenceNr)` where
-  // sequenceNr is the total event count (the OCC condition for the next append).
+  // otherwise replay full history from seq 0. Returns `(state, sequenceNr, owners)`
+  // where sequenceNr is the total event count (the OCC condition for the next append).
   let coldReadState = id => {
     let idStr = id->Spec.Id.toString
     let seedEffect = switch snapshotConfig {
@@ -220,8 +282,12 @@ module Make = (
     }
     seedEffect->Effect.flatMap(((seedState, seedSeq)) =>
       Ops.eventLog.replayStream(id, ~fromSeq=seedSeq)
-      ->Stream.runFold((seedState, seedSeq), ((st, n), ev) => (Behavior.evolve(st, ev), n + 1))
-      ->Effect.tap(((_, n)) => {
+      ->Stream.runFold((seedState, seedSeq, []), ((st, n, owners), ev) => (
+        Behavior.evolve(st, ev),
+        n + 1,
+        owners->recordEventOwners(ev),
+      ))
+      ->Effect.tap(((_, n, _)) => {
         let detail =
           seedSeq > 0
             ? `(snapshot@${seedSeq->Int.toString}, ${(n - seedSeq)->Int.toString} delta event(s))`
@@ -305,6 +371,14 @@ module Make = (
           {errorCode, errorDetail},
         )
         Ok(reference)
+      | CmdRefused({rejected}) =>
+        CommandTopic_Helpers.reportRejected(
+          ~component=Spec.name,
+          ~cause=AccessRefusal,
+          reference,
+          rejected,
+        )
+        Ok(reference)
       | CmdOk(_) if appendSucceeded =>
         CommandTopic_Helpers.reportAccepted(
           ~component=Spec.name,
@@ -339,24 +413,27 @@ module Make = (
     // path (`coldReadState`): seed from the persisted snapshot when enabled, else
     // full replay.
     let readState = switch replayCache->Lru.get(idStr) {
-    | Some((state, seqNr)) =>
+    | Some((state, seqNr, owners)) =>
       EffectLogger.logInfo(
         ~comp,
         `replay skipped (cached): id=${idStr}, seq=${seqNr->Int.toString}`,
-      )->Effect.map(_ => (state, seqNr))
+      )->Effect.map(_ => (state, seqNr, owners))
     | None => coldReadState(id)
     }
 
-    readState->Effect.flatMap(((initialState, sequenceNr)) => {
-      let (finalState, outcomes) =
-        topicItemsForId->Array.reduce((initialState, []), processCommand(~seq=sequenceNr))
+    readState->Effect.flatMap(((initialState, sequenceNr, initialOwners)) => {
+      let (finalState, finalOwners, outcomes) =
+        topicItemsForId->Array.reduce(
+          (initialState, initialOwners, []),
+          processCommand(~seq=sequenceNr),
+        )
 
       let eventsToAppend =
         outcomes
         ->Array.map(((_reference, outcome, meta)) =>
           switch outcome {
           | CmdOk(events) => events->Array.map(event => {Message.id, meta, event})
-          | CmdRejected(_) => []
+          | CmdRejected(_) | CmdRefused(_) => []
           }
         )
         ->Array.flat
@@ -365,7 +442,7 @@ module Make = (
       | [] =>
         // Nothing appended, but the read snapshot is valid — keep it warm for
         // the next command (also refreshes recency on a cache hit).
-        replayCache->Lru.put(idStr, (initialState, sequenceNr))
+        replayCache->Lru.put(idStr, (initialState, sequenceNr, initialOwners))
         let perRef = reportFinalOutcomes(
           outcomes,
           ~entityId=idStr,
@@ -392,7 +469,7 @@ module Make = (
             // The post-decide fold state IS the post-append replay result;
             // cache it so the next command for this id skips the replay.
             let newSeq = sequenceNr + generatedEvents'->Array.length
-            replayCache->Lru.put(idStr, (finalState, newSeq))
+            replayCache->Lru.put(idStr, (finalState, newSeq, finalOwners))
             // Persist a snapshot if this append crossed an interval boundary
             // (fire-and-forget — never blocks or fails the command).
             maybeWriteSnapshot(id, idStr, ~oldSeq=sequenceNr, ~newSeq, finalState)