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

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 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.196 (2026-07-31)
+
+* feat(rescript)!: one Node bindings package, not two ([1258d8c](https://github.com/ReventlessDev/reventless-core/commit/1258d8c2b2ff2636b36a849fc5bdf9005c6fb0eb))
+### Features
+
+* **spec:** add Money and a closed ISO 4217 Currency ([d4852ab](https://github.com/ReventlessDev/reventless-core/commit/d4852ab63e823e39fac793c4fa5ac31470db9655))
+
+### BREAKING CHANGES
+
+* `@reventlessdev/rescript-node-streams` and
+`@reventlessdev/rescript-node-zlib` are replaced by
+`@reventlessdev/rescript-node`. Module names are unchanged.
+
+
+
+# 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.196",
   "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.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-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-ssh2": "1.1.0-alpha.14",
-    "@reventlessdev/reventless-interop": "3.0.0-alpha.29",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.87"
+    "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.0",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
+    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.0",
+    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.0",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.114",
+    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.89",
+    "@reventlessdev/reventless-interop": "3.0.0-alpha.30"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/rescript.json

@@ -29,7 +29,7 @@
     "@reventlessdev/rescript-effect",
     "@reventlessdev/rescript-fast-csv",
     "@reventlessdev/rescript-hash-object",
-    "@reventlessdev/rescript-node-streams",
+    "@reventlessdev/rescript-node",
     "@reventlessdev/rescript-pulumi-pulumi",
     "@reventlessdev/rescript-ssh2",
     "@reventlessdev/rescript-uuid",

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_Helpers.res

@@ -1165,16 +1165,14 @@ let getInteropMeta = (): Pulumi.Output.t<JSON.t> => {
 // Stack metadata export — environment, region, timestamp, actor, git SHA.
 // Called from both exportPluginOutputs and exportPlatformOutputs.
 // ---------------------------------------------------------------------------
-@val external processEnv: dict<string> = "process.env"
-
 let exportDeploymentMetadata = () => {
   let metadata =
     [
       ("environment", Pulumi.Pulumi.getStackName()),
       ("region", Pulumi.Config.make(Some("aws"))->Pulumi.Config.get("region")->Option.getOr("unknown")),
       ("timestamp", Date.make()->Date.toISOString),
-      ("gitSha", processEnv->Dict.get("GITHUB_SHA")->Option.getOr("unknown")),
-      ("actor", processEnv->Dict.get("GITHUB_ACTOR")->Option.getOr("unknown")),
+      ("gitSha", NodeProcess.env->Dict.get("GITHUB_SHA")->Option.getOr("unknown")),
+      ("actor", NodeProcess.env->Dict.get("GITHUB_ACTOR")->Option.getOr("unknown")),
     ]
     ->Dict.fromArray
   Pulumi.Pulumi.export(
@@ -1516,15 +1514,15 @@ let exportPluginOutputs = (pluginOutputs: Plugin.outputs) => {
   | Some(hook) =>
     // Read deployment provenance from env vars synchronously (before Output.apply).
     let actor =
-      processEnv
+      NodeProcess.env
       ->Dict.get("GITHUB_ACTOR")
-      ->Option.orElse(processEnv->Dict.get("CI_COMMIT_AUTHOR"))
-      ->Option.orElse(processEnv->Dict.get("USER"))
+      ->Option.orElse(NodeProcess.env->Dict.get("CI_COMMIT_AUTHOR"))
+      ->Option.orElse(NodeProcess.env->Dict.get("USER"))
       ->Option.getOr("local")
     let deploymentId =
-      processEnv
+      NodeProcess.env
       ->Dict.get("GITHUB_SHA")
-      ->Option.orElse(processEnv->Dict.get("CI_COMMIT_SHA"))
+      ->Option.orElse(NodeProcess.env->Dict.get("CI_COMMIT_SHA"))
       ->Option.getOr(Date.make()->Date.toISOString)
     let schemaFor = name =>
       componentSchemaRegistry->Dict.get(name)->Option.getOr({})

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/src/util/FTPHandler.res.mjs

@@ -2,7 +2,7 @@
 
 import * as SSH2 from "@reventlessdev/rescript-ssh2/src/SSH2.res.mjs";
 import * as Ssh2 from "ssh2";
-import * as Stream from "stream";
+import * as Nodestream from "node:stream";
 import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect from "effect/Effect";
@@ -122,7 +122,7 @@ function ftp(connectionParams, ftpAction) {
             let err$1 = new Error("FTPHandler: Error in Write Stream");
             sftp.emit("error", err$1);
           });
-          return await Stream.promises.pipeline(ftpAction._0, ws);
+          return await Nodestream.promises.pipeline(ftpAction._0, ws);
         }
       }
     }, () => {});

package/tests/api/SuryToJsonSchemaTest.res

@@ -677,4 +677,69 @@ describe("SuryToJsonSchema:", () => {
       ))->toEqual((Some(JSON.Encode.string("type")), Some(JSON.Encode.string("type"))))
     )
   })
+
+  // The other half of that claim, stated so it cannot be confused with it.
+  // `Money` is the first semantic type that is *not* a brand: it turns a number
+  // into an object, so the wire shape changes and stored events written against
+  // the old field do not decode. The assertions below are the evidence for that
+  // — a schema diff before and after a retype is exactly this, and it is what
+  // says a deployment needs an upcaster before it can take the change.
+  describe("Money changes the field's shape, and says so:", () => {
+    let json = SuryToJsonSchema.deriveObjectSchema(
+      S.schema(s =>
+        {
+          "price": s.matches(Reventless.Money.schema),
+          "quantity": s.matches(S.float),
+        }
+      )->S.castToUnknown,
+    )
+    let keyOf = (name, key) => getPropertyOf(json, name)->Option.flatMap(s => getProperty(s, key))
+
+    testSync("the field is an object, not a number", () =>
+      expect(keyOf("price", "type"))->toEqual(Some(JSON.Encode.string("object")))
+    )
+
+    testSync("it carries the money id, sourced from the type", () =>
+      expect((keyOf("price", "x-reventless-semantic"), keyOf("price", "x-reventless-semantic-source")))
+      ->toEqual((Some(JSON.Encode.string("money")), Some(JSON.Encode.string("type"))))
+    )
+
+    // The control: an ordinary `float` price is what the field looked like
+    // before, and it emits nothing at all. Without this the assertions above
+    // would pass just as well against a schema that had always said `money`.
+    testSync("a plain numeric field emits no semantic", () =>
+      expect((keyOf("quantity", "type"), keyOf("quantity", "x-reventless-semantic")))->toEqual((
+        Some(JSON.Encode.string("number")),
+        None,
+      ))
+    )
+
+    testSync("the amount and the currency both reach the wire", () => {
+      let inner = getPropertyOf(json, "price")->Option.getOr(JSON.Encode.null)
+      expect((
+        getPropertyOf(inner, "amount")->Option.flatMap(s => getProperty(s, "type")),
+        getPropertyOf(inner, "currency")->Option.flatMap(s => getProperty(s, "type")),
+      ))->toEqual((Some(JSON.Encode.string("number")), Some(JSON.Encode.string("string"))))
+    })
+
+    // The closed currency arrives as an enum rather than a free string, which is
+    // what lets a consumer build a currency picker instead of a text box — and
+    // what makes `"eur"` unrepresentable on the wire as well as in the source.
+    testSync("the currency is an enum of ISO codes", () => {
+      let codes =
+        getPropertyOf(json, "price")
+        ->Option.getOr(JSON.Encode.null)
+        ->getPropertyOf("currency")
+        ->Option.flatMap(s => getProperty(s, "enum"))
+        ->Option.flatMap(JSON.Decode.array)
+        ->Option.getOr([])
+        ->Array.filterMap(JSON.Decode.string)
+      expect((
+        codes->Array.length == Reventless.Currency.all->Array.length,
+        codes->Array.includes("EUR"),
+        codes->Array.includes("JPY"),
+        codes->Array.includes("eur"),
+      ))->toEqual((true, true, true, false))
+    })
+  })
 })

package/tests/api/SuryToJsonSchemaTest.res.mjs

@@ -5,9 +5,11 @@ 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 Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Email$Reventless from "@reventlessdev/reventless-spec/src/semantic/Email.res.mjs";
+import * as Money$Reventless from "@reventlessdev/reventless-spec/src/semantic/Money.res.mjs";
 import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as Percent$Reventless from "@reventlessdev/reventless-spec/src/semantic/Percent.res.mjs";
+import * as Currency$Reventless from "@reventlessdev/reventless-spec/src/semantic/Currency.res.mjs";
 import * as DateTime$Reventless from "@reventlessdev/reventless-spec/src/types/DateTime.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";
@@ -981,6 +983,58 @@ globalThis.describe("SuryToJsonSchema:", () => {
       ]);
     });
   });
+  globalThis.describe("Money changes the field's shape, and says so:", () => {
+    let json = SuryToJsonSchema$ReventlessCore.deriveObjectSchema(S.schema(s => ({
+      price: s.m(Money$Reventless.schema),
+      quantity: s.m(S.float)
+    })));
+    let keyOf = (name, key) => Stdlib_Option.flatMap(getPropertyOf(json, name), s => getProperty(s, key));
+    globalThis.test("the field is an object, not a number", () => {
+      globalThis.expect(keyOf("price", "type")).toEqual("object");
+    });
+    globalThis.test("it carries the money id, sourced from the type", () => {
+      globalThis.expect([
+        keyOf("price", "x-reventless-semantic"),
+        keyOf("price", "x-reventless-semantic-source")
+      ]).toEqual([
+        "money",
+        "type"
+      ]);
+    });
+    globalThis.test("a plain numeric field emits no semantic", () => {
+      globalThis.expect([
+        keyOf("quantity", "type"),
+        keyOf("quantity", "x-reventless-semantic")
+      ]).toEqual([
+        "number",
+        undefined
+      ]);
+    });
+    globalThis.test("the amount and the currency both reach the wire", () => {
+      let inner = Stdlib_Option.getOr(getPropertyOf(json, "price"), null);
+      globalThis.expect([
+        Stdlib_Option.flatMap(getPropertyOf(inner, "amount"), s => getProperty(s, "type")),
+        Stdlib_Option.flatMap(getPropertyOf(inner, "currency"), s => getProperty(s, "type"))
+      ]).toEqual([
+        "number",
+        "string"
+      ]);
+    });
+    globalThis.test("the currency is an enum of ISO codes", () => {
+      let codes = Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(getPropertyOf(Stdlib_Option.getOr(getPropertyOf(json, "price"), null), "currency"), s => getProperty(s, "enum")), Stdlib_JSON.Decode.array), []), Stdlib_JSON.Decode.string);
+      globalThis.expect([
+        codes.length === Currency$Reventless.all.length,
+        codes.includes("EUR"),
+        codes.includes("JPY"),
+        codes.includes("eur")
+      ]).toEqual([
+        true,
+        true,
+        true,
+        false
+      ]);
+    });
+  });
 });
 
 export {

package/tests/logger/LogFormatTest.res

@@ -7,8 +7,7 @@ S.enableJson()
 // included — to JSON, which no-ops `bold`/`fmtComp`. The human-format
 // assertions below expect ANSI, so force text mode for this file. The
 // "JSON sink" block flips to json and restores text in its own setup.
-@val external _processEnv: Dict.t<string> = "process.env"
-_processEnv->Dict.set("REVENTLESS_LOG_FORMAT", "text")
+NodeProcess.env->Dict.set("REVENTLESS_LOG_FORMAT", "text")
 Reventless.AnsiStyle.reload()
 
 describe("LogFormat", () => {
@@ -193,11 +192,11 @@ describe("JSON sink", () => {
   // Flip to json for the whole block; restore text afterwards so a re-run of the
   // file (or shared module state) keeps the human-format assertions valid.
   beforeAll(() => {
-    _processEnv->Dict.set("REVENTLESS_LOG_FORMAT", "json")
+    NodeProcess.env->Dict.set("REVENTLESS_LOG_FORMAT", "json")
     Reventless.AnsiStyle.reload()
   })
   afterAll(() => {
-    _processEnv->Dict.set("REVENTLESS_LOG_FORMAT", "text")
+    NodeProcess.env->Dict.set("REVENTLESS_LOG_FORMAT", "text")
     Reventless.AnsiStyle.reload()
   })
 
@@ -344,10 +343,10 @@ describe("JSON sink", () => {
   })
 
   testSync("service field is emitted when REVENTLESS_SERVICE is set", () => {
-    _processEnv->Dict.set("REVENTLESS_SERVICE", "TestService")
+    NodeProcess.env->Dict.set("REVENTLESS_SERVICE", "TestService")
     let lines = captureLogs(() => log.info(~comp="Platform", "tick"))
     let got = lines->Array.get(0)->Option.flatMap(l => l->fieldOf("service"))
-    _processEnv->Dict.delete("REVENTLESS_SERVICE")
+    NodeProcess.env->Dict.delete("REVENTLESS_SERVICE")
     expect(got)->toEqual(Some("TestService"))
   })
 

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

package/tests/util/CsvStreamTest.res

@@ -4,16 +4,13 @@
 
 open JestGlobals
 
-// Write a UTF-8 string to a file synchronously (no return value).
-@module("fs") external writeFileSync: (string, string) => unit = "writeFileSync"
-
 // Counter for unique temp file names — avoids cross-test collisions.
 let fileCounter = ref(0)
 
 let writeTempCsv = (content: string): string => {
   fileCounter := fileCounter.contents + 1
   let path = `/tmp/reventless-csvstream-test-${Int.toString(fileCounter.contents)}.csv`
-  writeFileSync(path, content)
+  NodeFs.writeFileSync(path, content)
   path
 }
 

package/tests/util/CsvStreamTest.res.mjs

@@ -1,7 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
-import * as Fs from "fs";
 import * as Stream from "@reventlessdev/rescript-effect/src/Stream.res.mjs";
+import * as Nodefs from "node:fs";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect from "effect/Effect";
@@ -15,7 +15,7 @@ let fileCounter = {
 function writeTempCsv(content) {
   fileCounter.contents = fileCounter.contents + 1 | 0;
   let path = `/tmp/reventless-csvstream-test-` + fileCounter.contents.toString() + `.csv`;
-  Fs.writeFileSync(path, content);
+  Nodefs.writeFileSync(path, content, "utf8");
   return path;
 }