@reventlessdev/reventless-spec 3.0.0-alpha.95 → 3.0.0-alpha.97

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.97 (2026-08-02)
+
+### Features
+
+* **ppx:** add [@offload](https://github.com/offload) field shorthand with per-field threshold ([3d5e3b5](https://github.com/ReventlessDev/reventless-core/commit/3d5e3b5da5010547ce0eaf7d94d660daec67feed))
+
+
+# 3.0.0-alpha.96 (2026-08-02)
+
+### Bug Fixes
+
+* **spec:** add Offload.toJson to serialize a payload as untagged wire JSON ([6a4c60f](https://github.com/ReventlessDev/reventless-core/commit/6a4c60f606dd6657082981acf75a90070099bf29))
+
+
 # 3.0.0-alpha.95 (2026-08-02)
 
 **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.95",
+  "version": "3.0.0-alpha.97",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {

package/src/components/Plugin.res.mjs

@@ -44,7 +44,7 @@ let apiTargetSchema = S.union([
   S.literal("Platform")
 ]);
 
-let apiSchemaFragmentOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginApiFragments", apiSchemaFragmentSchema);
+let apiSchemaFragmentOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginApiFragments", undefined, apiSchemaFragmentSchema);
 
 let dcbEventLogOptionSchema = SuryResMjs.js_nullable(dcbEventLogDefinitionSchema);
 
@@ -202,7 +202,7 @@ let pluginStructureSchema = S.schema(s => ({
   requiredStoreDeclarations: s.m(requiredStoreDeclarationArrayOptionSchema)
 }));
 
-let pluginStructureOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginStructures", pluginStructureSchema);
+let pluginStructureOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginStructures", undefined, pluginStructureSchema);
 
 let pluginDefinitionSchema = S.schema(s => ({
   id: s.m(S.string),

package/src/semantic/Offload.res

@@ -127,8 +127,13 @@ plugin's own store; qualify as `"<plugin>.<store>"` to point at another's.
 
 Prefer the `@offload("<store>")` ppx shorthand over calling this by hand.
 */
-let forStore = (~plugin: option<string>=?, ~store: string, inner: S.t<'a>): S.t<payload<'a>> =>
-  schema(inner)->Semantic.mark(~id=Semantic.Id.offload, ~payload=StoredIn({plugin, store}))
+let forStore = (
+  ~plugin: option<string>=?,
+  ~store: string,
+  ~threshold: option<int>=?,
+  inner: S.t<'a>,
+): S.t<payload<'a>> =>
+  schema(inner)->Semantic.mark(~id=Semantic.Id.offload, ~payload=StoredIn({plugin, store, threshold}))
 
 /**
 The codec wrapped for an **optional** field (`js_nullable`), plus the `StoredIn`
@@ -139,13 +144,22 @@ for older protocol versions, say). The marker sits on the outer schema, where
 let optionSchema = (
   ~plugin: option<string>=?,
   ~store: string,
+  ~threshold: option<int>=?,
   inner: S.t<'a>,
 ): S.t<option<payload<'a>>> =>
   _jsNullable(schema(inner), ())->Semantic.mark(
     ~id=Semantic.Id.offload,
-    ~payload=StoredIn({plugin, store}),
+    ~payload=StoredIn({plugin, store, threshold}),
   )
 
+/** Serialize a payload to its **untagged** wire JSON: `Inline` becomes the bare
+    inner value's JSON, `Offloaded` becomes `{"$offload": {...}}`. Used where a
+    payload must be stored as a plain JSON blob rather than the ReScript variant —
+    e.g. the plugin read model, whose DynamoDB write path marshals the raw value
+    and would otherwise persist the variant's runtime `{TAG, _0}` shape. */
+let toJson = (inner: S.t<'a>, payload: payload<'a>): JSON.t =>
+  payload->S.reverseConvertToJsonOrThrow(schema(inner))
+
 /** The inline value, if this payload is `Inline`. `None` for `Offloaded` — a
     caller that must handle both arms uses `resolve` (async, fetches the ref); a
     caller that only ever sees inline values (a test, or a path where offloading
@@ -245,3 +259,36 @@ let getStore = (schema: S.t<'a>): option<Semantic.storeTarget> =>
   | Some({id, payload: StoredIn(target)}) if id == Semantic.Id.offload => Some(target)
   | _ => None
   }
+
+/** The framework-default inline-vs-offloaded byte cut, used when neither the field
+    marker nor the platform declares one. Retuning any level is safe: both arms of
+    the codec read back to identical bytes, so the threshold only decides how
+    *future* values are split — no wire change, no re-encoding, existing events
+    stay valid. */
+let defaultThreshold = 8192
+
+/** The per-field threshold an `@offload` field declares, if any — the top of the
+    precedence chain (`@offload({..., threshold})`). `None` when the field left it
+    unset, which defers to the platform default and then {!defaultThreshold}. */
+let getThreshold = (schema: S.t<'a>): option<int> =>
+  switch Semantic.get(schema) {
+  | Some({id, payload: StoredIn({threshold})}) if id == Semantic.Id.offload => threshold
+  | _ => None
+  }
+
+/**
+The effective threshold for a field, resolving the precedence chain most-specific
+first: the per-field `@offload({threshold})` (read from the field's schema), then
+the platform config default (`~platformDefault`, e.g. `MakeWithConfig`'s
+`offloadThreshold`), then {!defaultThreshold}.
+
+A client drives an offloadable field by reading its field schema, calling this to
+get the cut, and passing the result as {!prepare}'s `~threshold`. `prepare` stays
+threshold-explicit (it holds the *value* schema, not the field schema that carries
+the marker), so this is the seam that turns the declaration into a number.
+*/
+let effectiveThreshold = (schema: S.t<'a>, ~platformDefault: option<int>=?, ()): int =>
+  switch getThreshold(schema) {
+  | Some(t) => t
+  | None => platformDefault->Option.getOr(defaultThreshold)
+  }

package/src/semantic/Offload.res.mjs

@@ -61,26 +61,32 @@ function schema(inner) {
   ]);
 }
 
-function forStore(plugin, store, inner) {
+function forStore(plugin, store, threshold, inner) {
   return Semantic$Reventless.mark(schema(inner), Semantic$Reventless.Id.offload, {
     TAG: "StoredIn",
     _0: {
       plugin: plugin,
-      store: store
+      store: store,
+      threshold: threshold
     }
   });
 }
 
-function optionSchema(plugin, store, inner) {
+function optionSchema(plugin, store, threshold, inner) {
   return Semantic$Reventless.mark(SuryResMjs.js_nullable(schema(inner)), Semantic$Reventless.Id.offload, {
     TAG: "StoredIn",
     _0: {
       plugin: plugin,
-      store: store
+      store: store,
+      threshold: threshold
     }
   });
 }
 
+function toJson(inner, payload) {
+  return S.reverseConvertToJsonOrThrow(payload, schema(inner));
+}
+
 function getInline(payload) {
   if (payload.TAG === "Inline") {
     return Primitive_option.some(payload._0);
@@ -142,16 +148,44 @@ function getStore(schema) {
   }
 }
 
+function getThreshold(schema) {
+  let match = Semantic$Reventless.get(schema);
+  if (match === undefined) {
+    return;
+  }
+  let match$1 = match.payload;
+  if (typeof match$1 !== "object" || match$1.TAG === "ReferenceTo" || match.id !== Semantic$Reventless.Id.offload) {
+    return;
+  } else {
+    return match$1._0.threshold;
+  }
+}
+
+function effectiveThreshold(schema, platformDefault, param) {
+  let t = getThreshold(schema);
+  if (t !== undefined) {
+    return t;
+  } else {
+    return Stdlib_Option.getOr(platformDefault, 8192);
+  }
+}
+
+let defaultThreshold = 8192;
+
 export {
   offloadedRefSchema,
   sentinelKey,
   schema,
   forStore,
   optionSchema,
+  toJson,
   getInline,
   prepare,
   resolve,
   cachedFetch,
   getStore,
+  defaultThreshold,
+  getThreshold,
+  effectiveThreshold,
 }
 /* offloadedRefSchema Not a pure module */

package/src/semantic/Semantic.res

@@ -24,9 +24,12 @@ that can fail at runtime.
 /** Which entity a reference field points to. */
 type referenceTarget = {entity: string, plugin: option<string>}
 
-/** Which object store a storage-ref field's value lives in. `plugin` is absent
-    when the store belongs to the declaring plugin, which is the common case. */
-type storeTarget = {plugin: option<string>, store: string}
+/** Which object store a storage-ref / offload field's value lives in. `plugin` is
+    absent when the store belongs to the declaring plugin, which is the common
+    case. `threshold` is the per-field inline-vs-offloaded byte cut an `@offload`
+    field may declare (`None` for `@storageRef`, which is always a ref, and for
+    `@offload` fields that leave it to the platform default). */
+type storeTarget = {plugin: option<string>, store: string, threshold: option<int>}
 
 /** Per-semantic detail, for the semantics that carry any. */
 type payload =

package/src/semantic/StorageRef.res

@@ -114,7 +114,7 @@ let forStore = (~plugin: option<string>=?, ~store: string): S.t<t> =>
       }
     }
   )
-  ->Semantic.mark(~id=Semantic.Id.storageRef, ~payload=StoredIn({plugin, store}))
+  ->Semantic.mark(~id=Semantic.Id.storageRef, ~payload=StoredIn({plugin, store, threshold: None}))
 
 /** The store a field's schema declares its refs live in, if any. */
 let getStore = (schema: S.t<'a>): option<Semantic.storeTarget> =>

package/src/semantic/StorageRef.res.mjs

@@ -59,7 +59,8 @@ function forStore(plugin, store) {
     TAG: "StoredIn",
     _0: {
       plugin: plugin,
-      store: store
+      store: store,
+      threshold: undefined
     }
   });
 }