@reventlessdev/reventless-local 3.0.0-alpha.226 → 3.0.0-alpha.227

package/CHANGELOG.md

@@ -3,6 +3,17 @@
 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.227 (2026-08-18)
+
+### Bug Fixes
+
+* **api:** declare the reference door in the SDL every backend is built from ([5c1857e](https://github.com/ReventlessDev/reventless-core/commit/5c1857ea90ff40305a1c44a9e57043528e6a93aa))
+* **api:** make the by-index door answer, and let an elevated caller widen it ([0fe0c6f](https://github.com/ReventlessDev/reventless-core/commit/0fe0c6f8dec6228ecaba39577e28d780b4f79c83))
+### Features
+
+* **core:** let a reference name a retired row, and let an elevated caller open one ([9e2623a](https://github.com/ReventlessDev/reventless-core/commit/9e2623a4b22487561607fcc0ca19d51726069ee4))
+
+
 # 3.0.0-alpha.226 (2026-08-16)
 
 **Note:** Version bump only for package @reventlessdev/reventless-local

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/reventless-local",
-  "version": "3.0.0-alpha.226",
+  "version": "3.0.0-alpha.227",
   "description": "Local platform for Reventless (in-memory or SQLite backend, for development and testing without AWS)",
   "license": "Apache-2.0",
   "bin": {
@@ -35,23 +35,23 @@
     "sury": "11.0.0-alpha.4",
     "ws": "^8.18.0",
     "@reventlessdev/rescript-effect": "0.1.0-alpha.32",
-    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-graphql-yoga": "1.0.0-alpha.27",
+    "@reventlessdev/rescript-jest": "1.0.0-alpha.10",
     "@reventlessdev/rescript-mcp-sdk": "1.0.0-alpha.21",
-    "@reventlessdev/rescript-node": "2.0.0-alpha.7",
+    "@reventlessdev/rescript-node": "2.0.0-alpha.8",
+    "@reventlessdev/reventless-core": "3.0.0-alpha.239",
     "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
-    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.86",
-    "@reventlessdev/reventless-infra": "3.0.0-alpha.144",
-    "@reventlessdev/reventless-gwt": "1.0.0-alpha.185",
-    "@reventlessdev/reventless-core": "3.0.0-alpha.238",
-    "@reventlessdev/reventless-postgres": "3.0.0-alpha.102",
-    "@reventlessdev/reventless-seed": "1.0.0-alpha.15",
-    "@reventlessdev/reventless-spec": "3.0.0-alpha.116"
+    "@reventlessdev/reventless-gwt": "1.0.0-alpha.186",
+    "@reventlessdev/reventless-graphql-server": "1.0.0-alpha.87",
+    "@reventlessdev/reventless-infra": "3.0.0-alpha.145",
+    "@reventlessdev/reventless-postgres": "3.0.0-alpha.103",
+    "@reventlessdev/reventless-seed": "1.0.0-alpha.16",
+    "@reventlessdev/reventless-spec": "3.0.0-alpha.117"
   },
   "devDependencies": {
     "rescript": "12.3.0",
     "sury-ppx": "11.0.0-alpha.2",
-    "@reventlessdev/reventless-ppx": "1.0.0-alpha.68"
+    "@reventlessdev/reventless-ppx": "1.0.0-alpha.69"
   },
   "peerDependencies": {
     "rescript": "12.3.0"

package/src/Platform.res

@@ -1428,11 +1428,10 @@ module MakeWithConfig = (
       switch entry.indexQueries {
       | Some(indexes) =>
         indexes->Array.forEach((ic: Reventless.ReadModel.indexConfig) => {
-          let stripped =
-            ic.index->String.startsWith("by") && ic.index->String.length > 2
-              ? ic.index->String.slice(~start=2, ~end=ic.index->String.length)
-              : ic.index
-          let fieldName = entry.singleFieldName ++ "By" ++ stripped->String.capitalize
+          let fieldName = ReventlessCore.GraphQL_FragmentGenerator.indexQueryFieldName(
+            ~singleFieldName=entry.singleFieldName,
+            ~index=ic.index,
+          )
           queryResolvers->Dict.set(fieldName, async (_root, _args, _ctx): JSON.t =>
             connectionResponse([])
           )

package/src/Platform.res.mjs

@@ -9,7 +9,6 @@ import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
-import * as Stdlib_String from "@rescript/runtime/lib/es6/Stdlib_String.js";
 import * as Effect from "effect/Effect";
 import * as Pulumi from "@pulumi/pulumi";
 import * as Stdlib_Promise from "@rescript/runtime/lib/es6/Stdlib_Promise.js";
@@ -81,6 +80,7 @@ import * as LocalDcbEventLogStorage$ReventlessLocal from "./adapter/DcbEventLog/
 import * as LocalRuntimeEnvironment$ReventlessLocal from "./adapter/Runtime/LocalRuntimeEnvironment.res.mjs";
 import * as LocalScheduledPublisher$ReventlessLocal from "./adapter/Scheduler/LocalScheduledPublisher.res.mjs";
 import * as Platform_Admin_Structure$ReventlessCore from "@reventlessdev/reventless-core/src/admin/Platform_Admin_Structure.res.mjs";
+import * as GraphQL_FragmentGenerator$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/GraphQL_FragmentGenerator.res.mjs";
 import * as LocalCommandTopicChannel$ReventlessLocal from "./adapter/CommandTopic/LocalCommandTopicChannel.res.mjs";
 import * as LocalEventTopicPublisher$ReventlessLocal from "./adapter/EventTopic/LocalEventTopicPublisher.res.mjs";
 import * as StateChangeSlice_Builder$ReventlessLocal from "./components/StateChangeSlice_Builder.res.mjs";
@@ -1206,8 +1206,7 @@ function MakeWithConfig(Config) {
       let indexes = entry.indexQueries;
       if (indexes !== undefined) {
         indexes.forEach(ic => {
-          let stripped = ic.index.startsWith("by") && ic.index.length > 2 ? ic.index.slice(2, ic.index.length) : ic.index;
-          let fieldName = entry.singleFieldName + "By" + Stdlib_String.capitalize(stripped);
+          let fieldName = GraphQL_FragmentGenerator$ReventlessCore.indexQueryFieldName(entry.singleFieldName, ic.index);
           queryResolvers[fieldName] = async (_root, _args, _ctx) => connectionResponse([]);
         });
         return;
@@ -2933,8 +2932,7 @@ function Make($star) {
       let indexes = entry.indexQueries;
       if (indexes !== undefined) {
         indexes.forEach(ic => {
-          let stripped = ic.index.startsWith("by") && ic.index.length > 2 ? ic.index.slice(2, ic.index.length) : ic.index;
-          let fieldName = entry.singleFieldName + "By" + Stdlib_String.capitalize(stripped);
+          let fieldName = GraphQL_FragmentGenerator$ReventlessCore.indexQueryFieldName(entry.singleFieldName, ic.index);
           queryResolvers[fieldName] = async (_root, _args, _ctx) => connectionResponse([]);
         });
         return;

package/src/adapter/QueryDb/QueryDbResolvers_GraphQL.res

@@ -228,8 +228,6 @@ module Make = (Bus: LocalBus.T) => {
         )
       }
 
-    let cap = s => s->String.charAt(0)->String.toUpperCase ++ s->String.slice(~start=1)
-
     // Resolve query field names: check registry first, fall back to safe defaults.
     // Fallbacks use simple GraphQL built-in types to avoid referencing non-existent custom types.
     let registryEntry = Plugin_Helpers.queryFieldNamesRegistry->Dict.get(name)
@@ -271,10 +269,16 @@ module Make = (Bus: LocalBus.T) => {
     }
 
     // -- Main query: getById ---------------------------------------------------
+    // `includeRetired` here matches the connection field and the AppSync SDL the
+    // FragmentGenerator emits. The resolver below already reads it — `retiredAllows`
+    // consults `askedForRetired(~args)` on every door — so this argument was the
+    // only missing half, and without it an elevated caller could see an archived
+    // row in a list and not open it.
     let byIdSdl = if includeIdParam {
       switch subIdField {
-      | Some(sf) => `  ${singleQueryName}(id: ID!, ${sf}: String): ${returnTypeName}`
-      | None => `  ${singleQueryName}(id: ID!): ${returnTypeName}`
+      | Some(sf) =>
+        `  ${singleQueryName}(id: ID!, ${sf}: String, includeRetired: Boolean): ${returnTypeName}`
+      | None => `  ${singleQueryName}(id: ID!, includeRetired: Boolean): ${returnTypeName}`
       }
     } else {
       `  ${singleQueryName}: ${returnTypeName}`
@@ -402,6 +406,124 @@ module Make = (Bus: LocalBus.T) => {
     | None => "id"
     }
 
+    // -- Reference door: {listFieldName}Refs -----------------------------------
+    // Names the rows a caller already holds pointers to, and nothing more. Three
+    // fields, fixed by the type, so this cannot be widened by what a caller
+    // selects.
+    //
+    // Retirement is lifted here only where the view declared `@namedWhenRetired`.
+    // Ownership is not lifted at all, and the asymmetry is the point: an archived
+    // product is a thing the shop sold and every order naming one may say what it
+    // was, while a deactivated customer is somebody's row before it is anything
+    // else. One predicate answers "is this row still on offer", the other "is this
+    // row yours", and only the first is what an archive withdraws.
+    let refsSdl = if includeIdParam && subIdField === None {
+      [GraphQL_FragmentGenerator.deriveRefsQueryField(~listFieldName=listQueryName, ~returnTypeName)]
+    } else {
+      []
+    }
+    let refsResolverEntry: option<(string, ReventlessGraphqlServer.GraphQL_ServerInstance.resolverFn)> =
+      if includeIdParam && subIdField === None {
+        server.registerTypes(~sdlTypes=[GraphQL_FragmentGenerator.deriveRefTypeSdl(~returnTypeName)])
+        let resolver: ReventlessGraphqlServer.GraphQL_ServerInstance.resolverFn = async (
+          _root,
+          args,
+          ctx,
+        ) => {
+          switch await runInterceptor(~ctx, ~args) {
+          | Deny(_) => []->JSON.Encode.array
+          | Allow =>
+            let ids =
+              args
+              ->JSON.Decode.object
+              ->Option.flatMap(d => d->Dict.get("ids"))
+              ->Option.flatMap(JSON.Decode.array)
+              ->Option.getOr([])
+              ->Array.filterMap(JSON.Decode.string)
+            let spec = retiredSpecOf()
+            let namesRetired = spec->Option.mapOr(false, r => r.namedWhenRetired)
+            // The row's own retirement, read with the same `isRetiredValue` every
+            // other door narrows by — so "retired" here and "withheld" there are
+            // one answer, not two that drift.
+            let retirementOf = (item: JSON.t) =>
+              switch spec {
+              | None => (false, None)
+              | Some(r) =>
+                let cell = item->JSON.Decode.object->Option.flatMap(d => d->Dict.get(r.field))
+                let scope: Reventless.OwnerScope.retiredScope = {field: r.field, values: r.values}
+                let retired = scope->Reventless.OwnerScope.isRetiredValue(cell)
+                (
+                  retired,
+                  // The state that retired it, and only that. A live row reports
+                  // none — this door names rows, it does not publish a lifecycle
+                  // column to callers the list withholds. Nor does the boolean
+                  // form, where the field is the state and `retired` said it.
+                  retired && r.values->Option.isSome
+                    ? cell->Option.flatMap(JSON.Decode.string)
+                    : None,
+                )
+              }
+            switch Bus.getQueryDb(name) {
+            | Some(ops) =>
+              let load = key =>
+                ops.loadStream(key)
+                ->Stream.runCollect
+                ->Effect.catchAll(_ => Effect.succeed([]))
+                ->Effect.runPromise
+              let loaded = await ids->Array.map(async id =>
+                switch (await load(id))->Array.get(0) {
+                | Some(item) => (id, Some(item))
+                | None =>
+                  switch Api_Ids.alternateKey(id) {
+                  | Some(localId) => (localId, (await load(localId))->Array.get(0))
+                  | None => (id, None)
+                  }
+                }
+              )->Promise.all
+              loaded
+              ->Array.filterMap(((id, opt)) =>
+                opt
+                ->Option.filter(item => ownerAllows(~ctx, item))
+                ->Option.flatMap(item => {
+                  let (retired, state) = retirementOf(item)
+                  // A retired row leaves through this door only where the view
+                  // said it may. Where it did not, the door answers exactly as
+                  // every other one does — with nothing.
+                  if retired && !namesRetired {
+                    None
+                  } else {
+                    let label =
+                      item
+                      ->JSON.Decode.object
+                      ->Option.flatMap(d => d->Dict.get(labelField))
+                      ->Option.flatMap(JSON.Decode.string)
+                      // A view with no label field resolves to its id, which is
+                      // what `labelField`'s own fallback already decided.
+                      ->Option.getOr(id)
+                    Some(
+                      Dict.fromArray([
+                        ("id", JSON.Encode.string(id)),
+                        ("label", JSON.Encode.string(label)),
+                        ("retired", JSON.Encode.bool(retired)),
+                        (
+                          "retiredState",
+                          state->Option.mapOr(JSON.Encode.null, JSON.Encode.string),
+                        ),
+                      ])->JSON.Encode.object,
+                    )
+                  }
+                })
+              )
+              ->JSON.Encode.array
+            | None => []->JSON.Encode.array
+            }
+          }
+        }
+        Some((listQueryName ++ "Refs", resolver))
+      } else {
+        None
+      }
+
     // -- List query -------------------------------------------------------------
     // Look up the registered state schema (populated alongside queryFieldNamesRegistry)
     // so the resolver derives the same serverCapability the FragmentGenerator emitted.
@@ -666,20 +788,95 @@ module Make = (Bus: LocalBus.T) => {
     }
 
     // -- Index queries: {name}By{Index} ---------------------------------------
+    // Name, argument and return type all come from `GraphQL_FragmentGenerator`,
+    // which is also where the AppSync SDL gets them. They used to be spelled out
+    // here independently and disagreed with that emitter on all three, so the
+    // same door had a different signature per backend and worked on neither.
     let indexSdlFields = indexes->Array.map((ic: Reventless.ReadModel.indexConfig) =>
-      `  ${singleQueryName}By${cap(ic.index)}(${ic.index}: String!): [String]`
+      GraphQL_FragmentGenerator.deriveIndexQueryField(
+        ~singleFieldName=singleQueryName,
+        ~indexConfig=ic,
+        ~connectionTypeName=returnTypeName ++ "Connection",
+      )
     )
+    // Backward paging is refused rather than ignored, and refused on both
+    // backends rather than on the one that cannot do it. `listAllItemsConnection`
+    // already sets the rule for a door whose read cannot walk backwards — "fail
+    // loud rather than silently returning the forward page" — and its reasoning
+    // is about the answer, not about DynamoDB: `last: 2` handed the first two
+    // rows is a different question answered without saying so.
+    //
+    // The arguments stay in the SDL. One that appeared and disappeared with the
+    // backend would make adding a sort key a breaking schema change and force
+    // every client to feature-detect, which is the same argument `includeRetired`
+    // and the reference door are emitted unconditionally for.
+    let rejectBackwardPaging = (~args) => {
+      let given = key =>
+        switch args->JSON.Decode.object->Option.flatMap(d => d->Dict.get(key)) {
+        | None | Some(JSON.Null) => false
+        | Some(_) => true
+        }
+      if given("last") || given("before") {
+        throw(
+          GraphQL_CallerError.badUserInput(
+            "Backward pagination (last/before) is not supported on by-index connections; use first/after.",
+          ),
+        )
+      }
+    }
+    // A positional connection. This door answers an equality lookup on one index
+    // value and has no ordering key to cut a cursor from — the list door borrows
+    // its sort key because it orders by one. An offset is stable for as long as
+    // a page-forward takes, which is what the field advertises and no more.
+    let indexConnection = (~args, items: array<JSON.t>) => {
+      let arg = key => args->JSON.Decode.object->Option.flatMap(d => d->Dict.get(key))
+      let after =
+        arg("after")->Option.flatMap(JSON.Decode.string)->Option.flatMap(s => Int.fromString(s))->Option.getOr(-1)
+      let first =
+        arg("first")->Option.flatMap(JSON.Decode.float)->Option.map(Float.toInt)->Option.getOr(50)
+      let start = after + 1
+      let page = items->Array.slice(~start, ~end=start + first)
+      let taken = page->Array.length
+      let edges =
+        page->Array.mapWithIndex((item, i) =>
+          Dict.fromArray([
+            ("node", item),
+            ("cursor", (start + i)->Int.toString->JSON.Encode.string),
+          ])->JSON.Encode.object
+        )
+      let cursorAt = i => i->Int.toString->JSON.Encode.string
+      Dict.fromArray([
+        ("edges", edges->JSON.Encode.array),
+        (
+          "pageInfo",
+          Dict.fromArray([
+            ("hasNextPage", JSON.Encode.bool(start + taken < items->Array.length)),
+            ("hasPreviousPage", JSON.Encode.bool(start > 0)),
+            ("startCursor", taken > 0 ? cursorAt(start) : JSON.Encode.null),
+            ("endCursor", taken > 0 ? cursorAt(start + taken - 1) : JSON.Encode.null),
+          ])->JSON.Encode.object,
+        ),
+      ])->JSON.Encode.object
+    }
     let indexResolvers: array<(string, ReventlessGraphqlServer.GraphQL_ServerInstance.resolverFn)> = indexes->Array.map(
       (ic: Reventless.ReadModel.indexConfig) => {
-        let index = ic.index
-        let resolverName = singleQueryName ++ "By" ++ cap(index)
-        let filterField = ic.idField->Option.getOr(index)
+        let resolverName = GraphQL_FragmentGenerator.indexQueryFieldName(
+          ~singleFieldName=singleQueryName,
+          ~index=ic.index,
+        )
+        // The argument the caller passes and the row field this filters on are
+        // one and the same — the door reads the index's key, not its name.
+        let filterField = GraphQL_FragmentGenerator.indexKeyField(ic)
         let resolver: ReventlessGraphqlServer.GraphQL_ServerInstance.resolverFn = async (_root, args, ctx) => {
           switch await runInterceptor(~ctx, ~args) {
-          | Deny(_) => []->JSON.Encode.array
+          | Deny(_) => indexConnection(~args, [])
           | Allow =>
+            // After the interceptor, matching the AppSync pipeline, where the
+            // interceptor leads the chain and the query function's `request`
+            // raises this second.
+            rejectBackwardPaging(~args)
             let value =
-              args->JSON.Decode.object->Option.flatMap(d => d->Dict.get(index))->Option.flatMap(JSON.Decode.string)->Option.getOr("")
+              args->JSON.Decode.object->Option.flatMap(d => d->Dict.get(filterField))->Option.flatMap(JSON.Decode.string)->Option.getOr("")
             // Applied to whichever arm answers, rather than inside one of them: the
             // push-down and the scan are two ways to reach the same rows, and a
             // narrowing that lives in only one is a hole that appears when a
@@ -690,22 +887,24 @@ module Make = (Bus: LocalBus.T) => {
             // in-memory reuses its lazy snapshot). Fall back to scan+filter only
             // if no lookup is registered for this QueryDb.
             switch Bus.getQueryDbIndexLookup(name) {
-            | Some(lookup) => lookup(filterField, value)->scoped->JSON.Encode.array
+            | Some(lookup) => indexConnection(~args, lookup(filterField, value)->scoped)
             | None =>
               switch Bus.getQueryDbScan(name) {
               | Some(scanAll) =>
-                scanAll()
-                ->Array.filter(item =>
-                  item
-                  ->JSON.Decode.object
-                  ->Option.flatMap(d => d->Dict.get(filterField))
-                  ->Option.flatMap(JSON.Decode.string)
-                  ->Option.map(v => v == value)
-                  ->Option.getOr(false)
+                indexConnection(
+                  ~args,
+                  scanAll()
+                  ->Array.filter(item =>
+                    item
+                    ->JSON.Decode.object
+                    ->Option.flatMap(d => d->Dict.get(filterField))
+                    ->Option.flatMap(JSON.Decode.string)
+                    ->Option.map(v => v == value)
+                    ->Option.getOr(false)
+                  )
+                  ->scoped,
                 )
-                ->scoped
-                ->JSON.Encode.array
-              | None => []->JSON.Encode.array
+              | None => indexConnection(~args, [])
               }
             }
           }
@@ -718,6 +917,7 @@ module Make = (Bus: LocalBus.T) => {
     let allSdl =
       [byIdSdl]
       ->Array.concat(byIdsSdl)
+      ->Array.concat(refsSdl)
       ->Array.concat(listSdl)
       ->Array.concat(itemsSdl)
       ->Array.concat(indexSdlFields)
@@ -725,6 +925,7 @@ module Make = (Bus: LocalBus.T) => {
     let resolvers = Dict.make()
     resolvers->Dict.set(singleQueryName, byIdResolver)
     byIdsResolverEntry->Option.forEach(((k, v)) => resolvers->Dict.set(k, v))
+    refsResolverEntry->Option.forEach(((k, v)) => resolvers->Dict.set(k, v))
     listResolvers->Array.forEach(((k, v)) => resolvers->Dict.set(k, v))
     itemsResolvers->Array.forEach(((k, v)) => resolvers->Dict.set(k, v))
     indexResolvers->Array.forEach(((k, v)) => resolvers->Dict.set(k, v))

package/src/adapter/QueryDb/QueryDbResolvers_GraphQL.res.mjs

@@ -1,6 +1,7 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
 import * as Stream from "@reventlessdev/rescript-effect/src/Stream.res.mjs";
+import * as Stdlib_Int from "@rescript/runtime/lib/es6/Stdlib_Int.js";
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
 import * as Stdlib_Array from "@rescript/runtime/lib/es6/Stdlib_Array.js";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
@@ -16,6 +17,7 @@ import * as Plugin_Helpers$ReventlessCore from "@reventlessdev/reventless-core/s
 import * as SortKey_Filter$ReventlessLocal from "./SortKey_Filter.res.mjs";
 import * as QueryDbListQuery$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/QueryDbListQuery.res.mjs";
 import * as QueryDb_Callback$ReventlessCore from "@reventlessdev/reventless-core/src/components/QueryDb/QueryDb_Callback.res.mjs";
+import * as GraphQL_CallerError$ReventlessLocal from "../GraphQL_CallerError.res.mjs";
 import * as DomainGraphQL_Server$ReventlessLocal from "../DomainGraphQL_Server.res.mjs";
 import * as OwnerScopeDiagnostics$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/OwnerScopeDiagnostics.res.mjs";
 import * as GraphQL_FragmentGenerator$ReventlessCore from "@reventlessdev/reventless-core/src/components/Api/GraphQL_FragmentGenerator.res.mjs";
@@ -112,7 +114,6 @@ function Make(Bus) {
         return true;
       }
     };
-    let cap = s => s.charAt(0).toUpperCase() + s.slice(1);
     let registryEntry = Plugin_Helpers$ReventlessCore.queryFieldNamesRegistry[name];
     let singleQueryName = registryEntry !== undefined ? registryEntry.singleFieldName : name.charAt(0).toLowerCase() + name.slice(1);
     let listQueryName = registryEntry !== undefined ? registryEntry.listFieldName : name + "s";
@@ -124,7 +125,7 @@ function Make(Bus) {
       relay.registerNodeType(returnTypeName, name);
     }
     let byIdSdl = includeIdParam ? (
-        subIdField !== undefined ? `  ` + singleQueryName + `(id: ID!, ` + subIdField + `: String): ` + returnTypeName : `  ` + singleQueryName + `(id: ID!): ` + returnTypeName
+        subIdField !== undefined ? `  ` + singleQueryName + `(id: ID!, ` + subIdField + `: String, includeRetired: Boolean): ` + returnTypeName : `  ` + singleQueryName + `(id: ID!, includeRetired: Boolean): ` + returnTypeName
       ) : `  ` + singleQueryName + `: ` + returnTypeName;
     let byIdResolver = async (_root, args, ctx) => {
       let match = await runInterceptor(ctx, args);
@@ -219,6 +220,101 @@ function Make(Bus) {
       byIdsResolverEntry = undefined;
     }
     let labelField = registryEntry !== undefined ? Stdlib_Option.getOr(registryEntry.labelField, "id") : "id";
+    let refsSdl = includeIdParam && subIdField === undefined ? [GraphQL_FragmentGenerator$ReventlessCore.deriveRefsQueryField(listQueryName, returnTypeName)] : [];
+    let refsResolverEntry;
+    if (includeIdParam && subIdField === undefined) {
+      server.registerTypes([GraphQL_FragmentGenerator$ReventlessCore.deriveRefTypeSdl(returnTypeName)]);
+      let resolver$1 = async (_root, args, ctx) => {
+        let match = await runInterceptor(ctx, args);
+        if (typeof match === "object") {
+          return [];
+        }
+        let ids = Stdlib_Array.filterMap(Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(args), d => d["ids"]), Stdlib_JSON.Decode.array), []), Stdlib_JSON.Decode.string);
+        let spec = retiredSpecOf();
+        let namesRetired = Stdlib_Option.mapOr(spec, false, r => r.namedWhenRetired);
+        let retirementOf = item => {
+          if (spec === undefined) {
+            return [
+              false,
+              undefined
+            ];
+          }
+          let cell = Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d[spec.field]);
+          let scope_field = spec.field;
+          let scope_values = spec.values;
+          let scope = {
+            field: scope_field,
+            values: scope_values
+          };
+          let retired = OwnerScope$Reventless.isRetiredValue(scope, cell);
+          return [
+            retired,
+            retired && Stdlib_Option.isSome(spec.values) ? Stdlib_Option.flatMap(cell, Stdlib_JSON.Decode.string) : undefined
+          ];
+        };
+        let ops = Bus.getQueryDb(name);
+        if (ops === undefined) {
+          return [];
+        }
+        let load = key => Effect.runPromise(Effect.catchAll(Stream.runCollect(ops.loadStream(key)), param => Effect.succeed([])));
+        let loaded = await Promise.all(ids.map(async id => {
+          let item = (await load(id))[0];
+          if (item !== undefined) {
+            return [
+              id,
+              item
+            ];
+          }
+          let localId = Api_Ids$ReventlessCore.alternateKey(id);
+          if (localId !== undefined) {
+            return [
+              localId,
+              (await load(localId))[0]
+            ];
+          } else {
+            return [
+              id,
+              undefined
+            ];
+          }
+        }));
+        return Stdlib_Array.filterMap(loaded, param => {
+          let id = param[0];
+          return Stdlib_Option.flatMap(Stdlib_Option.filter(param[1], item => ownerAllows(ctx, item)), item => {
+            let match = retirementOf(item);
+            let retired = match[0];
+            if (retired && !namesRetired) {
+              return;
+            }
+            let label = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d[labelField]), Stdlib_JSON.Decode.string), id);
+            return Object.fromEntries([
+              [
+                "id",
+                id
+              ],
+              [
+                "label",
+                label
+              ],
+              [
+                "retired",
+                retired
+              ],
+              [
+                "retiredState",
+                Stdlib_Option.mapOr(match[1], null, prim => prim)
+              ]
+            ]);
+          });
+        });
+      };
+      refsResolverEntry = [
+        listQueryName + "Refs",
+        resolver$1
+      ];
+    } else {
+      refsResolverEntry = undefined;
+    }
     let stateSchemaOpt = Plugin_Helpers$ReventlessCore.stateSchemaRegistry[name];
     let capability = stateSchemaOpt !== undefined ? GraphQL_FragmentGenerator$ReventlessCore.deriveServerCapability(name, stateSchemaOpt) : GraphQL_FragmentGenerator$ReventlessCore.emptyCapability;
     let fetchAllItems = async () => {
@@ -250,7 +346,7 @@ function Make(Bus) {
           endCursor: null
         }
       };
-      let resolver$1 = async (_root, args, ctx) => {
+      let resolver$2 = async (_root, args, ctx) => {
         let match = await runInterceptor(ctx, args);
         if (typeof match === "object") {
           return emptyConnection;
@@ -277,11 +373,11 @@ function Make(Bus) {
       };
       match = [
         sdl,
-        resolver$1
+        resolver$2
       ];
     } else {
       let sdl$1 = [`  ` + listQueryName + `(nextToken: String, limit: Int): ` + pluralTypeName + `!`];
-      let resolver$2 = async (_root, args, ctx) => {
+      let resolver$3 = async (_root, args, ctx) => {
         let match = await runInterceptor(ctx, args);
         if (typeof match === "object") {
           return {
@@ -306,7 +402,7 @@ function Make(Bus) {
       };
       match = [
         sdl$1,
-        resolver$2
+        resolver$3
       ];
     }
     let listResolvers = [[
@@ -324,7 +420,7 @@ function Make(Bus) {
     }
     let itemsResolvers;
     if (subIdField !== undefined) {
-      let resolver$3 = async (_root, args, ctx) => {
+      let resolver$4 = async (_root, args, ctx) => {
         let emptyConn = {
           edges: [],
           pageInfo: {
@@ -423,22 +519,81 @@ function Make(Bus) {
       };
       itemsResolvers = [[
           singleQueryName + "Items",
-          resolver$3
+          resolver$4
         ]];
     } else {
       itemsResolvers = [];
     }
-    let indexSdlFields = indexes.map(ic => `  ` + singleQueryName + `By` + cap(ic.index) + `(` + ic.index + `: String!): [String]`);
+    let indexSdlFields = indexes.map(ic => GraphQL_FragmentGenerator$ReventlessCore.deriveIndexQueryField(singleQueryName, ic, returnTypeName + "Connection"));
+    let rejectBackwardPaging = args => {
+      let given = key => {
+        let match = Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(args), d => d[key]);
+        if (match !== undefined) {
+          return match !== null;
+        } else {
+          return false;
+        }
+      };
+      if (!(given("last") || given("before"))) {
+        return;
+      }
+      throw GraphQL_CallerError$ReventlessLocal.badUserInput("Backward pagination (last/before) is not supported on by-index connections; use first/after.");
+    };
+    let indexConnection = (args, items) => {
+      let arg = key => Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(args), d => d[key]);
+      let after = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(arg("after"), Stdlib_JSON.Decode.string), s => Stdlib_Int.fromString(s, undefined)), -1);
+      let first = Stdlib_Option.getOr(Stdlib_Option.map(Stdlib_Option.flatMap(arg("first"), Stdlib_JSON.Decode.float), prim => prim | 0), 50);
+      let start = after + 1 | 0;
+      let page = items.slice(start, start + first | 0);
+      let taken = page.length;
+      let edges = page.map((item, i) => Object.fromEntries([
+        [
+          "node",
+          item
+        ],
+        [
+          "cursor",
+          (start + i | 0).toString()
+        ]
+      ]));
+      return Object.fromEntries([
+        [
+          "edges",
+          edges
+        ],
+        [
+          "pageInfo",
+          Object.fromEntries([
+            [
+              "hasNextPage",
+              (start + taken | 0) < items.length
+            ],
+            [
+              "hasPreviousPage",
+              start > 0
+            ],
+            [
+              "startCursor",
+              taken > 0 ? start.toString() : null
+            ],
+            [
+              "endCursor",
+              taken > 0 ? ((start + taken | 0) - 1 | 0).toString() : null
+            ]
+          ])
+        ]
+      ]);
+    };
     let indexResolvers = indexes.map(ic => {
-      let index = ic.index;
-      let resolverName = singleQueryName + "By" + cap(index);
-      let filterField = Stdlib_Option.getOr(ic.idField, index);
+      let resolverName = GraphQL_FragmentGenerator$ReventlessCore.indexQueryFieldName(singleQueryName, ic.index);
+      let filterField = GraphQL_FragmentGenerator$ReventlessCore.indexKeyField(ic);
       let resolver = async (_root, args, ctx) => {
         let match = await runInterceptor(ctx, args);
         if (typeof match === "object") {
-          return [];
+          return indexConnection(args, []);
         }
-        let value = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(args), d => d[index]), Stdlib_JSON.Decode.string), "");
+        rejectBackwardPaging(args);
+        let value = Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(args), d => d[filterField]), Stdlib_JSON.Decode.string), "");
         let scoped = rows => rows.filter(item => {
           if (ownerAllows(ctx, item)) {
             return retiredAllows(ctx, args, item);
@@ -448,13 +603,13 @@ function Make(Bus) {
         });
         let lookup = Bus.getQueryDbIndexLookup(name);
         if (lookup !== undefined) {
-          return scoped(lookup(filterField, value));
+          return indexConnection(args, scoped(lookup(filterField, value)));
         }
         let scanAll = Bus.getQueryDbScan(name);
         if (scanAll !== undefined) {
-          return scoped(scanAll().filter(item => Stdlib_Option.getOr(Stdlib_Option.map(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d[filterField]), Stdlib_JSON.Decode.string), v => v === value), false)));
+          return indexConnection(args, scoped(scanAll().filter(item => Stdlib_Option.getOr(Stdlib_Option.map(Stdlib_Option.flatMap(Stdlib_Option.flatMap(Stdlib_JSON.Decode.object(item), d => d[filterField]), Stdlib_JSON.Decode.string), v => v === value), false))));
         } else {
-          return [];
+          return indexConnection(args, []);
         }
       };
       return [
@@ -462,12 +617,15 @@ function Make(Bus) {
         resolver
       ];
     });
-    let allSdl = [byIdSdl].concat(byIdsSdl).concat(match[0]).concat(itemsSdl).concat(indexSdlFields);
+    let allSdl = [byIdSdl].concat(byIdsSdl).concat(refsSdl).concat(match[0]).concat(itemsSdl).concat(indexSdlFields);
     let resolvers = {};
     resolvers[singleQueryName] = byIdResolver;
     Stdlib_Option.forEach(byIdsResolverEntry, param => {
       resolvers[param[0]] = param[1];
     });
+    Stdlib_Option.forEach(refsResolverEntry, param => {
+      resolvers[param[0]] = param[1];
+    });
     listResolvers.forEach(param => {
       resolvers[param[0]] = param[1];
     });

package/tests/UiHintsTest.res

@@ -103,30 +103,54 @@ describe("UiHints.emit", () => {
 // point, while mid-session it is almost always an editor mid-save, and killing a
 // running dev server over a keystroke is worse than the restart this replaces.
 
-// Both exits close the watcher AND clear the deadline. A watcher is `unref`ed
+// The edit is repeated, and that is not belt-and-braces.
+//
+// `fs.watch` does not promise that a write landing near the watcher's creation
+// is reported. The FSEvents stream behind it on macOS is armed asynchronously,
+// and a write that gets there first is not reported late — it is not reported at
+// all. Measured against this very module: once the stream is up the edit is seen
+// in about 10ms, and when it is not, the same edit produces no event in four
+// seconds, with which of the two happens varying by how many watchers the
+// process has already opened rather than by anything the test does.
+//
+// So a single edit tests the arming, not the reload. Repeating it on an interval
+// far longer than a reload takes — 50ms of debounce plus a file copy — leaves the
+// case where the first write lands identical to what it always was, and lets the
+// case where it is dropped recover on the next one instead of reporting that hot
+// reload is broken. Re-writing the same bytes is what a developer saving twice
+// does, so nothing here asserts less than it did.
+let retryEvery = 1000
+
+// All three exits close the watcher AND clear both timers. A watcher is `unref`ed
 // and would not hold the run open on its own, but a live 4-second timer would —
 // and "Jest did not exit" on a suite that passed is exactly the noise that
 // teaches a reader to ignore it.
-let waitForReload = (~timeoutMs: int=4000, ~afterWatching: unit => unit, ~uiHintsFile, ~dir) =>
+let waitForReload = (~timeoutMs: int=4000, ~edit: unit => unit, ~uiHintsFile, ~dir) =>
   Promise.make((resolve, _) => {
     let fired = ref(0)
     let watcher = ref(None)
     let deadline = ref(None)
+    let retry = ref(None)
     // Resolves with a count rather than rejecting on the deadline: "nothing was
     // re-served" is the expected answer in half these cases, and a rejection
     // would make the assertion read as an infrastructure failure.
     let finish = () => {
       watcher.contents->Option.forEach(NodeFs.watcherClose)
       deadline.contents->Option.forEach(clearTimeout)
+      retry.contents->Option.forEach(clearTimeout)
       resolve(fired.contents)
     }
+    let rec editUntilSeen = () => {
+      edit()
+      retry := Some(setTimeout(editUntilSeen, retryEvery))
+    }
     watcher :=
       UiHints.watch(~uiHintsFile, ~dir, ~onReload=() => {
         fired := fired.contents + 1
         finish()
       })
     deadline := Some(setTimeout(finish, timeoutMs))
-    afterWatching()
+    editUntilSeen()
   })
 
 describe("UiHints.watch", () => {
@@ -147,7 +171,7 @@ describe("UiHints.watch", () => {
     let fired = await waitForReload(
       ~uiHintsFile=Some(path),
       ~dir,
-      ~afterWatching=() => NodeFs.writeFileSync(path, edited),
+      ~edit=() => NodeFs.writeFileSync(path, edited),
     )
     expect((fired > 0, served(dir)))->toEqual((true, edited))
   })
@@ -163,7 +187,7 @@ describe("UiHints.watch", () => {
       ~timeoutMs=1500,
       ~uiHintsFile=Some(path),
       ~dir,
-      ~afterWatching=() => NodeFs.writeFileSync(path, `{"Catalog": {"views":`),
+      ~edit=() => NodeFs.writeFileSync(path, `{"Catalog": {"views":`),
     )
     expect((fired, served(dir)))->toEqual((0, declared))
   })
@@ -178,7 +202,10 @@ describe("UiHints.watch", () => {
     let fired = await waitForReload(
       ~uiHintsFile=Some(path),
       ~dir,
-      ~afterWatching=() => {
+      // Both halves of the save, so a repeat of this edit is the same story told
+      // again and still ends on the whole file — never a truncated write left
+      // standing after a complete one.
+      ~edit=() => {
         NodeFs.writeFileSync(path, `{"Catalog": {"views":`)
         let _ = setTimeout(() => NodeFs.writeFileSync(path, whole), 200)
       },

package/tests/UiHintsTest.res.mjs

@@ -88,7 +88,7 @@ globalThis.describe("UiHints.emit", () => {
   });
 });
 
-function waitForReload(timeoutMsOpt, afterWatching, uiHintsFile, dir) {
+function waitForReload(timeoutMsOpt, edit, uiHintsFile, dir) {
   let timeoutMs = timeoutMsOpt !== undefined ? timeoutMsOpt : 4000;
   return new Promise((resolve, param) => {
     let fired = {
@@ -100,6 +100,9 @@ function waitForReload(timeoutMsOpt, afterWatching, uiHintsFile, dir) {
     let deadline = {
       contents: undefined
     };
+    let retry = {
+      contents: undefined
+    };
     let finish = () => {
       Stdlib_Option.forEach(watcher.contents, prim => {
         prim.close();
@@ -107,14 +110,21 @@ function waitForReload(timeoutMsOpt, afterWatching, uiHintsFile, dir) {
       Stdlib_Option.forEach(deadline.contents, prim => {
         clearTimeout(prim);
       });
+      Stdlib_Option.forEach(retry.contents, prim => {
+        clearTimeout(prim);
+      });
       resolve(fired.contents);
     };
+    let editUntilSeen = () => {
+      edit();
+      retry.contents = Primitive_option.some(setTimeout(editUntilSeen, 1000));
+    };
     watcher.contents = UiHints$ReventlessLocal.watch(uiHintsFile, dir, () => {
       fired.contents = fired.contents + 1 | 0;
       finish();
     });
     deadline.contents = Primitive_option.some(setTimeout(finish, timeoutMs));
-    afterWatching();
+    editUntilSeen();
   });
 }
 
@@ -178,6 +188,8 @@ globalThis.describe("UiHints.watch", () => {
   });
 });
 
+let retryEvery = 1000;
+
 export {
   shipped,
   declared,
@@ -187,6 +199,7 @@ export {
   served,
   baselinePath,
   threw,
+  retryEvery,
   waitForReload,
 }
 /*  Not a pure module */

package/tests/adapter/GraphQL_SchemaInspectorTest.res

@@ -271,7 +271,7 @@ describe("GraphQL_SchemaInspector", () => {
       expect(result.typeDef->Option.isSome)->toBe(true)
       let typeDef = result.typeDef->Option.getOrThrow
       expect(typeDef->String.includes("type CatalogProduct"))->toBe(true)
-      expect(result.singleQuery->String.includes("Catalog_Product(id: ID!)"))->toBe(true)
+      expect(result.singleQuery->String.includes("Catalog_Product(id: ID!, includeRetired: Boolean)"))->toBe(true)
       expect(result.singleQuery->String.includes("CatalogProduct"))->toBe(true)
       expect(result.listQuery->Option.isSome)->toBe(true)
       let listQ = result.listQuery->Option.getOrThrow
@@ -298,7 +298,7 @@ describe("GraphQL_SchemaInspector", () => {
       )
       let inspection = ReventlessCore.GraphQL_SchemaInspector.inspectFragment(fragment)
       let sdl = inspection.sdlPreview
-      expect(sdl->String.includes("RM_Product(id: ID!): RMProduct"))->toBe(true)
+      expect(sdl->String.includes("RM_Product(id: ID!, includeRetired: Boolean): RMProduct"))->toBe(true)
       expect(sdl->String.includes("type RMProduct"))->toBe(true)
       // The type should have an injected id: ID! field (first field in the type)
       let typeLines = sdl->String.split("\n")
@@ -357,7 +357,7 @@ describe("GraphQL_SchemaInspector", () => {
       )
       let inspection = ReventlessCore.GraphQL_SchemaInspector.inspectFragment(fragment)
       let sdl = inspection.sdlPreview
-      expect(sdl->String.includes("Default_Thing(id: ID!): DefaultThing"))->toBe(true)
+      expect(sdl->String.includes("Default_Thing(id: ID!, includeRetired: Boolean): DefaultThing"))->toBe(true)
     })
   })
 
@@ -542,13 +542,15 @@ describe("GraphQL_SchemaInspector", () => {
         ],
       )
       let inspection = ReventlessCore.GraphQL_SchemaInspector.inspectFragment(fragment)
-      // TestState, TestStateEdge, TestStateConnection, TestStateFilter (Phase 4 connection filter)
+      // TestState, TestStateEdge, TestStateConnection, TestStateFilter (connection filter)
+      // + TestStateRef (the reference door's projection)
       // + CommandResult union + CommandAccepted + CommandRejected + CommandPending
       // (auto-injected whenever the fragment emits any mutation field).
-      expect(inspection.types->Array.length)->toBe(8)
+      expect(inspection.types->Array.length)->toBe(9)
       expect(inspection.mutations->Array.length)->toBe(1)
-      // single Test_State(id), list Test_States(...), and Test_StatesByIds(ids: [String!]!)
-      expect(inspection.queries->Array.length)->toBe(3)
+      // single Test_State(id), list Test_States(...), Test_StatesByIds(ids: [String!]!)
+      // and Test_StatesRefs(ids: [ID!]!) — the by-ids read projected to a reference.
+      expect(inspection.queries->Array.length)->toBe(4)
       expect(inspection.sdlPreview->String.includes("type TestState"))->toBe(true)
       expect(inspection.sdlPreview->String.includes("type TestStateEdge"))->toBe(true)
       expect(inspection.sdlPreview->String.includes("type TestStateConnection"))->toBe(true)

package/tests/adapter/GraphQL_SchemaInspectorTest.res.mjs

@@ -239,7 +239,7 @@ globalThis.describe("GraphQL_SchemaInspector", () => {
       globalThis.expect(Stdlib_Option.isSome(result.typeDef)).toBe(true);
       let typeDef = Stdlib_Option.getOrThrow(result.typeDef, undefined);
       globalThis.expect(typeDef.includes("type CatalogProduct")).toBe(true);
-      globalThis.expect(result.singleQuery.includes("Catalog_Product(id: ID!)")).toBe(true);
+      globalThis.expect(result.singleQuery.includes("Catalog_Product(id: ID!, includeRetired: Boolean)")).toBe(true);
       globalThis.expect(result.singleQuery.includes("CatalogProduct")).toBe(true);
       globalThis.expect(Stdlib_Option.isSome(result.listQuery)).toBe(true);
       let listQ = Stdlib_Option.getOrThrow(result.listQuery, undefined);
@@ -258,7 +258,7 @@ globalThis.describe("GraphQL_SchemaInspector", () => {
         }]);
       let inspection = GraphQL_SchemaInspector$ReventlessCore.inspectFragment(fragment);
       let sdl = inspection.sdlPreview;
-      globalThis.expect(sdl.includes("RM_Product(id: ID!): RMProduct")).toBe(true);
+      globalThis.expect(sdl.includes("RM_Product(id: ID!, includeRetired: Boolean): RMProduct")).toBe(true);
       globalThis.expect(sdl.includes("type RMProduct")).toBe(true);
       let typeLines = sdl.split("\n");
       let idFieldInType = typeLines.some(line => {
@@ -302,7 +302,7 @@ globalThis.describe("GraphQL_SchemaInspector", () => {
         }]);
       let inspection = GraphQL_SchemaInspector$ReventlessCore.inspectFragment(fragment);
       let sdl = inspection.sdlPreview;
-      globalThis.expect(sdl.includes("Default_Thing(id: ID!): DefaultThing")).toBe(true);
+      globalThis.expect(sdl.includes("Default_Thing(id: ID!, includeRetired: Boolean): DefaultThing")).toBe(true);
     });
   });
   globalThis.describe("Relay compliance", () => {
@@ -424,9 +424,9 @@ globalThis.describe("GraphQL_SchemaInspector", () => {
           authorization: undefined
         }]);
       let inspection = GraphQL_SchemaInspector$ReventlessCore.inspectFragment(fragment);
-      globalThis.expect(inspection.types.length).toBe(8);
+      globalThis.expect(inspection.types.length).toBe(9);
       globalThis.expect(inspection.mutations.length).toBe(1);
-      globalThis.expect(inspection.queries.length).toBe(3);
+      globalThis.expect(inspection.queries.length).toBe(4);
       globalThis.expect(inspection.sdlPreview.includes("type TestState")).toBe(true);
       globalThis.expect(inspection.sdlPreview.includes("type TestStateEdge")).toBe(true);
       globalThis.expect(inspection.sdlPreview.includes("type TestStateConnection")).toBe(true);

package/tests/adapter/QueryDbListResolverTest.res

@@ -102,7 +102,7 @@ let pageInfoString = (response: JSON.t, key: string): option<string> =>
 // Per-test fixture — fresh Bus + storage + registry + resolver
 // ─────────────────────────────────────────────────────────────
 
-let buildFixture = async (~name: string) => {
+let buildFixture = async (~name: string, ~indexes: array<Reventless.ReadModel.indexConfig>=[]) => {
   module Bus = LocalBus.Make()
   module Storage = LocalQueryDbStorage.Make(Bus)
   module Resolvers = QueryDbResolvers_GraphQL.Make(Bus)
@@ -151,7 +151,7 @@ let buildFixture = async (~name: string) => {
     ~api=(),
     ~apiRole=(),
     ~dataSourceName=""->Pulumi.Output.make,
-    ~indexes=[],
+    ~indexes,
     ~subIdField=None,
     ~idResolverConfigs=[],
     ~idsResolverConfigs=[],
@@ -440,3 +440,83 @@ describe("QueryDb list resolver — SQLite push-down path", () => {
     })
   )
 })
+
+// The by-index door answers a Relay connection, keyed on the index's column.
+// Both halves used to be wrong here and in the opposite direction on AppSync:
+// this backend promised `[String]` and returned whole rows, so every call failed
+// to serialise before a caller could reach the rows at all.
+describe("QueryDb by-index resolver", () => {
+  let statusIndex: array<Reventless.ReadModel.indexConfig> = [
+    {index: "status", type_: "S", projectionType: ALL},
+  ]
+
+  let indexResolver = async (~name) => {
+    let _ = await buildFixture(~name, ~indexes=statusIndex)
+    switch DomainGraphQL_Server.getQueryResolver(name ++ "ByStatus") {
+    | Some(r) => r
+    | None => JsError.throwWithMessage("index resolver not registered: " ++ name ++ "ByStatus")
+    }
+  }
+
+  beforeEach(() => {
+    DomainGraphQL_Server.reset()
+  })
+
+  testPromise("answers the rows carrying the index value, as edges", async () => {
+    let resolver = await indexResolver(~name="IdxA")
+    let response = await resolver(JSON.Encode.null, argsOf([("status", strJson("active"))]), emptyCtx)
+    let edges = getEdges(response)
+    expect(edges->Array.length)->toBe(3)
+    expect(edgeNodeField(edges->Array.getUnsafe(0), "productId"))->toBe("p-1")
+  })
+
+  testPromise("pages forward on first/after like every other connection", async () => {
+    let resolver = await indexResolver(~name="IdxB")
+    let page1 =
+      await resolver(
+        JSON.Encode.null,
+        argsOf([("status", strJson("active")), ("first", numJson(2))]),
+        emptyCtx,
+      )
+    expect(getEdges(page1)->Array.length)->toBe(2)
+    expect(pageInfoBool(page1, "hasNextPage"))->toBe(true)
+
+    let page2 =
+      await resolver(
+        JSON.Encode.null,
+        argsOf([
+          ("status", strJson("active")),
+          ("first", numJson(2)),
+          ("after", strJson(pageInfoString(page1, "endCursor")->Option.getOr(""))),
+        ]),
+        emptyCtx,
+      )
+    let edges2 = getEdges(page2)
+    expect(edges2->Array.length)->toBe(1)
+    expect(edgeNodeField(edges2->Array.getUnsafe(0), "productId"))->toBe("p-4")
+    expect(pageInfoBool(page2, "hasNextPage"))->toBe(false)
+  })
+
+  // Refused rather than ignored, and refused here because AppSync cannot do it:
+  // a door that paged backward on one backend and quietly returned the forward
+  // page on the other is the divergence this whole field was rebuilt to remove.
+  testPromise("refuses backward paging instead of answering forward", async () => {
+    let resolver = await indexResolver(~name="IdxC")
+    let outcome = try {
+      let _ =
+        await resolver(
+          JSON.Encode.null,
+          argsOf([("status", strJson("active")), ("last", numJson(2))]),
+          emptyCtx,
+        )
+      Ok()
+    } catch {
+    | e => Error(e->JsExn.fromException->Option.flatMap(JsExn.message)->Option.getOr(""))
+    }
+    switch outcome {
+    | Ok() => expect("no error")->toBe("a BAD_USER_INPUT refusal")
+    | Error(message) =>
+      expect(message->String.includes("Backward pagination (last/before) is not supported"))->toBe(true)
+    }
+  })
+})

package/tests/adapter/QueryDbListResolverTest.res.mjs

@@ -2,12 +2,14 @@
 
 import * as S from "sury/src/S.res.mjs";
 import * as Stdlib_JSON from "@rescript/runtime/lib/es6/Stdlib_JSON.js";
+import * as Stdlib_JsExn from "@rescript/runtime/lib/es6/Stdlib_JsExn.js";
 import * as Id$Reventless from "@reventlessdev/reventless-spec/src/types/Id.res.mjs";
 import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 import * as Pulumi from "@pulumi/pulumi";
 import * as Stdlib_JsError from "@rescript/runtime/lib/es6/Stdlib_JsError.js";
 import * as DcbTag$Reventless from "@reventlessdev/reventless-spec/src/components/DcbTag.res.mjs";
 import * as Identity$Reventless from "@reventlessdev/reventless-spec/src/types/Identity.res.mjs";
+import * as Primitive_exceptions from "@rescript/runtime/lib/es6/Primitive_exceptions.js";
 import * as ReadModel$Reventless from "@reventlessdev/reventless-spec/src/components/ReadModel.res.mjs";
 import * as Component$ReventlessCore from "@reventlessdev/reventless-core/src/components/Component.res.mjs";
 import * as LocalBus$ReventlessLocal from "../../src/adapter/LocalBus.res.mjs";
@@ -112,7 +114,8 @@ function pageInfoString(response, key) {
   return getString(pageInfo(response), key);
 }
 
-async function buildFixture(name) {
+async function buildFixture(name, indexesOpt) {
+  let indexes = indexesOpt !== undefined ? indexesOpt : [];
   let Bus = LocalBus$ReventlessLocal.Make({});
   let Storage = LocalQueryDbStorage$ReventlessLocal.Make(Bus);
   let Resolvers = QueryDbResolvers_GraphQL$ReventlessLocal.Make(Bus);
@@ -151,7 +154,7 @@ async function buildFixture(name) {
   Plugin_Helpers$ReventlessCore.stateSchemaRegistry[name] = rowStateSchemaWithAnnotations;
   let queryDb = Maker.make(undefined, undefined, undefined, undefined, undefined);
   let ops = await TestRunner$ReventlessLocal.resolve(Component$ReventlessCore.operations(queryDb));
-  Resolvers.make(name, undefined, undefined, Pulumi.output(""), [], undefined, [], [], "AllowAuthenticated", {});
+  Resolvers.make(name, undefined, undefined, Pulumi.output(""), indexes, undefined, [], [], "AllowAuthenticated", {});
   let r = DomainGraphQL_Server$ReventlessLocal.getQueryResolver(listFieldName);
   let resolver = r !== undefined ? r : Stdlib_JsError.throwWithMessage("resolver not registered: " + listFieldName);
   let rows = [
@@ -199,7 +202,7 @@ async function buildFixture(name) {
 globalThis.describe("QueryDb list resolver — keyset pagination", () => {
   globalThis.beforeEach(() => DomainGraphQL_Server$ReventlessLocal.reset());
   globalThis.test("first: 2 over a 5-row fixture returns 2 edges and hasNextPage = true", async () => {
-    let match = await buildFixture("PageA");
+    let match = await buildFixture("PageA", undefined);
     let response = await match[0](null, Object.fromEntries([[
         "first",
         2
@@ -212,7 +215,7 @@ globalThis.describe("QueryDb list resolver — keyset pagination", () => {
     globalThis.expect(edgeNodeField(edges[1], "productId")).toBe("p-2");
   });
   globalThis.test("after: <endCursor> walks forward without overlap", async () => {
-    let match = await buildFixture("PageB");
+    let match = await buildFixture("PageB", undefined);
     let resolver = match[0];
     let page1 = await resolver(null, Object.fromEntries([[
         "first",
@@ -251,7 +254,7 @@ globalThis.describe("QueryDb list resolver — keyset pagination", () => {
     globalThis.expect(pageInfoBool(page3, "hasNextPage")).toBe(false);
   });
   globalThis.test("last + before walks backward and flips hasPreviousPage", async () => {
-    let match = await buildFixture("PageC");
+    let match = await buildFixture("PageC", undefined);
     let resolver = match[0];
     let page1 = await resolver(null, Object.fromEntries([[
         "first",
@@ -314,7 +317,7 @@ globalThis.describe("QueryDb list resolver — keyset pagination", () => {
     globalThis.expect(pageInfoBool(firstPage, "hasPreviousPage")).toBe(false);
   });
   globalThis.test("filter.<field>Eq + first / after paginates only the narrowed subset", async () => {
-    let match = await buildFixture("PageD");
+    let match = await buildFixture("PageD", undefined);
     let resolver = match[0];
     let activeFilter = Object.fromEntries([[
         "statusEq",
@@ -356,7 +359,7 @@ globalThis.describe("QueryDb list resolver — keyset pagination", () => {
     globalThis.expect(pageInfoBool(page2, "hasNextPage")).toBe(false);
   });
   globalThis.test("orderBy DESC + first / after paginates the reverse-sorted view", async () => {
-    let match = await buildFixture("PageE");
+    let match = await buildFixture("PageE", undefined);
     let resolver = match[0];
     let orderBy = Object.fromEntries([
       [
@@ -404,7 +407,7 @@ globalThis.describe("QueryDb list resolver — keyset pagination", () => {
     globalThis.expect(edgeNodeField(edges2[1], "name")).toBe("Bravo");
   });
   globalThis.test("bare request (no first / after) returns a single bounded page", async () => {
-    let match = await buildFixture("PageF");
+    let match = await buildFixture("PageF", undefined);
     let response = await match[0](null, Object.fromEntries([]), emptyCtx);
     let edges = getEdges(response);
     globalThis.expect(edges.length).toBe(5);
@@ -424,7 +427,7 @@ globalThis.describe("QueryDb list resolver — SQLite push-down path", () => {
     return r;
   };
   globalThis.test("first:2 then after walks forward without overlap", () => withSqlite(async () => {
-    let match = await buildFixture("SqlPageA");
+    let match = await buildFixture("SqlPageA", undefined);
     let resolver = match[0];
     let page1 = await resolver(null, Object.fromEntries([[
         "first",
@@ -452,7 +455,7 @@ globalThis.describe("QueryDb list resolver — SQLite push-down path", () => {
     globalThis.expect(edgeNodeField(edges2[1], "productId")).toBe("p-4");
   }));
   globalThis.test("orderBy name DESC + first:2 returns the reverse-sorted head", () => withSqlite(async () => {
-    let match = await buildFixture("SqlPageB");
+    let match = await buildFixture("SqlPageB", undefined);
     let orderBy = Object.fromEntries([
       [
         "field",
@@ -479,7 +482,7 @@ globalThis.describe("QueryDb list resolver — SQLite push-down path", () => {
     globalThis.expect(edgeNodeField(edges1[1], "name")).toBe("Delta");
   }));
   globalThis.test("statusEq active narrows the pushed page", () => withSqlite(async () => {
-    let match = await buildFixture("SqlPageC");
+    let match = await buildFixture("SqlPageC", undefined);
     let activeFilter = Object.fromEntries([[
         "statusEq",
         "active"
@@ -495,6 +498,98 @@ globalThis.describe("QueryDb list resolver — SQLite push-down path", () => {
   }));
 });
 
+globalThis.describe("QueryDb by-index resolver", () => {
+  let statusIndex = [{
+      index: "status",
+      type_: "S",
+      projectionType: "ALL"
+    }];
+  let indexResolver = async name => {
+    await buildFixture(name, statusIndex);
+    let r = DomainGraphQL_Server$ReventlessLocal.getQueryResolver(name + "ByStatus");
+    if (r !== undefined) {
+      return r;
+    } else {
+      return Stdlib_JsError.throwWithMessage("index resolver not registered: " + name + "ByStatus");
+    }
+  };
+  globalThis.beforeEach(() => DomainGraphQL_Server$ReventlessLocal.reset());
+  globalThis.test("answers the rows carrying the index value, as edges", async () => {
+    let resolver = await indexResolver("IdxA");
+    let response = await resolver(null, Object.fromEntries([[
+        "status",
+        "active"
+      ]]), emptyCtx);
+    let edges = getEdges(response);
+    globalThis.expect(edges.length).toBe(3);
+    globalThis.expect(edgeNodeField(edges[0], "productId")).toBe("p-1");
+  });
+  globalThis.test("pages forward on first/after like every other connection", async () => {
+    let resolver = await indexResolver("IdxB");
+    let page1 = await resolver(null, Object.fromEntries([
+      [
+        "status",
+        "active"
+      ],
+      [
+        "first",
+        2
+      ]
+    ]), emptyCtx);
+    globalThis.expect(getEdges(page1).length).toBe(2);
+    globalThis.expect(pageInfoBool(page1, "hasNextPage")).toBe(true);
+    let page2 = await resolver(null, Object.fromEntries([
+      [
+        "status",
+        "active"
+      ],
+      [
+        "first",
+        2
+      ],
+      [
+        "after",
+        Stdlib_Option.getOr(getString(pageInfo(page1), "endCursor"), "")
+      ]
+    ]), emptyCtx);
+    let edges2 = getEdges(page2);
+    globalThis.expect(edges2.length).toBe(1);
+    globalThis.expect(edgeNodeField(edges2[0], "productId")).toBe("p-4");
+    globalThis.expect(pageInfoBool(page2, "hasNextPage")).toBe(false);
+  });
+  globalThis.test("refuses backward paging instead of answering forward", async () => {
+    let resolver = await indexResolver("IdxC");
+    let outcome;
+    try {
+      await resolver(null, Object.fromEntries([
+        [
+          "status",
+          "active"
+        ],
+        [
+          "last",
+          2
+        ]
+      ]), emptyCtx);
+      outcome = {
+        TAG: "Ok",
+        _0: undefined
+      };
+    } catch (raw_e) {
+      let e = Primitive_exceptions.internalToException(raw_e);
+      outcome = {
+        TAG: "Error",
+        _0: Stdlib_Option.getOr(Stdlib_Option.flatMap(Stdlib_JsExn.fromException(e), Stdlib_JsExn.message), "")
+      };
+    }
+    if (outcome.TAG === "Ok") {
+      globalThis.expect("no error").toBe("a BAD_USER_INPUT refusal");
+      return;
+    }
+    globalThis.expect(outcome._0.includes("Backward pagination (last/before) is not supported")).toBe(true);
+  });
+});
+
 export {
   rowStateSchema,
   rowStateSchemaWithAnnotations,