@reventlessdev/reventless-core 3.0.0-alpha.227 → 3.0.0-alpha.229

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.229 (2026-08-12)
+
+### Bug Fixes
+
+* **command:** drop null arguments, and let a caller read why a payload was refused ([bfee0dc](https://github.com/ReventlessDev/reventless-core/commit/bfee0dc37755596ea8bcce1fe2cccdace7759f10))
+* **schema:** stop publishing a nested record's optional field as required ([44ed433](https://github.com/ReventlessDev/reventless-core/commit/44ed433fd40fc54cee41d7ab50aa7aafec851a2a))
+
+
+# 3.0.0-alpha.228 (2026-08-12)
+
+### Features
+
+* **api:** publish each mutation argument's GraphQL type on the command schema ([9ea1a5b](https://github.com/ReventlessDev/reventless-core/commit/9ea1a5bdf1957a726f6452e122c8fcda73ae824f))
+
+
 # 3.0.0-alpha.227 (2026-08-12)
 
 **Note:** Version bump only for package @reventlessdev/reventless-core

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.227",
+  "version": "3.0.0-alpha.229",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -30,15 +30,15 @@
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.4",
-    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-node": "2.0.0-alpha.4",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
     "@reventlessdev/rescript-ssh2": "2.0.0-alpha.4",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
+    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
     "@reventlessdev/reventless-infra": "3.0.0-alpha.137",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.111",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.111"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/components/Api/GraphQL_FragmentGenerator.res

@@ -475,6 +475,37 @@ let deriveMutationFieldFromObject = (
   | None => None
   }
 
+// The rendered GraphQL type of every argument one mutation field declares,
+// keyed by argument name — `"Ordering_PlaceOrderShippingMethod!"`,
+// `"DateRangeInput"`, `"[Ordering_PlaceOrderLineItems!]!"`.
+//
+// A client that assembles its own mutation document must declare a variable per
+// argument, and it cannot derive these from JSON Schema: an enum's type name is
+// composed from the mutation field and the property, an object's comes from a
+// semantic or the field path, and the nullability comes from whether the sury
+// schema wrapped it in an option. None of that survives the JSON-Schema
+// projection, so the name is published rather than left to be re-derived from a
+// convention that would then live in two repos shipping on different cycles.
+//
+// Deliberately the same `fromSchemaType` call `deriveMutationFieldFromObject`
+// makes: one producer, so the published string and the SDL cannot disagree.
+// The collected type *definitions* are discarded — a caller wants the reference
+// each argument renders as, and the definitions are already in the schema this
+// generator emits.
+let mutationArgTypes = (~fieldName: string, variantSchema: S.t<unknown>): option<dict<string>> =>
+  SchemaType.fromSuryObject(~typeName=fieldName, variantSchema)->Option.map(fields => {
+    let out = Dict.make()
+    fields
+    ->Dict.toArray
+    ->Array.forEach(((argName, argType)) =>
+      out->Dict.set(
+        argName,
+        fromSchemaType(~required=true, ~asInput=true, argType, [], Set.make()),
+      )
+    )
+    out
+  })
+
 // ── Main generate function ─────────────────────────────────────────────────
 
 let generate = (

package/src/components/Api/GraphQL_FragmentGenerator.res.mjs

@@ -390,6 +390,16 @@ function deriveMutationFieldFromObject(fieldName, collectedTypes, seenTypes, var
   return `  ` + fieldName + argsPart + `: CommandResult!`;
 }
 
+function mutationArgTypes(fieldName, variantSchema) {
+  return Stdlib_Option.map(SchemaType$ReventlessCore.fromSuryObject(fieldName, variantSchema), fields => {
+    let out = {};
+    Object.entries(fields).forEach(param => {
+      out[param[0]] = fromSchemaType(true, true, param[1], [], new Set());
+    });
+    return out;
+  });
+}
+
 function generate(mutationEntries, queryEntries) {
   let types = [];
   let mutations = [];
@@ -571,6 +581,7 @@ export {
   deriveByIdsQueryField,
   deriveConnectionQueryField,
   deriveMutationFieldFromObject,
+  mutationArgTypes,
   generate,
 }
 /* Api_Naming-ReventlessCore Not a pure module */

package/src/components/Api/SuryToJsonSchema.res

@@ -116,6 +116,19 @@ let mergeAnnotations = (
 
 // ── SchemaType → JSON Schema ─────────────────────────────────────────────
 
+// Whether a field's own type says it may be absent. Read through a semantic,
+// which wraps the shape rather than replacing it — an optional storage ref is
+// `Semantic(storageRef, Nullable(string))`.
+//
+// This is the half of "is it required" that `optional` cannot answer, and vice
+// versa. See `objectRefToJsonSchema`, which uses both.
+let rec isNullableType = (st: SchemaType.schemaType): bool =>
+  switch st {
+  | Nullable(_) => true
+  | Semantic(_, inner) => isNullableType(inner)
+  | _ => false
+  }
+
 let rec fromSchemaType = (st: SchemaType.schemaType): JSON.t =>
   switch st {
   | ScalarString => jsonObject([("type", str("string"))])
@@ -222,7 +235,16 @@ and objectRefToJsonSchema = (
       withAnnotations
     }
     props->Dict.set(fieldName, withAnnotations)
-    if !(optional->Array.includes(fieldName)) {
+    // Optional two ways, because neither source answers alone. `optional` is
+    // read off the sury schema and is the only thing that can speak for a
+    // reference or a tagged field, which classify as `EntityId` before their
+    // nullable wrapper is ever examined. But it is computed for the schema
+    // handed to `deriveObjectSchema` and there is no equivalent one level in,
+    // so a nested record's own optional field had nothing saying so and came
+    // out *required* — a generated form refusing to submit without a field the
+    // domain never asked for, which is the failure the note above describes,
+    // one level down. The field's own type answers there.
+    if !(optional->Array.includes(fieldName)) && !isNullableType(fieldType) {
       required->Array.push(fieldName)
     }
   })

package/src/components/Api/SuryToJsonSchema.res.mjs

@@ -106,6 +106,24 @@ function mergeAnnotations(fieldSchema, fieldName, spec) {
   return obj;
 }
 
+function isNullableType(_st) {
+  while (true) {
+    let st = _st;
+    if (typeof st !== "object") {
+      return false;
+    }
+    switch (st.TAG) {
+      case "Nullable" :
+        return true;
+      case "Semantic" :
+        _st = st._1;
+        continue;
+      default:
+        return false;
+    }
+  };
+}
+
 function fromSchemaType(st) {
   if (typeof st !== "object") {
     switch (st) {
@@ -229,8 +247,9 @@ function objectRefToJsonSchema(annotations, optionalOpt, ownersOpt, fields) {
   let props = {};
   let required = [];
   Object.entries(fields).forEach(param => {
+    let fieldType = param[1];
     let fieldName = param[0];
-    let baseSchema = fromSchemaType(param[1]);
+    let baseSchema = fromSchemaType(fieldType);
     let withAnnotations = annotations !== undefined ? mergeAnnotations(baseSchema, fieldName, annotations) : baseSchema;
     let withAnnotations$1;
     if (owners.includes(fieldName)) {
@@ -245,7 +264,7 @@ function objectRefToJsonSchema(annotations, optionalOpt, ownersOpt, fields) {
       withAnnotations$1 = withAnnotations;
     }
     props[fieldName] = withAnnotations$1;
-    if (!optional.includes(fieldName)) {
+    if (!optional.includes(fieldName) && !isNullableType(fieldType)) {
       required.push(fieldName);
       return;
     }
@@ -311,6 +330,7 @@ export {
   jsonObject,
   withOptionalPlugin,
   mergeAnnotations,
+  isNullableType,
   fromSchemaType,
   withSemantic,
   objectRefToJsonSchema,

package/src/components/CommandGenerator/CommandGenerator_Callback.res

@@ -66,12 +66,45 @@ let stampOwnerFields = (
     | Owned({userId}) =>
       ownerFields->Array.forEach(field => obj->Dict.set(field, JSON.Encode.string(userId)))
     | Unidentified(why) =>
-      JsError.throwWithMessage(
+      Plugin_ResolverError.throwCallerFault(
         `Forbidden: ${serviceName}.${command} records an owner, but the caller could not be identified (${why})`,
       )
     }
   }
 
+/**
+Drop the arguments a caller explicitly sent as null.
+
+A transport hands over exactly the arguments the caller supplied, and GraphQL
+lets a caller supply null for any nullable argument. A command cannot represent
+that: sury compiles both spellings of an optional field — `field?: t` and
+`option<t>` — to `T | undefined`, so an explicit null fails to decode where
+leaving the argument out succeeds. Two ways of saying the same thing, one of
+them accepted.
+
+Nothing is lost by collapsing them. No generated argument can *hold* a JSON
+null either — `GraphQL_FragmentGenerator` maps every schema type to a scalar, a
+generated enum, an input object or a list — so a null argument carries no
+information beyond "not supplied", which is what its absence says.
+
+Shallow on purpose. A null *inside* an input object is a malformed value rather
+than an omission, and the one payload that can legitimately carry nulls is the
+permissive `S.json` direct-invocation schema, where they are the caller's data
+and not arguments at all.
+
+Here rather than in a resolver: this is the one place every transport's payload
+passes through, for the reason `stampOwnerFields` gives just above.
+*/
+let dropNullArguments = (obj: dict<JSON.t>) =>
+  obj
+  ->Dict.keysToArray
+  ->Array.forEach(key =>
+    switch obj->Dict.get(key) {
+    | Some(JSON.Null) => obj->Dict.delete(key)
+    | _ => ()
+    }
+  )
+
 let makeGenerateCommand = (
   ~publishJsons: CommandGenerator.publishJsons,
   ~publishJsonsAndWait: option<CommandTopic.publishJsonsAndWait>=?,
@@ -100,6 +133,7 @@ let makeGenerateCommand = (
           if stripIdFromParams {
             obj->Dict.delete("id")
           }
+          obj->dropNullArguments
           obj->stampOwnerFields(
             ~commandSchema,
             ~command=payload.command,
@@ -216,10 +250,16 @@ let makeGenerateCommand = (
           })
         | None => ()
         }
-        JsError.throwWithMessage(
-          `Error: Couldn't decode ${commandJson->JSON.stringify}: ${err
-            ->JSON.stringifyAny
-            ->Option.getOrThrow}`,
+        // sury's own message says which field and why ("Failed parsing at
+        // [\"deliveryWindow\"]: Expected … received null"). Serialising the
+        // error object instead produced its internal representation, which is
+        // now the caller's to read and was never the more informative of the two.
+        let reason = switch err->JsExn.fromException->Option.flatMap(JsExn.message) {
+        | Some(message) => message
+        | None => err->JSON.stringifyAny->Option.getOr("unknown error")
+        }
+        Plugin_ResolverError.throwCallerFault(
+          `Error: Couldn't decode ${commandJson->JSON.stringify}: ${reason}`,
         )
       }
     })

package/src/components/CommandGenerator/CommandGenerator_Callback.res.mjs

@@ -2,6 +2,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 Effect from "effect/Effect";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
@@ -45,10 +46,19 @@ function stampOwnerFields(obj, commandSchema, command, identity, serviceName) {
       });
       return;
     case "Unidentified" :
-      return Stdlib_JsError.throwWithMessage(`Forbidden: ` + serviceName + `.` + command + ` records an owner, but the caller could not be identified (` + why._0 + `)`);
+      return Plugin_ResolverError$ReventlessCore.throwCallerFault(`Forbidden: ` + serviceName + `.` + command + ` records an owner, but the caller could not be identified (` + why._0 + `)`);
   }
 }
 
+function dropNullArguments(obj) {
+  Object.keys(obj).forEach(key => {
+    let match = obj[key];
+    if (match === null) {
+      return Stdlib_Dict.$$delete(obj, key);
+    }
+  });
+}
+
 function makeGenerateCommand(publishJsons, publishJsonsAndWait, serviceName, commandSchema, componentKind, $staropt$star) {
   return payload => {
     let stripIdFromParams = $staropt$star !== undefined ? $staropt$star : true;
@@ -66,7 +76,7 @@ function makeGenerateCommand(publishJsons, publishJsonsAndWait, serviceName, com
         correlationId: msgId
       };
       let obj = Stdlib_Option.flatMap(JSON.stringify(payload.arguments), jsonString => Stdlib_JSON.Decode.object(JSON.parse(jsonString)));
-      let params = obj !== undefined ? (stripIdFromParams ? Stdlib_Dict.$$delete(obj, "id") : undefined, stampOwnerFields(obj, commandSchema, payload.command, payload.identity, serviceName), Object.entries(obj)) : Stdlib_JsError.throwWithMessage("Couldn't decode:" + Stdlib_Option.getOr(JSON.stringify(payload.arguments), "<payload.arguments>"));
+      let params = obj !== undefined ? (stripIdFromParams ? Stdlib_Dict.$$delete(obj, "id") : undefined, dropNullArguments(obj), stampOwnerFields(obj, commandSchema, payload.command, payload.identity, serviceName), Object.entries(obj)) : Stdlib_JsError.throwWithMessage("Couldn't decode:" + Stdlib_Option.getOr(JSON.stringify(payload.arguments), "<payload.arguments>"));
       let commandStr = payload.command;
       let match = params.length;
       let commandJson = match !== 0 ? Object.fromEntries([[
@@ -123,7 +133,9 @@ function makeGenerateCommand(publishJsons, publishJsonsAndWait, serviceName, com
             timestamp: Message$ReventlessCore.nowAsISOString()
           });
         }
-        return Stdlib_JsError.throwWithMessage(`Error: Couldn't decode ` + JSON.stringify(commandJson) + `: ` + Stdlib_Option.getOrThrow(JSON.stringify(err), undefined));
+        let message = Stdlib_Option.flatMap(Stdlib_JsExn.fromException(err), Stdlib_JsExn.message);
+        let reason = message !== undefined ? message : Stdlib_Option.getOr(JSON.stringify(err), "unknown error");
+        return Plugin_ResolverError$ReventlessCore.throwCallerFault(`Error: Couldn't decode ` + JSON.stringify(commandJson) + `: ` + reason);
       }
       let interceptor = commandInterceptorHook.contents;
       let interceptEffect = interceptor !== undefined ? Effect.promise(() => interceptor(payload.identity, serviceName, componentKind, payload.command, payload.arguments)) : Effect.succeed("Allow");
@@ -181,7 +193,8 @@ export {
   registerCommandInterceptor,
   clearCommandInterceptor,
   stampOwnerFields,
+  dropNullArguments,
   makeGenerateCommand,
   Make,
 }
-/* effect/Effect Not a pure module */
+/* Stdlib_JsExn Not a pure module */

package/src/plugin/component/Plugin_ResolverError.res

@@ -25,3 +25,44 @@ let registerOnResolverError = (hook: resolverErrorInfo => unit) => {
 let clearOnResolverError = () => {
   onResolverErrorHook.contents = None
 }
+
+// ── Caller-fault errors ──────────────────────────────────────────────────────
+//
+// A failure a transport may report to the caller verbatim, because it describes
+// the caller's own request: a payload that does not decode against the command
+// schema, a caller who cannot be identified for a command that records an owner.
+//
+// It needs marking because the transports below deliberately hide everything
+// else. graphql-yoga's `maskedErrors` answers `Unexpected error /
+// INTERNAL_SERVER_ERROR` for any thrown value that is not a `GraphQLError`,
+// which is right for a driver failure — an internal error is not the caller's
+// business, and its message may not be theirs to read either. It is wrong for
+// the two cases above: the server knows precisely what is wrong with the request
+// and answers with the one thing the caller cannot act on.
+//
+// The mark rides on the error's `name` rather than a wrapper type, so it
+// survives the `Effect` boundary, the `promise` boundary and the transports'
+// `Obj.magic` interop unchanged, and an adapter that knows nothing about it
+// keeps treating the error exactly as it does today.
+let callerFaultName = "ReventlessCallerFault"
+
+@set external setErrorName: (JsError.t, string) => unit = "name"
+
+/** Throw a failure that describes the caller's own request. */
+let throwCallerFault = (message: string): 'a => {
+  let error = JsError.make(message)
+  error->setErrorName(callerFaultName)
+  error->JsError.throw
+}
+
+/** Whether a caught failure is one a transport may report verbatim.
+
+    Matched as a substring because a command is generated inside an `Effect`, and
+    a failure crossing `runPromise` comes back re-wrapped with the original name
+    carried into the wrapper's — `(FiberFailure) ReventlessCallerFault`. The mark
+    is a name, not a message, so nothing else can put it there. */
+let isCallerFault = (exn: exn): bool =>
+  exn
+  ->JsExn.fromException
+  ->Option.flatMap(JsExn.name)
+  ->Option.mapOr(false, name => name->String.includes(callerFaultName))

package/src/plugin/component/Plugin_ResolverError.res.mjs

@@ -1,5 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 
 let onResolverErrorHook = {
   contents: undefined
@@ -13,9 +15,24 @@ function clearOnResolverError() {
   onResolverErrorHook.contents = undefined;
 }
 
+let callerFaultName = "ReventlessCallerFault";
+
+function throwCallerFault(message) {
+  let error = new Error(message);
+  error.name = callerFaultName;
+  throw error;
+}
+
+function isCallerFault(exn) {
+  return Stdlib_Option.mapOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(exn), Stdlib_JsExn.name), false, name => name.includes(callerFaultName));
+}
+
 export {
   onResolverErrorHook,
   registerOnResolverError,
   clearOnResolverError,
+  callerFaultName,
+  throwCallerFault,
+  isCallerFault,
 }
-/* No side effect */
+/* Stdlib_JsExn Not a pure module */

package/src/plugin/component/Plugin_Structure.res

@@ -318,6 +318,32 @@ let make = (
     | AllowGroups(_) | AllowAuthenticated | AllowAnonymous | DenyAll => None
     }
 
+  // Write each mutation argument's rendered GraphQL type onto the property it
+  // belongs to, so a consumer assembling its own mutation document declares the
+  // variable the server actually expects instead of guessing `String!`.
+  //
+  // Mutates the freshly derived schema in place — `deriveObjectSchema` has just
+  // built it and nothing else holds it yet. A property with no matching
+  // argument is left alone rather than annotated with a guess.
+  let annotateArgTypes = (schema: JSON.t, argTypes: dict<string>): JSON.t => {
+    schema
+    ->JSON.Decode.object
+    ->Option.flatMap(o => o->Dict.get("properties"))
+    ->Option.flatMap(JSON.Decode.object)
+    ->Option.forEach(props =>
+      props
+      ->Dict.toArray
+      ->Array.forEach(((key, prop)) =>
+        switch (argTypes->Dict.get(key), prop->JSON.Decode.object) {
+        | (Some(gqlType), Some(p)) =>
+          p->Dict.set("x-reventless-graphql-type", JSON.Encode.string(gqlType))
+        | _ => ()
+        }
+      )
+    )
+    schema
+  }
+
   let toCommandDef = (
     ~isAggregate,
     ~mutationFieldFor: string => string,
@@ -360,6 +386,20 @@ let make = (
           ? {"TAG": variantName}->Obj.magic
           : variantName->Obj.magic
       let requiredAccess = accessKeysFor(commandAuthorization(syntheticCommand))
+      // See the note on the record's `mutationField` for why a non-exposed
+      // variant gets the empty sentinel. It has no callable field, and the
+      // argument type names are composed *from* that field name, so there is
+      // nothing to publish for it either.
+      let mutationField = apiExposed ? mutationFieldFor(variantName) : ""
+      let jsonSchema = v->SuryToJsonSchema.deriveObjectSchema
+      let annotatedSchema = if apiExposed {
+        GraphQL_FragmentGenerator.mutationArgTypes(~fieldName=mutationField, v)->Option.mapOr(
+          jsonSchema,
+          annotateArgTypes(jsonSchema, _),
+        )
+      } else {
+        jsonSchema
+      }
       ({
         Reventless.Plugin.name: variantName,
         // The derived schema, not sury's raw one: `S.toJSONSchema` carries the
@@ -369,7 +409,10 @@ let make = (
         // matches a field against its setter — or picks the upload endpoint of
         // the store a command argument declares — then has nothing to match on.
         // `MCP_SchemaGenerator` already derives these same variant schemas.
-        schema: v->SuryToJsonSchema.deriveObjectSchema->JSON.stringify,
+        //
+        // Carries `x-reventless-graphql-type` per property — see
+        // `annotateArgTypes`.
+        schema: annotatedSchema->JSON.stringify,
         level,
         aggregateIdField,
         // A non-exposed (`@noApi`) variant has no callable mutation field. For a
@@ -381,7 +424,7 @@ let make = (
         // stays listed with `apiExposed: false` for the event-graph badge, but
         // no consumer can mistake it for a callable field. Exposed variants are
         // byte-identical.
-        mutationField: apiExposed ? mutationFieldFor(variantName) : "",
+        mutationField,
         references,
         allowedStates,
         targetState,

package/src/plugin/component/Plugin_Structure.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+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 Primitive_int from "@rescript/runtime/lib/es6/Primitive_int.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
@@ -294,12 +295,27 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
           TAG: variantName
         }) : variantName;
       let requiredAccess = accessKeysFor(commandAuthorization(syntheticCommand));
+      let mutationField = apiExposed ? mutationFieldFor(variantName) : "";
+      let jsonSchema = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(v);
+      let annotatedSchema = apiExposed ? Stdlib_Option.mapOr(GraphQL_FragmentGenerator$ReventlessCore.mutationArgTypes(mutationField, v), jsonSchema, __x => {
+          Stdlib_Option.forEach(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(jsonSchema), o => o["properties"]), Stdlib_JSON.Decode.object), props => {
+            Object.entries(props).forEach(param => {
+              let match = __x[param[0]];
+              let match$1 = Stdlib_JSON.Decode.object(param[1]);
+              if (match !== undefined && match$1 !== undefined) {
+                match$1["x-reventless-graphql-type"] = match;
+                return;
+              }
+            });
+          });
+          return jsonSchema;
+        }) : jsonSchema;
       return {
         name: variantName,
-        schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(v)),
+        schema: JSON.stringify(annotatedSchema),
         level: match[0],
         aggregateIdField: match[1],
-        mutationField: apiExposed ? mutationFieldFor(variantName) : "",
+        mutationField: mutationField,
         references: references,
         allowedStates: allowedStates,
         targetState: targetState,

package/tests/api/GraphQL_FragmentGeneratorTest.res

@@ -256,3 +256,87 @@ describe("semantic composites are named once, not once per field", () => {
     ))->toEqual((1, 1, true))
   })
 })
+
+// `mutationArgTypes` is what a client that assembles its own mutation document
+// reads instead of guessing the variable types. Its whole value is that it
+// agrees with the SDL, so the last case here checks every published string
+// against the argument the generator emitted for the same command.
+module PlaceOrder = {
+  @schema
+  type shippingMethod = Standard | Express
+
+  // A single-payload command reaches the generator as a plain object schema —
+  // the `Object(_)` branch of `generate` — which is also the shape one variant
+  // of a union presents to `mutationArgTypes`.
+  let schema =
+    S.schema(s =>
+      {
+        "orderId": s.matches(S.string),
+        "shippingMethod": s.matches(shippingMethodSchema),
+        "total": s.matches(Reventless.Money.schema),
+        "tip": s.matches(S.option(Reventless.Money.schema)),
+        "itemCount": s.matches(S.int),
+      }
+    )->S.castToUnknown
+}
+
+describe("GraphQL_FragmentGenerator.mutationArgTypes", () => {
+  let argTypes =
+    GraphQL_FragmentGenerator.mutationArgTypes(
+      ~fieldName="Ordering_PlaceOrder",
+      PlaceOrder.schema,
+    )->Option.getOr(Dict.make())
+
+  let typeOf = (name: string) => argTypes->Dict.get(name)
+
+  // The defect this exists for: a client that fell back to `String!` here got
+  // `Variable "$shippingMethod" of type "String!" used in position expecting
+  // type "Ordering_PlaceOrderShippingMethod!"` — a 200 carrying no data. The
+  // name is composed from the mutation field, so nothing downstream of the
+  // JSON Schema can reconstruct it.
+  testSync("names an enum by the type the mutation field composes", () =>
+    expect(typeOf("shippingMethod"))->toEqual(Some("Ordering_PlaceOrderShippingMethod!"))
+  )
+
+  // A semantic composite is named after the semantic, and takes the `Input`
+  // suffix in argument position.
+  testSync("names a semantic composite by its input type", () =>
+    expect(typeOf("total"))->toEqual(Some("MoneyInput!"))
+  )
+
+  // Nullability is the other half of the answer: with the right name and an
+  // unconditional `!` appended, the declaration still would not match.
+  testSync("distinguishes an optional argument from a required one", () =>
+    expect((typeOf("tip"), typeOf("total")))->toEqual((Some("MoneyInput"), Some("MoneyInput!")))
+  )
+
+  // Both of these differ from what the JSON-Schema type alone suggests —
+  // `orderId` is a plain string there and `itemCount` an integer — which is the
+  // narrower reason a client cannot derive even the scalars itself.
+  testSync("reports the scalar the server chose, not the JSON-Schema one", () =>
+    expect((typeOf("orderId"), typeOf("itemCount")))->toEqual((Some("ID!"), Some("Float!")))
+  )
+
+  // The property that makes publishing worth more than re-deriving downstream:
+  // one producer, so what a client declares and what the server declares cannot
+  // drift apart.
+  testSync("agrees with every argument the SDL declares", () => {
+    let fragment = GraphQL_FragmentGenerator.generate(
+      ~mutationEntries=[
+        {
+          ReventlessInfra.Api.fieldNames: ["Ordering_PlaceOrder"],
+          commandSchema: PlaceOrder.schema,
+          injectIdArg: false,
+        },
+      ],
+      ~queryEntries=[],
+    )
+    let field = mutationFor(fragment, "Ordering_PlaceOrder")->Option.getOr("")
+    let mismatched =
+      argTypes
+      ->Dict.toArray
+      ->Array.filter(((arg, gqlType)) => !(field->String.includes(`${arg}: ${gqlType}`)))
+      ->Array.map(((arg, gqlType)) => `${arg}: ${gqlType}`)
+    expect((mismatched, field->String.length > 0))->toEqual(([], true))
+  })
+})

package/tests/api/GraphQL_FragmentGeneratorTest.res.mjs

@@ -260,6 +260,68 @@ globalThis.describe("semantic composites are named once, not once per field", ()
   });
 });
 
+let shippingMethodSchema = S.union([
+  S.literal("Standard"),
+  S.literal("Express")
+]);
+
+let schema = S.schema(s => ({
+  orderId: s.m(S.string),
+  shippingMethod: s.m(shippingMethodSchema),
+  total: s.m(Money$Reventless.schema),
+  tip: s.m(S.option(Money$Reventless.schema)),
+  itemCount: s.m(S.int)
+}));
+
+let PlaceOrder = {
+  shippingMethodSchema: shippingMethodSchema,
+  schema: schema
+};
+
+globalThis.describe("GraphQL_FragmentGenerator.mutationArgTypes", () => {
+  let argTypes = Stdlib_Option.getOr(GraphQL_FragmentGenerator$ReventlessCore.mutationArgTypes("Ordering_PlaceOrder", schema), {});
+  globalThis.test("names an enum by the type the mutation field composes", () => {
+    globalThis.expect(argTypes["shippingMethod"]).toEqual("Ordering_PlaceOrderShippingMethod!");
+  });
+  globalThis.test("names a semantic composite by its input type", () => {
+    globalThis.expect(argTypes["total"]).toEqual("MoneyInput!");
+  });
+  globalThis.test("distinguishes an optional argument from a required one", () => {
+    globalThis.expect([
+      argTypes["tip"],
+      argTypes["total"]
+    ]).toEqual([
+      "MoneyInput",
+      "MoneyInput!"
+    ]);
+  });
+  globalThis.test("reports the scalar the server chose, not the JSON-Schema one", () => {
+    globalThis.expect([
+      argTypes["orderId"],
+      argTypes["itemCount"]
+    ]).toEqual([
+      "ID!",
+      "Float!"
+    ]);
+  });
+  globalThis.test("agrees with every argument the SDL declares", () => {
+    let fragment = GraphQL_FragmentGenerator$ReventlessCore.generate([{
+        fieldNames: ["Ordering_PlaceOrder"],
+        commandSchema: schema,
+        injectIdArg: false
+      }], []);
+    let field = Stdlib_Option.getOr(mutationFor(fragment, "Ordering_PlaceOrder"), "");
+    let mismatched = Object.entries(argTypes).filter(param => !field.includes(param[0] + `: ` + param[1])).map(param => param[0] + `: ` + param[1]);
+    globalThis.expect([
+      mismatched,
+      field.length > 0
+    ]).toEqual([
+      [],
+      true
+    ]);
+  });
+});
+
 export {
   OrderSliceCmd,
   mutationFor,
@@ -267,5 +329,6 @@ export {
   typeDefFor,
   AddProductCmd,
   ChangePriceCmd,
+  PlaceOrder,
 }
 /* commandSchema Not a pure module */

package/tests/api/SuryToJsonSchemaTest.res

@@ -921,4 +921,40 @@ describe("SuryToJsonSchema:", () => {
       ))->toEqual((Some(JSON.Encode.string("number")), Some(JSON.Encode.string("number"))))
     })
   })
+
+  // A nested record's own optional field. `optional` is computed for the schema
+  // handed to `deriveObjectSchema` and not threaded into `ObjectRef`, so a field
+  // one level in has only its nullable wrapper to say it may be absent — and the
+  // wrapper is exactly what a reader looking at `required` never sees.
+  describe("an optional field inside a nested record:", () => {
+    let inner = S.schema(s =>
+      {
+        "street": s.matches(S.string),
+        "unit": s.matches(S.option(S.string)),
+      }
+    )
+    let json = SuryToJsonSchema.deriveObjectSchema(
+      S.schema(s =>
+        {
+          "id": s.matches(S.string),
+          "address": s.matches(inner),
+        }
+      )->S.castToUnknown,
+    )
+    let nestedRequired =
+      getPropertyOf(json, "address")
+      ->Option.flatMap(a => getProperty(a, "required"))
+      ->Option.flatMap(JSON.Decode.array)
+      ->Option.getOr([])
+      ->Array.filterMap(JSON.Decode.string)
+
+    testSync("is not listed as required", () =>
+      expect(nestedRequired->Array.includes("unit"))->toBe(false)
+    )
+
+    testSync("while its non-optional sibling still is", () =>
+      expect(nestedRequired->Array.includes("street"))->toBe(true)
+    )
+  })
+
 })

package/tests/api/SuryToJsonSchemaTest.res.mjs

@@ -1271,6 +1271,23 @@ globalThis.describe("SuryToJsonSchema:", () => {
       ]);
     });
   });
+  globalThis.describe("an optional field inside a nested record:", () => {
+    let inner = S.schema(s => ({
+      street: s.m(S.string),
+      unit: s.m(S.option(S.string))
+    }));
+    let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(S.schema(s => ({
+      id: s.m(S.string),
+      address: s.m(inner)
+    })));
+    let nestedRequired = Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(getPropertyOf(json, "address"), a => getProperty(a, "required")), Stdlib_JSON.Decode.array), []), Stdlib_JSON.Decode.string);
+    globalThis.test("is not listed as required", () => {
+      globalThis.expect(nestedRequired.includes("unit")).toBe(false);
+    });
+    globalThis.test("while its non-optional sibling still is", () => {
+      globalThis.expect(nestedRequired.includes("street")).toBe(true);
+    });
+  });
 });
 
 export {

package/tests/commandgenerator/CommandGeneratorCallbackTest.res

@@ -125,4 +125,108 @@ describe("CommandGenerator_Callback.generateCommand:", () => {
       expect(publishedCmd.id)->toBe("agg-7")
     })
   })
+
+  // A transport hands over exactly what the caller supplied, and GraphQL lets a
+  // caller supply null for any nullable argument. sury compiles an optional
+  // field to `T | undefined`, so an explicit null used to fail to decode where
+  // leaving the argument out succeeded — two ways of saying the same thing, one
+  // of them accepted.
+  describe("an argument sent as null", () => {
+    let storeItem = (~args) => makeSlicePayload(~command="StoreItem", ~args)
+    let data = JSON.Object(Dict.fromArray([("kind", JSON.String("blob"))]))
+    let fieldOf = (cmd: Message.commandJson, name) =>
+      cmd.commandJson->JSON.Decode.object->Option.flatMap(o => o->Dict.get(name))
+
+    testPromise("is dropped, and the command decodes and publishes", async () => {
+      let payload = storeItem(
+        ~args=Dict.fromArray([
+          ("itemId", JSON.Encode.string("item-1")),
+          ("data", data),
+          ("note", JSON.Null),
+        ]),
+      )
+      let _outcome = await optionalFieldSliceGen(payload)->Effect.runPromise
+      let publishedCmd = capturedCmds.contents->Array.getUnsafe(0)
+      expect((capturedCmds.contents->Array.length, publishedCmd->fieldOf("note")))
+      ->toEqual((1, None))
+    })
+
+    testPromise("carrying a value is left exactly as sent", async () => {
+      let payload = storeItem(
+        ~args=Dict.fromArray([
+          ("itemId", JSON.Encode.string("item-2")),
+          ("data", data),
+          ("note", JSON.Encode.string("gift wrap")),
+        ]),
+      )
+      let _outcome = await optionalFieldSliceGen(payload)->Effect.runPromise
+      expect(capturedCmds.contents->Array.getUnsafe(0)->fieldOf("note"))
+      ->toEqual(Some(JSON.Encode.string("gift wrap")))
+    })
+
+    // The control the drop is modelled on: absent and explicitly-null must
+    // reach the domain as the same command.
+    testPromise("and one simply omitted produce the same command", async () => {
+      let withNull = storeItem(
+        ~args=Dict.fromArray([
+          ("itemId", JSON.Encode.string("item-3")),
+          ("data", data),
+          ("note", JSON.Null),
+        ]),
+      )
+      let withoutKey = storeItem(
+        ~args=Dict.fromArray([("itemId", JSON.Encode.string("item-3")), ("data", data)]),
+      )
+      let _ = await optionalFieldSliceGen(withNull)->Effect.runPromise
+      let _ = await optionalFieldSliceGen(withoutKey)->Effect.runPromise
+      let published = capturedCmds.contents
+      expect((published->Array.getUnsafe(0)).commandJson)
+      ->toEqual((published->Array.getUnsafe(1)).commandJson)
+    })
+
+    // Shallow on purpose. A null one level in is part of a value the caller
+    // sent, not an argument they left out — `data` is opaque JSON and its own
+    // nulls are data.
+    testPromise("nested inside a value is left alone", async () => {
+      let nested = JSON.Object(Dict.fromArray([("kind", JSON.Null)]))
+      let payload = storeItem(
+        ~args=Dict.fromArray([("itemId", JSON.Encode.string("item-4")), ("data", nested)]),
+      )
+      let _outcome = await optionalFieldSliceGen(payload)->Effect.runPromise
+      expect(capturedCmds.contents->Array.getUnsafe(0)->fieldOf("data"))->toEqual(Some(nested))
+    })
+  })
+
+  // A payload that does not decode describes the caller's own request, so a
+  // transport is allowed to report it. Unmarked, it arrives as "Unexpected
+  // error" and is indistinguishable from a database outage.
+  describe("a payload that cannot be decoded", () => {
+    let undecodable = () =>
+      makeSlicePayload(
+        ~command="StoreItem",
+        ~args=Dict.fromArray([("itemId", JSON.Encode.string("item-9"))]),
+      )
+
+    testPromise("is refused rather than published", async () => {
+      let refused = switch await optionalFieldSliceGen(undecodable())->Effect.runPromise {
+      | _ => false
+      | exception _ => true
+      }
+      expect((refused, capturedCmds.contents->Array.length))->toEqual((true, 0))
+    })
+
+    testPromise("is marked as the caller's fault, naming the field", async () => {
+      let failure = switch await optionalFieldSliceGen(undecodable())->Effect.runPromise {
+      | _ => None
+      | exception e => Some(e)
+      }
+      let marked = failure->Option.mapOr(false, Plugin_ResolverError.isCallerFault)
+      let saysWhy =
+        failure
+        ->Option.flatMap(JsExn.fromException)
+        ->Option.flatMap(JsExn.message)
+        ->Option.mapOr(false, m => m->String.includes("data"))
+      expect((marked, saysWhy))->toEqual((true, true))
+    })
+  })
 })

package/tests/commandgenerator/CommandGeneratorCallbackTest.res.mjs

@@ -1,8 +1,11 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 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 Effect from "effect/Effect";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as Plugin_ResolverError$ReventlessCore from "../../src/plugin/component/Plugin_ResolverError.res.mjs";
 import * as CommandGeneratorFixtures$ReventlessCore from "./CommandGeneratorFixtures.res.mjs";
 
 globalThis.beforeEach(() => CommandGeneratorFixtures$ReventlessCore.reset());
@@ -155,6 +158,144 @@ globalThis.describe("CommandGenerator_Callback.generateCommand:", () => {
       globalThis.expect(publishedCmd.id).toBe("agg-7");
     });
   });
+  globalThis.describe("an argument sent as null", () => {
+    let data = Object.fromEntries([[
+        "kind",
+        "blob"
+      ]]);
+    let fieldOf = (cmd, name) => Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(cmd.commandJson), o => o[name]);
+    globalThis.test("is dropped, and the command decodes and publishes", async () => {
+      let payload = CommandGeneratorFixtures$ReventlessCore.makeSlicePayload("StoreItem", Object.fromEntries([
+        [
+          "itemId",
+          "item-1"
+        ],
+        [
+          "data",
+          data
+        ],
+        [
+          "note",
+          null
+        ]
+      ]));
+      await Effect.runPromise(CommandGeneratorFixtures$ReventlessCore.optionalFieldSliceGen(payload));
+      let publishedCmd = CommandGeneratorFixtures$ReventlessCore.capturedCmds.contents[0];
+      globalThis.expect([
+        CommandGeneratorFixtures$ReventlessCore.capturedCmds.contents.length,
+        fieldOf(publishedCmd, "note")
+      ]).toEqual([
+        1,
+        undefined
+      ]);
+    });
+    globalThis.test("carrying a value is left exactly as sent", async () => {
+      let payload = CommandGeneratorFixtures$ReventlessCore.makeSlicePayload("StoreItem", Object.fromEntries([
+        [
+          "itemId",
+          "item-2"
+        ],
+        [
+          "data",
+          data
+        ],
+        [
+          "note",
+          "gift wrap"
+        ]
+      ]));
+      await Effect.runPromise(CommandGeneratorFixtures$ReventlessCore.optionalFieldSliceGen(payload));
+      globalThis.expect(fieldOf(CommandGeneratorFixtures$ReventlessCore.capturedCmds.contents[0], "note")).toEqual("gift wrap");
+    });
+    globalThis.test("and one simply omitted produce the same command", async () => {
+      let withNull = CommandGeneratorFixtures$ReventlessCore.makeSlicePayload("StoreItem", Object.fromEntries([
+        [
+          "itemId",
+          "item-3"
+        ],
+        [
+          "data",
+          data
+        ],
+        [
+          "note",
+          null
+        ]
+      ]));
+      let withoutKey = CommandGeneratorFixtures$ReventlessCore.makeSlicePayload("StoreItem", Object.fromEntries([
+        [
+          "itemId",
+          "item-3"
+        ],
+        [
+          "data",
+          data
+        ]
+      ]));
+      await Effect.runPromise(CommandGeneratorFixtures$ReventlessCore.optionalFieldSliceGen(withNull));
+      await Effect.runPromise(CommandGeneratorFixtures$ReventlessCore.optionalFieldSliceGen(withoutKey));
+      let published = CommandGeneratorFixtures$ReventlessCore.capturedCmds.contents;
+      globalThis.expect(published[0].commandJson).toEqual(published[1].commandJson);
+    });
+    globalThis.test("nested inside a value is left alone", async () => {
+      let nested = Object.fromEntries([[
+          "kind",
+          null
+        ]]);
+      let payload = CommandGeneratorFixtures$ReventlessCore.makeSlicePayload("StoreItem", Object.fromEntries([
+        [
+          "itemId",
+          "item-4"
+        ],
+        [
+          "data",
+          nested
+        ]
+      ]));
+      await Effect.runPromise(CommandGeneratorFixtures$ReventlessCore.optionalFieldSliceGen(payload));
+      globalThis.expect(fieldOf(CommandGeneratorFixtures$ReventlessCore.capturedCmds.contents[0], "data")).toEqual(nested);
+    });
+  });
+  globalThis.describe("a payload that cannot be decoded", () => {
+    let undecodable = () => CommandGeneratorFixtures$ReventlessCore.makeSlicePayload("StoreItem", Object.fromEntries([[
+        "itemId",
+        "item-9"
+      ]]));
+    globalThis.test("is refused rather than published", async () => {
+      let refused;
+      try {
+        await Effect.runPromise(CommandGeneratorFixtures$ReventlessCore.optionalFieldSliceGen(undecodable()));
+        refused = false;
+      } catch (exn) {
+        refused = true;
+      }
+      globalThis.expect([
+        refused,
+        CommandGeneratorFixtures$ReventlessCore.capturedCmds.contents.length
+      ]).toEqual([
+        true,
+        0
+      ]);
+    });
+    globalThis.test("is marked as the caller's fault, naming the field", async () => {
+      let failure;
+      try {
+        await Effect.runPromise(CommandGeneratorFixtures$ReventlessCore.optionalFieldSliceGen(undecodable()));
+        failure = undefined;
+      } catch (raw_e) {
+        failure = Primitive_exceptions.internalToException(raw_e);
+      }
+      let marked = Stdlib_Option.mapOr(failure, false, Plugin_ResolverError$ReventlessCore.isCallerFault);
+      let saysWhy = Stdlib_Option.mapOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(failure, Stdlib_JsExn.fromException), Stdlib_JsExn.message), false, m => m.includes("data"));
+      globalThis.expect([
+        marked,
+        saysWhy
+      ]).toEqual([
+        true,
+        true
+      ]);
+    });
+  });
 });
 
 /*  Not a pure module */

package/tests/commandgenerator/CommandGeneratorFixtures.res

@@ -85,6 +85,25 @@ type compositeTagCommand =
       version: string,
     })
 
+// A command carrying an optional field beside an opaque-JSON one. The optional
+// field is what a caller can send as null; the JSON field is a value whose own
+// nulls are data and must survive.
+@schema
+type optionalFieldCommand =
+  StoreItem({
+    itemId: @s.matches(Reventless.DcbTag.string) string,
+    data: JSON.t,
+    note?: string,
+  })
+
+let optionalFieldSliceGen = CommandGenerator_Callback.makeGenerateCommand(
+  ~publishJsons=MockPublishSpec.publishJsons,
+  ~serviceName="OptionalFieldSlice",
+  ~commandSchema=optionalFieldCommandSchema->S.castToUnknown,
+  ~componentKind=CommandGenerator_Callback.StateChangeSlice,
+  ~stripIdFromParams=false,
+)
+
 let singleTagSliceGen = CommandGenerator_Callback.makeGenerateCommand(
   ~publishJsons=MockPublishSpec.publishJsons,
   ~serviceName="SingleTagSlice",

package/tests/commandgenerator/CommandGeneratorFixtures.res.mjs

@@ -124,6 +124,15 @@ let compositeTagCommandSchema = S.schema(s => ({
   version: s.m(S.string)
 }));
 
+let optionalFieldCommandSchema = S.schema(s => ({
+  TAG: "StoreItem",
+  itemId: s.m(DcbTag$Reventless.string),
+  data: s.m(S.json),
+  note: s.m(S.option(S.string))
+}));
+
+let optionalFieldSliceGen = CommandGenerator_Callback$ReventlessCore.makeGenerateCommand(publishJsons, undefined, "OptionalFieldSlice", optionalFieldCommandSchema, "StateChangeSlice", false);
+
 let singleTagSliceGen = CommandGenerator_Callback$ReventlessCore.makeGenerateCommand(publishJsons, undefined, "SingleTagSlice", singleTagCommandSchema, "StateChangeSlice", false);
 
 let compositeTagSliceGen = CommandGenerator_Callback$ReventlessCore.makeGenerateCommand(publishJsons, undefined, "CompositeTagSlice", compositeTagCommandSchema, "StateChangeSlice", false);
@@ -187,6 +196,8 @@ export {
   TestGenerator,
   singleTagCommandSchema,
   compositeTagCommandSchema,
+  optionalFieldCommandSchema,
+  optionalFieldSliceGen,
   singleTagSliceGen,
   compositeTagSliceGen,
   makeSlicePayload,

package/tests/commandgenerator/OwnerStampingTest.res

@@ -150,6 +150,19 @@ describe("@owner stamping on the command path:", () => {
       )->toBe(true)
     )
 
+    // The refusal describes the caller's own request, so a transport is allowed
+    // to report it. Unmarked it arrives as "Unexpected error", which tells a
+    // caller who needs to authenticate nothing at all.
+    testPromise("the refusal is marked as the caller's fault", async () => {
+      let failure = switch await generate(
+        placeOrder(~customerId="cust-B", ~identity=Reventless.Identity.anonymous),
+      )->Effect.runPromise {
+      | _ => None
+      | exception e => Some(e)
+      }
+      expect(failure->Option.mapOr(false, Plugin_ResolverError.isCallerFault))->toBe(true)
+    })
+
     testPromise("nothing is published when the caller is refused", async () => {
       let _ = await refused(
         placeOrder(~customerId="cust-B", ~identity=Reventless.Identity.anonymous),

package/tests/commandgenerator/OwnerStampingTest.res.mjs

@@ -7,7 +7,9 @@ import * as Effect from "effect/Effect";
 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 Identity$Reventless from "@reventlessdev/reventless-spec/src/types/Identity.res.mjs";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as OwnerScope$Reventless from "@reventlessdev/reventless-spec/src/types/OwnerScope.res.mjs";
+import * as Plugin_ResolverError$ReventlessCore from "../../src/plugin/component/Plugin_ResolverError.res.mjs";
 import * as CommandGenerator_Callback$ReventlessCore from "../../src/components/CommandGenerator/CommandGenerator_Callback.res.mjs";
 
 S.enableJson();
@@ -160,6 +162,16 @@ globalThis.describe("@owner stamping on the command path:", () => {
     globalThis.test("an anonymous caller cannot place an owned command", async () => {
       globalThis.expect(await refused(placeOrder("cust-B", Identity$Reventless.anonymous))).toBe(true);
     });
+    globalThis.test("the refusal is marked as the caller's fault", async () => {
+      let failure;
+      try {
+        await Effect.runPromise(generate(placeOrder("cust-B", Identity$Reventless.anonymous)));
+        failure = undefined;
+      } catch (raw_e) {
+        failure = Primitive_exceptions.internalToException(raw_e);
+      }
+      globalThis.expect(Stdlib_Option.mapOr(failure, false, Plugin_ResolverError$ReventlessCore.isCallerFault)).toBe(true);
+    });
     globalThis.test("nothing is published when the caller is refused", async () => {
       await refused(placeOrder("cust-B", Identity$Reventless.anonymous));
       globalThis.expect(published.contents.length).toBe(0);

package/tests/plugin/PluginStructureTest.res

@@ -259,6 +259,26 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       expect((shipField->String.length > 0, cancelField))->toEqual((true, ""))
     })
 
+    // A consumer that builds its own mutation document declares one variable
+    // per argument, and JSON Schema does not carry the GraphQL type those
+    // variables need — `orderId` reads as a plain string there while the server
+    // declares `ID!`. So the rendered type rides along on the property.
+    testSync("ShipOrder: the command schema publishes each argument's GraphQL type", () => {
+      let shipOrder = structure.stateChangeSlices->Array.getUnsafe(1)
+      let ship = shipOrder.commands->Array.find(c => c.name == "ShipOrder")->Option.getOrThrow
+      expect(ship.schema->String.includes(`"x-reventless-graphql-type":"ID!"`))->toBe(true)
+    })
+
+    // The names are composed from the mutation field, and a `@noApi` variant
+    // has none — publishing a type derived from the empty sentinel would name
+    // types no schema declares.
+    testSync("CancelShipment: a @noApi variant publishes no argument types", () => {
+      let shipOrder = structure.stateChangeSlices->Array.getUnsafe(1)
+      let cancel =
+        shipOrder.commands->Array.find(c => c.name == "CancelShipment")->Option.getOrThrow
+      expect(cancel.schema->String.includes("x-reventless-graphql-type"))->toBe(false)
+    })
+
     testSync("ShipOrder: payload-less event ShipmentVoided is surfaced in events", () => {
       let shipOrder = structure.stateChangeSlices->Array.getUnsafe(1)
       expect(shipOrder.events->Array.map(e => e.name))->toEqual(["OrderShipped", "ShipmentVoided"])

package/tests/plugin/PluginStructureTest.res.mjs

@@ -447,6 +447,16 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
         ""
       ]);
     });
+    globalThis.test("ShipOrder: the command schema publishes each argument's GraphQL type", () => {
+      let shipOrder = structure.stateChangeSlices[1];
+      let ship = Stdlib_Option.getOrThrow(shipOrder.commands.find(c => c.name === "ShipOrder"), undefined);
+      globalThis.expect(ship.schema.includes(`"x-reventless-graphql-type":"ID!"`)).toBe(true);
+    });
+    globalThis.test("CancelShipment: a @noApi variant publishes no argument types", () => {
+      let shipOrder = structure.stateChangeSlices[1];
+      let cancel = Stdlib_Option.getOrThrow(shipOrder.commands.find(c => c.name === "CancelShipment"), undefined);
+      globalThis.expect(cancel.schema.includes("x-reventless-graphql-type")).toBe(false);
+    });
     globalThis.test("ShipOrder: payload-less event ShipmentVoided is surfaced in events", () => {
       let shipOrder = structure.stateChangeSlices[1];
       globalThis.expect(shipOrder.events.map(e => e.name)).toEqual([