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

package/CHANGELOG.md

@@ -3,6 +3,13 @@
 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.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.228",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -28,17 +28,17 @@
   "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-ssh2": "2.0.0-alpha.4",
+    "@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/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/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([