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

package/CHANGELOG.md

@@ -3,6 +3,32 @@
 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))
+
+### 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`".
+
+
+
 # 3.0.0-alpha.292 (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-local",
-  "version": "3.0.0-alpha.292",
+  "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": {
@@ -34,24 +34,24 @@
     "graphql-yoga": "^5.21.0",
     "sury": "11.0.0",
     "ws": "^8.18.0",
+    "@reventlessdev/rescript-effect": "1.0.0-alpha.1",
     "@reventlessdev/rescript-graphql-yoga": "1.0.0-alpha.29",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.13",
-    "@reventlessdev/rescript-effect": "1.0.0-alpha.1",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.23",
     "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.23",
     "@reventlessdev/rescript-pulumi-pulumi": "3.0.0-alpha.0",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.301",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.249",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.198",
-    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.149",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.165",
-    "@reventlessdev/reventless-seed": "1.0.0-alpha.35",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.170"
+    "@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",
     "sury-ppx": "11.0.0",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.103"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.104"
   },
   "peerDependencies": {
     "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";
@@ -672,7 +673,7 @@ function MakeWithConfig(Config) {
     isAsync: UiFragmentRegistrySlice_isAsync,
     make: UiFragmentRegistrySlice_make
   };
-  let Spec_Key = {
+  let Spec_Id = {
     schema: Id$Reventless.StringPure.schema,
     make: prim => prim,
     makeFromString: prim => prim,
@@ -683,7 +684,7 @@ function MakeWithConfig(Config) {
     name: UiFragments$ReventlessCore.name,
     moduleUrl: UiFragments$ReventlessCore.moduleUrl,
     stateSchema: UiFragments$ReventlessCore.stateSchema,
-    Key: Spec_Key,
+    Id: Spec_Id,
     consumedEventSchema: UiFragments$ReventlessCore.consumedEventSchema,
     config: UiFragments$ReventlessCore.config,
     subIdConfig: undefined,
@@ -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"
           ];
       }
@@ -2433,7 +2434,7 @@ function Make($star) {
     isAsync: UiFragmentRegistrySlice_isAsync,
     make: UiFragmentRegistrySlice_make
   };
-  let Spec_Key = {
+  let Spec_Id = {
     schema: Id$Reventless.StringPure.schema,
     make: prim => prim,
     makeFromString: prim => prim,
@@ -2444,7 +2445,7 @@ function Make($star) {
     name: UiFragments$ReventlessCore.name,
     moduleUrl: UiFragments$ReventlessCore.moduleUrl,
     stateSchema: UiFragments$ReventlessCore.stateSchema,
-    Key: Spec_Key,
+    Id: Spec_Id,
     consumedEventSchema: UiFragments$ReventlessCore.consumedEventSchema,
     config: UiFragments$ReventlessCore.config,
     subIdConfig: undefined,
@@ -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/adapter/CommandTopic/LocalCommandTopicChannel.res

@@ -62,7 +62,7 @@ module Make = (Bus: LocalBus.T) => {
     let handleChannelEvent = (
       handleCmds: ReventlessCore.CommandTopic.jsonCommandsHandler,
     ): Pulumi.Output.t<
-      ReventlessCore.Runtime.effectHandler<callbackEvent, 'context, unit, string>,
+      ReventlessCore.Runtime.effectInvocationHandler<callbackEvent, 'context, unit, string>,
     > => {
       handleCmdsRef.contents = Some(handleCmds)
 

package/src/adapter/Runtime/LocalRuntimeEnvironment.res

@@ -20,7 +20,7 @@ external asUnitHandler: ((JSON.t, unit) => promise<'r>) => (JSON.t, unit) => pro
 
 let make = (
   ~name as _: string,
-  ~handler: Pulumi.Output.t<ReventlessCore.Runtime.eventHandler<event, context, 'result>>,
+  ~handler: Pulumi.Output.t<ReventlessCore.Runtime.invocationHandler<event, context, 'result>>,
   ~memorySize as _=1024,
   ~timeout as _=30,
   ~opts as _=?,
@@ -62,6 +62,11 @@ let extractSentTimestamp = (_event: event) => Some(Date.now())
 // No redelivery in-process — the bus calls each handler once.
 let extractRetryCount = (_event: event) => Some(1)
 
-external asEventHandler: 'a => ReventlessCore.Runtime.eventHandler<event, context, 'r> = "%identity"
-external asEffectHandler: 'a => ReventlessCore.Runtime.effectHandler<event, context, 'r, 'error> =
+external asEventHandler: 'a => ReventlessCore.Runtime.invocationHandler<event, context, 'r> =
   "%identity"
+external asEffectHandler: 'a => ReventlessCore.Runtime.effectInvocationHandler<
+  event,
+  context,
+  'r,
+  'error,
+> = "%identity"

package/src/adapter/Task/LocalTaskBucket.res

@@ -17,7 +17,7 @@ let connect: Task_Adapter.connect<bucketParts, runtimeParts> = (
   ~opts as _,
 ) => ()
 
-let makeHandler = (callback: Task.bucketCallback): Runtime.eventHandler<
+let makeHandler = (callback: Task.bucketCallback): Runtime.invocationHandler<
   callbackEvent,
   context,
   array<Task.taskAction>,

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,