@reventlessdev/reventless-aws 3.0.0-alpha.259 → 3.0.0-alpha.261

package/CHANGELOG.md

@@ -3,6 +3,25 @@
 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.261 (2026-08-03)
+
+### Features
+
+* **aws:** let an outbound slice read an aggregate at runtime ([24585f8](https://github.com/ReventlessDev/reventless-core/commit/24585f869c15a07910434632d76d8c8d8058042b))
+
+
+# 3.0.0-alpha.260 (2026-08-03)
+
+### Bug Fixes
+
+* **aws:** a dimensioned DCB metric cannot carry a default value ([0c105e7](https://github.com/ReventlessDev/reventless-core/commit/0c105e7b7156ed64b923cc75731e3bc49a30bcbd))
+### 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))
+* **platform:** let a deployment choose what the host shell does ([ae0aec3](https://github.com/ReventlessDev/reventless-core/commit/ae0aec33dcf641f02187e8d6a3f3594c506820b6))
+
+
 # 3.0.0-alpha.259 (2026-08-02)
 
 **Note:** Version bump only for package @reventlessdev/reventless-aws

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-aws",
-  "version": "3.0.0-alpha.259",
+  "version": "3.0.0-alpha.261",
   "description": "AWS adapters for Reventless",
   "license": "Apache-2.0",
   "dependencies": {
@@ -11,18 +11,18 @@
     "@aws-sdk/s3-request-presigner": "3.970.0",
     "sury": "11.0.0-alpha.4",
     "uuid": "^13.0.0",
-    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.2",
-    "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
+    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.3",
     "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
+    "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
     "@reventlessdev/rescript-node": "2.0.0-alpha.1",
-    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.64",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
+    "@reventlessdev/rescript-pulumi-aws": "2.4.0-alpha.65",
     "@reventlessdev/rescript-uuid": "2.0.0-alpha.0",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.122",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.205",
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.18",
     "@reventlessdev/reventless-interop": "3.0.0-alpha.30",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.69",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.97"
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.71",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.207",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.124",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.99"
   },
   "devDependencies": {
     "rescript": "12.3.0",

package/src/Platform.res

@@ -82,6 +82,20 @@ let objectStoreEndpointsRef: ref<array<objectStoreEndpoint>> = ref([])
     `getApiConfig` does. */
 let getObjectStoreEndpoints = () => objectStoreEndpointsRef.contents
 
+/** The geocoder endpoint this platform provisioned, for the monolithic case.
+
+    In plugin mode the value crosses to the plugin stack as the `geocoderEndpoint`
+    export; when platform and plugin are one program there is no stack to read, so
+    `deployPlatform` records it here and `deployPlugin` picks it up — the same two
+    halves `objectStoreEndpointsRef` exists for.
+
+    A plain Output with `""` as the "no geocoder" sentinel, never
+    `option<Pulumi.Output.t<_>>`: any generic `Option.*` over an Output runs
+    `valFromOption`, whose nested-option probe hits the Output proxy — where every
+    property access returns a truthy Output — and corrupts it. Same reasoning, and
+    the same sentinel, as `PluginRuntime_Builder.inboundSliceReg.auditTableName`. */
+let geocoderEndpointRef: ref<Pulumi.Output.t<string>> = ref(Pulumi.Output.make(""))
+
 module MakeWithConfig = (
   Config: {
     let splitApi: bool
@@ -1149,6 +1163,25 @@ module MakeWithConfig = (
     // writes the prefix once and consumes it on both sides, so a mismatch is
     // unrepresentable rather than merely discouraged.
     uploadBucket?: ReventlessInfra.Platform.objectStore,
+    // Optional view modes the deployed shell loads at boot. Written to
+    // config.json as `viewModes`, with each mode's options flattened beside it
+    // (`Map({style})` ⇒ `"viewModes": ["map"], "mapStyle": …`). Unset ⇒ both
+    // keys omitted and the shell loads no optional mode, so a non-map
+    // deployment still downloads no maplibre chunk and gets a byte-identical
+    // config.json.
+    //
+    // This is the one input that decides what the shell *does* rather than what
+    // it points at, and it is load-bearing twice over: naming `Map` is what
+    // makes both the map view and the map-backed geo-point command input exist,
+    // and it is what makes a provisioned `geocoderPlaceIndex` reachable at all
+    // (the geocoder client is built inside the map chunk).
+    viewModes?: array<ReventlessInfra.Platform.viewMode>,
+    // Shell-owned config.json keys the framework has no opinion about
+    // (`accessTiers`, `platformName`, `assetOrigins`, `uiHintsUrl`, …), merged
+    // in verbatim under the computed keys. Untyped on purpose — re-declaring
+    // the shell's schema here would cost a lockstep core release per UI knob.
+    // A key that collides with a computed one fails the deploy naming it.
+    shellConfig?: dict<JSON.t>,
   }
 
   // Merged-mode outputs of deployPlatform — the merged API(s), plus the
@@ -2033,6 +2066,18 @@ module MakeWithConfig = (
       | None => Pulumi.Output.make(None)
       }
 
+      // Exported as well as written into config.json, because the browser is no
+      // longer the only caller: a plugin stack's slice Lambdas geocode too, and a
+      // plugin stack has no other way to see a value computed in this one.
+      //
+      // `""` when unset rather than a missing output, so the read side has one
+      // shape to handle instead of two — and "" is already what a client reads as
+      // "no geocoder configured".
+      let geocoderEndpointFlat =
+        geocoderEndpointOutput->Pulumi.Output.apply(o => o->Option.getOr(""))
+      Pulumi.Pulumi.export("geocoderEndpoint", geocoderEndpointFlat)
+      geocoderEndpointRef := geocoderEndpointFlat
+
       // Presign endpoints are no longer written to config.json: under route B the
       // client calls the platform API's `Upload_Presign` mutation (reachable from
       // `platformApiEndpoint`, already present) with the store it declares, so there
@@ -2055,7 +2100,7 @@ module MakeWithConfig = (
           eventsEpOpt,
           geocoderEpOpt,
         )) => {
-          let fields = [
+          let computed = [
             ("apiEndpoint", JSON.Encode.string(domainEp)),
             ("platformApiEndpoint", JSON.Encode.string(platformEp)),
             ("region", JSON.Encode.string(regionStr)),
@@ -2067,7 +2112,7 @@ module MakeWithConfig = (
           let withEvents = switch eventsEpOpt {
           | Some(ep) =>
             Array.concat(
-              fields,
+              computed,
               [
                 ("domainApiEventsEndpoint", JSON.Encode.string(ep)),
                 ("platformApiEventsEndpoint", JSON.Encode.string(ep)),
@@ -2080,13 +2125,19 @@ module MakeWithConfig = (
                 ),
               ],
             )
-          | None => fields
+          | None => computed
           }
           let withGeocoder = switch geocoderEpOpt {
           | Some(ep) => Array.concat(withEvents, [("geocoderEndpoint", JSON.Encode.string(ep))])
           | None => withEvents
           }
-          withGeocoder->Dict.fromArray->JSON.Encode.object->JSON.stringify
+          Util_ShellConfig.fields(
+            ~computed=withGeocoder,
+            ~viewModes=?cfg.viewModes,
+            ~shellConfig=?cfg.shellConfig,
+          )
+          ->JSON.Encode.object
+          ->JSON.stringify
         })
 
       let _ = PulumiAws.S3.BucketObject.make(
@@ -2181,6 +2232,30 @@ module MakeWithConfig = (
       {Reventless.Offload.store, key, hash, bytes: bytes->String.length}
     })
 
+    // Capability endpoints the platform provisioned, handed to this plugin's
+    // slice Lambdas as environment. Read across the stack reference in plugin
+    // mode and out of the platform's own record when platform and plugin are one
+    // program — the same two halves the offload bucket above is read through.
+    //
+    // Registered before `P.make()`: the slice runtime finalizers fire from inside
+    // the plugin build, and a variable registered after it would be built into
+    // nothing.
+    //
+    // A platform that provisioned no geocoder yields "", and the plugin's client
+    // reports `Unavailable` — retried, then surfaced by the heartbeat sweep. That
+    // is a modelled outcome, which is the point of the empty string: a plugin
+    // deployed against a platform without the capability degrades rather than
+    // failing to deploy.
+    let geocoderEndpoint: Pulumi.Output.t<string> = switch platformStackRef {
+    | Some(stackRef) =>
+      (
+        stackRef->Pulumi.StackReference.getOutput("geocoderEndpoint"):
+          Pulumi.Output.t<option<string>>
+      )->Pulumi.Output.apply(o => o->Option.getOr(""))
+    | None => geocoderEndpointRef.contents
+    }
+    PluginRuntime_Builder.registerCapabilityEnv("GEOCODER_ENDPOINT", geocoderEndpoint)
+
     module P = unpack(plugin)
     let pluginComponent = P.make()
     ReventlessCore.Plugin_Helpers.clearOffload()

package/src/Platform.res.mjs

@@ -40,6 +40,7 @@ import * as Plugin_Helpers$ReventlessCore from "@reventlessdev/reventless-core/s
 import * as Upload_Claim_S3$ReventlessAws from "./adapter/Upload/Upload_Claim_S3.res.mjs";
 import * as PgProjectionFeed$ReventlessAws from "./adapter/Postgres/PgProjectionFeed.res.mjs";
 import * as Util_LocalConfig$ReventlessAws from "./util/Util_LocalConfig.res.mjs";
+import * as Util_ShellConfig$ReventlessAws from "./util/Util_ShellConfig.res.mjs";
 import * as Util_StoreLayout$ReventlessAws from "./util/Util_StoreLayout.res.mjs";
 import * as IndexJs from "@pulumi/pulumi/runtime/index.js";
 import * as AppSync_EventsApi$ReventlessAws from "./adapter/Api/AppSync_EventsApi.res.mjs";
@@ -129,6 +130,10 @@ function getObjectStoreEndpoints() {
   return objectStoreEndpointsRef.contents;
 }
 
+let geocoderEndpointRef = {
+  contents: Pulumi.output("")
+};
+
 function MakeWithConfig(Config) {
   Stdlib_Option.forEach(Config.commandHandlerConfig.aggregates, param => {
     Stdlib_Option.forEach(param.sync, AggregateRuntime_Builder_Single$ReventlessAws.setConfig);
@@ -1123,6 +1128,9 @@ function MakeWithConfig(Config) {
       let domainEventsEndpointOutput = domainEventsApiOpt !== undefined ? AppSync_EventsApi$ReventlessAws.httpEndpoint(domainEventsApiOpt).apply(ep => ep + "/event") : Pulumi.output(undefined);
       let index = hostUiBundle.geocoderPlaceIndex;
       let geocoderEndpointOutput = index !== undefined ? Geocoder_AwsLocation$ReventlessAws.make(index.indexName, undefined, undefined).url.apply(u => u) : Pulumi.output(undefined);
+      let geocoderEndpointFlat = geocoderEndpointOutput.apply(o => Stdlib_Option.getOr(o, ""));
+      Pulumi$Pulumi.$$export("geocoderEndpoint", geocoderEndpointFlat);
+      geocoderEndpointRef.contents = geocoderEndpointFlat;
       let configJsonContent = Pulumi.all([
         Pulumi.all([
           resolvedDomainApiEndpoint,
@@ -1136,7 +1144,7 @@ function MakeWithConfig(Config) {
         let geocoderEpOpt = param[2];
         let eventsEpOpt = param[1];
         let match = param[0];
-        let fields = [
+        let computed = [
           [
             "apiEndpoint",
             match[0]
@@ -1166,7 +1174,7 @@ function MakeWithConfig(Config) {
             true
           ]
         ];
-        let withEvents = eventsEpOpt !== undefined ? fields.concat([
+        let withEvents = eventsEpOpt !== undefined ? computed.concat([
             [
               "domainApiEventsEndpoint",
               eventsEpOpt
@@ -1179,12 +1187,12 @@ function MakeWithConfig(Config) {
               "clientEventsNamespace",
               AppSync_EventsApi$ReventlessAws.clientNamespaceName
             ]
-          ]) : fields;
+          ]) : computed;
         let withGeocoder = geocoderEpOpt !== undefined ? withEvents.concat([[
               "geocoderEndpoint",
               geocoderEpOpt
             ]]) : withEvents;
-        return JSON.stringify(Object.fromEntries(withGeocoder));
+        return JSON.stringify(Util_ShellConfig$ReventlessAws.fields(withGeocoder, hostUiBundle.viewModes, hostUiBundle.shellConfig));
       });
       new (Aws.s3.BucketObject)("host-ui-config-json", {
         bucket: bucketName,
@@ -1239,6 +1247,8 @@ function MakeWithConfig(Config) {
         bytes: bytes.length
       };
     });
+    let geocoderEndpoint = platformStackRef !== undefined ? Primitive_option.valFromOption(platformStackRef).getOutput("geocoderEndpoint").apply(o => Stdlib_Option.getOr(o, "")) : geocoderEndpointRef.contents;
+    PluginRuntime_Builder$ReventlessAws.registerCapabilityEnv("GEOCODER_ENDPOINT", geocoderEndpoint);
     let pluginComponent = plugin.make();
     Plugin_Helpers$ReventlessCore.clearOffload();
     currentDeployTarget.contents = "Domain";
@@ -2349,6 +2359,9 @@ function Make($star) {
       let domainEventsEndpointOutput = domainEventsApiOpt !== undefined ? AppSync_EventsApi$ReventlessAws.httpEndpoint(domainEventsApiOpt).apply(ep => ep + "/event") : Pulumi.output(undefined);
       let index = hostUiBundle.geocoderPlaceIndex;
       let geocoderEndpointOutput = index !== undefined ? Geocoder_AwsLocation$ReventlessAws.make(index.indexName, undefined, undefined).url.apply(u => u) : Pulumi.output(undefined);
+      let geocoderEndpointFlat = geocoderEndpointOutput.apply(o => Stdlib_Option.getOr(o, ""));
+      Pulumi$Pulumi.$$export("geocoderEndpoint", geocoderEndpointFlat);
+      geocoderEndpointRef.contents = geocoderEndpointFlat;
       let configJsonContent = Pulumi.all([
         Pulumi.all([
           resolvedDomainApiEndpoint,
@@ -2362,7 +2375,7 @@ function Make($star) {
         let geocoderEpOpt = param[2];
         let eventsEpOpt = param[1];
         let match = param[0];
-        let fields = [
+        let computed = [
           [
             "apiEndpoint",
             match[0]
@@ -2392,7 +2405,7 @@ function Make($star) {
             true
           ]
         ];
-        let withEvents = eventsEpOpt !== undefined ? fields.concat([
+        let withEvents = eventsEpOpt !== undefined ? computed.concat([
             [
               "domainApiEventsEndpoint",
               eventsEpOpt
@@ -2405,12 +2418,12 @@ function Make($star) {
               "clientEventsNamespace",
               AppSync_EventsApi$ReventlessAws.clientNamespaceName
             ]
-          ]) : fields;
+          ]) : computed;
         let withGeocoder = geocoderEpOpt !== undefined ? withEvents.concat([[
               "geocoderEndpoint",
               geocoderEpOpt
             ]]) : withEvents;
-        return JSON.stringify(Object.fromEntries(withGeocoder));
+        return JSON.stringify(Util_ShellConfig$ReventlessAws.fields(withGeocoder, hostUiBundle.viewModes, hostUiBundle.shellConfig));
       });
       new (Aws.s3.BucketObject)("host-ui-config-json", {
         bucket: bucketName,
@@ -2465,6 +2478,8 @@ function Make($star) {
         bytes: bytes.length
       };
     });
+    let geocoderEndpoint = platformStackRef !== undefined ? Primitive_option.valFromOption(platformStackRef).getOutput("geocoderEndpoint").apply(o => Stdlib_Option.getOr(o, "")) : geocoderEndpointRef.contents;
+    PluginRuntime_Builder$ReventlessAws.registerCapabilityEnv("GEOCODER_ENDPOINT", geocoderEndpoint);
     let pluginComponent = plugin.make();
     Plugin_Helpers$ReventlessCore.clearOffload();
     currentDeployTarget.contents = "Domain";
@@ -2616,6 +2631,7 @@ export {
   getSplitApiOutputs,
   objectStoreEndpointsRef,
   getObjectStoreEndpoints,
+  geocoderEndpointRef,
   MakeWithConfig,
   Make,
 }

package/src/adapter/Geocoder/Geocoder_AwsLocation_Backend.res

@@ -0,0 +1,77 @@
+// Amazon Location as a geocoding transport for unattended callers.
+//
+// Policy — what a candidate is, the two ways a lookup fails, and when a ranked
+// list is confident enough to store — lives in `Reventless.Geocoding`, shared
+// with every other transport. This module only knows how to ask AWS and how to
+// turn its answer into that vocabulary.
+//
+// The public Function URL handler next door answers `200 []` for a genuine
+// no-match and `502 []` for a service failure, because a browser search box must
+// degrade quietly while a translator must not. This module makes the same
+// distinction at the source, for a caller that can reach the SDK directly.
+//
+// Runtime-pure: no Pulumi import, so it can be bundled into a Lambda entry point
+// without dragging deploy-time modules into the cold-start graph.
+
+module Search = AwsSdk.Location.SearchPlaceIndexForTextCommand
+
+/**
+Geocode one address.
+
+`Ok([])` is deliberately unreachable — an empty result set is `Error(NoMatch)`,
+because "the call worked and the answer is nothing" is a different fact from
+"the call worked", and the caller has to act differently on it.
+
+Candidates come back in the provider's ranking order, unfiltered. Choosing among
+them is `Reventless.Geocoding.confidentMatch`'s job.
+*/
+let search = async (~indexName: string, ~text: string, ~maxResults: int=5): result<
+  array<Reventless.Geocoding.candidate>,
+  Reventless.Geocoding.failure,
+> => {
+  let trimmed = text->String.trim
+  if indexName == "" {
+    Error(Unavailable("no place index configured (PLACE_INDEX_NAME unset)"))
+  } else if trimmed == "" {
+    // Not a service failure and not a service verdict — an empty query was never
+    // going to match, and asking would spend a request to be told so.
+    Error(NoMatch)
+  } else {
+    switch await Search.send(Search.make({indexName, text: trimmed, maxResults})) {
+    | resp =>
+      let candidates =
+        resp.results
+        ->Option.getOr([])
+        ->Array.filterMap(r =>
+          switch r.place {
+          | None => None
+          | Some(place) =>
+            // `[lng, lat]` — RFC 7946 order, converted here and nowhere else.
+            switch place.geometry->Option.flatMap(g => g.point) {
+            | Some(pt) if pt->Array.length >= 2 =>
+              switch Reventless.GeoPoint.make(
+                ~lat=pt->Array.getUnsafe(1),
+                ~lng=pt->Array.getUnsafe(0),
+              ) {
+              | Ok(point) =>
+                Some({
+                  Reventless.Geocoding.label: place.label->Option.getOr(""),
+                  point,
+                  relevance: r.relevance,
+                })
+              // A coordinate that fails the range check is dropped rather than
+              // propagated: it cannot be stored, and one bad row should not lose
+              // the good ones beside it.
+              | Error(_) => None
+              }
+            | _ => None
+            }
+          }
+        )
+      candidates->Array.length == 0 ? Error(NoMatch) : Ok(candidates)
+    | exception exn =>
+      let msg = exn->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr("unknown")
+      Error(Unavailable(msg))
+    }
+  }
+}

package/src/adapter/Geocoder/Geocoder_AwsLocation_Backend.res.mjs

@@ -0,0 +1,87 @@
+// Generated by ReScript, PLEASE EDIT WITH CARE
+
+import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
+import * as Location$AwsSdk from "@reventlessdev/rescript-aws-sdk/src/Location.res.mjs";
+import * as GeoPoint$Reventless from "@reventlessdev/reventless-spec/src/semantic/GeoPoint.res.mjs";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
+import * as ClientLocation from "@aws-sdk/client-location";
+
+async function search(indexName, text, maxResultsOpt) {
+  let maxResults = maxResultsOpt !== undefined ? maxResultsOpt : 5;
+  let trimmed = text.trim();
+  if (indexName === "") {
+    return {
+      TAG: "Error",
+      _0: {
+        TAG: "Unavailable",
+        _0: "no place index configured (PLACE_INDEX_NAME unset)"
+      }
+    };
+  }
+  if (trimmed === "") {
+    return {
+      TAG: "Error",
+      _0: "NoMatch"
+    };
+  }
+  let resp;
+  try {
+    resp = await Location$AwsSdk.SearchPlaceIndexForTextCommand.send(new ClientLocation.SearchPlaceIndexForTextCommand({
+      IndexName: indexName,
+      Text: trimmed,
+      MaxResults: maxResults
+    }));
+  } catch (raw_exn) {
+    let exn = Primitive_exceptions.internalToException(raw_exn);
+    let msg = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(exn), Stdlib_JsExn.message), "unknown");
+    return {
+      TAG: "Error",
+      _0: {
+        TAG: "Unavailable",
+        _0: msg
+      }
+    };
+  }
+  let candidates = Stdlib_Array.filterMap(Stdlib_Option.getOr(resp.Results, []), r => {
+    let place = r.Place;
+    if (place === undefined) {
+      return;
+    }
+    let pt = Stdlib_Option.flatMap(place.Geometry, g => g.Point);
+    if (pt === undefined) {
+      return;
+    }
+    if (pt.length < 2) {
+      return;
+    }
+    let point = GeoPoint$Reventless.make(pt[1], pt[0]);
+    if (point.TAG === "Ok") {
+      return {
+        label: Stdlib_Option.getOr(place.Label, ""),
+        point: point._0,
+        relevance: r.Relevance
+      };
+    }
+  });
+  if (candidates.length === 0) {
+    return {
+      TAG: "Error",
+      _0: "NoMatch"
+    };
+  } else {
+    return {
+      TAG: "Ok",
+      _0: candidates
+    };
+  }
+}
+
+let Search;
+
+export {
+  Search,
+  search,
+}
+/* Stdlib_JsExn Not a pure module */

package/src/adapter/Geocoder/Geocoder_AwsLocation_Ops.res

@@ -9,31 +9,9 @@
 // `[{label, lat, lng}]` as JSON. Any failure degrades to an empty array so the
 // caller never sees a hard error.
 
-// ── AWS Location SDK bindings (AWS SDK v3, client.send(new Command(...))) ────
-
-type locationClient
-
-type searchPlaceIndexForTextInput = {
-  @as("IndexName") indexName: string,
-  @as("Text") text: string,
-  @as("MaxResults") maxResults?: int,
-}
-// GeoJSON order: [lng, lat].
-type point = array<float>
-type geometry = {@as("Point") point?: point}
-type place = {@as("Label") label?: string, @as("Geometry") geometry?: geometry}
-type searchResult = {@as("Place") place?: place}
-type searchResponse = {@as("Results") results?: array<searchResult>}
-type searchCommand
-
-@module("@aws-sdk/client-location") @new
-external makeLocationClient: unit => locationClient = "LocationClient"
-
-@module("@aws-sdk/client-location") @new
-external makeSearchPlaceIndexForTextCommand: searchPlaceIndexForTextInput => searchCommand =
-  "SearchPlaceIndexForTextCommand"
-
-@send external send: (locationClient, searchCommand) => promise<searchResponse> = "send"
+// AWS Location lives in the bindings package, shared with the backend geocoder
+// adapter — one place owns the `[lng, lat]` order and the optional `Relevance`.
+module Search = AwsSdk.Location.SearchPlaceIndexForTextCommand
 
 @val external decodeURIComponent: string => string = "decodeURIComponent"
 
@@ -94,13 +72,22 @@ let handler = async (event: functionUrlEvent): response => {
   try {
     let indexName = getEnv("PLACE_INDEX_NAME")->Option.getOr("")
     let q = readQueryParam(event)->Option.getOr("")
-    if indexName == "" || q == "" {
+    if indexName == "" {
+      // A handler with no place index cannot answer anything, so this is the
+      // service being misconfigured — not a verdict on the address. It has to
+      // read as `502` for the same reason the catch below does: a `200 []` here
+      // tells an unattended caller "no such address", and it would then write
+      // that verdict, unretried, for every address it is handed while the
+      // deployment is broken. The browser is unaffected — it reads the body.
+      Console.error("Geocoder: PLACE_INDEX_NAME is unset")
+      {statusCode: 502, headers: jsonHeaders(), body: "[]"}
+    } else if q == "" {
+      // `200`, unlike the arm above: nothing was asked, so "no results" is a
+      // true and final answer rather than a failure to produce one. A search box
+      // sends this on every cleared input.
       {statusCode: 200, headers: jsonHeaders(), body: "[]"}
     } else {
-      let client = makeLocationClient()
-      let resp = await client->send(
-        makeSearchPlaceIndexForTextCommand({indexName, text: q, maxResults: 5}),
-      )
+      let resp = await Search.send(Search.make({indexName, text: q, maxResults: 5}))
       let results =
         resp.results
         ->Option.getOr([])
@@ -113,11 +100,23 @@ let handler = async (event: functionUrlEvent): response => {
               let lng = pt->Array.getUnsafe(0)
               let lat = pt->Array.getUnsafe(1)
               Some(
-                Dict.fromArray([
-                  ("label", JSON.Encode.string(label)),
-                  ("lat", JSON.Encode.float(lat)),
-                  ("lng", JSON.Encode.float(lng)),
-                ])->JSON.Encode.object,
+                Dict.fromArray(
+                  Array.concat(
+                    [
+                      ("label", JSON.Encode.string(label)),
+                      ("lat", JSON.Encode.float(lat)),
+                      ("lng", JSON.Encode.float(lng)),
+                    ],
+                    // Additive: the browser client reads the three fields above
+                    // and ignores this one. An unattended caller needs it to
+                    // apply `Geocoding.confidentMatch`, which is what keeps a
+                    // vague match from becoming a confident pin.
+                    switch r.relevance {
+                    | Some(rel) => [("relevance", JSON.Encode.float(rel))]
+                    | None => []
+                    },
+                  ),
+                )->JSON.Encode.object,
               )
             | _ => None
             }
@@ -133,6 +132,13 @@ let handler = async (event: functionUrlEvent): response => {
   } catch {
   | exn =>
     Console.error2("Geocoder: search failed", exn)
-    {statusCode: 200, headers: jsonHeaders(), body: "[]"}
+    // 502, not 200 — and still `[]`, which is the point. A browser search box
+    // reads the body and degrades to "no results" whether or not it checks the
+    // status, so nothing on that side changes. An unattended caller reads the
+    // status and can tell "the service is down" from "there is no such address",
+    // which is the difference between retrying and writing a verdict into an
+    // event log. One contract serves both because they disagree only about which
+    // half of the response they read.
+    {statusCode: 502, headers: jsonHeaders(), body: "[]"}
   }
 }