@reventlessdev/rescript-pulumi-aws 2.4.0-alpha.78 → 2.4.0-alpha.80

package/CHANGELOG.md

@@ -3,6 +3,28 @@
 All notable changes to this project will be documented in this file.
 See [Conventional Commits](https://conventionalcommits.org) for commit guidelines.
 
+# 2.4.0-alpha.80 (2026-08-18)
+
+### Bug Fixes
+
+* **aws:** make the unowned stub callable on the doors that call it ([931aa39](https://github.com/ReventlessDev/reventless-core/commit/931aa3968ae0e29befab7183125ed2453d4765cb))
+### Features
+
+* **aws:** compile every resolver against AppSync before the deploy attaches one ([635bc26](https://github.com/ReventlessDev/reventless-core/commit/635bc265c63e19f1a69f31dfefe116b523b1c39b))
+
+
+# 2.4.0-alpha.79 (2026-08-18)
+
+### Bug Fixes
+
+* **api:** make the by-index door answer, and let an elevated caller widen it ([0fe0c6f](https://github.com/ReventlessDev/reventless-core/commit/0fe0c6f8dec6228ecaba39577e28d780b4f79c83))
+* **aws:** apply [@owner](https://github.com/owner) on the DynamoDB by-ids and by-index doors ([a6b5afc](https://github.com/ReventlessDev/reventless-core/commit/a6b5afc2923bfa4d3e0b2990367f67e8ffdd8877))
+* **aws:** narrow retirement on every DynamoDB door, not only the list ([d6a799b](https://github.com/ReventlessDev/reventless-core/commit/d6a799b287b28e9c1f75e193adbf3f6328a6bf2d))
+### 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))
+
+
 # 2.4.0-alpha.78 (2026-08-16)
 
 ### Bug Fixes

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@reventlessdev/rescript-pulumi-aws",
-  "version": "2.4.0-alpha.78",
+  "version": "2.4.0-alpha.80",
   "description": "ReScript bindings for @pulumi/aws",
   "license": "Apache-2.0",
   "jest": {
@@ -22,8 +22,8 @@
     "@pulumi/aws": "~7.19.0",
     "@pulumi/aws-native": "^1.62.0",
     "sury": "11.0.0-alpha.4",
-    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.11",
-    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19"
+    "@reventlessdev/rescript-pulumi-pulumi": "2.3.0-alpha.19",
+    "@reventlessdev/rescript-aws-sdk": "3.0.0-alpha.12"
   },
   "devDependencies": {
     "esbuild": "^0.25.12",

package/src/AppSync/AppSync_Resolver_Functions.res

@@ -55,6 +55,155 @@ let ownerGuardPreamble = (~ownerField: string, ~elevatedGroups: array<string>) =
   const _owns = (row) => row == null || _exempt || row['${ownerField}'] === _sub;`
 }
 
+/**
+The exemption test on its own, for a door that narrows retirement but has no
+`@owner` field to have declared it already.
+
+Identical to the three lines `ownerGuardPreamble` opens with, and emitted only
+when that preamble is absent — two `const _exempt` in one function body is a
+syntax error, and two *different* definitions of exempt would be worse than one.
+*/
+let exemptPreamble = (~elevatedGroups: array<string>) => {
+  let elevatedLiteral = elevatedGroups->Array.map(g => `'${g}'`)->Array.join(", ")
+  `
+  const _id = ctx.identity;
+  const _sub = _id == null ? null : _id.sub;
+  const _groups = (_id != null && _id.claims != null && _id.claims['cognito:groups']) || [];
+  const _elevated = [${elevatedLiteral}];
+  const _exempt = _sub == null || _groups.some(g => _elevated.indexOf(g) >= 0);`
+}
+
+/**
+A by-key read's retirement guard: `_live(row)`, true when the caller may see it.
+
+The post-read half of the predicate `listAllItemsConnection` pushes into a
+FilterExpression. `GetItem` and `BatchGetItem` have no filter to push into — the
+row is fetched by key — so the decision is made on what came back, which is where
+the owner guard beside it already makes its own.
+
+`row[field] == null` keeps a row written before the annotation existed, matching
+the `attribute_not_exists` half of the list's clause and every other adapter's
+reading of an absent value.
+
+Asking is required, not merely permitted: `_exempt` alone leaves a retired row
+withheld until `includeRetired` is passed, so an operator's ordinary read is as
+narrow as anyone's. An archive that is always underfoot is not an archive.
+
+`~ownerScoped` says whether an `ownerGuardPreamble` has already been emitted into
+the same body; when it has, this reuses its `_exempt` instead of redeclaring one.
+*/
+let retiredGuardPreamble = (
+  ~retiredField: option<string>,
+  ~retiredValues: option<array<string>>,
+  ~elevatedGroups: array<string>,
+  ~ownerScoped: bool,
+) =>
+  switch retiredField {
+  | None => ""
+  | Some(field) =>
+    let prelude = ownerScoped ? "" : exemptPreamble(~elevatedGroups)
+    let isRetired = switch retiredValues {
+    | None => `row['${field}'] === true`
+    | Some(states) =>
+      let literal = states->Array.map(s => `'${s}'`)->Array.join(", ")
+      `[${literal}].indexOf(row['${field}']) >= 0`
+    }
+    `${prelude}
+  // ── retirement narrowing (generated) ──
+  const _wantsRetired = _exempt && ctx.args.includeRetired === true;
+  const _live = (row) =>
+    row == null || _wantsRetired || row['${field}'] == null || !(${isRetired});`
+  }
+
+/**
+The `@owner` predicate for an index door, as a FilterExpression clause.
+
+Same rule and same branch order as `listAllItemsConnection`'s own owner clause —
+provider before identity, because an IAM-signed service caller has no `sub` for a
+reason that has nothing to do with being anonymous — and pushed into the read for
+the same reason: an index door takes a `limit`, and a page cut before the
+predicate would come back short with nothing said about why.
+
+**Not applied to a group-restricted index.** Where `indexConfig.authorization` is
+set, the door already runs `authorizeIndexedAccess`: the caller must be in the
+named group AND be the holder the auth table records for that index value. Those
+rows are, by construction, other people's — an order assigned to a fulfilment
+operator is owned by the customer who placed it — so ANDing `@owner` on top would
+return nothing and revoke exactly the access the auth table was written to grant.
+An explicit per-index rule is the deployment's answer for that door; this is the
+default for doors that have none. `QueryDbResolvers_AppSync` decides which is
+which and passes `ownerField` only for the latter.
+*/
+let ownerFilterClause = (~ownerField: option<string>, ~elevatedGroups: array<string>) =>
+  switch ownerField {
+  | None => ""
+  | Some(field) =>
+    let elevatedLiteral = elevatedGroups->Array.map(g => `'${g}'`)->Array.join(", ")
+    `
+  // ── owner scoping (generated) ──
+  // Not read from ctx.args: a predicate deciding what the caller may see must
+  // arrive on a channel the caller cannot name.
+  const _oid = ctx.identity;
+  const _osub = _oid == null ? null : _oid.sub;
+  const _ogroups = (_oid != null && _oid.claims != null && _oid.claims['cognito:groups']) || [];
+  const _oelevated = [${elevatedLiteral}];
+  if (!(_osub == null || _ogroups.some(g => _oelevated.indexOf(g) >= 0))) {
+    if (expression) expression += ' AND ';
+    names['#owner'] = '${field}';
+    values[':owner'] = _osub;
+    expression += '#owner = :owner';
+  }
+  `
+  }
+
+/**
+The same retirement predicate as `retiredGuardPreamble`, for a door that reads
+with `Query` and therefore has a FilterExpression to put it in.
+
+Pushed into the read rather than applied to what came back, on
+`listAllItemsConnection`'s reasoning: an index door takes a `limit`, and
+narrowing after the read would hand back a page of fewer rows than the caller
+asked for while reporting nothing about why.
+
+Emits JS that appends to the `expression` / `names` / `values` the index
+templates already build, so it composes with a caller's own filter arguments
+instead of replacing them.
+*/
+let retiredFilterClause = (
+  ~retiredField: option<string>,
+  ~retiredValues: option<array<string>>,
+  ~elevatedGroups: array<string>,
+) =>
+  switch retiredField {
+  | None => ""
+  | Some(field) =>
+    let assignments = switch retiredValues {
+    | None => `      values[':retiredFalse'] = false;
+      expression += '(attribute_not_exists(#retired) OR #retired = :retiredFalse)';`
+    | Some(states) =>
+      let assigns =
+        states
+        ->Array.mapWithIndex((state, i) =>
+          `      values[':retiredValue${Int.toString(i)}'] = '${state}';`
+        )
+        ->Array.join("\n")
+      let comparisons =
+        states
+        ->Array.mapWithIndex((_, i) => `#retired <> :retiredValue${Int.toString(i)}`)
+        ->Array.join(" AND ")
+      `${assigns}
+      expression += '(attribute_not_exists(#retired) OR (${comparisons}))';`
+    }
+    `${exemptPreamble(~elevatedGroups)}
+  // ── retirement narrowing (generated) ──
+  if (!(_exempt && ctx.args.includeRetired === true)) {
+    if (expression) expression += ' AND ';
+    names['#retired'] = '${field}';
+${assignments}
+  }
+  `
+  }
+
 /**
 A by-key read's response, refusing a row the caller does not own.
 
@@ -66,29 +215,73 @@ the failure mode owner scoping exists to avoid. And an error would confirm the
 row exists to a caller who may not read it, which is a worse leak than the
 ambiguity it removes.
 */
-let ownerScopedResultResponse = (~ownerField: option<string>, ~elevatedGroups: array<string>) =>
-  switch ownerField {
-  | None => resultResponseCode
-  | Some(field) =>
+let ownerScopedResultResponse = (
+  ~ownerField: option<string>,
+  ~elevatedGroups: array<string>,
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
+) =>
+  switch (ownerField, retiredField) {
+  | (None, None) => resultResponseCode
+  | _ =>
+    let ownerPart = switch ownerField {
+    // Takes the row it ignores: APPSYNC_JS type-checks the resolver, so a
+  // zero-parameter stub called as `_owns(row)` is TS2554 ("Expected 0
+  // arguments, but got 1") and AppSync rejects the whole resolver at create
+  // time with "The code contains one or more errors". Only a door that emits
+  // the call conditionally is safe with a bare `() => true`, and that is not a
+  // property worth relying on across three templates.
+  | None => "\n  const _owns = (row) => true;"
+    | Some(field) =>
+      `
+  // ── owner scoping (generated) ──${ownerGuardPreamble(~ownerField=field, ~elevatedGroups)}`
+    }
+    let retiredPart = retiredGuardPreamble(
+      ~retiredField,
+      ~retiredValues,
+      ~elevatedGroups,
+      ~ownerScoped=ownerField->Option.isSome,
+    )
     `
 export function response(ctx) {
-  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
-  // ── owner scoping (generated) ──${ownerGuardPreamble(~ownerField=field, ~elevatedGroups)}
-  return _owns(ctx.result) ? ctx.result : null;
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);${ownerPart}${retiredPart}
+  return _owns(ctx.result)${retiredField->Option.isSome ? " && _live(ctx.result)" : ""} ? ctx.result : null;
 }`
   }
 
 /** The `queryByIdSort` counterpart — same rule, over the first row of a Query. */
-let ownerScopedFirstResultResponse = (~ownerField: option<string>, ~elevatedGroups: array<string>) =>
-  switch ownerField {
-  | None => firstResultResponseCode
-  | Some(field) =>
+let ownerScopedFirstResultResponse = (
+  ~ownerField: option<string>,
+  ~elevatedGroups: array<string>,
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
+) =>
+  switch (ownerField, retiredField) {
+  | (None, None) => firstResultResponseCode
+  | _ =>
+    let ownerPart = switch ownerField {
+    // Takes the row it ignores: APPSYNC_JS type-checks the resolver, so a
+  // zero-parameter stub called as `_owns(row)` is TS2554 ("Expected 0
+  // arguments, but got 1") and AppSync rejects the whole resolver at create
+  // time with "The code contains one or more errors". Only a door that emits
+  // the call conditionally is safe with a bare `() => true`, and that is not a
+  // property worth relying on across three templates.
+  | None => "\n  const _owns = (row) => true;"
+    | Some(field) =>
+      `
+  // ── owner scoping (generated) ──${ownerGuardPreamble(~ownerField=field, ~elevatedGroups)}`
+    }
+    let retiredPart = retiredGuardPreamble(
+      ~retiredField,
+      ~retiredValues,
+      ~elevatedGroups,
+      ~ownerScoped=ownerField->Option.isSome,
+    )
     `
 export function response(ctx) {
-  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
-  // ── owner scoping (generated) ──${ownerGuardPreamble(~ownerField=field, ~elevatedGroups)}
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);${ownerPart}${retiredPart}
   const _row = ctx.result.items[0] ?? null;
-  return _owns(_row) ? _row : null;
+  return _owns(_row)${retiredField->Option.isSome ? " && _live(_row)" : ""} ? _row : null;
 }`
   }
 
@@ -107,22 +300,23 @@ ${resultResponseCode}
 // Relay Node resolver — pipeline functions for node(id: ID!) query
 // ---------------------------------------------------------------------------
 
-/** Pipeline function (NONE datasource): decodes global ID and stashes typeName + localId. */
+/** Pipeline function (NONE datasource): decodes global ID and stashes typeName + localId.
+
+    Written without a `try`: APPSYNC_JS rejects try statements outright
+    (`@aws-appsync/no-try`), so a guarded version of this cannot be deployed at
+    all. Nothing is lost by dropping it — `util.base64Decode` does not throw on
+    malformed input, it returns the bytes it made of it, so the catch could never
+    run. An id that decodes to no `type:localId` pair therefore fails the one way
+    that is left: both halves stash as null, which is also what the guarded
+    version reported for a decode it could not parse. */
 let nodeDecodeGlobalId =
   `${importUtil}
 export function request(ctx) {
-  const globalId = ctx.args.id;
-  try {
-    const decoded = util.base64Decode(globalId);
-    const colonIdx = decoded.indexOf(':');
-    if (colonIdx > 0) {
-      ctx.stash.typeName = decoded.substring(0, colonIdx);
-      ctx.stash.localId = decoded.substring(colonIdx + 1);
-    }
-  } catch (e) {
-    ctx.stash.typeName = null;
-    ctx.stash.localId = null;
-  }
+  const decoded = util.base64Decode(ctx.args.id);
+  const colonIdx = decoded.indexOf(':');
+  const parsed = colonIdx > 0;
+  ctx.stash.typeName = parsed ? decoded.substring(0, colonIdx) : null;
+  ctx.stash.localId = parsed ? decoded.substring(colonIdx + 1) : null;
   return { payload: null };
 }
 export function response(ctx) {
@@ -157,7 +351,12 @@ export function response(ctx) {
 // declares no owner emits exactly the source it emitted before scoping existed.
 // A list that scopes beside a by-id read that does not is not a partial
 // delivery — it is a hole, reachable by anyone who can name a row.
-let getItemById = (~ownerField: option<string>=?, ~elevatedGroups: array<string>=[]) =>
+let getItemById = (
+  ~ownerField: option<string>=?,
+  ~elevatedGroups: array<string>=[],
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
+) =>
   `${importUtil}
 export function request(ctx) {
   return {
@@ -165,7 +364,7 @@ export function request(ctx) {
     key: { id: util.dynamodb.toDynamoDB(ctx.args.id) }
   };
 }
-${ownerScopedResultResponse(~ownerField, ~elevatedGroups)}
+${ownerScopedResultResponse(~ownerField, ~elevatedGroups, ~retiredField?, ~retiredValues?)}
 `->Pulumi.Input.make
 
 let queryById =
@@ -300,6 +499,8 @@ let queryByIdSort = (
   sortField: string,
   ~ownerField: option<string>=?,
   ~elevatedGroups: array<string>=[],
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
 ) =>
   `${importUtil}
 export function request(ctx) {
@@ -315,7 +516,7 @@ export function request(ctx) {
     }
   };
 }
-${ownerScopedFirstResultResponse(~ownerField, ~elevatedGroups)}
+${ownerScopedFirstResultResponse(~ownerField, ~elevatedGroups, ~retiredField?, ~retiredValues?)}
 `->Pulumi.Input.make
 
 // ---------------------------------------------------------------------------
@@ -384,14 +585,84 @@ export function request(ctx) {
 ${resultResponseCode}
 `->Pulumi.Input.make
 
+/**
+The by-index door's response.
+
+Cursors are the DynamoDB continuation token carrying the row's position in the
+page, exactly as `listAllItemsConnection` builds them — the two doors page over
+the same kind of result, so they page the same way. The boundary cursor covers
+the case that door documents: a filtered page can come back empty while a token
+is still set, and a client has to be able to resume past it.
+
+This replaces returning `ctx.result` raw. The field has always been declared as
+returning a `Connection!`, and handing back DynamoDB's `{items, nextToken}`
+satisfied no part of that contract.
+*/
+let indexConnectionResponseCode = `
+export function response(ctx) {
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
+  const items = ctx.result?.items ?? [];
+  const next = ctx.result?.nextToken ?? null;
+  const edges = items.map((item, i) => ({
+    node: item,
+    cursor: util.base64Encode(JSON.stringify({ token: next, index: i })),
+  }));
+  const boundary = next ? util.base64Encode(JSON.stringify({ token: next, index: -1 })) : null;
+  return {
+    edges,
+    pageInfo: {
+      hasNextPage: !!next,
+      hasPreviousPage: !!ctx.args.after,
+      startCursor: edges.length > 0 ? edges[0].cursor : boundary,
+      endCursor: edges.length > 0 ? edges[edges.length - 1].cursor : boundary,
+    },
+  };
+}`
+
+/** Refuses backward paging, for the reason `listAllItemsConnection` gives: the
+cursor is DynamoDB's own continuation token, which only walks forward, so
+`last`/`before` cannot be honoured and handing back the forward page would answer
+a different question without saying so.
+
+The arguments stay declared — one that came and went with the index's shape would
+make every client feature-detect — and the local backend refuses them with the
+same message, so the door reads the same either side of a deploy. */
+let indexBackwardPagingGuard = `
+  if (args.before != null || args.last != null) {
+    util.error('Backward pagination (last/before) is not supported on by-index connections; use first/after.', 'UnsupportedPagination');
+  }`
+
+/** Decodes the Relay `after` cursor back to the DynamoDB continuation token the
+response side encoded. Mirrors `listAllItemsConnection`'s request half. */
+let indexCursorPreamble = `
+  let after = null;
+  if (args.after != null && args.after !== '') {
+    const parsed = JSON.parse(util.base64Decode(args.after));
+    after = parsed.token ?? null;
+  }`
+
+// The arguments the by-index door declares, none of which is a column to match
+// on. `includeRetired` is a request to lift a restriction and the rest are
+// paging; left unlisted, the filter loop below turns each into a
+// `contains(#arg, :arg)` against an attribute no row carries, and the door
+// answers nothing.
+let indexReservedArgs = `key === 'first' || key === 'after' || key === 'last' || key === 'before' || key === 'includeRetired' || key === 'limit' || key === 'nextToken' || key === 'forward'`
+
 // AppSync JS runtime restrictions (APPSYNC_JS 1.0.0):
 //   - No `for` loops (for/for-of/for-in all fail validation)
 //   - No String() / .toString() — use '' + value instead
 //   - Object.keys().forEach() works for iteration
-let queryByIndexFiltered = (~index: string, ~idField: string) =>
+let queryByIndexFiltered = (
+  ~index: string,
+  ~idField: string,
+  ~ownerField: option<string>=?,
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
+  ~elevatedGroups: array<string>=[],
+) =>
   `${importUtil}
 export function request(ctx) {
-  const args = ctx.args;
+  const args = ctx.args;${indexBackwardPagingGuard}
   const query = {
     expression: '#${idField} = :${idField}',
     expressionNames: { '#${idField}': '${idField}' },
@@ -402,7 +673,7 @@ export function request(ctx) {
   const values = {};
   Object.keys(args).forEach(key => {
     const value = args[key];
-    if (key === '${idField}' || key === 'limit' || key === 'nextToken' || key === 'forward') return;
+    if (key === '${idField}' || ${indexReservedArgs}) return;
     if (value == null || value === '') return;
     if (expression) expression += ' AND';
     if (key === 'hideDeleted') {
@@ -417,12 +688,13 @@ export function request(ctx) {
       values[':' + key] = '' + value;
     }
   });
+${ownerFilterClause(~ownerField, ~elevatedGroups)}${retiredFilterClause(~retiredField, ~retiredValues, ~elevatedGroups)}${indexCursorPreamble}
   const result = {
     operation: 'Query',
     query,
     index: '${index}',
-    limit: (args.limit ?? 50),
-    nextToken: (args.nextToken ?? null),
+    limit: (args.first ?? 50),
+    nextToken: after,
     scanIndexForward: (args.forward ?? true)
   };
   if (expression) {
@@ -430,13 +702,21 @@ export function request(ctx) {
   }
   return result;
 }
-${resultResponseCode}
+${indexConnectionResponseCode}
 `->Pulumi.Input.make
 
-let queryByIndexSortFiltered = (~index: string, ~idField: string, ~sortField: string) =>
+let queryByIndexSortFiltered = (
+  ~index: string,
+  ~idField: string,
+  ~ownerField: option<string>=?,
+  ~sortField: string,
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
+  ~elevatedGroups: array<string>=[],
+) =>
   `${importUtil}
 export function request(ctx) {
-  const args = ctx.args;
+  const args = ctx.args;${indexBackwardPagingGuard}
   const query = args.${sortField}
     ? {
         expression: '#${idField} = :${idField} AND #${sortField} = :${sortField}',
@@ -456,7 +736,7 @@ export function request(ctx) {
   const values = {};
   Object.keys(args).forEach(key => {
     const value = args[key];
-    if (key === '${idField}' || key === '${sortField}' || key === 'limit' || key === 'nextToken' || key === 'forward') return;
+    if (key === '${idField}' || key === '${sortField}' || ${indexReservedArgs}) return;
     if (value == null || value === '') return;
     if (expression) expression += ' AND';
     if (key === 'hideDeleted') {
@@ -471,12 +751,13 @@ export function request(ctx) {
       values[':' + key] = '' + value;
     }
   });
+${ownerFilterClause(~ownerField, ~elevatedGroups)}${retiredFilterClause(~retiredField, ~retiredValues, ~elevatedGroups)}${indexCursorPreamble}
   const result = {
     operation: 'Query',
     query,
     index: '${index}',
-    limit: (args.limit ?? 50),
-    nextToken: (args.nextToken ?? null),
+    limit: (args.first ?? 50),
+    nextToken: after,
     scanIndexForward: (args.forward ?? true)
   };
   if (expression) {
@@ -484,7 +765,7 @@ export function request(ctx) {
   }
   return result;
 }
-${resultResponseCode}
+${indexConnectionResponseCode}
 `->Pulumi.Input.make
 
 // ---------------------------------------------------------------------------
@@ -998,7 +1279,12 @@ export function response(ctx) {
     time, since BatchGetItem's `tables` map keys on the literal table name.
     Single-key tables only — composite-key BatchGetItem needs both pk + sk per
     key entry, which this template doesn't construct. */
-let batchGetItemsByIds = (tableName: string) =>
+let batchGetItemsByIds = (
+  ~ownerField: option<string>=?,
+  ~retiredField: option<string>=?,
+  ~retiredValues: option<array<string>>=?,
+  ~elevatedGroups: array<string>=[],
+) => (tableName: string) =>
   `${importUtil}
 import { runtime } from '@aws-appsync/utils';
 export function request(ctx) {
@@ -1022,9 +1308,103 @@ export function response(ctx) {
   // missing id makes the entire field fail with "Cannot return null for
   // non-nullable type" and the caller sees data=null. Filter the nulls so
   // the field returns just the items that were found.
-  return (ctx.result?.data?.['${tableName}'] ?? []).filter(item => item !== null);
+  // The owner and retirement guards the list pushes into a FilterExpression,
+  // applied after the read because BatchGetItem has none to push into. A row the
+  // caller does not own is dropped rather than refused, for the reason the
+  // single-key door answers null: distinguishing "not yours" from "not there"
+  // would make this door an oracle for which ids exist.${switch ownerField {
+    | None => ""
+    | Some(field) => ownerGuardPreamble(~ownerField=field, ~elevatedGroups)
+    }}${retiredGuardPreamble(
+      ~retiredField,
+      ~retiredValues,
+      ~elevatedGroups,
+      ~ownerScoped=ownerField->Option.isSome,
+    )}
+  return (ctx.result?.data?.['${tableName}'] ?? []).filter(item =>
+    item !== null${ownerField->Option.isSome ? " && _owns(item)" : ""}${retiredField->Option.isSome
+      ? " && _live(item)"
+      : ""});
+}
+`
+
+/** The reference door — `{list}Refs(ids)`: what a caller holding a pointer to a
+    row may learn about it, and nothing else.
+
+    The same BatchGetItem as `batchGetItemsByIds`, projected in the response to
+    `{id, label, retired, retiredState}`. The projection is the type's — a caller
+    cannot ask for a price here because the SDL type has none — so the response
+    only has to *build* the three fields, never decide which to withhold.
+
+    `namedWhenRetired` is what a retired row turns on: false drops it, exactly as
+    every other door does; true lets it through with the state that withdrew it.
+    The owner rule is applied either way and is not what the annotation lifts. */
+let refsByIds = (
+  ~labelField: string,
+  ~retiredField: option<string>,
+  ~retiredValues: option<array<string>>,
+  ~namedWhenRetired: bool,
+  ~ownerField: option<string>=?,
+  ~elevatedGroups: array<string>=[],
+) => (tableName: string) => {
+  let ownerGuard = switch ownerField {
+  // Takes the row it ignores: APPSYNC_JS type-checks the resolver, so a
+  // zero-parameter stub called as `_owns(row)` is TS2554 ("Expected 0
+  // arguments, but got 1") and AppSync rejects the whole resolver at create
+  // time with "The code contains one or more errors". Only a door that emits
+  // the call conditionally is safe with a bare `() => true`, and that is not a
+  // property worth relying on across three templates.
+  | None => "\n  const _owns = (row) => true;"
+  | Some(field) => ownerGuardPreamble(~ownerField=field, ~elevatedGroups)
+  }
+  // Retirement, in the vocabulary the row itself uses: a member test for the
+  // state form, truthiness for the boolean one. Absent keeps the row live, which
+  // is what a row written before the annotation is.
+  let retiredExpr = switch (retiredField, retiredValues) {
+  | (None, _) => "false"
+  | (Some(f), Some(values)) =>
+    let literal = values->Array.map(v => `'${v}'`)->Array.join(", ")
+    `[${literal}].indexOf(row['${f}']) >= 0`
+  | (Some(f), None) => `row['${f}'] === true`
+  }
+  // Only the state form has a state to name, and only a retired row reports one:
+  // this door names rows, it does not publish a lifecycle column to callers the
+  // list withholds.
+  let stateExpr = switch (retiredField, retiredValues) {
+  | (Some(f), Some(_)) => `_retired(row) ? (row['${f}'] ?? null) : null`
+  | _ => "null"
+  }
+  `${importUtil}
+import { runtime } from '@aws-appsync/utils';
+export function request(ctx) {
+  const ids = ctx.args.ids ?? [];
+  if (ids.length === 0) return runtime.earlyReturn([]);
+  return {
+    operation: 'BatchGetItem',
+    tables: {
+      '${tableName}': {
+        keys: ids.map(id => ({ id: util.dynamodb.toDynamoDB(id) })),
+        consistentRead: true,
+      }
+    }
+  };
+}
+export function response(ctx) {
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);${ownerGuard}
+  const _retired = (row) => ${retiredExpr};
+  const _namesRetired = ${namedWhenRetired ? "true" : "false"};
+  return (ctx.result?.data?.['${tableName}'] ?? [])
+    .filter(row => row !== null && _owns(row))
+    .filter(row => _namesRetired || !_retired(row))
+    .map(row => ({
+      id: row.id,
+      label: row['${labelField}'] ?? row.id,
+      retired: _retired(row),
+      retiredState: ${stateExpr},
+    }));
 }
 `
+}
 
 // ---------------------------------------------------------------------------
 // DynamoDB write

package/src/AppSync/AppSync_Resolver_Functions.res.mjs

@@ -1,5 +1,6 @@
 // Generated by ReScript, PLEASE EDIT WITH CARE
 
+import * as Stdlib_Option from "@rescript/runtime/lib/es6/Stdlib_Option.js";
 
 let resultResponseCode = `
 export function response(ctx) {
@@ -32,31 +33,112 @@ function ownerGuardPreamble(ownerField, elevatedGroups) {
   const _owns = (row) => row == null || _exempt || row['` + ownerField + `'] === _sub;`;
 }
 
-function ownerScopedResultResponse(ownerField, elevatedGroups) {
-  if (ownerField !== undefined) {
-    return `
-export function response(ctx) {
-  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
-  // ── owner scoping (generated) ──` + ownerGuardPreamble(ownerField, elevatedGroups) + `
-  return _owns(ctx.result) ? ctx.result : null;
-}`;
+function exemptPreamble(elevatedGroups) {
+  let elevatedLiteral = elevatedGroups.map(g => `'` + g + `'`).join(", ");
+  return `
+  const _id = ctx.identity;
+  const _sub = _id == null ? null : _id.sub;
+  const _groups = (_id != null && _id.claims != null && _id.claims['cognito:groups']) || [];
+  const _elevated = [` + elevatedLiteral + `];
+  const _exempt = _sub == null || _groups.some(g => _elevated.indexOf(g) >= 0);`;
+}
+
+function retiredGuardPreamble(retiredField, retiredValues, elevatedGroups, ownerScoped) {
+  if (retiredField === undefined) {
+    return "";
+  }
+  let prelude = ownerScoped ? "" : exemptPreamble(elevatedGroups);
+  let isRetired;
+  if (retiredValues !== undefined) {
+    let literal = retiredValues.map(s => `'` + s + `'`).join(", ");
+    isRetired = `[` + literal + `].indexOf(row['` + retiredField + `']) >= 0`;
   } else {
-    return resultResponseCode;
+    isRetired = `row['` + retiredField + `'] === true`;
   }
+  return prelude + `
+  // ── retirement narrowing (generated) ──
+  const _wantsRetired = _exempt && ctx.args.includeRetired === true;
+  const _live = (row) =>
+    row == null || _wantsRetired || row['` + retiredField + `'] == null || !(` + isRetired + `);`;
 }
 
-function ownerScopedFirstResultResponse(ownerField, elevatedGroups) {
-  if (ownerField !== undefined) {
-    return `
+function ownerFilterClause(ownerField, elevatedGroups) {
+  if (ownerField === undefined) {
+    return "";
+  }
+  let elevatedLiteral = elevatedGroups.map(g => `'` + g + `'`).join(", ");
+  return `
+  // ── owner scoping (generated) ──
+  // Not read from ctx.args: a predicate deciding what the caller may see must
+  // arrive on a channel the caller cannot name.
+  const _oid = ctx.identity;
+  const _osub = _oid == null ? null : _oid.sub;
+  const _ogroups = (_oid != null && _oid.claims != null && _oid.claims['cognito:groups']) || [];
+  const _oelevated = [` + elevatedLiteral + `];
+  if (!(_osub == null || _ogroups.some(g => _oelevated.indexOf(g) >= 0))) {
+    if (expression) expression += ' AND ';
+    names['#owner'] = '` + ownerField + `';
+    values[':owner'] = _osub;
+    expression += '#owner = :owner';
+  }
+  `;
+}
+
+function retiredFilterClause(retiredField, retiredValues, elevatedGroups) {
+  if (retiredField === undefined) {
+    return "";
+  }
+  let assignments;
+  if (retiredValues !== undefined) {
+    let assigns = retiredValues.map((state, i) => `      values[':retiredValue` + i.toString() + `'] = '` + state + `';`).join("\n");
+    let comparisons = retiredValues.map((param, i) => `#retired <> :retiredValue` + i.toString()).join(" AND ");
+    assignments = assigns + `
+      expression += '(attribute_not_exists(#retired) OR (` + comparisons + `))';`;
+  } else {
+    assignments = `      values[':retiredFalse'] = false;
+      expression += '(attribute_not_exists(#retired) OR #retired = :retiredFalse)';`;
+  }
+  return exemptPreamble(elevatedGroups) + `
+  // ── retirement narrowing (generated) ──
+  if (!(_exempt && ctx.args.includeRetired === true)) {
+    if (expression) expression += ' AND ';
+    names['#retired'] = '` + retiredField + `';
+` + assignments + `
+  }
+  `;
+}
+
+function ownerScopedResultResponse(ownerField, elevatedGroups, retiredField, retiredValues) {
+  if (ownerField === undefined && retiredField === undefined) {
+    return resultResponseCode;
+  }
+  let ownerPart = ownerField !== undefined ? `
+  // ── owner scoping (generated) ──` + ownerGuardPreamble(ownerField, elevatedGroups) : "\n  const _owns = (row) => true;";
+  let retiredPart = retiredGuardPreamble(retiredField, retiredValues, elevatedGroups, Stdlib_Option.isSome(ownerField));
+  return `
 export function response(ctx) {
-  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
-  // ── owner scoping (generated) ──` + ownerGuardPreamble(ownerField, elevatedGroups) + `
-  const _row = ctx.result.items[0] ?? null;
-  return _owns(_row) ? _row : null;
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);` + ownerPart + retiredPart + `
+  return _owns(ctx.result)` + (
+    Stdlib_Option.isSome(retiredField) ? " && _live(ctx.result)" : ""
+  ) + ` ? ctx.result : null;
 }`;
-  } else {
+}
+
+function ownerScopedFirstResultResponse(ownerField, elevatedGroups, retiredField, retiredValues) {
+  if (ownerField === undefined && retiredField === undefined) {
     return firstResultResponseCode;
   }
+  let ownerPart = ownerField !== undefined ? `
+  // ── owner scoping (generated) ──` + ownerGuardPreamble(ownerField, elevatedGroups) : "\n  const _owns = (row) => true;";
+  let retiredPart = retiredGuardPreamble(retiredField, retiredValues, elevatedGroups, Stdlib_Option.isSome(ownerField));
+  return `
+export function response(ctx) {
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);` + ownerPart + retiredPart + `
+  const _row = ctx.result.items[0] ?? null;
+  return _owns(_row)` + (
+    Stdlib_Option.isSome(retiredField) ? " && _live(_row)" : ""
+  ) + ` ? _row : null;
+}`;
 }
 
 let pipelinePassThrough = importUtil + `
@@ -66,18 +148,11 @@ export function request(ctx) { return {}; }
 
 let nodeDecodeGlobalId = importUtil + `
 export function request(ctx) {
-  const globalId = ctx.args.id;
-  try {
-    const decoded = util.base64Decode(globalId);
-    const colonIdx = decoded.indexOf(':');
-    if (colonIdx > 0) {
-      ctx.stash.typeName = decoded.substring(0, colonIdx);
-      ctx.stash.localId = decoded.substring(colonIdx + 1);
-    }
-  } catch (e) {
-    ctx.stash.typeName = null;
-    ctx.stash.localId = null;
-  }
+  const decoded = util.base64Decode(ctx.args.id);
+  const colonIdx = decoded.indexOf(':');
+  const parsed = colonIdx > 0;
+  ctx.stash.typeName = parsed ? decoded.substring(0, colonIdx) : null;
+  ctx.stash.localId = parsed ? decoded.substring(colonIdx + 1) : null;
   return { payload: null };
 }
 export function response(ctx) {
@@ -102,7 +177,7 @@ export function response(ctx) {
 `;
 }
 
-function getItemById(ownerField, elevatedGroupsOpt) {
+function getItemById(ownerField, elevatedGroupsOpt, retiredField, retiredValues) {
   let elevatedGroups = elevatedGroupsOpt !== undefined ? elevatedGroupsOpt : [];
   return importUtil + `
 export function request(ctx) {
@@ -111,7 +186,7 @@ export function request(ctx) {
     key: { id: util.dynamodb.toDynamoDB(ctx.args.id) }
   };
 }
-` + ownerScopedResultResponse(ownerField, elevatedGroups) + `
+` + ownerScopedResultResponse(ownerField, elevatedGroups, retiredField, retiredValues) + `
 `;
 }
 
@@ -228,7 +303,7 @@ export function response(ctx) {
 `;
 }
 
-function queryByIdSort(sortField, ownerField, elevatedGroupsOpt) {
+function queryByIdSort(sortField, ownerField, elevatedGroupsOpt, retiredField, retiredValues) {
   let elevatedGroups = elevatedGroupsOpt !== undefined ? elevatedGroupsOpt : [];
   return importUtil + `
 export function request(ctx) {
@@ -244,7 +319,7 @@ export function request(ctx) {
     }
   };
 }
-` + ownerScopedFirstResultResponse(ownerField, elevatedGroups) + `
+` + ownerScopedFirstResultResponse(ownerField, elevatedGroups, retiredField, retiredValues) + `
 `;
 }
 
@@ -313,10 +388,46 @@ export function request(ctx) {
 `;
 }
 
-function queryByIndexFiltered(index, idField) {
+let indexConnectionResponseCode = `
+export function response(ctx) {
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);
+  const items = ctx.result?.items ?? [];
+  const next = ctx.result?.nextToken ?? null;
+  const edges = items.map((item, i) => ({
+    node: item,
+    cursor: util.base64Encode(JSON.stringify({ token: next, index: i })),
+  }));
+  const boundary = next ? util.base64Encode(JSON.stringify({ token: next, index: -1 })) : null;
+  return {
+    edges,
+    pageInfo: {
+      hasNextPage: !!next,
+      hasPreviousPage: !!ctx.args.after,
+      startCursor: edges.length > 0 ? edges[0].cursor : boundary,
+      endCursor: edges.length > 0 ? edges[edges.length - 1].cursor : boundary,
+    },
+  };
+}`;
+
+let indexBackwardPagingGuard = `
+  if (args.before != null || args.last != null) {
+    util.error('Backward pagination (last/before) is not supported on by-index connections; use first/after.', 'UnsupportedPagination');
+  }`;
+
+let indexCursorPreamble = `
+  let after = null;
+  if (args.after != null && args.after !== '') {
+    const parsed = JSON.parse(util.base64Decode(args.after));
+    after = parsed.token ?? null;
+  }`;
+
+let indexReservedArgs = `key === 'first' || key === 'after' || key === 'last' || key === 'before' || key === 'includeRetired' || key === 'limit' || key === 'nextToken' || key === 'forward'`;
+
+function queryByIndexFiltered(index, idField, ownerField, retiredField, retiredValues, elevatedGroupsOpt) {
+  let elevatedGroups = elevatedGroupsOpt !== undefined ? elevatedGroupsOpt : [];
   return importUtil + `
 export function request(ctx) {
-  const args = ctx.args;
+  const args = ctx.args;` + indexBackwardPagingGuard + `
   const query = {
     expression: '#` + idField + ` = :` + idField + `',
     expressionNames: { '#` + idField + `': '` + idField + `' },
@@ -327,7 +438,7 @@ export function request(ctx) {
   const values = {};
   Object.keys(args).forEach(key => {
     const value = args[key];
-    if (key === '` + idField + `' || key === 'limit' || key === 'nextToken' || key === 'forward') return;
+    if (key === '` + idField + `' || ` + indexReservedArgs + `) return;
     if (value == null || value === '') return;
     if (expression) expression += ' AND';
     if (key === 'hideDeleted') {
@@ -342,12 +453,13 @@ export function request(ctx) {
       values[':' + key] = '' + value;
     }
   });
+` + ownerFilterClause(ownerField, elevatedGroups) + retiredFilterClause(retiredField, retiredValues, elevatedGroups) + indexCursorPreamble + `
   const result = {
     operation: 'Query',
     query,
     index: '` + index + `',
-    limit: (args.limit ?? 50),
-    nextToken: (args.nextToken ?? null),
+    limit: (args.first ?? 50),
+    nextToken: after,
     scanIndexForward: (args.forward ?? true)
   };
   if (expression) {
@@ -355,14 +467,15 @@ export function request(ctx) {
   }
   return result;
 }
-` + resultResponseCode + `
+` + indexConnectionResponseCode + `
 `;
 }
 
-function queryByIndexSortFiltered(index, idField, sortField) {
+function queryByIndexSortFiltered(index, idField, ownerField, sortField, retiredField, retiredValues, elevatedGroupsOpt) {
+  let elevatedGroups = elevatedGroupsOpt !== undefined ? elevatedGroupsOpt : [];
   return importUtil + `
 export function request(ctx) {
-  const args = ctx.args;
+  const args = ctx.args;` + indexBackwardPagingGuard + `
   const query = args.` + sortField + `
     ? {
         expression: '#` + idField + ` = :` + idField + ` AND #` + sortField + ` = :` + sortField + `',
@@ -382,7 +495,7 @@ export function request(ctx) {
   const values = {};
   Object.keys(args).forEach(key => {
     const value = args[key];
-    if (key === '` + idField + `' || key === '` + sortField + `' || key === 'limit' || key === 'nextToken' || key === 'forward') return;
+    if (key === '` + idField + `' || key === '` + sortField + `' || ` + indexReservedArgs + `) return;
     if (value == null || value === '') return;
     if (expression) expression += ' AND';
     if (key === 'hideDeleted') {
@@ -397,12 +510,13 @@ export function request(ctx) {
       values[':' + key] = '' + value;
     }
   });
+` + ownerFilterClause(ownerField, elevatedGroups) + retiredFilterClause(retiredField, retiredValues, elevatedGroups) + indexCursorPreamble + `
   const result = {
     operation: 'Query',
     query,
     index: '` + index + `',
-    limit: (args.limit ?? 50),
-    nextToken: (args.nextToken ?? null),
+    limit: (args.first ?? 50),
+    nextToken: after,
     scanIndexForward: (args.forward ?? true)
   };
   if (expression) {
@@ -410,7 +524,7 @@ export function request(ctx) {
   }
   return result;
 }
-` + resultResponseCode + `
+` + indexConnectionResponseCode + `
 `;
 }
 
@@ -780,8 +894,10 @@ export function response(ctx) {
 `;
 }
 
-function batchGetItemsByIds(tableName) {
-  return importUtil + `
+function batchGetItemsByIds(ownerField, retiredField, retiredValues, $staropt$star) {
+  return tableName => {
+    let elevatedGroups = $staropt$star !== undefined ? $staropt$star : [];
+    return importUtil + `
 import { runtime } from '@aws-appsync/utils';
 export function request(ctx) {
   const ids = ctx.args.ids ?? [];
@@ -804,9 +920,73 @@ export function response(ctx) {
   // missing id makes the entire field fail with "Cannot return null for
   // non-nullable type" and the caller sees data=null. Filter the nulls so
   // the field returns just the items that were found.
-  return (ctx.result?.data?.['` + tableName + `'] ?? []).filter(item => item !== null);
+  // The owner and retirement guards the list pushes into a FilterExpression,
+  // applied after the read because BatchGetItem has none to push into. A row the
+  // caller does not own is dropped rather than refused, for the reason the
+  // single-key door answers null: distinguishing "not yours" from "not there"
+  // would make this door an oracle for which ids exist.` + (
+      ownerField !== undefined ? ownerGuardPreamble(ownerField, elevatedGroups) : ""
+    ) + retiredGuardPreamble(retiredField, retiredValues, elevatedGroups, Stdlib_Option.isSome(ownerField)) + `
+  return (ctx.result?.data?.['` + tableName + `'] ?? []).filter(item =>
+    item !== null` + (
+      Stdlib_Option.isSome(ownerField) ? " && _owns(item)" : ""
+    ) + (
+      Stdlib_Option.isSome(retiredField) ? " && _live(item)" : ""
+    ) + `);
 }
 `;
+  };
+}
+
+function refsByIds(labelField, retiredField, retiredValues, namedWhenRetired, ownerField, $staropt$star) {
+  return tableName => {
+    let elevatedGroups = $staropt$star !== undefined ? $staropt$star : [];
+    let ownerGuard = ownerField !== undefined ? ownerGuardPreamble(ownerField, elevatedGroups) : "\n  const _owns = (row) => true;";
+    let retiredExpr;
+    if (retiredField !== undefined) {
+      if (retiredValues !== undefined) {
+        let literal = retiredValues.map(v => `'` + v + `'`).join(", ");
+        retiredExpr = `[` + literal + `].indexOf(row['` + retiredField + `']) >= 0`;
+      } else {
+        retiredExpr = `row['` + retiredField + `'] === true`;
+      }
+    } else {
+      retiredExpr = "false";
+    }
+    let stateExpr = retiredField !== undefined && retiredValues !== undefined ? `_retired(row) ? (row['` + retiredField + `'] ?? null) : null` : "null";
+    return importUtil + `
+import { runtime } from '@aws-appsync/utils';
+export function request(ctx) {
+  const ids = ctx.args.ids ?? [];
+  if (ids.length === 0) return runtime.earlyReturn([]);
+  return {
+    operation: 'BatchGetItem',
+    tables: {
+      '` + tableName + `': {
+        keys: ids.map(id => ({ id: util.dynamodb.toDynamoDB(id) })),
+        consistentRead: true,
+      }
+    }
+  };
+}
+export function response(ctx) {
+  if (ctx.error) util.error(ctx.error.message, ctx.error.type);` + ownerGuard + `
+  const _retired = (row) => ` + retiredExpr + `;
+  const _namesRetired = ` + (
+      namedWhenRetired ? "true" : "false"
+    ) + `;
+  return (ctx.result?.data?.['` + tableName + `'] ?? [])
+    .filter(row => row !== null && _owns(row))
+    .filter(row => _namesRetired || !_retired(row))
+    .map(row => ({
+      id: row.id,
+      label: row['` + labelField + `'] ?? row.id,
+      retired: _retired(row),
+      retiredState: ` + stateExpr + `,
+    }));
+}
+`;
+  };
 }
 
 let putItem = importUtil + `
@@ -1019,6 +1199,10 @@ export {
   resultListResponseCode,
   importUtil,
   ownerGuardPreamble,
+  exemptPreamble,
+  retiredGuardPreamble,
+  ownerFilterClause,
+  retiredFilterClause,
   ownerScopedResultResponse,
   ownerScopedFirstResultResponse,
   pipelinePassThrough,
@@ -1031,6 +1215,10 @@ export {
   queryByIndex,
   queryByIndexDeletable,
   queryByIndexSort,
+  indexConnectionResponseCode,
+  indexBackwardPagingGuard,
+  indexCursorPreamble,
+  indexReservedArgs,
   queryByIndexFiltered,
   queryByIndexSortFiltered,
   listAllItems,
@@ -1043,6 +1231,7 @@ export {
   resolveIdByIndexSortArgument,
   resolveIds,
   batchGetItemsByIds,
+  refsByIds,
   putItem,
   addItemToList,
   deleteItem,

package/tests/AppSync_Resolver_FunctionsTest.mjs

@@ -23,7 +23,7 @@ describe('Resolver code structure', () => {
     ['queryByIndexDeletable(index)', F.queryByIndexDeletable('userId')],
     ['queryByIndexSort(index,idField,sortField)', F.queryByIndexSort('userId', 'userId', 'createdAt')],
     ['queryByIndexFiltered(index,idField)', F.queryByIndexFiltered('userId', 'userId')],
-    ['queryByIndexSortFiltered(index,idField,sortField)', F.queryByIndexSortFiltered('userId', 'userId', 'status')],
+    ['queryByIndexSortFiltered(index,idField,sortField)', F.queryByIndexSortFiltered('userId', 'userId', undefined, 'status')],
     ['listAllItems', F.listAllItems],
     ['resolveId(sourceIdField)', F.resolveId('productId')],
     ['resolveIdSort(sourceIdField,sourceSortField,targetSortField)', F.resolveIdSort('productId', 'status', 'status')],
@@ -437,7 +437,12 @@ describe('listAllItemsConnection', () => {
 // queryByIndexSortFiltered — complex template, most important to test
 // ---------------------------------------------------------------------------
 describe('queryByIndexSortFiltered', () => {
-  const code = F.queryByIndexSortFiltered('ownerId', 'ownerId', 'status')  // index, idField, sortField
+  // index, idField, ownerField, sortField — `ownerField` is optional but sits
+  // ahead of `sortField`, so it has to be passed explicitly. Skipping it slid
+  // the sort key into the owner slot and this file scoped the read by `status`
+  // while asserting it did not, which is the failure mode a positional call
+  // against a labelled-argument function always has.
+  const code = F.queryByIndexSortFiltered('ownerId', 'ownerId', undefined, 'status')
   const { request, response } = evalResolver(code)
 
   test('query by idField only when sortField is absent', () => {
@@ -483,9 +488,19 @@ describe('queryByIndexSortFiltered', () => {
     expect(request(ctx).scanIndexForward).toBe(true)
   })
 
-  test('response returns result on success', () => {
-    const ctx = makeCtx({ result: { items: [{ id: 'x' }] } })
-    expect(response(ctx)).toEqual({ items: [{ id: 'x' }] })
+  // The field this template is attached to has always been declared as returning
+  // a Connection; handing back DynamoDB's `{items, nextToken}` satisfied no part
+  // of that, so the door errored for every caller that selected `edges`.
+  test('response returns a Relay connection', () => {
+    const ctx = makeCtx({ result: { items: [{ id: 'x' }], nextToken: null } })
+    const out = response(ctx)
+    expect(out.edges.map(e => e.node)).toEqual([{ id: 'x' }])
+    expect(out.pageInfo.hasNextPage).toBe(false)
+  })
+
+  test('reports a further page when DynamoDB hands back a token', () => {
+    const ctx = makeCtx({ result: { items: [{ id: 'x' }], nextToken: 'TOK' } })
+    expect(response(ctx).pageInfo.hasNextPage).toBe(true)
   })
 })