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

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.228",
+  "version": "3.0.0-alpha.229",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -28,13 +28,13 @@
   "dependencies": {
     "sury": "11.0.0-alpha.4",
     "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-effect": "0.1.0-alpha.32",
-    "@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-interop": "3.0.0-alpha.30",

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/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);