@reventlessdev/reventless-seed 1.0.0-alpha.3 → 1.0.0-alpha.5

package/lib/ocaml/.compiler.log

@@ -1,2 +1,2 @@
-#Start(1785139469133)
-#Done(1785139473598)
+#Start(1785495045271)
+#Done(1785495045300)

package/lib/ocaml/ReventlessSeed.mlmap

@@ -7,3 +7,4 @@ Seed_Random
 Seed_Runner
 Seed_Types
 Seed_Upload
+UploadEndpointResolutionTest

package/lib/ocaml/Seed.res

@@ -14,11 +14,13 @@ module Connect = Seed_Connect
 
 exception Failed = Seed_Types.Failed
 
-// A live target a data set seeds against: an authenticated client, the upload
-// endpoint (empty when the deployment serves no uploads), and a label.
+// A live target a data set seeds against: an authenticated client, the
+// deployment's upload endpoints (the legacy single service and the per-store
+// map, either of which may be empty), and a label.
 type connection = Seed_Connect.connection = {
   client: Seed_Client.t,
   uploadEndpoint: string,
+  uploadEndpoints: dict<string>,
   label: string,
 }
 

package/lib/ocaml/Seed_Client.res

@@ -216,6 +216,42 @@ let queryAllNodes = async (t: t, ~field as fieldName: string, ~selection: string
 let countNodes = async (t: t, ~field: string): int =>
   (await queryAllNodes(t, ~field, ~selection="id"))->Array.length
 
+/**
+ * Polls a connection field until the collected nodes satisfy `satisfied`, or the
+ * timeout elapses. Read models are eventually consistent: a view queried the
+ * instant after the writes that feed it can still read empty or partial (a
+ * DynamoDB connection scan is eventually consistent by default, and the write and
+ * read-back can land on different replicas), so a cross-check that asserts on a
+ * single immediate read races the projection. Same rationale as `waitForIds`,
+ * for the "observe the whole connection" case rather than a fixed id set.
+ *
+ * On timeout, throws `Failed(onTimeout(finalNodes))` so the caller can report
+ * what the view actually settled on — distinguishing a still-empty view from a
+ * genuine count mismatch — instead of a bare assertion.
+ */
+let queryAllNodesUntil = async (
+  t: t,
+  ~field: string,
+  ~selection: string,
+  ~satisfied: array<JSON.t> => bool,
+  ~onTimeout: array<JSON.t> => string,
+  ~timeoutMs: int=60000,
+): array<JSON.t> => {
+  let deadline = nowMs() +. Int.toFloat(timeoutMs)
+  let result = ref(None)
+  while result.contents == None {
+    let nodes = await queryAllNodes(t, ~field, ~selection)
+    if satisfied(nodes) {
+      result := Some(nodes)
+    } else if nowMs() > deadline {
+      throw(Failed(onTimeout(nodes)))
+    } else {
+      await sleep(500)
+    }
+  }
+  result.contents->Option.getOr([])
+}
+
 /**
  * Polls a `<View>ByIds` field until every id is present.
  *

package/lib/ocaml/Seed_Connect.res

@@ -1,15 +1,25 @@
 // Turns endpoints plus a login function into a ready `connection`.
 //
 // A connection is what a data set seeds against: an authenticated GraphQL
-// client, the upload endpoint (empty when the deployment serves no uploads), and
-// a human label for the target. `make` is provider-agnostic — it prompts for
+// client, the deployment's upload endpoints (empty when it serves no uploads),
+// and a human label for the target. `make` is provider-agnostic — it prompts for
 // credentials, calls the supplied `login` to obtain a bearer, and wires it onto
 // the client via `useToken`. Where the bearer comes from (a local `/login`
 // round-trip, a Cognito id token) is the caller's concern.
 
 open Seed_Types
 
-type connection = {client: Seed_Client.t, uploadEndpoint: string, label: string}
+// `uploadEndpoint` is the legacy single presign service (and the local dev
+// server's one upload route); `uploadEndpoints` maps the qualified
+// `{plugin}.{store}` of each declared store to its own presign endpoint. Both,
+// because a deployment may publish either or both — see `Seed_Upload.endpointFor`
+// for the resolution between them.
+type connection = {
+  client: Seed_Client.t,
+  uploadEndpoint: string,
+  uploadEndpoints: dict<string>,
+  label: string,
+}
 
 /**
  * Prompts for credentials, calls `login` to mint a bearer, and returns a
@@ -20,23 +30,47 @@ let make = async (
   ~label: string,
   ~endpoint: string,
   ~uploadEndpoint: string,
+  ~uploadEndpoints: dict<string>=Dict.make(),
   ~login: (~username: string, ~password: string) => promise<string>,
   ~localDefaults: bool=false,
 ): connection => {
-  // `SEED_SKIP_UPLOADS` forces the connection to carry no upload endpoint, so a
-  // data set's upload phase no-ops the same way it does when a deployment serves
-  // none. Use it to seed domain data fast, or to skip a broken/absent upload path
-  // without editing the data set. It is the single knob: an empty
-  // `REVENTLESS_UPLOAD_ENDPOINT` env reads as "unset" (falls back to discovery),
-  // so this is the reliable way to disable uploads.
-  let uploadEndpoint = Seed_Prompt.envValue("SEED_SKIP_UPLOADS")->Option.isSome ? "" : uploadEndpoint
+  // `SEED_SKIP_UPLOADS` forces the connection to carry no upload endpoint at
+  // all, so a data set's upload phase no-ops the same way it does when a
+  // deployment serves none. Use it to seed domain data fast, or to skip a
+  // broken/absent upload path without editing the data set. It is the single
+  // knob: an empty `REVENTLESS_UPLOAD_ENDPOINT` env reads as "unset" (falls back
+  // to discovery), so this is the reliable way to disable uploads — which means
+  // it has to clear the per-store map too, or a declared store keeps uploading
+  // through it.
+  let skip = Seed_Prompt.envValue("SEED_SKIP_UPLOADS")->Option.isSome
+  let uploadEndpoint = skip ? "" : uploadEndpoint
+  let uploadEndpoints = skip ? Dict.make() : uploadEndpoints
   let (username, password) = await Seed_Prompt.credentials(~localDefaults)
   let token = await login(~username, ~password)
   let client = Seed_Client.make(~config={endpoint: endpoint})
   client->Seed_Client.useToken(token)
-  {client, uploadEndpoint, label}
+  {client, uploadEndpoint, uploadEndpoints, label}
 }
 
+/**
+ * The endpoint an asset destined for `store` uploads through, or the reason
+ * there is none — the message to report when the upload phase skips.
+ *
+ * `store` is the qualified `{plugin}.{store}` the asset's field declares, e.g.
+ * `"Catalog.productImages"`. Resolution is `Seed_Upload.endpointFor`; naming a
+ * store the deployment does not serve falls back to the legacy single service
+ * rather than to another store's endpoint.
+ */
+let uploadEndpointFor = (c: connection, ~store: string): result<string, string> =>
+  switch Seed_Upload.endpointFor(
+    ~store,
+    ~uploadEndpoint=c.uploadEndpoint,
+    ~uploadEndpoints=c.uploadEndpoints,
+  ) {
+  | Some(endpoint) => Ok(endpoint)
+  | None => Error(Seed_Upload.unresolvedReason(~store, ~uploadEndpoints=c.uploadEndpoints))
+  }
+
 /**
  * A login function backed by an HTTP login endpoint (the local dev
  * `/__inmemory/login` shape: POST `{username, password}` → `{token}`). Reuses
@@ -63,6 +97,10 @@ let envOr = (key: string, fallback: string): string =>
  * A ready `connect` thunk for the local dev platform, with the localhost
  * defaults baked in and overridable per endpoint (arg, then env var, then
  * default). Empty input at the credential prompt falls back to `admin`/`admin`.
+ *
+ * No per-store map: the local dev server serves every store through its one
+ * upload route, so a data set naming a store resolves to that route by the
+ * "declares a store with no matching endpoint" row.
  */
 let local = (~graphql=?, ~upload=?, ~login=?, ()): (unit => promise<connection>) => {
   let endpoint =

package/lib/ocaml/Seed_Upload.res

@@ -10,6 +10,11 @@
 // absolute URL against the endpoint's origin: AWS returns an absolute presigned
 // S3 URL (unchanged), while the local route returns a same-origin relative
 // `/{prefix}/{key}` that Node's `fetch` cannot PUT to until it is made absolute.
+//
+// `uploadAsset` is the transport and takes a resolved endpoint. *Which* endpoint
+// an asset uses — a deployment now publishes one per declared store — is
+// `endpointFor` below, kept separate so the decision is testable without a
+// running presign service.
 
 type fetchInit = {method: string, headers: dict<string>, body: string}
 type response
@@ -38,6 +43,60 @@ let asString = (json: JSON.t): option<string> =>
   | _ => None
   }
 
+/**
+ * Which endpoint an asset destined for `store` uploads through:
+ *
+ *   declares a store with a matching endpoint  → that store's endpoint
+ *   declares a store with no matching endpoint → the legacy single service
+ *   declares no store                          → the legacy single service
+ *   neither available                          → `None`
+ *
+ * `store` is the qualified `{plugin}.{store}` the platform keys its per-store
+ * presign endpoints by. The two middle rows are what keep a deployment predating
+ * per-store endpoints — and the local dev server, which serves one upload route
+ * — working unchanged.
+ *
+ * These are the same four rows the AutoUI renderer resolves an upload field by.
+ * Resolving one declaration by two different rules is how an asset lands in
+ * another plugin's bucket with a 2xx and a plausible-looking ref, so a missing
+ * key falls back to the legacy service rather than to some other store.
+ */
+let endpointFor = (
+  ~store: option<string>=?,
+  ~uploadEndpoint: string,
+  ~uploadEndpoints: dict<string>,
+): option<string> => {
+  let legacy = uploadEndpoint == "" ? None : Some(uploadEndpoint)
+  switch store {
+  | Some(s) => uploadEndpoints->Dict.get(s)->Option.orElse(legacy)
+  | None => legacy
+  }
+}
+
+/**
+ * Why `endpointFor` resolved nothing — the message a data set reports when its
+ * upload phase skips.
+ *
+ * "no upload endpoint" states a fact about the *deployment*; when the deployment
+ * publishes endpoints the caller could not match, the fact is about the *client*
+ * and that phrasing sends a reader to the bucket, the presign service and the
+ * IAM policy, all of which are correct. So the three cases are distinguished and
+ * the unmatched one names both the store it wanted and the keys it saw.
+ */
+let unresolvedReason = (~store: option<string>=?, ~uploadEndpoints: dict<string>): string => {
+  let available = uploadEndpoints->Dict.keysToArray
+  switch (Seed_Prompt.envValue("SEED_SKIP_UPLOADS"), store, available) {
+  | (Some(_), _, _) => "SEED_SKIP_UPLOADS is set"
+  | (None, _, []) => "this deployment publishes no upload endpoint"
+  | (None, Some(s), keys) =>
+    `this deployment publishes upload endpoints for ${keys->Array.join(", ")}, none for "${s}"`
+  | (None, None, keys) =>
+    `this deployment publishes only per-store upload endpoints (${keys->Array.join(
+        ", ",
+      )}) and this upload names no store`
+  }
+}
+
 // A `fetch` that reports an unreachable endpoint as `Error` instead of throwing,
 // so the two-step upload can thread failures without exceptions.
 let tryFetch = async (url: string, init: fetchInit): result<response, string> =>

package/lib/ocaml/UploadEndpointResolutionTest.res

@@ -0,0 +1,101 @@
+// Which endpoint an asset uploads through once a deployment publishes one per
+// declared store, and what a data set is told when none resolves.
+//
+// The four rows are the same ones the AutoUI renderer resolves an upload field
+// by. They are pinned here because the two middle ones are what keep a
+// deployment predating per-store endpoints — and the local dev server, which
+// serves a single upload route — working unchanged, and because the row that
+// falls back to the legacy service must never fall back to *another store*: that
+// uploads into a different plugin's bucket with a 2xx and a plausible ref.
+
+open JestGlobals
+
+@val @scope("process") external processEnv: dict<string> = "env"
+
+// `unresolvedReason` reads the knob, so the ambient environment has to be quiet.
+let clearSkip = () => processEnv->Dict.set("SEED_SKIP_UPLOADS", "")
+
+let perStore = Dict.fromArray([
+  ("Catalog.productImages", "https://catalog.example/"),
+  ("Ordering.invoices", "https://ordering.example/"),
+])
+
+describe("Seed.Upload.endpointFor", () => {
+  testSync("a declared store with a matching endpoint uses that store's endpoint", () =>
+    expect(
+      Seed.Upload.endpointFor(
+        ~store="Catalog.productImages",
+        ~uploadEndpoint="https://legacy.example/",
+        ~uploadEndpoints=perStore,
+      ),
+    )->toEqual(Some("https://catalog.example/"))
+  )
+
+  // Not "https://ordering.example/" — a wrong guess here is a silent
+  // wrong-bucket write.
+  testSync("a declared store with no matching endpoint falls back to the legacy service", () =>
+    expect(
+      Seed.Upload.endpointFor(
+        ~store="Catalog.brochures",
+        ~uploadEndpoint="https://legacy.example/",
+        ~uploadEndpoints=perStore,
+      ),
+    )->toEqual(Some("https://legacy.example/"))
+  )
+
+  testSync("naming no store uses the legacy service", () =>
+    expect(
+      Seed.Upload.endpointFor(~uploadEndpoint="https://legacy.example/", ~uploadEndpoints=perStore),
+    )->toEqual(Some("https://legacy.example/"))
+  )
+
+  testSync("neither available resolves nothing", () =>
+    expect(
+      Seed.Upload.endpointFor(
+        ~store="Catalog.brochures",
+        ~uploadEndpoint="",
+        ~uploadEndpoints=Dict.make(),
+      ),
+    )->toEqual(None)
+  )
+
+  // The local dev server's shape: one upload route, no per-store map, and a data
+  // set that names its store all the same.
+  testSync("a single-route deployment serves a store-naming data set", () =>
+    expect(
+      Seed.Upload.endpointFor(
+        ~store="Catalog.productImages",
+        ~uploadEndpoint="http://localhost:4000/__inmemory/upload",
+        ~uploadEndpoints=Dict.make(),
+      ),
+    )->toEqual(Some("http://localhost:4000/__inmemory/upload"))
+  )
+})
+
+// "no upload endpoint" states a fact about the deployment. When the deployment
+// publishes endpoints the caller could not match, the fact is about the client,
+// and that phrasing sends a reader to the bucket, the presign service and the
+// IAM policy — all of which are correct.
+describe("Seed.Upload.unresolvedReason", () => {
+  beforeEach(clearSkip)
+
+  testSync("no endpoints at all reads as a fact about the deployment", () =>
+    expect(
+      Seed.Upload.unresolvedReason(~store="Catalog.productImages", ~uploadEndpoints=Dict.make()),
+    )->toBe("this deployment publishes no upload endpoint")
+  )
+
+  testSync("an unmatched store names the store and the keys that were available", () => {
+    let msg = Seed.Upload.unresolvedReason(~store="Catalog.brochures", ~uploadEndpoints=perStore)
+    expect(msg)->toContain("Catalog.brochures")
+    expect(msg)->toContain("Catalog.productImages")
+    expect(msg)->toContain("Ordering.invoices")
+  })
+
+  testSync("the knob outranks both, so a skipped run is never read as a broken one", () => {
+    processEnv->Dict.set("SEED_SKIP_UPLOADS", "1")
+    expect(
+      Seed.Upload.unresolvedReason(~store="Catalog.productImages", ~uploadEndpoints=perStore),
+    )->toBe("SEED_SKIP_UPLOADS is set")
+  })
+})

package/package.json

@@ -1,10 +1,11 @@
 {
   "name": "@reventlessdev/reventless-seed",
-  "version": "1.0.0-alpha.3",
+  "version": "1.0.0-alpha.5",
   "description": "Reusable harness for seeding a Reventless platform through its public GraphQL command API",
   "license": "Apache-2.0",
   "devDependencies": {
-    "rescript": "12.3.0"
+    "rescript": "12.3.0",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.9"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/rescript.json

@@ -12,9 +12,16 @@
     {
       "dir": "src",
       "subdirs": true
+    },
+    {
+      "dir": "tests",
+      "subdirs": true,
+      "type": "dev"
     }
   ],
-  "dependencies": [],
+  "dependencies": [
+    "@reventlessdev/rescript-jest"
+  ],
   "compiler-flags": [],
   "suffix": ".res.mjs"
 }

package/src/Seed.res

@@ -14,11 +14,13 @@ module Connect = Seed_Connect
 
 exception Failed = Seed_Types.Failed
 
-// A live target a data set seeds against: an authenticated client, the upload
-// endpoint (empty when the deployment serves no uploads), and a label.
+// A live target a data set seeds against: an authenticated client, the
+// deployment's upload endpoints (the legacy single service and the per-store
+// map, either of which may be empty), and a label.
 type connection = Seed_Connect.connection = {
   client: Seed_Client.t,
   uploadEndpoint: string,
+  uploadEndpoints: dict<string>,
   label: string,
 }
 

package/src/Seed_Client.res

@@ -216,6 +216,42 @@ let queryAllNodes = async (t: t, ~field as fieldName: string, ~selection: string
 let countNodes = async (t: t, ~field: string): int =>
   (await queryAllNodes(t, ~field, ~selection="id"))->Array.length
 
+/**
+ * Polls a connection field until the collected nodes satisfy `satisfied`, or the
+ * timeout elapses. Read models are eventually consistent: a view queried the
+ * instant after the writes that feed it can still read empty or partial (a
+ * DynamoDB connection scan is eventually consistent by default, and the write and
+ * read-back can land on different replicas), so a cross-check that asserts on a
+ * single immediate read races the projection. Same rationale as `waitForIds`,
+ * for the "observe the whole connection" case rather than a fixed id set.
+ *
+ * On timeout, throws `Failed(onTimeout(finalNodes))` so the caller can report
+ * what the view actually settled on — distinguishing a still-empty view from a
+ * genuine count mismatch — instead of a bare assertion.
+ */
+let queryAllNodesUntil = async (
+  t: t,
+  ~field: string,
+  ~selection: string,
+  ~satisfied: array<JSON.t> => bool,
+  ~onTimeout: array<JSON.t> => string,
+  ~timeoutMs: int=60000,
+): array<JSON.t> => {
+  let deadline = nowMs() +. Int.toFloat(timeoutMs)
+  let result = ref(None)
+  while result.contents == None {
+    let nodes = await queryAllNodes(t, ~field, ~selection)
+    if satisfied(nodes) {
+      result := Some(nodes)
+    } else if nowMs() > deadline {
+      throw(Failed(onTimeout(nodes)))
+    } else {
+      await sleep(500)
+    }
+  }
+  result.contents->Option.getOr([])
+}
+
 /**
  * Polls a `<View>ByIds` field until every id is present.
  *

package/src/Seed_Client.res.mjs

@@ -208,6 +208,28 @@ async function countNodes(t, field) {
   return (await queryAllNodes(t, field, "id")).length;
 }
 
+async function queryAllNodesUntil(t, field, selection, satisfied, onTimeout, timeoutMsOpt) {
+  let timeoutMs = timeoutMsOpt !== undefined ? timeoutMsOpt : 60000;
+  let deadline = Date.now() + timeoutMs;
+  let result;
+  while (result === undefined) {
+    let nodes = await queryAllNodes(t, field, selection);
+    if (satisfied(nodes)) {
+      result = nodes;
+    } else {
+      if (Date.now() > deadline) {
+        throw {
+          RE_EXN_ID: Seed_Types$ReventlessSeed.Failed,
+          _1: onTimeout(nodes),
+          Error: new Error()
+        };
+      }
+      await sleep(500);
+    }
+  };
+  return Stdlib_Option.getOr(result, []);
+}
+
 async function waitForIds(t, fieldName, ids, timeoutMsOpt) {
   let timeoutMs = timeoutMsOpt !== undefined ? timeoutMsOpt : 60000;
   let deadline = Date.now() + timeoutMs;
@@ -255,6 +277,7 @@ export {
   sendAll,
   queryAllNodes,
   countNodes,
+  queryAllNodesUntil,
   waitForIds,
 }
 /* No side effect */

package/src/Seed_Connect.res

@@ -1,15 +1,25 @@
 // Turns endpoints plus a login function into a ready `connection`.
 //
 // A connection is what a data set seeds against: an authenticated GraphQL
-// client, the upload endpoint (empty when the deployment serves no uploads), and
-// a human label for the target. `make` is provider-agnostic — it prompts for
+// client, the deployment's upload endpoints (empty when it serves no uploads),
+// and a human label for the target. `make` is provider-agnostic — it prompts for
 // credentials, calls the supplied `login` to obtain a bearer, and wires it onto
 // the client via `useToken`. Where the bearer comes from (a local `/login`
 // round-trip, a Cognito id token) is the caller's concern.
 
 open Seed_Types
 
-type connection = {client: Seed_Client.t, uploadEndpoint: string, label: string}
+// `uploadEndpoint` is the legacy single presign service (and the local dev
+// server's one upload route); `uploadEndpoints` maps the qualified
+// `{plugin}.{store}` of each declared store to its own presign endpoint. Both,
+// because a deployment may publish either or both — see `Seed_Upload.endpointFor`
+// for the resolution between them.
+type connection = {
+  client: Seed_Client.t,
+  uploadEndpoint: string,
+  uploadEndpoints: dict<string>,
+  label: string,
+}
 
 /**
  * Prompts for credentials, calls `login` to mint a bearer, and returns a
@@ -20,23 +30,47 @@ let make = async (
   ~label: string,
   ~endpoint: string,
   ~uploadEndpoint: string,
+  ~uploadEndpoints: dict<string>=Dict.make(),
   ~login: (~username: string, ~password: string) => promise<string>,
   ~localDefaults: bool=false,
 ): connection => {
-  // `SEED_SKIP_UPLOADS` forces the connection to carry no upload endpoint, so a
-  // data set's upload phase no-ops the same way it does when a deployment serves
-  // none. Use it to seed domain data fast, or to skip a broken/absent upload path
-  // without editing the data set. It is the single knob: an empty
-  // `REVENTLESS_UPLOAD_ENDPOINT` env reads as "unset" (falls back to discovery),
-  // so this is the reliable way to disable uploads.
-  let uploadEndpoint = Seed_Prompt.envValue("SEED_SKIP_UPLOADS")->Option.isSome ? "" : uploadEndpoint
+  // `SEED_SKIP_UPLOADS` forces the connection to carry no upload endpoint at
+  // all, so a data set's upload phase no-ops the same way it does when a
+  // deployment serves none. Use it to seed domain data fast, or to skip a
+  // broken/absent upload path without editing the data set. It is the single
+  // knob: an empty `REVENTLESS_UPLOAD_ENDPOINT` env reads as "unset" (falls back
+  // to discovery), so this is the reliable way to disable uploads — which means
+  // it has to clear the per-store map too, or a declared store keeps uploading
+  // through it.
+  let skip = Seed_Prompt.envValue("SEED_SKIP_UPLOADS")->Option.isSome
+  let uploadEndpoint = skip ? "" : uploadEndpoint
+  let uploadEndpoints = skip ? Dict.make() : uploadEndpoints
   let (username, password) = await Seed_Prompt.credentials(~localDefaults)
   let token = await login(~username, ~password)
   let client = Seed_Client.make(~config={endpoint: endpoint})
   client->Seed_Client.useToken(token)
-  {client, uploadEndpoint, label}
+  {client, uploadEndpoint, uploadEndpoints, label}
 }
 
+/**
+ * The endpoint an asset destined for `store` uploads through, or the reason
+ * there is none — the message to report when the upload phase skips.
+ *
+ * `store` is the qualified `{plugin}.{store}` the asset's field declares, e.g.
+ * `"Catalog.productImages"`. Resolution is `Seed_Upload.endpointFor`; naming a
+ * store the deployment does not serve falls back to the legacy single service
+ * rather than to another store's endpoint.
+ */
+let uploadEndpointFor = (c: connection, ~store: string): result<string, string> =>
+  switch Seed_Upload.endpointFor(
+    ~store,
+    ~uploadEndpoint=c.uploadEndpoint,
+    ~uploadEndpoints=c.uploadEndpoints,
+  ) {
+  | Some(endpoint) => Ok(endpoint)
+  | None => Error(Seed_Upload.unresolvedReason(~store, ~uploadEndpoints=c.uploadEndpoints))
+  }
+
 /**
  * A login function backed by an HTTP login endpoint (the local dev
  * `/__inmemory/login` shape: POST `{username, password}` → `{token}`). Reuses
@@ -63,6 +97,10 @@ let envOr = (key: string, fallback: string): string =>
  * A ready `connect` thunk for the local dev platform, with the localhost
  * defaults baked in and overridable per endpoint (arg, then env var, then
  * default). Empty input at the credential prompt falls back to `admin`/`admin`.
+ *
+ * No per-store map: the local dev server serves every store through its one
+ * upload route, so a data set naming a store resolves to that route by the
+ * "declares a store with no matching endpoint" row.
  */
 let local = (~graphql=?, ~upload=?, ~login=?, ()): (unit => promise<connection>) => {
   let endpoint =