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

package/CHANGELOG.md

@@ -3,6 +3,14 @@
 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-spec",
-  "version": "3.0.0-alpha.97",
+  "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/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 */