@reventlessdev/reventless-spec 3.0.0-alpha.128 → 3.0.0-alpha.130

package/src/types/Message.res

@@ -141,22 +141,23 @@ type commandJson = {
 
 // ── 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.
+// over time — `kind`, `chapter`, `events`, `extensionPoints`, `apiExposed`, … A field
+// that is not optional is *present-required on decode*, so ONE message persisted before
+// it 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
+// schema expects: `null` for a `T | null` union (→ `None`), nothing at all for an
+// `option` (a union admitting `undefined` — also `None`), `[]` for a missing array, the
 // 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
+// nested object, and a zero value for a missing scalar. The `undefined` arm mirrors the
+// `null` one and must precede the enum/object guesses below it: an absent `option<enum>`
+// would otherwise heal to that enum's first variant and an absent `option<record>` to a
+// filled `{}`, turning `None` into a `Some` of an invented value. 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
@@ -229,6 +230,7 @@ let fillMissingDefaults: (S.t<'a>, JSON.t, array<string>) => JSON.t = %raw(`func
         var has=schema.has||{};
         if(value===undefined){
           if(has.null) return null;
+          if(has.undefined) return undefined;
           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,{},path);
           return undefined;
@@ -273,7 +275,7 @@ let parseJsonTolerant = (json, schema) =>
             ->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.`,
+          `written; the value above is fabricated, not recovered. Prefer an optional field.`,
         )
       }
       value

package/src/types/Message.res.mjs

@@ -87,6 +87,7 @@ let fillMissingDefaults = (function(schema, json, scalarFills){
         var has=schema.has||{};
         if(value===undefined){
           if(has.null) return null;
+          if(has.undefined) return undefined;
           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,{},path);
           return undefined;
@@ -126,7 +127,7 @@ function parseJsonTolerant(json, schema) {
       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.`);
+      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 an optional field.`);
     }
     return value;
   }

package/src/types/Transition.res

@@ -36,10 +36,23 @@
 // plugin structure is assembled, and what leaves is the pair of names the
 // structure already carried.
 type t<'state> =
-  /** No edge declared: legal in every state, moves the row nowhere. The honest
-      answer for a report a slice publishes, which must not be refused because
-      the row moved on while the report was in flight. */
+  /** Legal in every state, and moves the row nowhere. The honest answer for a
+      report a slice publishes, which must not be refused because the row moved
+      on while the report was in flight. A claim, not an omission — see
+      `Undeclared`, which is the omission. */
   | Unrestricted
+  /** The spec wrote no switch, and the ppx injected this. Never write it: say
+      `Unrestricted` if you mean the command is legal everywhere.
+
+      It reads exactly like `Unrestricted` — no from-set, no target — everywhere
+      but one place, and that place is why it exists. The harvested lifecycle
+      model may answer for silence; it may not narrow a claim. A corpus only
+      covers the states somebody wrote a scenario for, so letting it answer for
+      `Unrestricted` would shrink "legal in every state" down to an accident of
+      coverage, and the command would quietly stop being offered on the rows
+      nobody tested. With the two spelled apart, that shrinkage cannot happen and
+      a scenario that genuinely refutes the claim is a contradiction instead. */
+  | Undeclared
   /** Brings the row into existence, so there is no state it could come from.
       Distinct from `Unrestricted`, which draws no edge at all. */
   | Creates('state)
@@ -54,6 +67,7 @@ type t<'state> =
     tells apart. */
 let allowedStates = (transition: t<'state>): option<array<'state>> =>
   switch transition {
+  | Undeclared
   | Unrestricted
   | Creates(_) => None
   | Guards(states)
@@ -63,8 +77,21 @@ let allowedStates = (transition: t<'state>): option<array<'state>> =>
 /** The state the command's handler writes, or `None` for one that moves nothing. */
 let targetState = (transition: t<'state>): option<'state> =>
   switch transition {
+  | Undeclared
   | Unrestricted
   | Guards(_) => None
   | Creates(state)
   | Moves(_, state) => Some(state)
   }
+
+/** Whether the command is claimed legal in every state, as opposed to nothing
+    being claimed at all. The two erase to the same pair of `None`s above, so this
+    is the only thing that can tell a reader of the erased form which it holds. */
+let isUnrestricted = (transition: t<'state>): bool =>
+  switch transition {
+  | Unrestricted => true
+  | Undeclared
+  | Creates(_)
+  | Guards(_)
+  | Moves(_, _) => false
+  }

package/src/types/Transition.res.mjs

@@ -7,11 +7,11 @@ function allowedStates(transition) {
     return;
   }
   switch (transition.TAG) {
-    case "Creates" :
-      return;
     case "Guards" :
     case "Moves" :
       return transition._0;
+    default:
+      return;
   }
 }
 
@@ -22,15 +22,24 @@ function targetState(transition) {
   switch (transition.TAG) {
     case "Creates" :
       return Primitive_option.some(transition._0);
-    case "Guards" :
-      return;
     case "Moves" :
       return Primitive_option.some(transition._1);
+    default:
+      return;
+  }
+}
+
+function isUnrestricted(transition) {
+  if (typeof transition !== "object") {
+    return transition === "Unrestricted";
+  } else {
+    return false;
   }
 }
 
 export {
   allowedStates,
   targetState,
+  isUnrestricted,
 }
 /* No side effect */