@reventlessdev/reventless-spec 3.0.0-alpha.170 → 3.0.0-alpha.172

package/CHANGELOG.md

@@ -3,6 +3,37 @@
 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.172 (2026-10-21)
+
+* feat!: a rejected command says whether the model, the access check or the platform said no ([6a8a6b0](https://github.com/ReventlessDev/reventless-core/commit/6a8a6b0f2f31e766ae26a944c23b0904e51a5865))
+
+### BREAKING CHANGES
+
+* a type error variant with one of those names fails to
+compile; rename it for what the model means, such as AlreadyBooked. On
+AWS, rebuild every plugin against this release before a client selects
+cause: a plugin built earlier answers it with a non-null error.
+
+
+
+# 3.0.0-alpha.171 (2026-10-21)
+
+* feat!: a state view's row key is module Id ([08c9726](https://github.com/ReventlessDev/reventless-core/commit/08c972659a3d689a39fd5e2f2026597155e92210))
+* feat!: a plugin structure's component definitions are read-side and write-side defs ([ea2ab69](https://github.com/ReventlessDev/reventless-core/commit/ea2ab69e928ba16d7e640e4c66ab0e9ba034fe5c))
+
+### BREAKING CHANGES
+
+* a state view spec declares its row key as module Id. A
+hand-written module Key in a spec under StateView/ or StateViewStream/
+fails the build with "A state view's row key is `module Id`, not
+`module Key`".
+* Plugin.queryableDef, Plugin.writableDef, their schemas,
+isPublicQueryable and encodeQueryableDef no longer exist; a reader names
+readSideDef, writeSideDef, isPublicReadSide and encodeReadSideDef. There
+are no aliases, so the compiler lists every reader.
+
+
+
 # 3.0.0-alpha.170 (2026-10-21)
 
 * feat!: the write-side logic module is called the decision, and a codemod moves an app over ([cb573ff](https://github.com/ReventlessDev/reventless-core/commit/cb573ff5b928c7d7f3e75988dfaa65066f8c95eb))

package/package.json

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

package/schema/platform-api.graphql

@@ -9,11 +9,18 @@ type CommandPending {
 }
 
 type CommandRejected {
+  cause: CommandRejectionCause!
   errorCode: String!
   errorDetail: String
   msgId: ID!
 }
 
+enum CommandRejectionCause {
+  ACCESS
+  DOMAIN
+  INFRASTRUCTURE
+}
+
 union CommandResult = CommandAccepted | CommandPending | CommandRejected
 
 type Mutation {

package/src/components/CommandOutcome.res

@@ -0,0 +1,54 @@
+/**
+The codes the platform itself puts on a rejected command, as opposed to the
+error names a spec declares.
+
+A spec may not name an error like one of these: the PPX refuses it, so a
+client reading only `errorCode` can still tell a platform code from the
+model's. The PPX holds a copy of `platformErrorCodes` (it cannot read this
+file); a spec test keeps the two equal.
+*/
+type platformErrorCode =
+  /** The caller may not act: an `@authorize` rule or an ownership check refused. */
+  | Forbidden
+  /** Contention the retries could not absorb, or a handler that failed outright. */
+  | Conflict
+  /** The event log refused the append. */
+  | AppendFailed
+  /** The plugin is disconnected; retry later. */
+  | PluginUnavailable
+  /** An administrator deactivated the plugin. */
+  | PluginInactive
+  /** The plugin version was retired. */
+  | PluginRetired
+  /** An inbound translation's commands could not be published. */
+  | PublishFailed
+  /** An inbound translation refused its input. */
+  | TranslationFailed
+
+let code = (c: platformErrorCode): string =>
+  switch c {
+  | Forbidden => "Forbidden"
+  | Conflict => "Conflict"
+  | AppendFailed => "AppendFailed"
+  | PluginUnavailable => "PluginUnavailable"
+  | PluginInactive => "PluginInactive"
+  | PluginRetired => "PluginRetired"
+  | PublishFailed => "PublishFailed"
+  | TranslationFailed => "TranslationFailed"
+  }
+
+/** Every constructor, in declaration order. */
+let all = [
+  Forbidden,
+  Conflict,
+  AppendFailed,
+  PluginUnavailable,
+  PluginInactive,
+  PluginRetired,
+  PublishFailed,
+  TranslationFailed,
+]
+
+let platformErrorCodes = all->Array.map(code)
+
+let isPlatformErrorCode = (name: string): bool => platformErrorCodes->Array.includes(name)

package/src/components/CommandOutcome.res.mjs

@@ -0,0 +1,48 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+
+function code(c) {
+  switch (c) {
+    case "Forbidden" :
+      return "Forbidden";
+    case "Conflict" :
+      return "Conflict";
+    case "AppendFailed" :
+      return "AppendFailed";
+    case "PluginUnavailable" :
+      return "PluginUnavailable";
+    case "PluginInactive" :
+      return "PluginInactive";
+    case "PluginRetired" :
+      return "PluginRetired";
+    case "PublishFailed" :
+      return "PublishFailed";
+    case "TranslationFailed" :
+      return "TranslationFailed";
+  }
+}
+
+let all = [
+  "Forbidden",
+  "Conflict",
+  "AppendFailed",
+  "PluginUnavailable",
+  "PluginInactive",
+  "PluginRetired",
+  "PublishFailed",
+  "TranslationFailed"
+];
+
+let platformErrorCodes = all.map(code);
+
+function isPlatformErrorCode(name) {
+  return platformErrorCodes.includes(name);
+}
+
+export {
+  code,
+  all,
+  platformErrorCodes,
+  isPlatformErrorCode,
+}
+/* platformErrorCodes Not a pure module */

package/src/components/Plugin.res

@@ -173,7 +173,7 @@ type commandDef = {
       means the command does not move the row. */
   targetState: option<string>,
   /** Where the from-set came from, ranking an inherited edge against an authored
-      one the way `queryableDef.labelFieldSource` does for its field:
+      one the way `readSideDef.labelFieldSource` does for its field:
 
       - `"derived"` — the component's own scenarios.
       - `"declared"` — its `commandTransition` switch.
@@ -204,7 +204,7 @@ type commandDef = {
 }
 
 @schema
-type queryableDef = {
+type readSideDef = {
   name: string,
   queryField: string,
   schema: string,
@@ -276,7 +276,7 @@ type errorDef = {
 }
 
 @schema
-type writableDef = {
+type writeSideDef = {
   name: string,
   commands: array<commandDef>,
   producedEventTypes: array<string>,
@@ -289,7 +289,7 @@ type writableDef = {
       required list still lacks the key — both admin resolvers heal absent ones to
       `[]` on read, and a new one must be added there too. */
   errors: array<errorDef>,
-  /** Chapter grouping band — see `queryableDef.chapter`. */
+  /** Chapter grouping band — see `readSideDef.chapter`. */
   chapter: option<string>,
 }
 
@@ -299,7 +299,7 @@ type automationSliceDef = {
   consumedEventTypes: array<string>,
   producedCommandTypes: array<string>,
   targetName: string,
-  /** Chapter grouping band — see `queryableDef.chapter`. */
+  /** Chapter grouping band — see `readSideDef.chapter`. */
   chapter: option<string>,
   /** The declared `schedule`, as the JSON of `Schedule.timeSchema`; `None` for an
       automation started by events only, and in a structure from before the field. */
@@ -314,7 +314,7 @@ type outboundTranslationSliceDef = {
   targetName: option<string>,
   // Foreign system this slice publishes to — drives the external box (Event Graph).
   externalSystem: option<string>,
-  /** Chapter grouping band — see `queryableDef.chapter`. */
+  /** Chapter grouping band — see `readSideDef.chapter`. */
   chapter: option<string>,
   /** The topics this slice subscribes to, as `Spec.sourceNames` declares them —
       an Aggregate's `Spec.name` or a DCB source name. `Some([])` is the declared
@@ -333,7 +333,7 @@ type inboundTranslationSliceDef = {
   targetName: string,
   // Foreign system this slice receives from — drives the external box (Event Graph).
   externalSystem: option<string>,
-  /** Chapter grouping band — see `queryableDef.chapter`. */
+  /** Chapter grouping band — see `readSideDef.chapter`. */
   chapter: option<string>,
   /** The roles any of its commands' rules name; see `commandDef`. */
   requiredRoles?: array<string>,
@@ -393,7 +393,7 @@ type extensionDef = {
 An extension point owned by a plugin, from the producer side.
 
 `sourceEventTypes` are the `Delegate`'s events feeding the published protocol,
-plugin-qualified to match `writableDef.producedEventTypes`. `commandTypes` is the
+plugin-qualified to match `writeSideDef.producedEventTypes`. `commandTypes` is the
 EP's inbound protocol — None (read as []) for a `command = unit` EP, which routes
 nothing. Definitions persisted before a field was added must be re-emitted.
 */
@@ -474,10 +474,10 @@ is fabricated and warned about, so it is the one shape to avoid. Regression suit
 */
 @schema
 type pluginStructure = {
-  readModels: array<queryableDef>,
-  stateViewSlices: array<queryableDef>,
-  stateChangeSlices: array<writableDef>,
-  aggregates: array<writableDef>,
+  readModels: array<readSideDef>,
+  stateViewSlices: array<readSideDef>,
+  stateChangeSlices: array<writeSideDef>,
+  aggregates: array<writeSideDef>,
   automationSlices: array<automationSliceDef>,
   outboundTranslationSlices: array<outboundTranslationSliceDef>,
   inboundTranslationSlices: array<inboundTranslationSliceDef>,

package/src/components/Plugin.res.mjs

@@ -106,7 +106,7 @@ let commandDefSchema = Sury.$schema(s => ({
   ownerField: s.m(Sury.$option(Sury.string))
 }));
 
-let queryableDefSchema = Sury.$schema(s => ({
+let readSideDefSchema = Sury.$schema(s => ({
   name: s.m(Sury.string),
   queryField: s.m(Sury.string),
   schema: s.m(Sury.string),
@@ -141,7 +141,7 @@ let errorDefSchema = Sury.$schema(s => ({
   references: s.m(Sury.array(fieldReferenceSchema))
 }));
 
-let writableDefSchema = Sury.$schema(s => ({
+let writeSideDefSchema = Sury.$schema(s => ({
   name: s.m(Sury.string),
   commands: s.m(Sury.array(commandDefSchema)),
   producedEventTypes: s.m(Sury.array(Sury.string)),
@@ -239,10 +239,10 @@ let traitDeclarationSchema = Sury.$schema(s => ({
 }));
 
 let pluginStructureSchema = Sury.$schema(s => ({
-  readModels: s.m(Sury.array(queryableDefSchema)),
-  stateViewSlices: s.m(Sury.array(queryableDefSchema)),
-  stateChangeSlices: s.m(Sury.array(writableDefSchema)),
-  aggregates: s.m(Sury.array(writableDefSchema)),
+  readModels: s.m(Sury.array(readSideDefSchema)),
+  stateViewSlices: s.m(Sury.array(readSideDefSchema)),
+  stateChangeSlices: s.m(Sury.array(writeSideDefSchema)),
+  aggregates: s.m(Sury.array(writeSideDefSchema)),
   automationSlices: s.m(Sury.array(automationSliceDefSchema)),
   outboundTranslationSlices: s.m(Sury.array(outboundTranslationSliceDefSchema)),
   inboundTranslationSlices: s.m(Sury.array(inboundTranslationSliceDefSchema)),
@@ -290,10 +290,10 @@ export {
   commandLevelSchema,
   fieldReferenceSchema,
   commandDefSchema,
-  queryableDefSchema,
+  readSideDefSchema,
   eventDefSchema,
   errorDefSchema,
-  writableDefSchema,
+  writeSideDefSchema,
   automationSliceDefSchema,
   outboundTranslationSliceDefSchema,
   inboundTranslationSliceDefSchema,

package/src/components/StateAnnotations.res

@@ -161,7 +161,7 @@ type stateAnnotationSpec = {
   command's declared edge is written in terms of, a board draws its columns
   from and a state diagram renders. `Some(name)` when one such annotation
   exists; the PPX errors on duplicate `@lifecycle` annotations within the same
-  record. Codegen consumes this to populate `queryableDef.lifecycleField`, and
+  record. Codegen consumes this to populate `readSideDef.lifecycleField`, and
   falls back to a field literally named `"lifecycle"` whose shape is an enum
   when this annotation is absent — so a record whose field can honestly be
   called `lifecycle` declares one without ceremony.

package/src/components/StateViewSlice.res

@@ -53,11 +53,11 @@ module type Spec = {
 
   /**
   What a row is keyed by. `Id.StringPure` (a plain `string`) unless the view
-  declares its identity — `module Key = OrderId` — in which case a projection
+  declares its identity — `module Id = OrderId` — in which case a projection
   that keys a row by another entity's id does not compile. Auto-injected by
   `@@reventless.spec` in a `StateView/` folder.
   */
-  module Key: Id.T
+  module Id: Id.T
 
   /**
   Events this view slice projects. Only needs the fields required for the projection —
@@ -125,7 +125,7 @@ module type Projection = {
   Receives the event wrapped in a `consumed` envelope (event + `meta` +
   `recordedAt`); only events declared in `Spec.consumedEvent` — no wildcard needed.
   */
-  let project: consumed<Spec.consumedEvent> => array<Projection.action<Spec.Key.t, Spec.state>>
+  let project: consumed<Spec.consumedEvent> => array<Projection.action<Spec.Id.t, Spec.state>>
 
   /** File URL of this Projection module (`import.meta.url`). */
   let moduleUrl: string

package/src/lifecycle/CheckLifecycleModel.res

@@ -595,7 +595,8 @@ let lifecycleMapFor = (
 
 // ── Rule 2 and 3: the relation a command's own scenarios describe ───────────
 
-type outcome = Emitted | NoChange | Refused
+// `Rejected`: the decision rejected the command, the sidecar's `"error"`.
+type outcome = Emitted | NoChange | Rejected
 
 type observation = {
   title: string,
@@ -646,7 +647,7 @@ let outcomeOf = (s: scenario): outcome =>
   // `thenNoEvent`, and the empty `then` an older sidecar wrote for the same
   // thing. Accepted, and nothing happened.
   | "noEvent" | "" => NoChange
-  | "error" => Refused
+  | "error" => Rejected
   // A `then` this harvest has no reading for — a side effect, a published
   // command. Not an effect on this row either way.
   | _ => NoChange
@@ -739,7 +740,7 @@ let deriveCommands = (
         mine->Array.filterMap(o => o.outcome == Emitted || o.from == noRow ? None : Some(o.from)),
       ),
       refusedStates: sortedUnique(
-        mine->Array.filterMap(o => o.outcome == Refused && o.from != noRow ? Some(o.from) : None),
+        mine->Array.filterMap(o => o.outcome == Rejected && o.from != noRow ? Some(o.from) : None),
       ),
       targets: sortedUnique(
         effective->Array.filterMap(o => o.to == o.from || o.to == noRow ? None : Some(o.to)),
@@ -938,7 +939,7 @@ let compare = (
     // exercised in and **refused**: that is the switch and the behavior
     // disagreeing about the same row.
     //
-    // 🚨 **Refused, not merely inert.** `Unrestricted` claims the command is
+    // 🚨 **Rejected, not merely inert.** `Unrestricted` claims the command is
     // never refused — it does not claim the command always emits. A state where a
     // scenario shows it accepted and silent AGREES with that: returning `Ok([])`
     // for a command that would change nothing is this codebase's idempotency

package/src/lifecycle/CheckLifecycleModel.res.mjs

@@ -470,7 +470,7 @@ function outcomeOf(s) {
   let match = s.thenKind;
   switch (match) {
     case "error" :
-      return "Refused";
+      return "Rejected";
     case "event" :
       return "Emitted";
     default:
@@ -561,7 +561,7 @@ function deriveCommands(component, observations, labelled) {
         }
       })),
       refusedStates: sortedUnique(Stdlib_Array.filterMap(mine, o => {
-        if (o.outcome === "Refused" && o.from !== noRow) {
+        if (o.outcome === "Rejected" && o.from !== noRow) {
           return o.from;
         }
       })),

package/src/types/RoleCoverage.res

@@ -21,18 +21,18 @@ 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>) =>
+  let writeSide = (defs: array<Plugin.writeSideDef>) =>
     defs->Array.flatMap(w =>
       w.commands->Array.flatMap(c => rolesOf(`${w.name}.${c.name}`, c.requiredRoles))
     )
-  let queryable = (defs: array<Plugin.queryableDef>) =>
+  let readSide = (defs: array<Plugin.readSideDef>) =>
     defs->Array.flatMap(q => rolesOf(q.name, q.requiredRoles))
   Array.flat([
-    writable(structure.aggregates),
-    writable(structure.stateChangeSlices),
+    writeSide(structure.aggregates),
+    writeSide(structure.stateChangeSlices),
     structure.inboundTranslationSlices->Array.flatMap(s => rolesOf(s.name, s.requiredRoles)),
-    queryable(structure.readModels),
-    queryable(structure.stateViewSlices),
+    readSide(structure.readModels),
+    readSide(structure.stateViewSlices),
   ])
 }
 

package/src/types/RoleCoverage.res.mjs

@@ -13,14 +13,14 @@ function needsOf(structure, plugin) {
     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));
+  let writeSide = defs => defs.flatMap(w => w.commands.flatMap(c => rolesOf(w.name + `.` + c.name, c.requiredRoles)));
+  let readSide = defs => defs.flatMap(q => rolesOf(q.name, q.requiredRoles));
   return [
-    writable(structure.aggregates),
-    writable(structure.stateChangeSlices),
+    writeSide(structure.aggregates),
+    writeSide(structure.stateChangeSlices),
     structure.inboundTranslationSlices.flatMap(s => rolesOf(s.name, s.requiredRoles)),
-    queryable(structure.readModels),
-    queryable(structure.stateViewSlices)
+    readSide(structure.readModels),
+    readSide(structure.stateViewSlices)
   ].flat();
 }