@reventlessdev/reventless-core 3.0.0-alpha.204 → 3.0.0-alpha.206

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.206 (2026-08-03)
+
+### Features
+
+* **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.205 (2026-08-02)
+
+**Note:** Version bump only for package @reventlessdev/reventless-core
+
+
+
+
+
 # 3.0.0-alpha.204 (2026-08-02)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-core",
-  "version": "3.0.0-alpha.204",
+  "version": "3.0.0-alpha.206",
   "description": "Core package for Reventless framework",
   "license": "Apache-2.0",
   "jest": {
@@ -33,17 +33,17 @@
     "@reventlessdev/rescript-hash-object": "1.2.0-alpha.14",
     "@reventlessdev/rescript-node": "2.0.0-alpha.1",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
-    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.1",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
-    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.121",
+    "@reventlessdev/rescript-ssh2": "2.0.0-alpha.1",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.96"
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.123",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.98",
+    "@reventlessdev/rescript-uuid": "2.0.0-alpha.0"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.60"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.62"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/components/Dcb/Dcb_Builder.res

@@ -621,6 +621,9 @@ module Make = (
           ->Array.map((module(OTS: OutboundTranslationSlice.T)) => {
             let ots = OTS.make(
               ~dcbEventLog,
+              // Same dict the AutomationSlices get, so an outbound slice can
+              // name an Aggregate source by its Spec.name.
+              ~allEventTopics,
               ~publishJsons,
               ~runtime=?componentRuntime->Dict.get(OTS.Spec.name),
               ~opts,

package/src/components/Dcb/Dcb_Builder.res.mjs

@@ -329,7 +329,7 @@ function Make(DcbEventLogStorage) {
         ];
       }));
       let outboundTranslationSlicesOutputs = Object.fromEntries(outboundTranslationSlices.map(OTS => {
-        let ots = OTS.make(dcbEventLog, publishJsons, componentRuntime[OTS.Spec.name], opts);
+        let ots = OTS.make(dcbEventLog, allEventTopics, publishJsons, componentRuntime[OTS.Spec.name], opts);
         return [
           OTS.Spec.name,
           Component$ReventlessCore.outputs(ots)

package/src/components/OutboundTranslationSlice/OutboundTranslationSlice.res

@@ -29,6 +29,7 @@ module type T = {
 
   let make: (
     ~dcbEventLog: DcbEventLog.component,
+    ~allEventTopics: EventTopic.allOutputs=?,
     ~publishJsons: Pulumi.Output.t<CommandTopic.publishJsons>,
     ~runtime: ReventlessInfra.RuntimeHints.t=?,
     ~opts: Pulumi.ComponentResource.options=?,

package/src/components/OutboundTranslationSlice/OutboundTranslationSlice_Builder.res

@@ -65,7 +65,14 @@ module Make = (
       })
     }
 
-    let construct = (~dcbEventLog: DcbEventLog.component, ~publishJsons, ~runtime, self, _name) => {
+    let construct = (
+      ~dcbEventLog: DcbEventLog.component,
+      ~allEventTopics: EventTopic.allOutputs,
+      ~publishJsons,
+      ~runtime,
+      self,
+      _name,
+    ) => {
       let opts = {Pulumi.ComponentResource.parent: self->Component.toPulumiResource}
       let memorySize = ReventlessInfra.RuntimeHints.resolveMemory(runtime, ~default=1024)
       let timeout = ReventlessInfra.RuntimeHints.resolveTimeout(runtime, ~default=30)
@@ -86,7 +93,38 @@ module Make = (
       // once per slice instead of collapsing to a single entry.
       let dcbEventLogName =
         (dcbEventLog->Component.toPulumiResource).name->Option.getOr("") ++ "DcbEventLog"
-      let allEventTopics = Dict.fromArray([(dcbEventLogName, dcbEventTopicOutputs)])
+
+      // Everything this slice could subscribe to: the plugin-wide dict the
+      // caller passed, plus its own DCB log — which is always reachable whether
+      // or not a dict was supplied, so the `[]` default works in tests and
+      // fixtures that construct a slice with nothing else around it.
+      let availableTopics = allEventTopics->Dict.copy
+      availableTopics->Dict.set(dcbEventLogName, dcbEventTopicOutputs)
+
+      let sourceNames = switch Spec.sourceNames {
+      | [] => [dcbEventLogName]
+      | declared => declared
+      }
+
+      // Fail-fast, mirroring AutomationSlice_Builder: an unknown source name
+      // would otherwise be dropped by `EventTopic.filter`, leaving the collector
+      // subscribed to nothing. That surfaces much later as "the TODO list never
+      // populates", with nothing pointing at the typo that caused it.
+      sourceNames->Array.forEach(sourceName =>
+        if !(availableTopics->Dict.has(sourceName)) {
+          let availableNames =
+            availableTopics->Dict.keysToArray->Array.toSorted(String.compare)->Array.join(", ")
+          JsError.throwWithMessage(
+            `OutboundTranslationSlice "${Spec.name}" declares sourceName "${sourceName}", ` ++
+            `but no EventTopic with that key exists. ` ++
+            `Available source names: [${availableNames}]. ` ++
+            `A source is an Aggregate Spec.name or a DCB source name ` ++
+            `(typically "<pluginName>DcbEventLog"); \`[]\` means this plugin's own DCB log.`,
+          )
+        }
+      )
+
+      let eventTopics = availableTopics->EventTopic.filter(sourceNames->Belt.Set.String.fromArray)
 
       // Build the EventCollector inside an Output.all2 so both `queryDbOps` and
       // `publishJsonsFn` are captured in the same closure. The jsonEventsHandler
@@ -99,7 +137,7 @@ module Make = (
         ->Pulumi.Output.apply(((queryDbOps, publishJsonsFn)) => {
           let ec = SpecificEventCollector.make(
             ~name=Spec.name,
-            ~eventTopics=allEventTopics,
+            ~eventTopics,
             ~owner={kind: ComponentType.OutboundTranslationSlice, name: Spec.name},
             ~opts,
           )
@@ -114,14 +152,21 @@ module Make = (
                   // `event` payload — TAG + fields at the top level — not the
                   // wrapper. Splitting the wrapper yields eventType "Unknown",
                   // which DcbDecode drops without warning.
+                  let envelope = json->JSON.Decode.object
                   let rawEvent =
-                    json
-                    ->JSON.Decode.object
-                    ->Option.flatMap(d => d->Dict.get("event"))
-                    ->Option.getOr(json)
+                    envelope->Option.flatMap(d => d->Dict.get("event"))->Option.getOr(json)
+                  // The entity the event was published for. An Aggregate's event
+                  // payload does not repeat its own id, so without carrying this
+                  // out of the envelope `collect` cannot name the subject of the
+                  // outbound item it creates.
+                  let sourceId =
+                    envelope
+                    ->Option.flatMap(d => d->Dict.get("id"))
+                    ->Option.flatMap(JSON.Decode.string)
+                    ->Option.getOr("")
                   let (eventType, dataDict) = rawEvent->Message.splitMessage
                   switch decoder.decode(~eventType, ~data=dataDict) {
-                  | Some(event) => [event]
+                  | Some(event) => [(sourceId, event)]
                   | None => []
                   }
                 },
@@ -164,7 +209,7 @@ module Make = (
           let resources = (queryDb->Component.outputs).resources
           ec->EventCollectorRuntimeBuilder.forEventCollector(
             ~handler,
-            ~eventTopics=allEventTopics,
+            ~eventTopics,
             ~resources,
             ~memorySize,
             ~timeout,
@@ -184,8 +229,12 @@ module Make = (
         }),
       )
 
+      // Aggregated across every subscribed topic, as AutomationSlice does — with
+      // more than one source, the DCB log's resources alone are an undercount.
+      let aggregatedResources =
+        eventTopics->Dict.valuesToArray->Array.flatMap((t: EventTopic.outputs) => t.resources)
       let outputs: OutboundTranslationSlice.outputs = {
-        resources: dcbEventTopicOutputs.resources,
+        resources: aggregatedResources,
         queryDb: queryDb->Component.outputs,
       }
       self->Component.setOutputs(outputs)
@@ -193,6 +242,10 @@ module Make = (
 
     let make = (
       ~dcbEventLog,
+      // Defaulted so every existing call site — fixtures included — keeps
+      // compiling; a slice with no declared sources needs nothing but its own
+      // DCB log, which `construct` adds regardless.
+      ~allEventTopics=Dict.make(),
       ~publishJsons,
       ~runtime=?,
       ~opts=?,
@@ -200,7 +253,7 @@ module Make = (
       Component.make(
         ~componentType=OutboundTranslationSlice.componentType->ComponentType.toString,
         ~name=Spec.name,
-        ~construct=construct(~dcbEventLog, ~publishJsons, ~runtime, ...),
+        ~construct=construct(~dcbEventLog, ~allEventTopics, ~publishJsons, ~runtime, ...),
         ~opts,
       )
   }

package/src/components/OutboundTranslationSlice/OutboundTranslationSlice_Builder.res.mjs

@@ -10,12 +10,16 @@ import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Effect from "effect/Effect";
 import * as Stream$1 from "effect/Stream";
 import * as Pulumi from "@pulumi/pulumi";
+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 Stdlib_Promise from "@rescript/runtime/lib/es6/Stdlib_Promise.js";
 import * as Primitive_option from "@rescript/runtime/lib/es6/Primitive_option.js";
+import * as Primitive_string from "@rescript/runtime/lib/es6/Primitive_string.js";
 import * as DcbDecode$Reventless from "@reventlessdev/reventless-spec/src/components/DcbDecode.res.mjs";
 import * as ReadModel$Reventless from "@reventlessdev/reventless-spec/src/components/ReadModel.res.mjs";
 import * as Message$ReventlessCore from "../../Message.res.mjs";
 import * as Component$ReventlessCore from "../Component.res.mjs";
+import * as EventTopic$ReventlessCore from "../EventTopic/EventTopic.res.mjs";
 import * as EffectLogger$ReventlessCore from "../../util/EffectLogger.res.mjs";
 import * as ComponentType$ReventlessCore from "../../ComponentType.res.mjs";
 import * as RuntimeHints$ReventlessInfra from "@reventlessdev/reventless-infra/src/types/RuntimeHints.res.mjs";
@@ -50,74 +54,90 @@ function Make(RuntimeEnvironment) {
           await queryDbOps.save(Id$Reventless.$$String.makeFromString(param[0]), param[1], "Overwrite", undefined);
         });
       };
-      let make = (dcbEventLog, publishJsons, runtime, opts) => Component$ReventlessCore.make(ComponentType$ReventlessCore.toString(OutboundTranslationSlice$ReventlessCore.componentType), Spec.name, (extra, extra$1) => {
-        let opts_parent = Component$ReventlessCore.toPulumiResource(extra);
-        let opts = {
-          parent: opts_parent
-        };
-        let memorySize = RuntimeHints$ReventlessInfra.resolveMemory(runtime, 1024);
-        let timeout = RuntimeHints$ReventlessInfra.resolveTimeout(runtime, 30);
-        let queryDb = SpecificQueryDb.make(Api.api(), Api.apiRole(), undefined, {
-          kind: "OutboundTranslationSlice",
-          name: Spec.name
-        }, opts);
-        let dcbEventTopicOutputs = Component$ReventlessCore.outputs(dcbEventLog).eventTopic;
-        let dcbEventLogName = Stdlib_Option.getOr(Component$ReventlessCore.toPulumiResource(dcbEventLog).__name, "") + "DcbEventLog";
-        let allEventTopics = Object.fromEntries([[
-            dcbEventLogName,
-            dcbEventTopicOutputs
-          ]]);
-        let eventCollector = Pulumi.all([
-          Component$ReventlessCore.operations(queryDb),
-          publishJsons
-        ]).apply(param => {
-          let publishJsonsFn = param[1];
-          let queryDbOps = param[0];
-          let ec = SpecificEventCollector.make(Spec.name, allEventTopics, {
+      let make = (dcbEventLog, allEventTopicsOpt, publishJsons, runtime, opts) => {
+        let allEventTopics = allEventTopicsOpt !== undefined ? allEventTopicsOpt : ({});
+        return Component$ReventlessCore.make(ComponentType$ReventlessCore.toString(OutboundTranslationSlice$ReventlessCore.componentType), Spec.name, (extra, extra$1) => {
+          let opts_parent = Component$ReventlessCore.toPulumiResource(extra);
+          let opts = {
+            parent: opts_parent
+          };
+          let memorySize = RuntimeHints$ReventlessInfra.resolveMemory(runtime, 1024);
+          let timeout = RuntimeHints$ReventlessInfra.resolveTimeout(runtime, 30);
+          let queryDb = SpecificQueryDb.make(Api.api(), Api.apiRole(), undefined, {
             kind: "OutboundTranslationSlice",
             name: Spec.name
           }, opts);
-          let jsonEventsHandler = stream => Effect.flatMap(Stream.runCollect(Stream$1.flatMap(Stream$1.mapEffect(stream, json => Effect.sync(() => {
-            let rawEvent = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(json), d => d["event"]), json);
-            let match = Message$ReventlessCore.splitMessage(rawEvent);
-            let event = decoder.decode(match[0], match[1]);
-            if (event !== undefined) {
-              return [Primitive_option.valFromOption(event)];
-            } else {
-              return [];
+          let dcbEventTopicOutputs = Component$ReventlessCore.outputs(dcbEventLog).eventTopic;
+          let dcbEventLogName = Stdlib_Option.getOr(Component$ReventlessCore.toPulumiResource(dcbEventLog).__name, "") + "DcbEventLog";
+          let availableTopics = Object.assign({}, allEventTopics);
+          availableTopics[dcbEventLogName] = dcbEventTopicOutputs;
+          let declared = Spec.sourceNames;
+          let sourceNames = declared.length !== 0 ? declared : [dcbEventLogName];
+          sourceNames.forEach(sourceName => {
+            if (sourceName in availableTopics) {
+              return;
             }
-          })), events => Stream$1.fromIterable(events))), eventsArr => Effect.promise(async () => {
-            Callback.phase1(eventsArr);
-            await syncToQueryDb(queryDbOps);
-            Stdlib_Promise.$$catch(Callback.phase2(publishJsonsFn).then(() => syncToQueryDb(queryDbOps)), exn => {
-              let errMsg = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(exn), Stdlib_JsExn.message), "unknown");
-              Effect.runSync(EffectLogger$ReventlessCore.logError(`OutboundTranslationSlice(` + Spec.name + `)`, undefined, `detached phase 2 error: ` + errMsg));
-              return Promise.resolve();
-            });
+            let availableNames = Object.keys(availableTopics).toSorted(Primitive_string.compare).join(", ");
+            Stdlib_JsError.throwWithMessage(`OutboundTranslationSlice "` + Spec.name + `" declares sourceName "` + sourceName + `", but no EventTopic with that key exists. ` + (`Available source names: [` + availableNames + `]. `) + `A source is an Aggregate Spec.name or a DCB source name (typically "<pluginName>DcbEventLog"); \`[]\` means this plugin's own DCB log.`);
+          });
+          let eventTopics = EventTopic$ReventlessCore.filter(availableTopics, Belt_SetString.fromArray(sourceNames));
+          let eventCollector = Pulumi.all([
+            Component$ReventlessCore.operations(queryDb),
+            publishJsons
+          ]).apply(param => {
+            let publishJsonsFn = param[1];
+            let queryDbOps = param[0];
+            let ec = SpecificEventCollector.make(Spec.name, eventTopics, {
+              kind: "OutboundTranslationSlice",
+              name: Spec.name
+            }, opts);
+            let jsonEventsHandler = stream => Effect.flatMap(Stream.runCollect(Stream$1.flatMap(Stream$1.mapEffect(stream, json => Effect.sync(() => {
+              let envelope = Stdlib_JSON.Decode.object(json);
+              let rawEvent = Stdlib_Option.getOr(Stdlib_Option.flatMap(envelope, d => d["event"]), json);
+              let sourceId = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(envelope, d => d["id"]), Stdlib_JSON.Decode.string), "");
+              let match = Message$ReventlessCore.splitMessage(rawEvent);
+              let event = decoder.decode(match[0], match[1]);
+              if (event !== undefined) {
+                return [[
+                    sourceId,
+                    Primitive_option.valFromOption(event)
+                  ]];
+              } else {
+                return [];
+              }
+            })), events => Stream$1.fromIterable(events))), eventsArr => Effect.promise(async () => {
+              Callback.phase1(eventsArr);
+              await syncToQueryDb(queryDbOps);
+              Stdlib_Promise.$$catch(Callback.phase2(publishJsonsFn).then(() => syncToQueryDb(queryDbOps)), exn => {
+                let errMsg = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(exn), Stdlib_JsExn.message), "unknown");
+                Effect.runSync(EffectLogger$ReventlessCore.logError(`OutboundTranslationSlice(` + Spec.name + `)`, undefined, `detached phase 2 error: ` + errMsg));
+                return Promise.resolve();
+              });
+            }));
+            let handler = SpecificEventCollector.makeHandler(ec, jsonEventsHandler);
+            let resources = Component$ReventlessCore.outputs(queryDb).resources;
+            EventCollectorRuntimeBuilder.forEventCollector(handler, eventTopics, resources, memorySize, timeout, ec);
+            return ec;
+          });
+          Component$ReventlessCore.setOperations(extra, Pulumi.all([
+            Output$Pulumi.flatMap(eventCollector, Component$ReventlessCore.operations),
+            publishJsons
+          ]).apply(param => {
+            let publishJsonsFn = param[1];
+            return {
+              enqueueEvent: param[0].enqueueEvent,
+              translatePending: async () => await Callback.phase2(publishJsonsFn)
+            };
           }));
-          let handler = SpecificEventCollector.makeHandler(ec, jsonEventsHandler);
-          let resources = Component$ReventlessCore.outputs(queryDb).resources;
-          EventCollectorRuntimeBuilder.forEventCollector(handler, allEventTopics, resources, memorySize, timeout, ec);
-          return ec;
-        });
-        Component$ReventlessCore.setOperations(extra, Pulumi.all([
-          Output$Pulumi.flatMap(eventCollector, Component$ReventlessCore.operations),
-          publishJsons
-        ]).apply(param => {
-          let publishJsonsFn = param[1];
-          return {
-            enqueueEvent: param[0].enqueueEvent,
-            translatePending: async () => await Callback.phase2(publishJsonsFn)
+          let aggregatedResources = Object.values(eventTopics).flatMap(t => t.resources);
+          let outputs_queryDb = Component$ReventlessCore.outputs(queryDb);
+          let outputs = {
+            resources: aggregatedResources,
+            queryDb: outputs_queryDb
           };
-        }));
-        let outputs_resources = dcbEventTopicOutputs.resources;
-        let outputs_queryDb = Component$ReventlessCore.outputs(queryDb);
-        let outputs = {
-          resources: outputs_resources,
-          queryDb: outputs_queryDb
-        };
-        return Component$ReventlessCore.setOutputs(extra, outputs);
-      }, opts);
+          return Component$ReventlessCore.setOutputs(extra, outputs);
+        }, opts);
+      };
       return {
         Spec: Spec,
         Translation: Translation,

package/src/components/OutboundTranslationSlice/OutboundTranslationSlice_Callback.res

@@ -29,8 +29,10 @@ module type T = {
   /** The in-memory TODO list -- maps item ID to row. */
   let todoItems: Dict.t<todoRow>
 
-  /** Phase 1: update TODO list from a batch of events (collect only, no resolve). */
-  let phase1: array<Spec.consumedEvent> => unit
+  /** Phase 1: update TODO list from a batch of `(sourceId, event)` pairs
+      (collect only, no resolve). `sourceId` is the envelope id of the entity the
+      event was published for. */
+  let phase1: array<(string, Spec.consumedEvent)> => unit
 
   /** Phase 2: translate all pending items, optionally publishing commands via publishJsons. */
   let phase2: ReventlessInfra.CommandTopic.publishJsons => promise<unit>
@@ -54,10 +56,10 @@ module Make = (
   let makeMeta = (): Reventless.Message.meta =>
     Message.generateMeta(~service=`OutboundTranslationSlice:${Spec.name}`)
 
-  let phase1 = (events: array<Spec.consumedEvent>) => {
-    events->Array.forEach(event => {
+  let phase1 = (events: array<(string, Spec.consumedEvent)>) => {
+    events->Array.forEach(((sourceId, event)) => {
       // Collect new outbound items
-      Translation.collect(event)->Array.forEach(((id, item)) => {
+      Translation.collect(event, ~sourceId)->Array.forEach(((id, item)) => {
         switch todoItems->Dict.get(id) {
         | Some(_) => () // Already exists -- skip (idempotent)
         | None =>

package/src/components/OutboundTranslationSlice/OutboundTranslationSlice_Callback.res.mjs

@@ -34,8 +34,8 @@ function Make(Spec) {
     let todoItems = {};
     let makeMeta = () => Message$ReventlessCore.generateMeta(`OutboundTranslationSlice:` + Spec.name, undefined, undefined, undefined, undefined, undefined, undefined, undefined);
     let phase1 = events => {
-      events.forEach(event => {
-        Translation.collect(event).forEach(param => {
+      events.forEach(param => {
+        Translation.collect(param[1], param[0]).forEach(param => {
           let id = param[0];
           let match = todoItems[id];
           if (match !== undefined) {

package/tests/api/GeocodingTest.res

@@ -0,0 +1,65 @@
+open JestGlobals
+
+// `confidentMatch` is the gate between "the geocoder said something" and "a
+// coordinate is written into an event log". Every case it declines is a
+// plausible-looking pin it refused to draw, so the declines are the assertions
+// that matter here.
+//
+// It is provider-neutral policy (`Reventless.Geocoding`), shared by the SDK-backed
+// transport in this package and by any plugin reaching a geocoder over HTTP.
+
+module Geocoding = Reventless.Geocoding
+
+let point = (~lat, ~lng) =>
+  switch Reventless.GeoPoint.make(~lat, ~lng) {
+  | Ok(p) => p
+  | Error(why) => fail(why)
+  }
+
+let candidate = (~label, ~relevance=?): Geocoding.candidate => {
+  label,
+  point: point(~lat=48.2082, ~lng=16.3738),
+  relevance,
+}
+
+describe("Geocoder_AwsLocation_Geocoding.confidentMatch", () => {
+  testSync("a clear winner is the answer", () => {
+    let top = candidate(~label="Stephansplatz 1, Vienna", ~relevance=0.97)
+    let result = Geocoding.confidentMatch([top, candidate(~label="Elsewhere", ~relevance=0.4)])
+    expect(result->Option.map(c => c.Geocoding.label))->toEqual(Some("Stephansplatz 1, Vienna"))
+  })
+
+  testSync("a loose top match is declined", () => {
+    let result = Geocoding.confidentMatch([candidate(~label="Somewhere-ish", ~relevance=0.55)])
+    expect(result->Option.isNone)->toBe(true)
+  })
+
+  testSync("two near-equal candidates are ambiguous, not a winner", () => {
+    // The bare-town-name case: the service matched several places about equally
+    // well, and picking the first would pin a confident marker in the wrong one.
+    let result = Geocoding.confidentMatch([
+      candidate(~label="Springfield, IL", ~relevance=0.91),
+      candidate(~label="Springfield, MA", ~relevance=0.89),
+    ])
+    expect(result->Option.isNone)->toBe(true)
+  })
+
+  testSync("an unscored candidate is not confident", () => {
+    // An index that reports no relevance cannot support an unattended decision;
+    // accepting it would make the threshold meaningless where it matters most.
+    let result = Geocoding.confidentMatch([candidate(~label="Unscored")])
+    expect(result->Option.isNone)->toBe(true)
+  })
+
+  testSync("no candidates, no match", () => {
+    expect(Geocoding.confidentMatch([])->Option.isNone)->toBe(true)
+  })
+
+  testSync("the thresholds are callable, not baked in", () => {
+    let loose = [candidate(~label="Loose", ~relevance=0.62)]
+    expect(Geocoding.confidentMatch(loose)->Option.isNone)->toBe(true)
+    expect(
+      Geocoding.confidentMatch(loose, ~minRelevance=0.5)->Option.map(c => c.Geocoding.label),
+    )->toEqual(Some("Loose"))
+  })
+})

package/tests/api/GeocodingTest.res.mjs

@@ -0,0 +1,66 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as JestGlobals from "@reventlessdev/rescript-jest/src/JestGlobals.res.mjs";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as GeoPoint$Reventless from "@reventlessdev/reventless-spec/src/semantic/GeoPoint.res.mjs";
+import * as Geocoding$Reventless from "@reventlessdev/reventless-spec/src/semantic/Geocoding.res.mjs";
+
+function point(lat, lng) {
+  let p = GeoPoint$Reventless.make(lat, lng);
+  if (p.TAG === "Ok") {
+    return p._0;
+  } else {
+    return JestGlobals.fail(p._0);
+  }
+}
+
+function candidate(label, relevance) {
+  return {
+    label: label,
+    point: point(48.2082, 16.3738),
+    relevance: relevance
+  };
+}
+
+globalThis.describe("Geocoder_AwsLocation_Geocoding.confidentMatch", () => {
+  globalThis.test("a clear winner is the answer", () => {
+    let top = candidate("Stephansplatz 1, Vienna", 0.97);
+    let result = Geocoding$Reventless.confidentMatch([
+      top,
+      candidate("Elsewhere", 0.4)
+    ], undefined, undefined);
+    globalThis.expect(Stdlib_Option.map(result, c => c.label)).toEqual("Stephansplatz 1, Vienna");
+  });
+  globalThis.test("a loose top match is declined", () => {
+    let result = Geocoding$Reventless.confidentMatch([candidate("Somewhere-ish", 0.55)], undefined, undefined);
+    globalThis.expect(Stdlib_Option.isNone(result)).toBe(true);
+  });
+  globalThis.test("two near-equal candidates are ambiguous, not a winner", () => {
+    let result = Geocoding$Reventless.confidentMatch([
+      candidate("Springfield, IL", 0.91),
+      candidate("Springfield, MA", 0.89)
+    ], undefined, undefined);
+    globalThis.expect(Stdlib_Option.isNone(result)).toBe(true);
+  });
+  globalThis.test("an unscored candidate is not confident", () => {
+    let result = Geocoding$Reventless.confidentMatch([candidate("Unscored", undefined)], undefined, undefined);
+    globalThis.expect(Stdlib_Option.isNone(result)).toBe(true);
+  });
+  globalThis.test("no candidates, no match", () => {
+    globalThis.expect(Stdlib_Option.isNone(Geocoding$Reventless.confidentMatch([], undefined, undefined))).toBe(true);
+  });
+  globalThis.test("the thresholds are callable, not baked in", () => {
+    let loose = [candidate("Loose", 0.62)];
+    globalThis.expect(Stdlib_Option.isNone(Geocoding$Reventless.confidentMatch(loose, undefined, undefined))).toBe(true);
+    globalThis.expect(Stdlib_Option.map(Geocoding$Reventless.confidentMatch(loose, 0.5, undefined), c => c.label)).toEqual("Loose");
+  });
+});
+
+let Geocoding;
+
+export {
+  Geocoding,
+  point,
+  candidate,
+}
+/*  Not a pure module */