@reventlessdev/reventless-spec 3.0.0-alpha.71 → 3.0.0-alpha.73

package/CHANGELOG.md

@@ -3,6 +3,20 @@
 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.73 (2026-07-11)
+
+### Bug Fixes
+
+* **plugin-lifecycle:** heal message decode of definitions persisted before a schema field existed ([6bb3e72](https://github.com/ReventlessDev/reventless-core/commit/6bb3e7259ad606a0f77fb670bcfc680256592003))
+
+
+# 3.0.0-alpha.72 (2026-07-10)
+
+### Features
+
+* **plugin-structure:** capture per-component chapter grouping for the deployed graph ([f9c88a9](https://github.com/ReventlessDev/reventless-core/commit/f9c88a9a48d8c032ffe23f9e5277caf12c29e85c))
+
+
 # 3.0.0-alpha.71 (2026-07-10)
 
 **Note:** Version bump only for package @reventlessdev/reventless-spec

package/package.json

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

package/src/components/Plugin.res

@@ -215,6 +215,20 @@ type queryableDef = {
   existed decode as `None` (Public).
   */
   visibility: @s.matches(stringOptionSchema) option<string>,
+  /**
+  Intra-plugin grouping band (the "chapter") this component belongs to, captured at
+  build time from its source folder by the plugin generator: the first path segment
+  under the plugin's `src/` that is not a recognised kind-folder
+  (`src/<Chapter>/…/<Component>.res` → `Some("<Chapter>")`; a component directly under a
+  kind-folder → `None`). Lets a consumer that renders the event graph from the
+  *deployed* plugin structure group components into chapter sub-containers identically
+  to the authoring tooling, with no workspace/disk access — the renderer already
+  supports the bands (`DomainGraphD2 ~chapters`); only this datum was missing on the
+  deployed side. `None` (absent) renders flat. js_nullable (T | null) keeps it JSON-safe
+  inside the lifecycle Message union; always written (None → null), so defs persisted
+  before this field existed must be reset/re-emitted. See [[deployed-chapter-grouping]].
+  */
+  chapter: @s.matches(stringOptionSchema) option<string>,
 }
 
 /**
@@ -244,6 +258,8 @@ type writableDef = {
   arrays; `[]` when there are none. The structure is re-derived on every build/
   deploy, so no persisted-data back-compat shim is needed. */
   events: array<eventDef>,
+  /** Chapter grouping band — see `queryableDef.chapter`. */
+  chapter: @s.matches(stringOptionSchema) option<string>,
 }
 
 @schema
@@ -252,6 +268,8 @@ type automationSliceDef = {
   consumedEventTypes: array<string>,
   producedCommandTypes: array<string>,
   targetName: string,
+  /** Chapter grouping band — see `queryableDef.chapter`. */
+  chapter: @s.matches(stringOptionSchema) option<string>,
 }
 
 @schema
@@ -262,6 +280,8 @@ type outboundTranslationSliceDef = {
   targetName: @s.matches(stringOptionSchema) option<string>,
   // Foreign system this slice publishes to — drives the external box (Event Graph).
   externalSystem: @s.matches(stringOptionSchema) option<string>,
+  /** Chapter grouping band — see `queryableDef.chapter`. */
+  chapter: @s.matches(stringOptionSchema) option<string>,
 }
 
 @schema
@@ -271,6 +291,8 @@ type inboundTranslationSliceDef = {
   targetName: string,
   // Foreign system this slice receives from — drives the external box (Event Graph).
   externalSystem: @s.matches(stringOptionSchema) option<string>,
+  /** Chapter grouping band — see `queryableDef.chapter`. */
+  chapter: @s.matches(stringOptionSchema) option<string>,
 }
 
 @schema

package/src/components/Plugin.res.mjs

@@ -109,7 +109,8 @@ let queryableDefSchema = S.schema(s => ({
   labelField: s.m(S.string),
   searchableFields: s.m(S.array(S.string)),
   statusField: s.m(stringOptionSchema),
-  visibility: s.m(stringOptionSchema)
+  visibility: s.m(stringOptionSchema),
+  chapter: s.m(stringOptionSchema)
 }));
 
 let eventDefSchema = S.schema(s => ({
@@ -125,14 +126,16 @@ let writableDefSchema = S.schema(s => ({
   consumedEventTypes: s.m(S.array(S.string)),
   linkedViews: s.m(S.array(S.string)),
   consistencyRead: s.m(stringOptionSchema),
-  events: s.m(S.array(eventDefSchema))
+  events: s.m(S.array(eventDefSchema)),
+  chapter: s.m(stringOptionSchema)
 }));
 
 let automationSliceDefSchema = S.schema(s => ({
   name: s.m(S.string),
   consumedEventTypes: s.m(S.array(S.string)),
   producedCommandTypes: s.m(S.array(S.string)),
-  targetName: s.m(S.string)
+  targetName: s.m(S.string),
+  chapter: s.m(stringOptionSchema)
 }));
 
 let outboundTranslationSliceDefSchema = S.schema(s => ({
@@ -140,14 +143,16 @@ let outboundTranslationSliceDefSchema = S.schema(s => ({
   consumedEventTypes: s.m(S.array(S.string)),
   inboundCommandTypes: s.m(S.array(S.string)),
   targetName: s.m(stringOptionSchema),
-  externalSystem: s.m(stringOptionSchema)
+  externalSystem: s.m(stringOptionSchema),
+  chapter: s.m(stringOptionSchema)
 }));
 
 let inboundTranslationSliceDefSchema = S.schema(s => ({
   name: s.m(S.string),
   commandTypes: s.m(S.array(S.string)),
   targetName: s.m(S.string),
-  externalSystem: s.m(stringOptionSchema)
+  externalSystem: s.m(stringOptionSchema),
+  chapter: s.m(stringOptionSchema)
 }));
 
 let extensionDefSchema = S.schema(s => ({

package/src/generator/Codegen.res

@@ -269,6 +269,7 @@ let renderPluginStructureCall = (
   ~inboundTranslationSlices: array<string>,
   ~extensions: array<string>,
   ~extensionPoints: array<Pairing.extensionPointDef>,
+  ~componentChapters: array<(string, string)>,
 ): option<array<string>> => {
   // The structure call carries the EP *mapping* files (one per Delegate
   // connection), not the wrapped ExtensionPoint module — Plugin_Structure reads
@@ -337,6 +338,16 @@ let renderPluginStructureCall = (
       let entries = epMappingStems->Array.map(s => "module(" ++ s ++ ")")
       ls->Array.push("    ~extensionPoints=[" ++ entries->Array.join(", ") ++ "],")
     }
+    // Chapter grouping bands per component, captured from the source folder layout.
+    // Only emitted when at least one component lives under a chapter folder, so
+    // plugins with a flat `src/` keep a byte-identical generated Plugin.res.
+    if componentChapters->Array.length > 0 {
+      let entries =
+        componentChapters->Array.map(((stem, chapter)) =>
+          "(\"" ++ stem ++ "\", \"" ++ chapter ++ "\")"
+        )
+      ls->Array.push("    ~componentChapters=Dict.fromArray([" ++ entries->Array.join(", ") ++ "]),")
+    }
     ls->Array.push("  )")
     Some(ls)
   }
@@ -493,7 +504,11 @@ let renderAwsWrapper = (~compositionNamespace: string): string => {
 
 // ── Composition-variant render ───────────────────────────────────────────────
 
-let renderComposition = (~config: Config.config, ~resolved: Pairing.resolved): string => {
+let renderComposition = (
+  ~config: Config.config,
+  ~resolved: Pairing.resolved,
+  ~componentChapters: array<(string, string)>,
+): string => {
   let lines: array<string> = []
 
   // Header
@@ -616,6 +631,7 @@ let renderComposition = (~config: Config.config, ~resolved: Pairing.resolved): s
     ~inboundTranslationSlices=resolved.inboundTranslationSlices,
     ~extensions=resolved.extensions,
     ~extensionPoints=resolved.extensionPoints,
+    ~componentChapters,
   )
   let hasPluginStructure = pluginStructureLines->Option.isSome
   switch pluginStructureLines {
@@ -706,8 +722,28 @@ let render = (
 ): string => {
   validateUniqueSpecStems(~discovered)
   validateSliceTargets(~resolved)
+  // Chapter map, keyed by each component's spec stem (= its `Spec.name` for every
+  // graph-node kind, which is how `Plugin_Structure` looks the chapter up). Filtered
+  // to the actual component stems so body files (`_Behavior`, `_Projections`, …) —
+  // which `Discovery` also surfaces and which share their component's chapter — don't
+  // leak noise entries into the generated call. Tasks / extensions / extension points
+  // carry no chapter field, so they are excluded too.
+  let componentStems = Array.flat([
+    resolved.aggregates->Array.map(({spec}) => spec),
+    resolved.readModels->Array.map(({readModel}) => readModel),
+    resolved.stateChangeSlices,
+    resolved.stateViewSlices,
+    resolved.stateViewSlicesStream,
+    resolved.automationSlices,
+    resolved.outboundTranslationSlices,
+    resolved.inboundTranslationSlices,
+  ])
+  let componentChapters =
+    Discovery.chaptersByStem(discovered)->Array.filter(((stem, _)) =>
+      componentStems->Array.includes(stem)
+    )
   switch config.variant {
   | Aws({compositionNamespace}) => renderAwsWrapper(~compositionNamespace)
-  | Composition => renderComposition(~config, ~resolved)
+  | Composition => renderComposition(~config, ~resolved, ~componentChapters)
   }
 }

package/src/generator/Codegen.res.mjs

@@ -4,6 +4,7 @@ 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 Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Pairing$Reventless from "./Pairing.res.mjs";
+import * as Discovery$Reventless from "./Discovery.res.mjs";
 
 function stripSuffix(s, suffix) {
   if (s.endsWith(suffix)) {
@@ -185,7 +186,7 @@ function renderTaskMakeParam(tasks) {
   return "      ~tasks=[" + entries.join(", ") + "],";
 }
 
-function renderPluginStructureCall(name, aggregates, readModels, stateViewSlices, stateViewSlicesStream, stateChangeSlices, automationSlices, outboundTranslationSlices, inboundTranslationSlices, extensions, extensionPoints) {
+function renderPluginStructureCall(name, aggregates, readModels, stateViewSlices, stateViewSlicesStream, stateChangeSlices, automationSlices, outboundTranslationSlices, inboundTranslationSlices, extensions, extensionPoints, componentChapters) {
   let epMappingStems = extensionPoints.flatMap(param => param.mappings);
   let hasComponents = aggregates.length !== 0 || readModels.length !== 0 || stateViewSlices.length !== 0 || stateViewSlicesStream.length !== 0 || stateChangeSlices.length !== 0 || automationSlices.length !== 0 || outboundTranslationSlices.length !== 0 || inboundTranslationSlices.length !== 0 || extensions.length !== 0 || epMappingStems.length !== 0;
   if (!hasComponents) {
@@ -237,6 +238,10 @@ function renderPluginStructureCall(name, aggregates, readModels, stateViewSlices
     let entries$7 = epMappingStems.map(s => "module(" + s + ")");
     ls.push("    ~extensionPoints=[" + entries$7.join(", ") + "],");
   }
+  if (componentChapters.length !== 0) {
+    let entries$8 = componentChapters.map(param => "(\"" + param[0] + "\", \"" + param[1] + "\")");
+    ls.push("    ~componentChapters=Dict.fromArray([" + entries$8.join(", ") + "]),");
+  }
   ls.push("  )");
   return ls;
 }
@@ -332,7 +337,7 @@ function renderAwsWrapper(compositionNamespace) {
   ].join("\n");
 }
 
-function renderComposition(config, resolved) {
+function renderComposition(config, resolved, componentChapters) {
   let lines = [];
   lines.push("// AUTO-GENERATED — do not edit. Run `npm run generate` to update.");
   lines.push("");
@@ -389,7 +394,7 @@ function renderComposition(config, resolved) {
     lines.push("  // Extensions");
     push(renderExtensions(resolved.extensions));
   }
-  let pluginStructureLines = renderPluginStructureCall(config.name, resolved.aggregates, resolved.readModels, resolved.stateViewSlices, resolved.stateViewSlicesStream, resolved.stateChangeSlices, resolved.automationSlices, resolved.outboundTranslationSlices, resolved.inboundTranslationSlices, resolved.extensions, resolved.extensionPoints);
+  let pluginStructureLines = renderPluginStructureCall(config.name, resolved.aggregates, resolved.readModels, resolved.stateViewSlices, resolved.stateViewSlicesStream, resolved.stateChangeSlices, resolved.automationSlices, resolved.outboundTranslationSlices, resolved.inboundTranslationSlices, resolved.extensions, resolved.extensionPoints, componentChapters);
   let hasPluginStructure = Stdlib_Option.isSome(pluginStructureLines);
   if (pluginStructureLines !== undefined) {
     pluginStructureLines.forEach(l => {
@@ -448,9 +453,20 @@ function renderComposition(config, resolved) {
 function render(config, resolved, discovered) {
   validateUniqueSpecStems(discovered);
   validateSliceTargets(resolved);
+  let componentStems = [
+    resolved.aggregates.map(param => param.spec),
+    resolved.readModels.map(param => param.readModel),
+    resolved.stateChangeSlices,
+    resolved.stateViewSlices,
+    resolved.stateViewSlicesStream,
+    resolved.automationSlices,
+    resolved.outboundTranslationSlices,
+    resolved.inboundTranslationSlices
+  ].flat();
+  let componentChapters = Discovery$Reventless.chaptersByStem(discovered).filter(param => componentStems.includes(param[0]));
   let match = config.variant;
   if (typeof match !== "object") {
-    return renderComposition(config, resolved);
+    return renderComposition(config, resolved, componentChapters);
   } else {
     return renderAwsWrapper(match.compositionNamespace);
   }

package/src/generator/Discovery.res

@@ -22,6 +22,53 @@ type discoveredFile = {stem: string, componentType: componentType, epGroup: opti
 
 let folderToComponentType = ComponentKind.folderToKind
 
+// The intra-plugin grouping band ("chapter") a file belongs to, derived from its
+// path relative to `src/`: the first directory segment that is not a recognised
+// kind-folder. `src/<Chapter>/<Kind>/<Component>.res` → `Some("<Chapter>")`; a file
+// directly under a kind-folder (`src/<Kind>/<Component>.res`) or at the src root →
+// `None`. Uses the single-source `ComponentKind.isKindFolder`, so a chapter read
+// here (build time, disk) agrees with the authoring tool's identical heuristic and
+// with a chapter reflected off the deployed plugin structure. See
+// docs/plans/deployed-chapter-grouping.md.
+let chapterOf = (relPath: string): option<string> => {
+  let segments = relPath->String.split("/")
+  // Need at least one directory segment before the filename.
+  if segments->Array.length < 2 {
+    None
+  } else {
+    switch segments->Array.get(0) {
+    | Some(first) if !ComponentKind.isKindFolder(first) => Some(first)
+    | _ => None
+    }
+  }
+}
+
+// Deduplicated (stem → chapter) pairs across the discovered files, sorted by stem
+// for deterministic codegen. Only files that carry a chapter are included; stems are
+// unique within a plugin (validated), so keying by stem cannot collide. Body files
+// (`_Behavior`, `_Projections`, …) share their component's chapter but are never
+// looked up by `Spec.name`, so their presence is harmless.
+let chaptersByStem = (discovered: array<discoveredFile>): array<(string, string)> => {
+  let byStem: Dict.t<string> = Dict.make()
+  discovered->Array.forEach(d =>
+    switch chapterOf(d.relPath) {
+    | Some(ch) => byStem->Dict.set(d.stem, ch)
+    | None => ()
+    }
+  )
+  byStem
+  ->Dict.toArray
+  ->Array.toSorted(((a, _), (b, _)) =>
+    if a < b {
+      -1.0
+    } else if a > b {
+      1.0
+    } else {
+      0.0
+    }
+  )
+}
+
 let isAlwaysExcludedDir = (name: string): bool =>
   name === "Plugin" || name === "tests" || name === "lib"
 

package/src/generator/Discovery.res.mjs

@@ -4,6 +4,39 @@ import * as Nodepath from "node:path";
 import * as ComponentKind$Reventless from "../components/ComponentKind.res.mjs";
 import * as Generator_Node$Reventless from "./Generator_Node.res.mjs";
 
+function chapterOf(relPath) {
+  let segments = relPath.split("/");
+  if (segments.length < 2) {
+    return;
+  }
+  let first = segments[0];
+  if (first !== undefined && !ComponentKind$Reventless.isKindFolder(first)) {
+    return first;
+  }
+}
+
+function chaptersByStem(discovered) {
+  let byStem = {};
+  discovered.forEach(d => {
+    let ch = chapterOf(d.relPath);
+    if (ch !== undefined) {
+      byStem[d.stem] = ch;
+      return;
+    }
+  });
+  return Object.entries(byStem).toSorted((param, param$1) => {
+    let b = param$1[0];
+    let a = param[0];
+    if (a < b) {
+      return -1.0;
+    } else if (a > b) {
+      return 1.0;
+    } else {
+      return 0.0;
+    }
+  });
+}
+
 function isAlwaysExcludedDir(name) {
   if (name === "Plugin" || name === "tests") {
     return true;
@@ -151,6 +184,8 @@ let folderToComponentType = ComponentKind$Reventless.folderToKind;
 
 export {
   folderToComponentType,
+  chapterOf,
+  chaptersByStem,
   isAlwaysExcludedDir,
   matchesGlob,
   isExcluded,

package/src/types/Message.res

@@ -140,15 +140,96 @@ type commandJson = {
   delay?: int,
 }
 
+// ── Schema-migration-on-read ──────────────────────────────────────────────────
+// Nested `@schema` types (notably `pluginDefinition`/`pluginStructure`) gain fields
+// over time — `kind`, `chapter`, `events`, `extensionPoints`, `apiExposed`, … Because
+// those types are JSON-encoded inside union-variant payloads, every optional field must
+// use the `js_nullable` (`T | null`) encoding: it is the only JSON-safe optional form,
+// since `S.option`/`nullableAsOption` carry `undefined`, which fails sury's
+// `jsonableValidation` inside a union variant. That encoding is *present-required on
+// decode*, so ONE message persisted before a field was added SuryError-bricks decode. For
+// an aggregate that rehydrates from its own event log (the Plugin lifecycle aggregate),
+// that single event then freezes EVERY later heartbeat/redetect/connect on that instance
+// — a silent lifecycle freeze with no error surfaced near the operator.
+//
+// We heal on read. Strict decode stays the fast path (unchanged for every current
+// 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){
+  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){
+    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]); }
+        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(value===undefined) return [];
+        return value;
+      }
+      case "union": {
+        var has=schema.has||{};
+        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,{});
+          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(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 value;
+      }
+      default: return value;
+    }
+  }
+  // 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)));
+}`)
+
+// Strict parse with a single schema-migration-on-read retry (see fillMissingDefaults).
+let parseJsonTolerant = (json, schema) =>
+  switch json->S.parseJsonOrThrow(schema) {
+  | value => value
+  | exception firstErr =>
+    switch fillMissingDefaults(schema, json)->S.parseJsonOrThrow(schema) {
+    | value => value
+    | exception _ => throw(firstErr)
+    }
+  }
+
 /**
-Decode a JSON value into `'a` using a sury schema. Throws on parse failure.
+Decode a JSON value into `'a` using a sury schema.
+
+Strict decode is the fast path; on failure it applies a single schema-migration-on-read
+retry (see `fillMissingDefaults`) so a message persisted before a nested `@schema` field
+existed still decodes instead of bricking. Re-throws the original error if the fill does
+not resolve the failure.
 
 @example
 ```rescript
 let event = json->Message.decode(Category.eventSchema)
 ```
 */
-let decode = (json, schema: S.t<'a>) => json->S.parseJsonOrThrow(schema)
+let decode = (json, schema: S.t<'a>) => json->parseJsonTolerant(schema)
 
 /**
 Encode a value to JSON using a sury schema.
@@ -170,9 +251,11 @@ let toEventSchema' = (idSchema, eventSchema) =>
     event: s.field("event", eventSchema),
   })
 
-/** Decode a raw event JSON envelope into a typed `event'<'id, 'event>`. */
+/** Decode a raw event JSON envelope into a typed `event'<'id, 'event>`. Tolerant on
+    read (see `fillMissingDefaults`) so envelopes persisted before a nested field existed
+    still decode. */
 let decodeEvent' = (json, idSchema, eventSchema) =>
-  json->S.parseJsonOrThrow(toEventSchema'(idSchema, eventSchema))
+  json->parseJsonTolerant(toEventSchema'(idSchema, eventSchema))
 
 /** Extract the variant constructor name from a sury-encoded variant JSON. */
 let variantNameOfJson = json =>

package/src/types/Message.res.mjs

@@ -35,7 +35,62 @@ let commandJsonSchema = S.schema(s => ({
   delay: s.m(S.option(S.int))
 }));
 
-let decode = S.parseJsonOrThrow;
+let fillMissingDefaults = (function(schema, json){
+  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){
+    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]); }
+        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(value===undefined) return [];
+        return value;
+      }
+      case "union": {
+        var has=schema.has||{};
+        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,{});
+          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(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 value;
+      }
+      default: return value;
+    }
+  }
+  // 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)));
+});
+
+function parseJsonTolerant(json, schema) {
+  try {
+    return S.parseJsonOrThrow(json, schema);
+  } catch (firstErr) {
+    try {
+      return S.parseJsonOrThrow(fillMissingDefaults(schema, json), schema);
+    } catch (exn) {
+      throw firstErr;
+    }
+  }
+}
+
+let decode = parseJsonTolerant;
 
 let encode = S.reverseConvertToJsonOrThrow;
 
@@ -50,7 +105,7 @@ function toEventSchema$p(idSchema, eventSchema) {
 }
 
 function decodeEvent$p(json, idSchema, eventSchema) {
-  return S.parseJsonOrThrow(json, toEventSchema$p(idSchema, eventSchema));
+  return parseJsonTolerant(json, toEventSchema$p(idSchema, eventSchema));
 }
 
 function variantNameOfJson(json) {
@@ -97,6 +152,8 @@ export {
   contextSchema,
   statusChangeSchema,
   commandJsonSchema,
+  fillMissingDefaults,
+  parseJsonTolerant,
   decode,
   encode,
   InvalidEvent,