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

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.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
+
+* **spec,core:** record the storageRef annotation instead of inferring it ([06fb5d6](https://github.com/ReventlessDev/reventless-core/commit/06fb5d671db91fb536acefd0c2db69d98671da39))
+* **spec:** read a semantic marker through an optional field's wrapper ([abebaa9](https://github.com/ReventlessDev/reventless-core/commit/abebaa9e6c73986765bb3de589ba0414eb0d85da))
+
+
 # 3.0.0-alpha.193 (2026-07-30)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.193",
+  "version": "3.0.0-alpha.195",
   "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-hash-object": "1.2.0-alpha.13",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.31",
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.13",
     "@reventlessdev/rescript-fast-csv": "1.2.0-alpha.14",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
     "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.17",
     "@reventlessdev/rescript-ssh2": "1.1.0-alpha.14",
     "@reventlessdev/rescript-uuid": "1.1.0-alpha.17",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.111",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.86",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.29"
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.17",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.29",
+    "@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)
     }
@@ -498,6 +507,14 @@ let make = (
         Reventless.Plugin.store: target.plugin->Option.getOr(name) ++ "." ++ target.store,
         component,
         field,
+        // The annotation as its author wrote it. `target.plugin` is `None`
+        // exactly when the field left the store unqualified, so this is the
+        // source text rather than a guess at it — and this is the only place
+        // that distinction survives.
+        annotation: switch target.plugin {
+        | None => target.store
+        | Some(plugin) => plugin ++ "." ++ target.store
+        },
       })
     )
 

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
       };
     };
@@ -447,11 +446,15 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
         let properties = v.properties;
         return Stdlib_Array.filterMap(Object.entries(properties), param => {
           let field = param[0];
-          return Stdlib_Option.map(StorageRef$Reventless.getStore(param[1]), target => ({
-            store: Stdlib_Option.getOr(target.plugin, name) + "." + target.store,
-            component: component,
-            field: field
-          }));
+          return Stdlib_Option.map(StorageRef$Reventless.getStore(param[1]), target => {
+            let plugin = target.plugin;
+            return {
+              store: Stdlib_Option.getOr(target.plugin, name) + "." + target.store,
+              component: component,
+              field: field,
+              annotation: plugin !== undefined ? plugin + "." + target.store : target.store
+            };
+          });
         });
       } else {
         return [];

package/tests/api/SuryToJsonSchemaTest.res

@@ -606,6 +606,22 @@ describe("SuryToJsonSchema:", () => {
       )->toEqual(Some(JSON.Encode.string("string")))
     })
 
+    // An optional field's marker sits inside the wrapper sury-ppx builds around
+    // it, so this used to emit a plain nullable string: the field was a storage
+    // ref in the source and an untyped string on the wire. The semantic now
+    // survives, and it rides *beside* the nullable shape rather than replacing
+    // it — a reader still learns the value may be absent.
+    testSync("an optional storage-ref field keeps both its semantic and its nullability", () => {
+      let schema = S.schema(s =>
+        {"imageUrl": s.matches(S.option(Reventless.StorageRef.forStore(~store="productImages")))}
+      )->S.castToUnknown
+      let json = SuryToJsonSchema.deriveObjectSchema(schema)
+      expect(semanticOf(json, "imageUrl"))->toEqual(Some(JSON.Encode.string("storageRef")))
+      expect(
+        getPropertyOf(json, "imageUrl")->Option.flatMap(s => getProperty(s, "oneOf"))->Option.isSome,
+      )->toBe(true)
+    })
+
     testSync("a type-carried semantic beats an annotation naming the same field", () => {
       let withSpec = (schema, spec) =>
         schema->S.Metadata.set(~id=Reventless.StateAnnotations.stateAnnotationsId, spec)

package/tests/api/SuryToJsonSchemaTest.res.mjs

@@ -909,6 +909,14 @@ globalThis.describe("SuryToJsonSchema:", () => {
       let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
       globalThis.expect(Stdlib_Option.flatMap(getPropertyOf(json, "imageUrl"), s => getProperty(s, "type"))).toEqual("string");
     });
+    globalThis.test("an optional storage-ref field keeps both its semantic and its nullability", () => {
+      let schema = S.schema(s => ({
+        imageUrl: s.m(S.option(StorageRef$Reventless.forStore(undefined, "productImages")))
+      }));
+      let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(schema);
+      globalThis.expect(semanticOf(json, "imageUrl")).toEqual("storageRef");
+      globalThis.expect(Stdlib_Option.isSome(Stdlib_Option.flatMap(getPropertyOf(json, "imageUrl"), s => getProperty(s, "oneOf")))).toBe(true);
+    });
     globalThis.test("a type-carried semantic beats an annotation naming the same field", () => {
       let withSpec = (schema, spec) => S.Metadata.set(schema, StateAnnotations$Reventless.stateAnnotationsId, spec);
       let schema = withSpec(S.schema(s => ({

package/tests/plugin/PluginStructureTest.res

@@ -93,6 +93,20 @@ module PsAttachInvoiceSlice: ReventlessInfra.StateChangeSlice.T = {
   let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
 }
 
+module PsUploadAvatarSlice: ReventlessInfra.StateChangeSlice.T = {
+  module Spec = PsUploadAvatar
+  module Behavior = {
+    type state = PsUploadAvatar.state
+    let initialState = PsUploadAvatar.initialState
+    let evolve = PsUploadAvatar.evolve
+    let decide = PsUploadAvatar.decide
+    let moduleUrl = PsUploadAvatar.moduleUrl
+  }
+  let isAsync = false
+  type component = scsComponent
+  let make = (~dcbEventLog as _, ~publishJsons as _, ~tagKeysByEventType as _=?, ~crossPartitionTagKeys as _=?, ~runtime as _=?, ~opts as _=?): component => Obj.magic(0)
+}
+
 module PsChangePhotoSlice: ReventlessInfra.StateChangeSlice.T = {
   module Spec = PsChangePhoto
   module Behavior = {
@@ -535,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
 
@@ -694,9 +710,22 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       // `documents` is declared on a command field AND an event field of the
       // same component under the same field name — one declaration site, so
       // the identical triples collapse to one entry.
+      // `annotation` is the source text, not the key: the own-plugin store is
+      // written bare and the foreign one qualified, which is exactly the
+      // distinction no downstream comparison can recover.
       let expected: array<Reventless.Plugin.requiredStoreDeclaration> = [
-        {store: "TestPlugin.documents", component: "AttachInvoice", field: "documentUrl"},
-        {store: "branding.logos", component: "AttachInvoice", field: "logoUrl"},
+        {
+          store: "TestPlugin.documents",
+          component: "AttachInvoice",
+          field: "documentUrl",
+          annotation: "documents",
+        },
+        {
+          store: "branding.logos",
+          component: "AttachInvoice",
+          field: "logoUrl",
+          annotation: "branding.logos",
+        },
       ]
       expect(withStores.requiredStoreDeclarations)->toEqual(Some(expected))
     })
@@ -718,7 +747,7 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
         let entry =
           manifest.capabilities->Array.find(c => c.key == "TestPlugin.documents")->Option.getOrThrow
         let expected: array<Reventless.CapabilityManifest.provenance> = [
-          {component: "AttachInvoice", field: "documentUrl"},
+          {component: "AttachInvoice", field: "documentUrl", annotation: "documents"},
         ]
         expect(entry.declaredBy)->toEqual(expected)
       })
@@ -738,7 +767,8 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       "declaredBy": [
         {
           "component": "AttachInvoice",
-          "field": "documentUrl"
+          "field": "documentUrl",
+          "annotation": "documents"
         }
       ]
     },
@@ -748,7 +778,8 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       "declaredBy": [
         {
           "component": "AttachInvoice",
-          "field": "logoUrl"
+          "field": "logoUrl",
+          "annotation": "branding.logos"
         }
       ]
     }
@@ -760,6 +791,76 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
     })
   })
 
+  // Making a field optional says the value may be absent. It does not say the
+  // field stopped being a storage ref or a reference — but both walks read the
+  // marker through `Semantic.get`, and an optional field's marker sits on the
+  // schema inside the wrapper sury-ppx builds. Until that unwrap existed, adding
+  // a `?` to a field silently un-declared its store: nothing failed, an S3
+  // bucket just stopped being provisioned.
+  describe("optional carriers keep their declarations", () => {
+    let withOptional = Plugin_Structure.make(
+      ~name="TestPlugin",
+      ~stateChangeSlices=[module(PsUploadAvatarSlice)],
+    )
+
+    testSync("an optional storage ref still requires its store", () =>
+      expect(withOptional.requiredStores)->toEqual(Some(["TestPlugin.avatars"]))
+    )
+
+    // Declared on the command and on the event under one field name — the same
+    // collapse the required case makes, so optionality does not change arity.
+    testSync("and still carries one declaring site", () => {
+      let expected: array<Reventless.Plugin.requiredStoreDeclaration> = [
+        {
+          store: "TestPlugin.avatars",
+          component: "UploadAvatar",
+          field: "avatarUrl",
+          annotation: "avatars",
+        },
+      ]
+      expect(withOptional.requiredStoreDeclarations)->toEqual(Some(expected))
+    })
+
+    testSync("an optional reference is still collected", () => {
+      let cmd = (withOptional.stateChangeSlices->Array.getUnsafe(0)).commands->Array.getUnsafe(0)
+      let expected: array<Reventless.Plugin.fieldReference> = [
+        {fieldName: "referredBy", entity: "Customers", plugin: None},
+      ]
+      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
   // heuristic-only match warns and never reaches the manifest, so nothing is
   // provisioned from a guess — `imageUrl` is genuinely ambiguous between an

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";
@@ -13,6 +14,7 @@ import * as PsOrdersView$ReventlessCore from "./StateViewSlice/PsOrdersView.res.
 import * as PsPlaceOrder$ReventlessCore from "./StateChangeSlice/PsPlaceOrder.res.mjs";
 import * as PsChangePhoto$ReventlessCore from "./StateChangeSlice/PsChangePhoto.res.mjs";
 import * as CapabilityManifest$Reventless from "@reventlessdev/reventless-spec/src/components/CapabilityManifest.res.mjs";
+import * as PsUploadAvatar$ReventlessCore from "./StateChangeSlice/PsUploadAvatar.res.mjs";
 import * as PsAnnotatedView$ReventlessCore from "./StateViewSlice/PsAnnotatedView.res.mjs";
 import * as PsAttachInvoice$ReventlessCore from "./StateChangeSlice/PsAttachInvoice.res.mjs";
 import * as PsCustomersView$ReventlessCore from "./StateViewSlice/PsCustomersView.res.mjs";
@@ -215,13 +217,43 @@ let PsAttachInvoiceSlice = {
 };
 
 let Behavior$3 = {
+  initialState: false,
+  evolve: PsUploadAvatar$ReventlessCore.evolve,
+  decide: PsUploadAvatar$ReventlessCore.decide,
+  moduleUrl: PsUploadAvatar$ReventlessCore.moduleUrl
+};
+
+function make$7(param, param$1, param$2, param$3, param$4, param$5) {
+  return 0;
+}
+
+let PsUploadAvatarSlice_Spec = {
+  name: PsUploadAvatar$ReventlessCore.name,
+  moduleUrl: PsUploadAvatar$ReventlessCore.moduleUrl,
+  Id: Id$Reventless.$$String,
+  consumedEventSchema: PsUploadAvatar$ReventlessCore.consumedEventSchema,
+  errorSchema: PsUploadAvatar$ReventlessCore.errorSchema,
+  eventSchema: PsUploadAvatar$ReventlessCore.eventSchema,
+  commandSchema: PsUploadAvatar$ReventlessCore.commandSchema,
+  commandAuthorization: PsUploadAvatar$ReventlessCore.commandAuthorization,
+  readConsistency: PsUploadAvatar$ReventlessCore.readConsistency
+};
+
+let PsUploadAvatarSlice = {
+  Spec: PsUploadAvatarSlice_Spec,
+  Behavior: Behavior$3,
+  isAsync: false,
+  make: make$7
+};
+
+let Behavior$4 = {
   initialState: false,
   evolve: PsChangePhoto$ReventlessCore.evolve,
   decide: PsChangePhoto$ReventlessCore.decide,
   moduleUrl: PsChangePhoto$ReventlessCore.moduleUrl
 };
 
-function make$7(param, param$1, param$2, param$3, param$4, param$5) {
+function make$8(param, param$1, param$2, param$3, param$4, param$5) {
   return 0;
 }
 
@@ -239,9 +271,9 @@ let PsChangePhotoSlice_Spec = {
 
 let PsChangePhotoSlice = {
   Spec: PsChangePhotoSlice_Spec,
-  Behavior: Behavior$3,
+  Behavior: Behavior$4,
   isAsync: false,
-  make: make$7
+  make: make$8
 };
 
 let structure = Plugin_Structure$ReventlessCore.make("TestPlugin", undefined, undefined, [
@@ -645,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);
@@ -757,12 +789,14 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
         {
           store: "TestPlugin.documents",
           component: "AttachInvoice",
-          field: "documentUrl"
+          field: "documentUrl",
+          annotation: "documents"
         },
         {
           store: "branding.logos",
           component: "AttachInvoice",
-          field: "logoUrl"
+          field: "logoUrl",
+          annotation: "branding.logos"
         }
       ];
       globalThis.expect(withStores.requiredStoreDeclarations).toEqual(expected);
@@ -776,7 +810,8 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
         let entry = Stdlib_Option.getOrThrow(manifest.capabilities.find(c => c.key === "TestPlugin.documents"), undefined);
         let expected = [{
             component: "AttachInvoice",
-            field: "documentUrl"
+            field: "documentUrl",
+            annotation: "documents"
           }];
         globalThis.expect(entry.declaredBy).toEqual(expected);
       });
@@ -793,7 +828,8 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       "declaredBy": [
         {
           "component": "AttachInvoice",
-          "field": "documentUrl"
+          "field": "documentUrl",
+          "annotation": "documents"
         }
       ]
     },
@@ -803,7 +839,8 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       "declaredBy": [
         {
           "component": "AttachInvoice",
-          "field": "logoUrl"
+          "field": "logoUrl",
+          "annotation": "branding.logos"
         }
       ]
     }
@@ -813,6 +850,40 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       });
     });
   });
+  globalThis.describe("optional carriers keep their declarations", () => {
+    let withOptional = Plugin_Structure$ReventlessCore.make("TestPlugin", undefined, undefined, undefined, [PsUploadAvatarSlice], undefined, undefined, undefined, undefined, undefined, undefined);
+    globalThis.test("an optional storage ref still requires its store", () => {
+      globalThis.expect(withOptional.requiredStores).toEqual(["TestPlugin.avatars"]);
+    });
+    globalThis.test("and still carries one declaring site", () => {
+      let expected = [{
+          store: "TestPlugin.avatars",
+          component: "UploadAvatar",
+          field: "avatarUrl",
+          annotation: "avatars"
+        }];
+      globalThis.expect(withOptional.requiredStoreDeclarations).toEqual(expected);
+    });
+    globalThis.test("an optional reference is still collected", () => {
+      let cmd = withOptional.stateChangeSlices[0].commands[0];
+      let expected = [{
+          fieldName: "referredBy",
+          entity: "Customers",
+          plugin: undefined
+        }];
+      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);
     let eventWarnings = Capability_Inference$ReventlessCore.scanSchema("ChangePhoto", PsChangePhoto$ReventlessCore.eventSchema);
@@ -867,6 +938,7 @@ export {
   PsCustomersViewSlice,
   PsAnnotatedViewSlice,
   PsAttachInvoiceSlice,
+  PsUploadAvatarSlice,
   PsChangePhotoSlice,
   structure,
 }

package/tests/plugin/StateChangeSlice/PsUploadAvatar.res

@@ -0,0 +1,37 @@
+// Test fixture spec where every semantic carrier is OPTIONAL.
+//
+// The marker of an optional field sits on the schema *inside* the
+// undefined-union sury-ppx wraps it in, so a walk that reads only the outer
+// schema finds nothing. That failure is silent in the worst way: the plugin
+// compiles, deploys green, and provisions no object store — so `avatarUrl` is
+// the only declarer of `avatars` here on purpose. If the unwrap regresses, the
+// store requirement disappears entirely rather than merely losing a site.
+//
+// `referredBy` is the same trap for `@ref`: an optional reference that goes
+// uncollected drops out of `commandDef.references`.
+
+@@reventless.spec("UploadAvatar")
+
+type state = bool
+let initialState = false
+
+@schema
+type consumedEvent = OrderPlaced
+
+let evolve = (_state, _event) => true
+
+@schema
+type command =
+  | UploadAvatar({
+      customerId: string,
+      @storageRef("avatars") avatarUrl?: string,
+      @ref("Customers") referredBy?: string,
+    })
+
+@schema
+type error = CustomerNotFound
+
+@schema
+type event = AvatarUploaded({customerId: string, @storageRef("avatars") avatarUrl?: string})
+
+let decide = (_state, _command): result<array<event>, error> => Ok([])

package/tests/plugin/StateChangeSlice/PsUploadAvatar.res.mjs

@@ -0,0 +1,64 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
+import * as Reference$Reventless from "@reventlessdev/reventless-spec/src/components/Reference.res.mjs";
+import * as StorageRef$Reventless from "@reventlessdev/reventless-spec/src/semantic/StorageRef.res.mjs";
+
+let consumedEventSchema = S.literal("OrderPlaced");
+
+function evolve(_state, _event) {
+  return true;
+}
+
+let commandSchema = S.schema(s => ({
+  TAG: "UploadAvatar",
+  customerId: s.m(DcbTag$Reventless.string),
+  avatarUrl: s.m(S.option(StorageRef$Reventless.forStore(undefined, "avatars"))),
+  referredBy: s.m(S.option(Reference$Reventless.to_(undefined, undefined, "Customers")))
+}));
+
+let errorSchema = S.literal("CustomerNotFound");
+
+let eventSchema = S.schema(s => ({
+  TAG: "AvatarUploaded",
+  customerId: s.m(DcbTag$Reventless.string),
+  avatarUrl: s.m(S.option(StorageRef$Reventless.forStore(undefined, "avatars")))
+}));
+
+function decide(_state, _command) {
+  return {
+    TAG: "Ok",
+    _0: []
+  };
+}
+
+function commandAuthorization(param) {
+  return "AllowAuthenticated";
+}
+
+let name = "UploadAvatar";
+
+let Id;
+
+let initialState = false;
+
+let moduleUrl = "@reventlessdev/reventless-core/tests/plugin/StateChangeSlice/PsUploadAvatar.res.mjs";
+
+let readConsistency = "EscalateOnRetry";
+
+export {
+  name,
+  Id,
+  initialState,
+  consumedEventSchema,
+  evolve,
+  commandSchema,
+  errorSchema,
+  eventSchema,
+  decide,
+  moduleUrl,
+  commandAuthorization,
+  readConsistency,
+}
+/* consumedEventSchema Not a pure module */