@reventlessdev/reventless-core 3.0.0-alpha.194 → 3.0.0-alpha.195

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.195 (2026-07-30)
+
+### Bug Fixes
+
+* **core:** a command's field markers reach the wire, and its optional fields stay optional ([f1c1112](https://github.com/ReventlessDev/reventless-core/commit/f1c1112e9baa6b06e50097a5a618f49c9301cd0a))
+
+
 # 3.0.0-alpha.194 (2026-07-30)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.194",
+  "version": "3.0.0-alpha.195",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -29,16 +29,16 @@
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.31",
-    "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.14",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.13",
-    "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
+    "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.14",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.17",
-    "@reventlessdev/rescript-uuid": "1.1.0-alpha.17",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.112",
+    "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
     "@reventlessdev/rescript-ssh2": "1.1.0-alpha.14",
+    "@reventlessdev/rescript-uuid": "1.1.0-alpha.17",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.17",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.29",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.87"
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.88",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.113"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/components/Api/SchemaType.res

@@ -141,6 +141,42 @@ and shapeOf = (~parentName: string, ~fieldName: string, schema: S.t<unknown>): s
   }
 }
 
+/**
+The names of an object's optional properties, read from sury rather than from
+the IR.
+
+The IR cannot answer this for every field. `shapeOf` classifies a DCB-tagged or
+`@ref` field as `EntityId` before it ever looks at the union sury wraps an
+`option<…>` in — correctly, since those markers now describe the field through
+that wrapper — so an optional reference reaches the IR as a plain `EntityId`
+with its optionality spent. Asking the source schema keeps the two questions
+apart: what a field *is*, and whether it has to be there.
+
+Top-level properties only. A nested object's own fields are emitted by the
+`ObjectRef` branch, which has no `required` of its own today.
+*/
+let optionalFieldNames = (schema: S.t<unknown>): array<string> =>
+  switch schema {
+  | Object({properties}) =>
+    properties
+    ->Dict.toArray
+    ->Array.filterMap(((propName, propSchema)) =>
+      switch propSchema {
+      | Union({anyOf}) =>
+        anyOf->Array.some(v =>
+          switch v {
+          | Null(_) | Undefined(_) => true
+          | _ => false
+          }
+        )
+          ? Some(propName)
+          : None
+      | _ => None
+      }
+    )
+  | _ => []
+  }
+
 let fromSuryObject = (~typeName: string, schema: S.t<unknown>): option<dict<schemaType>> =>
   switch schema {
   | Object({properties}) =>

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

@@ -150,6 +150,27 @@ function shapeOf(parentName, fieldName, schema) {
   }
 }
 
+function optionalFieldNames(schema) {
+  if (schema.type === "object") {
+    return Stdlib_Array.filterMap(Object.entries(schema.properties), param => {
+      let propSchema = param[1];
+      if (propSchema.type === "union" && propSchema.anyOf.some(v => {
+          switch (v.type) {
+            case "null" :
+            case "undefined" :
+              return true;
+            default:
+              return false;
+          }
+        })) {
+        return param[0];
+      }
+    });
+  } else {
+    return [];
+  }
+}
+
 function fromSuryObject(typeName, schema) {
   if (schema.type !== "object") {
     return;
@@ -176,6 +197,7 @@ export {
   isIdsFieldName,
   fromSury,
   shapeOf,
+  optionalFieldNames,
   fromSuryObject,
 }
 /* DcbTag-Reventless Not a pure module */

package/src/components/Api/SuryToJsonSchema.res

@@ -179,8 +179,18 @@ and withSemantic = (fieldSchema: JSON.t, sem: Reventless.Semantic.t): JSON.t =>
     JSON.Encode.object(obj)
   }
 
+// `optional` names the fields that may be absent; everything else is required.
+// It comes from the sury schema (`SchemaType.optionalFieldNames`) rather than
+// from the IR, which cannot answer for a reference or a DCB-tagged field — both
+// classify as `EntityId` before the nullable wrapper is ever examined.
+//
+// Defaulting to "all required" mattered nowhere while only read-model state came
+// through here: nothing validates a read schema. A command schema is the input
+// of a form, and a field listed as required is one the form refuses to submit
+// without — which turned `imageUrl?` into a picture every product had to have.
 and objectRefToJsonSchema = (
   ~annotations: option<Reventless.StateAnnotations.stateAnnotationSpec>=?,
+  ~optional: array<string>=[],
   fields: dict<SchemaType.schemaType>,
 ): JSON.t => {
   let props = Dict.make()
@@ -194,7 +204,9 @@ and objectRefToJsonSchema = (
     | None => baseSchema
     }
     props->Dict.set(fieldName, withAnnotations)
-    required->Array.push(fieldName)
+    if !(optional->Array.includes(fieldName)) {
+      required->Array.push(fieldName)
+    }
   })
   let entries: array<(string, JSON.t)> = [
     ("type", str("object")),
@@ -212,7 +224,11 @@ let deriveObjectSchema = (schema: S.t<unknown>): JSON.t =>
   switch SchemaType.fromSuryObject(~typeName="", schema) {
   | Some(fields) =>
     let annotations = Reventless.StateAnnotations.getSpec(schema)
-    let objSchema = objectRefToJsonSchema(~annotations?, fields)
+    let objSchema = objectRefToJsonSchema(
+      ~annotations?,
+      ~optional=SchemaType.optionalFieldNames(schema),
+      fields,
+    )
     // Surface component-level visibility on the top-level object schema.
     // Omitted entirely for the default `Public` (None) so schemas stay compact.
     switch annotations {

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

@@ -177,7 +177,7 @@ function fromSchemaType(st) {
           ]
         ]);
       case "ObjectRef" :
-        return objectRefToJsonSchema(undefined, st._1);
+        return objectRefToJsonSchema(undefined, undefined, st._1);
       case "Enum" :
         return Object.fromEntries([
           [
@@ -221,7 +221,8 @@ function withSemantic(fieldSchema, sem) {
   return obj;
 }
 
-function objectRefToJsonSchema(annotations, fields) {
+function objectRefToJsonSchema(annotations, optionalOpt, fields) {
+  let optional = optionalOpt !== undefined ? optionalOpt : [];
   let props = {};
   let required = [];
   Object.entries(fields).forEach(param => {
@@ -229,7 +230,10 @@ function objectRefToJsonSchema(annotations, fields) {
     let baseSchema = fromSchemaType(param[1]);
     let withAnnotations = annotations !== undefined ? mergeAnnotations(baseSchema, fieldName, annotations) : baseSchema;
     props[fieldName] = withAnnotations;
-    required.push(fieldName);
+    if (!optional.includes(fieldName)) {
+      required.push(fieldName);
+      return;
+    }
   });
   let entries = [
     [
@@ -259,7 +263,7 @@ function deriveObjectSchema(schema) {
       ]]);
   }
   let annotations = StateAnnotations$Reventless.getSpec(schema);
-  let objSchema = objectRefToJsonSchema(annotations, fields);
+  let objSchema = objectRefToJsonSchema(annotations, SchemaType$ReventlessCore.optionalFieldNames(schema), fields);
   if (annotations === undefined) {
     return objSchema;
   }

package/src/plugin/component/Plugin_Structure.res

@@ -269,7 +269,14 @@ let make = (
         }
       ({
         Reventless.Plugin.name: variantName,
-        schema: (v->S.toJSONSchema->Obj.magic: JSON.t)->JSON.stringify,
+        // The derived schema, not sury's raw one: `S.toJSONSchema` carries the
+        // shape and drops every `x-reventless-*` marker the PPX put on the
+        // fields, so a command's `@storageRef`/`@semantic`/`@ref` reached the
+        // wire on the read side and nowhere on the write side. A reader that
+        // 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,
         level,
         aggregateIdField,
         // A non-exposed (`@noApi`) variant has no callable mutation field. For a
@@ -343,7 +350,9 @@ let make = (
         )
       ({
         Reventless.Plugin.name: variantName,
-        schema: (v->S.toJSONSchema->Obj.magic: JSON.t)->JSON.stringify,
+        // Derived for the same reason as `commandDef.schema` above: an event's
+        // field markers are the write side's half of the same vocabulary.
+        schema: v->SuryToJsonSchema.deriveObjectSchema->JSON.stringify,
         references,
       }: Reventless.Plugin.eventDef)
     }

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

@@ -1,6 +1,5 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as S from "sury/src/S.res.mjs";
 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";
@@ -229,7 +228,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       }
       return {
         name: variantName,
-        schema: JSON.stringify(S.toJSONSchema(v)),
+        schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(v)),
         level: match[0],
         aggregateIdField: match[1],
         mutationField: apiExposed ? mutationFieldFor(variantName) : "",
@@ -281,7 +280,7 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
       });
       return {
         name: variantName,
-        schema: JSON.stringify(S.toJSONSchema(v)),
+        schema: JSON.stringify(SuryToJsonSchema$ReventlessCore.deriveObjectSchema(v)),
         references: references
       };
     };

package/tests/plugin/PluginStructureTest.res

@@ -549,26 +549,28 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
     })
   })
 
-  // Phase 4: queryableDef.schema must carry x-reventless-* extension keys for
-  // annotated state types. Plugin_Structure now uses SuryToJsonSchema.deriveObjectSchema
-  // (annotation-aware) instead of S.toJSONSchema (metadata-blind).
-  describe("queryableDef.schema propagates x-reventless-* annotations", () => {
-    let getProperty = (json: JSON.t, key: string): option<JSON.t> =>
-      switch json->JSON.Decode.object {
-      | Some(obj) => obj->Dict.get(key)
-      | None => None
-      }
+  // Shared by the read-side and write-side schema cases below, which ask the
+  // same question of the same emitter.
+  let getProperty = (json: JSON.t, key: string): option<JSON.t> =>
+    switch json->JSON.Decode.object {
+    | Some(obj) => obj->Dict.get(key)
+    | None => None
+    }
 
-    let getPropertyOf = (json: JSON.t, fieldName: string): option<JSON.t> =>
-      switch getProperty(json, "properties") {
-      | Some(props) =>
-        switch props->JSON.Decode.object {
-        | Some(obj) => obj->Dict.get(fieldName)
-        | None => None
-        }
+  let getPropertyOf = (json: JSON.t, fieldName: string): option<JSON.t> =>
+    switch getProperty(json, "properties") {
+    | Some(props) =>
+      switch props->JSON.Decode.object {
+      | Some(obj) => obj->Dict.get(fieldName)
       | None => None
       }
+    | None => None
+    }
 
+  // Phase 4: queryableDef.schema must carry x-reventless-* extension keys for
+  // annotated state types. Plugin_Structure now uses SuryToJsonSchema.deriveObjectSchema
+  // (annotation-aware) instead of S.toJSONSchema (metadata-blind).
+  describe("queryableDef.schema propagates x-reventless-* annotations", () => {
     let parseSchema = (svs: Reventless.Plugin.queryableDef): JSON.t =>
       svs.schema->JSON.parseOrThrow
 
@@ -826,6 +828,37 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       ]
       expect(cmd.references)->toEqual(expected)
     })
+
+    // What `requiredStores` knows, the wire has to carry. A reader deciding
+    // which command fills a storage-ref field, or which store's endpoint an
+    // upload goes to, has only the command schema to go on.
+    testSync("the command schema carries the field's storage-ref marker", () => {
+      let cmd = (withOptional.stateChangeSlices->Array.getUnsafe(0)).commands->Array.getUnsafe(0)
+      let target =
+        cmd.schema
+        ->JSON.parseOrThrow
+        ->getPropertyOf("avatarUrl")
+        ->Option.flatMap(s => getProperty(s, "x-reventless-semantic-target"))
+        ->Option.flatMap(t => getProperty(t, "store"))
+        ->Option.flatMap(JSON.Decode.string)
+      expect(target)->toBe(Some("avatars"))
+    })
+
+    // A form submits what a schema says is required. `avatarUrl?` is optional in
+    // the spec, so listing it would make the picture mandatory in every UI that
+    // renders the command — the failure this pairs with, since carrying the
+    // marker is worth nothing if the field cannot be left empty.
+    testSync("an optional command argument is not required", () => {
+      let cmd = (withOptional.stateChangeSlices->Array.getUnsafe(0)).commands->Array.getUnsafe(0)
+      let required =
+        cmd.schema
+        ->JSON.parseOrThrow
+        ->getProperty("required")
+        ->Option.flatMap(JSON.Decode.array)
+        ->Option.getOr([])
+        ->Array.filterMap(JSON.Decode.string)
+      expect(required)->toEqual(["customerId"])
+    })
   })
 
   // Declarations are authoritative; the name heuristics are a lint. A

package/tests/plugin/PluginStructureTest.res.mjs

@@ -2,6 +2,7 @@
 
 import * as S from "sury/src/S.res.mjs";
 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 Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
@@ -676,23 +677,23 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       globalThis.expect(Plugin_Structure$ReventlessCore.statusFieldFromStateSchema("Test", schema)).toEqual(undefined);
     });
   });
+  let getProperty = (json, key) => {
+    let obj = Stdlib_JSON.Decode.object(json);
+    if (obj !== undefined) {
+      return obj[key];
+    }
+  };
+  let getPropertyOf = (json, fieldName) => {
+    let props = getProperty(json, "properties");
+    if (props === undefined) {
+      return;
+    }
+    let obj = Stdlib_JSON.Decode.object(props);
+    if (obj !== undefined) {
+      return obj[fieldName];
+    }
+  };
   globalThis.describe("queryableDef.schema propagates x-reventless-* annotations", () => {
-    let getProperty = (json, key) => {
-      let obj = Stdlib_JSON.Decode.object(json);
-      if (obj !== undefined) {
-        return obj[key];
-      }
-    };
-    let getPropertyOf = (json, fieldName) => {
-      let props = getProperty(json, "properties");
-      if (props === undefined) {
-        return;
-      }
-      let obj = Stdlib_JSON.Decode.object(props);
-      if (obj !== undefined) {
-        return obj[fieldName];
-      }
-    };
     let annotatedSchema = JSON.parse(structure.stateViewSlices[3].schema);
     globalThis.test("itemId carries x-reventless-id", () => {
       globalThis.expect(Stdlib_Option.flatMap(Stdlib_Option.flatMap(getPropertyOf(annotatedSchema, "itemId"), s => getProperty(s, "x-reventless-id")), Stdlib_JSON.Decode.bool)).toBe(true);
@@ -872,6 +873,16 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
         }];
       globalThis.expect(cmd.references).toEqual(expected);
     });
+    globalThis.test("the command schema carries the field's storage-ref marker", () => {
+      let cmd = withOptional.stateChangeSlices[0].commands[0];
+      let target = Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_Option.flatMap(getPropertyOf(JSON.parse(cmd.schema), "avatarUrl"), s => getProperty(s, "x-reventless-semantic-target")), t => getProperty(t, "store")), Stdlib_JSON.Decode.string);
+      globalThis.expect(target).toBe("avatars");
+    });
+    globalThis.test("an optional command argument is not required", () => {
+      let cmd = withOptional.stateChangeSlices[0].commands[0];
+      let required = Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(getProperty(JSON.parse(cmd.schema), "required"), Stdlib_JSON.Decode.array), []), Stdlib_JSON.Decode.string);
+      globalThis.expect(required).toEqual(["customerId"]);
+    });
   });
   globalThis.describe("capability inference", () => {
     let commandWarnings = Capability_Inference$ReventlessCore.scanSchema("ChangePhoto", PsChangePhoto$ReventlessCore.commandSchema);