@reventlessdev/reventless-spec 3.0.0-alpha.86 → 3.0.0-alpha.88

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.88 (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.87 (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.86 (2026-07-30)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.86",
+  "version": "3.0.0-alpha.88",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/components/CapabilityManifest.res

@@ -17,9 +17,14 @@ emits the platform's capability list from them.
 type kind = ObjectStore
 
 /** The declaration site: the component's spec name and the field carrying the
-    `@storageRef` annotation. */
+    `@storageRef` annotation, plus the store exactly as that field spells it.
+
+    `annotation` is optional only to keep reading a manifest emitted before it
+    existed: a plugin built earlier still parses, and a reader that cannot say
+    what the source says omits the claim rather than inventing one. Every
+    manifest emitted now carries it. */
 @schema
-type provenance = {component: string, field: string}
+type provenance = {component: string, field: string, annotation?: string}
 
 @schema
 type entry = {
@@ -50,7 +55,9 @@ let fromStructure = (structure: Plugin.pluginStructure): t => {
       kind: ObjectStore,
       key,
       declaredBy: declarations->Array.filterMap(d =>
-        d.store == key ? Some({component: d.component, field: d.field}) : None
+        d.store == key
+          ? Some({component: d.component, field: d.field, annotation: d.annotation})
+          : None
       ),
     }),
   }

package/src/components/CapabilityManifest.res.mjs

@@ -8,7 +8,8 @@ let kindSchema = S.literal("ObjectStore");
 
 let provenanceSchema = S.schema(s => ({
   component: s.m(S.string),
-  field: s.m(S.string)
+  field: s.m(S.string),
+  annotation: s.m(S.option(S.string))
 }));
 
 let entrySchema = S.schema(s => ({
@@ -31,7 +32,8 @@ function fromStructure(structure) {
         if (d.store === key) {
           return {
             component: d.component,
-            field: d.field
+            field: d.field,
+            annotation: d.annotation
           };
         }
       })

package/src/components/Plugin.res

@@ -275,8 +275,10 @@ type queryableDef = {
 One emitted event of a write side, with its field schema. Mirrors `commandDef`
 but for the past-tense facts a write side produces: `name` is the event variant
 name (e.g. `OrderPlaced`), `schema` is the JSON Schema of that variant's payload
-(same `S.toJSONSchema` serialization as `commandDef.schema`, incl. `x-reventless-*`
-extensions and the `TAG` const), `references` its cross-entity field links.
+(same serialization as `commandDef.schema`: `SuryToJsonSchema.deriveObjectSchema`,
+so field-level `x-reventless-*` extensions are carried and the variant's `TAG`
+discriminator is not — the constructor name is already `name`), `references` its
+cross-entity field links.
 Carried so developer tools (the `reventless-dev` / VSCode domain graph) can show
 event field rows — AutoUI ignores it. */
 @schema
@@ -386,12 +388,20 @@ One field's store requirement, with its provenance.
 carries; `component` and `field` name the declaration site. The site matters
 because a requirement only ever changes by editing a field — when a rename
 removes a store from the manifest, the diff has to say which field caused it.
+
+`annotation` is the store exactly as the field spells it — bare for a store
+the declaring plugin owns, qualified for a foreign one. It is recorded rather
+than reconstructed: only here is the owning plugin unambiguous, so anything
+downstream would have to infer it by comparing a registered plugin name with
+whatever name a deploy manifest happened to use, and those were never required
+to match.
 */
 @schema
 type requiredStoreDeclaration = {
   store: string,
   component: string,
   field: string,
+  annotation: string,
 }
 
 let requiredStoreDeclarationArrayOptionSchema = _jsNullable(

package/src/components/Plugin.res.mjs

@@ -181,7 +181,8 @@ let extensionPointDefArrayOptionSchema = SuryResMjs.js_nullable(S.array(extensio
 let requiredStoreDeclarationSchema = S.schema(s => ({
   store: s.m(S.string),
   component: s.m(S.string),
-  field: s.m(S.string)
+  field: s.m(S.string),
+  annotation: s.m(S.string)
 }));
 
 let requiredStoreDeclarationArrayOptionSchema = SuryResMjs.js_nullable(S.array(requiredStoreDeclarationSchema));

package/src/generator/PlatformCodegen.res

@@ -22,6 +22,7 @@ type provenance = {
   pluginName: string,
   component: string,
   field: string,
+  annotation: option<string>,
 }
 
 /** One capability the platform must provision: the qualified `{plugin}.{store}`
@@ -45,6 +46,7 @@ let union = (manifests: array<pluginManifest>): array<unionEntry> => {
           pluginName,
           component: site.component,
           field: site.field,
+          annotation: site.annotation,
         })
       switch byKey->Dict.get(entry.key) {
       | Some(existing) =>
@@ -71,17 +73,17 @@ let splitKey = (key: string): option<(string, string)> =>
     key->String.slice(~start=i + 1),
   ))
 
-// The provenance comment quotes the annotation as its author wrote it: a store
-// declared by its own plugin is unqualified, a foreign store keeps the
-// qualified form. The manifest carries only the deploy-manifest plugin name
-// (lowercase by convention) while the key carries the registered name, so the
-// comparison is case-insensitive — and it only shapes a comment.
-let annotationStore = (~pluginName, ~key): string =>
-  switch splitKey(key) {
-  | Some((keyPlugin, store)) if keyPlugin->String.toLowerCase == pluginName->String.toLowerCase => store
-  | _ => key
-  }
-
+// The provenance comment quotes the annotation as its author wrote it — taken
+// from the manifest, which recorded it at the one place the owning plugin was
+// unambiguous. Inferring it here is what this replaced: the manifest carries a
+// deploy-manifest entry name and the key carries the registered name, and no
+// rule relates the two (`platform-inspector` against `PlatformInspector` is an
+// ordinary pairing), so any comparison here eventually quotes a string that is
+// in no source file.
+//
+// A site with no recorded annotation predates the recording. It still names the
+// field, which is the comment's job; it just makes no claim about the source
+// text it cannot see.
 let renderEntry = (entry: unionEntry): result<array<string>, string> =>
   switch splitKey(entry.key) {
   | None =>
@@ -90,11 +92,13 @@ let renderEntry = (entry: unionEntry): result<array<string>, string> =>
     )
   | Some((plugin, store)) => {
       let comments =
-        entry.declaredBy->Array.map(site =>
-          `  // ${site.pluginName}: ${site.component}.${site.field} @storageRef(${quote(
-              annotationStore(~pluginName=site.pluginName, ~key=entry.key),
-            )})`
-        )
+        entry.declaredBy->Array.map(site => {
+          let site_ = `  // ${site.pluginName}: ${site.component}.${site.field}`
+          switch site.annotation {
+          | Some(annotation) => `${site_} @storageRef(${quote(annotation)})`
+          | None => site_
+          }
+        })
       let line = switch entry.kind {
       | ObjectStore => `  ObjectStore({plugin: ${quote(plugin)}, store: ${quote(store)}}),`
       }

package/src/generator/PlatformCodegen.res.mjs

@@ -14,7 +14,8 @@ function union(manifests) {
       let sites = entry.declaredBy.map(site => ({
         pluginName: pluginName,
         component: site.component,
-        field: site.field
+        field: site.field,
+        annotation: site.annotation
       }));
       let existing = byKey[entry.key];
       if (existing !== undefined) {
@@ -46,15 +47,6 @@ function splitKey(key) {
   ]);
 }
 
-function annotationStore(pluginName, key) {
-  let match = splitKey(key);
-  if (match !== undefined && match[0].toLowerCase() === pluginName.toLowerCase()) {
-    return match[1];
-  } else {
-    return key;
-  }
-}
-
 function renderEntry(entry) {
   let match = splitKey(entry.key);
   if (match === undefined) {
@@ -63,7 +55,15 @@ function renderEntry(entry) {
       _0: `malformed capability key ` + JSON.stringify(entry.key) + ` — expected "{plugin}.{store}" (is the plugin's capabilities.json hand-edited?)`
     };
   }
-  let comments = entry.declaredBy.map(site => `  // ` + site.pluginName + `: ` + site.component + `.` + site.field + ` @storageRef(` + JSON.stringify(annotationStore(site.pluginName, entry.key)) + `)`);
+  let comments = entry.declaredBy.map(site => {
+    let site_ = `  // ` + site.pluginName + `: ` + site.component + `.` + site.field;
+    let annotation = site.annotation;
+    if (annotation !== undefined) {
+      return site_ + ` @storageRef(` + JSON.stringify(annotation) + `)`;
+    } else {
+      return site_;
+    }
+  });
   let line = `  ObjectStore({plugin: ` + JSON.stringify(match[0]) + `, store: ` + JSON.stringify(match[1]) + `}),`;
   return {
     TAG: "Ok",
@@ -108,7 +108,6 @@ export {
   union,
   quote,
   splitKey,
-  annotationStore,
   renderEntry,
   header,
   render,

package/src/semantic/Semantic.res

@@ -90,8 +90,43 @@ let refined = (base: S.t<'a>, ~id: string, ~check: 'a => result<'a, string>): S.
     reach forms through `validateInput`, so they quote the offending value. */
 let showString = (raw: string): string => raw->JSON.Encode.string->JSON.stringify
 
-/** The semantic a field's schema carries, if any. */
-let get = (fieldSchema: S.t<'a>): option<t> => S.Metadata.get(fieldSchema, ~id=semanticId)
+/**
+The semantic a field's schema carries, if any.
+
+An **optional** field keeps its marker one level down. The ppx annotates the
+field's `string`, and sury-ppx then wraps that schema in a union with
+`Undefined`/`Null`; the wrapper is a new schema and carries no metadata of its
+own. So a walk that reads only the outer schema sees `imageUrl?: string` as
+carrying no semantic at all — the store goes undeclared, the reference goes
+uncollected, the branded scalar loses its brand. Every reader converges here, so
+following the wrapper once here is what keeps "optional" a statement about
+presence rather than a way to lose the field's type.
+
+The outer schema is read first, so a marker set on the wrapper itself still wins.
+Only a union with exactly one non-null variant is followed: that is the shape an
+optional field has, and a genuine multi-variant union has no single inner schema
+whose semantic could stand for the whole.
+*/
+let rec getFrom = (schema: S.t<unknown>): option<t> =>
+  switch S.Metadata.get(schema, ~id=semanticId) {
+  | Some(_) as found => found
+  | None =>
+    switch schema {
+    | Union({anyOf}) =>
+      switch anyOf->Array.filter(v =>
+        switch v {
+        | Null(_) | Undefined(_) => false
+        | _ => true
+        }
+      ) {
+      | [inner] => getFrom(inner)
+      | _ => None
+      }
+    | _ => None
+    }
+  }
+
+let get = (fieldSchema: S.t<'a>): option<t> => fieldSchema->S.castToUnknown->getFrom
 
 /** Whether a field's schema carries this specific semantic. */
 let has = (fieldSchema: S.t<'a>, ~id: string): bool =>

package/src/semantic/Semantic.res.mjs

@@ -40,12 +40,37 @@ function showString(raw) {
   return JSON.stringify(raw);
 }
 
-function get(fieldSchema) {
-  return S.Metadata.get(fieldSchema, semanticId);
+function getFrom(_schema) {
+  while (true) {
+    let schema = _schema;
+    let found = S.Metadata.get(schema, semanticId);
+    if (found !== undefined) {
+      return found;
+    }
+    if (schema.type !== "union") {
+      return;
+    }
+    let match = schema.anyOf.filter(v => {
+      switch (v.type) {
+        case "null" :
+        case "undefined" :
+          return false;
+        default:
+          return true;
+      }
+    });
+    if (match.length !== 1) {
+      return;
+    }
+    _schema = match[0];
+    continue;
+  };
 }
 
+let get = getFrom;
+
 function has(fieldSchema, id) {
-  let s = S.Metadata.get(fieldSchema, semanticId);
+  let s = getFrom(fieldSchema);
   if (s !== undefined) {
     return s.id === id;
   } else {
@@ -59,6 +84,7 @@ export {
   mark,
   refined,
   showString,
+  getFrom,
   get,
   has,
 }