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

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.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.194",
   "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-fast-csv": "1.2.0-alpha.14",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.13",
     "@reventlessdev/rescript-node-streams": "1.1.0-alpha.13",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.9",
     "@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/reventless-infra": "3.0.0-alpha.112",
+    "@reventlessdev/rescript-ssh2": "1.1.0-alpha.14",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.29",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.87"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/plugin/component/Plugin_Structure.res

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

@@ -447,11 +447,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 = {
@@ -694,9 +708,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 +745,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 +765,8 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       "declaredBy": [
         {
           "component": "AttachInvoice",
-          "field": "documentUrl"
+          "field": "documentUrl",
+          "annotation": "documents"
         }
       ]
     },
@@ -748,7 +776,8 @@ describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       "declaredBy": [
         {
           "component": "AttachInvoice",
-          "field": "logoUrl"
+          "field": "logoUrl",
+          "annotation": "branding.logos"
         }
       ]
     }
@@ -760,6 +789,45 @@ 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)
+    })
+  })
+
   // 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

@@ -13,6 +13,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 +216,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 +270,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, [
@@ -757,12 +788,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 +809,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 +827,8 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       "declaredBy": [
         {
           "component": "AttachInvoice",
-          "field": "documentUrl"
+          "field": "documentUrl",
+          "annotation": "documents"
         }
       ]
     },
@@ -803,7 +838,8 @@ globalThis.describe("Plugin_Structure.make — Phase 2 graph fields", () => {
       "declaredBy": [
         {
           "component": "AttachInvoice",
-          "field": "logoUrl"
+          "field": "logoUrl",
+          "annotation": "branding.logos"
         }
       ]
     }
@@ -813,6 +849,30 @@ 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.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 +927,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 */