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

package/CHANGELOG.md

@@ -3,6 +3,23 @@
 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.95 (2026-08-02)
+
+**Note:** Version bump only for package @reventlessdev/reventless-spec
+
+
+
+
+
+# 3.0.0-alpha.94 (2026-08-02)
+
+### Features
+
+* **spec:** add [@offload](https://github.com/offload) inline-or-reference field primitive ([a54c39c](https://github.com/ReventlessDev/reventless-core/commit/a54c39ceb45b2c0b63caffd8ad039e732a5eb95d))
+* **spec:** add Offload prepare/resolve/cachedFetch client helpers ([2855990](https://github.com/ReventlessDev/reventless-core/commit/2855990ba5cc56bd691460d3614ac666382c7fac))
+* **spec:** make plugin structure/apiSchemaFragment offloadable payloads ([a0391bf](https://github.com/ReventlessDev/reventless-core/commit/a0391bf26f91035460cbf90f52d105a1003414c3))
+
+
 # 3.0.0-alpha.93 (2026-08-02)
 
 ### Features

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.93",
+  "version": "3.0.0-alpha.95",
   "description": "Specifications for Reventless",
   "license": "Apache-2.0",
   "bin": {
@@ -21,7 +21,7 @@
     "sury": "11.0.0-alpha.4",
     "sury-ppx": "11.0.0-alpha.2",
     "yaml": "^2.8.3",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.0"
+    "@reventlessdev/rescript-node": "2.0.0-alpha.1"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/components/Plugin.res

@@ -106,7 +106,7 @@ type apiTarget = Domain | Platform
 // inside union variant payloads. js_nullable creates T | null (no undefined) which is
 // JSON-safe and passes jsonableValidation in all contexts.
 @module("sury/src/Sury.res.mjs") external _jsNullable: (S.t<'a>, unit) => S.t<option<'a>> = "js_nullable"
-let apiSchemaFragmentOptionSchema = _jsNullable(apiSchemaFragmentSchema, ())
+let apiSchemaFragmentOffloadSchema = Offload.optionSchema(~store="pluginApiFragments", apiSchemaFragmentSchema)
 let dcbEventLogOptionSchema = _jsNullable(dcbEventLogDefinitionSchema, ())
 // js_nullable creates T | null which passes sury's jsonableValidation inside union variant payloads.
 let stringOptionSchema = _jsNullable(S.string, ())
@@ -488,7 +488,7 @@ type pluginStructure = {
   option<array<requiredStoreDeclaration>>,
 }
 
-let pluginStructureOptionSchema = _jsNullable(pluginStructureSchema, ())
+let pluginStructureOffloadSchema = Offload.optionSchema(~store="pluginStructures", pluginStructureSchema)
 
 /**
 The self-description of a deployed plugin, persisted in the plugin's event store.
@@ -509,9 +509,11 @@ type pluginDefinition = {
   // Use [] when the plugin does not need version negotiation.
   extensionProtocols: array<extensionProtocol>,
   // GraphQL schema fragment contributed by this plugin (optional, set at build time).
-  // Uses @s.matches(apiSchemaFragmentOptionSchema) — js_nullable creates T | null
-  // (not T | undefined | null), which passes sury's jsonableValidation inside union variants.
-  apiSchemaFragment: @s.matches(apiSchemaFragmentOptionSchema) option<apiSchemaFragment>,
+  // Offloadable: a large SDL fragment is content-addressed to the pluginApiFragments
+  // store by the client and carried by reference; a small one stays Inline. optionSchema
+  // wraps the untagged codec in js_nullable (T | null, not T | undefined | null) so it
+  // passes jsonableValidation inside the lifecycle Message union, and marks the store.
+  apiSchemaFragment: @s.matches(apiSchemaFragmentOffloadSchema) option<Offload.payload<apiSchemaFragment>>,
   // API target for schema routing in split-API mode.
   // None/"Domain" → fragment goes to the DomainApi (default).
   // Some("Platform") → fragment goes to the PlatformApi; excluded from DomainApi runtime schema.
@@ -519,7 +521,9 @@ type pluginDefinition = {
   // which passes sury's jsonableValidation inside union variant payloads.
   apiTarget: @s.matches(stringOptionSchema) option<string>,
   // Component graph metadata — populated by makePluginDefinition; absent for older protocol versions.
-  structure: @s.matches(pluginStructureOptionSchema) option<pluginStructure>,
+  // Offloadable: the large structure is content-addressed to the pluginStructures store by
+  // the client and carried by reference; a small one stays Inline (see apiSchemaFragment).
+  structure: @s.matches(pluginStructureOffloadSchema) option<Offload.payload<pluginStructure>>,
   // DCB EventLog definition for plugins that bundle a DcbEventLog component.
   // Carries the EventTopic ARN so the admin can provision cross-plugin SNS
   // subscriptions from this plugin's DCB topic → peer EventCollectors.

package/src/components/Plugin.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as S from "sury/src/S.res.mjs";
+import * as Offload$Reventless from "../semantic/Offload.res.mjs";
 import * as SuryResMjs from "sury/src/Sury.res.mjs";
 
 let pluginKindSchema = S.union([
@@ -43,7 +44,7 @@ let apiTargetSchema = S.union([
   S.literal("Platform")
 ]);
 
-let apiSchemaFragmentOptionSchema = SuryResMjs.js_nullable(apiSchemaFragmentSchema);
+let apiSchemaFragmentOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginApiFragments", apiSchemaFragmentSchema);
 
 let dcbEventLogOptionSchema = SuryResMjs.js_nullable(dcbEventLogDefinitionSchema);
 
@@ -201,7 +202,7 @@ let pluginStructureSchema = S.schema(s => ({
   requiredStoreDeclarations: s.m(requiredStoreDeclarationArrayOptionSchema)
 }));
 
-let pluginStructureOptionSchema = SuryResMjs.js_nullable(pluginStructureSchema);
+let pluginStructureOffloadSchema = Offload$Reventless.optionSchema(undefined, "pluginStructures", pluginStructureSchema);
 
 let pluginDefinitionSchema = S.schema(s => ({
   id: s.m(S.string),
@@ -211,9 +212,9 @@ let pluginDefinitionSchema = S.schema(s => ({
   extensions: s.m(S.array(extensionDefinitionSchema)),
   eventCollector: s.m(S.string),
   extensionProtocols: s.m(S.array(extensionProtocolSchema)),
-  apiSchemaFragment: s.m(apiSchemaFragmentOptionSchema),
+  apiSchemaFragment: s.m(apiSchemaFragmentOffloadSchema),
   apiTarget: s.m(stringOptionSchema),
-  structure: s.m(pluginStructureOptionSchema),
+  structure: s.m(pluginStructureOffloadSchema),
   dcbEventLog: s.m(dcbEventLogOptionSchema),
   kind: s.m(pluginKindSchema)
 }));
@@ -232,7 +233,7 @@ export {
   extensionProtocolSchema,
   apiSchemaFragmentSchema,
   apiTargetSchema,
-  apiSchemaFragmentOptionSchema,
+  apiSchemaFragmentOffloadSchema,
   dcbEventLogOptionSchema,
   stringOptionSchema,
   stringArrayOptionSchema,
@@ -257,7 +258,7 @@ export {
   requiredStoreDeclarationSchema,
   requiredStoreDeclarationArrayOptionSchema,
   pluginStructureSchema,
-  pluginStructureOptionSchema,
+  pluginStructureOffloadSchema,
   pluginDefinitionSchema,
 }
 /* pluginKindSchema Not a pure module */

package/src/semantic/Offload.res

@@ -0,0 +1,247 @@
+/**
+A field whose large value lives in a content-addressed object store, carried by
+reference — or inline when it is small enough not to be worth a round trip.
+
+## Sibling of `StorageRef`, not the same thing
+
+`StorageRef` and `Offload` are two members of one family: both say "this field's
+value lives in an object store", both declare that store through the shared
+`Semantic.StoredIn` marker, and both are produced by a **client** that uploads
+the bytes before the command is issued — never by the framework inside `decide`.
+They differ in what the field carries:
+
+- `@storageRef` is always a reference (an origin-relative path a store minted),
+  and the reference *is* the value the reader sees (a URL it renders).
+- `@offload` is an **inline-or-reference** value. Below a size threshold the
+  value stays embedded; above it the client stores the bytes under a
+  content-addressed key and the field carries `Offloaded{store, key, hash, bytes}`.
+  A reader resolves either arm back to the value.
+
+Content addressing (the key is the SHA-256 of the bytes) makes the store write
+idempotent and deduplicating: the same value stored twice lands on the same key,
+so identical payloads across versions or tenants hold one object, not many.
+
+## The backward-compatible wire form
+
+Every event already in history stored the value **inline and unwrapped** — a
+plain record, with no variant tag. So the codec here must decode those bytes
+unchanged, which rules out sury's default tagged-union encoding (`{TAG, _0}`).
+
+Instead the codec is *untagged* and sniffs a reserved sentinel key:
+
+- an `Offloaded` value encodes as `{"$offload": {store, key, hash, bytes}}`;
+- an `Inline` value encodes as the raw value, exactly as before.
+
+On decode, a JSON object carrying the `$offload` key is an `Offloaded`; anything
+else is decoded as the inner value into `Inline`. A record field name can never
+be `$offload` (identifiers cannot start with `$`), so a legacy inline payload can
+never be mistaken for a reference, and vice versa — no migration, and a
+pre-change fixture decodes as `Inline` untouched.
+
+@example
+```rescript
+// an event/command field, optional and offloadable to the "pluginStructures" store
+structure: @s.matches(Offload.optionSchema(~store="pluginStructures", pluginStructureSchema))
+  option<Offload.payload<pluginStructure>>
+```
+*/
+
+/** The reference an offloaded value carries: which store holds it, the
+    content-addressed key, the content hash (== the key's basis), and the byte
+    length. `hash` is redundant with `key` today (`key` is `sha256/<hash>`) but
+    named so a reader can verify integrity without parsing the key. */
+@schema
+type offloadedRef = {
+  store: string,
+  key: string,
+  hash: string,
+  bytes: int,
+}
+
+/** A field's value: embedded, or a reference to bytes the client stored. */
+type payload<'a> =
+  | Inline('a)
+  | Offloaded(offloadedRef)
+
+/** `nullableAsOption` emits `T | undefined | null`, which fails
+    `jsonableValidation` inside an event union; `js_nullable` emits `T | null`,
+    which is JSON-safe there. Same reason `Plugin.res` reaches for it. */
+@module("sury/src/Sury.res.mjs")
+external _jsNullable: (S.t<'a>, unit) => S.t<option<'a>> = "js_nullable"
+
+/** The codec builds on `S.json`, which sury 11 gates behind an explicit enable.
+    Doing it here (at module load, before any `schema` call) makes the primitive
+    self-contained: importing `Offload` is enough, no consumer has to remember. */
+S.enableJson()
+
+/** The object key under which an `Offloaded` value hides. Reserved: no ReScript
+    record field encodes to a key starting with `$`, so it cannot collide with an
+    inline payload's own fields. */
+let sentinelKey = "$offload"
+
+/**
+The untagged inline-or-reference codec for a field of inner type `'a`.
+
+Parameterised by the inner value's schema because the `Inline` arm round-trips
+through it. The `Offloaded` arm round-trips through `offloadedRefSchema` under the
+sentinel key. See the module doc for why this is untagged.
+*/
+let schema = (inner: S.t<'a>): S.t<payload<'a>> => {
+  // Offloaded arm: recognised by the reserved sentinel key, strict, and tried
+  // first so an offloaded value is never mistaken for an inline one. The ref is
+  // a fixed new shape that needs no healing, so a direct json-transform is fine.
+  let offloadedArm = S.json->S.transform(s => {
+    parser: json =>
+      switch json->JSON.Decode.object->Option.flatMap(dict => dict->Dict.get(sentinelKey)) {
+      | Some(refJson) => Offloaded(refJson->S.parseJsonOrThrow(offloadedRefSchema))
+      | None => s.fail("not an offloaded reference")
+      },
+    serializer: payload =>
+      switch payload {
+      | Offloaded(ref) =>
+        Dict.fromArray([(sentinelKey, ref->S.reverseConvertToJsonOrThrow(offloadedRefSchema))])
+        ->JSON.Encode.object
+      | Inline(_) => s.fail("not an offloaded reference")
+      },
+  })
+  // Inline arm: the inner schema applied through sury's own pipeline, so it
+  // inherits whatever tolerance the surrounding decode uses — the lifecycle
+  // Message decoder heals older payloads with missing fields. This is why the
+  // codec is a union rather than one json-transform with a nested
+  // parseJsonOrThrow: a nested parse runs strict and breaks the frozen corpus.
+  let inlineArm = inner->S.transform(s => {
+    parser: value => Inline(value),
+    serializer: payload =>
+      switch payload {
+      | Inline(value) => value
+      | Offloaded(_) => s.fail("not an inline value")
+      },
+  })
+  S.union([offloadedArm, inlineArm])
+}
+
+/**
+The codec plus the `StoredIn` marker declaring which store the field's references
+live in, for a **non-optional** field. `plugin` is absent for the declaring
+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}))
+
+/**
+The codec wrapped for an **optional** field (`js_nullable`), plus the `StoredIn`
+marker. This is the common case: offloadable fields are usually optional (absent
+for older protocol versions, say). The marker sits on the outer schema, where
+`Semantic.get` reads it first.
+*/
+let optionSchema = (
+  ~plugin: option<string>=?,
+  ~store: string,
+  inner: S.t<'a>,
+): S.t<option<payload<'a>>> =>
+  _jsNullable(schema(inner), ())->Semantic.mark(
+    ~id=Semantic.Id.offload,
+    ~payload=StoredIn({plugin, store}),
+  )
+
+/** 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
+    is not yet wired) uses this. */
+let getInline = (payload: payload<'a>): option<'a> =>
+  switch payload {
+  | Inline(value) => Some(value)
+  | Offloaded(_) => None
+  }
+
+// ── Client helpers ─────────────────────────────────────────────────────────
+//
+// The producer/reader surface that makes offloading easy for a client to drive.
+// Both take their store I/O as injected transports so this module stays pure
+// and provider-agnostic: a browser passes a presigned PUT / fetch, the Node seed
+// passes a direct SDK call, a test passes an in-memory map. The plugin's own
+// deploy-time producer is the exception — it offloads Pulumi-natively (declares a
+// content-addressed object resource) rather than through `prepare`, because its
+// value is a `Pulumi.Output` and a resource cannot be created inside `.apply`.
+
+/**
+Decide inline-or-offloaded for one value and, when it is large, upload it.
+
+Serializes `value` with `schema`; if the JSON is below `threshold` it stays
+`Inline` (no round trip). Otherwise it is hashed, uploaded under the
+content-addressed key `sha256/<hash>`, and returned as `Offloaded`. Because the
+key is the content hash, re-uploading identical bytes writes the same object —
+idempotent, and the source of cross-version/cross-client dedupe.
+
+`~hash` and `~upload` are injected so this stays provider-agnostic; `~hash` must
+be a stable content hash (the same bytes must always hash the same). Size is the
+JSON string's length in characters — a close proxy for byte length on the
+mostly-ASCII JSON these payloads are, and only ever used for the threshold cut.
+*/
+let prepare = (
+  value: 'a,
+  ~schema: S.t<'a>,
+  ~store: string,
+  ~threshold: int,
+  ~hash: string => string,
+  ~upload: (~key: string, ~bytes: string) => promise<unit>,
+): promise<payload<'a>> => {
+  let bytes = value->S.reverseConvertToJsonStringOrThrow(schema)
+  if bytes->String.length < threshold {
+    Promise.resolve(Inline(value))
+  } else {
+    let digest = hash(bytes)
+    let key = "sha256/" ++ digest
+    upload(~key, ~bytes)->Promise.then(() =>
+      Promise.resolve(Offloaded({store, key, hash: digest, bytes: bytes->String.length}))
+    )
+  }
+}
+
+/**
+Resolve a payload back to its value: `Inline` directly, `Offloaded` by fetching
+the object's bytes (via the injected `~fetch`) and decoding with `schema`.
+
+Offloaded objects are written by current code, so their bytes decode strictly —
+unlike the inline arm of the wire codec, which heals older event payloads.
+*/
+let resolve = (payload: payload<'a>, ~schema: S.t<'a>, ~fetch: string => promise<string>): promise<
+  'a,
+> =>
+  switch payload {
+  | Inline(value) => Promise.resolve(value)
+  | Offloaded({key}) =>
+    fetch(key)->Promise.then(bytes => Promise.resolve(bytes->S.parseJsonStringOrThrow(schema)))
+  }
+
+/**
+Wrap a `~fetch` so each content-addressed key is fetched at most once per process.
+
+Keys are immutable (they are content hashes), so a fetched object can be cached
+forever — every replay/projection that references the same hash reuses it, and
+concurrent resolves of the same key share the one in-flight promise.
+*/
+let cachedFetch = (fetch: string => promise<string>): (string => promise<string>) => {
+  let cache: dict<promise<string>> = Dict.make()
+  key =>
+    switch cache->Dict.get(key) {
+    | Some(inflight) => inflight
+    | None =>
+      let inflight = fetch(key)
+      cache->Dict.set(key, inflight)
+      inflight
+    }
+}
+
+/** The store an `@offload` field declares, if any — the read side of the marker,
+    used by provisioning to know the field requires this store to exist. Distinct
+    from `StorageRef.getStore` by the semantic id, so the two families stay
+    separable (offload objects are content-addressed and durable up front; they
+    must not be swept by the pending-upload claimer). */
+let getStore = (schema: S.t<'a>): option<Semantic.storeTarget> =>
+  switch Semantic.get(schema) {
+  | Some({id, payload: StoredIn(target)}) if id == Semantic.Id.offload => Some(target)
+  | _ => None
+  }

package/src/semantic/Offload.res.mjs

@@ -0,0 +1,157 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as Semantic$Reventless from "./Semantic.res.mjs";
+import * as SuryResMjs from "sury/src/Sury.res.mjs";
+
+let offloadedRefSchema = S.schema(s => ({
+  store: s.m(S.string),
+  key: s.m(S.string),
+  hash: s.m(S.string),
+  bytes: s.m(S.int)
+}));
+
+S.enableJson();
+
+let sentinelKey = "$offload";
+
+function schema(inner) {
+  let offloadedArm = S.transform(S.json, s => ({
+    p: json => {
+      let refJson = Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(json), dict => dict[sentinelKey]);
+      if (refJson !== undefined) {
+        return {
+          TAG: "Offloaded",
+          _0: S.parseJsonOrThrow(refJson, offloadedRefSchema)
+        };
+      } else {
+        return s.fail("not an offloaded reference", undefined);
+      }
+    },
+    s: payload => {
+      if (payload.TAG === "Inline") {
+        return s.fail("not an offloaded reference", undefined);
+      } else {
+        return Object.fromEntries([[
+            sentinelKey,
+            S.reverseConvertToJsonOrThrow(payload._0, offloadedRefSchema)
+          ]]);
+      }
+    }
+  }));
+  let inlineArm = S.transform(inner, s => ({
+    p: value => ({
+      TAG: "Inline",
+      _0: value
+    }),
+    s: payload => {
+      if (payload.TAG === "Inline") {
+        return payload._0;
+      } else {
+        return s.fail("not an inline value", undefined);
+      }
+    }
+  }));
+  return S.union([
+    offloadedArm,
+    inlineArm
+  ]);
+}
+
+function forStore(plugin, store, inner) {
+  return Semantic$Reventless.mark(schema(inner), Semantic$Reventless.Id.offload, {
+    TAG: "StoredIn",
+    _0: {
+      plugin: plugin,
+      store: store
+    }
+  });
+}
+
+function optionSchema(plugin, store, inner) {
+  return Semantic$Reventless.mark(SuryResMjs.js_nullable(schema(inner)), Semantic$Reventless.Id.offload, {
+    TAG: "StoredIn",
+    _0: {
+      plugin: plugin,
+      store: store
+    }
+  });
+}
+
+function getInline(payload) {
+  if (payload.TAG === "Inline") {
+    return Primitive_option.some(payload._0);
+  }
+}
+
+function prepare(value, schema, store, threshold, hash, upload) {
+  let bytes = S.reverseConvertToJsonStringOrThrow(value, schema, undefined);
+  if (bytes.length < threshold) {
+    return Promise.resolve({
+      TAG: "Inline",
+      _0: value
+    });
+  }
+  let digest = hash(bytes);
+  let key = "sha256/" + digest;
+  return upload(key, bytes).then(() => Promise.resolve({
+    TAG: "Offloaded",
+    _0: {
+      store: store,
+      key: key,
+      hash: digest,
+      bytes: bytes.length
+    }
+  }));
+}
+
+function resolve(payload, schema, fetch) {
+  if (payload.TAG === "Inline") {
+    return Promise.resolve(payload._0);
+  } else {
+    return fetch(payload._0.key).then(bytes => Promise.resolve(S.parseJsonStringOrThrow(bytes, schema)));
+  }
+}
+
+function cachedFetch(fetch) {
+  let cache = {};
+  return key => {
+    let inflight = cache[key];
+    if (inflight !== undefined) {
+      return inflight;
+    }
+    let inflight$1 = fetch(key);
+    cache[key] = inflight$1;
+    return inflight$1;
+  };
+}
+
+function getStore(schema) {
+  let match = Semantic$Reventless.get(schema);
+  if (match === undefined) {
+    return;
+  }
+  let target = match.payload;
+  if (typeof target !== "object" || target.TAG === "ReferenceTo" || match.id !== Semantic$Reventless.Id.offload) {
+    return;
+  } else {
+    return target._0;
+  }
+}
+
+export {
+  offloadedRefSchema,
+  sentinelKey,
+  schema,
+  forStore,
+  optionSchema,
+  getInline,
+  prepare,
+  resolve,
+  cachedFetch,
+  getStore,
+}
+/* offloadedRefSchema Not a pure module */

package/src/semantic/Semantic.res

@@ -48,6 +48,11 @@ module Id = {
   let dateTime = "dateTime"
   let reference = "reference"
   let storageRef = "storageRef"
+  // A field whose large value the client stored in a content-addressed object
+  // store and carries by reference (inline below a size threshold). Sibling of
+  // `storageRef`: same `StoredIn` store declaration, but an inline-or-reference
+  // value rather than an always-a-ref path string.
+  let offload = "offload"
 
   // The branded scalars. Each refines a `string` or a number without changing
   // its shape, so a field gains one of these without anything stored changing.

package/src/semantic/Semantic.res.mjs

@@ -6,6 +6,7 @@ let Id = {
   dateTime: "dateTime",
   reference: "reference",
   storageRef: "storageRef",
+  offload: "offload",
   email: "email",
   phone: "phone",
   url: "url",