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

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.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
+
+* **spec:** add DateRange semantic type ([d85b6cc](https://github.com/ReventlessDev/reventless-core/commit/d85b6cc18241644905241df2abd99949dd758059))
+
+
 # 3.0.0-alpha.89 (2026-07-31)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.89",
+  "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/semantic/DateRange.res

@@ -0,0 +1,148 @@
+/**
+A span of time: two ISO-8601 instants, a start and an end, as one value.
+
+## Why the pair is the value, not two fields beside each other
+
+Before this type a span was a *guess*. A view that wanted a calendar, a timeline
+or a gantt bar asked which fields were date-like and took the first named
+`start…` and the first named `end…`, independently. Three things go wrong and
+all three are silent: two intervals in one row mispair across each other (a bar
+drawn from one interval's start to the other's end); an interval named anything
+else — `checkIn`/`checkOut`, `from`/`to` — is invisible; and a lone `started…`
+point pairs with whatever `end…` is nearby. Making the two instants one value
+removes the pairing question: a consumer either holds the span or it does not.
+
+The parts keep their own `dateTime` marker, so a walker that only understands
+date-times still sees them, and the whole carries `dateRange` besides. That is
+the same layering `Money` uses — the amount keeps being a number, the composite
+adds the meaning the number cannot carry.
+
+## `[start, end)` — end exclusive
+
+A range runs from `start` up to but not including `end`. `09:00–11:00` and
+`11:00–13:00` are adjacent, not overlapping, and an all-day grid needs no
+off-by-one-millisecond convention invented per consumer. This is a decision, not
+a default: `overlaps` and `contains` are the only places it is written, and no
+layout may re-decide it.
+
+## Why the ordering rule is not enforced at decode
+
+`start <= end` relates two fields, so — unlike `Money`'s wholeness, which is a
+property of one field and rides on that field's schema — it is a *record-level*
+invariant. sury 11.0.0-alpha.4 miscompiles a refinement wrapping a record schema
+(it hoists the result object above the field reads, so parse and serialize throw
+`Cannot access 'v0' before initialization`), and the pin has not moved. So the
+rule lives in `validate`/`make` and **the schema does not enforce it at decode**.
+
+This is the first semantic type in this library whose invariant the boundary does
+not check: `Money` rejects a fractional minor unit on the way in; `DateRange`
+will accept a range that ends before it starts if one is ever written. A reader
+who assumes parity with `Money` assumes wrong. When sury fixes the record
+refinement the rule moves into the schema and `validate` stays as its single
+definition — the relationship `Money.validateAmount` has with `amountSchema`.
+
+Parsing is `Date.fromString` on each instant. A range whose strings do not parse
+is a decode-time problem the `DateTime` marker does not currently catch either,
+so there is no second validation layer here — a reversed *parseable* range is
+what `validate` catches, and an unparseable one is out of both their scope.
+
+## How a field declares it
+
+The field's declared type *is* `DateRange.t`, and sury-ppx resolves it to this
+module's `schema`:
+
+```rescript
+@schema type state = {
+  orderId: string,
+  deliveryWindow: option<Reventless.DateRange.t>,
+}
+```
+
+which serializes as `{"start": "2026-03-02T09:00:00Z", "end": "2026-03-02T11:00:00Z"}`.
+
+**Introduced as a new optional field it is additive** — an absent optional
+decodes to `None` for events written before it existed, so no upcaster and no
+projection rebuild. It costs a log something only if it *collapses* an existing
+`start*`/`end*` pair, which rewrites the wire shape the way `Money` rewrote
+`price: float`. That collapse belongs to whoever builds the upcaster.
+*/
+
+@schema
+type t = {
+  /** The instant the range opens, inclusive. */
+  start: @s.matches(DateTime.string) string,
+  /** The instant the range closes, **exclusive** — the range does not contain
+      it. `@as("end")` puts `end` on the wire (where the UI's own `GanttChart`
+      already spells it that way); `end_` is the source spelling because `end`
+      is awkward as a bare ReScript field. */
+  @as("end") end_: @s.matches(DateTime.string) string,
+}
+
+/** The sury schema for a date-range field, carrying the `dateRange` semantic.
+
+    Shadows the schema sury-ppx derived from the type above: the derived one is
+    the shape, and this adds the marker the shape cannot carry. The ordering rule
+    is deliberately *not* refined in here — see the module doc. */
+let schema: S.t<t> = schema->Semantic.mark(~id=Semantic.Id.dateRange)
+
+/** An instant as milliseconds since the epoch — `NaN` if it does not parse. The
+    one place a range's strings become numbers, so end-exclusivity and the
+    ordering rule are all expressed against a single parse. */
+let millis = (instant: string): float => instant->Date.fromString->Date.getTime
+
+/**
+Validate a range's ordering, saying why when it is reversed.
+
+The single statement of the `start <= end` rule; `make` is derived from it, and
+`schema` will be once sury's record refinement is fixed. An unparseable instant
+is not caught here (see the module doc) — a reversed range means two instants
+that both parse, the earlier one second.
+*/
+let validate = (range: t): result<t, string> =>
+  millis(range.start) > millis(range.end_)
+    ? Error(
+        `a range ends before it starts: ${range.start} is after ${range.end_}. ` ++
+        `A range is [start, end) — the start is the earlier instant.`,
+      )
+    : Ok(range)
+
+/** Build a validated range from its two instants. `end` is exclusive. */
+let make = (~start: string, ~end_: string): result<t, string> => validate({start, end_})
+
+/**
+The range's length as a `Duration`, in whole seconds — the composite composing
+with one of the branded scalars.
+
+Total: a valid range has a non-negative length, and a zero-length range is
+zero seconds. Truncated to whole seconds because that is what `Duration` is.
+*/
+let duration = (range: t): Duration.t =>
+  Duration.unsafe(Math.trunc((millis(range.end_) -. millis(range.start)) /. 1000.0)->Float.toInt)
+
+/**
+Whether an instant falls within the range — at or after `start`, strictly before
+`end`. End-exclusive, so the instant that opens the next adjacent range is *not*
+contained by this one. One of the two places `[start, end)` is decided.
+*/
+let contains = (range: t, instant: string): bool => {
+  let t = millis(instant)
+  t >= millis(range.start) && t < millis(range.end_)
+}
+
+/**
+Whether two ranges share any instant. End-exclusive: `09:00–11:00` and
+`11:00–13:00` are adjacent and do *not* overlap. The other place `[start, end)`
+is decided — a layout that re-decides it will disagree with this.
+*/
+let overlaps = (a: t, b: t): bool =>
+  millis(a.start) < millis(b.end_) && millis(b.start) < millis(a.end_)
+
+/**
+The range as text: the two instants with an en dash between them —
+`"2026-03-02T09:00:00Z – 2026-03-02T11:00:00Z"`.
+
+Locale-independent, matching the rest of the framework's formatters: the same
+value reads the same in every log line and every test. A calendar-style
+rendering is the presentation layer's job.
+*/
+let format = (range: t): string => `${range.start} – ${range.end_}`

package/src/semantic/DateRange.res.mjs

@@ -0,0 +1,74 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as DateTime$Reventless from "../types/DateTime.res.mjs";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+
+let schema = S.schema(s => ({
+  start: s.m(DateTime$Reventless.string),
+  end: s.m(DateTime$Reventless.string)
+}));
+
+let schema$1 = Semantic$Reventless.mark(schema, Semantic$Reventless.Id.dateRange, undefined);
+
+function millis(instant) {
+  return new Date(instant).getTime();
+}
+
+function validate(range) {
+  if (new Date(range.start).getTime() > new Date(range.end).getTime()) {
+    return {
+      TAG: "Error",
+      _0: `a range ends before it starts: ` + range.start + ` is after ` + range.end + `. A range is [start, end) — the start is the earlier instant.`
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: range
+    };
+  }
+}
+
+function make(start, end_) {
+  return validate({
+    start: start,
+    end: end_
+  });
+}
+
+function duration(range) {
+  return Math.trunc((new Date(range.end).getTime() - new Date(range.start).getTime()) / 1000.0) | 0;
+}
+
+function contains(range, instant) {
+  let t = new Date(instant).getTime();
+  if (t >= new Date(range.start).getTime()) {
+    return t < new Date(range.end).getTime();
+  } else {
+    return false;
+  }
+}
+
+function overlaps(a, b) {
+  if (new Date(a.start).getTime() < new Date(b.end).getTime()) {
+    return new Date(b.start).getTime() < new Date(a.end).getTime();
+  } else {
+    return false;
+  }
+}
+
+function format(range) {
+  return range.start + ` – ` + range.end;
+}
+
+export {
+  schema$1 as schema,
+  millis,
+  validate,
+  make,
+  duration,
+  contains,
+  overlaps,
+  format,
+}
+/* schema Not a pure module */

package/src/semantic/Semantic.res

@@ -63,6 +63,12 @@ module Id = {
   // this one changes a field's *shape* — a number becomes an object — so it is
   // a wire-breaking declaration rather than a refinement of one.
   let money = "money"
+
+  // The second composite. A pair of ISO-8601 instants as one value, replacing a
+  // span the UI used to guess from a `start*`/`end*` name pair. Like `money` it
+  // is an object on the wire; unlike it, adopting it as a *new* optional field
+  // is additive — an absent optional decodes to `None`.
+  let dateRange = "dateRange"
 }
 
 let semanticId: S.Metadata.Id.t<t> = S.Metadata.Id.make(~namespace="reventless", ~name="semantic")

package/src/semantic/Semantic.res.mjs

@@ -13,7 +13,8 @@ let Id = {
   bytes: "bytes",
   duration: "duration",
   color: "color",
-  money: "money"
+  money: "money",
+  dateRange: "dateRange"
 };
 
 let semanticId = S.Metadata.Id.make("reventless", "semantic");

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