@reventlessdev/reventless-core 3.0.0-alpha.200 → 3.0.0-alpha.202

package/CHANGELOG.md

@@ -3,6 +3,22 @@
 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.202 (2026-08-02)
+
+### Features
+
+* **core:** deploy-time offload hook seam for plugin payloads ([7f970eb](https://github.com/ReventlessDev/reventless-core/commit/7f970eb449765e781559c6596ee49dd74b9451bc))
+* **spec:** make plugin structure/apiSchemaFragment offloadable payloads ([a0391bf](https://github.com/ReventlessDev/reventless-core/commit/a0391bf26f91035460cbf90f52d105a1003414c3))
+
+
+# 3.0.0-alpha.201 (2026-08-02)
+
+### Features
+
+* **aws,core,doc:** environment-tiered CloudWatch log retention and levels ([8032023](https://github.com/ReventlessDev/reventless-core/commit/803202305a7d352484b8df5e58df03c92ca58b5f))
+* **aws,core,spec,seed-aws:** expire uploads nobody committed a reference to ([f63e84c](https://github.com/ReventlessDev/reventless-core/commit/f63e84c1a11cc350b799a6f69a2e7427cf1ea6e9))
+
+
 # 3.0.0-alpha.200 (2026-08-01)
 
 * feat(aws,core,spec)!: qualify store prefixes by plugin and refuse name collisions ([da39405](https://github.com/ReventlessDev/reventless-core/commit/da394059d9f8f981bf7adc79e2c1ce2b429e0267))

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.200",
+  "version": "3.0.0-alpha.202",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -30,20 +30,20 @@
     "uuid": "^13.0.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
+    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.0",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
     "@reventlessdev/rescript-node": "2.0.0-alpha.0",
-    "@reventlessdev/rescript-fast-csv": "2.0.0-alpha.0",
-    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.117",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.92",
+    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.0",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.119",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.94",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.59"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.60"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/adapter/Runtime/Runtime.res

@@ -200,6 +200,11 @@ type commandHandlerConfig = {
   sqsBatchSize?: int,
   ephemeralStorageMb?: int,
   logRetentionDays?: int,
+  // Minimum log level for this handler ("silent" | "error" | "warn" | "info" |
+  // "debug"), mapped onto the `LOG_LEVEL` env var the logger reads. Overrides the
+  // per-environment tier default. Transport-neutral: the in-memory platform reads
+  // it the same way via the env var.
+  logLevel?: string,
   envVars?: dict<string>,
 }
 
@@ -220,5 +225,8 @@ module CommandHandlerDefaults = {
   let timeout = 30
   let sqsBatchSize = 10
   let ephemeralStorageMb = 512
-  let logRetentionDays = 7
+  // No `logRetentionDays` / `logLevel` default here: both are resolved per
+  // environment tier by the AWS platform (`Util_LogRetention`), not by a flat
+  // framework constant. An unset field means "follow the stack's tier", which a
+  // single number could not express.
 }

package/src/adapter/Runtime/Runtime.res.mjs

@@ -48,8 +48,7 @@ let CommandHandlerDefaults = {
   memorySize: 1024,
   timeout: 30,
   sqsBatchSize: 10,
-  ephemeralStorageMb: 512,
-  logRetentionDays: 7
+  ephemeralStorageMb: 512
 };
 
 export {

package/src/admin/Platform_Admin.res

@@ -309,7 +309,7 @@ module Make = (
       })
     let eventLogEntries = Array.concat(eventLogEntriesFromAggregates, dcbResult.eventLogEntries)
     Config.hooks.subscriptionInfraHook->Option.forEach(hook =>
-      hook({allQueryDbs, allEventTopics, eventLogEntries, opts})
+      hook({pluginName: name, allQueryDbs, allEventTopics, eventLogEntries, opts})
     )
 
     let queryEngine = QueryEngineAdapter.make(allQueryDbs)

package/src/admin/Platform_Admin.res.mjs

@@ -150,6 +150,7 @@ function Make(RuntimeEnvironment) {
       }));
       let eventLogEntries = eventLogEntriesFromAggregates.concat(dcbResult.eventLogEntries);
       Stdlib_Option.forEach(Config.hooks.subscriptionInfraHook, hook => hook({
+        pluginName: Platform_Admin_Structure$ReventlessCore.pluginId,
         allQueryDbs: allQueryDbs,
         allEventTopics: aggregateEventTopics,
         eventLogEntries: eventLogEntries,

package/src/admin/Platform_AdminApi.res

@@ -89,7 +89,7 @@ let pluginStatusSubscriptionSource: GraphQL_Stitcher.subscriptionSource = {
 // (`injectAwsAuthAll(~group="Admin")`), and uploads are a regular authenticated-user
 // operation. They are added instead to the **domain** API's platform-owned base
 // (`domainBaseFragment` in the AWS/local Platform), which takes the default
-// `AllowAuthenticated` auth. See [docs/plans/upload-release-path.md] § "Which API".
+// `AllowAuthenticated` auth. See [docs/plans/done/upload-release-path.md] § "Which API".
 let uploadTypes = [
   `type Upload_Ticket {\n  uploadUrl: String!\n  storageRef: String!\n}`,
   `type Upload_ReleaseResult {\n  released: Boolean!\n  reason: String\n}`,

package/src/components/Api/StorageRefFields.res

@@ -0,0 +1,124 @@
+// Which fields of which committed events can hold a storage ref — read off the
+// declarations rather than hand-listed.
+//
+// This is the deploy-time half of the claim mechanism (see
+// [docs/plans/done/upload-pending-claim-and-expiry.md]). An uploaded object is minted
+// carrying a "pending" tag and expires while it still has one, so something has
+// to notice when an event finally references it. That something needs to know
+// three things, and a `@storageRef` declaration already says all three:
+//
+//   which events to observe   only variants with at least one declared field
+//   where the refs sit        the field name, and whether it holds one or many
+//   which store they're in    the target, qualified to `{plugin}.{store}`
+//
+// Deriving it here rather than in the claimer means the runtime carries a flat
+// lookup table and no schema machinery: the Lambda reads `{eventType → fields}`
+// and never sees a sury schema. It also means an annotation added, moved or
+// deleted changes what gets claimed on the next deploy, with nothing to keep in
+// sync by hand.
+//
+// Read the same way `Plugin_Structure` reads the same declarations — top-level
+// properties of each variant, via `StorageRef.getFieldStore`. A store nested
+// inside an object is not provisioned there and so is not claimed here: one
+// reading, consistently narrow, rather than two that could disagree about which
+// fields exist.
+
+/** One declared ref-bearing field of one event variant. */
+type refField = {
+  /** The field's name on the event's payload (`data` on the wire). */
+  field: string,
+  /** Whether the field holds one ref or an array of them. */
+  arity: Reventless.StorageRef.arity,
+  /** The store the refs live in, qualified `{plugin}.{store}` — already
+      resolved against the declaring plugin, so a reader never has to know
+      whose plugin it came from. */
+  store: string,
+}
+
+/** The ref-bearing fields of one event variant. Only variants with at least
+    one are produced, so an empty result means "this event log carries no
+    storage refs" and the caller can skip it entirely. */
+type eventRefFields = {
+  eventType: string,
+  fields: array<refField>,
+}
+
+// A variant is `{TAG: "<Name>", …fields}` (payload-less variants are a bare
+// string const and can hold nothing, so they drop out here).
+let fromVariant = (~plugin: string, variant: S.t<unknown>): option<eventRefFields> =>
+  switch variant {
+  | S.Object({properties}) =>
+    switch properties->Dict.get("TAG") {
+    | Some(String({const: ?Some(eventType)})) =>
+      let fields =
+        properties
+        ->Dict.toArray
+        ->Array.filterMap(((field, fieldSchema)) =>
+          Reventless.StorageRef.getFieldStore(fieldSchema)->Option.map(((target, arity)) => {
+            field,
+            arity,
+            // An unqualified store belongs to the declaring plugin — the same
+            // resolution `Plugin_Structure` makes, so the key the claimer looks
+            // up is the key the deploy provisioned.
+            store: target.plugin->Option.getOr(plugin) ++ "." ++ target.store,
+          })
+        )
+        ->Array.toSorted((a, b) => String.compare(a.field, b.field))
+      fields->Array.length == 0 ? None : Some({eventType, fields})
+    | _ => None
+    }
+  | _ => None
+  }
+
+/**
+The ref-bearing fields of every variant in an event log's event schema.
+
+`~plugin` is the registered name of the plugin the event log belongs to, used
+to qualify a store the annotation left unqualified.
+*/
+let fromEventSchema = (~plugin: string, eventSchema: S.t<unknown>): array<eventRefFields> =>
+  switch eventSchema {
+  | Union({anyOf}) => anyOf->Array.filterMap(v => fromVariant(~plugin, v))
+  | other => fromVariant(~plugin, other)->Option.mapOr([], e => [e])
+  }
+
+/**
+The wire form the claimer reads: `{"<eventType>": [{"field", "arity", "store"}]}`.
+
+A flat JSON object rather than a schema, because it crosses into a Lambda's
+environment: the runtime side does a dictionary lookup and a field read, and
+carries no sury dependency to do it.
+*/
+let toJson = (entries: array<eventRefFields>): JSON.t =>
+  entries
+  ->Array.map(({eventType, fields}) => (
+    eventType,
+    fields
+    ->Array.map(({field, arity, store}) =>
+      Dict.fromArray([
+        ("field", JSON.Encode.string(field)),
+        (
+          "arity",
+          JSON.Encode.string(
+            switch arity {
+            | Single => "one"
+            | Multiple => "many"
+            },
+          ),
+        ),
+        ("store", JSON.Encode.string(store)),
+      ])->JSON.Encode.object
+    )
+    ->JSON.Encode.array,
+  ))
+  ->Dict.fromArray
+  ->JSON.Encode.object
+
+/** The distinct stores an event log's declarations point at. What the claimer's
+    IAM has to cover for that log, and what a coverage check compares against
+    the set of stores the deploy actually provisioned. */
+let storesOf = (entries: array<eventRefFields>): array<string> =>
+  entries
+  ->Array.flatMap(({fields}) => fields->Array.map(({store}) => store))
+  ->Belt.Set.String.fromArray
+  ->Belt.Set.String.toArray

package/src/components/Api/StorageRefFields.res.mjs

@@ -0,0 +1,88 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+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 Belt_SetString from "@rescript/runtime/lib/es6/Belt_SetString.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
+import * as StorageRef$Reventless from "@reventlessdev/reventless-spec/src/semantic/StorageRef.res.mjs";
+
+function fromVariant(plugin, variant) {
+  if (variant.type !== "object") {
+    return;
+  }
+  let properties = variant.properties;
+  let match = properties["TAG"];
+  if (match === undefined) {
+    return;
+  }
+  if (match.type !== "string") {
+    return;
+  }
+  let eventType = match.const;
+  if (eventType === undefined) {
+    return;
+  }
+  let fields = Stdlib_Array.filterMap(Object.entries(properties), param => {
+    let field = param[0];
+    return Stdlib_Option.map(StorageRef$Reventless.getFieldStore(param[1]), param => {
+      let target = param[0];
+      return {
+        field: field,
+        arity: param[1],
+        store: Stdlib_Option.getOr(target.plugin, plugin) + "." + target.store
+      };
+    });
+  }).toSorted((a, b) => Primitive_string.compare(a.field, b.field));
+  if (fields.length === 0) {
+    return;
+  } else {
+    return {
+      eventType: eventType,
+      fields: fields
+    };
+  }
+}
+
+function fromEventSchema(plugin, eventSchema) {
+  if (eventSchema.type === "union") {
+    return Stdlib_Array.filterMap(eventSchema.anyOf, v => fromVariant(plugin, v));
+  } else {
+    return Stdlib_Option.mapOr(fromVariant(plugin, eventSchema), [], e => [e]);
+  }
+}
+
+function toJson(entries) {
+  return Object.fromEntries(entries.map(param => [
+    param.eventType,
+    param.fields.map(param => {
+      let tmp;
+      tmp = param.arity === "Single" ? "one" : "many";
+      return Object.fromEntries([
+        [
+          "field",
+          param.field
+        ],
+        [
+          "arity",
+          tmp
+        ],
+        [
+          "store",
+          param.store
+        ]
+      ]);
+    })
+  ]));
+}
+
+function storesOf(entries) {
+  return Belt_SetString.toArray(Belt_SetString.fromArray(entries.flatMap(param => param.fields.map(param => param.store))));
+}
+
+export {
+  fromVariant,
+  fromEventSchema,
+  toJson,
+  storesOf,
+}
+/* StorageRef-Reventless Not a pure module */

package/src/plugin/component/Plugin_Builder.res

@@ -738,6 +738,31 @@ module Make = (
         // so reading it inside the async callback would always yield "Domain".
         let capturedDeployTarget = Spec.hooks.deployTarget.contents
 
+        // Offload the two large pluginDefinition fields at deploy time when a
+        // provider offers an object store (AWS writes a content-addressed object
+        // and returns a reference); unset locally, so they stay Inline. Both
+        // values are concrete here, so the hook — and the object write it does —
+        // runs at graph-construction time, before the Pulumi.Output.apply below
+        // (a resource cannot be created inside .apply). Unconditional: these
+        // fields are always large enough to be worth offloading.
+        let toPayload = (value, ~schema, ~store) =>
+          switch Plugin_Helpers.offloadHook.contents {
+          | Some(hook) =>
+            Reventless.Offload.Offloaded(
+              hook(~store, ~bytes=value->S.reverseConvertToJsonStringOrThrow(schema)),
+            )
+          | None => Reventless.Offload.Inline(value)
+          }
+        let apiSchemaFragmentPayload = toPayload(
+          apiSchemaFragment,
+          ~schema=Reventless.Plugin.apiSchemaFragmentSchema,
+          ~store="pluginApiFragments",
+        )
+        let structurePayload =
+          pluginStructure->Option.map(s =>
+            toPayload(s, ~schema=Reventless.Plugin.pluginStructureSchema, ~store="pluginStructures")
+          )
+
         // DCB EventLog definition — Some when this plugin has a DcbEventLog
         // component, None otherwise. Admin's manageSubscriptions reads this to
         // provision cross-plugin SNS subscriptions from peer plugins' DCB
@@ -769,9 +794,9 @@ module Make = (
             extensions: extensionsDefinitions,
             eventCollector: eventCollectorUrn,
             extensionProtocols: [],
-            apiSchemaFragment: Some(apiSchemaFragment),
+            apiSchemaFragment: Some(apiSchemaFragmentPayload),
             apiTarget: Some(capturedDeployTarget),
-            structure: pluginStructure,
+            structure: structurePayload,
             dcbEventLog: dcbEventLogDef,
             // Business role from the deploy-time metadata registry (set via
             // registerPluginMetadata). Unset → Domain. Rides the handshake to the
@@ -888,7 +913,7 @@ module Make = (
         // Gives the AWS platform access to allQueryDbs, allEventTopics, and eventLogEntries
         // without coupling reventless-core to reventless-aws.
         Spec.hooks.subscriptionInfraHook->Option.forEach(hook =>
-          hook({allQueryDbs, allEventTopics, eventLogEntries, opts})
+          hook({pluginName: name, allQueryDbs, allEventTopics, eventLogEntries, opts})
         )
 
         module SpecificHeartbeat = Heartbeat_Builder.Make(HeartbeatRunner)

package/src/plugin/component/Plugin_Builder.res.mjs

@@ -8,6 +8,7 @@ import * as Belt_SetString from "@rescript/runtime/lib/es6/Belt_SetString.js";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
+import * as Plugin$Reventless from "@reventlessdev/reventless-spec/src/components/Plugin.res.mjs";
 import * as Logger$ReventlessCore from "../../util/Logger.res.mjs";
 import * as Plugin$ReventlessCore from "./Plugin.res.mjs";
 import * as StackReference$Pulumi from "@reventlessdev/rescript-pulumi-pulumi/src/StackReference.res.mjs";
@@ -486,6 +487,22 @@ function Make(Spec) {
           let match$3 = EventCollectorHelper.make(childName, eventTopics, opts);
           let eventCollector = match$3[0];
           let capturedDeployTarget = Spec.hooks.deployTarget.contents;
+          let toPayload = (value, schema, store) => {
+            let hook = Plugin_Helpers$ReventlessCore.offloadHook.contents;
+            if (hook !== undefined) {
+              return {
+                TAG: "Offloaded",
+                _0: hook(store, S.reverseConvertToJsonStringOrThrow(value, schema, undefined))
+              };
+            } else {
+              return {
+                TAG: "Inline",
+                _0: value
+              };
+            }
+          };
+          let apiSchemaFragmentPayload = toPayload(apiSchemaFragment, Plugin$Reventless.apiSchemaFragmentSchema, "pluginApiFragments");
+          let structurePayload = Stdlib_Option.map(pluginStructure, s => toPayload(s, Plugin$Reventless.pluginStructureSchema, "pluginStructures"));
           let dcbOutputs$1 = dcbResult.dcbEventLogOutputs;
           let dcbEventLogDef;
           if (dcbOutputs$1 !== undefined) {
@@ -509,9 +526,9 @@ function Make(Spec) {
             extensions: extensionsDefinitions,
             eventCollector: param[1],
             extensionProtocols: [],
-            apiSchemaFragment: apiSchemaFragment,
+            apiSchemaFragment: apiSchemaFragmentPayload,
             apiTarget: capturedDeployTarget,
-            structure: pluginStructure,
+            structure: structurePayload,
             dcbEventLog: param[2],
             kind: Stdlib_Option.getOr(Stdlib_Option.flatMap(Plugin_Helpers$ReventlessCore.pluginMetadataRegistry.contents, m => m.kind), "Domain")
           }));
@@ -547,6 +564,7 @@ function Make(Spec) {
           let tasksOutputs = Plugin_Helpers$ReventlessCore.createTasks(tasks, aggregatesOutputs, scheduler, schedulerRoleUrn, publishToAggregates, queryEngine, Spec.resourceNaming, componentRuntime, opts);
           let resolvers = Plugin_Helpers$ReventlessCore.createResolvers(allQueryDbs);
           Stdlib_Option.forEach(Spec.hooks.subscriptionInfraHook, hook => hook({
+            pluginName: extra$1,
             allQueryDbs: allQueryDbs,
             allEventTopics: aggregateEventTopics,
             eventLogEntries: eventLogEntries,

package/src/plugin/component/Plugin_Helpers.res

@@ -785,6 +785,27 @@ let clearOnPluginDeployed = () => {
   onPluginDeployedHook.contents = None
 }
 
+// ---------------------------------------------------------------------------
+// Deploy-time offload hook — content-addresses a large pluginDefinition field
+// to an object store and returns the reference. Set by a provider that can
+// write objects (AWS creates a BucketObject); unset on the local platform, so
+// the fields stay Inline. `bytes` is the already-serialized JSON of the value;
+// the provider hashes it, stores it at `sha256/<hash>`, and returns the ref.
+// Fired synchronously at graph-construction time (the value is concrete and a
+// resource cannot be created inside a Pulumi.Output.apply).
+// ---------------------------------------------------------------------------
+let offloadHook: ref<option<(~store: string, ~bytes: string) => Reventless.Offload.offloadedRef>> = ref(
+  None,
+)
+
+let registerOffload = (hook: (~store: string, ~bytes: string) => Reventless.Offload.offloadedRef) => {
+  offloadHook.contents = Some(hook)
+}
+
+let clearOffload = () => {
+  offloadHook.contents = None
+}
+
 // ---------------------------------------------------------------------------
 // Platform-deployed hook — fires after deployPlatform / makePlatform
 // completes, providing platform-level metadata with resolved values.
@@ -911,6 +932,11 @@ type eventQueryRegistrationParams = {
 // are assembled inside builderOutputs.  Lets the AWS platform wire StateTopic and
 // EventLogSubscription Lambdas without touching reventless-core.
 type subscriptionInfraParams = {
+  /** The plugin's registered name. Carried because infrastructure wired from
+      here can be per plugin rather than per component — and because a
+      declaration that names a store without qualifying it means "this plugin's
+      own", which is unreadable without knowing whose plugin it is. */
+  pluginName: string,
   allQueryDbs: ReventlessInfra.QueryDb.allOutputs,
   allEventTopics: dict<ReventlessInfra.EventTopic.outputs>,
   eventLogEntries: array<ReventlessInfra.Api.eventLogSchemaEntry>,

package/src/plugin/component/Plugin_Helpers.res.mjs

@@ -418,6 +418,18 @@ function clearOnPluginDeployed() {
   onPluginDeployedHook.contents = undefined;
 }
 
+let offloadHook = {
+  contents: undefined
+};
+
+function registerOffload(hook) {
+  offloadHook.contents = hook;
+}
+
+function clearOffload() {
+  offloadHook.contents = undefined;
+}
+
 let onPlatformDeployedHook = {
   contents: undefined
 };
@@ -1015,6 +1027,9 @@ export {
   onPluginDeployedHook,
   registerOnPluginDeployed,
   clearOnPluginDeployed,
+  offloadHook,
+  registerOffload,
+  clearOffload,
   onPlatformDeployedHook,
   lastPlatformDeployedInfo,
   registerOnPlatformDeployed,

package/src/plugin/component/Plugin_Structure.res

@@ -503,7 +503,11 @@ let make = (
     properties
     ->Dict.toArray
     ->Array.filterMap(((field, fieldSchema)) =>
-      Reventless.StorageRef.getStore(fieldSchema)->Option.map(target => {
+      // `getFieldStore`, not `getStore`: a `@storageRef("s") urls: array<string>`
+      // field carries the marker on its *element*, so reading the field schema
+      // directly answered `None` and the store went unprovisioned — the same
+      // silence as never having written the annotation.
+      Reventless.StorageRef.getFieldStore(fieldSchema)->Option.map(((target, _arity)) => {
         Reventless.Plugin.store: target.plugin->Option.getOr(name) ++ "." ++ target.store,
         component,
         field,

package/src/plugin/component/Plugin_Structure.res.mjs

@@ -446,7 +446,8 @@ function make(name, aggregatesOpt, readModelsOpt, stateViewSlicesOpt, stateChang
         let properties = v.properties;
         return Stdlib_Array.filterMap(Object.entries(properties), param => {
           let field = param[0];
-          return Stdlib_Option.map(StorageRef$Reventless.getStore(param[1]), target => {
+          return Stdlib_Option.map(StorageRef$Reventless.getFieldStore(param[1]), param => {
+            let target = param[0];
             let plugin = target.plugin;
             return {
               store: Stdlib_Option.getOr(target.plugin, name) + "." + target.store,

package/src/plugin/lifecycle/PluginsReadModelSpec.res

@@ -24,13 +24,15 @@ type state = {
   extensions: array<Reventless.Plugin.extensionDefinition>,
   status: status,
   statusChange: Message.statusChange,
-  apiSchemaFragment: @s.matches(Reventless.Plugin.apiSchemaFragmentOptionSchema) option<Reventless.Plugin.apiSchemaFragment>,
+  apiSchemaFragment: @s.matches(Reventless.Plugin.apiSchemaFragmentOffloadSchema)
+    option<Reventless.Offload.payload<Reventless.Plugin.apiSchemaFragment>>,
   // API target for split-API schema routing. Absent/None means "Domain" (backward compat).
   // "Platform" → excluded from DomainApi runtime schema stitching in updateApiSchema.
   apiTarget?: string,
   // Plugin structure (component metadata) — surfaced via Platform_ComponentDefinitions.
   // None for older plugins whose protocol version did not carry the field.
-  structure: @s.matches(Reventless.Plugin.pluginStructureOptionSchema) option<Reventless.Plugin.pluginStructure>,
+  structure: @s.matches(Reventless.Plugin.pluginStructureOffloadSchema)
+    option<Reventless.Offload.payload<Reventless.Plugin.pluginStructure>>,
   // DCB EventLog definition for plugins that bundle a DcbEventLog component.
   // Admin's manageSubscriptions uses this to wire cross-plugin SNS subscriptions
   // from this plugin's DCB topic → peer EventCollectors (and vice-versa). None
@@ -72,9 +74,9 @@ type queryResult = {
   extensionNames: array<string>,
   extensions: array<Reventless.Plugin.extensionDefinition>,
   status: status,
-  apiSchemaFragment: option<Reventless.Plugin.apiSchemaFragment>,
+  apiSchemaFragment: option<Reventless.Offload.payload<Reventless.Plugin.apiSchemaFragment>>,
   apiTarget?: string,
-  structure: option<Reventless.Plugin.pluginStructure>,
+  structure: option<Reventless.Offload.payload<Reventless.Plugin.pluginStructure>>,
   dcbEventLog: option<Reventless.Plugin.dcbEventLogDefinition>,
   kind: option<Reventless.Plugin.pluginKind>,
 }

package/src/plugin/lifecycle/PluginsReadModelSpec.res.mjs

@@ -23,9 +23,9 @@ let stateSchema = S.schema(s => ({
   extensions: s.m(S.array(Plugin$Reventless.extensionDefinitionSchema)),
   status: s.m(statusSchema),
   statusChange: s.m(Message$ReventlessCore.statusChangeSchema),
-  apiSchemaFragment: s.m(Plugin$Reventless.apiSchemaFragmentOptionSchema),
+  apiSchemaFragment: s.m(Plugin$Reventless.apiSchemaFragmentOffloadSchema),
   apiTarget: s.m(S.option(S.string)),
-  structure: s.m(Plugin$Reventless.pluginStructureOptionSchema),
+  structure: s.m(Plugin$Reventless.pluginStructureOffloadSchema),
   dcbEventLog: s.m(Plugin$Reventless.dcbEventLogOptionSchema),
   kind: s.m(S.option(Plugin$Reventless.pluginKindSchema)),
   otherConnectedVersions: s.m(S.array(Plugin$Reventless.versionSchema))

package/tests/api/StorageRefFieldsTest.res

@@ -0,0 +1,148 @@
+// What the claim component ever gets to see, decided here.
+//
+// `StorageRefFields.fromEventSchema` is the deploy-time reading of the
+// `@storageRef` declarations that becomes the claimer's entire input: an event
+// variant it does not produce is an event the claimer never reads a record for,
+// and a field it does not list is a ref that never gets claimed — so the object
+// keeps its pending tag and, on a store with expiry enabled, is eventually
+// deleted while something still references it.
+//
+// Which makes the interesting assertions the negative ones: what is *absent*
+// from this output is what silently rots.
+
+open JestGlobals
+
+module Fields = StorageRefFields
+
+// An event union, shaped the way sury encodes a ReScript variant: one object per
+// variant, discriminated by a `TAG` string constant.
+let variant = (~tag: string, fields: array<(string, S.t<unknown>)>): S.t<unknown> =>
+  S.object(s => {
+    let _ = s.field("TAG", S.literal(tag)->S.castToUnknown)
+    fields->Array.forEach(((name, schema)) => {
+      let _ = s.field(name, schema)
+    })
+    ()
+  })->S.castToUnknown
+
+let ref_ = (~plugin: option<string>=?, ~store: string) =>
+  Reventless.StorageRef.forStore(~plugin?, ~store)->S.castToUnknown
+
+describe("StorageRefFields.fromEventSchema", () => {
+  testSync("finds a declared single-valued ref field and qualifies its store", () => {
+    let schema = S.union([variant(~tag="ProductImageChanged", [("imageUrl", ref_(~store="productImages"))])])->S.castToUnknown
+    expect(Fields.fromEventSchema(~plugin="Catalog", schema))->toEqual([
+      {
+        Fields.eventType: "ProductImageChanged",
+        fields: [
+          {Fields.field: "imageUrl", arity: Single, store: "Catalog.productImages"},
+        ],
+      },
+    ])
+  })
+
+  // The annotation's own qualification wins: a field pointing at another
+  // plugin's store must not be re-attributed to the plugin that wrote it, or the
+  // claimer resolves the wrong bucket and refuses the ref as out-of-store.
+  testSync("a qualified declaration keeps the store it names", () => {
+    let schema =
+      S.union([
+        variant(~tag="OrderPhotoAttached", [("photo", ref_(~plugin="Catalog", ~store="productImages"))]),
+      ])->S.castToUnknown
+    expect(
+      Fields.fromEventSchema(~plugin="Ordering", schema)
+      ->Array.flatMap(e => e.fields->Array.map(f => f.store)),
+    )->toEqual(["Catalog.productImages"])
+  })
+
+  // `@storageRef` on an `array<string>` attaches the marker to the ELEMENT, so
+  // reading the field schema directly answers None. The claimer needs the arity
+  // to know whether to read one value or iterate.
+  testSync("finds a multi-valued ref field and records its arity", () => {
+    let schema =
+      S.union([
+        variant(~tag="GalleryReplaced", [("imageUrls", S.array(ref_(~store="productImages"))->S.castToUnknown)]),
+      ])->S.castToUnknown
+    expect(
+      Fields.fromEventSchema(~plugin="Catalog", schema)->Array.flatMap(e => e.fields),
+    )->toEqual([{Fields.field: "imageUrls", arity: Multiple, store: "Catalog.productImages"}])
+  })
+
+  // Narrow input by construction: a platform whose plugins declare no store
+  // provisions no claimer at all, and an event log carrying no declaration is
+  // never subscribed to.
+  testSync("a variant with no declared field is omitted entirely", () => {
+    let schema =
+      S.union([
+        variant(~tag="ProductRenamed", [("name", S.string->S.castToUnknown)]),
+        variant(~tag="ProductImageChanged", [("imageUrl", ref_(~store="productImages"))]),
+      ])->S.castToUnknown
+    expect(Fields.fromEventSchema(~plugin="Catalog", schema)->Array.map(e => e.eventType))->toEqual([
+      "ProductImageChanged",
+    ])
+  })
+
+  testSync("an event schema with no declaration anywhere yields nothing", () => {
+    let schema = S.union([variant(~tag="ProductRenamed", [("name", S.string->S.castToUnknown)])])->S.castToUnknown
+    expect(Fields.fromEventSchema(~plugin="Catalog", schema))->toEqual([])
+  })
+
+  // A string field that merely looks like a ref is not one. Declaration
+  // outranks inference everywhere else in the framework, and this is the reading
+  // that has to agree with `Plugin_Structure`'s — the claimer can only reach a
+  // store the deploy actually provisioned.
+  testSync("an unannotated string field is not treated as a ref", () => {
+    let schema =
+      S.union([variant(~tag="ProductImported", [("imageUrl", S.string->S.castToUnknown)])])->S.castToUnknown
+    expect(Fields.fromEventSchema(~plugin="Catalog", schema))->toEqual([])
+  })
+
+  testSync("a single-variant (non-union) event schema is read the same way", () => {
+    let schema = variant(~tag="ProductImageChanged", [("imageUrl", ref_(~store="productImages"))])
+    expect(Fields.fromEventSchema(~plugin="Catalog", schema)->Array.map(e => e.eventType))->toEqual([
+      "ProductImageChanged",
+    ])
+  })
+})
+
+describe("StorageRefFields.toJson", () => {
+  // The wire form crosses into a Lambda's environment, where the handler decodes
+  // it with plain JSON reads. Both ends are pinned here because a drift is
+  // silent: an unreadable entry is indistinguishable from an absent one, and an
+  // absent one means "nothing to claim".
+  testSync("emits field, arity and store per event type", () => {
+    let entries: array<Fields.eventRefFields> = [
+      {
+        eventType: "ProductImageChanged",
+        fields: [{field: "imageUrl", arity: Single, store: "Catalog.productImages"}],
+      },
+      {
+        eventType: "GalleryReplaced",
+        fields: [{field: "imageUrls", arity: Multiple, store: "Catalog.productImages"}],
+      },
+    ]
+    expect(Fields.toJson(entries)->JSON.stringify)->toBe(
+      `{"ProductImageChanged":[{"field":"imageUrl","arity":"one","store":"Catalog.productImages"}],` ++
+      `"GalleryReplaced":[{"field":"imageUrls","arity":"many","store":"Catalog.productImages"}]}`,
+    )
+  })
+})
+
+describe("StorageRefFields.storesOf", () => {
+  testSync("collects the distinct stores an event log's declarations reach", () => {
+    let entries: array<Fields.eventRefFields> = [
+      {
+        eventType: "A",
+        fields: [{field: "a", arity: Single, store: "Catalog.productImages"}],
+      },
+      {
+        eventType: "B",
+        fields: [
+          {field: "b", arity: Single, store: "Catalog.productImages"},
+          {field: "c", arity: Multiple, store: "Ordering.receipts"},
+        ],
+      },
+    ]
+    expect(Fields.storesOf(entries))->toEqual(["Catalog.productImages", "Ordering.receipts"])
+  })
+})

package/tests/api/StorageRefFieldsTest.res.mjs

@@ -0,0 +1,152 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as S from "sury/src/S.res.mjs";
+import * as StorageRef$Reventless from "@reventlessdev/reventless-spec/src/semantic/StorageRef.res.mjs";
+import * as StorageRefFields$ReventlessCore from "../../src/components/Api/StorageRefFields.res.mjs";
+
+function variant(tag, fields) {
+  return S.object(s => {
+    s.f("TAG", S.literal(tag));
+    fields.forEach(param => {
+      s.f(param[0], param[1]);
+    });
+  });
+}
+
+let ref_ = StorageRef$Reventless.forStore;
+
+globalThis.describe("StorageRefFields.fromEventSchema", () => {
+  globalThis.test("finds a declared single-valued ref field and qualifies its store", () => {
+    let schema = S.union([variant("ProductImageChanged", [[
+          "imageUrl",
+          StorageRef$Reventless.forStore(undefined, "productImages")
+        ]])]);
+    globalThis.expect(StorageRefFields$ReventlessCore.fromEventSchema("Catalog", schema)).toEqual([{
+        eventType: "ProductImageChanged",
+        fields: [{
+            field: "imageUrl",
+            arity: "Single",
+            store: "Catalog.productImages"
+          }]
+      }]);
+  });
+  globalThis.test("a qualified declaration keeps the store it names", () => {
+    let schema = S.union([variant("OrderPhotoAttached", [[
+          "photo",
+          StorageRef$Reventless.forStore("Catalog", "productImages")
+        ]])]);
+    globalThis.expect(StorageRefFields$ReventlessCore.fromEventSchema("Ordering", schema).flatMap(e => e.fields.map(f => f.store))).toEqual(["Catalog.productImages"]);
+  });
+  globalThis.test("finds a multi-valued ref field and records its arity", () => {
+    let schema = S.union([variant("GalleryReplaced", [[
+          "imageUrls",
+          S.array(StorageRef$Reventless.forStore(undefined, "productImages"))
+        ]])]);
+    globalThis.expect(StorageRefFields$ReventlessCore.fromEventSchema("Catalog", schema).flatMap(e => e.fields)).toEqual([{
+        field: "imageUrls",
+        arity: "Multiple",
+        store: "Catalog.productImages"
+      }]);
+  });
+  globalThis.test("a variant with no declared field is omitted entirely", () => {
+    let schema = S.union([
+      variant("ProductRenamed", [[
+          "name",
+          S.string
+        ]]),
+      variant("ProductImageChanged", [[
+          "imageUrl",
+          StorageRef$Reventless.forStore(undefined, "productImages")
+        ]])
+    ]);
+    globalThis.expect(StorageRefFields$ReventlessCore.fromEventSchema("Catalog", schema).map(e => e.eventType)).toEqual(["ProductImageChanged"]);
+  });
+  globalThis.test("an event schema with no declaration anywhere yields nothing", () => {
+    let schema = S.union([variant("ProductRenamed", [[
+          "name",
+          S.string
+        ]])]);
+    globalThis.expect(StorageRefFields$ReventlessCore.fromEventSchema("Catalog", schema)).toEqual([]);
+  });
+  globalThis.test("an unannotated string field is not treated as a ref", () => {
+    let schema = S.union([variant("ProductImported", [[
+          "imageUrl",
+          S.string
+        ]])]);
+    globalThis.expect(StorageRefFields$ReventlessCore.fromEventSchema("Catalog", schema)).toEqual([]);
+  });
+  globalThis.test("a single-variant (non-union) event schema is read the same way", () => {
+    let schema = variant("ProductImageChanged", [[
+        "imageUrl",
+        StorageRef$Reventless.forStore(undefined, "productImages")
+      ]]);
+    globalThis.expect(StorageRefFields$ReventlessCore.fromEventSchema("Catalog", schema).map(e => e.eventType)).toEqual(["ProductImageChanged"]);
+  });
+});
+
+globalThis.describe("StorageRefFields.toJson", () => {
+  globalThis.test("emits field, arity and store per event type", () => {
+    let entries = [
+      {
+        eventType: "ProductImageChanged",
+        fields: [{
+            field: "imageUrl",
+            arity: "Single",
+            store: "Catalog.productImages"
+          }]
+      },
+      {
+        eventType: "GalleryReplaced",
+        fields: [{
+            field: "imageUrls",
+            arity: "Multiple",
+            store: "Catalog.productImages"
+          }]
+      }
+    ];
+    globalThis.expect(JSON.stringify(StorageRefFields$ReventlessCore.toJson(entries))).toBe(`{"ProductImageChanged":[{"field":"imageUrl","arity":"one","store":"Catalog.productImages"}],"GalleryReplaced":[{"field":"imageUrls","arity":"many","store":"Catalog.productImages"}]}`);
+  });
+});
+
+globalThis.describe("StorageRefFields.storesOf", () => {
+  globalThis.test("collects the distinct stores an event log's declarations reach", () => {
+    let entries = [
+      {
+        eventType: "A",
+        fields: [{
+            field: "a",
+            arity: "Single",
+            store: "Catalog.productImages"
+          }]
+      },
+      {
+        eventType: "B",
+        fields: [
+          {
+            field: "b",
+            arity: "Single",
+            store: "Catalog.productImages"
+          },
+          {
+            field: "c",
+            arity: "Multiple",
+            store: "Ordering.receipts"
+          }
+        ]
+      }
+    ];
+    globalThis.expect(StorageRefFields$ReventlessCore.storesOf(entries)).toEqual([
+      "Catalog.productImages",
+      "Ordering.receipts"
+    ]);
+  });
+});
+
+let Fields;
+
+export {
+  Fields,
+  variant,
+  ref_,
+}
+/*  Not a pure module */

package/tests/message/MessageTest.res

@@ -109,7 +109,7 @@ describe("Message should", () => {
       extensionProtocols: [],
       apiSchemaFragment: None,
       apiTarget: None,
-      structure: Some({
+      structure: Some(Reventless.Offload.Inline({
         readModels: [],
         stateViewSlices: [],
         stateChangeSlices: [],
@@ -132,7 +132,7 @@ describe("Message should", () => {
         extensionPoints: None,
         requiredStores: None,
         requiredStoreDeclarations: None,
-      }),
+      })),
       dcbEventLog: None,
       kind: Domain,
     }
@@ -186,7 +186,8 @@ describe("Message should", () => {
         },
       )->toBe("Domain")
       expect(d.apiSchemaFragment->Option.isNone)->toBe(true)
-      let structure: Reventless.Plugin.pluginStructure = d.structure->Option.getOrThrow
+      let structure: Reventless.Plugin.pluginStructure =
+        d.structure->Option.flatMap(Reventless.Offload.getInline)->Option.getOrThrow
       let agg = structure.aggregates->Array.getUnsafe(0)
       expect(agg.events->Array.length)->toBe(0)
       expect(agg.chapter->Option.isNone)->toBe(true)

package/tests/message/MessageTest.res.mjs

@@ -2,6 +2,7 @@
 
 import * as S from "sury/src/S.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Offload$Reventless from "@reventlessdev/reventless-spec/src/semantic/Offload.res.mjs";
 import * as Message$ReventlessCore from "../../src/Message.res.mjs";
 import * as PluginSpec$ReventlessCore from "../../src/plugin/lifecycle/PluginSpec.res.mjs";
 
@@ -100,26 +101,29 @@ globalThis.describe("Message should", () => {
       apiSchemaFragment: undefined,
       apiTarget: undefined,
       structure: {
-        readModels: [],
-        stateViewSlices: [],
-        stateChangeSlices: [],
-        aggregates: [{
-            name: "Order",
-            commands: [],
-            producedEventTypes: [],
-            consumedEventTypes: [],
-            linkedViews: [],
-            consistencyRead: undefined,
-            events: [],
-            chapter: undefined
-          }],
-        automationSlices: [],
-        outboundTranslationSlices: [],
-        inboundTranslationSlices: [],
-        extensions: [],
-        extensionPoints: undefined,
-        requiredStores: undefined,
-        requiredStoreDeclarations: undefined
+        TAG: "Inline",
+        _0: {
+          readModels: [],
+          stateViewSlices: [],
+          stateChangeSlices: [],
+          aggregates: [{
+              name: "Order",
+              commands: [],
+              producedEventTypes: [],
+              consumedEventTypes: [],
+              linkedViews: [],
+              consistencyRead: undefined,
+              events: [],
+              chapter: undefined
+            }],
+          automationSlices: [],
+          outboundTranslationSlices: [],
+          inboundTranslationSlices: [],
+          extensions: [],
+          extensionPoints: undefined,
+          requiredStores: undefined,
+          requiredStoreDeclarations: undefined
+        }
       },
       dcbEventLog: undefined,
       kind: "Domain"
@@ -169,7 +173,7 @@ globalThis.describe("Message should", () => {
       tmp = match === "Domain" ? "Domain" : "other";
       globalThis.expect(tmp).toBe("Domain");
       globalThis.expect(Stdlib_Option.isNone(d$1.apiSchemaFragment)).toBe(true);
-      let structure = Stdlib_Option.getOrThrow(d$1.structure, undefined);
+      let structure = Stdlib_Option.getOrThrow(Stdlib_Option.flatMap(d$1.structure, Offload$Reventless.getInline), undefined);
       let agg = structure.aggregates[0];
       globalThis.expect(agg.events.length).toBe(0);
       globalThis.expect(Stdlib_Option.isNone(agg.chapter)).toBe(true);