@reventlessdev/reventless-spec 3.0.0-alpha.96 → 3.0.0-alpha.98

package/CHANGELOG.md

@@ -3,6 +3,21 @@
 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.98 (2026-08-03)
+
+### Features
+
+* **aws:** let a deployment hand its plugins a geocoder ([143bf41](https://github.com/ReventlessDev/reventless-core/commit/143bf4137765362ce07dd42db0f4a57057da9f13))
+* **outbound:** let an outbound slice read an aggregate, and geocode addresses with it ([867e63e](https://github.com/ReventlessDev/reventless-core/commit/867e63e774ebc8b78b2b19c78645c8a12a8d06f6))
+
+
+# 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

package/package.json

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

package/src/components/OutboundTranslationSlice.res

@@ -76,6 +76,29 @@ module type Spec = {
   /** Name of the aggregate or StateChangeSlice that receives the inbound command, or None for fire-and-forget. */
   let targetName: option<string>
 
+  /**
+  Event sources this slice subscribes to, by topic key.
+
+  `[]` — the default and the historical behaviour — means this plugin's own DCB
+  event log. Naming sources explicitly subscribes to them instead: an Aggregate's
+  `Spec.name`, or a DCB source name (conventionally `"<pluginName>DcbEventLog"`),
+  matching the keys `AutomationSlice` mappings already use.
+
+  This exists because an outbound slice is the framework's one component for
+  *calling an external service and feeding the answer back*, and that job is not
+  specific to DCB-modelled entities. An Aggregate whose events should trigger an
+  outbound call had no route to one while this list was hard-wired.
+
+  Unlike `AutomationSlice`, the sources are a flat list rather than per-source
+  `Mapping` modules. An automation needs a `resolve` per source (a different
+  event completes the item depending on where it came from); an outbound item is
+  resolved by its own `translate` succeeding, so the only thing that varies per
+  source is the decode — and the one `consumedEvent` union already covers that.
+  The cost of the flat form is that two sources sharing an event-type name are
+  indistinguishable; declare only the sources whose events you mean.
+  */
+  let sourceNames: array<string>
+
   /** Optional display name of the foreign system this anti-corruption slice publishes
       to (e.g. `"EmailService"`). Drives the **external box** drawn outside the plugin
       in the Event Graph / Context Map (see docs/plans/translation-external-boxes.md).
@@ -94,8 +117,15 @@ module type Translation = {
   Collect: map an incoming event to zero or more new outbound items.
   Each item has an `id` (deduplication key) and the `outboundItem` payload.
   Returns empty array if this event is not relevant.
+
+  `~sourceId` is the id of the entity the event was published for — the envelope's
+  `id`, not part of the event payload. A DCB event usually names its own subject
+  in the payload (`OrderPlaced({orderId, …})`) and can ignore this; an Aggregate's
+  event generally does not, because the aggregate id is what addressed it in the
+  first place. Without this the outbound item for `Registered({email, address})`
+  would have no way to say *which customer* it is for.
   */
-  let collect: Spec.consumedEvent => array<(string, Spec.outboundItem)>
+  let collect: (Spec.consumedEvent, ~sourceId: string) => array<(string, Spec.outboundItem)>
 
   /**
   Translate: call the external service for a single outbound item.

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/Geocoding.res

@@ -0,0 +1,101 @@
+/**
+Turning an address into a point, and deciding whether to believe the answer.
+
+The *transport* is provider-specific — Amazon Location, a self-hosted Nominatim,
+a vendor's HTTP API — and lives with its provider. What lives here is everything
+that is the same regardless of who answers: the shape of an answer, the two ways
+a lookup can fail, and the rule for when a ranked list is confident enough to
+write a coordinate into an event log.
+
+That split matters because the confidence rule is the part that is easy to get
+wrong and expensive to get wrong twice. A caller that re-derives it — takes
+`results[0]` because the list was ranked — produces a plausible marker in the
+wrong region, drawn without an error anywhere. Deciding it once, here, is what
+stops each transport inventing its own answer.
+*/
+
+/** One candidate a geocoder returned. */
+type candidate = {
+  /** The provider's canonical rendering of the address it matched. */
+  label: string,
+  point: GeoPoint.t,
+  /**
+  How well this result matches the query, 0…1.
+
+  `None` when the provider does not score its results. That is not the same as a
+  low score and must not be read as a high one — `confidentMatch` declines it,
+  because an unscored list cannot support an unattended decision.
+  */
+  relevance: option<float>,
+}
+
+/**
+Why a lookup produced no usable point.
+
+Two constructors rather than one message because the caller's retry decision
+turns on exactly this distinction, and a `switch` is the only form of it that
+cannot be got wrong. A translator that cannot tell "no such address" from "the
+service is down" turns one outage into a permanent verdict on every address in
+flight.
+*/
+type failure =
+  | /** The provider could not be reached, or refused the call. Retry. */
+  Unavailable(string)
+  | /** The provider answered, and had nothing for this text. Do not retry. */
+  NoMatch
+
+/**
+The port a caller reaches a geocoder through.
+
+Everything above says what an answer looks like; this says how one is asked for.
+Written down as a type before anything is injected against it, so that swapping
+the implementation underneath a caller is a change of *supplier* rather than a
+change of call site: whatever eventually hands a translator its geocoder — an
+HTTP client reading an endpoint out of its environment, a provider SDK called
+directly — has to satisfy this, and the `await search(~text=…)` in the caller
+does not move.
+
+`~text` is the address as a human typed it, unnormalised. Normalising it is the
+provider's job, and its canonical rendering comes back as `candidate.label`.
+*/
+type search = (~text: string) => promise<result<array<candidate>, failure>>
+
+/** The default confidence floor. A starting point, not a finding — the first
+    real corpus of addresses is what should set it. */
+let defaultMinRelevance = 0.8
+
+/**
+The one candidate confident enough to store, or `None`.
+
+Two ways to be unsure, and both decline:
+
+- the top candidate scores below `minRelevance` — the provider matched
+  something, loosely;
+- the runner-up scores within `ambiguityMargin` of the top — the provider
+  matched several things about equally well, which is what a bare town name
+  does.
+
+`None` means "ask a human", not "no result". The candidates are still there for
+a caller that wants to show them.
+*/
+let confidentMatch = (
+  candidates: array<candidate>,
+  ~minRelevance: float=defaultMinRelevance,
+  ~ambiguityMargin: float=0.1,
+): option<candidate> =>
+  switch candidates->Array.get(0) {
+  | None => None
+  | Some(top) =>
+    switch top.relevance {
+    | None => None
+    | Some(topScore) =>
+      if topScore < minRelevance {
+        None
+      } else {
+        switch candidates->Array.get(1)->Option.flatMap(c => c.relevance) {
+        | Some(runnerUp) if topScore -. runnerUp < ambiguityMargin => None
+        | _ => Some(top)
+        }
+      }
+    }
+  }

package/src/semantic/Geocoding.res.mjs

@@ -0,0 +1,33 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+
+function confidentMatch(candidates, minRelevanceOpt, ambiguityMarginOpt) {
+  let minRelevance = minRelevanceOpt !== undefined ? minRelevanceOpt : 0.8;
+  let ambiguityMargin = ambiguityMarginOpt !== undefined ? ambiguityMarginOpt : 0.1;
+  let top = candidates[0];
+  if (top === undefined) {
+    return;
+  }
+  let topScore = top.relevance;
+  if (topScore === undefined) {
+    return;
+  }
+  if (topScore < minRelevance) {
+    return;
+  }
+  let runnerUp = Stdlib_Option.flatMap(candidates[1], c => c.relevance);
+  if (runnerUp !== undefined && topScore - runnerUp < ambiguityMargin) {
+    return;
+  } else {
+    return top;
+  }
+}
+
+let defaultMinRelevance = 0.8;
+
+export {
+  defaultMinRelevance,
+  confidentMatch,
+}
+/* No side effect */

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,11 +144,12 @@ 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
@@ -253,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,22 +61,24 @@ 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
     }
   });
 }
@@ -146,6 +148,30 @@ 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,
@@ -158,5 +184,8 @@ export {
   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
     }
   });
 }