@reventlessdev/reventless-local 3.0.0-alpha.293 → 3.0.0-alpha.294

package/CHANGELOG.md

@@ -3,6 +3,19 @@
 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.294 (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.293 (2026-10-21)
 
 * feat!: a state view's row key is module Id ([08c9726](https://github.com/ReventlessDev/reventless-core/commit/08c972659a3d689a39fd5e2f2026597155e92210))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-local",
-  "version": "3.0.0-alpha.293",
+  "version": "3.0.0-alpha.294",
   "description": "Local platform for Reventless (in-memory or SQLite backend, for development and testing without AWS)",
   "license": "Apache-2.0",
   "bin": {
@@ -35,18 +35,18 @@
     "sury": "11.0.0",
     "ws": "^8.18.0",
     "@reventlessdev/rescript-effect": "1.0.0-alpha.1",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.13",
     "@reventlessdev/rescript-graphql-yoga": "1.0.0-alpha.29",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.13",
     "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.23",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.23",
     "@reventlessdev/rescript-pulumi-pulumi": "3.0.0-alpha.0",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.302",
-    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.150",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.250",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.199",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.166",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.171",
-    "@reventlessdev/reventless-seed": "1.0.0-alpha.35"
+    "@reventlessdev/reventless-core": "3.0.0-alpha.303",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.23",
+    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.151",
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.251",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.167",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.200",
+    "@reventlessdev/reventless-seed": "1.0.0-alpha.36",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.172"
   },
   "devDependencies": {
     "rescript": "12.3.1",

package/src/Platform.res

@@ -1862,9 +1862,12 @@ module MakeWithConfig = (
         }
         switch statusByName->Dict.get(pluginPrefix) {
         | Some(Connected) => None
-        | Some(Disconnected) => Some(("PluginUnavailable", "plugin is disconnected"))
-        | Some(Inactive) => Some(("PluginInactive", "plugin is inactive"))
-        | Some(Retired) => Some(("PluginRetired", "plugin version has been retired"))
+        | Some(Disconnected) =>
+          Some((Reventless.CommandOutcome.code(PluginUnavailable), "plugin is disconnected"))
+        | Some(Inactive) =>
+          Some((Reventless.CommandOutcome.code(PluginInactive), "plugin is inactive"))
+        | Some(Retired) =>
+          Some((Reventless.CommandOutcome.code(PluginRetired), "plugin version has been retired"))
         | None => None
         }
       }

package/src/Platform.res.mjs

@@ -26,6 +26,7 @@ import * as UiSlots$ReventlessLocal from "./UiSlots.res.mjs";
 import * as Component$ReventlessCore from "@reventlessdev/reventless-core/src/components/Component.res.mjs";
 import * as LocalBus$ReventlessLocal from "./adapter/LocalBus.res.mjs";
 import * as Api_Naming$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/Api_Naming.res.mjs";
+import * as CommandOutcome$Reventless from "@reventlessdev/reventless-spec/src/components/CommandOutcome.res.mjs";
 import * as PluginSpec$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/lifecycle/PluginSpec.res.mjs";
 import * as UserStore$ReventlessLocal from "./adapter/Auth/UserStore.res.mjs";
 import * as TestRunner$ReventlessLocal from "./test/TestRunner.res.mjs";
@@ -1393,17 +1394,17 @@ function MakeWithConfig(Config) {
           return;
         case "Disconnected" :
           return [
-            "PluginUnavailable",
+            CommandOutcome$Reventless.code("PluginUnavailable"),
             "plugin is disconnected"
           ];
         case "Inactive" :
           return [
-            "PluginInactive",
+            CommandOutcome$Reventless.code("PluginInactive"),
             "plugin is inactive"
           ];
         case "Retired" :
           return [
-            "PluginRetired",
+            CommandOutcome$Reventless.code("PluginRetired"),
             "plugin version has been retired"
           ];
       }
@@ -3149,17 +3150,17 @@ function Make($star) {
           return;
         case "Disconnected" :
           return [
-            "PluginUnavailable",
+            CommandOutcome$Reventless.code("PluginUnavailable"),
             "plugin is disconnected"
           ];
         case "Inactive" :
           return [
-            "PluginInactive",
+            CommandOutcome$Reventless.code("PluginInactive"),
             "plugin is inactive"
           ];
         case "Retired" :
           return [
-            "PluginRetired",
+            CommandOutcome$Reventless.code("PluginRetired"),
             "plugin version has been retired"
           ];
       }

package/src/adapter/CommandGenerator/CommandGeneratorResolvers_GraphQL.res

@@ -35,14 +35,15 @@ let extractIdentity = (ctx: JSON.t): Reventless.Identity.t => {
 // Returns a `CommandRejected` outcome with a fresh msgId so the GraphQL union
 // resolves consistently — matches the existing CommandResult contract.
 
-let rejectForbidden = (~field: string): JSON.t => JSON.Object(
-  Dict.fromArray([
-    ("__typename", JSON.String("CommandRejected")),
-    ("msgId", JSON.String(ReventlessCore.Message.uuid())),
-    ("errorCode", JSON.String("Forbidden")),
-    ("errorDetail", JSON.String(`Mutation.${field}: identity is not authorized`)),
-  ]),
-)
+let rejectForbidden = (~field: string): JSON.t =>
+  CommandTopic.commandOutcomeToJson(
+    Rejected({
+      msgId: ReventlessCore.Message.uuid(),
+      errorCode: Reventless.CommandOutcome.code(Forbidden),
+      errorDetail: Some(`Mutation.${field}: identity is not authorized`),
+      cause: AccessRefusal,
+    }),
+  )
 
 // -- Plugin status gate -------------------------------------------------------
 // Set by the platform after Admin.construct to wire a per-mutation lookup against
@@ -60,18 +61,16 @@ let pluginStatusGate: ref<option<string => option<(string, string)>>> = ref(None
 let setPluginStatusGate = fn => pluginStatusGate := Some(fn)
 let resetPluginStatusGate = () => pluginStatusGate := None
 
-let rejectPluginStatus = (
-  ~field: string,
-  ~errorCode: string,
-  ~detail: string,
-): JSON.t => JSON.Object(
-  Dict.fromArray([
-    ("__typename", JSON.String("CommandRejected")),
-    ("msgId", JSON.String(ReventlessCore.Message.uuid())),
-    ("errorCode", JSON.String(errorCode)),
-    ("errorDetail", JSON.String(`Mutation.${field}: ${detail}`)),
-  ]),
-)
+// The plugin, not the model, is what said no.
+let rejectPluginStatus = (~field: string, ~errorCode: string, ~detail: string): JSON.t =>
+  CommandTopic.commandOutcomeToJson(
+    Rejected({
+      msgId: ReventlessCore.Message.uuid(),
+      errorCode,
+      errorDetail: Some(`Mutation.${field}: ${detail}`),
+      cause: InfrastructureFailure,
+    }),
+  )
 
 let checkPluginStatus = (~field: string): option<JSON.t> =>
   switch pluginStatusGate.contents {

package/src/adapter/CommandGenerator/CommandGeneratorResolvers_GraphQL.res.mjs

@@ -10,6 +10,7 @@ import * as Identity$Reventless from "@reventlessdev/reventless-spec/src/types/I
 import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as Message$ReventlessCore from "@reventlessdev/reventless-core/src/Message.res.mjs";
 import * as Authorization$Reventless from "@reventlessdev/reventless-spec/src/types/Authorization.res.mjs";
+import * as CommandOutcome$Reventless from "@reventlessdev/reventless-spec/src/components/CommandOutcome.res.mjs";
 import * as CommandTopic$ReventlessCore from "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic.res.mjs";
 import * as GraphQL_CallerError$ReventlessLocal from "../GraphQL_CallerError.res.mjs";
 import * as Plugin_ResolverError$ReventlessCore from "@reventlessdev/reventless-core/src/plugin/component/Plugin_ResolverError.res.mjs";
@@ -29,24 +30,13 @@ function extractIdentity(ctx) {
 }
 
 function rejectForbidden(field) {
-  return Object.fromEntries([
-    [
-      "__typename",
-      "CommandRejected"
-    ],
-    [
-      "msgId",
-      Message$ReventlessCore.uuid()
-    ],
-    [
-      "errorCode",
-      "Forbidden"
-    ],
-    [
-      "errorDetail",
-      `Mutation.` + field + `: identity is not authorized`
-    ]
-  ]);
+  return CommandTopic$ReventlessCore.commandOutcomeToJson({
+    TAG: "Rejected",
+    msgId: Message$ReventlessCore.uuid(),
+    errorCode: CommandOutcome$Reventless.code("Forbidden"),
+    errorDetail: `Mutation.` + field + `: identity is not authorized`,
+    cause: "AccessRefusal"
+  });
 }
 
 let pluginStatusGate = {
@@ -62,24 +52,13 @@ function resetPluginStatusGate() {
 }
 
 function rejectPluginStatus(field, errorCode, detail) {
-  return Object.fromEntries([
-    [
-      "__typename",
-      "CommandRejected"
-    ],
-    [
-      "msgId",
-      Message$ReventlessCore.uuid()
-    ],
-    [
-      "errorCode",
-      errorCode
-    ],
-    [
-      "errorDetail",
-      `Mutation.` + field + `: ` + detail
-    ]
-  ]);
+  return CommandTopic$ReventlessCore.commandOutcomeToJson({
+    TAG: "Rejected",
+    msgId: Message$ReventlessCore.uuid(),
+    errorCode: errorCode,
+    errorDetail: `Mutation.` + field + `: ` + detail,
+    cause: "InfrastructureFailure"
+  });
 }
 
 function checkPluginStatus(field) {

package/src/reexport/CommandTopic.res.mjs

@@ -6,6 +6,8 @@ let componentType = CommandTopic$ReventlessCore.componentType;
 
 let NotPublishedToChannel = CommandTopic$ReventlessCore.NotPublishedToChannel;
 
+let refusalCauseToGraphQL = CommandTopic$ReventlessCore.refusalCauseToGraphQL;
+
 let commandOutcomeHook = CommandTopic$ReventlessCore.commandOutcomeHook;
 
 let registerCommandOutcome = CommandTopic$ReventlessCore.registerCommandOutcome;
@@ -47,6 +49,7 @@ let filter = CommandTopic$ReventlessCore.filter;
 export {
   componentType,
   NotPublishedToChannel,
+  refusalCauseToGraphQL,
   commandOutcomeHook,
   registerCommandOutcome,
   clearCommandOutcome,

package/tests/adapter/CommandAuthorizationTest.res

@@ -139,6 +139,12 @@ describe("CommandGeneratorResolvers_GraphQL — per-constructor authorization",
     )
     expect(getTypename(response))->toEqual("CommandRejected")
     expect(getErrorCode(response))->toEqual("Forbidden")
+    expect(
+      response
+      ->JSON.Decode.object
+      ->Option.flatMap(o => o->Dict.get("cause"))
+      ->Option.flatMap(JSON.Decode.string),
+    )->toEqual(Some("ACCESS"))
     expect(calls.contents)->toEqual([])
   })
 

package/tests/adapter/CommandAuthorizationTest.res.mjs

@@ -134,6 +134,7 @@ globalThis.describe("CommandGeneratorResolvers_GraphQL — per-constructor autho
     let response = await match[2](null, {}, ctxFor(userIdentity));
     globalThis.expect(getTypename(response)).toEqual("CommandRejected");
     globalThis.expect(getErrorCode(response)).toEqual("Forbidden");
+    globalThis.expect(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(response), o => o["cause"]), Stdlib_JSON.Decode.string)).toEqual("ACCESS");
     globalThis.expect(match[3].contents).toEqual([]);
   });
   globalThis.test("anonymous invoking Archive is rejected with Forbidden", async () => {

package/tests/adapter/GraphQL_SchemaInspectorTest.res

@@ -609,9 +609,9 @@ describe("GraphQL_SchemaInspector", () => {
         let inspection = ReventlessCore.GraphQL_SchemaInspector.inspectFragment(fragment)
         // TestState, TestStateEdge, TestStateConnection, TestStateFilter (connection filter)
         // + TestStateRef (the reference door's projection)
-        // + CommandResult union + CommandAccepted + CommandRejected + CommandPending
-        // (auto-injected whenever the fragment emits any mutation field).
-        expect(inspection.types->Array.length)->toBe(9)
+        // + CommandResult union + CommandAccepted + CommandRejectionCause + CommandRejected
+        // + CommandPending (auto-injected whenever the fragment emits any mutation field).
+        expect(inspection.types->Array.length)->toBe(10)
         expect(inspection.mutations->Array.length)->toBe(1)
         // single Test_State(id), list Test_States(...), Test_StatesByIds(ids: [String!]!)
         // and Test_StatesRefs(ids: [ID!]!) — the by-ids read projected to a reference.

package/tests/adapter/GraphQL_SchemaInspectorTest.res.mjs

@@ -430,7 +430,7 @@ globalThis.describe("GraphQL_SchemaInspector", () => {
           authorization: undefined
         }]);
       let inspection = GraphQL_SchemaInspector$ReventlessCore.inspectFragment(fragment);
-      globalThis.expect(inspection.types.length).toBe(9);
+      globalThis.expect(inspection.types.length).toBe(10);
       globalThis.expect(inspection.mutations.length).toBe(1);
       globalThis.expect(inspection.queries.length).toBe(4);
       globalThis.expect(inspection.sdlPreview.includes("type TestState")).toBe(true);

package/tests/adapter/InboundTranslationMutationTest.res

@@ -44,6 +44,11 @@ let selection = `__typename
   ... on CommandAccepted { msgId entityId eventCount }
   ... on CommandRejected { msgId errorCode errorDetail }`
 
+// The same selection with `cause`, which a client opts into.
+let selectionWithCause = `__typename
+  ... on CommandAccepted { msgId entityId eventCount }
+  ... on CommandRejected { msgId errorCode errorDetail cause }`
+
 let signedIn = (groups): Reventless.Identity.t => {
   userId: "u-1",
   username: "alice",
@@ -67,7 +72,7 @@ let execute = async (~caller, source) =>
     "contextValue": contextOf(caller),
   })
 
-let runMutation = async (~status: string) =>
+let runMutation = async (~status: string, ~selection=selection) =>
   await execute(
     ~caller=Some(signedIn([])),
     `mutation {
@@ -153,6 +158,23 @@ describe("InboundTranslationSlice mutation — response envelope", () => {
     expect(published.contents->Array.length)->toBe(0)
   })
 
+  testPromise("a client selecting cause learns the model said no", async () => {
+    let result = await runMutation(~status="pending", ~selection=selectionWithCause)
+    expect(errorMessages(result))->toEqual([])
+    let node = payload(result)
+    expect(node->str("errorCode"))->toEqual(Some("TranslationFailed"))
+    expect(node->str("cause"))->toEqual(Some("DOMAIN"))
+  })
+
+  testPromise("a client not selecting cause gets exactly the fields it asked for", async () => {
+    let node = payload(await runMutation(~status="pending"))
+    expect(
+      node
+      ->JSON.Decode.object
+      ->Option.map(d => d->Dict.keysToArray->Array.toSorted(String.compare)),
+    )->toEqual(Some(["__typename", "errorCode", "errorDetail", "msgId"]))
+  })
+
   testSync("the mutation field is typed CommandResult!", () => {
     let fieldLine =
       DomainGraphQL_Server.asInterface.buildSdl()
@@ -176,7 +198,7 @@ let feedField = "Catalog_CatalogFeed"
 let runFeed = async (~caller, ~kind) =>
   await execute(
     ~caller,
-    `mutation { r: ${feedField}(kind: "${kind}", id: "x-1") { ${selection} } }`,
+    `mutation { r: ${feedField}(kind: "${kind}", id: "x-1") { ${selectionWithCause} } }`,
   )
 
 describe("InboundTranslationSlice mutation — the door", () => {
@@ -206,6 +228,7 @@ describe("InboundTranslationSlice mutation — the door", () => {
   testPromise("a caller holding none of the commands' roles is refused", async () => {
     let node = payload(await runFeed(~caller=Some(signedIn(["Ops"])), ~kind="product"))
     expect(node->str("errorCode"))->toEqual(Some("Forbidden"))
+    expect(node->str("cause"))->toEqual(Some("ACCESS"))
     expect(published.contents->Array.length)->toBe(0)
   })
 
@@ -225,6 +248,7 @@ describe("InboundTranslationSlice mutation — the door", () => {
   testPromise("the caller reaches the per-command check", async () => {
     let node = payload(await runFeed(~caller=Some(signedIn(["Merchandiser"])), ~kind="both"))
     expect(node->str("errorCode"))->toEqual(Some("Forbidden"))
+    expect(node->str("cause"))->toEqual(Some("ACCESS"))
     expect(published.contents->Array.length)->toBe(0)
   })
 })

package/tests/adapter/InboundTranslationMutationTest.res.mjs

@@ -5,6 +5,7 @@ import * as Stdlib_Dict from "@rescript/runtime/lib/es6/Stdlib_Dict.js";
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as Identity$Reventless from "@reventlessdev/reventless-spec/src/types/Identity.res.mjs";
 import * as Util_Sury$Reventless from "@reventlessdev/reventless-spec/src/util/Util_Sury.res.mjs";
 import * as Dcb_Builder$ReventlessCore from "@reventlessdev/reventless-core/src/components/Dcb/Dcb_Builder.res.mjs";
@@ -49,6 +50,10 @@ let selection = `__typename
   ... on CommandAccepted { msgId entityId eventCount }
   ... on CommandRejected { msgId errorCode errorDetail }`;
 
+let selectionWithCause = `__typename
+  ... on CommandAccepted { msgId entityId eventCount }
+  ... on CommandRejected { msgId errorCode errorDetail cause }`;
+
 function signedIn(groups) {
   return {
     userId: "u-1",
@@ -77,9 +82,10 @@ async function execute(caller, source) {
   });
 }
 
-async function runMutation(status) {
+async function runMutation(status, selectionOpt) {
+  let selection$1 = selectionOpt !== undefined ? selectionOpt : selection;
   return await execute(signedIn([]), `mutation {
-    r: ` + fieldName + `(paymentId: "pay-1", orderId: "ord-1", status: "` + status + `") { ` + selection + ` }
+    r: ` + fieldName + `(paymentId: "pay-1", orderId: "ord-1", status: "` + status + `") { ` + selection$1 + ` }
   }`);
 }
 
@@ -110,7 +116,7 @@ globalThis.describe("InboundTranslationSlice mutation — response envelope", ()
     InboundTranslationResolvers_GraphQL$ReventlessLocal.bindReceive(fieldName, (inputJson, caller) => Callback.receive(publishJsons, inputJson, caller, undefined));
   });
   globalThis.test("a successful translation resolves as CommandAccepted, with no errors", async () => {
-    let result = await runMutation("completed");
+    let result = await runMutation("completed", undefined);
     globalThis.expect(errorMessages(result)).toEqual([]);
     let node = payload(result);
     globalThis.expect(str(node, "__typename")).toEqual("CommandAccepted");
@@ -121,7 +127,7 @@ globalThis.describe("InboundTranslationSlice mutation — response envelope", ()
     globalThis.expect(published.contents.length).toBe(1);
   });
   globalThis.test("a rejected translation resolves as CommandRejected, with no errors", async () => {
-    let result = await runMutation("pending");
+    let result = await runMutation("pending", undefined);
     globalThis.expect(errorMessages(result)).toEqual([]);
     let node = payload(result);
     globalThis.expect(str(node, "__typename")).toEqual("CommandRejected");
@@ -136,6 +142,22 @@ globalThis.describe("InboundTranslationSlice mutation — response envelope", ()
     }
     globalThis.expect(published.contents.length).toBe(0);
   });
+  globalThis.test("a client selecting cause learns the model said no", async () => {
+    let result = await runMutation("pending", selectionWithCause);
+    globalThis.expect(errorMessages(result)).toEqual([]);
+    let node = payload(result);
+    globalThis.expect(str(node, "errorCode")).toEqual("TranslationFailed");
+    globalThis.expect(str(node, "cause")).toEqual("DOMAIN");
+  });
+  globalThis.test("a client not selecting cause gets exactly the fields it asked for", async () => {
+    let node = payload(await runMutation("pending", undefined));
+    globalThis.expect(Stdlib_Option.map(Stdlib_JSON.Decode.object(node), d => Object.keys(d).toSorted(Primitive_string.compare))).toEqual([
+      "__typename",
+      "errorCode",
+      "errorDetail",
+      "msgId"
+    ]);
+  });
   globalThis.test("the mutation field is typed CommandResult!", () => {
     let fieldLine = DomainGraphQL_Server$ReventlessLocal.asInterface.buildSdl().split("\n").find(line => line.includes(fieldName));
     globalThis.expect(Stdlib_Option.map(fieldLine, l => l.endsWith(": CommandResult!"))).toEqual(true);
@@ -165,7 +187,7 @@ let CatalogFeedCallback = InboundTranslationSlice_Callback$ReventlessCore.Make({
 let feedField = "Catalog_CatalogFeed";
 
 async function runFeed(caller, kind) {
-  return await execute(caller, `mutation { r: ` + feedField + `(kind: "` + kind + `", id: "x-1") { ` + selection + ` } }`);
+  return await execute(caller, `mutation { r: ` + feedField + `(kind: "` + kind + `", id: "x-1") { ` + selectionWithCause + ` } }`);
 }
 
 globalThis.describe("InboundTranslationSlice mutation — the door", () => {
@@ -180,6 +202,7 @@ globalThis.describe("InboundTranslationSlice mutation — the door", () => {
   globalThis.test("a caller holding none of the commands' roles is refused", async () => {
     let node = payload(await runFeed(signedIn(["Ops"]), "product"));
     globalThis.expect(str(node, "errorCode")).toEqual("Forbidden");
+    globalThis.expect(str(node, "cause")).toEqual("ACCESS");
     globalThis.expect(published.contents.length).toBe(0);
   });
   globalThis.test("an unauthenticated caller is refused", async () => {
@@ -195,6 +218,7 @@ globalThis.describe("InboundTranslationSlice mutation — the door", () => {
   globalThis.test("the caller reaches the per-command check", async () => {
     let node = payload(await runFeed(signedIn(["Merchandiser"]), "both"));
     globalThis.expect(str(node, "errorCode")).toEqual("Forbidden");
+    globalThis.expect(str(node, "cause")).toEqual("ACCESS");
     globalThis.expect(published.contents.length).toBe(0);
   });
 });
@@ -207,6 +231,7 @@ export {
   published,
   publishJsons,
   selection,
+  selectionWithCause,
   signedIn,
   contextOf,
   execute,

package/tests/components/dcb/DcbRejectionCauseTest.res

@@ -0,0 +1,271 @@
+// A rejected command says who said no, on the wire a client reads. Driven through
+// the producer path (`runInlineAndCollect` → `commandOutcomeToJson`) over the real
+// in-memory and SQLite DCB stores: the model (`decide`), the caller (ownership),
+// and the platform (exhausted retries, a failing store).
+
+open JestGlobals
+
+let _ = TestRunner.setup()
+let opts: Pulumi.CustomResourceOptions.t = {}
+
+module Message = ReventlessCore.Message
+module CommandTopic_Helpers = ReventlessCore.CommandTopic_Helpers
+
+module OrderSlice = {
+  let name = "CauseOrders"
+  module Id = Reventless.Id.String
+  let moduleUrl: string = %raw(`import.meta.url`)
+
+  @schema
+  type event =
+    | OrderPlaced({orderId: @s.matches(Reventless.DcbTag.string) string, customerId: string})
+    | OrderCancelled({orderId: @s.matches(Reventless.DcbTag.string) string})
+
+  @schema
+  type consumedEvent =
+    | OrderPlaced({
+        orderId: @s.matches(Reventless.DcbTag.string) string,
+        customerId: @s.matches(Reventless.Owner.string) string,
+      })
+    | OrderCancelled({orderId: @s.matches(Reventless.DcbTag.string) string})
+
+  @schema
+  type command =
+    | PlaceOrder({
+        orderId: @s.matches(Reventless.DcbTag.string) string,
+        customerId: @s.matches(Reventless.Owner.string) string,
+      })
+    | CancelOrder({orderId: @s.matches(Reventless.DcbTag.string) string})
+
+  @schema
+  type error = OrderAlreadyPlaced | OrderNotFound
+}
+
+module OrderDecision = {
+  type state = {placed: bool, cancelled: bool}
+  let initialState = {placed: false, cancelled: false}
+  let moduleUrl = OrderSlice.moduleUrl
+
+  let evolve = (state, event: OrderSlice.consumedEvent) =>
+    switch event {
+    | OrderPlaced(_) => {...state, placed: true}
+    | OrderCancelled(_) => {...state, cancelled: true}
+    }
+
+  let decide = (state, command: OrderSlice.command): result<
+    array<OrderSlice.event>,
+    OrderSlice.error,
+  > =>
+    switch command {
+    | PlaceOrder({orderId, customerId}) =>
+      state.placed ? Error(OrderAlreadyPlaced) : Ok([OrderPlaced({orderId, customerId})])
+    | CancelOrder({orderId}) =>
+      state.placed ? Ok([OrderCancelled({orderId: orderId})]) : Error(OrderNotFound)
+    }
+}
+
+module OrderHandler = ReventlessCore.StateChangeSlice_Callback.Make(OrderSlice, OrderDecision)
+
+let partitionTag = Reventless.DcbTag.Simple({key: "orderId"})
+
+// ─── Callers ────────────────────────────────────────────────────────────────
+
+external asIdentity: 'a => Reventless.Identity.t = "%identity"
+
+let cognito = (~userId): Reventless.Identity.t =>
+  asIdentity({"userId": userId, "username": userId, "groups": ["User"], "provider": "Cognito"})
+
+let owner = cognito(~userId="cust-A")
+let stranger = cognito(~userId="cust-B")
+
+// ─── Generator → producer path ──────────────────────────────────────────────
+
+let generated: ref<array<Message.commandJson>> = ref([])
+
+let generate = ReventlessCore.CommandGenerator_Callback.makeGenerateCommand(
+  ~publishJsons=async cmds => generated := generated.contents->Array.concat(cmds),
+  ~serviceName=OrderSlice.name,
+  ~commandSchema=OrderSlice.commandSchema->S.castToUnknown,
+  ~componentKind=ReventlessCore.CommandGenerator_Callback.StateChangeSlice,
+  ~stripIdFromParams=false,
+)
+
+let envelope = async (~command, ~args, ~identity) => {
+  generated := []
+  let p: ReventlessCore.CommandGenerator.payload = Obj.magic({
+    "command": command,
+    "arguments": Obj.magic(Dict.fromArray(args)),
+    "meta": {"ip": [], "user": "test", "info": ""},
+    "identity": identity,
+  })
+  let _ = await generate(p)->Effect.runPromise
+  generated.contents->Array.getUnsafe(0)
+}
+
+let handlerOver = (eventLog): CommandTopic_Helpers.jsonCommandsHandler =>
+  stream =>
+    OrderHandler.handleCommands(
+      ~partitionTag,
+      eventLog,
+      stream->Stream.map((item: CommandTopic_Helpers.topicItem<JSON.t>) => {
+        ReventlessInfra.CommandTopic.command: item.command->Message.decodeCommand'(
+          Reventless.Id.String.schema,
+          OrderSlice.commandSchema,
+        ),
+        reference: item.reference,
+      }),
+    )
+
+// The wire answer a client gets for one command: (`__typename`, `errorCode`, `cause`).
+let send = async (eventLog, cmd: Message.commandJson) => {
+  let outcomes = await CommandTopic_Helpers.runInlineAndCollect([cmd], handlerOver(eventLog))
+  let json = outcomes->Array.getUnsafe(0)->CommandTopic_Helpers.commandOutcomeToJson
+  let str = key =>
+    json
+    ->JSON.Decode.object
+    ->Option.flatMap(o => o->Dict.get(key))
+    ->Option.flatMap(JSON.Decode.string)
+  (str("__typename"), str("errorCode"), str("cause"))
+}
+
+let str = JSON.Encode.string
+let place = (~identity) =>
+  envelope(
+    ~command="PlaceOrder",
+    ~args=[("orderId", str("o-1")), ("customerId", str("cust-A"))],
+    ~identity,
+  )
+let cancel = (~identity) =>
+  envelope(~command="CancelOrder", ~args=[("orderId", str("o-1"))], ~identity)
+
+// ─── Backends ───────────────────────────────────────────────────────────────
+
+type appendMode = Real | AlwaysConflict | StoreFails
+
+// One fresh event log per scenario; `mode` replaces the store's append to fail
+// the way the platform can.
+let eventLogOn = async (~name, ~mode) => {
+  module Bus = LocalBus.Make()
+  module Storage = LocalDcbEventLogStorage.Make(Bus)
+  let s = Storage.make(
+    ~name,
+    ~indexes=[],
+    ~partitionTag=Reventless.DcbTag.Simple({key: "orderId"}),
+    ~opts,
+  )
+  let real = await s.operations->TestRunner.resolve
+  let storage: ReventlessCore.DcbEventLog_Adapter.operations = switch mode {
+  | Real => real
+  | AlwaysConflict => {...real, append: async (_, ~condition as _=?) => Error(Conflict)}
+  | StoreFails => {
+      ...real,
+      append: async (_, ~condition as _=?) => Error(StorageFailure("disk unavailable")),
+    }
+  }
+  module Log = ReventlessCore.DcbEventLog_Operations.Make({
+    let name = name
+    let serviceName = name
+    let storage = storage
+    let publishJson = async (_, _, _) => ()
+  })
+  let eventLog: ReventlessCore.DcbEventLog.operations = {
+    read: Log.read,
+    append: Log.append,
+    readStream: Log.readStream,
+    appendStream: Log.appendStream,
+  }
+  eventLog
+}
+
+let runUnderMemory = async fn => {
+  BackendState.setMemory()
+  await fn()
+}
+
+let runUnderSqlite = async fn => {
+  let db = SqliteDriver.openDb(~path=":memory:")
+  BackendState.setSqlite(~db, ~path=":memory:")
+  await fn()
+  BackendState.setMemory()
+  db->SqliteDriver.close
+}
+
+let _ = beforeEach(() => {
+  Reventless.OwnerScope.setElevatedGroups(["Admin"])
+  OrderHandler.resetCache()
+})
+
+let counter = ref(0)
+let fresh = prefix => {
+  counter := counter.contents + 1
+  `${prefix}-${counter.contents->Int.toString}`
+}
+
+let backends = [("in-memory", runUnderMemory), ("SQLite", runUnderSqlite)]
+
+backends->Array.forEach(((label, runUnder)) =>
+  describe(`a rejection's cause (${label} backend)`, () => {
+    testPromise(
+      "the model's no: a decide error arrives with DOMAIN",
+      async () =>
+        await runUnder(
+          async () => {
+            let log = await eventLogOn(~name=fresh("CauseDomain"), ~mode=Real)
+            let first = await send(log, await place(~identity=owner))
+            expect(first)->toEqual((Some("CommandAccepted"), None, None))
+            let again = await send(log, await place(~identity=owner))
+            expect(again)->toEqual((
+              Some("CommandRejected"),
+              Some("OrderAlreadyPlaced"),
+              Some("DOMAIN"),
+            ))
+          },
+        ),
+    )
+
+    testPromise(
+      "the caller's no: an ownership refusal arrives with ACCESS",
+      async () =>
+        await runUnder(
+          async () => {
+            let log = await eventLogOn(~name=fresh("CauseAccess"), ~mode=Real)
+            let _ = await send(log, await place(~identity=owner))
+            let refused = await send(log, await cancel(~identity=stranger))
+            expect(refused)->toEqual((Some("CommandRejected"), Some("Forbidden"), Some("ACCESS")))
+          },
+        ),
+    )
+
+    testPromise(
+      "the platform's no: an exhausted retry loop arrives with INFRASTRUCTURE",
+      async () =>
+        await runUnder(
+          async () => {
+            let log = await eventLogOn(~name=fresh("CauseConflict"), ~mode=AlwaysConflict)
+            let failed = await send(log, await place(~identity=owner))
+            expect(failed)->toEqual((
+              Some("CommandRejected"),
+              Some("Conflict"),
+              Some("INFRASTRUCTURE"),
+            ))
+          },
+        ),
+    )
+
+    testPromise(
+      "the platform's no: a failing store arrives with INFRASTRUCTURE",
+      async () =>
+        await runUnder(
+          async () => {
+            let log = await eventLogOn(~name=fresh("CauseStore"), ~mode=StoreFails)
+            let failed = await send(log, await place(~identity=owner))
+            expect(failed)->toEqual((
+              Some("CommandRejected"),
+              Some("AppendFailed"),
+              Some("INFRASTRUCTURE"),
+            ))
+          },
+        ),
+    )
+  })
+)

package/tests/components/dcb/DcbRejectionCauseTest.res.mjs

@@ -0,0 +1,440 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Sury from "sury";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Effect from "effect/Effect";
+import * as Stream from "effect/Stream";
+import * as Owner$Reventless from "@reventlessdev/reventless-spec/src/components/Owner.res.mjs";
+import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
+import * as OwnerScope$Reventless from "@reventlessdev/reventless-spec/src/types/OwnerScope.res.mjs";
+import * as Message$ReventlessCore from "@reventlessdev/reventless-core/src/Message.res.mjs";
+import * as LocalBus$ReventlessLocal from "../../../src/adapter/LocalBus.res.mjs";
+import * as TestRunner$ReventlessLocal from "../../../src/test/TestRunner.res.mjs";
+import * as BackendState$ReventlessLocal from "../../../src/adapter/BackendState.res.mjs";
+import * as SqliteDriver$ReventlessLocal from "../../../src/adapter/SqliteDriver.res.mjs";
+import * as CommandTopic_Helpers$ReventlessCore from "@reventlessdev/reventless-core/src/components/CommandTopic/CommandTopic_Helpers.res.mjs";
+import * as DcbEventLog_Operations$ReventlessCore from "@reventlessdev/reventless-core/src/components/DcbEventLog/DcbEventLog_Operations.res.mjs";
+import * as LocalDcbEventLogStorage$ReventlessLocal from "../../../src/adapter/DcbEventLog/LocalDcbEventLogStorage.res.mjs";
+import * as CommandGenerator_Callback$ReventlessCore from "@reventlessdev/reventless-core/src/components/CommandGenerator/CommandGenerator_Callback.res.mjs";
+import * as StateChangeSlice_Callback$ReventlessCore from "@reventlessdev/reventless-core/src/components/StateChangeSlice/StateChangeSlice_Callback.res.mjs";
+
+TestRunner$ReventlessLocal.setup();
+
+let opts = {};
+
+let name = "CauseOrders";
+
+let moduleUrl = import.meta.url;
+
+let eventSchema = Sury.union([
+  Sury.$schema(s => ({
+    TAG: "OrderPlaced",
+    orderId: s.m(DcbTag$Reventless.string),
+    customerId: s.m(Sury.string)
+  })),
+  Sury.$schema(s => ({
+    TAG: "OrderCancelled",
+    orderId: s.m(DcbTag$Reventless.string)
+  }))
+]);
+
+let consumedEventSchema = Sury.union([
+  Sury.$schema(s => ({
+    TAG: "OrderPlaced",
+    orderId: s.m(DcbTag$Reventless.string),
+    customerId: s.m(Owner$Reventless.string)
+  })),
+  Sury.$schema(s => ({
+    TAG: "OrderCancelled",
+    orderId: s.m(DcbTag$Reventless.string)
+  }))
+]);
+
+let commandSchema = Sury.union([
+  Sury.$schema(s => ({
+    TAG: "PlaceOrder",
+    orderId: s.m(DcbTag$Reventless.string),
+    customerId: s.m(Owner$Reventless.string)
+  })),
+  Sury.$schema(s => ({
+    TAG: "CancelOrder",
+    orderId: s.m(DcbTag$Reventless.string)
+  }))
+]);
+
+let errorSchema = Sury.union([
+  Sury.literal("OrderAlreadyPlaced"),
+  Sury.literal("OrderNotFound")
+]);
+
+function authorizationOf(param) {
+  return "AllowAuthenticated";
+}
+
+function commandTransition(param) {
+  return "Undeclared";
+}
+
+let traits = [];
+
+let OrderSlice = {
+  name: name,
+  Id: undefined,
+  moduleUrl: moduleUrl,
+  eventSchema: eventSchema,
+  consumedEventSchema: consumedEventSchema,
+  commandSchema: commandSchema,
+  errorSchema: errorSchema,
+  authorizationOf: authorizationOf,
+  commandTransition: commandTransition,
+  traits: traits,
+  readConsistency: "EscalateOnRetry"
+};
+
+let initialState = {
+  placed: false,
+  cancelled: false
+};
+
+function evolve(state, event) {
+  if (event.TAG === "OrderPlaced") {
+    return {
+      placed: true,
+      cancelled: state.cancelled
+    };
+  } else {
+    return {
+      placed: state.placed,
+      cancelled: true
+    };
+  }
+}
+
+function decide(state, command) {
+  if (command.TAG === "PlaceOrder") {
+    if (state.placed) {
+      return {
+        TAG: "Error",
+        _0: "OrderAlreadyPlaced"
+      };
+    } else {
+      return {
+        TAG: "Ok",
+        _0: [{
+            TAG: "OrderPlaced",
+            orderId: command.orderId,
+            customerId: command.customerId
+          }]
+      };
+    }
+  } else if (state.placed) {
+    return {
+      TAG: "Ok",
+      _0: [{
+          TAG: "OrderCancelled",
+          orderId: command.orderId
+        }]
+    };
+  } else {
+    return {
+      TAG: "Error",
+      _0: "OrderNotFound"
+    };
+  }
+}
+
+let OrderDecision = {
+  initialState: initialState,
+  moduleUrl: moduleUrl,
+  evolve: evolve,
+  decide: decide
+};
+
+let OrderHandler = StateChangeSlice_Callback$ReventlessCore.Make({
+  name: name,
+  moduleUrl: moduleUrl,
+  consumedEventSchema: consumedEventSchema,
+  errorSchema: errorSchema,
+  eventSchema: eventSchema,
+  commandSchema: commandSchema,
+  authorizationOf: authorizationOf,
+  commandTransition: commandTransition,
+  traits: traits,
+  readConsistency: "EscalateOnRetry"
+})({
+  initialState: initialState,
+  evolve: evolve,
+  decide: decide,
+  moduleUrl: moduleUrl
+});
+
+let partitionTag = {
+  TAG: "Simple",
+  _0: {
+    key: "orderId"
+  }
+};
+
+function cognito(userId) {
+  return {
+    userId: userId,
+    username: userId,
+    groups: ["User"],
+    provider: "Cognito"
+  };
+}
+
+let owner = {
+  userId: "cust-A",
+  username: "cust-A",
+  groups: ["User"],
+  provider: "Cognito"
+};
+
+let stranger = {
+  userId: "cust-B",
+  username: "cust-B",
+  groups: ["User"],
+  provider: "Cognito"
+};
+
+let generated = {
+  contents: []
+};
+
+let generate = CommandGenerator_Callback$ReventlessCore.makeGenerateCommand(async cmds => {
+  generated.contents = generated.contents.concat(cmds);
+}, undefined, name, commandSchema, "StateChangeSlice", false, undefined);
+
+async function envelope(command, args, identity) {
+  generated.contents = [];
+  let p = {
+    command: command,
+    arguments: Object.fromEntries(args),
+    meta: {
+      ip: [],
+      user: "test",
+      info: ""
+    },
+    identity: identity
+  };
+  await Effect.runPromise(generate(p));
+  return generated.contents[0];
+}
+
+function handlerOver(eventLog) {
+  return stream => OrderHandler.handleCommands(undefined, undefined, partitionTag, eventLog, Stream.map(stream, item => ({
+    command: Message$ReventlessCore.decodeCommand$p(item.command, Id$Reventless.$$String.schema, commandSchema),
+    reference: item.reference
+  })));
+}
+
+async function send(eventLog, cmd) {
+  let outcomes = await CommandTopic_Helpers$ReventlessCore.runInlineAndCollect([cmd], handlerOver(eventLog));
+  let json = CommandTopic_Helpers$ReventlessCore.commandOutcomeToJson(outcomes[0]);
+  let str = key => Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(json), o => o[key]), Stdlib_JSON.Decode.string);
+  return [
+    str("__typename"),
+    str("errorCode"),
+    str("cause")
+  ];
+}
+
+function str(prim) {
+  return prim;
+}
+
+function place(identity) {
+  return envelope("PlaceOrder", [
+    [
+      "orderId",
+      "o-1"
+    ],
+    [
+      "customerId",
+      "cust-A"
+    ]
+  ], identity);
+}
+
+function cancel(identity) {
+  return envelope("CancelOrder", [[
+      "orderId",
+      "o-1"
+    ]], identity);
+}
+
+async function eventLogOn(name, mode) {
+  let Bus = LocalBus$ReventlessLocal.Make({});
+  let Storage = LocalDcbEventLogStorage$ReventlessLocal.Make(Bus);
+  let s = Storage.make(name, [], {
+    TAG: "Simple",
+    _0: {
+      key: "orderId"
+    }
+  }, undefined, opts);
+  let real = await TestRunner$ReventlessLocal.resolve(s.operations);
+  let storage;
+  switch (mode) {
+    case "Real" :
+      storage = real;
+      break;
+    case "AlwaysConflict" :
+      storage = {
+        read: real.read,
+        append: async (param, param$1) => ({
+          TAG: "Error",
+          _0: "Conflict"
+        }),
+        readStream: real.readStream
+      };
+      break;
+    case "StoreFails" :
+      storage = {
+        read: real.read,
+        append: async (param, param$1) => ({
+          TAG: "Error",
+          _0: {
+            TAG: "StorageFailure",
+            _0: "disk unavailable"
+          }
+        }),
+        readStream: real.readStream
+      };
+      break;
+  }
+  let publishJson = async (param, param$1, param$2) => {};
+  let Log = DcbEventLog_Operations$ReventlessCore.Make({
+    name: name,
+    serviceName: name,
+    storage: storage,
+    publishJson: publishJson
+  });
+  return {
+    read: Log.read,
+    append: Log.append,
+    readStream: Log.readStream,
+    appendStream: Log.appendStream
+  };
+}
+
+async function runUnderMemory(fn) {
+  BackendState$ReventlessLocal.setMemory();
+  return await fn();
+}
+
+async function runUnderSqlite(fn) {
+  let db = SqliteDriver$ReventlessLocal.openDb(":memory:");
+  BackendState$ReventlessLocal.setSqlite(db, ":memory:");
+  await fn();
+  BackendState$ReventlessLocal.setMemory();
+  return SqliteDriver$ReventlessLocal.close(db);
+}
+
+globalThis.beforeEach(() => {
+  OwnerScope$Reventless.setElevatedGroups(["Admin"]);
+  OrderHandler.resetCache();
+});
+
+let counter = {
+  contents: 0
+};
+
+function fresh(prefix) {
+  counter.contents = counter.contents + 1 | 0;
+  return prefix + `-` + counter.contents.toString();
+}
+
+let backends = [
+  [
+    "in-memory",
+    runUnderMemory
+  ],
+  [
+    "SQLite",
+    runUnderSqlite
+  ]
+];
+
+backends.forEach(param => {
+  let runUnder = param[1];
+  globalThis.describe(`a rejection's cause (` + param[0] + ` backend)`, () => {
+    globalThis.test("the model's no: a decide error arrives with DOMAIN", async () => await runUnder(async () => {
+      let log = await eventLogOn(fresh("CauseDomain"), "Real");
+      let first = await send(log, await place(owner));
+      globalThis.expect(first).toEqual([
+        "CommandAccepted",
+        undefined,
+        undefined
+      ]);
+      let again = await send(log, await place(owner));
+      globalThis.expect(again).toEqual([
+        "CommandRejected",
+        "OrderAlreadyPlaced",
+        "DOMAIN"
+      ]);
+    }));
+    globalThis.test("the caller's no: an ownership refusal arrives with ACCESS", async () => await runUnder(async () => {
+      let log = await eventLogOn(fresh("CauseAccess"), "Real");
+      await send(log, await place(owner));
+      let refused = await send(log, await cancel(stranger));
+      globalThis.expect(refused).toEqual([
+        "CommandRejected",
+        "Forbidden",
+        "ACCESS"
+      ]);
+    }));
+    globalThis.test("the platform's no: an exhausted retry loop arrives with INFRASTRUCTURE", async () => await runUnder(async () => {
+      let log = await eventLogOn(fresh("CauseConflict"), "AlwaysConflict");
+      let failed = await send(log, await place(owner));
+      globalThis.expect(failed).toEqual([
+        "CommandRejected",
+        "Conflict",
+        "INFRASTRUCTURE"
+      ]);
+    }));
+    globalThis.test("the platform's no: a failing store arrives with INFRASTRUCTURE", async () => await runUnder(async () => {
+      let log = await eventLogOn(fresh("CauseStore"), "StoreFails");
+      let failed = await send(log, await place(owner));
+      globalThis.expect(failed).toEqual([
+        "CommandRejected",
+        "AppendFailed",
+        "INFRASTRUCTURE"
+      ]);
+    }));
+  });
+});
+
+let Message;
+
+let CommandTopic_Helpers;
+
+export {
+  opts,
+  Message,
+  CommandTopic_Helpers,
+  OrderSlice,
+  OrderDecision,
+  OrderHandler,
+  partitionTag,
+  cognito,
+  owner,
+  stranger,
+  generated,
+  generate,
+  envelope,
+  handlerOver,
+  send,
+  str,
+  place,
+  cancel,
+  eventLogOn,
+  runUnderMemory,
+  runUnderSqlite,
+  counter,
+  fresh,
+  backends,
+}
+/*  Not a pure module */