@reventlessdev/reventless-spec 3.0.0-alpha.90 → 3.0.0-alpha.91

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.91 (2026-08-01)
+
+### Bug Fixes
+
+* **spec,core:** heal a missing scalar on read ([de9a98e](https://github.com/ReventlessDev/reventless-core/commit/de9a98ec5fe11ec19bef80626e99244d9c30a6b1))
+* **spec,core:** make the storageRef annotation optional, as its readers already are ([c8477c5](https://github.com/ReventlessDev/reventless-core/commit/c8477c5c34384b864c06716dc5896310629dc349))
+
+
 # 3.0.0-alpha.90 (2026-08-01)
 
 ### Features

package/package.json

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

package/src/components/CapabilityManifest.res

@@ -56,7 +56,7 @@ let fromStructure = (structure: Plugin.pluginStructure): t => {
       key,
       declaredBy: declarations->Array.filterMap(d =>
         d.store == key
-          ? Some({component: d.component, field: d.field, annotation: d.annotation})
+          ? Some({component: d.component, field: d.field, annotation: ?d.annotation})
           : None
       ),
     }),

package/src/components/Plugin.res

@@ -395,13 +395,26 @@ 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.
+
+Optional for the same reason `CapabilityManifest.provenance` and
+`PlatformCodegen.provenance` — the two places this value travels onward to —
+already declare it optional: an event stored before the field existed cannot
+say what the source said, and a reader that cannot say omits the claim rather
+than inventing one. Every definition emitted now carries it.
+
+That is not a stylistic preference. It was first added here as a required
+`string` while events written without it were already stored, and since the
+lifecycle aggregate replays its own log before every decision, those events
+stopped decoding and the plugin's registration froze for two days. `None` is
+also the honest value: `""` would assert the author wrote an empty annotation.
+See the schema-evolution note on `pluginStructure` below.
 */
 @schema
 type requiredStoreDeclaration = {
   store: string,
   component: string,
   field: string,
-  annotation: string,
+  annotation: @s.matches(stringOptionSchema) option<string>,
 }
 
 let requiredStoreDeclarationArrayOptionSchema = _jsNullable(
@@ -409,6 +422,32 @@ let requiredStoreDeclarationArrayOptionSchema = _jsNullable(
   (),
 )
 
+/**
+Adding a field here? It has to be a shape a stale event can be healed into.
+
+Everything reachable from `pluginDefinition` is persisted in the Plugin lifecycle
+aggregate's event log, and that aggregate replays its own log before every
+decision. Events already written do not have your new field, so if decoding one
+of them throws, the aggregate cannot process ANY command for that plugin — it
+stops answering the deploy handshake and its registration silently freezes at
+whatever version connected last.
+
+`Message.parseJsonTolerant` heals a stale event on read, but only for shapes it
+can supply a value for: a `T | null` union (→ `None`), an array (→ `[]`), a
+mandatory enum (→ first variant), a nested object (→ recursively filled), and a
+scalar (→ `""` / `0` / `false`, logged as a warning because it is a fabricated
+value, not a derived one).
+
+So: **prefer `js_nullable` for anything genuinely optional**, and expect a scalar
+addition to show up as a warning in the logs of every deployment that still holds
+older events. A field that can be absent should say so in its type rather than
+lean on the healer.
+
+The regression suite for this is `PluginLifecycleCorpusTest` in reventless-core,
+which decodes frozen payloads captured off a deployed log. If it goes red naming
+your field, re-shape the field — do not re-cut the fixtures. Background:
+`docs/analysis/plugin-definition-schema-evolution-wedge.md`.
+*/
 @schema
 type pluginStructure = {
   readModels: array<queryableDef>,

package/src/components/Plugin.res.mjs

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

package/src/types/Message.res

@@ -156,27 +156,53 @@ type commandJson = {
 // message); only when it throws do we schema-guide the raw JSON and retry once. The fill
 // walks the target sury schema and inserts, for any absent field, the value that field's
 // schema expects: `null` for a `T | null` union (→ `None`), `[]` for a missing array, the
-// first variant of a mandatory enum (`kind` → `Domain`), and a filled `{}` for a missing
-// nested object. It descends only into values actually present, matches tagged-union
-// members by their `TAG` const, is purely additive (clones via a JSON round-trip; never
-// re-encodes through the schema), is idempotent on valid data, and falls back to the
-// ORIGINAL error when the fill doesn't resolve the failure — so genuine corruption still
-// surfaces. See docs/plans/platform-infrastructure-in-plugin-list.md (durable fix option 2).
-let fillMissingDefaults: (S.t<'a>, JSON.t) => JSON.t = %raw(`function(schema, json){
+// first variant of a mandatory enum (`kind` → `Domain`), a filled `{}` for a missing
+// nested object, and a zero value for a missing scalar. It descends only into values
+// actually present, matches tagged-union members by their `TAG` const, is purely additive
+// (clones via a JSON round-trip; never re-encodes through the schema), is idempotent on
+// valid data, and falls back to the ORIGINAL error when the fill doesn't resolve the
+// failure — so genuine corruption still surfaces.
+// See docs/plans/platform-infrastructure-in-plugin-list.md (durable fix option 2).
+//
+// The scalar arm is the odd one out and is deliberately noisy. Every other fill is
+// *derived* — the schema states what an absent value means, and the fill supplies exactly
+// that. A scalar has no such statement, so `""` / `0` / `false` is a value this code
+// invented: right for a descriptive field added later, wrong for a field that carries
+// meaning. It also widens what can be masked, since a genuinely truncated payload now
+// decodes where it used to throw. Every scalar fill is therefore reported to the caller
+// and logged, so healing stays findable instead of becoming the silent default. Without
+// it, a required-scalar addition freezes an aggregate outright — see
+// docs/analysis/plugin-definition-schema-evolution-wedge.md.
+//
+// `bigint` is excluded on purpose: it has no JSON representation, so any value invented
+// here would fail the retry anyway and mask the real error path.
+//
+// `scalarFills` is an out-parameter: the walker pushes `path := value` for each scalar it
+// invented.
+let fillMissingDefaults: (S.t<'a>, JSON.t, array<string>) => JSON.t = %raw(`function(schema, json, scalarFills){
   function isSchema(x){ return x && typeof x === "object" && typeof x.type === "string"; }
   function firstConst(anyOf){ var m=(anyOf||[]).find(function(s){return s.const!==undefined;}); return m ? m.const : undefined; }
-  function fill(schema, value){
+  function scalarDefault(schema){
+    if(schema.const!==undefined) return schema.const;
+    switch(schema.type){
+      case "string": return "";
+      case "number": return 0;
+      case "boolean": return false;
+      default: return undefined;
+    }
+  }
+  function fill(schema, value, path){
     if(!isSchema(schema)) return value;
     switch(schema.type){
       case "object": {
         if(value===undefined){ value={}; }
         else if(value===null || typeof value!=="object" || Array.isArray(value)) return value;
         var items=schema.items||[];
-        for(var i=0;i<items.length;i++){ var it=items[i]; value[it.location]=fill(it.schema, value[it.location]); }
+        for(var i=0;i<items.length;i++){ var it=items[i]; value[it.location]=fill(it.schema, value[it.location], path+"."+it.location); }
         return value;
       }
       case "array": {
-        if(Array.isArray(value)){ var el=schema.additionalItems; return isSchema(el) ? value.map(function(v){return fill(el,v);}) : value; }
+        if(Array.isArray(value)){ var el=schema.additionalItems; return isSchema(el) ? value.map(function(v,ix){return fill(el,v,path+"["+ix+"]");}) : value; }
         if(value===undefined) return [];
         return value;
       }
@@ -185,24 +211,30 @@ let fillMissingDefaults: (S.t<'a>, JSON.t) => JSON.t = %raw(`function(schema, js
         if(value===undefined){
           if(has.null) return null;
           var c=firstConst(schema.anyOf); if(c!==undefined) return c;
-          var obj=(schema.anyOf||[]).find(function(s){return s.type==="object";}); if(obj) return fill(obj,{});
+          var obj=(schema.anyOf||[]).find(function(s){return s.type==="object";}); if(obj) return fill(obj,{},path);
           return undefined;
         }
         if(value===null) return null;
         var members=schema.anyOf||[];
-        if(Array.isArray(value)){ var a=members.find(function(s){return s.type==="array";}); return a ? fill(a,value) : value; }
+        if(Array.isArray(value)){ var a=members.find(function(s){return s.type==="array";}); return a ? fill(a,value,path) : value; }
         if(typeof value==="object"){
           var m=members.find(function(s){return s.type==="object" && (s.items||[]).some(function(it){return it.location==="TAG" && it.schema.const===value.TAG;});});
           if(!m) m=members.find(function(s){return s.type==="object";});
-          return m ? fill(m,value) : value;
+          return m ? fill(m,value,path) : value;
         }
         return value;
       }
-      default: return value;
+      default: {
+        if(value!==undefined) return value;
+        var d=scalarDefault(schema);
+        if(d===undefined) return value;
+        scalarFills.push(path + " := " + JSON.stringify(d));
+        return d;
+      }
     }
   }
   // Clone via JSON round-trip (json is already pure JSON) so the caller's value is never mutated.
-  return fill(schema, JSON.parse(JSON.stringify(json)));
+  return fill(schema, JSON.parse(JSON.stringify(json)), "");
 }`)
 
 // Strict parse with a single schema-migration-on-read retry (see fillMissingDefaults).
@@ -210,8 +242,22 @@ let parseJsonTolerant = (json, schema) =>
   switch json->S.parseJsonOrThrow(schema) {
   | value => value
   | exception firstErr =>
-    switch fillMissingDefaults(schema, json)->S.parseJsonOrThrow(schema) {
-    | value => value
+    let scalarFills = []
+    switch fillMissingDefaults(schema, json, scalarFills)->S.parseJsonOrThrow(schema) {
+    | value =>
+      // Only the invented values are worth a line. A heal that used nothing but
+      // schema-derived defaults is the mechanism working as designed.
+      if scalarFills->Array.length > 0 {
+        Console.warn(
+          `[reventless] decoded a stored message by inventing ${scalarFills
+            ->Array.length
+            ->Int.toString} missing scalar field(s): ${scalarFills->Array.join(
+              ", ",
+            )}. A required scalar was added to a persisted type after this message was ` ++
+          `written; the value above is fabricated, not recovered. Prefer a js_nullable (T | null) field.`,
+        )
+      }
+      value
     | exception _ => throw(firstErr)
     }
   }

package/src/types/Message.res.mjs

@@ -35,21 +35,30 @@ let commandJsonSchema = S.schema(s => ({
   delay: s.m(S.option(S.int))
 }));
 
-let fillMissingDefaults = (function(schema, json){
+let fillMissingDefaults = (function(schema, json, scalarFills){
   function isSchema(x){ return x && typeof x === "object" && typeof x.type === "string"; }
   function firstConst(anyOf){ var m=(anyOf||[]).find(function(s){return s.const!==undefined;}); return m ? m.const : undefined; }
-  function fill(schema, value){
+  function scalarDefault(schema){
+    if(schema.const!==undefined) return schema.const;
+    switch(schema.type){
+      case "string": return "";
+      case "number": return 0;
+      case "boolean": return false;
+      default: return undefined;
+    }
+  }
+  function fill(schema, value, path){
     if(!isSchema(schema)) return value;
     switch(schema.type){
       case "object": {
         if(value===undefined){ value={}; }
         else if(value===null || typeof value!=="object" || Array.isArray(value)) return value;
         var items=schema.items||[];
-        for(var i=0;i<items.length;i++){ var it=items[i]; value[it.location]=fill(it.schema, value[it.location]); }
+        for(var i=0;i<items.length;i++){ var it=items[i]; value[it.location]=fill(it.schema, value[it.location], path+"."+it.location); }
         return value;
       }
       case "array": {
-        if(Array.isArray(value)){ var el=schema.additionalItems; return isSchema(el) ? value.map(function(v){return fill(el,v);}) : value; }
+        if(Array.isArray(value)){ var el=schema.additionalItems; return isSchema(el) ? value.map(function(v,ix){return fill(el,v,path+"["+ix+"]");}) : value; }
         if(value===undefined) return [];
         return value;
       }
@@ -58,35 +67,47 @@ let fillMissingDefaults = (function(schema, json){
         if(value===undefined){
           if(has.null) return null;
           var c=firstConst(schema.anyOf); if(c!==undefined) return c;
-          var obj=(schema.anyOf||[]).find(function(s){return s.type==="object";}); if(obj) return fill(obj,{});
+          var obj=(schema.anyOf||[]).find(function(s){return s.type==="object";}); if(obj) return fill(obj,{},path);
           return undefined;
         }
         if(value===null) return null;
         var members=schema.anyOf||[];
-        if(Array.isArray(value)){ var a=members.find(function(s){return s.type==="array";}); return a ? fill(a,value) : value; }
+        if(Array.isArray(value)){ var a=members.find(function(s){return s.type==="array";}); return a ? fill(a,value,path) : value; }
         if(typeof value==="object"){
           var m=members.find(function(s){return s.type==="object" && (s.items||[]).some(function(it){return it.location==="TAG" && it.schema.const===value.TAG;});});
           if(!m) m=members.find(function(s){return s.type==="object";});
-          return m ? fill(m,value) : value;
+          return m ? fill(m,value,path) : value;
         }
         return value;
       }
-      default: return value;
+      default: {
+        if(value!==undefined) return value;
+        var d=scalarDefault(schema);
+        if(d===undefined) return value;
+        scalarFills.push(path + " := " + JSON.stringify(d));
+        return d;
+      }
     }
   }
   // Clone via JSON round-trip (json is already pure JSON) so the caller's value is never mutated.
-  return fill(schema, JSON.parse(JSON.stringify(json)));
+  return fill(schema, JSON.parse(JSON.stringify(json)), "");
 });
 
 function parseJsonTolerant(json, schema) {
   try {
     return S.parseJsonOrThrow(json, schema);
   } catch (firstErr) {
+    let scalarFills = [];
+    let value;
     try {
-      return S.parseJsonOrThrow(fillMissingDefaults(schema, json), schema);
+      value = S.parseJsonOrThrow(fillMissingDefaults(schema, json, scalarFills), schema);
     } catch (exn) {
       throw firstErr;
     }
+    if (scalarFills.length !== 0) {
+      console.warn(`[reventless] decoded a stored message by inventing ` + scalarFills.length.toString() + ` missing scalar field(s): ` + scalarFills.join(", ") + `. A required scalar was added to a persisted type after this message was written; the value above is fabricated, not recovered. Prefer a js_nullable (T | null) field.`);
+    }
+    return value;
   }
 }