@reventlessdev/reventless-spec 3.0.0-alpha.155 → 3.0.0-alpha.157

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.
 
+# 3.0.0-alpha.157 (2026-10-01)
+
+### Bug Fixes
+
+* check a plugin's roles against the user pool's groups ([ddb3c42](https://github.com/ReventlessDev/reventless-core/commit/ddb3c422b7226a19800e781abd5f03af18867007))
+
+
+# 3.0.0-alpha.156 (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.155 (2026-10-01)
 
 ### Features

package/package.json

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

package/src/components/Aggregate.res

@@ -55,12 +55,15 @@ module type Spec = {
       the npm specifier for runtime dynamic imports. */
   let moduleUrl: string
 
+  /** The roles this spec's rules name: its plugin's `Roles.t`, which the PPX
+      supplies; `Role.name` where the plugin declares none. */
+  type role
   /** Authorization rule evaluated at the GraphQL resolver entry before any
       command is dispatched. Auto-injected by `@@reventless.spec` and on
       structurally-detected inline spec modules — defaults to
       `AllowAuthenticated`; override at the file/module level with
       `@@reventless.authorize(<rule>)`. */
-  let commandAuthorization: command => Authorization.permission
+  let commandAuthorization: command => Authorization.rule<role>
 
   /** The lifecycle enum this component's commands move a row through — the
       linked view's own, e.g. `type lifecycleState = Customers.accountStatus`.

package/src/components/InboundTranslationSlice.res

@@ -56,11 +56,14 @@ module type Spec = {
       Auto-injected by `@@reventless.spec` defaulting to `None` — set it to name the box. */
   let externalSystem: option<string>
 
+  /** The roles this spec's rules name: its plugin's `Roles.t`, which the PPX
+      supplies; `Role.name` where the plugin declares none. */
+  type role
   /** Authorization rule evaluated at the GraphQL resolver entry before any
       external input is translated. Auto-injected by `@@reventless.spec` and
       on structurally-detected inline spec modules — defaults to
       `AllowAuthenticated`. */
-  let commandAuthorization: command => Authorization.permission
+  let commandAuthorization: command => Authorization.rule<role>
 
   /** The lifecycle enum this component's commands move a row through — the
       linked view's own, e.g. `type lifecycleState = Customers.accountStatus`.

package/src/components/Plugin.res

@@ -194,6 +194,10 @@ type commandDef = {
   /** Access keys — any one of them — a caller needs to be *offered* this command.
       A hint derived from the server's rule, never the refusal itself. */
   requiredAccess: option<array<string>>,
+  /** The roles `requiredAccess` was mapped from, as the rule names them. Absent
+      where the rule names none; read by the deploy check that every role maps to
+      a group the platform provides. */
+  requiredRoles?: array<string>,
   /** The `@owner` command field the server stamps with the caller's identity; a
       client omits it from a form, since whatever it collects is discarded. */
   ownerField: option<string>,
@@ -249,6 +253,8 @@ type queryableDef = {
   /** Access keys — any one of them — a caller needs to be *offered* this view. A
       denied read comes back empty rather than erroring, hence the hint. */
   requiredAccess: option<array<string>>,
+  /** The roles `requiredAccess` was mapped from; see `commandDef`. */
+  requiredRoles?: array<string>,
 }
 
 /** One emitted event of a write side. `name` is the variant name, `schema` its
@@ -326,6 +332,8 @@ type inboundTranslationSliceDef = {
   externalSystem: option<string>,
   /** Chapter grouping band — see `queryableDef.chapter`. */
   chapter: option<string>,
+  /** The roles any of its commands' rules name; see `commandDef`. */
+  requiredRoles?: array<string>,
 }
 
 /** A published event of an extension point and the internal events producing it.

package/src/components/Plugin.res.mjs

@@ -102,6 +102,7 @@ let commandDefSchema = Sury.$schema(s => ({
   allowedStatesSource: s.m(Sury.$option(Sury.string)),
   apiExposed: s.m(Sury.$option(Sury.boolean)),
   requiredAccess: s.m(Sury.$option(Sury.array(Sury.string))),
+  requiredRoles: s.m(Sury.$option(Sury.array(Sury.string))),
   ownerField: s.m(Sury.$option(Sury.string))
 }));
 
@@ -124,7 +125,8 @@ let queryableDefSchema = Sury.$schema(s => ({
   singleQueryField: s.m(Sury.$option(Sury.string)),
   idField: s.m(Sury.$option(Sury.string)),
   idFieldSource: s.m(Sury.$option(Sury.string)),
-  requiredAccess: s.m(Sury.$option(Sury.array(Sury.string)))
+  requiredAccess: s.m(Sury.$option(Sury.array(Sury.string))),
+  requiredRoles: s.m(Sury.$option(Sury.array(Sury.string)))
 }));
 
 let eventDefSchema = Sury.$schema(s => ({
@@ -174,7 +176,8 @@ let inboundTranslationSliceDefSchema = Sury.$schema(s => ({
   commandTypes: s.m(Sury.array(Sury.string)),
   targetName: s.m(Sury.string),
   externalSystem: s.m(Sury.$option(Sury.string)),
-  chapter: s.m(Sury.$option(Sury.string))
+  chapter: s.m(Sury.$option(Sury.string)),
+  requiredRoles: s.m(Sury.$option(Sury.array(Sury.string)))
 }));
 
 let publishedEventDefSchema = Sury.$schema(s => ({

package/src/components/ReadModel.res

@@ -190,12 +190,15 @@ module type Spec = {
   /** Optional composite-key configuration. `None` for single-key tables. */
   let subIdConfig: option<subIdConfig<state>>
 
+  /** The roles this spec's rules name: its plugin's `Roles.t`, which the PPX
+      supplies; `Role.name` where the plugin declares none. */
+  type role
   /** Authorization rule evaluated at the GraphQL resolver entry before any
       query is resolved. Auto-injected by `@@reventless.spec` and on
       structurally-detected inline spec modules — defaults to
       `AllowAuthenticated`; override at the file/module level with
       `@@reventless.authorize(<rule>)`. */
-  let authorization: Authorization.permission
+  let authorization: Authorization.rule<role>
 
   /** AutoUI visibility hint. Auto-injected by `@@reventless.spec` and on
       structurally-detected inline spec modules — defaults to

package/src/components/StateChangeSlice.res

@@ -75,12 +75,15 @@ module type Spec = {
   /** Schema for the command type — used to extract DCB tags for the conditional read. */
   let commandSchema: S.t<command>
 
+  /** The roles this spec's rules name: its plugin's `Roles.t`, which the PPX
+      supplies; `Role.name` where the plugin declares none. */
+  type role
   /** Authorization rule evaluated at the GraphQL resolver entry before any
       command is dispatched. Auto-injected by `@@reventless.spec` and on
       structurally-detected inline spec modules — defaults to
       `AllowAuthenticated`; override at the file/module level with
       `@@reventless.authorize(<rule>)`. */
-  let commandAuthorization: command => Authorization.permission
+  let commandAuthorization: command => Authorization.rule<role>
 
   /** The lifecycle enum this component's commands move a row through — the
       linked view's own, e.g. `type lifecycleState = Customers.accountStatus`.

package/src/components/StateViewSlice.res

@@ -73,11 +73,14 @@ module type Spec = {
   /** Optional composite-key configuration. `None` for single-key tables. */
   let subIdConfig: option<ReadModel.subIdConfig<state>>
 
+  /** The roles this spec's rules name: its plugin's `Roles.t`, which the PPX
+      supplies; `Role.name` where the plugin declares none. */
+  type role
   /** Authorization rule evaluated at the GraphQL resolver entry before any
       query is resolved. Auto-injected by `@@reventless.spec` and on
       structurally-detected inline spec modules — defaults to
       `AllowAuthenticated`. */
-  let authorization: Authorization.permission
+  let authorization: Authorization.rule<role>
 
   /** AutoUI visibility hint. Auto-injected by `@@reventless.spec` and on
       structurally-detected inline spec modules — defaults to

package/src/generator/Codegen.res

@@ -567,12 +567,17 @@ let renderMain = (~config: Config.config): string => {
     "module Platform = ReventlessAws.Platform.Make()",
     "module " ++ name ++ " = Plugin.Make(Platform)",
     "",
-    "let default = Platform.deployPlugin(",
-    "  ~plugin=module(" ++ name ++ "),",
-    ")",
-    "",
+    // The plugin is deployed once the user pool's groups are in, for the check
+    // that every role it needs has one, which runs while `deployPlugin` builds
+    // it. A promise rather than a top-level await: Pulumi `require`s the
+    // program, which Node refuses for a module that awaits at the top level.
+    // Pulumi resolves the promise in the stack outputs.
+    "let default = ReventlessAws.Platform.loadProvidedGroups()->Promise.thenResolve(() => {",
+    "  let deployed = Platform.deployPlugin(~plugin=module(" ++ name ++ "))",
     // PostDeploy runs after the graph is registered (exports, cross-stack output).
-    "ReventlessInfra.DeployBootstrap.run(PostDeploy)",
+    "  ReventlessInfra.DeployBootstrap.run(PostDeploy)",
+    "  deployed",
+    "})",
     "",
   ]->Array.join("\n")
 }

package/src/generator/Codegen.res.mjs

@@ -365,11 +365,11 @@ function renderMain(config) {
     "module Platform = ReventlessAws.Platform.Make()",
     "module " + name + " = Plugin.Make(Platform)",
     "",
-    "let default = Platform.deployPlugin(",
-    "  ~plugin=module(" + name + "),",
-    ")",
-    "",
-    "ReventlessInfra.DeployBootstrap.run(PostDeploy)",
+    "let default = ReventlessAws.Platform.loadProvidedGroups()->Promise.thenResolve(() => {",
+    "  let deployed = Platform.deployPlugin(~plugin=module(" + name + "))",
+    "  ReventlessInfra.DeployBootstrap.run(PostDeploy)",
+    "  deployed",
+    "})",
     ""
   ].join("\n");
 }

package/src/types/AccountsManifest.res

@@ -8,7 +8,7 @@ reads it and writes back into it.
 
 Here rather than in either platform package because a manifest that works on one
 platform and silently fails on the other is the whole cost being avoided. It sits
-beside [Identity] and [AdminGroup] for the same reason those do: the vocabulary
+beside [Identity] and [Role] for the same reason those do: the vocabulary
 the two platforms share about who is signed in.
 
 🚨 **The password field is a bootstrap credential, not a stored secret.** The file
@@ -237,6 +237,28 @@ let locate = (~given: option<string>=?, ()): result<located, string> =>
     }
   }
 
+/**
+The groups the accounts here belong to: the manifest's, else the template's, else
+none. What a platform provides beyond its administrator group, for the check that
+every role a plugin needs has a group.
+
+Read, never seeded — this runs in a deploy or a start, which must not write the
+file `locate` would. The template counts because it is the cast a fresh clone
+provisions; a deploy from CI has no manifest and the same accounts to come.
+*/
+let declaredGroups = (): array<string> => {
+  let template = NodePath.join([NodeProcess.cwd(), templateName])
+  let file = NodeFs.existsSync(defaultPath())
+    ? Some(defaultPath())
+    : NodeFs.existsSync(template)
+    ? Some(template)
+    : None
+  switch file->Option.map(parseFile) {
+  | Some(Ok(entries)) => entries->Array.flatMap(e => e.groups)
+  | Some(Error(_)) | None => []
+  }
+}
+
 // ── Preparing ────────────────────────────────────────────────────────────────
 
 /** One account after preparation: what the file now declares, and whether this

package/src/types/AccountsManifest.res.mjs

@@ -246,6 +246,23 @@ function locate(given, param) {
   }
 }
 
+function declaredGroups() {
+  let template = Nodepath.join(process.cwd(), templateName);
+  let file = Nodefs.existsSync(defaultPath()) ? defaultPath() : (
+      Nodefs.existsSync(template) ? template : undefined
+    );
+  let match = Stdlib_Option.map(file, parseFile);
+  if (match !== undefined) {
+    if (match.TAG === "Ok") {
+      return match._0.flatMap(e => e.groups);
+    } else {
+      return [];
+    }
+  } else {
+    return [];
+  }
+}
+
 function prepare(file) {
   let e = parseFile(file);
   if (e.TAG !== "Ok") {
@@ -306,6 +323,7 @@ export {
   templateName,
   pathOf,
   locate,
+  declaredGroups,
   prepare,
 }
 /* entrySchema Not a pure module */

package/src/types/Authorization.res

@@ -1,22 +1,49 @@
 // Provider-agnostic authorization rules. Evaluated against the
 // `Identity.t` resolved by an `Auth_Adapter.Provider.authenticate` call.
 //
-// `array<string>` for groups (not a parameterised variant) keeps the
-// framework decoupled from any application's specific group set —
-// applications can define their own typed `group` variant and convert via
-// a thin helper, see docs/analysis/authentication-authorization.md §4.2.
+// A spec writes its rules over its plugin's own roles, `rule<Roles.t>`, so a
+// misspelled role does not compile. The framework reads them as `permission`,
+// the same rule over role names, which `Role.groupOf` maps to the group that
+// stands for each role in this deployment.
 
-@schema
-type permission =
-  | AllowGroups(array<string>)
+type rule<'role> =
+  | AllowRoles(array<'role>)
   | AllowAuthenticated
   | AllowAnonymous
   | DenyAll
 
-let isAllowed = (rule: permission, identity: Identity.t): bool =>
+/** A rule over role names: what the framework compares, maps and publishes. */
+type permission = rule<Role.name>
+
+/** A spec's rule as the framework reads it. Each role must be a case without a
+    payload, which is its name at run time; anything else is refused. */
+@module("./authorizationNamed.mjs")
+external named: rule<'role> => permission = "named"
+
+/** The roles a rule names, before mapping. */
+let rolesOf = (rule: permission): array<Role.name> =>
+  switch rule {
+  | AllowRoles(roles) => roles
+  | AllowAuthenticated | AllowAnonymous | DenyAll => []
+  }
+
+/** The groups a rule admits, mapped. */
+let groupsOf = (rule: permission): array<string> => rule->rolesOf->Array.map(Role.groupOf)
+
+/**
+Whether a rule admits a caller, given whether they are signed in and which roles
+they hold. The one decision both `isAllowed` and a GWT scenario make, so the two
+cannot read a rule differently.
+*/
+let admits = (rule: permission, ~signedIn: bool, ~holds: Role.name => bool): bool =>
   switch rule {
   | DenyAll => false
   | AllowAnonymous => true
-  | AllowAuthenticated => identity.userId !== "anonymous"
-  | AllowGroups(groups) => groups->Array.some(group => identity.groups->Array.includes(group))
+  | AllowAuthenticated => signedIn
+  | AllowRoles(roles) => roles->Array.some(holds)
   }
+
+let isAllowed = (rule: permission, identity: Identity.t): bool =>
+  admits(rule, ~signedIn=identity.userId !== "anonymous", ~holds=role =>
+    identity.groups->Array.includes(Role.groupOf(role))
+  )

package/src/types/Authorization.res.mjs

@@ -1,24 +1,31 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as Sury from "sury";
+import * as Role$Reventless from "./Role.res.mjs";
+import * as AuthorizationNamedMjs from "./authorizationNamed.mjs";
 
-let permissionSchema = Sury.union([
-  Sury.$schema(s => ({
-    TAG: "AllowGroups",
-    _0: s.m(Sury.array(Sury.string))
-  })),
-  Sury.literal("AllowAuthenticated"),
-  Sury.literal("AllowAnonymous"),
-  Sury.literal("DenyAll")
-]);
+function named(prim) {
+  return AuthorizationNamedMjs.named(prim);
+}
 
-function isAllowed(rule, identity) {
+function rolesOf(rule) {
+  if (typeof rule !== "object") {
+    return [];
+  } else {
+    return rule._0;
+  }
+}
+
+function groupsOf(rule) {
+  return rolesOf(rule).map(Role$Reventless.groupOf);
+}
+
+function admits(rule, signedIn, holds) {
   if (typeof rule === "object") {
-    return rule._0.some(group => identity.groups.includes(group));
+    return rule._0.some(holds);
   }
   switch (rule) {
     case "AllowAuthenticated" :
-      return identity.userId !== "anonymous";
+      return signedIn;
     case "AllowAnonymous" :
       return true;
     case "DenyAll" :
@@ -26,8 +33,15 @@ function isAllowed(rule, identity) {
   }
 }
 
+function isAllowed(rule, identity) {
+  return admits(rule, identity.userId !== "anonymous", role => identity.groups.includes(Role$Reventless.groupOf(role)));
+}
+
 export {
-  permissionSchema,
+  named,
+  rolesOf,
+  groupsOf,
+  admits,
   isAllowed,
 }
-/* permissionSchema Not a pure module */
+/* Role-Reventless Not a pure module */

package/src/types/OwnerScope.res

@@ -67,8 +67,10 @@ elevation would let two views disagree about who an operator is, so a caller
 scoped on one view would be unscoped on the next — and the gap would appear one
 view at a time, as views were added.
 
-Resolved as: an explicit `setElevatedGroups` wins, else the environment, else
-empty. The env fallback exists because a deployment is **two kinds of process**,
+Resolved as: an explicit `setElevatedGroups` / `setElevatedRoles` (joined) wins,
+else the environment, else empty. Roles are resolved to groups here, so the
+environment carries groups and a runtime never needs the role mapping to read it.
+The env fallback exists because a deployment is **two kinds of process**,
 not one. On a cloud provider the read predicate for a table-backed view is baked
 into resolver source by the deploy program, while stamping and the SQL-backed
 reads run later inside separate function runtimes the deploy never enters. A
@@ -86,13 +88,39 @@ external _elevatedGroupsEnv: option<string> = "process.env.REVENTLESS_ELEVATED_G
 
 let explicitElevatedGroups: ref<option<array<string>>> = ref(None)
 
+/** The elevated list stated as roles, kept unresolved so a role mapping stated
+    after it still applies. */
+let explicitElevatedRoles: ref<option<array<Role.name>>> = ref(None)
+
 /** Set the list for this process. Wins over the environment — a platform root
     that states its operator groups in code means it, and should not be silently
     overridden by a stray variable. */
 let setElevatedGroups = (groups: array<string>) => explicitElevatedGroups := Some(groups)
 
+/** The same setting stated as roles, each resolved to the group that stands for
+    it. Joined with `setElevatedGroups` where a root states both. */
+let setElevatedRoles = (roles: array<Role.name>) => explicitElevatedRoles := Some(roles)
+
 /** Forget an explicit setting and fall back to the environment again. */
-let clearElevatedGroups = () => explicitElevatedGroups := None
+let clearElevatedGroups = () => {
+  explicitElevatedGroups := None
+  explicitElevatedRoles := None
+}
+
+/** The explicit settings joined, or `None` when neither was given. */
+let explicitElevated = (): option<array<string>> =>
+  switch (explicitElevatedGroups.contents, explicitElevatedRoles.contents) {
+  | (None, None) => None
+  | (groups, roles) =>
+    Some(
+      groups
+      ->Option.getOr([])
+      ->Array.concat(roles->Option.getOr([])->Array.map(Role.groupOf))
+      ->Set.fromArray
+      ->Set.values
+      ->Array.fromIterator,
+    )
+  }
 
 /**
 Name the elevated groups only where the deployment has not already answered.
@@ -111,16 +139,23 @@ environment: the more specific statement wins, and the default only fills silenc
 🚨 **An explicit empty list is an answer, and this must not fill it in.** A
 deployment that deliberately elevates nobody has decided that; a default landing
 on top would silently re-grant the cross-owner read it withheld. That is why this
-reads [explicitElevatedGroups] rather than [elevatedGroups] — the latter answers
+reads [explicitElevated] rather than [elevatedGroups] — the latter answers
 `[]` for "nobody" and for "nothing said" alike, and those must not be treated the
 same here.
 */
 let defaultElevatedGroups = (groups: array<string>) =>
-  switch (explicitElevatedGroups.contents, _elevatedGroupsEnv) {
+  switch (explicitElevated(), _elevatedGroupsEnv) {
   | (None, None) => explicitElevatedGroups := Some(groups)
   | _ => ()
   }
 
+/** `defaultElevatedGroups` stated as roles, resolved when read. */
+let defaultElevatedRoles = (roles: array<Role.name>) =>
+  switch (explicitElevated(), _elevatedGroupsEnv) {
+  | (None, None) => explicitElevatedRoles := Some(roles)
+  | _ => ()
+  }
+
 let parseElevatedGroups = (raw: string): array<string> =>
   raw
   ->String.split(",")
@@ -136,7 +171,7 @@ appearing later in a process still takes effect. Reading a raw ref would have
 frozen whichever half happened to be consulted first.
 */
 let elevatedGroups = (): array<string> =>
-  switch explicitElevatedGroups.contents {
+  switch explicitElevated() {
   | Some(groups) => groups
   | None =>
     switch _elevatedGroupsEnv {

package/src/types/OwnerScope.res.mjs

@@ -3,6 +3,7 @@
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Role$Reventless from "./Role.res.mjs";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as Identity$Reventless from "./Identity.res.mjs";
 
@@ -14,16 +15,34 @@ let explicitElevatedGroups = {
   contents: undefined
 };
 
+let explicitElevatedRoles = {
+  contents: undefined
+};
+
 function setElevatedGroups(groups) {
   explicitElevatedGroups.contents = groups;
 }
 
+function setElevatedRoles(roles) {
+  explicitElevatedRoles.contents = roles;
+}
+
 function clearElevatedGroups() {
   explicitElevatedGroups.contents = undefined;
+  explicitElevatedRoles.contents = undefined;
 }
 
-function defaultElevatedGroups(groups) {
+function explicitElevated() {
   let match = explicitElevatedGroups.contents;
+  let match$1 = explicitElevatedRoles.contents;
+  if (match === undefined && match$1 === undefined) {
+    return;
+  }
+  return Array.from(new Set(Stdlib_Option.getOr(match, []).concat(Stdlib_Option.getOr(match$1, []).map(Role$Reventless.groupOf))).values());
+}
+
+function defaultElevatedGroups(groups) {
+  let match = explicitElevated();
   let match$1 = process.env.REVENTLESS_ELEVATED_GROUPS;
   if (match !== undefined || match$1 !== undefined) {
     return;
@@ -33,12 +52,23 @@ function defaultElevatedGroups(groups) {
   }
 }
 
+function defaultElevatedRoles(roles) {
+  let match = explicitElevated();
+  let match$1 = process.env.REVENTLESS_ELEVATED_GROUPS;
+  if (match !== undefined || match$1 !== undefined) {
+    return;
+  } else {
+    explicitElevatedRoles.contents = roles;
+    return;
+  }
+}
+
 function parseElevatedGroups(raw) {
   return raw.split(",").map(prim => prim.trim()).filter(part => part.length > 0);
 }
 
 function elevatedGroups() {
-  let groups = explicitElevatedGroups.contents;
+  let groups = explicitElevated();
   if (groups !== undefined) {
     return groups;
   }
@@ -305,9 +335,13 @@ export {
   isJsString,
   systemProviders,
   explicitElevatedGroups,
+  explicitElevatedRoles,
   setElevatedGroups,
+  setElevatedRoles,
   clearElevatedGroups,
+  explicitElevated,
   defaultElevatedGroups,
+  defaultElevatedRoles,
   parseElevatedGroups,
   elevatedGroups,
   classify,
@@ -323,4 +357,4 @@ export {
   retiredScopeOf,
   isRetiredValue,
 }
-/* Identity-Reventless Not a pure module */
+/* Role-Reventless Not a pure module */

package/src/types/Role.res

@@ -0,0 +1,178 @@
+/***
+A role is a job someone does — `Merchandiser`, `Fulfilment`, `Admin` — and is what
+a command or a view requires. A group is how an identity provider records that a
+person has one: the `groups` of a token, of a user pool, of `users.yaml`.
+
+Plugins speak of roles. Each declares the ones it uses as a payload-less variant in
+its own `src/Roles.res`, and the PPX turns `AllowRoles([Merchandiser])` into these
+names. Roles are joined by name, so two plugins that both declare `Fulfilment` mean
+the same role.
+
+The platform says which group stands for which role, only where they differ; every
+other role maps to the group of the same name. This module holds that mapping for
+the process, so enforcement, the published access keys and the deploy check all
+read one answer.
+*/
+
+/** A role's name before mapping. A string at run time, so it crosses every
+    boundary a group does, but private: a plugin's role comes from its own
+    `Roles.t` (the PPX checks the case, then calls `make`), and any other string
+    has to pass through `make` where a reader can see it is unchecked. */
+type name = private string
+
+external make: string => name = "%identity"
+external fromStringSchema: S.t<string> => S.t<name> = "%identity"
+
+let nameSchema: S.t<name> = fromStringSchema(S.string)
+
+/** The framework's administrator: members administer a deployment. */
+let admin: name = make("Admin")
+
+/**
+The renamed roles, resolved as an explicit `setGroups`, else the environment,
+else none.
+
+The environment exists for the same reason as `REVENTLESS_ELEVATED_GROUPS`: a
+deployment is two kinds of process, and a function runtime that evaluates a rule
+(the SQL-backed view reads) never runs the platform root that stated the mapping.
+`REVENTLESS_ROLE_GROUPS` carries only the renamed roles, as
+`Merchandiser=shop-merch-team,Fulfilment=shop-ops`.
+*/
+@val
+external _roleGroupsEnv: option<string> = "process.env.REVENTLESS_ROLE_GROUPS"
+
+let envKey = "REVENTLESS_ROLE_GROUPS"
+
+let explicitGroups: ref<option<array<(name, string)>>> = ref(None)
+
+/** Set once a platform has rendered something from the mapping — an AWS admin
+    API's directive is written while the platform is built. A mapping stated
+    after that would leave the two disagreeing. */
+let frozen = ref(false)
+
+let freeze = () => frozen := true
+
+/** State which group stands for which role, where the two differ. Wins over the
+    environment, like every other explicit platform setting. Refused once frozen,
+    rather than applying to half the deployment. */
+let setGroups = (pairs: array<(name, string)>) =>
+  if frozen.contents {
+    JsError.throwWithMessage(
+      "Role mapping stated after the platform was built — call roleGroups before Platform.Make().",
+    )
+  } else {
+    explicitGroups := Some(pairs)
+  }
+
+let clearGroups = () => {
+  explicitGroups := None
+  frozen := false
+}
+
+let parseGroups = (raw: string): array<(name, string)> =>
+  raw
+  ->String.split(",")
+  ->Array.filterMap(part =>
+    switch part->String.split("=")->Array.map(String.trim) {
+    | [role, group] if role != "" && group != "" => Some((make(role), group))
+    | _ => None
+    }
+  )
+
+/** The renamed roles in force, as `(role, group)`. */
+let renamed = (): array<(name, string)> =>
+  switch explicitGroups.contents {
+  | Some(pairs) => pairs
+  | None => _roleGroupsEnv->Option.mapOr([], parseGroups)
+  }
+
+/** The mapping as `REVENTLESS_ROLE_GROUPS` writes it, or `None` when no role is
+    renamed — absent rather than empty, as for the elevated groups. */
+let envValue = (): option<string> =>
+  switch renamed() {
+  | [] => None
+  | pairs =>
+    Some(pairs->Array.map(((role, group)) => `${(role :> string)}=${group}`)->Array.join(","))
+  }
+
+/** The group that stands for `role`. */
+let groupOf = (role: name): string =>
+  switch renamed()->Array.find(((r, _)) => r == role) {
+  | Some((_, group)) => group
+  | None => (role :> string)
+  }
+
+/** The group that stands for the administrator. Written into the admin API's
+    directives, the elevated default and the shell's configuration. */
+let adminGroup = (): string => groupOf(admin)
+
+/**
+Where the groups this deployment provides come from: what the identity provider
+reports where the platform can ask it, else the administrator group and accounts
+manifest a platform finds for itself and the groups a platform root declares.
+
+Sources rather than values, read when the check runs: a platform states them
+while its functor is applied, before the root has said how its roles map. Empty
+until a platform or a root says anything, which is how a check knows whether it
+has an answer to compare against.
+*/
+let groupSources: ref<array<unit => array<string>>> = ref([])
+
+/** The groups a root declared with `provideGroups`, kept apart so a listing can
+    contradict them. */
+let declaredGroups: ref<array<string>> = ref([])
+
+/** The groups the identity provider itself reported, and which provider that was. */
+type listing = {source: string, groups: array<string>}
+
+let listing: ref<option<listing>> = ref(None)
+
+let provideGroupsFrom = (source: unit => array<string>) =>
+  groupSources := groupSources.contents->Array.concat([source])
+
+let provideGroups = (groups: array<string>) => {
+  declaredGroups := declaredGroups.contents->Array.concat(groups)
+  provideGroupsFrom(() => groups)
+}
+
+/**
+Record what the identity provider says it has. A platform that can ask (the AWS
+user pool) does, before its plugins are built. The listing is then the whole
+answer: a group a manifest names, a root declares or the mapping points to is
+provided only if the provider has it, since a group it lacks refuses everybody.
+*/
+let provideListedGroups = (~source: string, groups: array<string>) =>
+  listing := Some({source, groups})
+
+let clearProvidedGroups = () => {
+  groupSources := []
+  declaredGroups := []
+  listing := None
+}
+
+let _distinct = (groups: array<string>) => groups->Set.fromArray->Set.values->Array.fromIterator
+
+/** The groups a deployment provides: the provider's listing where there is one,
+    else every source plus every group the mapping names. `None` when nothing was
+    provided — a process that is not a platform (a unit test, a function runtime)
+    has no answer to give. */
+let providedGroups = (): option<array<string>> =>
+  switch (listing.contents, groupSources.contents) {
+  | (Some({groups}), _) => Some(_distinct(groups))
+  | (None, []) => None
+  | (None, sources) =>
+    Some(
+      sources
+      ->Array.flatMap(source => source())
+      ->Array.concat(renamed()->Array.map(((_, group)) => group))
+      ->_distinct,
+    )
+  }
+
+/** The declared groups the provider's listing does not have. Empty without a
+    listing, when there is nothing to contradict them. */
+let declaredButMissing = (): array<string> =>
+  switch listing.contents {
+  | None => []
+  | Some({groups}) => declaredGroups.contents->Array.filter(g => !(groups->Array.includes(g)))
+  }

package/src/types/Role.res.mjs

@@ -0,0 +1,171 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+
+let nameSchema = Sury.string;
+
+let admin = "Admin";
+
+let explicitGroups = {
+  contents: undefined
+};
+
+let frozen = {
+  contents: false
+};
+
+function freeze() {
+  frozen.contents = true;
+}
+
+function setGroups(pairs) {
+  if (frozen.contents) {
+    return Stdlib_JsError.throwWithMessage("Role mapping stated after the platform was built — call roleGroups before Platform.Make().");
+  } else {
+    explicitGroups.contents = pairs;
+    return;
+  }
+}
+
+function clearGroups() {
+  explicitGroups.contents = undefined;
+  frozen.contents = false;
+}
+
+function parseGroups(raw) {
+  return Stdlib_Array.filterMap(raw.split(","), part => {
+    let match = part.split("=").map(prim => prim.trim());
+    if (match.length !== 2) {
+      return;
+    }
+    let role = match[0];
+    let group = match[1];
+    if (role !== "" && group !== "") {
+      return [
+        role,
+        group
+      ];
+    }
+  });
+}
+
+function renamed() {
+  let pairs = explicitGroups.contents;
+  if (pairs !== undefined) {
+    return pairs;
+  } else {
+    return Stdlib_Option.mapOr(process.env.REVENTLESS_ROLE_GROUPS, [], parseGroups);
+  }
+}
+
+function envValue() {
+  let pairs = renamed();
+  if (pairs.length !== 0) {
+    return pairs.map(param => param[0] + `=` + param[1]).join(",");
+  }
+}
+
+function groupOf(role) {
+  let match = renamed().find(param => param[0] === role);
+  if (match !== undefined) {
+    return match[1];
+  } else {
+    return role;
+  }
+}
+
+function adminGroup() {
+  return groupOf(admin);
+}
+
+let groupSources = {
+  contents: []
+};
+
+let declaredGroups = {
+  contents: []
+};
+
+let listing = {
+  contents: undefined
+};
+
+function provideGroupsFrom(source) {
+  groupSources.contents = groupSources.contents.concat([source]);
+}
+
+function provideGroups(groups) {
+  declaredGroups.contents = declaredGroups.contents.concat(groups);
+  provideGroupsFrom(() => groups);
+}
+
+function provideListedGroups(source, groups) {
+  listing.contents = {
+    source: source,
+    groups: groups
+  };
+}
+
+function clearProvidedGroups() {
+  groupSources.contents = [];
+  declaredGroups.contents = [];
+  listing.contents = undefined;
+}
+
+function _distinct(groups) {
+  return Array.from(new Set(groups).values());
+}
+
+function providedGroups() {
+  let match = listing.contents;
+  let match$1 = groupSources.contents;
+  if (match !== undefined) {
+    return Array.from(new Set(match.groups).values());
+  }
+  if (match$1.length === 0) {
+    return;
+  }
+  let groups = match$1.flatMap(source => source()).concat(renamed().map(param => param[1]));
+  return Array.from(new Set(groups).values());
+}
+
+function declaredButMissing() {
+  let match = listing.contents;
+  if (match === undefined) {
+    return [];
+  }
+  let groups = match.groups;
+  return declaredGroups.contents.filter(g => !groups.includes(g));
+}
+
+let envKey = "REVENTLESS_ROLE_GROUPS";
+
+export {
+  nameSchema,
+  admin,
+  envKey,
+  explicitGroups,
+  frozen,
+  freeze,
+  setGroups,
+  clearGroups,
+  parseGroups,
+  renamed,
+  envValue,
+  groupOf,
+  adminGroup,
+  groupSources,
+  declaredGroups,
+  listing,
+  provideGroupsFrom,
+  provideGroups,
+  provideListedGroups,
+  clearProvidedGroups,
+  _distinct,
+  providedGroups,
+  declaredButMissing,
+}
+/* nameSchema Not a pure module */

package/src/types/RoleCoverage.res

@@ -0,0 +1,115 @@
+/***
+Whether a platform can provide every role a plugin needs.
+
+A rule naming a role no group stands for refuses everybody it was written for, and
+nothing says so until someone is refused on a deployed stack. So every role a
+component's rule names, and every elevated role, must map to a group the platform
+provides: the groups its identity provider reports where the platform can ask it,
+else the administrator group, the accounts manifest, the role mapping and any
+groups a root declares (see `Role.providedGroups`).
+*/
+
+type need = {
+  plugin: string,
+  /** The component and, for a command, the command: `Product.AddProduct`. */
+  item: string,
+  role: Role.name,
+  group: string,
+}
+
+let needsOf = (structure: Plugin.pluginStructure, ~plugin: string): array<need> => {
+  let need = (item, role) => {plugin, item, role, group: Role.groupOf(role)}
+  let rolesOf = (item, roles: option<array<string>>) =>
+    roles->Option.getOr([])->Array.map(role => need(item, Role.make(role)))
+  let writable = (defs: array<Plugin.writableDef>) =>
+    defs->Array.flatMap(w =>
+      w.commands->Array.flatMap(c => rolesOf(`${w.name}.${c.name}`, c.requiredRoles))
+    )
+  let queryable = (defs: array<Plugin.queryableDef>) =>
+    defs->Array.flatMap(q => rolesOf(q.name, q.requiredRoles))
+  Array.flat([
+    writable(structure.aggregates),
+    writable(structure.stateChangeSlices),
+    structure.inboundTranslationSlices->Array.flatMap(s => rolesOf(s.name, s.requiredRoles)),
+    queryable(structure.readModels),
+    queryable(structure.stateViewSlices),
+  ])
+}
+
+/** The elevated roles as needs of the platform itself. */
+let elevatedNeeds = (roles: array<Role.name>): array<need> =>
+  roles->Array.map(role => {
+    plugin: "platform",
+    item: "elevated roles",
+    role,
+    group: Role.groupOf(role),
+  })
+
+let unmet = (needs: array<need>, ~provided: array<string>): array<need> =>
+  needs->Array.filter(n => !(provided->Array.includes(n.group)))
+
+let describe = (n: need): string => {
+  let role = (n.role :> string)
+  n.group == role
+    ? `${n.plugin}: ${n.item} needs the role ${role}`
+    : `${n.plugin}: ${n.item} needs the role ${role} (mapped to the group ${n.group})`
+}
+
+/** What to do about it depends on where the provided groups came from: a
+    provider that was asked can only be given the group, while a manifest or a
+    declaration can be corrected. */
+let remedy = (~provided: array<string>, ~listing: option<Role.listing>): string =>
+  switch listing {
+  | Some({source}) =>
+    let source = source->String.charAt(0)->String.toUpperCase ++ source->String.slice(~start=1)
+    `  ${source} has the groups: ${provided->Array.join(", ")}.\n` ++
+    `  Create the group there (provision-accounts creates the groups of the accounts ` ++ `manifest), or map the role to a group it has (Platform.roleGroups).`
+  | None =>
+    `  The platform provides the groups: ${provided->Array.join(", ")}.\n` ++
+    `  Add an account in that group to the accounts manifest (.reventless/users.yaml), ` ++
+    `map the role to a group that exists (Platform.roleGroups), or declare the groups ` ++ `of a user pool this deployment did not create (Platform.providedGroups).`
+  }
+
+let unmetMessage = (
+  missing: array<need>,
+  ~provided: array<string>,
+  ~listing: option<Role.listing>=?,
+): string =>
+  `Roles this platform cannot provide — every caller would be refused:\n` ++
+  missing->Array.map(n => `  ${describe(n)}`)->Array.join("\n") ++
+  "\n" ++
+  remedy(~provided, ~listing)
+
+/** A declared group the provider says it does not have: the declaration is wrong,
+    whether or not a plugin needs the group today. */
+let contradictedMessage = (groups: array<string>, ~listing: Role.listing): string =>
+  `Groups declared with Platform.providedGroups that ${listing.source} does not have: ` ++
+  `${groups->Array.join(", ")}.\n` ++
+  `  It has: ${listing.groups->Array.join(", ")}. Create them there or remove the declaration.`
+
+/**
+Refuse a plugin needing a role nobody provides, and a deployment electing a role
+nobody provides. A no-op in a process where no platform stated what it provides
+(`Role.providedGroups()` is `None`), which is a unit test or a function runtime
+rather than a deployment.
+
+The elevated roles are checked with every plugin rather than once by the platform
+because a plugin's own stack builds no platform, and a check that runs in only one
+of the two programs is skipped in the other.
+*/
+let check = (structure: Plugin.pluginStructure, ~plugin: string): unit =>
+  switch Role.providedGroups() {
+  | None => ()
+  | Some(provided) =>
+    let listing = Role.listing.contents
+    switch (listing, Role.declaredButMissing()) {
+    | (Some(listing), groups) if groups != [] =>
+      JsError.throwWithMessage(contradictedMessage(groups, ~listing))
+    | _ => ()
+    }
+    let elevated = OwnerScope.explicitElevatedRoles.contents->Option.getOr([])
+    switch unmet(needsOf(structure, ~plugin)->Array.concat(elevatedNeeds(elevated)), ~provided) {
+    | [] => ()
+    | missing => JsError.throwWithMessage(unmetMessage(missing, ~provided, ~listing?))
+    }
+  }

package/src/types/RoleCoverage.res.mjs

@@ -0,0 +1,93 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
+import * as Role$Reventless from "./Role.res.mjs";
+import * as Primitive_object from "@rescript/runtime/lib/es6/Primitive_object.js";
+import * as OwnerScope$Reventless from "./OwnerScope.res.mjs";
+
+function needsOf(structure, plugin) {
+  let rolesOf = (item, roles) => Stdlib_Option.getOr(roles, []).map(role => ({
+    plugin: plugin,
+    item: item,
+    role: role,
+    group: Role$Reventless.groupOf(role)
+  }));
+  let writable = defs => defs.flatMap(w => w.commands.flatMap(c => rolesOf(w.name + `.` + c.name, c.requiredRoles)));
+  let queryable = defs => defs.flatMap(q => rolesOf(q.name, q.requiredRoles));
+  return [
+    writable(structure.aggregates),
+    writable(structure.stateChangeSlices),
+    structure.inboundTranslationSlices.flatMap(s => rolesOf(s.name, s.requiredRoles)),
+    queryable(structure.readModels),
+    queryable(structure.stateViewSlices)
+  ].flat();
+}
+
+function elevatedNeeds(roles) {
+  return roles.map(role => ({
+    plugin: "platform",
+    item: "elevated roles",
+    role: role,
+    group: Role$Reventless.groupOf(role)
+  }));
+}
+
+function unmet(needs, provided) {
+  return needs.filter(n => !provided.includes(n.group));
+}
+
+function describe(n) {
+  let role = n.role;
+  if (n.group === role) {
+    return n.plugin + `: ` + n.item + ` needs the role ` + role;
+  } else {
+    return n.plugin + `: ` + n.item + ` needs the role ` + role + ` (mapped to the group ` + n.group + `)`;
+  }
+}
+
+function remedy(provided, listing) {
+  if (listing === undefined) {
+    return `  The platform provides the groups: ` + provided.join(", ") + `.\n  Add an account in that group to the accounts manifest (.reventless/users.yaml), map the role to a group that exists (Platform.roleGroups), or declare the groups of a user pool this deployment did not create (Platform.providedGroups).`;
+  }
+  let source = listing.source;
+  let source$1 = source.charAt(0).toUpperCase() + source.slice(1);
+  return `  ` + source$1 + ` has the groups: ` + provided.join(", ") + `.\n  Create the group there (provision-accounts creates the groups of the accounts manifest), or map the role to a group it has (Platform.roleGroups).`;
+}
+
+function unmetMessage(missing, provided, listing) {
+  return `Roles this platform cannot provide — every caller would be refused:\n` + missing.map(n => `  ` + describe(n)).join("\n") + "\n" + remedy(provided, listing);
+}
+
+function contradictedMessage(groups, listing) {
+  return `Groups declared with Platform.providedGroups that ` + listing.source + ` does not have: ` + (groups.join(", ") + `.\n`) + (`  It has: ` + listing.groups.join(", ") + `. Create them there or remove the declaration.`);
+}
+
+function check(structure, plugin) {
+  let provided = Role$Reventless.providedGroups();
+  if (provided === undefined) {
+    return;
+  }
+  let listing = Role$Reventless.listing.contents;
+  let match = Role$Reventless.declaredButMissing();
+  if (listing !== undefined && Primitive_object.notequal(match, [])) {
+    Stdlib_JsError.throwWithMessage(contradictedMessage(match, listing));
+  }
+  let elevated = Stdlib_Option.getOr(OwnerScope$Reventless.explicitElevatedRoles.contents, []);
+  let missing = unmet(needsOf(structure, plugin).concat(elevatedNeeds(elevated)), provided);
+  if (missing.length !== 0) {
+    return Stdlib_JsError.throwWithMessage(unmetMessage(missing, provided, listing));
+  }
+}
+
+export {
+  needsOf,
+  elevatedNeeds,
+  unmet,
+  describe,
+  remedy,
+  unmetMessage,
+  contradictedMessage,
+  check,
+}
+/* Role-Reventless Not a pure module */

package/src/types/authorizationNamed.mjs

@@ -0,0 +1,17 @@
+// `Authorization.named`: a plugin's rule, whose roles are its own `Roles.t`
+// cases, as the framework's rule over role names. A payload-less case is its
+// name at run time, so the rule is returned as it is once every role has been
+// checked to be one; anything else would be compared with group names and
+// never match, so it is refused here instead.
+export function named(rule) {
+  if (rule !== null && typeof rule === "object" && rule.TAG === "AllowRoles") {
+    for (const role of rule._0) {
+      if (typeof role !== "string") {
+        throw new Error(
+          `Authorization: a role must be a case of a plugin's Roles.t without a payload, got ${JSON.stringify(role)}`,
+        );
+      }
+    }
+  }
+  return rule;
+}

package/src/types/AdminGroup.res

@@ -1,27 +0,0 @@
-/**
-The group whose members administer a deployment.
-
-One definition, because the name is decided **twice and independently**: an
-authorization rule names it to allow a read, and [OwnerScope.elevatedGroups]
-names it to exempt a caller from `@owner` narrowing. Nothing checks that the two
-agree, and a deployment where they disagree is refused nowhere — the
-administrator passes every authorization check and then reads *empty views*,
-because every owner-scoped view filters them out. Empty-because-scoped and
-empty-because-there-is-nothing look identical from outside.
-
-In `spec` rather than in a provider package because **both platforms hard-code
-it**: the AWS platform decorates its admin API with it, while the local platform
-both wraps its `Platform_*` fields in it and hands it to the built-in developer
-account. A constant only one of them could reach would leave the other exactly as
-divergent as it is today.
-
-🚨 **This buys agreement, not the freedom to rename.** `"Admin"` is written into
-every example's `@@reventless.authorize` annotations, and a PPX annotation takes a
-literal — so the consumers that matter most *cannot* read this constant. Changing
-the value here would leave those annotations behind and silently split the two
-mechanisms this exists to hold together, which is the failure above rather than a
-compile error. Renaming the administrator group is a different and much larger
-act. `AdminGroupTest` asserts that the constant and the platform's own annotation
-still say the same thing, because that boundary can carry no other check.
-*/
-let name = "Admin"

package/src/types/AdminGroup.res.mjs

@@ -1,9 +0,0 @@
-// Generated by ReScript, PLEASE EDIT WITH CARE
-
-
-let name = "Admin";
-
-export {
-  name,
-}
-/* No side effect */